Skip to content

Review panel session - #106

Merged
tishun merged 7 commits into
feature/resumable-streamsfrom
topic/tishun/review-panel-latest
Nov 11, 2026
Merged

tishun merged 7 commits into
feature/resumable-streamsfrom
topic/tishun/review-panel-latest

Conversation

@tishun

@tishun tishun commented Nov 10, 2026

Copy link
Copy Markdown
Collaborator

Apply the following improvements (read commit messages for details):

  • fix(streams): make the examples and the dependency floors tell the truth
  • fix(streams): guard the pool and the shutdown path; add the panel reports
  • fix(streams): bound stream_max_run on the field, not in the setup check
  • feat(streams): finished() tells an ended run; a finished run lives stream_done_ttl
  • refactor(streams): remove indirection the one-per-process backend never needed
  • test(streams): prove the documented behaviours, through public seams
  • docs(streams): say what the feature does and costs, not what it was meant to

A review panel on this branch (specs/review-panel.md) confirmed three
blockers. Two were in the four agent-SDK example apps, one in the floor
the package declares.

The example `events` routes declared an `after` query parameter and passed
it to `sse()`. A handler-supplied cursor beats `Last-Event-ID` on purpose,
so a browser that reconnected with a newer header got everything after the
stale query value sent again: a silent duplicate, the one thing the feature
promises not to do. The routes now let `sse()` read the request itself,
as the guide and the design show.

The example `cancel` routes returned `{"cancelled": await streams.cancel()}`
under a `dict[str, bool]` annotation. `cancel()` returns `None`, so every
call cancelled the run and then answered 500. They now answer 204.

The stream response catches `_SlowConsumer` to free a reader slot quietly.
On Starlette below 0.46 the body runs in a bare anyio task group, so the
exception arrives wrapped in an `ExceptionGroup`, escapes the handler, and
uvicorn logs it as an unhandled application error. FastAPI 0.134.0 is the
first release that requires Starlette 0.46, so the floor moves there
rather than carrying group-unwrapping code for versions CI never installs.

Installing the declared floors by hand found a second false one, older
than this branch: `config.py` imports `redis.driver_info`, which first
shipped in redis-py 7.2.0. No release below it could import the package
under the declared `>=6.2.0`, nor under main's `>=6.0.0`. The floor is now
`redis>=7.2.0`; it breaks no install that worked before.
…orts

lifespan.py: `aclose()` can wait up to five seconds for producers to write
their final entries. It ran before the pool close with nothing around it,
so a server that cancelled the shutdown there left the pool open. The pool
close now sits in a `finally`.

stream_backend.py, `spawn()`: `aclose()` cancels the tasks it finds once.
A writer opened before shutdown and spawned after was never cancelled; its
first append self-cancelled and its final write raced the pool close.
`spawn()` now refuses during shutdown, like `open()` does.

streams.py, `check_stream_settings()`: each live reader holds a pool
connection for a blocking read. A pool no larger than `stream_max_readers`
let readers take every connection, after which producers could not write,
not even the final entry, and readers saw `producer_lost` for a producer
that was alive. The configuration guide recommended exactly that pairing:
100 connections against the 256-reader default, and a 5 s socket timeout
against the 15 s heartbeat that `.streams()` already refused. The setup now
refuses a pool that is not larger than the reader cap, and the guide gained
a block that works with streams.

streams.py, `sse()`: the reader cap was enforced when the response ran,
after `_prepare()` had already read `XINFO STREAM` and a first page. A
client reconnecting in a loop at capacity cost Redis a full connect per
refused attempt. The cap is now checked before any Redis call, through the
same `_at_capacity()` that `_reserve_reader()` uses, and the 503 body lives
in one `_busy_response()`.

docs/guide/streams.md states both refusals and the 503-before-lookup order.
…eant to

Ten documentation items from specs/review-panel-action-plan.md (A13-A22).
Each fixes a place where the docs promised, hid or misdescribed something
the code does.

Streams guide
- EventSource fails any non-200 response and never retries, so the 503 a
  reader gets at the cap, with its Retry-After, stops the browser for good.
  The guide read as if it reconnected; it now says to open a new one.
- Every connect reads XINFO STREAM, which returns the first and last entries
  in full. That is the dominant cost of a reconnect storm and nothing said
  so; Limits now does, with the setting that bounds it.
- A client that closes mid-read costs a Redis connection, and on a server
  that does not cancel on disconnect a dead client holds its slot for a
  heartbeat. Both are correct behaviour a capacity planner needs to know.
- Payloads are stored as the coder's text. Sessions document encryption at
  rest; streams said nothing. Redis keys now says so and points at the
  Encryptor pattern.

Sessions guide
- Design §11 asked the sessions guide to show the stream routes as an
  access-dependency example and session_expiry() as the way to end an open
  stream with the session, and to link the WebSocket limitation to the
  future WebSocket reader. None of it was written. It is now.

Reference and docstring
- finish() can raise four exceptions and documented none, while append()
  documented the same set. Both the docstring and the reference row list
  them.

Design document
- Goal 2 promised the run survives "a gateway restart" while the non-goals
  and the guide say a producer dies with its process; goal 6 listed "one
  active run per scope" as an SDK goal after decision 4 moved it to the
  application. Both goals now match the design they head.
- The telemetry row listed a replay-bytes counter that was never built and
  that nobody asked for. Struck.

Demo and examples
- The demo README said a redeploy "never loses the answer"; only a finished
  one survives. It linked a spec that says "phase 1", which the brief keeps
  out of user-facing text; main.py linked it too. Both links are gone and
  the sentence tells the truth.
- The demo spec mapped a route to streams.active(), removed by decision 4,
  and linked a mockup index.html that was never committed. The row names the
  app's own pointer; the orphan mockups/style.css, referenced by nothing, is
  deleted.
- The examples index said the demo's streams "come from a stub until the SDK
  has them", a line older than the migration to the real feature.
Nine test items from specs/review-panel-action-plan.md (T1-T9). The panel
found behaviours the guide promises that nothing tested, tests that reached
into private attributes, three copies of the same probe, and two fixtures
with the same name.

New coverage (T1)
- A reader whose Redis ACL is read-only cannot end a silent run; the guide
  says it sends `stream.error` `producer_lost` instead. No test created such
  a user. One does now, and the path works.
- Stream telemetry had no test while every other feature has a test_otel_*.
  tests/unit/test_otel_streams.py compares the documented operation and
  result labels with the ones the modules emit, as whole sets, so the
  docstring and the code cannot drift apart unnoticed, and drives the
  reader gauge, the latency histogram, the spans and the slow-consumer
  counter without Redis.
- `stream.gap` was observed only from the read loop, never as the SSE frame
  a browser gets. A producer that skips a sequence number now shows it
  through the HTTP response.
- A session revoked while a stream is open was described in the guide and
  tested nowhere: the reconnect after `stream_max_connection_duration`
  now fails in the application's dependency with 401.
- A slow consumer closed by the send timeout reconnects with the last ID it
  received and gets exactly what followed.

Public seams instead of internals (T2)
- Five tests read `_prepare`, `_pages`, `_readers` or a generator frame to
  prove behaviour that `follow()` and `sse()` expose. They use those now.
  Tests that must pause a transaction at EXEC keep their hooks: no public
  seam can time that.

Fixtures (T3)
- `settings_env` was copied into two files and `configure()` cleared the
  settings cache on entry only, so a value could leak into the next test.
  One fixture in tests/stream_support.py, built on `configure()`, clears on
  both sides; the copies are gone.

Sync points (T4)
- Two bare sleeps before a cancel and a shutdown waited for a producer by
  guessing. They poll `XLEN` for the entries they need.

One probe (T5)
- The support probe existed three times: in the SDK, in the test module and
  in the nox session, each parsing `COMMAND INFO` by hand. The test module
  and the session import `probe_streams_support`, so the three can no
  longer disagree about what "supported" means.

Conventions (T6, T7)
- SKILL.md said unit tests use fakeredis; the stream unit tests cannot,
  since fakeredis lacks `XADD IDMP`, `XCFGSET` and `DELEX`. The skill says so.
- The "feature turns itself off" path was proven only on the 7.4 CI job.
  Two unit tests stub the probe's answer: one warning, every entry point
  refuses, and the lifespan start reaches the same state. The topology and
  example-run files carry `@requires_redis` like every other integration
  test.

Topologies (T8, T9)
- The response-modes test keyed on `STREAMS_TEST_CLUSTER=1` and then
  pointed the Cluster client at the standalone URL, while every other test
  reads `STREAMS_TEST_CLUSTER_URL`; with the documented variable it never
  ran on a Cluster. It reads the URL now, and the design cites it.
- Design goal 8 claims Sentinel and nothing could run against one.
  `stream_case` gains a `sentinel` topology from `STREAMS_TEST_SENTINEL_URL`,
  skipped like Cluster and Enterprise when unset, and the guide says the
  path is supported by design and not exercised in CI.
…er needed

Five cleanups, no behaviour changes; every stream and session test
passes as before.

Support detection. The result was kept in a one-field dataclass,
mirrored on `_PoolState.stream_capabilities`, and rebound through
`_start()` at every lifespan start, but nothing ever read the pool slot.
The rate-limit and session backends need a shared slot because they are
built per request; `StreamBackend` is one object per process, so the slot,
the dataclass and the `capabilities=` argument were indirection with no
consumer. Support is now `_supported` on the backend, and `_start()` resets
it when the lifespan binds a new pool. deps.py drops the runtime import.

Spawned producers. Three registries - a task set, a task-by-run dict
and a writer-by-task dict - were kept in step by hand, and the task set
always equalled the writer dict's keys. One dict of writers by run serves
`cancel()`, `aclose()` and the cancel-unless-ending rule, each reading
`writer._task` and `writer._ending` directly.

