[s2 lite] clamp=true ignored on read sessions — returns 416 instead of clamping to stream tail

[NiklasDah]

Description

Read sessions on S2 Lite with clamp=true still return 416 Range Not Satisfiable when the requested starting position is beyond the stream tail (e.g., reading from seq_num=0 on an empty stream). According to the docs, clamp should silently adjust the starting point to the stream tail instead of erroring.

Reproduce

1. Create a new (empty) stream
2. Start a read session with seq_num=0 and clamp=true:

   GET /v1/streams/{stream_id}/records?seq_num=0&clamp=true
   

3. Observe a 416 response instead of a clamped read session:

   RangeNotSatisfiableError: Range not satisfiable: requested position is beyond the stream tail (seq_num=0).
   Use 'clamp: true' to start from the tail instead.
   

The error message itself even suggests using clamp: true — which is already set.

Expected Behavior

Per the docs:

When clamp is enabled and the starting point is beyond the stream tail, the session should begin reading from the tail rather than returning an error.

The read session should open successfully, clamped to the current tail, and follow for new records (if unbounded).

Actual Behavior

The clamp parameter is ignored. The server returns 416 Range Not Satisfiable with a response suggesting the caller use clamp: true — the very flag that was already provided.

request{method=GET uri=/v1/streams/HxmuEnT9XeZ7wPfnmk-GE/records?seq_num=0&clamp=true version=HTTP/1.1}:
  tower_http::trace::on_response: finished processing request latency=0 ms status=416

SDK trace:

RangeNotSatisfiableError: Range not satisfiable: requested position is beyond the stream tail (seq_num=0).
  Use 'clamp: true' to start from the tail instead.
    at streamRead (.../node_modules/@s2-dev/streamstore/dist/esm/lib/stream/transport/fetch/shared.js:29:19)

Notes

• Reproduced with ghcr.io/s2-streamstore/s2:0.29.21.

[shikhar]

The error message was recently fixed in the TypeScript SDK, that was confusing if you were already clamping s2-streamstore/s2-sdk-typescript@843b6e4

But you should not need clamp if starting from 0, so long as you are able to follow

https://s2.dev/docs/api/records/read#starting-point-out-of-range & https://s2.dev/docs/api/records/read#follow-live-updates

It is clear that you are specifying clamp, but not whether this was a unary or session read request as that is determined based on headers (#317).

Can you confirm if you are using read or readSession? If the former, you will need a non-zero wait to long poll.

[NiklasDah]

I was using read, sorry - did not realize that this was only differentiated on the headers:

await stream.read(
      { start: { from: { seqNum: 0 }, clamp: true } },
      { as: "string" },
    );

[shikhar]

stop: { waitSecs: 1 }

will make read long-poll for 1s and return an empty batch if the stream is still empty, instead of an immediate 416

Even with readSession, to not get an immediate 416, you need it to follow for live updates. This will happen by default if you don't specify a limit, or you can be similarly explicit with the wait param.

[NiklasDah]

I see, but I still have to say that the behaviour was confusing in combination with the old error message. Thank for you for the clarification though.

Maybe the SDK types could forbid using clamp without stop in that case?

[shikhar]

Yes I can see how this is confusing @NiklasDah, keeping this open to think about how to make the semantics clearer. Thanks for the feedback!