Updating SessionStorage data format to additionally scope data

[kriswest]

Describe your change

Updates the description of and types governing the use SessionStorage by getAgent to scope the data by identityUrl and window.name, thus ensuring iframes in a common window don't overwrite each others data and data for multiple different apps on teh same origin can be retained (to support navigating to a different app and then back again).

Docs preview deeplink: https://deploy-preview-1442--fdc3.netlify.app/docs/next/api/ref/GetAgent#persisted-connection-data

Related Issue

resolves #1430

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 canceled.

Name	Link
🔨 Latest commit	e5a0a49
🔍 Latest deploy log	https://app.netlify.com/sites/fdc3/deploys/674881fde96ae2000899e67c

[robmoffat]

LGTM

[Roaders]

I read the docs and I'm afraid I couldn't figure out what it's trying to tell me. It talks about generating a key by appending window.name to "FDC3-Desktop-Agent-Details-" but it then also talks about the key being the identity url.

Ah... I think I have it. The identityURL is used as the key in the session storage. The key above is then used within the object saved to session storage.

so you would access it something like this:

const sessionData = sessionStorage.get(myApIdentityUrl);
const agentDetails = sessionStorage["FDC3-Desktop-Agent-Details-myWindowName"];

I think that it might make it clearer if you include some sample code like that.... (there is always the possibility that I am just being stupid and it's perfectly clear to everyone else!)

[kriswest]

HI @Roaders, thanks for reading that and for the code suggestion that would make it clearer. I did intend it the other way round:

const sessionData:SessionStorageFormat = sessionStorage.get("FDC3-Desktop-Agent-Details-myWindowName");
const agentDetails: DesktopAgentDetails = sessionStorage["myApIdentityUrl"];

As multiple (same-origin) apps could have been loaded in one window. I'll drop an update to clarify.

[Roaders]

Much clearer (to me). SLight mistake in teh code though. You refer to sessionData on the first line but sessionStorage on the second. It should be:

const sessionData:SessionStorageFormat = sessionStorage.get("FDC3-Desktop-Agent-Details-myWindowName");
const agentDetails: DesktopAgentDetails = sessionData["myApIdentityUrl"];

[kriswest]

Well spotted @Roaders - fixed.

[kriswest]

Approved at SWG #1458

[kemerava]

LGTM

[kriswest]

@novavi this is implemented in fdc3-for-web-getAgent-refactor via functions in this file: https://github.com/finos/FDC3/blob/fdc3-for-web-impl-getAgent-refactor/packages/fdc3-get-agent/src/sessionStorage/DesktopAgentDetails.ts

The functions are then used in a few places in the getAgent implementation in this file: https://github.com/finos/FDC3/blob/fdc3-for-web-impl-getAgent-refactor/packages/fdc3-get-agent/src/strategies/getAgent.ts

It's all working well and to the updated spec, hence I think this PR to update the docs to match is ready to merge, it just needs your approval.

[novavi]

LGTM