Skip to content

Collapse the three outward session-decode error messages into one #521

Description

@turner

Parent

ADR-0006 decision 9 — docs/adr/0006-session-wire-format-and-one-decoder.md. Follow-up to #504.

What this is

#504 gave the decoder one internal error contract: js/sessionCodec.js raises a single SessionDecodeError for every malformed session, carrying the underlying failure as cause.

It deliberately did not change what extractConfig reports outward. The three arms in js/urlUtils.js still rethrow cause in the three shapes they have always thrown:

  • the blob:/data: arm rethrows the raw cause — which is a bare string from BGZip, not an Error, so name and message are both undefined
  • the File arm: Failed to parse session file: <cause.message>
  • the URL arm: Failed to load session from URL/file: Failed to parse session from URL/file: <cause.message> (double-wrapped)

That was correct for #504, whose acceptance criterion was byte-identical golden snapshots. It is not the end state. The original complaint stands: the same malformed input still produces a different message depending on which path reached it, which makes a user's bug report ambiguous about where their link actually failed. And the first arm can still reject with a value that is not an Error at all.

What to build

One outward failure shape for a session that will not decode, reported the same way whatever fetched it. Whatever it is, it must always be an Error, and it should say both what failed to decode and where the session came from — those are two facts, not two messages.

Acceptance criteria

  • A session that will not decode produces the same error shape from all three arms
  • The rejection is always an Error — no bare string escapes extractConfig
  • The source of the session (parameter, file, URL) survives in the error
  • test/__snapshots__/testDecoderGolden.js.snap is updated per fixture, with a row added to the "Authorised snapshot movements" table in test/testDecoderGolden.js naming this issue

Note on the snapshots

This ticket moves golden snapshots, and that is the point of it existing separately. Every moved fixture must be one you can explain — a fixture you did not expect to move is a bug report, not a snapshot to accept. See the convention in the header of test/testDecoderGolden.js.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions