FCE-3580: define tsunami error model - #577
Merged
Merged
Conversation
MiloszFilimowski
requested review from
Tay0108,
Copilot and
czerwiukk
and removed request for
Tay0108 and
czerwiukk
July 30, 2026 15:08
Document the error-model decision in packages/tsunami/AGENTS.md: every failing imperative method rejects with a typed FishjamError subclass and the same object is mirrored into the matching ClientState field, applied to device acquisition, addTrack (TrackTypeError becomes a rejection), and connect() (typed rejections consistent with peerStatus). Land the base primitive: FishjamError (cause + recoverability) with ClientDisposedError refactored onto it under src/errors/. Concrete error classes land with their first consumer in the follow-up tickets. Bump the base tsconfig lib to es2022 for Error.cause typing (tsunami is the only package extending it).
MiloszFilimowski
force-pushed
the
mfilimowski/FCE-3580
branch
from
July 31, 2026 08:40
3c7c643 to
add1f83
Compare
czerwiukk
approved these changes
Jul 31, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Answers the FCE-3580 decision ticket: how errors surface in tsunami's API.
The decision (documented in
packages/tsunami/AGENTS.md): both surfaces, one error object — a failing imperative method rejects with a typedFishjamErrorsubclass, and the same object is mirrored into the matchingClientStatefield; a later success clears it. Applied to the three ticket paths:DeviceErrorsubclass; same object incameraError/microphoneError.initializeDevicesresolves with a result — degraded init is a supported outcome.addTrackin a room refusing the track kindTrackTypeError— never a synchronous throw (the legacy sync throw becomes a rejection; adapter keeps the pinned keep-local recovery).connect()AuthError/JoinError/SocketError/ConnectionError(neverundefined, never hangs) and setspeerStatus: "error"from the same event list.Code in this PR is deliberately minimal: the
FishjamErrorbase (cause+recoverability) withClientDisposedErrorrefactored onto it undersrc/errors/, plus a one-wordlibbump toes2022forError.causetyping. Concrete error classes land with their first consumer (device controller, connect state machine, addTrack migration) per the YAGNI rule in AGENTS.md.Motivation and Context
The FCE-3030 test review (#543) showed these paths had the weakest coverage because there was nothing stable to assert on: legacy
connect()rejects withundefined(the test fake had to reject with a realErrorto be testable at all — making the suite stricter than production), device failures surface through four different mechanisms, andTrackTypeError's synchronous throw is specified only by a comment in the fake. Typed errors make every path testable asawait expect(op).rejects.toBeInstanceOf(X)plus a state assertion — first-class, not incidental.Documentation impact
Types of changes