[WIP] FDC3 for Web specification

kriswest commented 2 months ago

resolves #896 This PR adds specifications and documentation related to enabling FDC3 for the web. This was based off of the committee's working doc and an initial PR (#1167) with the draft by @thorsent.

This assumes that "@finos/fdc3" will implement getAgent() and communication mechanisms to work with a Desktop Agent running in a different browser window.

The protocols were codified as "Web Connection Protocol (WCP)" for negotiating the handshake between the library and desktop agents, and "Browser Communication Protocol (BCP)" which encompasses the complete "wire protocol". The former is entirely specific to working in a Web Browser, however the latter might be reused in other implementations and hence may change name (e.g. 'The FDC3 Wire Protocol' or similar).

This documentation followed three streams:

Modifications for users of FDC3 - primarily related to using getAgent() for connectivity instead of relying on the global fdc object
Instructions for desktop agent implementers - provides a specification for "browser-resident desktop agents" as well as "preload desktop agents", along with typescript definitions.
A specification for getAgent() - to be used by implementers of the "@finos/fdc3" library, and for reference by desktop agent implementers.

Some changes and additions were made from the original working document:

The optional initialization fields for channel selector and intent resolver were eliminated. The DA knows whether it can provide these UI elements and so therefore it should be the DA that decides how to accomplish this. However, there are cases where a DA cannot reasonably provide these UI elements in a browser, therefore this spec mandates that "@finos/fdc3" provide built-in UI capabilities that a DA can optionally enable them.
This spec also covers window disconnects by suggesting use of a well known polling mechanism.
A new folder called "specs" was created to house many of the specifications involved. Previously, there was no true distinction between implementation specs and user specs in the FDC3 overview.

netlify[bot] commented 2 months ago

Deploy Preview for fdc3 failed. Why did it fail? →

Name	Link
Latest commit	50fe214da5da19728fa246d2efcb12230b9d1f5b
Latest deploy log	https://app.netlify.com/sites/fdc3/deploys/667d3b3306a91d00085b84cc

robmoffat commented 2 months ago

Problem with this is that there were loads of discussions happening on #1167, can we re-open that PR or something?

kriswest commented 2 months ago

Problem with this is that there were loads of discussions happening on #1167, can we re-open that PR or something?

@robmoffat even though its closed you can still comment on it - however, I'll see if I can apply a bunch of the requested changes and resolve those conversations so we can thin down the set, then I'll return to schemas and code generation. I still need to add connection flow messages and intent resolver messages, but otherwise the schemas are relatively complete (assuming they are correct, which we don't know yet).

robmoffat commented 2 weeks ago

Just had a go at Java type generation using this branch. It's definitely coming together:

There's a weird thing going on where it generates a Java class for every string constant. Might be fixable using a java port of https://github.com/glideapps/quicktype/pull/2314
Some weirdness around errors:

(base) rob@robs-mbp api % ls *Error* 
FindInstancesErrors.java    OpenErrorResponsePayload.java   ResponsePayloadError.java
FluffyError.java        PurpleError.java

There seems to be some duplication in these files and they also have weird names. Can you take a look?

finos / FDC3