Add support for schema-based message definitions

[shakyShane]

Feature entry pointbefore

Features can opt-in when ready. Each feature would contain 3 top-level keys

• notifications
• requests
• subscriptions

These are designed to match the messaging API directly, and will provide automatic documentation for
native teams as they integrate.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "WebCompatMessages",
  "description": "Requests, Notifications and Subscriptions from the Web Compat feature",
  "additionalProperties": false,
  "properties": {
    "notifications": {},
    "requests": {
      "oneOf": [
        {
          "$ref": "./web-compat/web-share.json"
        }
      ]
    },
    "subscriptions": {}
  },
  "required": [
    "requests",
    "notifications",
    "subscriptions"
  ]
}

Feature entry point NEW

Place a folder inside src/messages with at least 1 notification, request or subscription

📁 src/messages
  - 📁 duck-player
     - setUserValues.notify.json

When you have multiple messages, will look more like

📁 src/messages
  - 📁 duck-player
     - setUserValues.notify.json
     - getUserValues.request.json
     - getUserValues.response.json
     - onUserValuesUpdated.subscribe.json

src/messages

Individual Message

The important parts of a message are:

• method this is what native teams will map to their handlers
• params (optional) this is the payload we'll send in the outgoing message
• result (optional) this is the payload the native side will return in a response to a request.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "WebShare",
  "additionalProperties": false,
  "description": "todo: add description for `webShare` message",
  "required": ["method", "params", "result"],
  "properties": {
    "method": {
      "const": "webShare"
    },
    "params": {
      "title": "WebShareParams",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "title": {
          "description": "todo: add description for 'title' field",
          "type": "string"
        },
        "url": {
          "description": "todo: add description for 'url' field",
          "type": "string"
        },
        "text": {
          "description": "todo: add description for 'text' field",
          "type": "string"
        }
      }
    },
    "result": {
      "description": "todo: add return type here"
    }
  }
}

Individual Message NEW

Notifications

Notifications have 2 elements - method and params.

• method: this is represented in the filename, everything before the first . will be used
• params: in your json schema file, add the object type and properties as seen below

notification without params

{ "$schema": "http://json-schema.org/draft-07/schema#" }

Given the filename debug.notity.json, this will generate

export interface DebugNotification {
  method: "debug";
}

notification with params

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "additionalProperties": false,
  "required": ["a"],
  "properties": {
    "a": {
      "type": "string"
    }
  }
}

Given the filename debug.notity.json, this will generate

export interface SetValueNotification {
  method: "setValue";
  params: SetValueParams;
}
export interface SetValueParams {
  a: string;
}

requests & responses

Requests work the same, except they use the file format debug.request.json.

• method: as above, it's inferred from the filename
• params: as above

Requests differ from Notifications in that they have an optional return type.
To create a return type, create a new file debug.response.json.

As above, the response can contain an object with properties.

For example, it might be common to not have any params, but to expect a return types (for example, when fetching data).

To create that situation, create the following 2 file

• fetchData.request.json
• fetchData.response.json

{ "$schema": "http://json-schema.org/draft-07/schema#" }

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "MyData",
  "type": "object",
  "properties": {
    "a": {
      "type": "string"
    }
  }
}

These 2 files would create the following:

export interface FetchDataRequest {
  method: "setValue";
  result: MyData;
}
export interface MyData {
  a: string
}

subscriptions

Subscriptions use the file format onChange.subscribe.json.

• subscriptionEvent: onChange from the filename
• params: as above, anything specified under the top level type will be used

Generated Types

From those JSON files, we get these types that can be imported and used in each feature

/**
 * Requests, Notifications and Subscriptions from the Web Compat feature
 */
export interface WebCompatMessages {
  requests: WebShare;
}
/**
 * todo: add description for `webShare` message
 */
export interface WebShare {
  method: "webShare";
  params: WebShareParams;
  /**
   * todo: add return type here
   */
  result: {
    [k: string]: unknown;
  };
}
export interface WebShareParams {
  /**
   * todo: add description for 'title' field
   */
  title?: string;
  /**
   * todo: add description for 'url' field
   */
  url?: string;
  /**
   * todo: add description for 'text' field
   */
  text?: string;
}

Javascript Usage

Once we have the types, we can proxy calls to notify, request and subscribe and provide
type-checking.

For example, from the types above we know that this feature can only make a request for webShare.

export class WebCompat extends ContentFeature {
  init() {
    this.request('webShare', dataToSend)
      .then(result => console.log(result))
      .catch(console.error)
  }
}

[shakyShane]

• duckplayer typed messages #941
• Add support for schema-based message definitions #846 👈
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

Join @shakyShane and the rest of your teammates on Graphite

[shakyShane]

What's changed in the update:

• Removed the need to specify any types in the feature file 🎉
  • The original had a requirement where the feature author had to add the following JSDOC comment within each feature: @extends {ContentFeature<import('../types/web-compat.js').WebCompatMessages>}
  • The new version completely removes this - instead we import and augment the module inside a types files that the feature author never touches

[shakyShane]

@jonathanKingston I need to add a couple of unit tests for the code-gen part, but this is ready to re-review now :)

[shakyShane]

CC: @muodov

[shakyShane]

@jonathanKingston I updated the description with the new simpler model.

[shakyShane]

@jonathanKingston can you take another look through this 🙏🏻

[jonathanKingston]

Thanks for getting this over the line! Really great work!