Erroneous Property / Structure for Channel Events

[robmoffat]

Minor Issue

Please use minor issues for discrepancies or errors found in the spec or supporting documentation, examples, and other materials. If you wish to propose a new feature or a revision to an existing feature, please use the Enhancement Request template.

Area of Issue

• App Directory
• API
• Context Data
• Intents
• Desktop Agent Bridging
• Use Cases
• Other

This is a bit confusing:

// Events.ts

/**
 * Type defining the format of event `userChannelChanged` objects
 */
export interface FDC3ChannelChangedEvent extends FDC3Event {
  readonly type: 'userChannelChanged';
  readonly details: {
    currentChannelId: string | null;
  };
}

// BrowserTypes.ts

export interface ChannelChangedEvent {
  /**
   * Metadata for messages sent by a Desktop Agent to an app notifying it of an event.
   */
  meta: BroadcastEventMeta;
  /**
   * The message payload contains details of the event that the app is being notified about.
   */
  payload: ChannelChangedEventPayload;
  /**
   * 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.
   */
  type: 'channelChangedEvent';
}

/**
 * The message payload contains details of the event that the app is being notified about.
 */
export interface ChannelChangedEventPayload {
  /**
   * The Id of the channel that the app was added to or `null` if it was removed from a
   * channel.
   */
  newChannelId: null | string;
}

the problem is that one is taking a newChannelId and the other is currentChannelId.
... and the event type changes too

ok, this is a weird issue, definitely an error:

/**
 * Type defining the format of event objects that may be received
 * via the FDC3 API's `addEventListener` function.
 */
export interface FDC3Event extends ApiEvent {
  readonly string: FDC3EventTypes;
  readonly details: any;
}

/**
 * Type defining the format of event `userChannelChanged` objects
 */
export interface FDC3ChannelChangedEvent extends FDC3Event {
  readonly type: 'userChannelChanged';
  readonly details: {
    currentChannelId: string | null;
  };
}

There's a property called "string" on the FDC3Event!

3:01
I'll raise an issue

Message Kris West

[kriswest]

The FDC3Event schema looks correct to me:

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

Lines 522 to 539 in 7abbe23

	"FDC3Event": {
	"title": "FDC3 Event",
	"description": "An event object received via the FDC3 API's addEventListener function. Will always include both type and details, which describe type of the event and any additional details respectively.",
	"type": "object",
	"properties": {
	"type": {
	"$ref": "#/definitions/FDC3EventType"
	},
	"details": {
	"title": "Event details",
	"description": "Additional details of the event, such as the `currentChannelId` for a CHANNEL_CHANGED event.",
	"type": "object",
	"additionalProperties": true
	}
	},
	"required":["type","details"],
	"additionalProperties": false
	},

The error is only in the typescript for FDC3Event:

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

Lines 34 to 37 in 7abbe23

	export interface FDC3Event extends ApiEvent {
	readonly string: FDC3EventTypes;
	readonly details: any;
	}

and is probably not affecting anyone much as its not replicated on the subtypes:

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

Lines 42 to 47 in 7abbe23

	export interface FDC3ChannelChangedEvent extends FDC3Event {
	readonly type: 'userChannelChanged';
	readonly details: {
	currentChannelId: string | null;
	};
	}

Nevertheless its unintended and should be fixed. It is probably not affecting conformance...

As for the different field names, it looks like @kemerava and I were working on these in parallel. I think the message used in FDC3 for Web might predate us adding event listeners to the API (as the proxy and channel selectors needed to know about the channel change before apps could listen for it). Its implementable as is (but you have to translate the field name when you fire the event which is inelegant - just has to happen in proxy code which does the event firing on receipt of message so its handled for all implementations that use the FDC3 lib for getAgent - @Roaders take note as you don't use said lib).

To improve on it I suggest we add both fields to the message, deprecate newChannelId (preferring currentChannelId from the FDC3 API) and have the proxy code check for checkCurrentId then fallback to newChannelId if not present. The schema will need a little finesse with an anyOf so it can take either parameter but require one to be present (won't replicate in the typescript where both props will be optional but thats the best we can do).

Does that sound agreeable @robmoffat?

[robmoffat]

Yes, this sounds like a good approach.

[kriswest]

resolved in #1742