Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

FDC3 for Web specification #1191

Open
wants to merge 175 commits into
base: main
Choose a base branch
from
Open

FDC3 for Web specification #1191

wants to merge 175 commits into from

Conversation

kriswest
Copy link
Contributor

@kriswest kriswest commented Apr 15, 2024

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:

Copy link

netlify bot commented Apr 15, 2024

Deploy Preview for fdc3 ready!

Name Link
🔨 Latest commit 15e9214
🔍 Latest deploy log https://app.netlify.com/sites/fdc3/deploys/67236d54d5a369000814dead
😎 Deploy Preview https://deploy-preview-1191--fdc3.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

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

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

This comment was marked as outdated.

@kriswest

This comment was marked as outdated.

@kriswest
Copy link
Contributor Author

@novavi @Roaders @robmoffat I finally got around to adding some admonitions to the docs about CSPs and the injected iframes - could you give them a look what you have a minute and let me know if they sound correct and complete?

See:

docs/api/ref/GetAgent.md Outdated Show resolved Hide resolved
docs/api/ref/GetAgent.md Outdated Show resolved Hide resolved
docs/api/ref/GetAgent.md Outdated Show resolved Hide resolved
docs/api/ref/GetAgent.md Outdated Show resolved Hide resolved
docs/api/spec.md Outdated Show resolved Hide resolved
schemas/api/fdc3UserInterfaceRestyle.schema.json Outdated Show resolved Hide resolved
schemas/api/fdc3UserInterfaceRestyle.schema.json Outdated Show resolved Hide resolved
src/api/GetAgent.ts Outdated Show resolved Hide resolved
s2tQuicktypeUtil.js Outdated Show resolved Hide resolved
@kriswest kriswest requested review from hughtroeger and a team October 1, 2024 13:35
@kriswest kriswest mentioned this pull request Oct 1, 2024
* `false`. Setting this flag to `true` will inhibit that behavior, leaving
* `window.fdc3` unset.
*
* @property {function} failover An optional function that provides a
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be good to make this property a URL or a function. If a URL, it should basically open a window with that URL, acting in essentially the same way as a window proxy function that you'd end up writing.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@robmoffat that is what we had in the original proposal. I believe you asked us to simplify it and remove the URL option. All it changes is who writes and maintains the code lives that loads the window (or iframe...) and then waits for it to be ready.

If we go with the URL option we'll need a clear description of how it will behave (as going that route the app will not ahve any control over properties of the window) .

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about offering a util fn or example implementation in the docs to handle it via copy-paste. I'm somewhat agnostic as to what we do at the moment.

I beleive the original proposal was:
failover?: (args: GetAgentParams) => Promise<URL | WindowProxy | DesktopAgent>

but then who passes in instances of the URL class? It would therefore be Promise<string | WindowProxy | DesktopAgent> and we'd have some error handling to do if the string was not a URL (reject with AgentError.InvalidFailover ).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok I was thinking:

failover?: string | (args: GetAgentParams) => Promise<WindowProxy | DesktopAgent>

Copy link
Contributor Author

@kriswest kriswest Oct 9, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Saves a few characters yes. Code working with the string will need to check its a URL, load it up into an iframe and at least wait for the load event to fire before trying to contact it. Thats the same as you need to do for adaptors loaded into an iframe so it could be handled by a util function.

However, we put the current draft to the discussion group for review and the SWG for adoption already. Given this is at the edge of what we're doing it might be better to wait for a subsequent version and focus on releasing what we've done so far.

@kriswest kriswest dismissed robmoffat’s stale review October 9, 2024 11:10

Outdated - many changes since that review. Requesting new reviews from maintainers

bingenito
bingenito previously approved these changes Oct 18, 2024
Copy link
Member

@bingenito bingenito left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed by @Roaders, so providing approval on behalf of org.

kriswest and others added 2 commits October 21, 2024 12:55
@kriswest kriswest requested a review from novavi October 25, 2024 15:05
…-fns

Deprecating functions in Methods.ts
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

FDC3 For Web browsers
8 participants