Skip to content

[T3 Connect] TypeScript SDK: fail the connection instead of crashing Node on a bad message - #6010

Merged
bradleyshep merged 4 commits into
masterfrom
bradley/ts-sdk-node-crash
Nov 6, 2026
Merged

bradleyshep merged 4 commits into
masterfrom
bradley/ts-sdk-node-crash

Conversation

@bradleyshep

@bradleyshep bradleyshep commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Part of the work to move T3 Code's T3 Connect relay onto SpacetimeDB. Non-blocking. T3's workaround: never change the row layout of tables or views that clients subscribe to.

Description of Changes

In Node, a server message the SDK fails to apply, such as a row that doesn't match the client's bindings, throws out of the WebSocket listener and crashes the process. An error thrown in an app callback (onInsert, onConnect, …) does the same.

  • A message that fails to apply is handled like one that fails to decode: it is logged and ends the connection, queued messages are dropped, and pending calls settle. The app gets a WebSocketProtocolError whose cause is the original error, through onConnectError if the connection wasn't established yet and through onDisconnect otherwise. Like master's protocol errors, it doesn't retry automatically. Without automatic reconnect, a message that fails to decode now does the same instead of throwing.
  • A throwing callback is logged, the remaining callbacks still run, and the connection stays open.

The C# SDK already logs, fails pending calls and disconnects (source). An app that prefers to crash on a bad message can do so in onDisconnect or onConnectError, and an app that wants to handle callback errors itself can wrap its own callbacks.

#6091 makes the most common mismatch, an added column, readable.

API and ABI breaking changes

This is technically a breaking change, because errors that used to escape the SDK no longer do. An error thrown from an app callback is now logged instead of thrown, so global error handlers, error monitoring and test assertions inside callbacks no longer see it, and a message the SDK can't apply now ends the connection, so a Node service that relied on crashing and being restarted now stays up but disconnected unless it handles the error. We don't expect apps to rely on the old behavior, since it crashed Node processes and left browser calls hanging, and users would only notice when a callback throws or the server sends rows that don't match their bindings.

Rollback safety impact

n/a

Expected complexity level and risk

Testing

Added:

  • Tests that a player row one byte short, as from bindings out of step with the module, ends the connection: onDisconnect gets a WebSocketProtocolError caused by the RangeError, the pending reducer call rejects, and a later message is ignored. On master the error escapes the WebSocket listener instead.
  • Tests that the same row arriving before InitialConnection is reported through onConnectError, and onDisconnect is never called.
  • Tests that a throwing onConnect is logged, a second onConnect still runs, and the connection stays open. On master the error escapes the WebSocket listener.

The existing reconnect test for an incomplete subscription replay response checks that a protocol error with automatic reconnect on still ends the connection without retrying.

Not tested directly: a first message that fails to decode, because the test adapter only sends well-formed messages. It reaches the same handler as the case before InitialConnection above.

@bradleyshep
bradleyshep force-pushed the bradley/ts-sdk-node-crash branch 2 times, most recently from 593741b to d6aa799 Compare September 30, 2026 17:38
@bradleyshep bradleyshep changed the title TypeScript SDK: fail the connection instead of crashing Node on a bad message [T3 Connect] TypeScript SDK: fail the connection instead of crashing Node on a bad message Sep 30, 2026
@bradleyshep
bradleyshep force-pushed the bradley/ts-sdk-node-crash branch from d6aa799 to 5c8d0ea Compare October 1, 2026 17:26
@bradleyshep
bradleyshep force-pushed the bradley/ts-sdk-node-crash branch from 5c8d0ea to 273bca5 Compare October 6, 2026 15:52
…nnot be applied

A server message the client cannot decode or apply (for example, bindings out of step with the module's schema) threw out of the WebSocket message listener, as did an error thrown by a user callback. Browsers only report such errors; Node rethrows them on the next tick, which kills the host process.

- A message that cannot be applied is logged and ends the connection: queued messages are dropped, calls in flight settle, and onDisconnect receives the error.
- A callback that throws is logged, and the other callbacks still run on an open connection.
@Nintron27

Nintron27 commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Is this *needed* for T3? No, but it seems like a straightforward quick-win to have either way. Stacking this with #6091 would be a really nice add. With this PR, the TypeScript SDK won't crash the process (in Node) anymore, with #6091 the TypeScript and C# SDKs will handle new DB columns added to the end by just ignoring them all together till the client bindings are updated like how the Rust SDK works.

I'd recommend this (along with #6091, which is stacked on this branch).

@Nintron27
Nintron27 marked this pull request as ready for review November 3, 2026 15:42
@cloutiertyler

cloutiertyler commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

I updated the description. The breaking-changes section now says this is technically a breaking change, since an error thrown from a callback is now logged instead of thrown, and a message the SDK can't apply now ends the connection instead of crashing Node. We also clarified that crashing in onDisconnect only covers bad messages, because a throwing callback doesn't disconnect.

Route a message that fails to apply through the same handler as one that
fails to decode, and stop that handler from rethrowing when automatic
reconnect is off. A failure before the connection is established now
reaches onConnectError instead of onDisconnect, and every such failure
arrives as a WebSocketProtocolError with the original error as its cause.
@cloutiertyler

Copy link
Copy Markdown
Contributor

We pushed bd40ced to this branch. A message that fails to apply now goes through #handleProtocolError, the same path as one that fails to decode, and that handler no longer rethrows when automatic reconnect is off. Before, a failure before the connection was established reached onDisconnect even though onConnect never ran, and the error type depended on whether automatic reconnect was on. Now that case goes to onConnectError, and every bad message arrives as a WebSocketProtocolError with the original error as its cause. The truncated-row test checks the new error shape, a new test covers the failure before InitialConnection, and we updated the description and testing section to match.

@bradleyshep
bradleyshep added this pull request to the merge queue Nov 6, 2026
Merged via the queue into master with commit 2613d19 Nov 6, 2026
125 of 127 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants