Context clearing (1197)

CHANGELOG.md

@@ -14,6 +14,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added clarification regarding expected behavior upon repeated calls to `addContextListener` on same or overlapping types (allowed) and `addIntentListener` on same intent (rejected; new error type added). ([#1394](https://github.com/finos/FDC3/pull/1394))
 * Ported FDC3 Conformance Project as-is into the FDC3 Monorepo, just including minimal fixes for typescript compilation. ([#1576](https://github.com/finos/FDC3/pull/1576))
 
+* Added `clearContext` function and associated `contextClearedEvent` 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

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/generated/bridging/BridgingTypes.ts

@@ -114,9 +114,9 @@ export interface ErrorResponseMessagePayload {
  * Constants representing the errors that can be encountered when calling the `open` method
  * on the DesktopAgent object (`fdc3`).
  *
- * Constants representing the errors that can be encountered when calling the `findIntent`,
- * `findIntentsByContext`, `raiseIntent` or `raiseIntentForContext` methods on the
- * DesktopAgent (`fdc3`).
+ * Constants representing the errors that can be encountered when calling the
+ * `addIntentListener`, `findIntent`, `findIntentsByContext`, `raiseIntent` or
+ * `raiseIntentForContext` methods on the DesktopAgent (`fdc3`).
  */
 export type ResponseErrorDetail =
   | 'AccessDenied'
@@ -136,6 +136,7 @@ export type ResponseErrorDetail =
   | 'TargetAppUnavailable'
   | 'TargetInstanceUnavailable'
   | 'UserCancelledResolution'
+  | 'IntentListenerConflict'
   | 'IntentHandlerRejected'
   | 'NoResultReturned'
   | 'AgentDisconnected'
@@ -1134,9 +1135,9 @@ export interface PayloadClass {
  *
  * Should be set if the raiseIntent request returned an error.
  *
- * Constants representing the errors that can be encountered when calling the `findIntent`,
- * `findIntentsByContext`, `raiseIntent` or `raiseIntentForContext` methods on the
- * DesktopAgent (`fdc3`).
+ * Constants representing the errors that can be encountered when calling the
+ * `addIntentListener`, `findIntent`, `findIntentsByContext`, `raiseIntent` or
+ * `raiseIntentForContext` methods on the DesktopAgent (`fdc3`).
  *
  * Array of error message strings for responses that were not returned to the bridge before
  * the timeout or because an error occurred. Should be the same length as the `errorSources`
@@ -1157,6 +1158,7 @@ export type FindInstancesErrors =
   | 'UserCancelledResolution'
   | 'ApiTimeout'
   | 'InvalidArguments'
+  | 'IntentListenerConflict'
   | 'AgentDisconnected'
   | 'NotConnectedToBridge'
   | 'ResponseToBridgeTimedOut'
@@ -2572,9 +2574,9 @@ export interface OpenAgentErrorResponsePayload {
  * the timeout or because an error occurred. Should be the same length as the `errorSources`
  * array and ordered the same. May be omitted if all sources responded without errors.
  *
- * Constants representing the errors that can be encountered when calling the `findIntent`,
- * `findIntentsByContext`, `raiseIntent` or `raiseIntentForContext` methods on the
- * DesktopAgent (`fdc3`).
+ * Constants representing the errors that can be encountered when calling the
+ * `addIntentListener`, `findIntent`, `findIntentsByContext`, `raiseIntent` or
+ * `raiseIntentForContext` methods on the DesktopAgent (`fdc3`).
  */
 export type OpenErrorResponsePayload =
   | 'AppNotFound'
@@ -4031,9 +4033,9 @@ export interface RaiseIntentResultAgentErrorResponsePayload {
  * Constants representing the errors that can be encountered when calling the `open` method
  * on the DesktopAgent object (`fdc3`).
  *
- * Constants representing the errors that can be encountered when calling the `findIntent`,
- * `findIntentsByContext`, `raiseIntent` or `raiseIntentForContext` methods on the
- * DesktopAgent (`fdc3`).
+ * Constants representing the errors that can be encountered when calling the
+ * `addIntentListener`, `findIntent`, `findIntentsByContext`, `raiseIntent` or
+ * `raiseIntentForContext` methods on the DesktopAgent (`fdc3`).
  */
 export type RaiseIntentResultErrorMessage =
   | 'IntentHandlerRejected'
@@ -6489,6 +6491,7 @@ const typeMap: any = {
     'ErrorOnLaunch',
     'IntentDeliveryFailed',
     'IntentHandlerRejected',
+    'IntentListenerConflict',
     'InvalidArguments',
     'MalformedContext',
     'MalformedMessage',
@@ -6538,6 +6541,7 @@ const typeMap: any = {
     'AgentDisconnected',
     'DesktopAgentNotFound',
     'IntentDeliveryFailed',
+    'IntentListenerConflict',
     'InvalidArguments',
     'MalformedContext',
     'MalformedMessage',

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

@@ -16,7 +16,8 @@
         "intentEvent",
         "privateChannelOnAddContextListenerEvent",
         "privateChannelOnDisconnectEvent",
-        "privateChannelOnUnsubscribeEvent"
+        "privateChannelOnUnsubscribeEvent",
+        "contextClearedEvent"
       ],
       "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/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-schema/schemas/api/contextClearedEvent.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://fdc3.finos.org/schemas/next/api/contextClearedEvent.schema.json",
+  "type": "object",
+  "title": "contextCleared Event",
+  "description": "An event message from the Desktop Agent to an app indicating that context has been cleared on a channel.",
+  "allOf": [
+    {
+      "$ref": "agentEvent.schema.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "$ref": "#/$defs/ContextClearedEventType"
+        },
+        "payload": {
+          "$ref": "#/$defs/ContextClearedEventPayload"
+        },
+        "meta": true
+      },
+      "additionalProperties": false
+    }
+  ],
+  "$defs": {
+    "ContextClearedEventType": {
+      "title": "ContextCleared Event Message Type",
+      "const": "contextClearedEvent"
+    },
+    "ContextClearedEventPayload": {
+      "title": "contextCleared Event Payload",
+      "type": "object",
+      "properties": {
+        "channelId": {
+          "title": "Channel Id",
+          "description": "The Id of the channel that was cleared.",
+          "type": ["string", "null"]
+        },
+        "contextType": {
+          "title": "Context Type",
+          "description": "The type of context that was cleared, or null if all types were cleared.",
+          "type": ["string", "null"]
+        }
+      },
+      "required": ["channelId", "contextType"],
+      "additionalProperties": false
+    }
+}
+}

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
@@ -76,8 +77,40 @@
    */
   addContextListener(contextType: string | null, handler: ContextHandler): Promise<Listener>;
 
+  /**
+   * Clears context from the channel, and triggers the event listener on the `contextCleared` event 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.
+   *
+   * If no `contextType` is provided, all contexts will be cleared.
+   */
+  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.
  */