Repository navigation
Review panel session - #106
Merged
tishun merged 7 commits intoNov 11, 2026
Merged
Conversation
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 Report✅ All modified and coverable lines are covered by tests. 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
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
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.
Apply the following improvements (read commit messages for details):