pytest-stream-lifecycle 0.1.0a1__tar.gz

pytest_stream_lifecycle-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+permissions:
+  contents: read
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}-${{ github.event_name == 'workflow_dispatch' && github.run_id || 'standard' }}
+  cancel-in-progress: true
+jobs:
+  tests:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ['3.11', '3.14']
+        dependencies: [latest]
+        include:
+          - os: ubuntu-latest
+            python: '3.11'
+            dependencies: minimum
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e ".[dev]"
+      - if: matrix.dependencies == 'minimum'
+        run: python -m pip install pytest==8.0.0 uvicorn==0.30.0 httpx==0.27.0 httpx-sse==0.4.0
+      - run: python -m pytest -q
+  quality:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: '3.12'
+      - run: python -m pip install -e '.[dev]'
+      - run: python -m ruff check .
+      - run: python -m ruff format --check .
+      - run: python -m build
+      - run: python -m twine check dist/*

pytest_stream_lifecycle-0.1.0a1/.github/workflows/release.yml

@@ -0,0 +1,152 @@
+name: Release preparation
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Check only, publish to TestPyPI, or publish to PyPI"
+        type: choice
+        options:
+          - check
+          - testpypi
+          - pypi
+        default: check
+        required: true
+
+permissions:
+  contents: read
+
+# Distinct from the reusable CI workflow's concurrency group. Do not cancel
+# a release while a build or publication is in progress.
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: '3.12'
+      - name: Validate target and publication ref
+        env:
+          RELEASE_TARGET: ${{ inputs.target }}
+          RELEASE_REPOSITORY: ${{ github.repository }}
+          RELEASE_REF: ${{ github.ref }}
+          RELEASE_SHA: ${{ github.sha }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          case "$RELEASE_TARGET" in
+            check) exit 0 ;;
+            testpypi|pypi) ;;
+            *) echo 'Invalid release target' >&2; exit 1 ;;
+          esac
+          if [[ "$RELEASE_REPOSITORY" != 'shenxi200-eng/pytest-stream-lifecycle' ]]; then
+            echo 'Publication is restricted to the canonical repository' >&2
+            exit 1
+          fi
+          version="$(python -c 'import pathlib, tomllib; print(tomllib.loads(pathlib.Path("pyproject.toml").read_text(encoding="utf-8"))["project"]["version"])')"
+          if [[ "$RELEASE_REF" != "refs/tags/v${version}" ]]; then
+            echo 'Publication requires the exact v{project.version} tag' >&2
+            exit 1
+          fi
+          git fetch --no-tags origin '+refs/heads/main:refs/remotes/origin/main'
+          if ! git merge-base --is-ancestor "$RELEASE_SHA" refs/remotes/origin/main; then
+            echo 'The tagged commit must be an ancestor of origin/main' >&2
+            exit 1
+          fi
+
+  tests:
+    needs: validate
+    permissions:
+      contents: read
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    needs: [validate, tests]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: '3.12'
+      - name: Build isolated distributions and check metadata
+        shell: bash
+        run: |
+          set -euo pipefail
+          python -m pip install build twine
+          dist_dir="$(mktemp -d "$RUNNER_TEMP/release-dist.XXXXXX")"
+          echo "DIST_DIR=$dist_dir" >> "$GITHUB_ENV"
+          python -m build --outdir "$dist_dir"
+          python -m twine check --strict "$dist_dir"/*
+          shopt -s nullglob
+          wheels=("$dist_dir"/*.whl)
+          sdists=("$dist_dir"/*.tar.gz)
+          (( ${#wheels[@]} == 1 && ${#sdists[@]} == 1 )) || { echo 'Expected one wheel and one sdist' >&2; exit 1; }
+          sha256sum "${wheels[0]}" "${sdists[0]}"
+      - name: Test the built wheel in a fresh virtual environment
+        env:
+          PYTHONPATH: ''
+        shell: bash
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          wheels=("$DIST_DIR"/*.whl)
+          (( ${#wheels[@]} == 1 ))
+          python -m venv "$RUNNER_TEMP/release-wheel-venv"
+          python="$RUNNER_TEMP/release-wheel-venv/bin/python"
+          "$python" -m pip install "${wheels[0]}[dev]"
+          "$python" -c 'import pathlib, sysconfig, pytest_stream_lifecycle as p; module = pathlib.Path(p.__file__).resolve(); site = pathlib.Path(sysconfig.get_paths()["purelib"]).resolve(); print(f"Wheel module: {module}"); assert module.is_relative_to(site), "Package was not imported from the wheel environment"'
+          "$python" -m pytest -q
+      - name: Upload verified distributions
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: release-distributions
+          path: ${{ env.DIST_DIR }}/*
+          if-no-files-found: error
+
+  publish-testpypi:
+    if: inputs.target == 'testpypi'
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: release-distributions
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          attestations: true
+
+  publish-pypi:
+    if: inputs.target == 'pypi'
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: release-distributions
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+        with:
+          repository-url: https://upload.pypi.org/legacy/
+          attestations: true

pytest_stream_lifecycle-0.1.0a1/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage*
+htmlcov/
+dist/
+build/
+*.egg-info/
+.env
+.env.*

pytest_stream_lifecycle-0.1.0a1/AGENTS.md

@@ -0,0 +1 @@
+Project: pytest-stream-lifecycle. Independent pytest plugin; Python 3.11+; asyncio only; real loopback HTTP/1.1 via Uvicorn. Use explicit lifecycle instrumentation, never infer cleanup from a closed client or cancel unrelated tasks. Preserve failure evidence. No external publishing except by primary session. No credentials, private paths, or unverified performance/novelty claims in repository.

pytest_stream_lifecycle-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0a1 — 2026-11-12
+
+First experimental alpha; the public API may change.
+
+- Real loopback HTTP/1.1 ASGI server fixture on the test's asyncio event loop.
+- Bounded SSE and line readers, including POST requests and explicit disconnects.
+- Lifecycle observations requiring explicit acknowledgement after cleanup.
+- Buffering, detached-upstream and repeated-session examples.
+- Failure diagnostics preserve primary errors and nested cleanup exceptions.
+- Cross-platform regression tests for Linux, macOS and Windows.
+
+Limits: asyncio and explicitly instrumented resources only. Client closure is
+not proof of upstream cleanup, and a local marker does not prove remote work or
+billing stopped. Event-loop-blocking or cancellation-resistant apps need process
+isolation for a hard stop.

pytest_stream_lifecycle-0.1.0a1/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+Start with a reproducible failure and a bounded change. Include a regression
+case that fails without the fix and passes with it. Do not replace real-network
+coverage with mocks for network lifecycle behavior.
+
+```sh
+python -m pip install -e '.[dev]'
+python -m pytest -q
+python -m ruff check .
+python -m ruff format --check .
+python -m build
+python -m twine check dist/*
+```
+
+AI-assisted contributions are welcome. Disclose material AI assistance, verify
+all code and references, and never present generated test results as observed
+runs. Keep credentials, private logs, and customer traffic out of issues and
+fixtures. Synthetic applications should be small and run without remote APIs.
+
+The public API is experimental. Discuss major scope expansion before building
+it; HTTP/2, WebSockets, model evaluation, and general process supervision are
+outside the initial scope.

pytest_stream_lifecycle-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shenxi200-eng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytest_stream_lifecycle-0.1.0a1/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.5
+Name: pytest-stream-lifecycle
+Version: 0.1.0a1
+Summary: Real-network streaming and explicit cleanup assertions for ASGI tests
+Project-URL: Documentation, https://github.com/shenxi200-eng/pytest-stream-lifecycle/blob/main/docs/api.md
+Project-URL: Source, https://github.com/shenxi200-eng/pytest-stream-lifecycle
+Project-URL: Issues, https://github.com/shenxi200-eng/pytest-stream-lifecycle/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asgi,pytest,sse,streaming,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Requires-Dist: httpx-sse<0.5,>=0.4
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pytest<10,>=8
+Requires-Dist: uvicorn<1,>=0.30
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: fastapi; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: sse-starlette; extra == 'dev'
+Requires-Dist: starlette; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pytest-stream-lifecycle
+
+Test streaming delivery and disconnect cleanup over real loopback HTTP.
+
+**Experimental alpha. Python 3.11+, asyncio.**
+No GPU, model API credentials, or external service is needed.
+
+## What it catches
+
+A final response-body assertion can pass even when every token was buffered.
+Closing a client can also leave a producer or upstream task running. This plugin
+provides:
+
+- `stream_server`: an ASGI app served by Uvicorn on a retained local socket.
+- `server.sse()` / `server.lines()`: bounded incremental reads over real HTTP/1.1.
+- `stream_probe`: explicit resource observations and cleanup acknowledgements.
+
+It is not a load tester, LLM evaluator, SSE parser, or general leak detector.
+The SSE parser is [httpx-sse](https://github.com/florimondmanca/httpx-sse).
+
+## Install
+
+Install the experimental alpha in your test environment:
+
+```sh
+python -m pip install pytest-stream-lifecycle==0.1.0a1
+```
+
+To install the current source instead:
+
+```sh
+python -m pip install 'git+https://github.com/shenxi200-eng/pytest-stream-lifecycle.git'
+```
+
+Maintainers can follow the [release checklist](https://github.com/shenxi200-eng/pytest-stream-lifecycle/blob/main/docs/releasing.md).
+
+For the example below, also install `fastapi` and `sse-starlette`. These are
+example/development dependencies, not plugin runtime requirements. Installation
+registers the pytest fixtures automatically; pytest-asyncio is not required.
+
+## Test delivery, then disconnect
+
+Save as `test_stream.py` and run `python -m pytest -q test_stream.py`:
+
+```python
+import asyncio
+
+from fastapi import FastAPI
+from sse_starlette.sse import EventSourceResponse
+
+
+def test_disconnect(stream_server, stream_probe):
+    async def scenario():
+        app = FastAPI()
+        release = asyncio.Event()
+
+        async def tokens():
+            with stream_probe.track("producer") as observed:
+                try:
+                    yield {"event": "token", "data": "first"}
+                    await release.wait()
+                    yield {"event": "token", "data": "second"}
+                finally:
+                    # This synthetic producer owns no external resource.
+                    # In real code, await cleanup BEFORE marking it closed.
+                    observed.mark_closed()
+
+        @app.get("/events")
+        async def events():
+            # Listens for disconnects even while tokens() is waiting.
+            return EventSourceResponse(tokens())
+
+        async with stream_server(app) as server:
+            async with server.sse("/events") as stream:
+                assert (await stream.next()).data == "first"
+                stream_probe.assert_active("producer")
+            # Assert while the server is STILL RUNNING: its shutdown must
+            # not hide an application that ignores client disconnects.
+            await stream_probe.wait_closed("producer", timeout=2)
+            assert not release.is_set()
+
+    asyncio.run(scenario())
+```
+
+The first event must arrive before the release gate opens. Exiting the stream
+context disconnects the client; it does **not** assert server cleanup. The
+separate probe assertion checks that an observed producer exited and explicitly
+acknowledged cleanup without a non-cancellation error.
+
+For a real upstream, instrument its lifetime separately. Call `mark_closed()`
+only after the cleanup you intend to test has completed successfully. Leaving
+`track()` without that acknowledgement fails `wait_closed()`, even if the task
+has already exited. The marker is application-supplied evidence, not an
+independent guarantee that a remote provider stopped work or billing.
+
+## Executable comparisons
+
+```sh
+git clone https://github.com/shenxi200-eng/pytest-stream-lifecycle.git
+cd pytest-stream-lifecycle
+python -m venv .venv
+# Activate .venv using your shell's activation command.
+python -m pip install -e '.[dev]'
+python -m pytest examples/test_contracts.py -v
+python -m pytest -q
+```
+
+The examples compare a buffered implementation that passes a body-only test
+with a streaming contract that detects it. They also cover incremental delivery,
+20 sequential sessions, and a detached upstream that remains alive after the
+producer closes. Negative examples use `pytest.raises`: a passing test means
+the defect was **detected**, not that the intentionally broken app is correct.
+
+## Boundaries
+
+- Same-loop asyncio and loopback HTTP/1.1 only: not Trio, HTTP/2, TLS,
+  WebSockets, or browser/proxy emulation.
+- Resource observations are explicit. Unknown resources do not count as clean;
+  uninstrumented tasks are outside the probe's coverage.
+- Cleanup checks should run before server teardown. Server shutdown can itself
+  cancel request tasks and otherwise hide a broken disconnect handler.
+- An in-process server cannot forcibly kill code that blocks the event loop or
+  continually suppresses cancellation. Such apps need process isolation.
+- A local cleanup marker does not prove remote cancellation, GPU work cessation,
+  or a provider's billing state.
+
+See the [API guide](https://github.com/shenxi200-eng/pytest-stream-lifecycle/blob/main/docs/api.md), [design and related work](https://github.com/shenxi200-eng/pytest-stream-lifecycle/blob/main/docs/design.md), and
+[contribution guide](https://github.com/shenxi200-eng/pytest-stream-lifecycle/blob/main/CONTRIBUTING.md). Development uses AI-assisted implementation
+and review; generated code and claims must be checked rather than treated as
+verification evidence. AI-assisted contributions have the same testing and review
+requirements as other contributions.

pytest_stream_lifecycle-0.1.0a1/README.md

@@ -0,0 +1,131 @@
+# pytest-stream-lifecycle
+
+Test streaming delivery and disconnect cleanup over real loopback HTTP.
+
+**Experimental alpha. Python 3.11+, asyncio.**
+No GPU, model API credentials, or external service is needed.
+
+## What it catches
+
+A final response-body assertion can pass even when every token was buffered.
+Closing a client can also leave a producer or upstream task running. This plugin
+provides:
+
+- `stream_server`: an ASGI app served by Uvicorn on a retained local socket.
+- `server.sse()` / `server.lines()`: bounded incremental reads over real HTTP/1.1.
+- `stream_probe`: explicit resource observations and cleanup acknowledgements.
+
+It is not a load tester, LLM evaluator, SSE parser, or general leak detector.
+The SSE parser is [httpx-sse](https://github.com/florimondmanca/httpx-sse).
+
+## Install
+
+Install the experimental alpha in your test environment:
+
+```sh
+python -m pip install pytest-stream-lifecycle==0.1.0a1
+```
+
+To install the current source instead:
+
+```sh
+python -m pip install 'git+https://github.com/shenxi200-eng/pytest-stream-lifecycle.git'
+```
+
+Maintainers can follow the [release checklist](https://github.com/shenxi200-eng/pytest-stream-lifecycle/blob/main/docs/releasing.md).
+
+For the example below, also install `fastapi` and `sse-starlette`. These are
+example/development dependencies, not plugin runtime requirements. Installation
+registers the pytest fixtures automatically; pytest-asyncio is not required.
+
+## Test delivery, then disconnect
+
+Save as `test_stream.py` and run `python -m pytest -q test_stream.py`:
+
+```python
+import asyncio
+
+from fastapi import FastAPI
+from sse_starlette.sse import EventSourceResponse
+
+
+def test_disconnect(stream_server, stream_probe):
+    async def scenario():
+        app = FastAPI()
+        release = asyncio.Event()
+
+        async def tokens():
+            with stream_probe.track("producer") as observed:
+                try:
+                    yield {"event": "token", "data": "first"}
+                    await release.wait()
+                    yield {"event": "token", "data": "second"}
+                finally:
+                    # This synthetic producer owns no external resource.
+                    # In real code, await cleanup BEFORE marking it closed.
+                    observed.mark_closed()
+
+        @app.get("/events")
+        async def events():
+            # Listens for disconnects even while tokens() is waiting.
+            return EventSourceResponse(tokens())
+
+        async with stream_server(app) as server:
+            async with server.sse("/events") as stream:
+                assert (await stream.next()).data == "first"
+                stream_probe.assert_active("producer")
+            # Assert while the server is STILL RUNNING: its shutdown must
+            # not hide an application that ignores client disconnects.
+            await stream_probe.wait_closed("producer", timeout=2)
+            assert not release.is_set()
+
+    asyncio.run(scenario())
+```
+
+The first event must arrive before the release gate opens. Exiting the stream
+context disconnects the client; it does **not** assert server cleanup. The
+separate probe assertion checks that an observed producer exited and explicitly
+acknowledged cleanup without a non-cancellation error.
+
+For a real upstream, instrument its lifetime separately. Call `mark_closed()`
+only after the cleanup you intend to test has completed successfully. Leaving
+`track()` without that acknowledgement fails `wait_closed()`, even if the task
+has already exited. The marker is application-supplied evidence, not an
+independent guarantee that a remote provider stopped work or billing.
+
+## Executable comparisons
+
+```sh
+git clone https://github.com/shenxi200-eng/pytest-stream-lifecycle.git
+cd pytest-stream-lifecycle
+python -m venv .venv
+# Activate .venv using your shell's activation command.
+python -m pip install -e '.[dev]'
+python -m pytest examples/test_contracts.py -v
+python -m pytest -q
+```
+
+The examples compare a buffered implementation that passes a body-only test
+with a streaming contract that detects it. They also cover incremental delivery,
+20 sequential sessions, and a detached upstream that remains alive after the
+producer closes. Negative examples use `pytest.raises`: a passing test means
+the defect was **detected**, not that the intentionally broken app is correct.
+
+## Boundaries
+
+- Same-loop asyncio and loopback HTTP/1.1 only: not Trio, HTTP/2, TLS,
+  WebSockets, or browser/proxy emulation.
+- Resource observations are explicit. Unknown resources do not count as clean;
+  uninstrumented tasks are outside the probe's coverage.
+- Cleanup checks should run before server teardown. Server shutdown can itself
+  cancel request tasks and otherwise hide a broken disconnect handler.
+- An in-process server cannot forcibly kill code that blocks the event loop or
+  continually suppresses cancellation. Such apps need process isolation.
+- A local cleanup marker does not prove remote cancellation, GPU work cessation,
+  or a provider's billing state.
+
+See the [API guide](https://github.com/shenxi200-eng/pytest-stream-lifecycle/blob/main/docs/api.md), [design and related work](https://github.com/shenxi200-eng/pytest-stream-lifecycle/blob/main/docs/design.md), and
+[contribution guide](https://github.com/shenxi200-eng/pytest-stream-lifecycle/blob/main/CONTRIBUTING.md). Development uses AI-assisted implementation
+and review; generated code and claims must be checked rather than treated as
+verification evidence. AI-assisted contributions have the same testing and review
+requirements as other contributions.

pytest_stream_lifecycle-0.1.0a1/docs/api.md

@@ -0,0 +1,94 @@
+# API guide
+
+The pytest plugin exposes two function-scoped fixtures. Use them within one
+asyncio event loop per test, either through `asyncio.run()` or your own async
+pytest integration.
+
+## Server
+
+```python
+async with stream_server(app, startup_timeout=5.0, shutdown_timeout=5.0, lifespan="on") as server:
+    print(server.url)  # http://127.0.0.1:<ephemeral-port>
+```
+
+`stream_server` is the `live_server` factory, also exported for non-pytest use.
+It runs on the test's event loop, retains its port-zero socket, and does not
+install signal handlers or reconfigure global logging. `lifespan` accepts
+`"on"`, `"auto"`, or `"off"`; choose `"off"` for an app without lifespan support.
+Startup and shutdown failures raise `ServerError`. Deadlines require cooperative
+async code; they cannot preempt code that blocks the event loop.
+
+## Stream readers
+
+```python
+async with server.sse("/events", method="POST", json={"prompt": "hello"}) as stream:
+    event = await stream.next(timeout=2.0)
+    assert event.data
+
+async with server.lines("/jsonl", headers={"X-Test": "yes"}) as stream:
+    line = await stream.next()
+```
+
+- `sse()` yields a reader of `httpx_sse.ServerSentEvent` objects; `lines()` yields
+  strings, without decoding JSON or filtering empty lines.
+- `timeout=2.0` is the default for connection/response headers and each read.
+  `next(timeout=...)` overrides one read. It is not a whole-session deadline.
+  Timeouts must be positive and finite.
+- Paths must start with a single `/`; absolute URLs and `//host` paths are
+  rejected. Request options such as `json`, `params`, and `headers` are passed
+  to HTTPX. Environment proxy settings are ignored (`trust_env=False`). Redirects
+  are not followed by default; callers opting in to redirects are responsible
+  for the destination.
+- HTTP errors and invalid SSE content types fail the context entry. Read timeout,
+  read error, and EOF before a requested event/line raise `LifecycleError`.
+  EOF is an error for `next()`, not an end-of-stream assertion API.
+- A timed-out reader is closed, not reusable. Keep one reader context open for
+  multiple `next()` calls. Concurrent reads on the same reader are rejected.
+- `await stream.aclose()` is idempotent. Context exit also closes the reader.
+  Client closure is deliberately separate from server-side cleanup assertions.
+
+## Lifecycle probe
+
+```python
+with stream_probe.track("upstream") as observed:
+    try:
+        await use_resource()
+    finally:
+        await close_resource()
+        observed.mark_closed()
+
+await stream_probe.wait_closed("upstream", timeout=2.0)
+```
+
+`track(name)` is a synchronous context manager for instrumentation **inside async
+code**. Entering it records a distinct resource instance; multiple instances may
+share a label. Put the acknowledgement after successful cleanup, not unconditionally
+in an outer `finally`. A second cancellation can interrupt awaited cleanup.
+The probe neither shields cleanup nor cancels application tasks.
+
+| Operation | Meaning |
+| --- | --- |
+| `track(name)` | Record one resource lifetime; name must be a nonempty string. |
+| `observed.mark_closed()` | Acknowledge cleanup while the observation is still active. |
+| `assert_active(name)` | Require at least one currently active instance. |
+| `await wait_started(name, timeout=2.0)` | Wait for at least one observed instance; it may already have exited. |
+| `await wait_closed(*names, timeout=2.0)` | Require each label to have been observed, and all its observed instances to have exited with cleanup acknowledged and no non-cancellation error. |
+| `started_count(name)` | Number of entered instances for this label, including closed ones. |
+| `active_labels` | A `frozenset` of labels with currently active instances. |
+
+Unknown labels wait until observed or timeout; an empty `wait_closed()` call
+fails. An exited instance without acknowledgement or with a recorded error fails
+immediately. `CancelledError` and `GeneratorExit` propagate but are not recorded
+as cleanup failures by themselves; an acknowledgement is still required.
+Failures use `LifecycleError`, an `AssertionError` subclass.
+
+Observations are retained for the probe's lifetime, so an earlier failure is not
+forgotten when another instance with the same name closes successfully. A probe
+binds to its first running event loop and rejects reuse from another loop. It
+can be constructed outside that loop. `LifecycleProbe` is exported for use
+without pytest.
+
+A successful check describes instances observed **so far**, not resources that
+might start later. Synchronize application start points explicitly. Check both
+producer and upstream labels while the server is still running, before test
+teardown has a chance to cancel them.