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!

[kriswest]

@hellosmithy one thing I would update in the write up:

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

They wouldn't receive a null context - rather they would:

• if working through the desktop agent API (fdc3.joinChannel, fdc3.addContextListener): NOT receive the specified contexts on joining or adding a context listener - these are sent automatically if present and would no longer be present
• if working through the Channel interface: NOT receive the specified contexts when calling theChannel.getCurrentContext - you don't receive context automatically on adding a listener via the channel interface - confusing I know!

From there this needs a PR to implement it that will touch:

• https://github.com/finos/FDC3/blob/main/src/api/Channel.ts
• https://github.com/finos/FDC3/blob/main/docs/api/ref/Channel.md
• https://github.com/finos/FDC3/blob/main/docs/api/spec.md (compliance and Context channels sections - explaining if its required for compliance and providing an overview of the capability).
• https://github.com/finos/FDC3/blob/main/schemas/context/nothing.schema.json (both docs for fdc3.nothing and Typescript type are generated from this file now so the new property needs adding here and usage explained in the description)

I'd be most happy for you to take that on ;-) although we'll need your CLA in place to merge it. Ideally, it gets done before next months SWG meeting so we can get it adopted into the 2.2 scope. If the CLa is likeloy to get in the way of that timeline, let me know and I'll see if I can help get the PR done!

[robmoffat]

I really like the idea of the clearContext method. I'm less sure about the fdc3.nothing approach, it seems like it is a bit confusing, but I get how this could work right now rather than waiting for a new version of FDC3 to come out.

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

So one thing that isn't really clear then is:

• is broadcasting fdc3.nothing with no subtype clearing all context?
• would it mean something to raise an intent with fdc3.nothing with a subtype?

Perhaps this would be better in a specific, new context type, say fdc3.clear?

[kriswest]

@robmoffat by 'the fdc3.nothing approach' do you mean manual broadcast of that triggering a clear? If so I think that very much optional and not something we need to do.

However, if you mean the DA broadcasting fdc3.nothing to indicate that a clear has happened, then I do think we need a form of notification and fdc3.nothing works pretty well for it. Its got few other uses (raising intents without a context) that seem semantically compatible as its just supposed to represent a lack of context.