Document bridge messages

app/src/bridge/messaging.ts

@@ -1,106 +1,178 @@
 "use strict";
 
 import {
-    Image,
     MediaStatus,
     ReceiverStatus,
-    SenderApplication,
-    SenderMessage,
-    Volume
+    SenderMessage
 } from "./components/cast/types";
 
-import { ReceiverDevice } from "./types";
-
-interface CastSessionUpdated {
-    sessionId: string;
-    statusText: string;
-    namespaces: Array<{ name: string }>;
-    volume: Volume;
-}
-
-interface CastSessionCreated extends CastSessionUpdated {
-    appId: string;
-    appImages: Image[];
-    displayName: string;
-    receiverFriendlyName: string;
-    senderApps: SenderApplication[];
-    transportId: string;
-}
+import {
+    ReceiverDevice,
+    CastSessionCreatedDetails,
+    CastSessionUpdatedDetails
+} from "./types";
 
 /**
+ * IMPORTANT:
  * Messages that cross the native messaging channel. MUST keep
  * in-sync with the extension's version at:
  *   ext/src/messaging.ts > MessageDefinitions
  */
 type MessageDefinitions = {
-    "cast:sessionCreated": CastSessionCreated;
-    "cast:sessionUpdated": CastSessionUpdated;
-    "cast:sessionStopped": {
-        sessionId: string;
+    /**
+     * First message sent by the extension to the bridge.
+     * Includes extension version string. Responds directly with version
+     * string of the bridge to compare.
+     *
+     * Still uses `:/` message separator for compat talking to older
+     * bridge versions.
+     */
+    "bridge:getInfo": string;
+    "bridge:/getInfo": string;
+
+    /**
+     * Tells a bridge to begin service discovery (and whether to
+     * establish connections to monitor the status of the receiver
+     * devices).
+     */
+    "bridge:startDiscovery": {
+        shouldWatchStatus: boolean;
     };
-    "cast:receivedSessionMessage": {
-        sessionId: string;
-        namespace: string;
-        messageData: string;
+
+    /**
+     * Sent to extension from the bridge whenever a receiver device is
+     * found.
+     */
+    "main:receiverDeviceUp": { deviceId: string; deviceInfo: ReceiverDevice };
+    /**
+     * Sent to extension from the bridge whenever a previously found
+     * receiver device is lost.
+     */
+    "main:receiverDeviceDown": { deviceId: string };
+
+    /**
+     * Sent to the extension from the bridge whenever a
+     * `RECEIVER_STATUS` message (`NS_RECEIVER`) is received.
+     */
+    "main:receiverDeviceStatusUpdated": {
+        deviceId: string;
+        status: ReceiverStatus;
     };
-    "cast:impl_sendMessage": {
-        sessionId: string;
-        messageId: string;
-        error?: string;
+    /**
+     * Sent to the extension from the bridge whenever a
+     * `MEDIA_STATUS` message (`NS_RECEIVER`) is received.
+     */
+    "main:receiverDeviceMediaStatusUpdated": {
+        deviceId: string;
+        status: MediaStatus;
     };
+
+    /**
+     * Sent to bridge from cast API instance when a session request is
+     * initiated.
+     */
     "bridge:createCastSession": {
         appId: string;
         receiverDevice: ReceiverDevice;
     };
+    /**
+     * Connects to, and sends a `STOP` message on the `NS_RECEIVER`
+     * channel for the given receiver device.
+     */
+    "bridge:stopCastSession": {
+        receiverDevice: ReceiverDevice;
+    };
+
+    /**
+     * Sent to cast API instances whenever a session is created or
+     * updates. Updated details is a mutable subset of session details
+     * otherwise fixed on creation.
+     */
+    "cast:sessionCreated": CastSessionCreatedDetails;
+    "cast:sessionUpdated": CastSessionUpdatedDetails;
+    /**
+     * Sent to cast API instances whenever a session is stopped.
+     */
+    "cast:sessionStopped": {
+        sessionId: string;
+    };
+
+    /**
+     * Sent to bridge from cast API instance whenever an `NS_RECEIVER`
+     * message needs to be sent.
+     */
     "bridge:sendCastReceiverMessage": {
         sessionId: string;
         messageData: SenderMessage;
         messageId: string;
     };
+
+    /**
+     * Sent to bridge from cast API instance whenever a application
+     * session message needs to be sent (via
+     * `chrome.cast.Session#sendMessage`).
+     */
     "bridge:sendCastSessionMessage": {
         sessionId: string;
         namespace: string;
         messageData: object | string;
         messageId: string;
     };
-    "bridge:stopCastSession": {
-        receiverDevice: ReceiverDevice;
+    /**
+     * Sent to cast API instance from bridge when session message
+     * received from a receiver device.
+     */
+    "cast:receivedSessionMessage": {
+        sessionId: string;
+        namespace: string;
+        messageData: string;
     };
 
     /**
-     * getInfo uses the old :/ form for compat with old bridge
-     * versions.
+     * Sent to cast API instance from bridge whenever a message
+     * operation is completed. If an error ocurred, an error string will
+     * be passed as the `error` data property.
+     *
+     * TODO: Check how/if this works with receiver messages (via
+     * `bridge:sendCastReceiverMessage`).
      */
-    "bridge:getInfo": string;
-    "bridge:/getInfo": string;
-
-    "bridge:startDiscovery": {
-        shouldWatchStatus: boolean;
+    "cast:impl_sendMessage": {
+        sessionId: string;
+        messageId: string;
+        error?: string;
     };
 
+    /**
+     * Sent to the bridge to start an HTTP media server at a given file
+     * path on the given port.
+     */
     "bridge:startMediaServer": {
         filePath: string;
         port: number;
     };
-    "bridge:stopMediaServer": {};
+    /**
+     * Sent to media sender from bridge when the media server is ready
+     * to serve files.
+     */
     "mediaCast:mediaServerStarted": {
         mediaPath: string;
         subtitlePaths: string[];
         localAddress: string;
     };
+    /**
+     * Sent to bridge to stop HTTP media server.
+     */
+    "bridge:stopMediaServer": {};
+    /**
+     * Sent to media sender from bridge when the media server has
+     * stopped.
+     */
     "mediaCast:mediaServerStopped": {};
+    /**
+     * Sent to media sender from bridge when the media server has
+     * encountered an error.
+     */
     "mediaCast:mediaServerError": {};
-
-    "main:receiverDeviceUp": { deviceId: string; deviceInfo: ReceiverDevice };
-    "main:receiverDeviceDown": { deviceId: string };
-    "main:receiverDeviceStatusUpdated": {
-        deviceId: string;
-        status: ReceiverStatus;
-    };
-    "main:receiverDeviceMediaStatusUpdated": {
-        deviceId: string;
-        status: MediaStatus;
-    };
 };
 
 interface MessageBase<K extends keyof MessageDefinitions> {

app/src/bridge/types.ts

@@ -1,6 +1,11 @@
 "use strict";
 
-import { ReceiverStatus } from "./components/cast/types";
+import {
+    Image,
+    ReceiverStatus,
+    SenderApplication,
+    Volume
+} from "./components/cast/types";
 
 export interface ReceiverDevice {
     host: string;
@@ -9,3 +14,18 @@ export interface ReceiverDevice {
     port: number;
     status?: ReceiverStatus;
 }
+
+export interface CastSessionUpdatedDetails {
+    sessionId: string;
+    statusText: string;
+    namespaces: Array<{ name: string }>;
+    volume: Volume;
+}
+export interface CastSessionCreatedDetails extends CastSessionUpdatedDetails {
+    appId: string;
+    appImages: Image[];
+    displayName: string;
+    receiverFriendlyName: string;
+    senderApps: SenderApplication[];
+    transportId: string;
+}

ext/src/cast/api/types.ts

@@ -49,14 +49,14 @@ export interface ReceiverStatus {
     volume: Volume;
 }
 
-export interface CastSessionUpdated {
+export interface CastSessionUpdatedDetails {
     sessionId: string;
     statusText: string;
     namespaces: Array<{ name: string }>;
     volume: Volume;
 }
 
-export interface CastSessionCreated extends CastSessionUpdated {
+export interface CastSessionCreatedDetails extends CastSessionUpdatedDetails {
     appId: string;
     appImages: Image[];
     displayName: string;

ext/src/messaging.ts

@@ -11,8 +11,8 @@ import {
 } from "./background/receiverSelector";
 
 import {
-    CastSessionCreated,
-    CastSessionUpdated,
+    CastSessionCreatedDetails,
+    CastSessionUpdatedDetails,
     MediaStatus,
     ReceiverStatus,
     SenderMessage
@@ -57,7 +57,7 @@ type ExtMessageDefinitions = {
     "cast:selectReceiver/cancelled": {};
 
     "main:closeReceiverSelector": {};
-    
+
     "main:initializeCast": { appId: string };
     "cast:initialized": BridgeInfo;
 
@@ -67,80 +67,166 @@ type ExtMessageDefinitions = {
 };
 
 /**
+ * IMPORTANT:
  * Messages that cross the native messaging channel. MUST keep
  * in-sync with the bridge's version at:
  *   app/src/bridge/messaging.ts > MessageDefinitions
  */
 type AppMessageDefinitions = {
-    "cast:sessionCreated": CastSessionCreated;
-    "cast:sessionUpdated": CastSessionUpdated;
-    "cast:sessionStopped": {
-        sessionId: string;
+    /**
+     * First message sent by the extension to the bridge.
+     * Includes extension version string. Responds directly with version
+     * string of the bridge to compare.
+     *
+     * Still uses `:/` message separator for compat talking to older
+     * bridge versions.
+     */
+    "bridge:getInfo": string;
+    "bridge:/getInfo": string;
+
+    /**
+     * Tells a bridge to begin service discovery (and whether to
+     * establish connections to monitor the status of the receiver
+     * devices).
+     */
+    "bridge:startDiscovery": {
+        shouldWatchStatus: boolean;
     };
-    "cast:receivedSessionMessage": {
-        sessionId: string;
-        namespace: string;
-        messageData: string;
+
+    /**
+     * Sent to extension from the bridge whenever a receiver device is
+     * found.
+     */
+    "main:receiverDeviceUp": { deviceId: string; deviceInfo: ReceiverDevice };
+    /**
+     * Sent to extension from the bridge whenever a previously found
+     * receiver device is lost.
+     */
+    "main:receiverDeviceDown": { deviceId: string };
+
+    /**
+     * Sent to the extension from the bridge whenever a
+     * `RECEIVER_STATUS` message (`NS_RECEIVER`) is received.
+     */
+    "main:receiverDeviceStatusUpdated": {
+        deviceId: string;
+        status: ReceiverStatus;
     };
-    "cast:impl_sendMessage": {
-        sessionId: string;
-        messageId: string;
-        error?: string;
+    /**
+     * Sent to the extension from the bridge whenever a
+     * `MEDIA_STATUS` message (`NS_RECEIVER`) is received.
+     */
+    "main:receiverDeviceMediaStatusUpdated": {
+        deviceId: string;
+        status: MediaStatus;
     };
+
+    /**
+     * Sent to bridge from cast API instance when a session request is
+     * initiated.
+     */
     "bridge:createCastSession": {
         appId: string;
         receiverDevice: ReceiverDevice;
     };
+    /**
+     * Connects to, and sends a `STOP` message on the `NS_RECEIVER`
+     * channel for the given receiver device.
+     */
+    "bridge:stopCastSession": {
+        receiverDevice: ReceiverDevice;
+    };
+
+    /**
+     * Sent to cast API instances whenever a session is created or
+     * updates. Updated details is a mutable subset of session details
+     * otherwise fixed on creation.
+     */
+    "cast:sessionCreated": CastSessionCreatedDetails;
+    "cast:sessionUpdated": CastSessionUpdatedDetails;
+    /**
+     * Sent to cast API instances whenever a session is stopped.
+     */
+    "cast:sessionStopped": {
+        sessionId: string;
+    };
+
+    /**
+     * Sent to bridge from cast API instance whenever an `NS_RECEIVER`
+     * message needs to be sent.
+     */
     "bridge:sendCastReceiverMessage": {
         sessionId: string;
         messageData: SenderMessage;
         messageId: string;
     };
+
+    /**
+     * Sent to bridge from cast API instance whenever a application
+     * session message needs to be sent (via
+     * `chrome.cast.Session#sendMessage`).
+     */
     "bridge:sendCastSessionMessage": {
         sessionId: string;
         namespace: string;
         messageData: object | string;
         messageId: string;
     };
-    "bridge:stopCastSession": {
-        receiverDevice: ReceiverDevice;
+    /**
+     * Sent to cast API instance from bridge when session message
+     * received from a receiver device.
+     */
+    "cast:receivedSessionMessage": {
+        sessionId: string;
+        namespace: string;
+        messageData: string;
     };
 
     /**
-     * getInfo uses the old :/ form for compat with old bridge
-     * versions.
+     * Sent to cast API instance from bridge whenever a message
+     * operation is completed. If an error ocurred, an error string will
+     * be passed as the `error` data property.
+     *
+     * TODO: Check how/if this works with receiver messages (via
+     * `bridge:sendCastReceiverMessage`).
      */
-    "bridge:getInfo": string;
-    "bridge:/getInfo": string;
-
-    "bridge:startDiscovery": {
-        shouldWatchStatus: boolean;
+    "cast:impl_sendMessage": {
+        sessionId: string;
+        messageId: string;
+        error?: string;
     };
 
+    /**
+     * Sent to the bridge to start an HTTP media server at a given file
+     * path on the given port.
+     */
     "bridge:startMediaServer": {
         filePath: string;
         port: number;
     };
-    "bridge:stopMediaServer": {};
+    /**
+     * Sent to media sender from bridge when the media server is ready
+     * to serve files.
+     */
     "mediaCast:mediaServerStarted": {
         mediaPath: string;
         subtitlePaths: string[];
         localAddress: string;
     };
+    /**
+     * Sent to bridge to stop HTTP media server.
+     */
+    "bridge:stopMediaServer": {};
+    /**
+     * Sent to media sender from bridge when the media server has
+     * stopped.
+     */
     "mediaCast:mediaServerStopped": {};
+    /**
+     * Sent to media sender from bridge when the media server has
+     * encountered an error.
+     */
     "mediaCast:mediaServerError": {};
-
-    // Device discovery
-    "main:receiverDeviceUp": { deviceId: string; deviceInfo: ReceiverDevice };
-    "main:receiverDeviceDown": { deviceId: string };
-    "main:receiverDeviceStatusUpdated": {
-        deviceId: string;
-        status: ReceiverStatus;
-    };
-    "main:receiverDeviceMediaStatusUpdated": {
-        deviceId: string;
-        status: MediaStatus;
-    };
 };
 
 type MessageDefinitions = ExtMessageDefinitions & AppMessageDefinitions;