DuckPlayer: Updated messaging docs & data types (#412)

* Updated messaging docs & data types

* lint

* lint

* lint

---------

Co-authored-by: Shane Osbourne <[email protected]>

Author: shakyShane

.eslintignore

@@ -1,8 +1,8 @@
 build/
 docs/
-lib/
+/lib
 Sources/ContentScopeScripts/dist/
 integration-test/extension/contentScope.js
 integration-test/pages/build
 packages/special-pages/pages/**/public
-unit-test/script-overload-snapshots/
+unit-test/script-overload-snapshots/

package.json

@@ -20,6 +20,7 @@
     "build-windows": "node scripts/inject.js --platform windows",
     "build-integration": "node scripts/inject.js --platform integration",
     "docs": "typedoc",
+    "docs.watch": "typedoc --watch",
     "postbuild": "npm run build --workspaces --if-present",
     "tsc": "tsc",
     "tsc.watch": "tsc --watch",

packages/messaging/index.js

@@ -12,28 +12,47 @@
  *     - For example, to learn what configuration is required for Webkit, see: {@link WebkitMessagingConfig}
  *     - Or, to learn about how messages are sent and received in Webkit, see {@link WebkitMessagingTransport}
  *
- * @example Webkit Messaging
+ * ## Links
+ * Please see the following links for examples
  *
- * ```javascript
- * [[include:packages/messaging/lib/examples/webkit.example.js]]```
+ * - Windows: {@link WindowsMessagingConfig}
+ * - Webkit: {@link WebkitMessagingConfig}
+ * - Schema: {@link "Messaging Schema"}
  *
- * @example Windows Messaging
- *
- * ```javascript
- * [[include:packages/messaging/lib/examples/windows.example.js]]```
  */
-import { WindowsMessagingConfig, WindowsMessagingTransport, WindowsInteropMethods } from './lib/windows.js'
+import { WindowsMessagingConfig, WindowsMessagingTransport, WindowsInteropMethods, WindowsNotification, WindowsRequestMessage } from './lib/windows.js'
 import { WebkitMessagingConfig, WebkitMessagingTransport } from './lib/webkit.js'
+import { NotificationMessage, RequestMessage, Subscription, MessageResponse, MessageError, SubscriptionEvent } from './schema.js'
 
 /**
- * @implements {MessagingTransport}
+ * Common options/config that are *not* transport specific.
+ */
+export class MessagingContext {
+    /**
+     * @param {object} params
+     * @param {string} params.context
+     * @param {string} params.featureName
+     * @param {"production" | "development"} params.env
+     * @internal
+     */
+    constructor (params) {
+        this.context = params.context
+        this.featureName = params.featureName
+        this.env = params.env
+    }
+}
+
+/**
+ *
  */
 export class Messaging {
     /**
-     * @param {WebkitMessagingConfig | WindowsMessagingConfig} config
+     * @param {MessagingContext} messagingContext
+     * @param {WebkitMessagingConfig | WindowsMessagingConfig | TestTransportConfig} config
      */
-    constructor (config) {
-        this.transport = getTransport(config)
+    constructor (messagingContext, config) {
+        this.messagingContext = messagingContext
+        this.transport = getTransport(config, this.messagingContext)
     }
 
     /**
@@ -50,7 +69,13 @@ export class Messaging {
      * @param {Record<string, any>} [data]
      */
     notify (name, data = {}) {
-        this.transport.notify(name, data)
+        const message = new NotificationMessage({
+            context: this.messagingContext.context,
+            featureName: this.messagingContext.featureName,
+            method: name,
+            params: data
+        })
+        this.transport.notify(message)
     }
 
     /**
@@ -68,7 +93,15 @@ export class Messaging {
      * @return {Promise<any>}
      */
     request (name, data = {}) {
-        return this.transport.request(name, data)
+        const id = name + '.response'
+        const message = new RequestMessage({
+            context: this.messagingContext.context,
+            featureName: this.messagingContext.featureName,
+            method: name,
+            params: { data: '' },
+            id
+        })
+        return this.transport.request(message)
     }
 
     /**
@@ -77,7 +110,12 @@ export class Messaging {
      * @return {() => void}
      */
     subscribe (name, callback) {
-        return this.transport.subscribe(name, callback)
+        const msg = new Subscription({
+            context: this.messagingContext.context,
+            featureName: this.messagingContext.featureName,
+            subscriptionName: name
+        })
+        return this.transport.subscribe(msg, callback)
     }
 }
 
@@ -86,44 +124,90 @@ export class Messaging {
  */
 export class MessagingTransport {
     /**
-     * @param {string} name
-     * @param {Record<string, any>} [data]
+     * @param {NotificationMessage} msg
      * @returns {void}
      */
-    notify (name, data = {}) {
+    notify (msg) {
         throw new Error("must implement 'notify'")
     }
 
     /**
-     * @param {string} name
-     * @param {Record<string, any>} [data]
+     * @param {RequestMessage} msg
      * @param {{signal?: AbortSignal}} [options]
      * @return {Promise<any>}
      */
-    request (name, data = {}, options = {}) {
+    request (msg, options = {}) {
         throw new Error('must implement')
     }
 
     /**
-     * @param {string} name
+     * @param {Subscription} msg
      * @param {(value: unknown) => void} callback
      * @return {() => void}
      */
-    subscribe (name, callback) {
+    subscribe (msg, callback) {
         throw new Error('must implement')
     }
 }
 
 /**
- * @param {WebkitMessagingConfig | WindowsMessagingConfig} config
+ * Use this to create testing transport on the fly.
+ * It's useful for debugging, and for enabling scripts to run in
+ * other environments - for example, testing in a browser without the need
+ * for a full integration
+ *
+ * ```js
+ * [[include:packages/messaging/lib/examples/test.example.js]]```
+ */
+export class TestTransportConfig {
+    /**
+     * @param {MessagingTransport} impl
+     */
+    constructor (impl) {
+        this.impl = impl
+    }
+}
+
+/**
+ * @implements {MessagingTransport}
+ */
+export class TestTransport {
+    /**
+     * @param {TestTransportConfig} config
+     * @param {MessagingContext} messagingContext
+     */
+    constructor (config, messagingContext) {
+        this.config = config
+        this.messagingContext = messagingContext
+    }
+
+    notify (msg) {
+        return this.config.impl.notify(msg)
+    }
+
+    request (msg, options) {
+        return this.config.impl.request(msg)
+    }
+
+    subscribe (msg, callback) {
+        return this.config.impl.subscribe(msg, callback)
+    }
+}
+
+/**
+ * @param {WebkitMessagingConfig | WindowsMessagingConfig | TestTransportConfig} config
+ * @param {MessagingContext} messagingContext
  * @returns {MessagingTransport}
  */
-function getTransport (config) {
+function getTransport (config, messagingContext) {
     if (config instanceof WebkitMessagingConfig) {
-        return new WebkitMessagingTransport(config)
+        return new WebkitMessagingTransport(config, messagingContext)
     }
     if (config instanceof WindowsMessagingConfig) {
-        return new WindowsMessagingTransport(config)
+        return new WindowsMessagingTransport(config, messagingContext)
+    }
+    if (config instanceof TestTransportConfig) {
+        return new TestTransport(config, messagingContext)
     }
     throw new Error('unreachable')
 }
@@ -150,5 +234,13 @@ export {
     WebkitMessagingTransport,
     WindowsMessagingConfig,
     WindowsMessagingTransport,
-    WindowsInteropMethods
+    WindowsInteropMethods,
+    NotificationMessage,
+    RequestMessage,
+    Subscription,
+    MessageResponse,
+    MessageError,
+    SubscriptionEvent,
+    WindowsNotification,
+    WindowsRequestMessage
 }

packages/messaging/lib/examples/payloads.js

@@ -0,0 +1,59 @@
+import { NotificationMessage, RequestMessage, MessageResponse, SubscriptionEvent } from '../../index.js'
+
+/**
+ * This is the payload sent for a notification
+ * @type {NotificationMessage}
+ */
+const notification = {
+    context: 'contentScopeScripts',
+    featureName: 'duckPlayerOverlays',
+    method: 'setUserValues',
+    params: {}
+}
+
+/**
+ * This is the payload sent for a Request.
+ * @type {RequestMessage}
+ */
+const request = {
+    context: 'contentScopeScripts',
+    featureName: 'duckPlayerOverlays',
+    method: 'setUserValues',
+    params: {},
+    id: 'setUserValues.response'
+}
+
+/**
+ * This is the payload for a response
+ * @type {MessageResponse}
+ */
+const messageResponse = {
+    context: 'contentScopeScripts',
+    featureName: 'duckPlayerOverlays',
+    result: {},
+    id: 'setUserValues.response',
+    error: undefined
+}
+
+/**
+ * This is the payload response for an error
+ * @type {MessageResponse}
+ */
+const messageResponseError = {
+    context: 'contentScopeScripts',
+    featureName: 'duckPlayerOverlays',
+    result: undefined,
+    id: 'setUserValues.response',
+    error: { message: '' }
+}
+
+/**
+ * This is the payload response for a subscriptionEvent
+ * @type {SubscriptionEvent}
+ */
+const event = {
+    context: 'contentScopeScripts',
+    featureName: 'duckPlayerOverlays',
+    subscriptionName: 'setUserValues',
+    params: {}
+}

packages/messaging/lib/examples/test.example.js

@@ -0,0 +1,53 @@
+import { Messaging, MessagingContext, TestTransportConfig } from '../../index.js'
+
+/**
+ * Creates an ad-hoc messaging transport on the fly - useful for testing
+ * You need to implement
+ * - notify
+ * - request
+ * - subscribe
+ */
+const config = new TestTransportConfig({
+    notify (msg) {
+        console.log(msg)
+    },
+    request: (msg) => {
+        if (msg.method === 'getUserValues') {
+            return Promise.resolve({
+                foo: 'bar'
+            })
+        }
+        return Promise.resolve(null)
+    },
+    subscribe (msg) {
+        console.log(msg)
+        return () => {
+            console.log('teardown')
+        }
+    }
+})
+
+const messagingContext = new MessagingContext({
+    context: 'contentScopeScripts',
+    featureName: 'hello-world',
+    env: 'development'
+})
+
+/**
+ * And then send notifications!
+ */
+const messaging = new Messaging(messagingContext, config)
+messaging.notify('helloWorld')
+
+/**
+ * Or request some data
+ */
+messaging.request('getData', { foo: 'bar' }).then(console.log).catch(console.error)
+
+/**
+ * Or subscribe for push messages
+ */
+const unsubscribe = messaging.subscribe('getData', (data) => console.log(data))
+
+// later
+unsubscribe()