FDC3 API Metadata

[julianna-ciq]

Describe your change

Add support for sending metadata to FDC3 API calls

Related Issue

resolves #1290

ToDo List to complete PR

• Add metadata params to typescript sources in API @julianna-ciq
• Add metadata params to DACP message schemas @julianna-ciq
• Add handle of metadata params to agent-proxy implementation @julianna-ciq
• Update types.ts for new handler arguments for metadata
• Update ContextMetadata.ts to handle additional metadata
• Add content to jsDocs about new metadata params in @julianna-ciq
  • DesktopAgent.ts
  • Channel.ts
  • Types.ts
• Fix EasyCLA status
• Resolve conflicts @julianna-ciq
• Migrate this PR to a FINOS repo branch for collaboration (merge into finos/fdc3-api-metadata and raise new PR @julianna-ciq
• Copy content added to jsDocs (about metadata params) to website/docs/api/ref/* pages (DesktopAgent, Channel, Types, Metadata). @julianna-ciq
• Review and improve metadata content already added in api/spec.md @kriswest
• Add functional use case content on Metadata to website/docs/api/spec.md @kriswest
• Add content to DACP overview on metadata in website/docs/api/specs/desktopAgentCommunicationProtocol.md @kriswest
• Fix CI and website build failures @kriswest or @julianna-ciq

Follow up work post acceptance of PR

• Update FDC3 reference implementation to support the metadata properties (Raise new issue)
• Implement tests for metadata handling in fdc3-agent-proxy (Raise new issue)
• Implement new conformance tests (raise new issue)
• Define conformance tests for metadata, including any backwards compatibility tests needed. (Raise new issue)
• Translate new metadata arguments to .NET specs (Raise new issue for @bingenito )
• Translate new metadata arguments to golang specs (Raise new issue for @kemerava )

Contributor License Agreement

• I acknowledge that a contributor license agreement is required and that I have one in place or will seek to put one in place ASAP.

Review Checklist

• Issue: If a change was made to the FDC3 Standard, was an issue linked above?
• CHANGELOG: Is a CHANGELOG.md entry included?
• API changes: Does this PR include changes to any of the FDC3 APIs (DesktopAgent, Channel, PrivateChannel, Listener, Bridging)?
  • Docs & Sources: If yes, were both documentation (/docs) and sources updated?
    
    JSDoc comments on interfaces and types should be matched to the main documentation in /docs
  • Conformance tests: If yes, are conformance test definitions (/toolbox/fdc3-conformance) still correct and complete?
    
    Conformance test definitions should cover all required aspects of an FDC3 Desktop Agent implementation, which are usually marked with a MUST keyword, and optional features (SHOULD or MAY) where the format of those features is defined
  • Schemas: If yes, were changes applied to the Bridging and FDC3 for Web protocol schemas?
    
    The Web Connection protocol and Desktop Agent Communication Protocol schemas must be able to support all necessary aspects of the Desktop Agent API, while Bridging must support those aspects necessary for Desktop Agents to communicate with each other
    • If yes, was code generation (npm run build) run and the results checked in?
      
      Generated code will be found at /src/api/BrowserTypes.ts and/or /src/bridging/BridgingTypes.ts
• Context types: Were new Context type schemas created or modified in this PR?
  • Were the field type conventions adhered to?
  • Was the BaseContext schema applied via allOf (as it is in existing types)?
  • Was a title and description provided for all properties defined in the schema?
  • Was at least one example provided?
  • Was code generation (npm run build) run and the results checked in?
    
    Generated code will be found at /src/context/ContextTypes.ts
• Intents: Were new Intents created in this PR?
  • Were the intent name prefixes and other naming conventions & characteristics adhered to?
  • Was the new intent added to the list in the Intents Overview?

[netlify]

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

Name	Link
🔨 Latest commit	333f128
🔍 Latest deploy log	https://app.netlify.com/projects/fdc3/deploys/6979de6b0b04c1000731d223

[robmoffat]

I see this issue:

generated/api/BrowserTypes.ts(6913,3): error TS1117: An object literal cannot have multiple properties with the same name.
2:51:50 PM: npm error Lifecycle script `build` failed with error:
2:51:50 PM: npm error code 2
2:51:50 PM: npm error path /opt/build/repo/packages/fdc3-schema
2:51:50 PM: npm error workspace @finos/fdc3-schema@2.2.0
2:51:50 PM: npm error location /opt/build/repo/packages/fdc3-schema
2:51:50 PM: npm error command failed
2:51:50 PM: npm error command sh -c npm run generate && tsc --module es2022
2:51:50 PM: > @finos/fdc3-context@2.2.0 build
2:51:50 PM: > npm run generate && tsc --module es2022

[kriswest]

Lets remove this as superseded by content in the wiki

[robmoffat]

do DAs ever sign things?

[kriswest]

Its not what's intended no, but they do pass it through.

Your question has me wondering if we we should change this so you have two separate types for App-provided fields and and DA-provided fields that have no overlapping types, then a union that combines the two as the full set of metadata fields. That would be a lot easier to comprehend!

WDYT @julianna-ciq ?

[robmoffat]

what if you want to raise an intent with metadata, but not appId? Do you put null for the app?

[kriswest]

As its optional, you can pass undefined. I believe this was @Roaders suggestion.

I more used to passing null (so make it required but union with null), but I'm not actually sure if that still a well thought of pattern... null has a meaning for us elsewhere (such as listen to all types) - is it more consistent for us to stick to a familiar pattern or is it better semantics to use undefined (as we are not providing that argument) 🤷‍♂️