Merge pull request #1858 from finos/1857-starting-an-app-on-a-channel

kriswest · web-flow · commit db2cbf269c8d · 2026-04-17T12:55:54.000+01:00
Ensure current user channel is resolved before DesktopAgentProxy is used
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -67,6 +67,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Stopped fdc3-workbench flagging FDC3 version 2.2 as unsupported. ([#1841](https://github.com/finos/FDC3/pull/1841))
 * Resolved vulnerable dependencies (esbuild, serialize-javascript, elliptic) and consolidated shared devDependencies to simplify future maintenance. ([#1841](https://github.com/finos/FDC3/pull/1841))
 * Fixed the lack of handling of WCP6Disconnect messages in MessagePort example in the FDC3 Web reference implementation. ([#1854](https://github.com/finos/FDC3/pull/1854))
+* Fixed handling of DesktopAgents that start apps joined to a user channel by the agent-proxy by retrieving the current user channel on start-up. ([#1858](https://github.com/finos/FDC3/pull/1858))
+* Fixed a race condition in `DefaultChannelSupport` initialization where the current user channel was retrieved asynchronously without being awaited, which could cause apps started on a user channel by the Desktop Agent to miss their initial channel assignment. ([#1858](https://github.com/finos/FDC3/pull/1858))
 
 ## [FDC3 Standard 2.2](https://github.com/finos/FDC3/compare/v2.1..v2.2) - 2025-03-12
 
diff --git a/packages/fdc3-agent-proxy/src/channels/ChannelSupport.ts b/packages/fdc3-agent-proxy/src/channels/ChannelSupport.ts
@@ -1,6 +1,14 @@
-import { Channel, ContextHandler, EventHandler, FDC3EventTypes, Listener, PrivateChannel } from '@finos/fdc3-standard';
+import {
+  Channel,
+  Connectable,
+  ContextHandler,
+  EventHandler,
+  FDC3EventTypes,
+  Listener,
+  PrivateChannel,
+} from '@finos/fdc3-standard';
 
-export interface ChannelSupport {
+export interface ChannelSupport extends Connectable {
   getUserChannel(): Promise<Channel | null>;
   getUserChannels(): Promise<Channel[]>;
   getOrCreate(id: string): Promise<Channel>;
diff --git a/packages/fdc3-agent-proxy/src/channels/DefaultChannelSupport.ts b/packages/fdc3-agent-proxy/src/channels/DefaultChannelSupport.ts
@@ -1,5 +1,6 @@
 import {
   Channel,
+  Connectable,
   ContextHandler,
   Listener,
   PrivateChannel,
@@ -35,7 +36,7 @@ import {
 import { throwIfUndefined } from '../util/throwIfUndefined.js';
 import { Logger } from '../util/Logger.js';
 
-export class DefaultChannelSupport implements ChannelSupport {
+export class DefaultChannelSupport implements ChannelSupport, Connectable {
   readonly messaging: Messaging;
   readonly channelSelector: ChannelSelector;
   readonly messageExchangeTimeout: number;
@@ -55,8 +56,14 @@ export class DefaultChannelSupport implements ChannelSupport {
         this.joinUserChannel(channelId);
       }
     });
+  }
+
+  async connect(): Promise<void> {
+    //retrieve the current user channel in case the Desktop Agent started us on a channel
+    this.currentChannel = await this.getUserChannel();
 
-    this.addEventListener(async (e: ApiEvent) => {
+    //register for channelChangedEvents to track any DesktopAgent managed user channel changes
+    await this.addEventListener(async (e: ApiEvent) => {
       const cce = e as FDC3ChannelChangedEvent;
       const newChannelId = cce.details.currentChannelId;
       Logger.debug('Desktop Agent reports channel changed: ', newChannelId);
@@ -65,12 +72,12 @@ export class DefaultChannelSupport implements ChannelSupport {
 
       // if theres a newChannelId, retrieve details of the channel
       if (newChannelId != null) {
-        theChannel = (await this.getUserChannelsCached()).find(uc => uc.id == newChannelId) ?? null;
+        theChannel = (await this.getUserChannels()).find(uc => uc.id == newChannelId) ?? null;
         if (!theChannel) {
           // Channel not found - query user channels in case they have changed for some reason
           Logger.debug('Unknown user channel, querying Desktop Agent for updated user channels: ', newChannelId);
           await this.getUserChannels();
-          theChannel = (await this.getUserChannelsCached()).find(uc => uc.id == newChannelId) ?? null;
+          theChannel = (await this.getUserChannels()).find(uc => uc.id == newChannelId) ?? null;
           if (!theChannel) {
             Logger.warn(
               'Received user channel update with unknown user channel (user channel listeners will not work): ',
@@ -81,83 +88,88 @@ export class DefaultChannelSupport implements ChannelSupport {
       }
 
       this.currentChannel = theChannel;
-      this.channelSelector.updateChannel(theChannel?.id ?? null, await this.getUserChannelsCached());
+      this.channelSelector.updateChannel(theChannel?.id ?? null, await this.getUserChannels());
     }, 'userChannelChanged');
   }
 
+  async disconnect(): Promise<void> {
+    // no-op
+  }
+
   async addEventListener(handler: EventHandler, type: FDC3EventTypes | null): Promise<Listener> {
     const listener = new DesktopAgentEventListener(this.messaging, this.messageExchangeTimeout, type, handler);
     await listener.register();
     return listener;
   }
 
   async getUserChannel(): Promise<Channel | null> {
-    const request: GetCurrentChannelRequest = {
-      meta: this.messaging.createMeta(),
-      type: 'getCurrentChannelRequest',
-      payload: {},
-    };
-    const response = await this.messaging.exchange<GetCurrentChannelResponse>(
-      request,
-      'getCurrentChannelResponse',
-      this.messageExchangeTimeout
-    );
-
-    throwIfUndefined(
-      response.payload.channel,
-      'Invalid response from Desktop Agent to getCurrentChannel (channel should be explicitly null if no channel is set)!',
-      response,
-      ChannelError.NoChannelFound
-    );
+    if (this.currentChannel) {
+      //if the current channel is know,, return it as this variable is maintained by a channelChangedEvent listener
+      return this.currentChannel;
+    } else {
+      const request: GetCurrentChannelRequest = {
+        meta: this.messaging.createMeta(),
+        type: 'getCurrentChannelRequest',
+        payload: {},
+      };
+      const response = await this.messaging.exchange<GetCurrentChannelResponse>(
+        request,
+        'getCurrentChannelResponse',
+        this.messageExchangeTimeout
+      );
 
-    //handle successful responses - errors will already have been thrown by exchange above
-    /* istanbul ignore else */
-    if (response.payload.channel) {
-      return new DefaultChannel(
-        this.messaging,
-        this.messageExchangeTimeout,
-        response.payload.channel.id,
-        'user',
-        response.payload.channel.displayMetadata
+      throwIfUndefined(
+        response.payload.channel,
+        'Invalid response from Desktop Agent to getCurrentChannel (channel should be explicitly null if no channel is set)!',
+        response,
+        ChannelError.NoChannelFound
       );
-    } else if (response.payload.channel === null) {
-      //this is a valid response if no channel is set
-      return null;
-    } else {
-      //Should not reach here as we will throw in exchange or throwIfNotFound
-      return null;
+
+      //handle successful responses - errors will already have been thrown by exchange above
+      /* istanbul ignore else */
+      if (response.payload.channel) {
+        return new DefaultChannel(
+          this.messaging,
+          this.messageExchangeTimeout,
+          response.payload.channel.id,
+          'user',
+          response.payload.channel.displayMetadata
+        );
+      } else if (response.payload.channel === null) {
+        //this is a valid response if no channel is set
+        return null;
+      } else {
+        //Should not reach here as we will throw in exchange or throwIfNotFound
+        return null;
+      }
     }
   }
 
-  async getUserChannelsCached(): Promise<Channel[]> {
+  async getUserChannels(): Promise<Channel[]> {
+    //If the user channels are known, return them as they are not expected to change
     if (this.userChannels) {
       return this.userChannels;
     } else {
-      this.userChannels = await this.getUserChannels();
+      const request: GetUserChannelsRequest = {
+        meta: this.messaging.createMeta(),
+        type: 'getUserChannelsRequest',
+        payload: {},
+      };
+      const response = await this.messaging.exchange<GetUserChannelsResponse>(
+        request,
+        'getUserChannelsResponse',
+        this.messageExchangeTimeout
+      );
+
+      //handle successful responses
+      const channels = response.payload.userChannels!;
+      this.userChannels = channels.map(
+        c => new DefaultChannel(this.messaging, this.messageExchangeTimeout, c.id, 'user', c.displayMetadata)
+      );
       return this.userChannels;
     }
   }
 
-  async getUserChannels(): Promise<Channel[]> {
-    const request: GetUserChannelsRequest = {
-      meta: this.messaging.createMeta(),
-      type: 'getUserChannelsRequest',
-      payload: {},
-    };
-    const response = await this.messaging.exchange<GetUserChannelsResponse>(
-      request,
-      'getUserChannelsResponse',
-      this.messageExchangeTimeout
-    );
-
-    //handle successful responses
-    const channels = response.payload.userChannels!;
-    this.userChannels = channels.map(
-      c => new DefaultChannel(this.messaging, this.messageExchangeTimeout, c.id, 'user', c.displayMetadata)
-    );
-    return this.userChannels;
-  }
-
   async getOrCreate(id: string): Promise<Channel> {
     const request: GetOrCreateChannelRequest = {
       meta: this.messaging.createMeta(),
@@ -223,7 +235,7 @@ export class DefaultChannelSupport implements ChannelSupport {
       this.messageExchangeTimeout
     );
     this.currentChannel = null;
-    this.channelSelector.updateChannel(null, await this.getUserChannelsCached());
+    this.channelSelector.updateChannel(null, await this.getUserChannels());
   }
 
   async joinUserChannel(id: string) {
@@ -240,7 +252,7 @@ export class DefaultChannelSupport implements ChannelSupport {
       this.messageExchangeTimeout
     );
 
-    const userChannels = await this.getUserChannelsCached();
+    const userChannels = await this.getUserChannels();
     this.currentChannel = userChannels.find(c => c.id == id) ?? null;
     if (this.currentChannel == null) {
       throw new Error(ChannelError.NoChannelFound);
diff --git a/packages/fdc3-agent-proxy/test/features/broadcast.feature b/packages/fdc3-agent-proxy/test/features/broadcast.feature
@@ -28,7 +28,6 @@ Feature: Broadcasting
       | payload.channelId | payload.context.type | payload.context.name | matches_type             |
       | one               | {null}               | {null}               | joinUserChannelRequest   |
       | {null}            | {null}               | {null}               | getUserChannelsRequest   |
-      | {null}            | {null}               | {null}               | getCurrentChannelRequest |
       | one               | fdc3.instrument      | Apple                | broadcastRequest         |
 
   Scenario: Context listener receives originating app metadata
diff --git a/packages/fdc3-agent-proxy/test/features/user-channel-sync.feature b/packages/fdc3-agent-proxy/test/features/user-channel-sync.feature
@@ -27,7 +27,6 @@ Feature: Updating User Channel State
       | one               | {null}              | {null}               | joinUserChannelRequest   |
       | {null}            | {null}              | {null}               | getUserChannelsRequest   |
       | one               | fdc3.instrument     | {null}               | getCurrentContextRequest |
-      | {null}            | {null}              | {null}               | getCurrentChannelRequest |
       | one               | fdc3.instrument     | {null}               | getCurrentContextRequest |
 
   Scenario: Changing User Channel Doesn't Receive Incorrect Context on Listener
diff --git a/packages/fdc3-agent-proxy/test/features/user-channels-set-by-agent.feature b/packages/fdc3-agent-proxy/test/features/user-channels-set-by-agent.feature
@@ -0,0 +1,41 @@
+Feature: User Channels Support where the Desktop Agent puts the app on a channel
+
+  Background: Desktop Agent API
+    Given User Channels one, two and three
+    Given schemas loaded
+    Given A Desktop Agent in "api" that puts apps on channel "one"
+    Given "instrumentMessageOne" is a BroadcastEvent message on channel "one" with context "fdc3.instrument"
+    
+  Scenario: Initial User Channel
+        At startup, the user channel should be set
+
+    When I call "{api}" with "getCurrentChannel"
+    Then "{result}" is an object with the following contents
+      | id  | type | displayMetadata.color |
+      | one | user | red                   |
+
+  Scenario: Adding a Typed Listener on a given User Channel
+    Given "resultHandler" pipes context to "contexts"
+    And I call "{api}" with "addContextListener" with parameters "fdc3.instrument" and "{resultHandler}"
+    And messaging receives "{instrumentMessageOne}"
+    Then "{contexts}" is an array of objects with the following contents
+      | id.ticker | type            | name  |
+      | AAPL      | fdc3.instrument | Apple |
+    And messaging will have posts
+      | payload.channelId | payload.contextType | matches_type              |
+      | {null}            | fdc3.instrument     | addContextListenerRequest |
+      | one               | fdc3.instrument     | getCurrentContextRequest  |
+
+  Scenario: I should be able to leave a user channel, and not receive messages on it
+    Given "resultHandler" pipes context to "contexts"
+    And I call "{api}" with "addContextListener" with parameters "fdc3.instrument" and "{resultHandler}"
+    And I call "{api}" with "leaveCurrentChannel"
+    Then messaging will have posts
+      | payload.channelId | payload.contextType | payload.listenerUUID | matches_type               |
+      | {null}            | fdc3.instrument     | {null}               | addContextListenerRequest  |
+      | one               | fdc3.instrument     | {null}               | getCurrentContextRequest   |
+      | {null}            | {null}              | {null}               | leaveCurrentChannelRequest |
+      | {null}            | {null}              | {null}               | getUserChannelsRequest     |
+    And messaging receives "{instrumentMessageOne}"
+    Then "{contexts}" is an array of objects with the following contents
+      | id.ticker | type | name |
diff --git a/packages/fdc3-agent-proxy/test/features/user-channels.feature b/packages/fdc3-agent-proxy/test/features/user-channels.feature
@@ -60,7 +60,6 @@ Feature: Basic User Channels Support
       | payload.channelId | matches_type             |
       | one               | joinUserChannelRequest   |
       | {null}            | getUserChannelsRequest   |
-      | {null}            | getCurrentChannelRequest |
 
   Scenario: Changing Channel via Deprecated API
         You should be able to join a channel knowing it's ID.
@@ -74,7 +73,6 @@ Feature: Basic User Channels Support
       | payload.channelId | matches_type             |
       | one               | joinUserChannelRequest   |
       | {null}            | getUserChannelsRequest   |
-      | {null}            | getCurrentChannelRequest |
 
   Scenario: Adding a Typed Listener on a given User Channel
     Given "resultHandler" pipes context to "contexts"
@@ -192,8 +190,6 @@ Feature: Basic User Channels Support
       | payload.channelId | payload.context.type | payload.context.id.ticker | matches_type             |
       | one               | {null}               | {null}                    | joinUserChannelRequest   |
       | {null}            | {null}               | {null}                    | getUserChannelsRequest   |
-      | {null}            | {null}               | {null}                    | getCurrentChannelRequest |
-      | {null}            | {null}               | {null}                    | getCurrentChannelRequest |
       | one               | fdc3.instrument      | AAPL                      | broadcastRequest         |
       | one               | {null}               | {null}                    | getCurrentContextRequest |
 
@@ -279,9 +275,6 @@ Feature: Basic User Channels Support
       | one   | user | red                   | triangle              | The one channel      |
       | two   | user | red                   | triangle              | The two channel      |
       | three | user | red                   | triangle              | The three channel    |
-    And messaging will have posts
-      | meta.source.appId | meta.source.instanceId | matches_type           |
-      | cucumber-app      | cucumber-instance      | getUserChannelsRequest |
 
   Scenario: Destructured joinUserChannel and getCurrentChannel work correctly
     When I destructure method "joinUserChannel" from "{api}"
@@ -295,7 +288,6 @@ Feature: Basic User Channels Support
       | payload.channelId | matches_type             |
       | one               | joinUserChannelRequest   |
       | {null}            | getUserChannelsRequest   |
-      | {null}            | getCurrentChannelRequest |
 
   Scenario: Destructured channel getCurrentContext after broadcast
     Given "resultHandler" pipes context to "contexts"
diff --git a/packages/fdc3-agent-proxy/test/step-definitions/generic.steps.ts b/packages/fdc3-agent-proxy/test/step-definitions/generic.steps.ts
@@ -20,9 +20,9 @@ const logLevel = LogLevel.WARN;
 const schemaBasePath = path.join(import.meta.dirname, '../../../');
 setupGenericSteps(schemaBasePath);
 
-Given('A Desktop Agent in {string}', async (world: CustomWorld, field: string) => {
+function createDesktopAgent(world: CustomWorld, field: string, initialChannelId?: string) {
   if (!world.messaging) {
-    world.messaging = new TestMessaging(world.props[CHANNEL_STATE]);
+    world.messaging = new TestMessaging(world.props[CHANNEL_STATE], initialChannelId);
   }
 
   // n.b. using short timeouts to avoid extending tests unnecessarily
@@ -31,13 +31,29 @@ Given('A Desktop Agent in {string}', async (world: CustomWorld, field: string) =
   const is = new DefaultIntentSupport(world.messaging, new SimpleIntentResolver(world), 1500, 3000);
   const as = new DefaultAppSupport(world.messaging, 1500, 3000);
 
-  const da = new DesktopAgentProxy(hs, cs, is, as, [hs], logLevel);
+  const da = new DesktopAgentProxy(hs, cs, is, as, [hs, cs], logLevel);
+  return da;
+}
+
+Given('A Desktop Agent in {string}', async (world: CustomWorld, field: string) => {
+  const da = createDesktopAgent(world, field);
   await da.connect();
 
   world.props[field] = da;
   world.props['result'] = null;
 });
 
+Given(
+  'A Desktop Agent in {string} that puts apps on channel {string}',
+  async (world: CustomWorld, field: string, channelId: string) => {
+    const da = createDesktopAgent(world, field, channelId);
+    await da.connect();
+
+    world.props[field] = da;
+    world.props['result'] = null;
+  }
+);
+
 When('messaging receives a heartbeat event', (world: CustomWorld) => {
   world.messaging?.receive({
     type: 'heartbeatEvent',
diff --git a/packages/fdc3-agent-proxy/test/support/TestMessaging.ts b/packages/fdc3-agent-proxy/test/support/TestMessaging.ts
@@ -111,7 +111,7 @@ export class TestMessaging extends AbstractMessaging {
 
   readonly automaticResponses: AutomaticResponse[];
 
-  constructor(channelState: { [key: string]: Context[] }) {
+  constructor(channelState: { [key: string]: Context[] }, initialChannelId?: string) {
     super({ appId: 'cucumber-app', instanceId: 'cucumber-instance' });
 
     this.channelState = channelState;
@@ -126,7 +126,7 @@ export class TestMessaging extends AbstractMessaging {
       new FindInstances(),
       new Open(),
       new GetOrCreateChannel(),
-      new ChannelState(this.channelState),
+      new ChannelState(this.channelState, initialChannelId),
       new GetUserChannels(),
       new RegisterListeners(),
       new UnsubscribeListeners(),
diff --git a/packages/fdc3-agent-proxy/test/support/responses/ChannelState.ts b/packages/fdc3-agent-proxy/test/support/responses/ChannelState.ts
diff --git a/packages/fdc3-get-agent/src/messaging/message-port.ts b/packages/fdc3-get-agent/src/messaging/message-port.ts
diff --git a/packages/fdc3-standard/src/ui/ChannelSelector.ts b/packages/fdc3-standard/src/ui/ChannelSelector.ts