First-page transaction. `_prepare` queued the cursor's own `XRANGE`
only when a cursor was given, so the replies that followed had to be
indexed by position with two conditionals. The command is always queued
now - with no cursor it is `XRANGE 0-0 0-0`, which is empty - and every
reply has one fixed position.

Duplicates and dead guards.
- `STORE_ERRORS` was a byte-for-byte copy of the session module's tuple,
  with a comment pointing at the original. The new `_errors.py` holds the
  one definition, with the reason `RedisClusterException` must be in it.
- `except _END_ERRORS` could only ever see a `StreamError`: `_retry` turns
  every driver error into one before it gets there. It says
  `except StreamError` now, and the tuple is gone.
- `_read_only` duplicated the public `created` flag with the sign flipped.
- `_new_id()` wrapped one call; `_frame()` wrapped one `encode_frame` call.
  Both are inlined where they were used.
- The demo had two `_text` helpers with two return types, in runs.py and
  lens.py; lens.py now imports the one in runs.py.

Telemetry. `stream_span` took an `attributes` argument that no caller
passed, and the module's own rule forbids the attributes a stream span could
carry. The parameter is gone and the docstring says why.

The design's row for deps.py described the removed slot and now
describes where support lives and why.
The setting's description said "at most 86400" and the configuration
table listed `<= 86400` under Validation, but the model carried only
`gt=0`: `RedisSettings(stream_max_run=90000)` built fine and was refused
only when `.streams()` ran `check_stream_settings()`. Every other bound in
that table is a pydantic constraint a reader can trust from the Field.

A limit on one field belongs on the field. `stream_max_run` now has
`le=86_400`, with the reason beside it: Redis keeps a stream's idempotency
keys for at most a day, and that window must cover a run's whole life. The
setup check loses the branch and keeps only the rules that compare two
settings, which is what it exists for. The unit test asks `get_settings()`
to refuse the value, so the bound holds for an application that never
enables streams.
…ream_done_ttl

D-3: the guide told applications that allow one run at a time to copy the
demo's claim logic, which inferred "this run ended" from the stream's TTL.
That worked only while a finished run's TTL was below a running one's, so
the demo had a startup check forbidding settings the SDK allows, a ten-second
grace for a claim whose stream did not exist yet, and a read of the private
key layout. The SDK can answer the question itself.

- `StreamBackend.finished(stream_id, *, scope)` returns True once the stream
  holds its final entry, False while the run goes on, None when there is no
  such stream. It reads the tail `stream_replay_page` entries at a time,
  because a producer that missed a cancel keeps appending after the end;
  the last entry alone would say the run was live.
- The end sets the stream's TTL to `stream_done_ttl` with a plain EXPIRE.
  The `LT` that made ending only ever shorten a run existed for the demo's
  TTL heuristic; with that gone, a finished run simply lives
  `stream_done_ttl` from its last end, which is what the setting's name
  says. A second end adds no entry and sets the same lifetime again.
- The demo opens the run first and then claims, so a claim always names a
  run `finished()` can inspect; a refused second run is cancelled. The
  startup check, the grace period and the key rebuild are gone. The guide's
  "One run at a time" shows the same pattern, and the two topology tests
  that pinned the LT rule now pin the new one.

D-1: `aclose()`, the lifespan comment and the guide said live readers close
at shutdown. They do not: an ASGI server runs the lifespan shutdown after
open responses end, so under uvicorn a stop waits for readers unless
`--timeout-graceful-shutdown` is set. A new "Shutdown" section says so and
gives both deploy outcomes - `cancelled` after a graceful stop,
`producer_lost` after a kill - and `aclose()`'s docstring stops claiming
what it cannot do.

D-6: the guide and README now say that redis-py 7.2.0 is the oldest release
that imports and that CI tests 8.0.1 and 8.1.0, instead of leaving the floor
to be read as a tested range.

D-7: a third of the guide was four agent-SDK recipes pinned to SDK versions,
duplicating the apps in examples/agent_sdks/ that nothing tests. The guide
keeps "Rules for every SDK" and points at the apps; the apps' docstrings no
longer cite guide sections that are gone.

The design document records the TTL change and the new method; the plan
marks the four decisions done.
@codecov-commenter

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.69%. Comparing base (fd7f483) to head (fca0778).

Additional details and impacted files
@@                      Coverage Diff                      @@
##           feature/resumable-streams     #106      +/-   ##
=============================================================
+ Coverage                      96.35%   96.69%   +0.34%     
=============================================================
  Files                             17       18       +1     
  Lines                           3536     3542       +6     
=============================================================
+ Hits                            3407     3425      +18     
+ Misses                           129      117      -12     
Flag Coverage Δ
integration 80.71% <91.76%> (+0.54%) ⬆️
unit 85.34% <61.17%> (+0.95%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@tishun
tishun merged commit 0efe121 into feature/resumable-streams Nov 11, 2026
27 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.

2 participants