Updating SessionStorage data format to additionally scope data

kriswest commented 2 days ago

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

[x] 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

[x] Issue: If a change was made to the FDC3 Standard, was an issue linked above?
[x] 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)?
- [x] 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[bot] commented 2 days ago

Deploy Preview for fdc3 ready!

Name	Link
Latest commit	662d28aa4e0d38a2952e767c313bfb3ff403d9b4
Latest deploy log	https://app.netlify.com/sites/fdc3/deploys/6740b1127b6ee800089d083d
Deploy Preview	https://deploy-preview-1442--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.

Roaders commented 8 hours ago

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 commented 5 hours ago

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.

finos / FDC3