FDC3 for Web specification

[kriswest]

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.

Deep links to docs for review:

• API overview now links out to Support Platforms for details of API access: https://deploy-preview-1191--fdc3.netlify.app/docs/next/api/spec#implementation-language
• Supported platforms now recommends the use of getAgent() for gaining access to an API implementation for web apps: https://deploy-preview-1191--fdc3.netlify.app/docs/next/api/supported-platforms
• getAgent() reference docs for app implementors: https://deploy-preview-1191--fdc3.netlify.app/docs/next/api/ref/GetAgent
• AgentError enumeration added for connection issues: https://deploy-preview-1191--fdc3.netlify.app/docs/next/api/ref/Errors#agenterror
• New Desktop Agent specifications section:
  • Preload Desktop Agents (existing implementations using window.fdc3): https://deploy-preview-1191--fdc3.netlify.app/docs/next/api/specs/preloadDesktopAgents
  • Browser-Resident Desktop Agents: https://deploy-preview-1191--fdc3.netlify.app/docs/next/api/specs/browserDesktopAgents
  • Web Connection Protocol (WCP): https://deploy-preview-1191--fdc3.netlify.app/docs/next/api/specs/webConnectionProtocol
  • DesktopAgent Communication Protocol (DACP): https://deploy-preview-1191--fdc3.netlify.app/docs/next/api/specs/desktopAgentCommunicationProtocol

[netlify[bot]]

✅ Deploy Preview for fdc3 ready!

Name	Link
🔨 Latest commit	976af80d5ba8d831e202aabcd37d1a7886e4c930
🔍 Latest deploy log	https://app.netlify.com/sites/fdc3/deploys/66f3fabcbedbca00083c8d27
😎 Deploy Preview	https://deploy-preview-1191--fdc3.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[robmoffat]

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

[kriswest]

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]

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?

[kriswest]

COnverting to ready to review to generate preview -its not really ready other than the Supported Platforms, GetAgent pages and the GetAgent.ts source file. Much more work is needed to on the WCP and DACP specs, some of the API overview etc..

[robmoffat]

/netlify

[kriswest]

netlify is rudely ignoring us @robmoffat ;-)

[robmoffat]

Getting this in the netlify logs:

