544 Desktop Agent Bridging

docs/.markdownlint.jsonc

@@ -0,0 +1,11 @@
+{
+	//Disabled as we often use manual H1 heading for reference pages, 
+	// where the markdown metadata is picked up as the top level heading
+	"single-h1": false,
+	//Many lines in md files are longer than 80 chars
+	"line-length": false,
+	//We have repeated headings, like 'Properties' or 'Fields' in reference docs.
+	"no-duplicate-header": {
+		"siblings_only": true
+	}
+}

docs/api-bridging/ref/PrivateChannel.broadcast.md

@@ -0,0 +1,85 @@
+---
+id: PrivateChannel.broadcast
+sidebar_label: PC.broadcast
+title: PrivateChannel.broadcast
+---
+
+Desktop Agent bridging message exchange for a `broadcast` API call on a [`PrivateChannel`](../../api/ref/PrivateChannel). Generated by API calls:
+
+* [`PrivateChannel.broadcast(context: Context)`](../../api/ref/Channel#broadcast) (inherited from the [Channel](../../api/ref/Channel#broadcast) class)
+
+[Message Exchange Type](../spec#individual-message-exchanges): **Request only**
+
+:::caution
+
+Some additional tracking of PrivateChannel metadata is required on the Desktop Agent that created each PrivateChannel and on any Desktop Agent interacting with it, in order to use these message exchanges. Please see the [relevant section of the API Bridging overview](../spec#privatechannels) for more details.
+
+:::
+
+## Message exchange
+
+```mermaid
+sequenceDiagram
+    participant DA as Desktop Agent A
+    participant DAB as Desktop Agent Bridge
+    participant DB as Desktop Agent B
+    participant DC as Desktop Agent C
+    DA ->>+ DAB: PrivateChannel.broadcast
+    DAB ->>+ DB: PrivateChannel.broadcast
+```
+
+## Request format
+
+### Schema
+
+[https://fdc3.finos.org/schemas/next/bridging/privateChannelBroadcast.schema.json](/schemas/next/bridging/privateChannelBroadcast.schema.json)
+
+### Example
+
+```javascript
+fdc3.addIntentListener("QuoteStream", async (context) => {
+    const privateChannel: PrivateChannel = await fdc3.createPrivateChannel();
+    const symbol = context.id.ticker;
+
+    // This gets called when the remote side adds a context listener
+    const addContextListener = privateChannel.onAddContextListener((contextType) => {
+        // broadcast price quotes as they come in from our quote feed
+        feed.onQuote(symbol, (price) => {
+            privateChannel.broadcast({ type: "price", price});
+        });
+    });
+
+    ...
+
+    return channel;
+});
+```
+
+Broadcast messages that are sent from Agents that received the private channel from a remote agent are sent to the Desktop Agent that created the channel and returned it as an `IntentResult`, which is responsible for forwarding them onto other subscribers. If a broadcast message is generated on the Agent that created the channel it simply forwards it onto each subscriber.
+
+Hence, the broadcast message should be repeated once for each subscriber, and modified such that it includes a destination, specified as a full `AppIdentifier`, and the `type` should indicate that it is a `PrivateChannel` broadcast:
+
+```json
+// DAB -> agent-B
+{
+    "type": "PrivateChannel.broadcast", //modified type for PrivateChannel broadcasts
+    "payload": {
+        "channel": "private-channel-ABC123",
+        "context": { /*contextObj*/}
+    },
+    "meta": {
+        "requestGuid": "<requestGuid>",
+        "timestamp": "2020-03-...",
+        "source": {
+            "appId": "AChatApp",
+            "instanceId": "02e575aa-4c3a-4b66-acad-155073be21f6",
+            "desktopAgent": "agent-A" //added by DAB
+        },
+        "destination": {
+            "appId": "AnotherApp",
+            "instanceId": "02e235ba-acad-4b66-4c3a-547073be23f1",
+            "desktopAgent": "agent-B"
+        }
+    }
+}
+```

docs/api-bridging/ref/PrivateChannel.eventListenerAdded.md

@@ -0,0 +1,66 @@
+---
+id: PrivateChannel.eventListenerAdded
+sidebar_label: PC.eventListenerAdded
+title: PrivateChannel.eventListenerAdded
+---
+
+Desktop Agent bridging message exchange for the addition of an event handler to a [`PrivateChannel`](../../api/ref/PrivateChannel). Generated by API calls:
+
+* [`PrivateChannel.onAddContextListener(handler: (contextType?: string) => void)`](../../api/ref/PrivateChannel#onaddcontextlistener)
+* [`PrivateChannel.onUnsubscribe(handler: (contextType?: string) => void)`](../../api/ref/PrivateChannel#onunsubscribe)
+* [`PrivateChannel.onDisconnect(handler: () => void)`](../../api/ref/PrivateChannel#ondisconnect)
+
+[Message Exchange Type](../spec#individual-message-exchanges): **Request only**
+
+:::caution
+
+Some additional tracking of PrivateChannel metadata is required on the Desktop Agent that created each PrivateChannel and on any Desktop Agent interacting with it, in order to use these message exchanges. Please see the [relevant section of the API Bridging overview](../spec#privatechannels) for more details.
+
+:::
+
+Private channels support a number of additional event listeners (`onAddContextListener`, `onUnsubscribe`, `onDisconnect`), when an application adds one of these event listeners to a private channel that was created remotely and returned as an `IntentResult` (which should be tracked by the Desktop Agent Bridge client) a message needs to be sent to the agent that created the channel to facilitate routing of event messages. A single message type is used for this with a `payload.listenerType` field.
+
+## Message exchange
+
+```mermaid
+sequenceDiagram
+    participant DA as Desktop Agent A
+    participant DAB as Desktop Agent Bridge
+    participant DB as Desktop Agent B
+    participant DC as Desktop Agent C
+    DA ->>+ DAB: PrivateChannel.eventListenerAdded
+    DAB ->>+ DB: PrivateChannel.eventListenerAdded
+```
+
+## Request format
+
+### Schema
+
+[https://fdc3.finos.org/schemas/next/bridging/privateChannelEventListenerAdded.schema.json](/schemas/next/bridging/privateChannelEventListenerAdded.schema.json)
+
+### Example
+
+```json
+// agent-A -> DAB
+{
+    "type": "PrivateChannel.eventListenerAdded",
+    "payload": {
+        "channel": "private-channel-ABC123",
+        "listenerType": "onAddContextListener"
+    },
+    "meta": {
+        "requestGuid": "<requestGuid>",
+        "timestamp": "2020-03-...",
+        "source": {
+            "appId": "AChatApp",
+            "instanceId": "02e575aa-4c3a-4b66-acad-155073be21f6",
+            "desktopAgent": "agent-A" //added by DAB
+        },
+        "destination": {
+            "appId": "AnotherApp",
+            "instanceId": "02e235ba-acad-4b66-4c3a-547073be23f1",
+            "desktopAgent": "agent-B"
+        }
+    }
+}
+```

docs/api-bridging/ref/PrivateChannel.eventListenerRemoved.md

@@ -0,0 +1,69 @@
+---
+id: PrivateChannel.eventListenerRemoved
+sidebar_label: PC.eventListenerRemoved
+title: PrivateChannel.eventListenerRemoved
+---
+
+Desktop Agent bridging message exchange for the removal of an event handler from a [`PrivateChannel`](../../api/ref/PrivateChannel). Generated by API calls:
+
+* [`listener.unsubscribe()`](../../api/ref/Types#listener)
+  * for [`Listener`](../../api/ref/Types#listener) objects returned by [`PrivateChannel`](../../api/ref/PrivateChannel) functions:
+    * [`onAddContextListener(handler: (contextType?: string)`](../../api/ref/PrivateChannel#onaddcontextlistener)
+    * [`onUnsubscribe(handler: (contextType?: string) => void)`](../../api/ref/PrivateChannel#onunsubscribe)
+    * [`onDisconnect(handler: () => void)`](../../api/ref/PrivateChannel#ondisconnect)
+* [`PrivateChannel.disconnect()`](../../api/ref/PrivateChannel#disconnect)
+
+[Message Exchange Type](../spec#individual-message-exchanges): **Request only**
+
+:::caution
+
+Some additional tracking of PrivateChannel metadata is required on the Desktop Agent that created each PrivateChannel and on any Desktop Agent interacting with it, in order to use these message exchanges. Please see the [relevant section of the API Bridging overview](../spec#privatechannels) for more details.
+
+:::
+
+Private channels support a number of additional event listeners (`onAddContextListener`, `onUnsubscribe`, `onDisconnect`), when an application removes an event listener from a PrivateChannel that was created remotely and returned as an `IntentResult` (which should be tracked by the Desktop Agent Bridge client) a message needs to be sent to the agent that created the channel so it can discard retained routing information. A single message type is used for this with a `payload.listenerType` field.
+
+## Message exchange
+
+```mermaid
+sequenceDiagram
+    participant DA as Desktop Agent A
+    participant DAB as Desktop Agent Bridge
+    participant DB as Desktop Agent B
+    participant DC as Desktop Agent C
+    DA ->>+ DAB: PrivateChannel.eventListenerRemoved
+    DAB ->>+ DB: PrivateChannel.eventListenerRemoved
+```
+
+## Request format
+
+### Schema
+
+[https://fdc3.finos.org/schemas/next/bridging/privateChannelEventListenerRemoved.schema.json](/schemas/next/bridging/privateChannelEventListenerRemoved.schema.json)
+
+### Example
+
+```json
+// agent-A -> DAB
+{
+    "type": "PrivateChannel.eventListenerRemoved",
+    "payload": {
+        "channel": "private-channel-ABC123",
+        "listenerType": "onAddContextListener"
+    },
+    "meta": {
+        "requestGuid": "<requestGuid>",
+        "timestamp": "2020-03-...",
+        "source": {
+            "appId": "AChatApp",
+            "instanceId": "02e575aa-4c3a-4b66-acad-155073be21f6",
+            "desktopAgent": "agent-A" //added by DAB
+        },
+        "destination": {
+            "appId": "AnotherApp",
+            "instanceId": "02e235ba-acad-4b66-4c3a-547073be23f1",
+            "desktopAgent": "agent-B"
+        }
+    }
+}
+```

docs/api-bridging/ref/PrivateChannel.onAddContextListener.md

@@ -0,0 +1,64 @@
+---
+id: PrivateChannel.onAddContextListener
+sidebar_label: PC.onAddContextListener
+title: PrivateChannel.onAddContextListener
+---
+
+Desktop Agent bridging message exchange for the addition of a [`ContextHandler`](../../api/ref/Types#contexthandler) to a [`PrivateChannel`](../../api/ref/PrivateChannel). Generated by API call:
+
+* [`PrivateChannel.addContextListener(contextType: string | null, handler: ContextHandler)`](../../api/ref/Channel#addcontextlistener) (inherited from `Channel`)
+
+[Message Exchange Type](../spec#individual-message-exchanges): **Request only**
+
+:::caution
+
+Some additional tracking of PrivateChannel metadata is required on the Desktop Agent that created each PrivateChannel and on any Desktop Agent interacting with it, in order to use these message exchanges. Please see the [relevant section of the API Bridging overview](../spec#privatechannels) for more details.
+
+:::
+
+When a `ContextListener` is added to a `PrivateChannel` any applications that have added an `onAddContextListener` handler MUST be notified. If the listener is on the agent that created that channel, it should forward the message onto all the registered listeners. If the listener is added on a remote agent it MUST send the message to the agent that created the channel which will repeat it onto the other listeners without modifying the source information.
+
+## Message exchange
+
+```mermaid
+sequenceDiagram
+    participant DA as Desktop Agent A
+    participant DAB as Desktop Agent Bridge
+    participant DB as Desktop Agent B
+    participant DC as Desktop Agent C
+    DA ->>+ DAB: PrivateChannel.onAddContextListener
+    DAB ->>+ DB: PrivateChannel.onAddContextListener
+```
+
+## Request format
+
+### Schema
+
+[https://fdc3.finos.org/schemas/next/bridging/privateChannelOnAddContextListener.schema.json](/schemas/next/bridging/privateChannelOnAddContextListener.schema.json)
+
+### Example
+
+```json
+// agent-A -> DAB
+{
+    "type": "PrivateChannel.onAddContextListener",
+    "payload": {
+        "channel": "private-channel-ABC123",
+        "contextType": "fdc3.instrument"
+    },
+    "meta": {
+        "requestGuid": "<requestGuid>",
+        "timestamp": "2020-03-...",
+        "source": {
+            "appId": "AnotherApp",
+            "instanceId": "02e235ba-acad-4b66-4c3a-547073be23f1",
+            "desktopAgent": "agent-B" //added by DAB
+        },
+        "destination": {
+            "appId": "AChatApp",
+            "instanceId": "02e575aa-4c3a-4b66-acad-155073be21f6",
+            "desktopAgent": "agent-A"
+        }
+    }
+}
+```

docs/api-bridging/ref/PrivateChannel.onDisconnect.md

@@ -0,0 +1,63 @@
+---
+id: PrivateChannel.onDisconnect
+sidebar_label: PC.onDisconnect
+title: PrivateChannel.onDisconnect
+---
+
+Desktop Agent bridging message exchange for a `disconnect()` API call on  [`PrivateChannel`](../../api/ref/PrivateChannel). Generated by API call:
+
+* [`PrivateChannel.disconnect()`](../../api/ref/PrivateChannel#disconnect)
+
+[Message Exchange Type](../spec#individual-message-exchanges): **Request only**
+
+:::caution
+
+Some additional tracking of PrivateChannel metadata is required on the Desktop Agent that created each PrivateChannel and on any Desktop Agent interacting with it, in order to use these message exchanges. Please see the [relevant section of the API Bridging overview](../spec#privatechannels) for more details.
+
+:::
+
+When the `disconnect` function is is called on a `PrivateChannel` any applications that have added an `onDisconnect` handler or an `onUnsubscribe` handler (which is automatically called when an application disconnects) MUST be notified. If the listener is on the agent that created that channel, it should forward the message onto all the registered listeners. If the listener is added on a remote agent it MUST send the message to the agent that created the channel which will repeat it onto the other listeners without modifying the source information. If the `PrivateChannel` was created by a remote agent, only the single `PrivateChannel.onDisconnect` is required. It is the responsibility of the Desktop Agent that created the channel to ensure that any relevant `onUnsubscribe` handlers are also called by sending additional `PrivateChannel.onUnsubscribe` messages to them before forwarding the `PrivateChannel.onDisconnect`. This applies whether the disconnection occurred on that agent or on a remote agent.
+
+## Message exchange
+
+```mermaid
+sequenceDiagram
+    participant DA as Desktop Agent A
+    participant DAB as Desktop Agent Bridge
+    participant DB as Desktop Agent B
+    participant DC as Desktop Agent C
+    DA ->>+ DAB: PrivateChannel.onDisconnect
+    DAB ->>+ DB: PrivateChannel.onDisconnect
+```
+
+## Request format
+
+### Schema
+
+[https://fdc3.finos.org/schemas/next/bridging/privateChannelOnDisconnect.schema.json](/schemas/next/bridging/privateChannelOnDisconnect.schema.json)
+
+### Example
+
+```json
+// agent-A -> DAB
+{
+    "type": "PrivateChannel.onDisconnect",
+    "payload": {
+        "channel": "private-channel-ABC123"
+    },
+    "meta": {
+        "requestGuid": "<requestGuid>",
+        "timestamp": "2020-03-...",
+        "source": {
+            "appId": "AnotherApp",
+            "instanceId": "02e235ba-acad-4b66-4c3a-547073be23f1",
+            "desktopAgent": "agent-B" //added by DAB
+        },
+        "destination": {
+            "appId": "AChatApp",
+            "instanceId": "02e575aa-4c3a-4b66-acad-155073be21f6",
+            "desktopAgent": "agent-A"
+        }
+    }
+}
+```