FDC3 for Web specification #1191

kriswest · 2024-04-15T13:44:39Z

resolves #896
resolves #1385
resolves #1402

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

Draft Agent agnostic fdc3 spec

netlify · 2024-04-15T13:44:55Z

✅ Deploy Preview for fdc3 canceled.

Name	Link
🔨 Latest commit	`ed22949`
🔍 Latest deploy log	https://app.netlify.com/sites/fdc3/deploys/6734b99fd9905a0008cbe86f

…tep schema

…rom review

kriswest · 2024-11-04T22:39:38Z

@kemerava many thanks for the detailed review. I've resolved most of the comments for things fixed. I've left a few open for you to look at, please resolve those as well. Our branch protection will require you to post another review/confirm requested changes have been made.

pvoznyuk · 2024-11-06T21:18:45Z

docs/api/ref/GetAgent.md

+
+```js
+    const desktopAgent = await getAgent({
+        timeoutMs: 250,


Timeouts are usually counted in milliseconds. Isn’t it overkill to name it timeoutMs rather than just timeout?

Hi Pavlo, we actually started out with timeout but moved to timeoutMs after review comments suggested its slightly more intuitive. I think it probably boils down to personal preference.

pvoznyuk · 2024-11-06T21:21:20Z

docs/api/spec.md

@@ -603,7 +613,7 @@ To find a User channel, one calls:
 ```ts
 // returns an array of channels
 const allChannels = await fdc3.getUserChannels();
-const redChannel = allChannels.find(c => c.id === 'red');
+const redChannel = allChannels.find(c => c.id === "red");


I think this would be the correct example.

const redChannel = allChannels.find(c => c.id === "fdc3.channel.1");

Good point (match IDs to the recommended FDC3 channels). I'll implement that change.

Hmm, well technically this example significantly predates this PR (and in fact the recommended channels).

To be honest, I don't think it a good example at all. If you already know the channel name (as it the case in this example) you wouldn't do this at all. Rather you would more simply do:

const redChannel = fdc3.getOrCreateChannel("fdc3.channel.1");

Frankly, I think we should replace this example and the matching one at: https://fdc3.finos.org/docs/api/ref/DesktopAgent#getuserchannels
Particularly as the use case for fdc3.getUserChannels is not to find a specific channel, but to get the whole list to do something with.

Let me know if you're up for raising that as a separate issue (and perhaps PR), otherwise I can take care of it. It can be done quickly and without a vote as its not changing the standard, jsut improving its docs.

I think this documentation improvement can be done in-place as it doesn't affect any functionality.

robmoffat · 2024-11-08T10:13:38Z

schemas/api/fdc3UserInterfaceDrag.schema.json

@@ -2,7 +2,7 @@
  "$schema": "http://json-schema.org/draft-07/schema#",


I still don't think we're going to need this message. Would be nice to merge my PoC into @julianna-ciq 's add-on module to prove that.

The approach that you very briefly explained to positioning the iframe from inside by first resizing it to cover the whole parent window still seems risky, likely to cause display artefacts and is likely slower to apply (requires more messaging and rendering).

We've also reviewed the current standard docs multiple times and checked the consensus of the SWG on them which we'd have to repeat if changing them significantly. We would need both a write-up and discussion of what you propose doing to change it and, personally, I don't think it worth further delaying this project to do so - no actual benefit to it has been articulated as yet.

hughtroeger

Minor comments, content looks good 👍

docs/api/ref/GetAgent.md

schemas/api/api.schema.json

schemas/api/getInfoRequest.schema.json

Co-authored-by: Hugh Troeger <[email protected]>

openfin-johans

Looks good to me!

thorsent and others added 6 commits February 29, 2024 12:21

First pass browser-resident DAs

1ba26e0

Add BCP definitions

fd94343

Finish protocols

253dc93

Update docs/specs/getAgent.md

28c7a95

Merge branch 'fdc3-for-web' into thorsent/fdc3-for-web-spec

02d0322

Merge pull request #1167 from thorsent/thorsent/fdc3-for-web-spec

3ebd5f2

Draft Agent agnostic fdc3 spec

kriswest added 2 commits April 16, 2024 18:37

50% complete json schemas for api wire protocol messages

ac7723f

completing most API call messages in wire protocol

de724be

kriswest marked this pull request as draft April 17, 2024 09:47

kriswest added 3 commits April 17, 2024 13:10

adding messages for managing context and intent listeners

8bcaab2

Completing private channel message exchanges and all event messages

bc8ec0f

prettier

fbf7598

This comment was marked as outdated.

Sign in to view

minor jsdoc correction

971f62d

kriswest mentioned this pull request Apr 22, 2024

FDC3 for Web Browsers Discussion group 18th April 2024 #1192

