wred-lifespan 0.1.0__tar.gz

wred_lifespan-0.1.0/.gitignore

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

wred_lifespan-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Harrison Erd
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

wred_lifespan-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: wred-lifespan
+Version: 0.1.0
+Summary: ASGI startup and shutdown hooks for Wred
+Author-email: Harrison Erd <harrisonerd@gmail.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Dist: wred>=0.14,<0.15
+Requires-Dist: pytest>=8 ; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24 ; extra == "test"
+Requires-Dist: httpx>=0.27 ; extra == "test"
+Requires-Dist: uvicorn>=0.30,<1 ; extra == "test"
+Provides-Extra: test
+
+# wred-lifespan
+
+Async startup and shutdown hooks for Wred, through one function:
+`lifespan_application`. Requires Python 3.11+, Wred 0.14, and an asyncio ASGI
+server such as Uvicorn.
+
+Install from PyPI:
+
+```sh
+python -m pip install wred-lifespan
+```
+
+```python
+from wred import App
+from wred_lifespan import lifespan_application
+
+api = App()
+
+
+async def startup():
+    print("Starting up")
+
+
+async def shutdown():
+    print("Shutting down")
+
+
+@api.route("/")
+async def hello(request):
+    return {"hello": "world"}
+
+
+app = lifespan_application(api, on_start=startup, on_shutdown=shutdown)
+```
+
+Save the example as `app.py`. Register routes on `api` and serve `app`:
+
+```sh
+python -m pip install uvicorn
+uvicorn app:app --lifespan on --workers 2
+```
+
+## Configuration
+
+```python
+app = lifespan_application(
+    api,
+    on_start=[connect_database, warm_cache],
+    on_shutdown=[close_cache, close_database],
+    hook_timeout=10.0,
+)
+```
+
+Both hook arguments are optional and accept one async callable or an iterable
+of async callables. Each takes no arguments. Hooks run sequentially in the
+supplied order; place dependent resource cleanup before its dependencies.
+Iterables are captured when wrapping the app and can be reused across lifespans.
+Use `functools.partial` on an async function to bind arguments.
+
+`hook_timeout` defaults to **30 seconds per hook** and must be positive and
+finite. Each cleanup hook gets a fresh timeout, so a hung hook cannot consume
+the next hook's budget. For N shutdown hooks, allow at least N × `hook_timeout`
+for cleanup in your process supervisor's termination grace period, in addition
+to time for draining requests. Startup failure can take the startup hooks' time
+plus the entire cleanup budget before it is reported.
+
+Synchronous hooks are rejected during configuration. Hooks must use
+nonblocking async operations and cooperate with cancellation. Python's
+[`asyncio.timeout`](https://docs.python.org/3.11/library/asyncio-task.html#asyncio.timeout)
+cannot forcibly stop blocking code or a coroutine that indefinitely suppresses
+cancellation. Set timeouts in external clients too. Moving blocking work to a
+thread does not make that thread cancellable.
+
+## Cleanup and failure behavior
+
+- Startup completion is sent only after every startup hook finishes.
+- Startup exception or timeout stops subsequent startup hooks and runs **all
+  shutdown hooks** as rollback before sending `lifespan.startup.failed`.
+- Shutdown attempts every hook even if an earlier hook fails or times out.
+  It sends `lifespan.shutdown.failed` if any cleanup failed, including all
+  ordinary errors in the diagnostic; otherwise it sends completion.
+- Cancellation, a broken lifespan connection, or an unexpected message after
+  startup begins also triggers cleanup. The original exception propagates;
+  secondary cleanup errors are logged through the `wred_lifespan` logger.
+- Cancellation during cleanup interrupts that hook; remaining hooks are still
+  attempted before cancellation propagates. Interrupted hooks are not retried.
+  Process-exit exceptions and forced process termination can prevent cleanup.
+
+Startup and shutdown callbacks are independent, so the wrapper cannot infer
+which acquisitions correspond to which cleanup. Cleanup hooks must tolerate
+missing or partially initialized resources. For example, with HTTPX installed:
+
+```python
+import httpx
+
+client = None
+
+
+async def startup():
+    global client
+    client = httpx.AsyncClient(timeout=5.0)
+    # If this fails, shutdown still closes the client.
+    response = await client.get("https://example.com")
+    response.raise_for_status()
+
+
+async def shutdown():
+    global client
+    if client is not None:
+        await client.aclose()
+        client = None
+```
+
+Assign acquired resources before performing later operations that can fail.
+An acquisition that fails before returning a resource must clean up its own
+partial work. Prefer separate shutdown hooks for independent resources so a
+failure closing one cannot skip closing another.
+
+## Deployment
+
+Hooks run once per lifespan connection, usually once per worker, in the event
+loop serving that worker. They do not run at import or per request. Hook-owned
+resources must belong to the correct worker/event loop; the wrapper does not
+provide shared application state or cluster-wide coordination. Registering a
+scheduled job in startup therefore starts one job per worker.
+
+Wrap the application once. The wrapper owns the ASGI lifespan protocol and does
+not compose another application's existing lifespan handler. HTTP and other
+scopes are forwarded unchanged. The earlier `on_start` and `on_shutdown`
+decorator exports have been removed; those names now appear only as keyword
+arguments to `lifespan_application`.
+
+The Linux integration test runs two real Uvicorn workers, concurrent HTTP
+clients, worker replacement, SIGHUP restarts, and SIGTERM shutdown. It checks
+that requests only see initialized resources and every gracefully stopped
+worker executes cleanup. Uvicorn may close accepted idle connections during
+restart; the test records these transport disconnects separately and permits
+them only during restart. For deployments requiring uninterrupted requests,
+drain traffic at the load balancer before terminating instances. Lifespan hooks
+alone cannot guarantee zero downtime or cleanup after SIGKILL.
+
+## Development
+
+From a source checkout:
+
+```sh
+python -m pip install -e '.[test]'
+python -m pytest -s
+python -m pytest -m 'not integration'  # fast protocol tests only
+python -m build
+python benchmarks/request_overhead.py
+```
+
+The benchmark compares raw Wred with the wrapper using in-process HTTP ASGI
+calls. It measures wrapper overhead, not network throughput or production
+capacity. The worker test is a finite deployment check, not a long-running soak.
+

wred_lifespan-0.1.0/README.md

@@ -0,0 +1,156 @@
+# wred-lifespan
+
+Async startup and shutdown hooks for Wred, through one function:
+`lifespan_application`. Requires Python 3.11+, Wred 0.14, and an asyncio ASGI
+server such as Uvicorn.
+
+Install from PyPI:
+
+```sh
+python -m pip install wred-lifespan
+```
+
+```python
+from wred import App
+from wred_lifespan import lifespan_application
+
+api = App()
+
+
+async def startup():
+    print("Starting up")
+
+
+async def shutdown():
+    print("Shutting down")
+
+
+@api.route("/")
+async def hello(request):
+    return {"hello": "world"}
+
+
+app = lifespan_application(api, on_start=startup, on_shutdown=shutdown)
+```
+
+Save the example as `app.py`. Register routes on `api` and serve `app`:
+
+```sh
+python -m pip install uvicorn
+uvicorn app:app --lifespan on --workers 2
+```
+
+## Configuration
+
+```python
+app = lifespan_application(
+    api,
+    on_start=[connect_database, warm_cache],
+    on_shutdown=[close_cache, close_database],
+    hook_timeout=10.0,
+)
+```
+
+Both hook arguments are optional and accept one async callable or an iterable
+of async callables. Each takes no arguments. Hooks run sequentially in the
+supplied order; place dependent resource cleanup before its dependencies.
+Iterables are captured when wrapping the app and can be reused across lifespans.
+Use `functools.partial` on an async function to bind arguments.
+
+`hook_timeout` defaults to **30 seconds per hook** and must be positive and
+finite. Each cleanup hook gets a fresh timeout, so a hung hook cannot consume
+the next hook's budget. For N shutdown hooks, allow at least N × `hook_timeout`
+for cleanup in your process supervisor's termination grace period, in addition
+to time for draining requests. Startup failure can take the startup hooks' time
+plus the entire cleanup budget before it is reported.
+
+Synchronous hooks are rejected during configuration. Hooks must use
+nonblocking async operations and cooperate with cancellation. Python's
+[`asyncio.timeout`](https://docs.python.org/3.11/library/asyncio-task.html#asyncio.timeout)
+cannot forcibly stop blocking code or a coroutine that indefinitely suppresses
+cancellation. Set timeouts in external clients too. Moving blocking work to a
+thread does not make that thread cancellable.
+
+## Cleanup and failure behavior
+
+- Startup completion is sent only after every startup hook finishes.
+- Startup exception or timeout stops subsequent startup hooks and runs **all
+  shutdown hooks** as rollback before sending `lifespan.startup.failed`.
+- Shutdown attempts every hook even if an earlier hook fails or times out.
+  It sends `lifespan.shutdown.failed` if any cleanup failed, including all
+  ordinary errors in the diagnostic; otherwise it sends completion.
+- Cancellation, a broken lifespan connection, or an unexpected message after
+  startup begins also triggers cleanup. The original exception propagates;
+  secondary cleanup errors are logged through the `wred_lifespan` logger.
+- Cancellation during cleanup interrupts that hook; remaining hooks are still
+  attempted before cancellation propagates. Interrupted hooks are not retried.
+  Process-exit exceptions and forced process termination can prevent cleanup.
+
+Startup and shutdown callbacks are independent, so the wrapper cannot infer
+which acquisitions correspond to which cleanup. Cleanup hooks must tolerate
+missing or partially initialized resources. For example, with HTTPX installed:
+
+```python
+import httpx
+
+client = None
+
+
+async def startup():
+    global client
+    client = httpx.AsyncClient(timeout=5.0)
+    # If this fails, shutdown still closes the client.
+    response = await client.get("https://example.com")
+    response.raise_for_status()
+
+
+async def shutdown():
+    global client
+    if client is not None:
+        await client.aclose()
+        client = None
+```
+
+Assign acquired resources before performing later operations that can fail.
+An acquisition that fails before returning a resource must clean up its own
+partial work. Prefer separate shutdown hooks for independent resources so a
+failure closing one cannot skip closing another.
+
+## Deployment
+
+Hooks run once per lifespan connection, usually once per worker, in the event
+loop serving that worker. They do not run at import or per request. Hook-owned
+resources must belong to the correct worker/event loop; the wrapper does not
+provide shared application state or cluster-wide coordination. Registering a
+scheduled job in startup therefore starts one job per worker.
+
+Wrap the application once. The wrapper owns the ASGI lifespan protocol and does
+not compose another application's existing lifespan handler. HTTP and other
+scopes are forwarded unchanged. The earlier `on_start` and `on_shutdown`
+decorator exports have been removed; those names now appear only as keyword
+arguments to `lifespan_application`.
+
+The Linux integration test runs two real Uvicorn workers, concurrent HTTP
+clients, worker replacement, SIGHUP restarts, and SIGTERM shutdown. It checks
+that requests only see initialized resources and every gracefully stopped
+worker executes cleanup. Uvicorn may close accepted idle connections during
+restart; the test records these transport disconnects separately and permits
+them only during restart. For deployments requiring uninterrupted requests,
+drain traffic at the load balancer before terminating instances. Lifespan hooks
+alone cannot guarantee zero downtime or cleanup after SIGKILL.
+
+## Development
+
+From a source checkout:
+
+```sh
+python -m pip install -e '.[test]'
+python -m pytest -s
+python -m pytest -m 'not integration'  # fast protocol tests only
+python -m build
+python benchmarks/request_overhead.py
+```
+
+The benchmark compares raw Wred with the wrapper using in-process HTTP ASGI
+calls. It measures wrapper overhead, not network throughput or production
+capacity. The worker test is a finite deployment check, not a long-running soak.

wred_lifespan-0.1.0/benchmarks/request_overhead.py

@@ -0,0 +1,57 @@
+"""In-process request overhead; excludes network, server, and concurrency costs."""
+
+import argparse
+import asyncio
+import statistics
+import time
+
+from wred import App
+
+from wred_lifespan import lifespan_application
+
+
+async def main(requests, rounds):
+    api = App()
+
+    @api.route("/")
+    async def hello(request):
+        return {"hello": "world"}
+
+    scope = {"type": "http", "method": "GET", "path": "/"}
+
+    async def receive():
+        return {"type": "http.request", "body": b""}
+
+    async def send(message):
+        pass
+
+    wrapped = lifespan_application(api)
+    samples = {"wred": [], "wrapped": []}
+    for turn in range(rounds + 1):
+        order = [("wred", api), ("wrapped", wrapped)]
+        if turn % 2:
+            order.reverse()
+        for name, app in order:
+            start = time.perf_counter()
+            for _ in range(requests):
+                await app(scope, receive, send)
+            elapsed = time.perf_counter() - start
+            if turn:  # Discard warmup; alternate order to reduce timing bias.
+                samples[name].append(elapsed / requests * 1_000_000)
+    raw, wrapped_time = (statistics.median(samples[name]) for name in samples)
+    print(
+        f"{requests:,} requests/round; {rounds} measured rounds; median microseconds/request"
+    )
+    print(
+        f"Wred: {raw:.3f}; wrapped: {wrapped_time:.3f}; added: {wrapped_time - raw:.3f}"
+    )
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--requests", type=int, default=100_000)
+    parser.add_argument("--rounds", type=int, default=7)
+    args = parser.parse_args()
+    if args.requests < 1 or args.rounds < 1:
+        parser.error("requests and rounds must be positive")
+    asyncio.run(main(args.requests, args.rounds))

wred_lifespan-0.1.0/examples/wrapped.py

@@ -0,0 +1,23 @@
+"""Run with: uvicorn examples.wrapped:app --lifespan on"""
+
+from wred import App
+
+from wred_lifespan import lifespan_application
+
+api = App()
+
+
+async def startup():
+    print("Starting up")
+
+
+async def shutdown():
+    print("Shutting down")
+
+
+@api.route("/")
+async def hello(request):
+    return {"hello": "world"}
+
+
+app = lifespan_application(api, on_start=startup, on_shutdown=shutdown)

wred_lifespan-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["flit_core>=3.12,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "wred-lifespan"
+version = "0.1.0"
+description = "ASGI startup and shutdown hooks for Wred"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [{ name = "Harrison Erd", email = "harrisonerd@gmail.com" }]
+dependencies = ["wred>=0.14,<0.15"]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.24", "httpx>=0.27", "uvicorn>=0.30,<1"]
+
+[tool.flit.sdist]
+include = ["tests/", "examples/", "benchmarks/"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+markers = ["integration: real worker processes and network sockets"]
+
+[tool.ruff]
+target-version = "py311"

wred_lifespan-0.1.0/tests/test_lifespan.py

@@ -0,0 +1,320 @@
+import asyncio
+
+import httpx
+import pytest
+from wred import App
+
+from wred_lifespan import lifespan_application
+
+
+async def exchange(app, events=("lifespan.startup", "lifespan.shutdown")):
+    """Drive the ASGI protocol and return messages sent by the application."""
+    incoming = asyncio.Queue()
+    outgoing = []
+    for event in events:
+        incoming.put_nowait({"type": event})
+
+    async def send(message):
+        outgoing.append(message)
+
+    async with asyncio.timeout(2):
+        await app({"type": "lifespan"}, incoming.get, send)
+    return outgoing
+
+
+async def test_wred_serves_requests_between_completed_hooks():
+    api = App()
+    events = []
+
+    async def startup():
+        await asyncio.sleep(0)
+        events.append("ready")
+
+    async def shutdown():
+        await asyncio.sleep(0)
+        events.append("closed")
+
+    @api.route("/")
+    async def hello(request):
+        return {"hello": "world", "ready": events == ["ready"]}
+
+    app = lifespan_application(api, on_start=startup, on_shutdown=shutdown)
+
+    assert events == []
+    incoming, outgoing = asyncio.Queue(), asyncio.Queue()
+    async with asyncio.timeout(2), asyncio.TaskGroup() as tasks:
+        tasks.create_task(app({"type": "lifespan"}, incoming.get, outgoing.put))
+        await incoming.put({"type": "lifespan.startup"})
+        assert await outgoing.get() == {"type": "lifespan.startup.complete"}
+        assert events == ["ready"]
+        async with httpx.AsyncClient(
+            transport=httpx.ASGITransport(app), base_url="http://test"
+        ) as client:
+            for _ in range(2):
+                response = await client.get("/")
+                assert response.status_code == 200
+                assert response.json() == {"hello": "world", "ready": True}
+        assert events == ["ready"]
+        await incoming.put({"type": "lifespan.shutdown"})
+        assert await outgoing.get() == {"type": "lifespan.shutdown.complete"}
+        assert events == ["ready", "closed"]
+
+
+async def test_other_scopes_and_downstream_errors_pass_through():
+    scope = {"type": "websocket", "state": {"token": "hello"}}
+    incoming = asyncio.Queue()
+    incoming.put_nowait({"type": "websocket.connect"})
+    outgoing = []
+    failure = RuntimeError("downstream error")
+
+    async def downstream(scope, receive, send):
+        assert await receive() == {"type": "websocket.connect"}
+        await send({"type": "websocket.send", "text": scope["state"]["token"]})
+        scope["state"]["visited"] = True
+        raise failure
+
+    async def unexpected():
+        pytest.fail("Lifespan callbacks must not run for WebSocket scopes")
+
+    async def send(message):
+        outgoing.append(message)
+
+    app = lifespan_application(downstream, on_start=unexpected, on_shutdown=unexpected)
+    async with asyncio.timeout(2):
+        with pytest.raises(RuntimeError) as caught:
+            await app(scope, incoming.get, send)
+    assert caught.value is failure
+    assert scope["state"]["visited"] is True
+    assert outgoing == [{"type": "websocket.send", "text": "hello"}]
+
+
+@pytest.mark.parametrize("transport", ["receive", "send"])
+async def test_transport_errors_propagate(transport):
+    calls = []
+    failure = OSError("connection lost")
+
+    async def receive():
+        if transport == "receive":
+            raise failure
+        return {"type": "lifespan.startup"}
+
+    async def send(message):
+        calls.append(message)
+        raise failure
+
+    with pytest.raises(OSError) as caught:
+        await lifespan_application(App())({"type": "lifespan"}, receive, send)
+    assert caught.value is failure
+    assert calls == (
+        [{"type": "lifespan.startup.complete"}] if transport == "send" else []
+    )
+
+
+@pytest.mark.parametrize(
+    "events",
+    [
+        ["lifespan.shutdown"],
+        ["lifespan.startup", "lifespan.startup"],
+        ["unknown"],
+    ],
+)
+async def test_out_of_order_messages_are_rejected(events):
+    with pytest.raises(RuntimeError, match="Expected lifespan\\."):
+        await exchange(lifespan_application(App()), events)
+
+
+@pytest.mark.parametrize("option", ["on_start", "on_shutdown"])
+@pytest.mark.parametrize("invalid", [lambda: None, [None], [lambda: None]])
+def test_non_async_hooks_are_rejected_at_configuration(option, invalid):
+    with pytest.raises(TypeError, match="hooks must be async"):
+        lifespan_application(App(), **{option: invalid})
+
+
+@pytest.mark.parametrize("timeout", [0, -1, float("nan"), float("inf"), None, True])
+def test_timeouts_must_be_positive_and_finite(timeout):
+    with pytest.raises(ValueError, match="positive finite"):
+        lifespan_application(App(), hook_timeout=timeout)
+
+
+@pytest.mark.parametrize("option", [None, "on_start", "on_shutdown"])
+async def test_optional_hooks_and_iterators_are_reusable_per_connection(option):
+    events = []
+
+    class Hook:
+        async def __call__(self):
+            events.append("called")
+
+    options = {} if option is None else {option: iter([Hook()])}
+    app = lifespan_application(App(), **options)
+    for _ in range(2):
+        assert await exchange(app) == [
+            {"type": "lifespan.startup.complete"},
+            {"type": "lifespan.shutdown.complete"},
+        ]
+    assert events == ([] if option is None else ["called", "called"])
+
+
+@pytest.mark.parametrize("phase", ["startup", "shutdown"])
+@pytest.mark.parametrize("suppress", [False, True])
+async def test_timeouts_cancel_hooks_and_allow_remaining_cleanup(phase, suppress):
+    events = []
+
+    async def hang():
+        try:
+            await asyncio.Event().wait()
+        except asyncio.CancelledError:
+            if not suppress:
+                raise
+        finally:
+            events.append("cancelled")
+
+    async def cleanup():
+        events.append("cleaned")
+
+    async def skipped():
+        events.append("unexpected")
+
+    app = lifespan_application(
+        App(),
+        on_start=[hang, skipped] if phase == "startup" else None,
+        on_shutdown=cleanup if phase == "startup" else [hang, cleanup],
+        hook_timeout=0.01,
+    )
+    messages = await exchange(app)
+    assert events == ["cancelled", "cleaned"]
+    assert messages[-1]["type"] == f"lifespan.{phase}.failed"
+    assert "TimeoutError" in messages[-1]["message"]
+    assert len(messages) == (1 if phase == "startup" else 2)
+
+
+@pytest.mark.parametrize("phase", ["startup", "running", "shutdown"])
+async def test_external_cancellation_cleans_up_then_propagates(phase):
+    incoming, outgoing = asyncio.Queue(), asyncio.Queue()
+    entered = asyncio.Event()
+    events = []
+    incoming.put_nowait({"type": "lifespan.startup"})
+    if phase == "shutdown":
+        incoming.put_nowait({"type": "lifespan.shutdown"})
+
+    async def startup():
+        if phase == "startup":
+            entered.set()
+            await asyncio.Event().wait()
+
+    async def first_cleanup():
+        events.append("first")
+        if phase == "shutdown":
+            entered.set()
+            await asyncio.Event().wait()
+
+    async def last_cleanup():
+        events.append("last")
+
+    app = lifespan_application(
+        App(), on_start=startup, on_shutdown=[first_cleanup, last_cleanup]
+    )
+    async with asyncio.timeout(2), asyncio.TaskGroup() as tasks:
+        task = tasks.create_task(app({"type": "lifespan"}, incoming.get, outgoing.put))
+        if phase == "running":
+            assert await outgoing.get() == {"type": "lifespan.startup.complete"}
+        else:
+            await entered.wait()
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+    assert events == ["first", "last"]
+    remaining = []
+    while not outgoing.empty():
+        remaining.append(outgoing.get_nowait())
+    assert remaining == (
+        [{"type": "lifespan.startup.complete"}] if phase == "shutdown" else []
+    )
+
+
+@pytest.mark.parametrize(
+    "broken_at", ["startup_ack", "shutdown_receive", "shutdown_ack"]
+)
+async def test_broken_connection_cleans_up_exactly_once(broken_at):
+    events = []
+    received = 0
+    failure = OSError("connection lost")
+
+    async def cleanup():
+        events.append("closed")
+
+    async def receive():
+        nonlocal received
+        received += 1
+        if received == 1:
+            return {"type": "lifespan.startup"}
+        if broken_at == "shutdown_receive":
+            raise failure
+        return {"type": "lifespan.shutdown"}
+
+    async def send(message):
+        if (
+            broken_at == "startup_ack"
+            and message["type"] == "lifespan.startup.complete"
+        ) or (
+            broken_at == "shutdown_ack"
+            and message["type"] == "lifespan.shutdown.complete"
+        ):
+            raise failure
+
+    with pytest.raises(OSError) as caught:
+        await lifespan_application(App(), on_shutdown=cleanup)(
+            {"type": "lifespan"}, receive, send
+        )
+    assert caught.value is failure
+    assert events == ["closed"]
+
+
+async def test_shutdown_attempts_remaining_hooks_and_reports_all_errors():
+    events = []
+
+    async def first():
+        events.append("first")
+        raise ValueError("first cleanup failed")
+
+    async def second():
+        events.append("second")
+        raise RuntimeError("second cleanup failed")
+
+    async def last():
+        events.append("last")
+
+    messages = await exchange(
+        lifespan_application(App(), on_shutdown=[first, second, last])
+    )
+    assert events == ["first", "second", "last"]
+    assert messages[-1]["type"] == "lifespan.shutdown.failed"
+    assert "first cleanup failed" in messages[-1]["message"]
+    assert "second cleanup failed" in messages[-1]["message"]
+
+
+async def test_partial_startup_rolls_back_acquired_resources_and_reports_both_errors():
+    resources = []
+
+    async def acquire():
+        resources.append("connection")
+
+    async def fail():
+        raise RuntimeError("startup failed")
+
+    async def must_not_run():
+        resources.append("unexpected")
+
+    async def close():
+        resources.clear()
+        raise ValueError("rollback failed after closing")
+
+    messages = await exchange(
+        lifespan_application(
+            App(), on_start=[acquire, fail, must_not_run], on_shutdown=close
+        )
+    )
+    assert resources == []
+    assert len(messages) == 1
+    assert messages[0]["type"] == "lifespan.startup.failed"
+    assert "startup failed" in messages[0]["message"]
+    assert "rollback failed after closing" in messages[0]["message"]

wred_lifespan-0.1.0/tests/test_workers.py

@@ -0,0 +1,141 @@
+"""Actual sockets, process signals, and worker replacement (POSIX only)."""
+
+import asyncio
+import os
+import signal
+import socket
+import sys
+from pathlib import Path
+
+import httpx
+import pytest
+
+pytestmark = [
+    pytest.mark.integration,
+    pytest.mark.skipif(sys.platform != "linux", reason="Linux process signals"),
+]
+
+
+async def test_workers_serve_during_replacement_and_rolling_restart(tmp_path):
+    event_dir = tmp_path / "events"
+    event_dir.mkdir()
+    environment = os.environ.copy()
+    # Carry the exact Wred installation/source path used by this test process.
+    environment["PYTHONPATH"] = os.pathsep.join(
+        [str(Path(__file__).parent), *[str(Path(p).resolve()) for p in sys.path if p]]
+    )
+    environment["WRED_LIFESPAN_EVENTS"] = str(event_dir)
+
+    def pids(event):
+        return {int(path.stem) for path in event_dir.glob(f"*.{event}")}
+
+    async def wait_for(predicate):
+        async with asyncio.timeout(15):
+            while not predicate():
+                assert process.returncode is None, log_path.read_text()
+                await asyncio.sleep(0.025)
+
+    log_path = tmp_path / "server.log"
+    counts = [0] * 8
+    seen = set()
+    transition = False
+    disconnects = []
+    stop = asyncio.Event()
+    with socket.socket() as listener, log_path.open("w") as log:
+        listener.bind(("127.0.0.1", 0))
+        port = listener.getsockname()[1]
+        listener.listen(128)
+        process = await asyncio.create_subprocess_exec(
+            *[
+                sys.executable,
+                "-m",
+                "uvicorn",
+                "worker_app:app",
+                "--fd",
+                str(listener.fileno()),
+                "--workers",
+                "2",
+                "--lifespan",
+                "on",
+                "--no-access-log",
+                "--timeout-graceful-shutdown",
+                "5",
+            ],
+            env=environment,
+            pass_fds=(listener.fileno(),),
+            stdout=log,
+            stderr=log,
+            start_new_session=True,
+        )
+        try:
+            await wait_for(lambda: len(pids("started")) == 2)
+            original = pids("started")
+            async with httpx.AsyncClient(
+                base_url=f"http://127.0.0.1:{port}",
+                timeout=5,
+                limits=httpx.Limits(max_connections=8, max_keepalive_connections=0),
+            ) as client:
+
+                async def traffic(index):
+                    while not stop.is_set():
+                        during_restart = transition
+                        try:
+                            response = await client.get("/")
+                        except (
+                            httpx.RemoteProtocolError,
+                            httpx.ReadError,
+                            httpx.ConnectError,
+                        ):
+                            # Uvicorn closes idle sockets during shutdown. Track
+                            # transport losses only in the explicit restart window.
+                            if not during_restart:
+                                raise
+                            disconnects.append(index)
+                            continue
+                        assert response.status_code == 200
+                        result = response.json()
+                        assert result["ready"] is True
+                        seen.add(result["pid"])
+                        counts[index] += 1
+
+                async with asyncio.timeout(45), asyncio.TaskGroup() as tasks:
+                    for index in range(len(counts)):
+                        tasks.create_task(traffic(index))
+                    await wait_for(lambda: sum(counts) >= 100 and original <= seen)
+                    # Gracefully stop one worker; the supervisor must replace it.
+                    transition = True
+                    victim = min(original)
+                    os.kill(victim, signal.SIGTERM)
+                    await wait_for(lambda: len(pids("started")) == 3)
+                    await wait_for(lambda: victim in pids("stopped"))
+                    replacement = pids("started") - original
+                    await wait_for(lambda: replacement <= seen)
+                    before_restart = pids("started")
+                    process.send_signal(signal.SIGHUP)
+                    await wait_for(lambda: len(pids("started")) == 5)
+                    await wait_for(lambda: before_restart <= pids("stopped"))
+                    await wait_for(lambda: pids("started") - before_restart <= seen)
+                    transition = False
+                    stable_target = sum(counts) + 1000
+                    await wait_for(lambda: sum(counts) >= stable_target)
+                    stop.set()
+            process.send_signal(signal.SIGTERM)
+            code = await asyncio.wait_for(process.wait(), timeout=10)
+            assert code == 0, log_path.read_text()
+            assert pids("started") == pids("stopped")
+            assert all(count > 0 for count in counts)
+            print(
+                f"{sum(counts)} successful requests; {len(seen)} worker PIDs; "
+                f"{len(disconnects)} restart transport disconnects; all cleaned up"
+            )
+        finally:
+            # Reap the process tree even when an assertion or deadline fails.
+            try:
+                os.killpg(process.pid, signal.SIGTERM)
+            except ProcessLookupError:
+                pass
+            try:
+                await asyncio.wait_for(process.wait(), timeout=5)
+            except TimeoutError:
+                os.killpg(process.pid, signal.SIGKILL)
+                await asyncio.wait_for(process.wait(), timeout=5)

wred_lifespan-0.1.0/tests/worker_app.py

@@ -0,0 +1,34 @@
+"""Instrumented application for real process lifecycle tests."""
+
+import asyncio
+import os
+from pathlib import Path
+
+from wred import App
+
+from wred_lifespan import lifespan_application
+
+api = App()
+resource = None
+events = Path(os.environ["WRED_LIFESPAN_EVENTS"])
+
+
+async def startup():
+    global resource
+    resource = (events / f"{os.getpid()}.resource").open("w")
+    (events / f"{os.getpid()}.started").touch()
+
+
+async def shutdown():
+    if resource is not None:
+        resource.close()
+    (events / f"{os.getpid()}.stopped").touch()
+
+
+@api.route("/")
+async def hello(request):
+    await asyncio.sleep(0.005)
+    return {"pid": os.getpid(), "ready": resource is not None and not resource.closed}
+
+
+app = lifespan_application(api, on_start=startup, on_shutdown=shutdown, hook_timeout=1)

wred_lifespan-0.1.0/wred_lifespan/__init__.py

@@ -0,0 +1,145 @@
+"""Bounded startup and best-effort cleanup for asyncio ASGI applications."""
+
+import asyncio
+import logging
+import math
+from collections.abc import Awaitable, Callable, Iterable
+from inspect import iscoroutinefunction
+from traceback import format_exception
+from typing import Any, TypeAlias
+
+__version__ = "0.1.0"
+__all__ = ["lifespan_application"]
+
+Scope: TypeAlias = dict[str, Any]
+Message: TypeAlias = dict[str, Any]
+Receive: TypeAlias = Callable[[], Awaitable[Message]]
+Send: TypeAlias = Callable[[Message], Awaitable[None]]
+ASGIApplication: TypeAlias = Callable[[Scope, Receive, Send], Awaitable[None]]
+LifespanHandler: TypeAlias = Callable[[], Awaitable[None]]
+Handlers: TypeAlias = LifespanHandler | Iterable[LifespanHandler] | None
+_logger = logging.getLogger(__name__)
+
+
+def _handlers(value: Handlers) -> tuple[LifespanHandler, ...]:
+    if value is None:
+        return ()
+    handlers = (value,) if callable(value) else tuple(value)
+    for handler in handlers:
+        if not (
+            iscoroutinefunction(handler)
+            or iscoroutinefunction(getattr(handler, "__call__", None))  # noqa: B004 - async callable objects.
+        ):
+            raise TypeError(
+                "Lifespan hooks must be async functions taking no arguments"
+            )
+    return handlers
+
+
+async def _run(handler: LifespanHandler, seconds: float) -> None:
+    async with asyncio.timeout(seconds) as deadline:
+        await handler()
+    # A hook that catches cancellation and returns still missed its deadline.
+    if deadline.expired():
+        raise TimeoutError("Lifespan hook exceeded its timeout")
+
+
+async def _cleanup(
+    handlers: tuple[LifespanHandler, ...], seconds: float
+) -> list[BaseException]:
+    errors: list[BaseException] = []
+    for handler in handlers:
+        try:
+            await _run(handler, seconds)
+        except (Exception, asyncio.CancelledError) as exc:  # noqa: BLE001 - attempt every cleanup.
+            # Each cleanup gets its own deadline; one failure cannot skip the rest.
+            errors.append(exc)
+    return errors
+
+
+def _log_errors(errors: list[BaseException]) -> None:
+    for error in errors:
+        if not isinstance(error, asyncio.CancelledError):
+            _logger.error(
+                "Lifespan cleanup failed",
+                exc_info=(type(error), error, error.__traceback__),
+            )
+
+
+def _result(phase: str, errors: list[BaseException]) -> Message:
+    for error in errors:
+        if isinstance(error, asyncio.CancelledError):
+            _log_errors(errors)
+            raise error
+    if errors:
+        failure = BaseExceptionGroup(f"Lifespan {phase} failed", errors)
+        return {
+            "type": f"lifespan.{phase}.failed",
+            "message": "".join(format_exception(failure)),
+        }
+    return {"type": f"lifespan.{phase}.complete"}
+
+
+async def _receive(receive: Receive, phase: str) -> None:
+    message = await receive()
+    if message["type"] != f"lifespan.{phase}":
+        raise RuntimeError(f"Expected lifespan.{phase}, received {message['type']}")
+
+
+def lifespan_application(
+    app: ASGIApplication,
+    *,
+    on_start: Handlers = None,
+    on_shutdown: Handlers = None,
+    hook_timeout: float = 30.0,
+) -> ASGIApplication:
+    """Wrap an ASGI app with async startup and shutdown hooks.
+
+    Hooks run in supplied order, each with its own positive, finite timeout in
+    seconds. Shutdown hooks also run after partial startup failure, cancellation,
+    or a broken lifespan connection; they must tolerate uninitialized resources.
+    All cleanup hooks are attempted even when another fails or times out.
+
+    Timeouts require cooperative asyncio code. Blocking code or suppressed
+    cancellation cannot be forcibly stopped. This wrapper owns lifespan scopes;
+    all other scopes are forwarded unchanged to app.
+    """
+    if not callable(app):
+        raise TypeError("app must be an ASGI callable")
+    if (
+        isinstance(hook_timeout, bool)
+        or not isinstance(hook_timeout, (int, float))
+        or not math.isfinite(hook_timeout)
+        or hook_timeout <= 0
+    ):
+        raise ValueError("hook_timeout must be a positive finite number of seconds")
+    startup, shutdown = _handlers(on_start), _handlers(on_shutdown)
+
+    async def application(scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "lifespan":
+            await app(scope, receive, send)
+            return
+
+        await _receive(receive, "startup")
+        cleanup_started = False
+        try:
+            try:
+                for handler in startup:
+                    await _run(handler, hook_timeout)
+            except Exception as exc:  # noqa: BLE001 - report failures through ASGI.
+                cleanup_started = True
+                errors = [exc, *await _cleanup(shutdown, hook_timeout)]
+                await send(_result("startup", errors))
+                return
+            await send({"type": "lifespan.startup.complete"})
+            await _receive(receive, "shutdown")
+            cleanup_started = True
+            errors = await _cleanup(shutdown, hook_timeout)
+            await send(_result("shutdown", errors))
+        finally:
+            # Transport errors, protocol errors, and cancellation still release
+            # resources. Preserve the original exception and log cleanup errors.
+            if not cleanup_started:
+                _log_errors(await _cleanup(shutdown, hook_timeout))
+
+    return application