Context Clearing

CHANGELOG.md

@@ -13,6 +13,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 * Added details of and procedures for resolving fully-qualified appIds and unqualified appIds in the API and Bridging Parts of the Standard. ([#1523](https://github.com/finos/FDC3/pull/1523))
 
+* Added `clearContext` function to the `Channel` API, to be able to clear specific or all context types from the channel. ([#1379](https://github.com/finos/FDC3/pull/1379))
+
 ### Changed
 
 ### Deprecated
@@ -50,6 +52,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added .NET docs for Events to API reference. ([#1441](https://github.com/finos/FDC3/pull/1441))
 * Setup package publishing for mono-repo packages. ([#1520](https://github.com/finos/FDC3/pull/1520))
 * Implementation PR for FDC3 for the Web ([#896](https://github.com/finos/FDC3/pull/896))
+  - resolves ([#1209](https://github.com/finos/FDC3/issues/1209))
+  - resolves ([#1297](https://github.com/finos/FDC3/issues/1297)) 
+  - resolves ([#1429](https://github.com/finos/FDC3/issues/1429)) 
+  - resolves ([#1430](https://github.com/finos/FDC3/issues/1430))
+  - resolves ([#1431](https://github.com/finos/FDC3/issues/1431))
+  - resolves ([#1432](https://github.com/finos/FDC3/issues/1432)) 
+  - resolves ([#1433](https://github.com/finos/FDC3/issues/1433))
+  - resolves ([#1468](https://github.com/finos/FDC3/issues/1468))
+  - resolves ([#810](https://github.com/finos/FDC3/issues/810))
+  - resolves ([#832](https://github.com/finos/FDC3/issues/832))
+  - resolves ([#1487](https://github.com/finos/FDC3/issues/1487))
+  - resolves ([#1488](https://github.com/finos/FDC3/issues/1488))
 * Adjusted reference Desktop Agent implementation for FDC3 for Web to open a new app instance when raiseIntent is called with an appId but no instanceId ([#1556](https://github.com/finos/FDC3/pull/1556))
 
 ### Changed

packages/fdc3-agent-proxy/src/channels/DefaultChannel.ts

@@ -1,13 +1,17 @@
-import { ContextHandler, DisplayMetadata, Listener, Channel } from '@finos/fdc3-standard';
+import { ContextHandler, DisplayMetadata, Listener, Channel, EventHandler } from '@finos/fdc3-standard';
 import { Context } from '@finos/fdc3-context';
 import { Messaging } from '../Messaging';
 import { DefaultContextListener } from '../listeners/DefaultContextListener';
 import {
   BroadcastRequest,
   BroadcastResponse,
+  ClearContextRequest,
+  ClearContextResponse,
   GetCurrentContextRequest,
   GetCurrentContextResponse,
 } from '@finos/fdc3-schema/generated/api/BrowserTypes';
+import { RegisterableListener } from '../listeners/RegisterableListener';
+import { EventListener } from '../listeners/EventListener';
 
 export class DefaultChannel implements Channel {
   protected readonly messaging: Messaging;
@@ -98,4 +102,30 @@ export class DefaultChannel implements Channel {
     await listener.register();
     return listener;
   }
+
+  async clearContext(contextType?: string): Promise<void> {
+    // first, ensure channel state is up-to-date
+    const request: ClearContextRequest = {
+      meta: this.messaging.createMeta(),
+      payload: {
+        channelId: this.id,
+        contextType: contextType ?? null,
+      },
+      type: 'clearContextRequest',
+    };
+    await this.messaging.exchange<ClearContextResponse>(request, 'clearContextResponse', this.messageExchangeTimeout);
+  }
+
+  async addEventListener(type: string | null, handler: EventHandler): Promise<Listener> {
+    let listener: RegisterableListener;
+    switch (type) {
+      case 'contextCleared':
+        listener = new EventListener(this.messaging, 'contextCleared', handler);
+        break;
+      default:
+        throw new Error('Unsupported event type: ' + type);
+    }
+    await listener.register();
+    return listener;
+  }
 }

packages/fdc3-schema/schemas/api/agentResponse.schema.json

@@ -35,7 +35,8 @@
         "privateChannelUnsubscribeEventListenerResponse",
         "raiseIntentForContextResponse",
         "raiseIntentResponse",
-        "raiseIntentResultResponse"
+        "raiseIntentResultResponse",
+        "clearContextResponse"
       ],
       "description": "Identifies the type of the message and it is typically set to the FDC3 function name that the message relates to, e.g. 'findIntent', with 'Response' appended."
     },

packages/fdc3-schema/schemas/api/appRequest.schema.json

@@ -35,7 +35,8 @@
         "privateChannelDisconnectRequest",
         "privateChannelUnsubscribeEventListenerRequest",
         "raiseIntentForContextRequest",
-        "raiseIntentRequest"
+        "raiseIntentRequest",
+        "clearContextRequest"
       ],
       "description": "Identifies the type of the message and it is typically set to the FDC3 function name that the message relates to, e.g. 'findIntent', with 'Request' appended."
     },

packages/fdc3-schema/schemas/api/clearContextRequest.schema.json

@@ -0,0 +1,56 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://fdc3.finos.org/schemas/next/api/clearContextRequest.schema.json",
+	"type": "object",
+	"title": "Clear Context Request",
+	"description": "A request to clear context on a channel.",
+	"allOf": [
+		{
+			"$ref": "appRequest.schema.json"
+		},
+		{
+			"type": "object",
+			"properties": {
+				"type": {
+					"$ref": "#/$defs/ClearContextRequestType"
+				},
+				"payload": {
+					"$ref": "#/$defs/ClearContextRequestPayload"
+				},
+				"meta": true
+			},
+			"additionalProperties": false
+		}
+	],
+	"$defs": {
+		"ClearContextRequestType": {
+			"title": "Clear Context Request Message Type",
+			"const": "clearContextRequest"
+		},
+		"ClearContextRequestPayload": {
+			"title": "Clear Context Request Payload",
+			"type": "object",
+			"properties": {
+				"channelId": {
+					"title": "Channel Id",
+					"description": "The id of the channel to clear the context on.",
+					"type": "string"
+				},
+				"contextType": {
+					"title": "Context type",
+					"description": "The type of context to clear for OR `null` indicating that all context types on the channel should be cleared.",
+					"oneOf": [
+						{
+							"type": "string"
+						},
+						{
+							"type": "null"
+						}
+					]
+				}
+			},
+			"required": ["channelId", "contextType"],
+			"additionalProperties": false
+		}
+	}
+}

packages/fdc3-schema/schemas/api/clearContextResponse.schema.json

@@ -0,0 +1,29 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://fdc3.finos.org/schemas/next/api/clearContextResponse.schema.json",
+	"type": "object",
+	"title": "Clear Context Response",
+	"description": "A response to a request to clear context on a channel.",
+	"allOf": [
+		{
+			"$ref": "agentResponse.schema.json"
+		},
+		{
+			"type": "object",
+			"properties": {
+				"type": {
+					"$ref": "#/$defs/ClearContextResponseType"
+				},
+				"payload": true,
+				"meta": true
+			},
+			"additionalProperties": false
+		}
+	],
+	"$defs": {
+		"ClearContextResponseType": {
+			"title": "Clear Context Response Message Type",
+			"const": "clearContextResponse"
+		}
+	}
+}

packages/fdc3-standard/src/api/Channel.ts

@@ -7,6 +7,7 @@
 import { ContextHandler } from './Types';
 import { DisplayMetadata } from './DisplayMetadata';
 import { Listener } from './Listener';
+import { EventHandler } from './Events';
 
 /**
  * Represents a context channel that applications can use to send and receive
@@ -73,8 +74,40 @@
    */
   addContextListener(contextType: string | null, handler: ContextHandler): Promise<Listener>;
 
+  /**
+   * Clears context from the channel, and broadcasts an `fdc3.nothing` context to notify existing listeners that the context was cleared. Listeners added to the channel and calls to [`getCurrentContext`](#getcurrentcontext) will not receive any existing context until new context is broadcast to the channel. 
+   * 
+   * If a `contextType` is provided, only contexts of that type will be cleared and the `contextType` of the `fdc3.nothing` context will be set to that type name. 
+   * 
+   * If no `contextType` is provided, all contexts will be cleared and the `contextType` of the `fdc3.nothing` context will be omitted.
+   */
+  clearContext(contextType?: string): Promise<void>;
+
+  /**
+   * Register a handler for events from the Channel. Whenever the handler function
+   * is called it will be passed an event object with details related to the event.
+   *
+   * ```js
+   * // any event type
+   * const listener = await myChannel.addEventListener(null, event => {
+   *   console.log(`Received event ${event.type}\n\tDetails: ${event.details}`);
+   * });
+   *
+   * // listener for a specific event type
+   * const contextClearedListener = await myChannel.addEventListener(
+   *    "contextCleared",
+   *    event => { ... }
+   * );
+   * ```
+   *
+   * @param {string | null} type If non-null, only events of the specified type will be received by the handler.
+   * @param {EventHandler} handler A function that events received will be passed to.
+   *
+   */
+  addEventListener(type: string | null, handler: EventHandler): Promise<Listener>;  
+
   /**
    * @deprecated use `addContextListener(null, handler)` instead of `addContextListener(handler)`.
    */
   addContextListener(handler: ContextHandler): Promise<Listener>;
 }

packages/fdc3-standard/src/api/Events.ts

@@ -46,6 +46,16 @@ export interface FDC3ChannelChangedEvent extends FDC3Event {
   };
 }
 
+/**
+ * Type defining the format of event `contextCleared` objects
+ */
+export interface FDC3ContextClearedEvent extends FDC3Event {
+  readonly type: 'contextCleared';
+  readonly details: {
+    contextType: string | null;
+  };
+}
+
 /**
  * Type defining valid type strings for Private Channel events.
  */

website/docs/api/conformance/App-Channel-Tests.md

@@ -60,3 +60,19 @@ hide_title: true
 - `ACContextHistoryTyped`: Perform above test.
 - `ACContextHistoryMultiple`: **B** Broadcasts multiple history items of both types.  Ensure that only the last version of each type is received by **A**.
 - `ACContextHistoryLast`: In step 5. **A** retrieves the _untyped_ current context of the channel via `const currentContext = await testChannel.getCurrentContext()`. Ensure that A receives only the very last broadcast context item _of any type_.
+
+
+## Clearing Context
+
+| App | Step                    | Details                                                         |
+|-----|-------------------------|-----------------------------------------------------------------|
+| A   | 1. Retrieve `Channel`   | Retrieve a `Channel` object representing an 'App' channel called `test-channel` using: <br />`const testChannel = await fdc3.getOrCreateChannel("test-channel")` |
+| A   | 2. Add Context Listener | Add an _typed_ context listener for `fdc3.instrument`, using: <br />`await testChannel.addContextListener("fdc3.instrument",handler)`|
+| B   | 3. Retrieve `Channel`   | Retrieve a `Channel` object representing the same 'App' channel A did (`test-channel`)|
+| B   | 4. Broadcast            | B broadcasts both an `fdc3.instrument` context and an `fdc3.contact` context, using: <br /> `testChannel.broadcast(<fdc3.instrument>)` <br /> `testChannel.broadcast(<fdc3.contact>)`|
+| A   | 5. Receive Context      | An fdc3.instrument context is received by the handler added in step 2.<br />Ensure that the fdc3.instrument received by A is identical to that sent by B<br />Ensure that the fdc3.contact context is NOT received.                                                                   |
+| A   | 6. Add Event Listener    | Add an event listener for `contextCleared` event, using: <br />`await testChannel.addEventListener("contextCleared",handler)`  |
+| B   | 7. Clear Context            | B clears context using `testChannel.clearContext()`|
+
+- `ACClearContext1`: Perform above test.
+- `ACClearContext2`: Perform above test, but add specific type of the context type to the `testChannel.clearContext()`.