Closed

12 tasks

This comment was marked as outdated.

Sign in to view

Merge branch 'main' into fdc3-for-web

3d72ff0

kriswest mentioned this pull request Apr 30, 2024

Agent agnostic fdc3 spec #1167

Merged

kriswest added 11 commits April 30, 2024 13:25

Updating getAgent and Errors docs pages for fdc3-for-the-web

68121b7

minor clarification in Private Channel content

7d975e9

moving new DA specs files

4def718

Updates to API spec based on PR feedback

278eca6

improving supported platforms content

f5366a0

Updating raiseIntent API messages to include a NeedsResolution message

a43c7a1

Adding Web Connection protocol messages

5d45c1d

Merge branch 'DOTNET-FDC3-signatures' into fdc3-for-web

ce2e30d

Corrections to API schemas from testing

cdd5737

fixing further minor schema errors

eebb133

failed attempts to resolve an issue with compiling the WCPConnectionS…

6c5d5aa

…tep schema

kriswest added 5 commits November 4, 2024 18:20

Corrections from review

93226f9

Corrections to message schemas from review

e48bf19

Corrections to schema comments an generated code, from review

f44482d

More corrections to schemas, generated bridging types and Method.ts f…

120f450

…rom review

comment correction

b063ee4

pvoznyuk reviewed Nov 6, 2024

View reviewed changes

robmoffat requested review from mistryvinay and removed request for novavi November 7, 2024 14:04

kriswest requested review from kemerava and novavi November 7, 2024 14:05

robmoffat mentioned this pull request Nov 8, 2024

FDC3 For Web Browsers Implementation #1309

Open

robmoffat previously approved these changes Nov 8, 2024

View reviewed changes

Fixing capitalisation of schema id (URL)

56932f9

kriswest dismissed robmoffat’s stale review via 56932f9 November 8, 2024 16:16

Merge branch 'main' into fdc3-for-web

8dd4ad6

hughtroeger previously approved these changes Nov 11, 2024

View reviewed changes

docs/api/ref/GetAgent.md Outdated Show resolved Hide resolved

schemas/api/api.schema.json Outdated Show resolved Hide resolved

schemas/api/getInfoRequest.schema.json Outdated Show resolved Hide resolved

Update docs/api/ref/GetAgent.md

b57635f

Co-authored-by: Hugh Troeger <[email protected]>

kriswest dismissed hughtroeger’s stale review via b57635f November 13, 2024 14:36

kriswest and others added 2 commits November 13, 2024 14:37

Update schemas/api/api.schema.json

834ca1c

Co-authored-by: Hugh Troeger <[email protected]>

Update schemas/api/getInfoRequest.schema.json

ed22949

Co-authored-by: Hugh Troeger <[email protected]>

robmoffat approved these changes Nov 13, 2024

View reviewed changes

kemerava approved these changes Nov 13, 2024

View reviewed changes

hughtroeger approved these changes Nov 13, 2024

View reviewed changes

novavi approved these changes Nov 13, 2024

View reviewed changes

robmoffat requested a review from openfin-johans November 13, 2024 14:58

openfin-johans approved these changes Nov 13, 2024

View reviewed changes

kriswest merged commit 5b9c140 into main Nov 13, 2024
7 checks passed

kriswest deleted the fdc3-for-web branch November 13, 2024 17:57

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FDC3 for Web specification #1191

FDC3 for Web specification #1191

kriswest commented Apr 15, 2024 •

edited

Loading

netlify bot commented Apr 15, 2024 •

edited

Loading

This comment was marked as outdated.

This comment was marked as outdated.

kriswest commented Nov 4, 2024

pvoznyuk Nov 6, 2024

kriswest Nov 7, 2024

pvoznyuk Nov 6, 2024

kriswest Nov 7, 2024

kriswest Nov 7, 2024

pvoznyuk Nov 11, 2024

robmoffat Nov 8, 2024

kriswest Nov 8, 2024

hughtroeger left a comment

openfin-johans left a comment

		@@ -2,7 +2,7 @@
		"$schema": "http://json-schema.org/draft-07/schema#",

FDC3 for Web specification #1191

FDC3 for Web specification #1191

Conversation

kriswest commented Apr 15, 2024 • edited Loading

netlify bot commented Apr 15, 2024 • edited Loading

✅ Deploy Preview for fdc3 canceled.

This comment was marked as outdated.

This comment was marked as outdated.

kriswest commented Nov 4, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hughtroeger left a comment

Choose a reason for hiding this comment

openfin-johans left a comment

Choose a reason for hiding this comment

kriswest commented Apr 15, 2024 •

edited

Loading

netlify bot commented Apr 15, 2024 •

edited

Loading