Merge branch 'master' into master

Author: inteltiger

doc/Client-Portal Protocol.md

@@ -1,4 +1,4 @@
-# Client-Portal Communication Protocol (version 1.1)
+# Client-Portal Communication Protocol (version 1.2)
 <!--
 |date | contributor | revision |
 | :-------: | :------------: | :------------: |
@@ -16,7 +16,10 @@ Here is a table describing the detailed name and definition.
 |:----|:-----------|
 | Portal | The MCU component listening at the Socket.io server port, accepting signaling connections initiated by Clients, receive/send signaling messages from/to Clients. |
 | Client | The program running on end-user’s device which interacts with MCU Server by messages defined in this documentation.|
-| Signaling Connection | The signaling channel between Client and Portal established by Client to send, receive and fetch signaling messages. |
+| Connection | A transport channel between client and server. Different kinds of connections may have different transport protocols. |
+| Signaling Connection | The signaling channel between client and Portal established by Client to send, receive and fetch signaling messages. |
+| WebRTC Connection | A WebRTC transport channel between client and WebRTC agent. It may carry audio and video data. Detailed information about WebRTC could be found [here](https://webrtc.org/). |
+| QUIC Connection | A QUIC transport channel between client and QUIC agent. Detailed information about QUIC could be found [here](https://quicwg.org/). |
 | Room | The logical entity of a conference in which all conference members (participants) exchange their video/audio streams, and where mixed streams are generated. Every room must be assigned with a unique identification **(RoomID)** in the MCU scope. |
 | User | The service account defined in the third-party integration application. The user ID and user role must be specified when asking for a token. |
 | Participant | The logical entity of a user when participating in a conference with a valid token. Every participant must be assigned with a unique identification **(ParticipantID)** in the room scope, and must be assigned a set of operation permissions according to its role. |
@@ -61,7 +64,7 @@ Given that Portal has accepted Clients connecting and the socket object is ready
 - **NotificationName** must be with type of string, and with value defined in this specification;
 - **NotificationData** must be with type of object, and with format defined in this specification, and will be absent if no notification data is present.
 
-## 3.2 Connection Maintenance
+## 3.2 Signaling Connection Maintenance
 ### 3.2.1 Client Connects
 Portal should be able to listen at either a secure or an insecure socket.io server port to accept Clients’ connecting requests.  If the secure socket.io server is enabled, the SSL certificate and private key store path must be correctly specified by configuration item portal.keystorePath in portal.toml.<br>
 
@@ -144,11 +147,13 @@ This a format for client reconnects.
         {
          publish: {
              audio: true | false,
-             video: true | false
+             video: true | false,
+             data:  true | false
          },
          subscribe: {
              audio: true | false,
-             video: true | false
+             video: true | false,
+             data:  true | false
          }
         }
 
@@ -164,7 +169,8 @@ This a format for client reconnects.
           {
            id: string(StreamID),
            type: "forward" | "augmented" |"mixed",
-           media: object(MediaInfo),
+           media: object(MediaInfo) | null,
+           data: true | false,
            info: object(PublicationInfo)/*If type equals "forward"*/
                 | object(AugmentInfo)/*If type equals "augmented"*/
                 | object(ViewInfo)/*If type equals "mixed"*/
@@ -243,7 +249,7 @@ This a format for client reconnects.
           object(PublicationInfo):
             {
              owner: string(ParticipantId),
-             type: "webrtc" | "streaming" | "sip",
+             type: "webrtc" | "streaming" | "sip" | "quic",
              inViews: [String(ViewLabel)],
              attributes: object(ClientDefinedAttributes)
             }
@@ -350,38 +356,48 @@ This a format for client reconnects.
      message: string(Message)
     }
 
-### 3.3.7 Participant Starts Publishing a WebRTC Stream to Room
+### 3.3.7 Participant Starts Publishing a Stream to Room
 **RequestName**: “publish”<br>
 
 **RequestData**: The PublicationRequest object with following definition:
 
+```
   object(PublicationRequest)::
     {
-     media: object(WebRTCMediaOptions),
-     attributes: object(ClientDefinedAttributes)
+     media: object(WebRTCMediaOptions) | null,
+     data: true | false,
+     transport: object(TransportOptions),
+     attributes: object(ClientDefinedAttributes) | null
     }
+```
+
+A publication can send either media or data, but a QUIC *transport* channel can support multiple stream for both media and data. Setting `media:null` and `data:false` is meaningless, so it should be rejected by server. Protocol itself doesn't forbit to create WebRTC connection for data. However, SCTP data channel is not implemented at server side, so currently `data:true` is only support by QUIC transport channels. 
+
+```
+  object(WebRTCMediaOptions)::
+    {
+      audio: {
+            source: "mic" | "screen-cast" | "raw-file" | "encoded-file"
+            }
+            | false,
+      video: {
+            source: "camera"| "screen-cast"  | "raw-file" | "encoded-file",
+            parameters:
+              {
+                resolution: object(Resolution),
+                framerate: number(FramerateFPS)
+              }
+            }
+            | false
+    }
+```
 
-    object(WebRTCMediaOptions)::
-      {
-       audio: {
-              source: "mic" | "screen-cast" | "raw-file" | "encoded-file"
-             }
-             | false,
-       video: {
-              source: "camera"| "screen-cast"  | "raw-file" | "encoded-file",
-              parameters:
-                {
-                 resolution: object(Resolution),
-                 framerate: number(FramerateFPS)
-                }
-             }
-             | false
-      }
 **ResponseData**: The PublicationResult object with following definition if **ResponseStatus** is “ok”:
 
   object(PublicationResult)::
     {
-     id: string(SessionId) //will be used as the stream id when it gets ready.
+      transportId: string(transportId),  // Can be reused in the following publication or subscription.
+     publicationId: string(SessionId) //will be used as the stream id when it gets ready.
     }
 ### 3.3.8 Participant Stops Publishing a Stream to Room
 **RequestName**: “unpublish”<br>
@@ -431,7 +447,8 @@ This a format for client reconnects.
 
   object(SubscriptionRequest)::
     {
-     media: object(MediaSubOptions)
+     media: object(MediaSubOptions),
+     transport: object(TransportOptions),
     }
 
     object(MediaSubOptions)::
@@ -464,7 +481,8 @@ This a format for client reconnects.
 
   object(SubscriptionResult)::
     {
-     id: string(SubscriptionId)
+      transportId: string(transportId),  // Can be reused in the following publication or subscription.
+     subscriptionId: string(SubscriptionId)
     }
 ### 3.3.12 Participant Stops a Self-Initiated Subscription
 **RequestName**: “unsubscribe”<br>
@@ -519,14 +537,14 @@ This a format for client reconnects.
 
   object(SOACMessage)::
     {
-     id: string(SessionId), /* StreamId returned in publishing or SubscriptionId returned in subscribing*/
+     id: string(transportId), /* Transport ID returned in publishing or subscribing*/
      signaling: object(OfferAnswer) | object(CandidateMessage) | object(RemovedCandidatesMessage)
     }
 
     object(OfferAnswer)::
       {
        type: "offer" | "answer",
-       sdp: string(SDP)
+       sdp: string(SDP) | null,  // WebRTC connection
       }
 
     object(CandidateMessage)::
@@ -547,24 +565,59 @@ This a format for client reconnects.
        sdpMLineIndex: number(mLineIndex),   // optional in RemovedCandidatesMessage
        candidate: string(candidateSdp)
       }
+
+    object(TransportOptions)::
+      {
+        type: "webrtc" | "quic",
+        id: string(transportId) | null,  // null will result to create a new transport channel. Always be null if transport type is webrtc because webrtc agent doesn't support multiple transceivers on a single PeerConnection at this time.
+      }
+
 **ResponseData**: undefined if **ResponseStatus** is “ok”.
 ### 3.3.15 Participant Receives Session Progress
 **NotificationName**: “progress”<br>
 
-**NotificationData**: The SessionProgress object with following definition.
+**NotificationData**: The SessionProgress or TransportProgress object with following definition.
 
-  object(SessionProgress)::
+  object(TransportProgress)::
     {
-     id: string(SessionId), /* StreamId returned in publishing or SubscriptionId returned in subscribing*/
-     status: "soac" | "ready" | "error",
-     data: object(OfferAnswer) | object(CandidateMessage)/*If status equals “soac”*/
+      id: string(transportId),
+      status: "soac" | "ready" | "error",
+      data: object(OfferAnswer) | object(CandidateMessage)  /*If status equals “soac”*/
           | (undefined/*If status equals “ready” and session is NOT for recording*/
-             | object(RecorderInfo)/*If status equals “ready” and session is for recording*/ )
           | string(Reason)/*If status equals “error”*/
     }
 
-    object(RecorderInfo)::
-      {
-       host: string(HostnameOrIPOfRecorder),
-       file: string(FullPathNameOfRecordedFile)
-      }
+  object(SessionProgress)::
+    {
+     id: string(SessionId), /* StreamId returned in publishing or SubscriptionId returned in subscribing*/
+     status: "ready" | "error"
+    }
+
+# 4. Examples
+
+This section provides a few examples of signaling messages for specific purposes.
+
+## 4.1 Forward data through data channel over QUIC
+
+An endpoint is joined the meeting, and it wants to publish a data stream over a QUIC transport channel.
+
+Step 1: Client sends a "publish" request.
+
+```
+{
+  media: null,
+  data: true,
+  transport: {type: 'quic'}
+}
+```
+
+Step 2: Receive a response from server.
+
+```
+{
+  transportId: undefined,
+  publicationId: '91e247051d494cddbd4ad461445637c4'
+}
+```
+
+Step 3: Create a new WebTransport or get an existing WebTransport, then create a new BidirectionalStream or SendStream. Write data to stream. The URL of WebTransport should be included in token. WebTransport is shared by all media streams, data streams and signaling which belong to the same client.

doc/design/quic-transport-payload-format.md

@@ -0,0 +1,44 @@
+# QUIC Transport Payload and Message Format
+
+This post defines the payload and message format for data transmitted over [WebTransport](https://w3c.github.io/webtransport/#web-transport).
+
+## Streams
+
+Both server and client can initialize a stream. When a stream is created, initial side sends a session ID, which is a 128 bit length message to the remote side. Session ID could be a publication ID or subscription ID as defined in [Client-Portal Protocol](https://github.com/open-webrtc-toolkit/owt-server/blob/master/doc/Client-Portal%20Protocol.md). As the session ID issued by server may less than 128 bit right now, fill it with 0 in most significant bits. Session ID 0 is reserved for signaling. When remote side receives the session ID, it should check whether session ID is valid. Terminate the stream if session ID is invalid, or send the same session ID to client if it is valid. Depends on the type of stream it created, one side or both sides are ready to send data.
+
+## Datagram
+
+Each package has a 128 bit header for session ID.
+
+```
+    0                   1                   2                   3
+    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+   |                                                               |
+   |                      Session Identifier                       |
+   |                             ....                              |
+   |                                                               |
+   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+   |                      Datagram Data (*)                      ...
+   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+```
+
+It may increase about 2% network cost.
+
+## Signaling Session
+
+After creating a WebTransport, a stream with session 0 should be created for authentication and signaling. Every signaling message is followed by a 32 bit length integer that indicates the body's length.
+
+```
+    0                   1                   2                   3
+    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+   |                      Message length                           |
+   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+   |                          Message                            ...
+   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+```
+
+## Authentication
+
+If signaling messages are transmitted over WebTransport, authentication follows the regular process defined by [Client-Portal Protocol](https://github.com/open-webrtc-toolkit/owt-server/blob/master/doc/Client-Portal%20Protocol.md). Otherwise, client sends a token for WebTransport as a signaling message. WebTransport token is issued during joining a conference. If token is valid, server sends a 128 bit length transport ID to client. The transport ID should be same as the one included in token.

doc/servermd/AnalyticsGuide.md

@@ -135,7 +135,7 @@ Start up MCU in Docker container:
 
 ````
 cd Release-vxxx
-./bin/init-all.sh --deps
+./bin/init-all.sh --deps ##default password for user owt is owt
 ./bin/start-all.sh
 ````
 

docker/Dockerfile

@@ -220,13 +220,18 @@ WORKDIR /home
 ARG NODE_VER=v10.21.0
 ARG NODE_REPO=https://nodejs.org/dist/${NODE_VER}/node-${NODE_VER}-linux-x64.tar.xz
 
-COPY --from=owt-build /home/owt-server/dist /home/owt
-COPY startowt.sh /home/
-
-RUN apt-get update && apt-get install -y -q --no-install-recommends ca-certificates wget xz-utils rabbitmq-server mongodb libboost-system-dev libboost-thread-dev liblog4cxx-dev libglib2.0-0 libfreetype6-dev curl
+RUN apt-get update && apt-get install -y -q --no-install-recommends ca-certificates wget xz-utils rabbitmq-server mongodb libboost-system-dev libboost-thread-dev liblog4cxx-dev libglib2.0-0 libfreetype6-dev curl sudo
 
 RUN wget ${NODE_REPO} && \
     tar xf node-${NODE_VER}-linux-x64.tar.xz && \
     cp node-*/* /usr/local -rf && rm -rf node-*
 
+RUN useradd -m owt && echo "owt:owt" | chpasswd && adduser owt sudo
+
+COPY --chown=owt:owt --from=owt-build /home/owt-server/dist /home/owt
+COPY --chown=owt:owt startowt.sh /home/
+
+USER owt
+
+CMD /bin/bash
 ENV LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/usr/local/lib/x86_64-linux-gnu

docker/README.md

@@ -44,10 +44,13 @@ Note that `externalip` and `network_interface` should be both set if there are e
     a) Launch a Docker container with following command to simply try OWT:
 
     ```shell
-    docker run -itd --name=owt --net=host owt:run /home/startowt.sh
+    docker run -itd --name=owt --net=host owt:run bash
+    docker exec -it owt bash
+    cd /home/
+    ./startowt.sh    ##default password for user owt is owt
     ```
     Then OWT service should be launched and you can connect to https://localhost:3004 to start your OWT journey.
 
     b) Launch OWT service with Docker swarm with script ```conference/build_server.sh```
     
-    c) Customize different OWT module images and launch OWT service with Kubernetes.
+    c) Customize different OWT module images and launch OWT service with Kubernetes.