4:46:09 PM: [INFO] Docs markdown link couldn't be resolved: (../api/ref/PrivateChannel.md) in "/opt/build/repo/docs/api/specs/browserCommunicationProtocol.md" for version current
[INFO] Docs markdown link couldn't be resolved: (../api/ref/PrivateChannel.md) in "/opt/build/repo/docs/api/specs/browserCommunicationProtocol.md" for version current
[success] [webpackbar] Client: Compiled with some errors in 1.48m
4:46:09 PM: SyntaxError: /opt/build/repo/docs/api/ref/Errors.md: Expected corresponding JSX closing tag for <MDXLayout>. (400:0)
4:46:09 PM:   398 | </TabItem>
4:46:09 PM:   399 | </Tabs>
4:46:10 PM: > 400 | </TabItem>
4:46:10 PM:       | ^
4:46:10 PM:   401 | </Tabs>
4:46:10 PM:   402 | <h2 {...{"id":"bridgingerror"}}><inlineCode parentName="h2">{`BridgingError`}</inlineCode></h2>
4:46:10 PM:   403 | <p><inlineCode parentName="p">{`@experimental`}</inlineCode></p>
4:46:10 PM: [ERROR] Client bundle compiled with errors therefore further build is impossible.
4:46:10 PM: Failed during stage 'building site': Build script returned non-zero exit code: 2 (https://ntl.fyi/exit-code-2)
4:46:10 PM: error Command failed with exit code 1. (https://ntl.fyi/exit-code-1)
4:46:10 PM: info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
4:46:10 PM: ​
4:46:10 PM: "build.command" failed                                        
4:46:10 PM: ────────────────────────────────────────────────────────────────

[kriswest]

@robmoffat what date was it complaining about that link? Its been fixed for 3 weeks and the last netlify comment was on July 1st apparently...

[kriswest]

/netlify

[robmoffat]

/netlify

[kriswest]

/netlify

[robmoffat]

/netlify

[robmoffat]

Preview here: https://deploy-preview-1191--fdc3.netlify.app

[kriswest]

Yes and can discuss there. This has been sat in the proposal for >6 months but we haven't talked about it recently.

[kriswest]

@novavi @Lecss @robmoffat @Davidhanson90 @Roaders @flashd2n @ksgeorgieva @openfin-johans @hughtroeger @bingenito @thorsent I believe this PR now represents a complete first draft of the spec addition and is ready for review. We'll be hosting a review meeting on Thursday 19th September at the FDC3 for Web working group, which I'll announce to the FDC3 mailing list soon, with a goal of accepting this into the FDC3 2.2 scope at the SWG meeting on 26th Sept.

In the meantime, could any of you with a spare minute to a look and let me know if you spot any errors, rendering issues or content that is not clear? Please feel free to notify colleagues etc..

Deep links to docs for review:

• API overview now links out to Support Platforms for details of API access: https://deploy-preview-1191--fdc3.netlify.app/docs/next/api/spec#implementation-language
• Supported platforms now recommends the use of getAgent() for gaining access to an API implementation for web apps: https://deploy-preview-1191--fdc3.netlify.app/docs/next/api/supported-platforms
• getAgent() reference docs for app implementors: https://deploy-preview-1191--fdc3.netlify.app/docs/next/api/ref/GetAgent
• AgentError enumeration added for connection issues: https://deploy-preview-1191--fdc3.netlify.app/docs/next/api/ref/Errors#agenterror
• New Desktop Agent specifications section:
  • Preload Desktop Agents (existing implementations using window.fdc3): https://deploy-preview-1191--fdc3.netlify.app/docs/next/api/specs/preloadDesktopAgents
  • Browser-Resident Desktop Agents: https://deploy-preview-1191--fdc3.netlify.app/docs/next/api/specs/browserDesktopAgents
  • Web Connection Protocol (WCP): https://deploy-preview-1191--fdc3.netlify.app/docs/next/api/specs/webConnectionProtocol
  • DesktopAgent Communication Protocol (DACP): https://deploy-preview-1191--fdc3.netlify.app/docs/next/api/specs/desktopAgentCommunicationProtocol

Finally, many thanks to all involved in the meetings and for @thorsent for kicking off the mammoth task of documenting the new protocols and procedures. Separate thanks will go to @robmoffat when we get the software in - thats a mammoth task too!

[Roaders]

Very very minor issue (but I'm nerdy enough that it's bothering me! 🤓) ...

The spacing in the example code is not consistent!

We have

import { DesktopAgent, getAgent } from "@finos/fdc3";

(https://deploy-preview-1191--fdc3.netlify.app/docs/next/api/supported-platforms#web)

and

import {raiseIntent} from '@finos/fdc3';

(https://deploy-preview-1191--fdc3.netlify.app/docs/next/api/supported-platforms#2-es6-style-function-wrappers)

I will fully understand if you ignore and deal with much more important things!! 😄

[kriswest]

@Roaders no problem, I'm with you on that one! The first is mine, second much older. Fixed along with a coupe of other examples in 2e5da9805cf1f68254ff983495558436ba78ace0

[Roaders]

I'm still reading through. There might be more. I'll add them as comments on the code rather than here. This was more of a general issues as I'd seen it in at least one or 2 places.

[Roaders]

read through finished. I probably did it wrong and should have started a review rather than individual comments (not done much github pr reviews). Apologies for all the individual messages. The docs look great though. Very thorough and well written.

[kriswest]

read through finished. I probably did it wrong and should have started a review rather than individual comments (not done much github pr reviews). Apologies for all the individual messages. The docs look great though. Very thorough and well written.

No problem and many thanks for your time on the review @Roaders - the docs are better for it!