Skip to content

[T3 Connect] TypeScript and C# SDKs: old clients skip columns added to a table - #6091

Merged
Nintron27 merged 3 commits into
masterfrom
bradley/ts-sdk-row-boundaries
Nov 12, 2026
Merged

Nintron27 merged 3 commits into
masterfrom
bradley/ts-sdk-row-boundaries

Conversation

@bradleyshep

@bradleyshep bradleyshep commented Oct 6, 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: add new tables or views in place of adding columns to ones clients subscribe to.

Description of Changes

The migration docs allow adding a column to the end of a table and say old clients won't see it (docs). In the TypeScript and C# SDKs, an old client misreads every row after the first: TypeScript throws RangeError, and C# silently returns wrong values.

Both read rows back to back and ignore the row boundaries the server sends (RowSizeHint). The Rust SDK uses them (source).

Each row is now read from its own slice, as in Rust, so trailing columns the bindings don't know are skipped.

  • TypeScript: #parseRowList. A zero fixed size, which the server never sends, throws, as it does in C#.
  • C#: a SeekRow helper before each row in the seven row loops, with no per-row allocation.

Removing, reordering or retyping a column still breaks old clients.

API and ABI breaking changes

This breaks nothing, because the wire format is unchanged and the server already sends exact boundaries. It's only an API change in spirit, since RowSizeHint is now documented as mandatory.

Rollback safety impact

n/a

Expected complexity level and risk

  1. Every row read in two SDKs goes through the new code. Clients whose bindings match read the same bytes as before.

Testing

  • TypeScript and C# tests: an old client reads two rows with an added column, with variable- and fixed-size rows. Both fail without the change.
  • pnpm test (480 passing) and pnpm lint
  • C#: 112 tests pass; dotnet build -warnaserror and dotnet format --verify-no-changes

@Nintron27

Copy link
Copy Markdown
Contributor

Yeah, I'd recommend this for the T3 push, not because it's "needed" but because it's a nice add in general and is pretty simple.

@Nintron27
Nintron27 marked this pull request as ready for review November 3, 2026 15:48
Penguinjanator pushed a commit to Penguinjanator/SpacetimeDB that referenced this pull request Nov 7, 2026
…Node on a bad message (clockworklabs#6010)

> 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](https://github.com/clockworklabs/SpacetimeDB/blob/1395aaffa524aa2cbdc9a938021cd5d1e3fc90f7/sdks/csharp/src/SpacetimeDBClient.cs#L461-L465)).
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.

clockworklabs#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

1.

# Testing

Added:

- [x] 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.
- [x] Tests that the same row arriving before `InitialConnection` is
reported through `onConnectError`, and `onDisconnect` is never called.
- [x] 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.

---------

Co-authored-by: Nintron <nintron@sent.com>
Co-authored-by: Tyler Cloutier <cloutiertyler@aol.com>

@cloutiertyler cloutiertyler left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should really be done as a larger effort to have the client negotiate a schema with the server most likely. RowSizeHint was originally a performance optimization and I don't think it was meant to be relied upon.

I think we'd either have to decide to change that to become a guarantee (and remove the None) or do the negotiation thing.

Either way, this is kind of a janky kludge which kind of hacks it in without a proper design.

@cloutiertyler

cloutiertyler commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

I've changed my mind here actually. It turns out that Rust already relies on this capability, so I think we should go for consistency here and have all the SDKs behave the same way. But crucially this means two things:

  1. The "hint" is not a hint, it's a mandatory part of the API contract
  2. We should add a TODO to have the client negotiate its schema with the server so that the server only sends down the rows it needs in the future to avoid wasting bandwidth sending columns the clients are going to skip anyway.

I pushed the changes I would need to see, and so I've approved this PR.

bradleyshep and others added 3 commits November 11, 2026 20:22
The server sends where each row starts (RowSizeHint), but the TypeScript
and C# SDKs read rows back to back. A module that adds a column to the
end of a table, which the migration docs say non-updated clients can
ignore, made those clients misread every row after the first: TypeScript
threw, C# returned wrong values. The Rust SDK already decodes each row
from its own slice.

Decode each row from its own slice in both SDKs. TypeScript keeps the
back-to-back read for a zero fixed size, which the server never sends
but the SDK's test helpers do.
Every SDK now finds rows through `RowSizeHint`, so document that the
server must send exact boundaries and that clients must ignore bytes
left in a row after decoding the columns they know. Remove the note
proposing a `None` variant, which would break that contract, and add a
TODO for schema negotiation so the server only sends the columns a
client expects.

Remove the TypeScript fallback for a zero fixed size. Only test helpers
sent it, so give them real row boundaries and reject it as C# does.
The bandwidth use-case still applies once the client and server negotiate
a schema, because the server would then send only the columns the client
expects and rows could be decoded back to back. Say that it depends on
negotiation so that it doesn't contradict the API contract on `size_hint`.
@Nintron27
Nintron27 force-pushed the bradley/ts-sdk-row-boundaries branch from 33aae64 to 2ecf96d Compare November 12, 2026 01:24
@Nintron27
Nintron27 changed the base branch from bradley/ts-sdk-node-crash to master November 12, 2026 01:25
@Nintron27
Nintron27 added this pull request to the merge queue Nov 12, 2026
Merged via the queue into master with commit 205e55c Nov 12, 2026
123 of 125 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