Context Clearing

[hellosmithy]

Enhancement Request

NOTE: Edited to reflect discussion from Standard WG Meeting - May 23rd, 2024 #1215

Use Case:

Enable explicit clearing of individual contexts including within multi-context channels. For instance, removing a filter from a data grid (e.g., by instrument, trade, or time range) while keeping other context filters intact.

Current Limitations:

• fdc3.nothing: Limited to clearing all contexts on a channel, lacks the ability to target specific contexts.
• broadcast context with null id field: Requires creating empty versions of each context type, which is cumbersome and inconsistent due to some fields being non-nullable.

Additional Information

The issue of context clearing was most recently discussed at the #1215 Standard WG Meeting and several possible solutions were floated.

• Extend fdc3.nothing to include an optional subType field to indicate a specific context
• Addition of a clearContext channel method
• Addition of a string constant to id fields to indicate a cleared context
  • Not pursued further in this proposal due to not having clear semantics, and also not resolving the issue of contexts having different required fields, and therefore not having a canonical empty context type.
• Redesign of the broadcast API to support null contexts, e.g. by adding an additional type param or by adding the type to the existing metadata param
  • Whilst this might be the cleanest solution, not pursued further in this proposal due to being the least backwards compatible option. But if there is appetite for broader changes it may be worth considering.

No decision was made, but there was general consensus that any solution would need to address both requirements of:

• Updating any internal currentContext state in the desktop agent
• Broadcasting the cleared context to any listeners
  • Accounting for both * and individual context listeners

Proposed Solution

A combination of the first two options would address both the above requirements.

Extend fdc3.nothing context

interface Nothing {
  type: 'fdc3.nothing';
  subType?: string;
}

• If a subType is not provided it represents a lack of context as per the existing behaviour.
• If a subType is provided it indicates the lack of the specified context.

E.g.

{
  type: 'fdc3.nothing',
  subType: 'fdc3.timeRange'
}

The above indicates the lack of a time range context

Addition of a Channel.clearContext method

interface Channel {
  ...
  broadcast(context: Context): Promise<void>;  
  getCurrentContext(contextType?: string): Promise<Context|null>;
  clearContext(contextType?: string): Promise<void>;
  addContextListener(contextType: string | null, handler: ContextHandler): Promise<Listener>;
}

Functionality:

• Clear the specified context type if provided, or all contexts if no type is specified
  • Internal context is updated by the desktop agent
  • Any subsequent joiners to the channel or calls to getCurrentContext will receive a null value for the cleared context type
• Update all channel listeners that are subscribed to the fdc3.nothing context type
  • If a single context is being cleared then a subType is provided
  • If all contexts are being cleared then subType is omitted

NOTE: Any direct listeners to the cleared subType would not receive any updates as the existing type contract expects that they would only get updates of the context being cleared. As such any consuming application would need to explicitly opt-in to context clearing updates with a separate listener of fdc3.nothing contexts.

E.g.

channel.addContextListener('fdc3.timeRange', (context: Fdc3TimeRange) => {
  // ... update app state
})

channel.addContextListener('fdc3.nothing', (context: Fdc3Nothing) => {
  switch (context.subType) {
    case 'fdc3.timeRange':
      // ... update app state
    default:
      // ... clear all contexts
  }
}

Rationale for Hybrid Approach

• Internal State Management: The clearContext method directly updates the FDC3 internal context state in a declarative way that matches existing methods.
• Backward Compatibility: Broadcasting fdc3.nothing with a subType allows context listeners to opt-in to receive specific contexts that have been cleared, without requiring major breaking changes to existing context listeners

Some trade-offs:

• Ergonomics and Clarity: This solution is not as a discoverable or intuitive as an API redesign might be, but errs on the side of backwards compatibility.
• API Changes for Desktop Agent Providers whilst backwards compatibility is maintained for consumers, providers would need to make implementation changes to implement the internal context state clearing and broadcasting behaviour

Some edge cases:

• What happens if an fdc3.nothing with subType is broadcast directly rather than triggered by a call to clearContext? Would the internal context still be cleared?

[kriswest]

@hellosmithy Many thanks for the detailed write up. This was previously considered under issue #301, and has subsequently been raised as a question in a meeting at least once. Hence, I believe this is worth revisiting and I propose to do so at the May SWG meeting.

[hellosmithy]

I've updated the above proposal to reflect the discussion from the last WG

[kriswest]

Many thanks @hellosmithy!