Add getAgent opt-in flags for own broadcasts and self intent resolution

Implements #1751 and #1860 by adding two optional booleans to GetAgentParams:

- receiveOwnBroadcasts: when set, the Desktop Agent delivers an app's own
  broadcasts back to it. Defaults to false (current behaviour).
- resolveOwnIntents: when set, the raising app's own instance is considered
  when resolving an intent it raised. Defaults to false (current behaviour);
  other instances of the same app remain eligible either way.

The flags travel on the WCP4ValidateAppIdentity handshake message and are
stored per-instance by the reference Desktop Agent (each instance of an app
may connect with different getAgent options). BroadcastHandler makes its
self-delivery filter conditional on receiveOwnBroadcasts; IntentHandler
excludes the raising instance (by instanceId) unless resolveOwnIntents is set,
dropping any AppIntent left with no resolvers so a self-only intent yields
NoAppsFound.

Updates the API spec, getAgent, broadcast, Channel and raiseIntent/
raiseIntentForContext documentation (including net-new intent self-resolution
wording), regenerates schema types, and adds conformance/BDD tests.

Author: Roaders

CHANGELOG.md

@@ -12,6 +12,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Added conformance coverage for `ChannelError.NoChannelFound`, `ChannelError.MalformedContext`, and `ChannelError.InvalidArguments`. ([#1779](https://github.com/finos/FDC3/issues/1779))
 * Added conformance coverage verifying that Desktop Agent methods continue to work when destructured from the `fdc3` object. ([#1778](https://github.com/finos/FDC3/issues/1778))
 * Added standalone Workbench examples for the FDC3 2.2 `fdc3.action`, `fdc3.fileAttachment`, `fdc3.message`, `fdc3.orderList`, `fdc3.tradeList`, and `fdc3.timeRange` context types. ([#1949](https://github.com/finos/FDC3/pull/1949))
+* Added `receiveOwnBroadcasts` and `resolveOwnIntents` options to `getAgent`, allowing an application to opt in to receiving its own broadcasts and/or having its own instance considered when resolving intents it raises. Both default to the existing behaviour (an app does not receive its own broadcasts and an intent is not resolved to the raising instance; other instances of the same app remain eligible). The options are carried on the `WCP4ValidateAppIdentity` handshake message and stored per-instance by the Desktop Agent. Updated the API spec, `getAgent`, `broadcast`, `Channel` and `raiseIntent`/`raiseIntentForContext` documentation, and added conformance tests. ([#1751](https://github.com/finos/FDC3/issues/1751), [#1860](https://github.com/finos/FDC3/issues/1860))
 * Added advanced conformance tests (`fdc3.intentListenerConflict`) covering intent listener conflicts, verifying that `addIntentListener`/`addIntentListenerWithContext` reject with `ResolveError.IntentListenerConflict` for conflicting listeners (unfiltered, or overlapping context types) and allow non-overlapping filtered listeners, listeners for different intents, and re-adding after `unsubscribe()`. Added the corresponding test definitions to the "Avoiding Adding Multiple Intent Listeners" section of the Intents conformance docs.
 * Added a classification field to Instrument context type ([#1665](https://github.com/finos/FDC3/pull/1665))
 * Added Go language binding. ([#1483](https://github.com/finos/FDC3/pull/1483))

packages/fdc3-get-agent/src/strategies/IdentityValidationHandler.ts

@@ -56,6 +56,12 @@ export class IdentityValidationHandler {
       payload: {
         identityUrl,
         actualUrl,
+        ...(this.options.receiveOwnBroadcasts !== undefined && {
+          receiveOwnBroadcasts: this.options.receiveOwnBroadcasts,
+        }),
+        ...(this.options.resolveOwnIntents !== undefined && {
+          resolveOwnIntents: this.options.resolveOwnIntents,
+        }),
       },
     };
 

packages/fdc3-get-agent/src/strategies/getAgent.ts

@@ -211,6 +211,8 @@ export const getAgent: GetAgentType = (params?: GetAgentParams) => {
     channelSelector: true,
     intentResolver: true,
     timeoutMs: DEFAULT_GETAGENT_TIMEOUT_MS,
+    receiveOwnBroadcasts: false,
+    resolveOwnIntents: false,
     //default log levels are set in the relevant logging utils
   };
 

packages/fdc3-schema/generated/api/BrowserTypes.ts

@@ -299,6 +299,20 @@ export interface WebConnectionProtocol4ValidateAppIdentityPayload {
    * Instance UUID associated with the requested instanceId.
    */
   instanceUuid?: string;
+  /**
+   * Flag indicating that the application wishes to receive its own broadcasts, i.e. context
+   * messages it broadcasts to a channel it is joined to (or listening on) should be delivered
+   * back to it. Defaults to false when omitted, in which case the Desktop Agent SHOULD NOT
+   * deliver the application's own broadcasts back to it.
+   */
+  receiveOwnBroadcasts?: boolean;
+  /**
+   * Flag indicating that the application is willing for its own instance to be considered
+   * when resolving intents that it raises. Defaults to false when omitted, in which case the
+   * Desktop Agent SHOULD NOT resolve an intent raised by the application instance to that
+   * same instance (other instances of the same app remain eligible).
+   */
+  resolveOwnIntents?: boolean;
 }
 
 /**
@@ -5213,6 +5227,8 @@ const typeMap: any = {
       { json: 'identityUrl', js: 'identityUrl', typ: '' },
       { json: 'instanceId', js: 'instanceId', typ: u(undefined, '') },
       { json: 'instanceUuid', js: 'instanceUuid', typ: u(undefined, '') },
+      { json: 'receiveOwnBroadcasts', js: 'receiveOwnBroadcasts', typ: u(undefined, true) },
+      { json: 'resolveOwnIntents', js: 'resolveOwnIntents', typ: u(undefined, true) },
     ],
     false
   ),

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

@@ -45,6 +45,16 @@
               "title": "instanceUuid",
               "description": "Instance UUID associated with the requested instanceId.",
               "type": "string"
+            },
+            "receiveOwnBroadcasts": {
+              "title": "receiveOwnBroadcasts",
+              "description": "Flag indicating that the application wishes to receive its own broadcasts, i.e. context messages it broadcasts to a channel it is joined to (or listening on) should be delivered back to it. Defaults to false when omitted, in which case the Desktop Agent SHOULD NOT deliver the application's own broadcasts back to it.",
+              "type": "boolean"
+            },
+            "resolveOwnIntents": {
+              "title": "resolveOwnIntents",
+              "description": "Flag indicating that the application is willing for its own instance to be considered when resolving intents that it raises. Defaults to false when omitted, in which case the Desktop Agent SHOULD NOT resolve an intent raised by the application instance to that same instance (other instances of the same app remain eligible).",
+              "type": "boolean"
             }
           },
           "additionalProperties": false,

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

@@ -85,6 +85,25 @@ export type GetAgentType = (params?: GetAgentParams) => Promise<DesktopAgent>;
  * @property {GetAgentLogLevels} logLevels Settings that determine what should
  * will logged by the getAgent() implementation and DesktopAgentProxy to the
  * JavaScript console.
+ *
+ * @property {boolean} receiveOwnBroadcasts Flag indicating that the application
+ * wishes to receive its own broadcasts, i.e. context messages that it broadcasts
+ * to a channel it is joined to (or listening on) should be delivered back to it.
+ * Defaults to `false`, in which case a Desktop Agent SHOULD NOT deliver an
+ * application's own broadcasts back to it. Applications can distinguish their own
+ * broadcasts from those of other instances of the same app via the `source`
+ * (`instanceId`) in the [`ContextMetadata`](ref/Metadata#contextmetadata) provided
+ * to their context handlers. MAY be ignored by Desktop Agent Preload (container)
+ * implementations.
+ *
+ * @property {boolean} resolveOwnIntents Flag indicating that the application is
+ * willing for its own instance to be considered when resolving intents that it
+ * raises (i.e. an intent it raises may be delivered back to the same instance).
+ * Defaults to `false`, in which case a Desktop Agent SHOULD NOT resolve an intent
+ * raised by an application instance to that same instance (other instances of the
+ * same app remain eligible). If enabling this leaves no eligible targets, the
+ * raising app receives a `NoAppsFound` error. MAY be ignored by Desktop Agent
+ * Preload (container) implementations.
  */
 export type GetAgentParams = {
   timeoutMs?: number;
@@ -94,6 +113,8 @@ export type GetAgentParams = {
   dontSetWindowFdc3?: boolean;
   failover?: (args: GetAgentParams) => Promise<WindowProxy | DesktopAgent>;
   logLevels?: GetAgentLogLevels;
+  receiveOwnBroadcasts?: boolean;
+  resolveOwnIntents?: boolean;
 };
 
 /**

toolbox/fdc3-for-web/fdc3-web-impl/src/ServerContext.ts

@@ -13,6 +13,17 @@ export type AppRegistration = {
   state: State;
   appId: string;
   instanceId: InstanceID;
+
+  /** Whether this instance opted in (via getAgent) to receiving its own
+   *  broadcasts. When falsy, the Desktop Agent does not deliver context
+   *  messages broadcast by this instance back to it. */
+  receiveOwnBroadcasts?: boolean;
+
+  /** Whether this instance opted in (via getAgent) to having its own instance
+   *  considered when resolving intents that it raises. When falsy, the Desktop
+   *  Agent excludes this instance from resolution of intents it raises (other
+   *  instances of the same app remain eligible). */
+  resolveOwnIntents?: boolean;
 };
 
 /**

toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/BroadcastHandler.ts

@@ -445,13 +445,17 @@ export class BroadcastHandler implements MessageHandler {
       return r.channelId == null && ucId == arg0.payload.channelId;
     };
 
+    // Unless the broadcasting app opted in (via getAgent's receiveOwnBroadcasts),
+    // its own broadcasts are not delivered back to it.
+    const receiveOwnBroadcasts = sc.getInstanceDetails(from.instanceId)?.receiveOwnBroadcasts ?? false;
+
     const matchingListeners = this.contextListeners
       // Deliver the message to apps listening to the right channel
       .filter(r => matchesExactChannel(r) || matchesUserChannel(r))
       // Deliver the message to apps with matching context type listeners
       .filter(r => r.contextType == null || r.contextType == arg0.payload.context.type)
-      // Don't deliver messages back to the broadcasting app
-      .filter(r => r.instanceId !== from.instanceId);
+      // Don't deliver messages back to the broadcasting app (unless it opted in)
+      .filter(r => receiveOwnBroadcasts || r.instanceId !== from.instanceId);
 
     const matchingApps: FullAppIdentifier[] = matchingListeners
       .map(r => {

toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/IntentHandler.ts

@@ -426,6 +426,13 @@ export class IntentHandler implements MessageHandler {
 
   async raiseIntentToAnyApp(arg0: IntentRequest[], sc: ServerContext<AppRegistration>): Promise<void> {
     const connectedApps = await sc.getConnectedApps();
+    // Unless the raising app opted in (via getAgent's resolveOwnIntents), its own
+    // instance is not considered when resolving an intent that it raised. Other
+    // instances of the same app remain eligible.
+    const raiser = arg0[0].from;
+    const raiserResolvesOwnIntents = raiser.instanceId
+      ? (sc.getInstanceDetails(raiser.instanceId)?.resolveOwnIntents ?? false)
+      : false;
     const matchingIntents = arg0.flatMap(i => this.directory.retrieveIntents(i.context.type, i.intent, undefined));
     const matchingRegistrations = arg0.flatMap(i =>
       this.registrations.filter(
@@ -439,29 +446,36 @@ export class IntentHandler implements MessageHandler {
 
     const allIntents = this.directory.retrieveAllIntents();
 
-    const appIntents: AppIntent[] = uniqueIntentNames.map(i => {
-      const directoryAppsWithIntent = matchingIntents.filter(mi => mi.intentName == i).map(mi => mi.appId);
-      const runningDirectoryApps = connectedApps.filter(ca => directoryAppsWithIntent.includes(ca.appId));
-      const appRegistrations = matchingRegistrations
-        .filter(registration => registration.intentName === i) // filter registrations for the current intent
-        .map(listener => ({ appId: listener.appId, instanceId: listener.instanceId, state: State.Connected }))
-        .filter(appRegistration => allIntents.every(intent => intent.appId !== appRegistration.appId)); // filter out apps that have intents registered in the directory
-
-      const runningApps: AppRegistration[] = [...runningDirectoryApps, ...appRegistrations];
+    const appIntents: AppIntent[] = uniqueIntentNames
+      .map(i => {
+        const directoryAppsWithIntent = matchingIntents.filter(mi => mi.intentName == i).map(mi => mi.appId);
+        const runningDirectoryApps = connectedApps.filter(ca => directoryAppsWithIntent.includes(ca.appId));
+        const appRegistrations = matchingRegistrations
+          .filter(registration => registration.intentName === i) // filter registrations for the current intent
+          .map(listener => ({ appId: listener.appId, instanceId: listener.instanceId, state: State.Connected }))
+          .filter(appRegistration => allIntents.every(intent => intent.appId !== appRegistration.appId)); // filter out apps that have intents registered in the directory
+
+        const runningApps: AppRegistration[] = [...runningDirectoryApps, ...appRegistrations].filter(
+          app => raiserResolvesOwnIntents || app.instanceId !== raiser.instanceId
+        );
 
-      return {
-        intent: {
-          name: i,
-          displayName: i,
-        },
-        apps: [
-          ...runningApps,
-          ...directoryAppsWithIntent.map(d => {
-            return { appId: d };
-          }),
-        ],
-      };
-    });
+        return {
+          intent: {
+            name: i,
+            displayName: i,
+          },
+          apps: [
+            ...runningApps,
+            ...directoryAppsWithIntent.map(d => {
+              return { appId: d };
+            }),
+          ],
+        };
+        // Drop any intent left with no resolvers (e.g. because the only handler was
+        // the raising instance, which was excluded above), so the caller receives a
+        // NoAppsFound error rather than an empty resolution.
+      })
+      .filter(appIntent => appIntent.apps.length > 0);
 
     const narrowedAppIntents = await this.narrowIntents(arg0[0].from, appIntents, arg0[0].context, sc);
 

toolbox/fdc3-for-web/fdc3-web-impl/src/handlers/OpenHandler.ts

@@ -365,6 +365,13 @@ export class OpenHandler implements MessageHandler {
       sc.post(msg, instanceId);
     };
 
+    // Self-interaction preferences supplied by the app via getAgent, captured
+    // per-instance (each instance of an app may connect with different options).
+    const applySelfInteractionOptions = (registration: AppRegistration) => {
+      registration.receiveOwnBroadcasts = arg0.payload.receiveOwnBroadcasts ?? false;
+      registration.resolveOwnIntents = arg0.payload.resolveOwnIntents ?? false;
+    };
+
     if (arg0.payload.instanceUuid) {
       // existing app reconnecting
       console.debug('App attempting to reconnect:', arg0.payload.instanceUuid);
@@ -378,6 +385,7 @@ export class OpenHandler implements MessageHandler {
           ', instanceId',
           arg0.payload.instanceUuid
         );
+        applySelfInteractionOptions(appIdentity);
         sc.setInstanceDetails(from, appIdentity);
         sc.setAppState(from, State.Connected);
         return returnSuccess(appIdentity.appId, appIdentity.instanceId);
@@ -390,6 +398,8 @@ export class OpenHandler implements MessageHandler {
     // we need to assign an identity to this app - this should have been generated when it was launched
     const appIdentity = sc.getInstanceDetails(from);
     if (appIdentity) {
+      applySelfInteractionOptions(appIdentity);
+      sc.setInstanceDetails(from, appIdentity);
       sc.setAppState(appIdentity.instanceId, State.Connected);
       returnSuccess(appIdentity.appId, appIdentity.instanceId);