SSR safety: ResourceTypeFromIri is a module-level singleton mutated per request

[silverbackdan]

Summary

resource-utils.ts exports a module-level singleton, shared across every SSR request in the Node process:

export const ResourceTypeFromIri = new ResourceTypeFromIriCls()
export const getResourceTypeFromIri = ResourceTypeFromIri._call.bind(ResourceTypeFromIri)

…and it is mutated from per-request code — cwa.ts:68, inside the Cwa constructor, which the Nuxt plugin runs once per SSR request:

ResourceTypeFromIri.setPathPrefix((new URL(this.apiUrl)).pathname)

Why it is benign today

apiUrl comes from runtimeConfig and is identical for every request, so every request writes the same pathPrefix. The mutation is idempotent and the race is unobservable.

Why it is still worth fixing

It is a genuine SSR-safety footgun: per-request state written to process-global state. It holds only by the coincidence that the value happens to be request-invariant. Anything that later makes the prefix vary — multi-tenant / per-host API URLs, a per-request apiUrl override, previewing against a different API — turns this into cross-request contamination that would be very hard to trace, because getResourceTypeFromIri is called from everywhere (IRI parsing, depth headers, resource typing).

It also sits directly adjacent to auth-cookie handling: it is one line above the CwaFetch construction in the same constructor. The eager-capture fix in #263 deliberately keeps the request cookie in a per-instance closure precisely to avoid this pattern — ResourceTypeFromIri is the counter-example that proves "constructed per request" does not imply "state is per request", and it is the shape a future contributor might copy.

Suggested direction

Make the prefix per-instance rather than process-global — e.g. resolve it from injected config at the call sites that need it, or hang it off the per-request Cwa/CwaFetch rather than a shared singleton. The awkwardness is that getResourceTypeFromIri is used as a free function throughout the codebase, so this is a non-trivial refactor and needs a plan; hence raising rather than fixing inline.

No known user-facing bug — this is a latent hazard, raised while investigating #263 so it is not lost.

Discovered during the #263 investigation.

[silverbackdan]

Investigation findings — the proposed direction in this issue is the wrong fix

Do not apply yet. Documenting the analysis and a plan; no code changed.

1. The value is application-wide by design, not per-request

The issue proposes making the prefix per-instance. That models a variance that does not exist. cwa.ts:56-69:

const { public: { cwa: { apiUrl, apiUrlBrowser } } } = useRuntimeConfig()
this.apiUrl = isClient ? (apiUrlBrowser || apiUrl || default) : (apiUrl || apiUrlBrowser || default)
if (this.apiUrl) {
  ResourceTypeFromIri.setPathPrefix((new URL(this.apiUrl)).pathname)
}

runtimeConfig is process-level, and the server always resolves apiUrl (never apiUrlBrowser) — so every request in the process derives an identical prefix. Confirmed by the repo owner: the API URL is "an application-wide setting… It does not need to be scoped to the individual client."

⇒ There is no live bug here. The mutation is idempotent; the race is unobservable. This is a latent hazard only.

2. Blast radius of the proposed refactor

• getResourceTypeFromIri — free function, 16 non-spec files
• ResourceTypeFromIri.getPathPrefix() — 7 non-spec sites: storage/stores/fetcher/actions.ts:158, api/api-documentation.ts:121, api/fetcher/fetcher.ts:98 + :349, templates/components/main/ComponentGroup.Util.Synchronizer.ts:144, templates/components/main/admin/_common/useDynamicPositionSelectOptions.ts:36, templates/components/main/admin/resource-manager/_parts/AddComponentDialog.vue:163
• setPathPrefix — 1 site (cwa.ts:68)

The hard part is not the Vue components. It is the pure functions and store actions (storage/stores/fetcher/actions.ts, manifest-utils) which have no instance in scope and no natural way to obtain one without restructuring how those modules are constructed. Threading a per-request instance into them would meaningfully complicate the store layer — to express a per-request variance that the design rules out.

3. Recommended instead: enforce the invariant

Keep the singleton (it is the right shape — the value genuinely is process-wide) and make the single write point reject a conflicting re-assignment:

setPathPrefix(prefix?: string) {
  if (this.pathPrefix !== undefined && prefix !== this.pathPrefix) {
    throw new Error(
      `The API path prefix is application-wide and cannot change per request `
      + `(had '${this.pathPrefix}', got '${prefix}'). A per-request apiUrl requires `
      + `scoping this state per instance — see #264.`,
    )
  }
  this.pathPrefix = prefix
}

Rationale. The hazard this issue describes is not "it leaks today" — it is "if the prefix ever becomes request-varying, it becomes silent, untraceable cross-request contamination."

• The refactor prevents that by scoping the state.
• The guard prevents the silence: the first request with a differing prefix throws immediately, in dev, with a message naming the cause — instead of surfacing weeks later as one tenant seeing another's data.

It also encodes the invariant executably. Today nothing states "this is application-wide" — it merely happens to be true, which is exactly why it reads as a footgun. If per-tenant API URLs are ever genuinely needed, the guard fires at once and the refactor gets done deliberately, with the guard explaining why.

Honest limitation: the guard does not make leakage structurally impossible the way the refactor would. It converts a silent failure into a loud one. Given the value is application-wide by design, that is judged the right trade — but it is a trade.

Plan (when picked up)

1. Add the conflicting-write guard to ResourceTypeFromIriCls.setPathPrefix.
2. Tests in resource-utils.spec.ts (TDD — confirm each fails for the right reason first):
   • a repeat call with the same prefix is a no-op (the real per-request path — must not throw)
   • a repeat call with a different prefix throws, naming both values
   • setPathPrefix(undefined) after a set prefix — decide and pin: currently a legitimate reset, or a conflict? (cwa.ts:68 only calls it when this.apiUrl is truthy, so undefined never reaches it in practice.)
   • the singleton is module-level and shared across spec files — reset it in beforeEach/afterEach or the guard will leak failures between tests.
3. Comment on the export stating the invariant and pointing here.
4. Consider whether throw or logger.error is right — a throw during plugin setup breaks the whole app, which is correct for a genuine misconfiguration but harsh if any legitimate reset path exists. Decide before implementing.

Sequencing

#266 should land first — a real defect (a path-less API URL breaks all resource typing and the #261 depth headers) in the same method, affecting real deployments. This issue is a latent hazard with no live symptom.

Note #266's fix normalises a root pathname ('/') to undefined inside setPathPrefix, so the guard here must be written after that normalisation — otherwise '/' and undefined would read as a conflict.