skirr 0.1.0__tar.gz

skirr-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+/target/
+*.so
+__pycache__/
+.pytest_cache/
+.venv/
+*.egg-info/
+
+/dist/

skirr-0.1.0/COMPLIANCE.md

@@ -0,0 +1,56 @@
+# HTTP/ASGI prototype requirements matrix
+
+Normative references: [ASGI 3.0](https://asgi.readthedocs.io/en/latest/specs/main.html),
+[HTTP/WebSocket 2.5](https://asgi.readthedocs.io/en/latest/specs/www.html),
+[Lifespan 2.0](https://asgi.readthedocs.io/en/latest/specs/lifespan.html),
+[RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html),
+[RFC 9112](https://www.rfc-editor.org/rfc/rfc9112.html).
+
+This matrix tracks specific evidence. It is not a blanket compliance claim.
+Specifications and verified errata need another review before a release.
+
+| Contract | Evidence / state |
+|---|---|
+| ASGI 3 asynchronous application interface | Real ASGI apps, FastAPI benchmark |
+| HTTP scopes, paths, query strings, repeated headers | `test_scope_headers_and_percent_decoding` |
+| Absolute-target authority replaces Host | `test_absolute_target_authority_overrides_host` |
+| Incremental fixed/chunked request bodies | Upload, fragmentation, and native segmentation tests |
+| Exact request boundaries and ordered pipelining | Fixed-upload/pipeline test and native consumed-prefix test |
+| Framing ambiguity closes the connection | Table of malformed requests plus a pipelined successor |
+| Resource bounds and integer overflow | 100/101-header boundaries, oversized head/body cases; native chunk syntax/overflow test |
+| Response start/body order and header validation | Response validation and iterable-header-pair tests; broader invalid-message matrix remains |
+| Duplicate response fields preserved | Repeated Set-Cookie socket test |
+| Header snapshots and owned scope values | Empty/obs-text/trimmed values, retained/mutated scope headers, changed same-length values, and large/duplicate header tables; mutation of response headers after start |
+| Native send call signature | Invalid arity/type and positional/keyword send calls through a real application |
+| Ready awaitable iterator returns the receive value | Explicit `__await__` iterator completion plus socket echo/fragmentation tests |
+| HEAD/204/205/304 no response body | Parameterized bodyless pipeline test |
+| Response Content-Length checked | Mismatch before/after response bytes begin, with no second response appended |
+| Streaming sends flush before app completion | Event-controlled streaming socket test |
+| ASGI response trailers | Multi-message trailer socket test |
+| receive waits after the final request event | Disconnect test |
+| Pending receive wakes when the response completes | Response-completion socket test |
+| Closed send raises OSError | Backpressure/disconnect test |
+| Cancelled receive may be replaced | Cancellation socket test |
+| Retained request callables cannot cross requests | Retained-channel socket test |
+| Immediate awaits preserve fairness | Streaming producer, ready disconnect receives and queued-marker pipeline checks |
+| Buffered pipelining remains ordered while an app is held | 200-request pipeline test |
+| Eager execution preserves Task and context isolation | Ready/waiting app context test |
+| Embedding task factories are respected | Custom factory socket test |
+| Disconnect during dispatch cannot panic or stop serving | Final/streaming TCP resets and subsequent healthy-request test |
+| Server closed-send errors are quiet; application failures remain visible | Disconnect logging regression and ready/waiting Task failures, including application OSError and cancellation |
+| Scope method/version defaults do not leak across requests | Mixed HTTP/1.0 and HTTP/1.1 methods on keepalive connections |
+| Completion outside the native reactor flushes output | 24 independently held applications released together |
+| Large body data and chunk framing survive partial writes | Byte-exact streamed payloads at 4095/4096/4097 bytes and 8 MiB |
+| Lifespan on serving loop; request state shallow copies | Lifespan/state test for on/off; optional state omitted only when explicitly off |
+| Explicit startup.failed prevents serving | Lifespan failure test |
+| Graceful shutdown ordering | Cancellation cleanup precedes lifespan shutdown in embedding test; process-level qualification remains |
+| Slow-client timeouts and truncated EOF | Implemented; broader deadline/EOF matrix remains |
+| WebSockets | Unsupported; upgrade rejected with 501 |
+| Optional ASGI extensions | None advertised |
+| HTTP/2, HTTP/3, TLS | Unsupported |
+
+Before production: complete the remaining HTTP requirement-by-requirement audit,
+add property/fuzz coverage, extend the native/Python AddressSanitizer checks with leak and fuzz qualification,
+qualify all advertised Python/platform combinations, and exercise prolonged
+mixed-client load and shutdown failures. Differential server behavior is useful
+evidence but does not replace the specifications as the authority.

skirr-0.1.0/Cargo.lock

@@ -0,0 +1,140 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "httparse"
+version = "1.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
+
+[[package]]
+name = "libc"
+version = "0.2.191"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "700d18fa267b73b9b521fd7e13580e2f446916f176cacee1ab63fcc8191f1655"
+dependencies = [
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b3fc0c4d08f6bb10e71fe39dfb9e2f59c6eb6854e22ec8092f50c69a4499adb"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfc0b8e19df29aad7086cf977bb0c2a2f143e30567eb113e9cf72b62ca698330"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6100e8a4b5eba53afaa5ed078364851a0b2499c553a44c31026b929049b49dc6"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6143877a16e82b5a727b7127ff4cd86858a24a28d745d72f43e6f227c7b1bdb3"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "skirr"
+version = "0.1.0"
+dependencies = [
+ "httparse",
+ "libc",
+ "pyo3",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"

skirr-0.1.0/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "skirr"
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.88"
+license = "MIT"
+description = "A small experimental ASGI-only server"
+repository = "https://gitman.io/patx/skirr"
+exclude = ["bench/**", "docs/**"]
+readme = "README.md"
+
+[lib]
+name = "_native"
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+pyo3 = "0.29"
+httparse = "1.10"
+libc = "0.2"
+
+[features]
+extension-module = ["pyo3/extension-module"]
+
+[profile.release]
+lto = "thin"
+codegen-units = 1
+

skirr-0.1.0/DESIGN.md

@@ -0,0 +1,142 @@
+# Prototype decisions
+
+Skirr is an ASGI transport, not an application framework. Keep a single native
+owner for each connection and run the application on the same thread and loop.
+
+The prototype tests Peregrine's native-poller integration: epoll itself is
+registered with asyncio, and the callback processes bounded native work. This
+keeps uvloop usable and avoids another runtime and cross-thread request queues.
+The alternative Weft design drives Tokio through a replacement asyncio selector.
+Both deserve measurement; neither language nor reactor choice guarantees a win.
+
+Sources reviewed:
+
+- [Weft ASGI](https://github.com/grepjava/weft/blob/cec2030ed2a2f6e3fcb54df1270cc654cc9247e3/src/asgi.rs)
+- [Weft callable types](https://github.com/grepjava/weft/blob/cec2030ed2a2f6e3fcb54df1270cc654cc9247e3/src/types.rs)
+- [Peregrine ASGI](https://github.com/grepjava/peregrine/blob/3f8cac19b60ce6a151a07a5535a7e4ee8e3bbccf/Sources/PeregrineServer/ASGIDispatch.swift)
+- [Peregrine connections](https://github.com/grepjava/peregrine/blob/3f8cac19b60ce6a151a07a5535a7e4ee8e3bbccf/Sources/PeregrineServer/Connection.swift)
+- [Peregrine fuzzing](https://github.com/grepjava/peregrine/blob/3f8cac19b60ce6a151a07a5535a7e4ee8e3bbccf/Sources/PeregrineFuzzTargets/FuzzTargets.swift)
+
+Native send and receive return a completed awaitable for ready operations and
+Futures for waits. A shared completed-None awaitable avoids allocating a Future for every send.
+A bounded operation budget forces cooperative yields even on fast sockets.
+
+Connections have monotonically assigned identities; request callables refer to
+their own request state and hold weak connection/worker references. Connections
+are not recycled into the same identity. This is simpler than a slab for the
+prototype and preserves the stale-callback safety property of generation tokens.
+A slab is a later profiling decision.
+
+Worker fields and connection state use thread-local ownership (Rc/RefCell),
+not locks. Mutable state borrows must end before potentially reentrant Python
+calls. CPython object ownership uses PyO3 rather than a parallel handwritten
+reference-counting abstraction. Free-threaded Python is intentionally unqualified.
+
+## Profile-driven optimization
+
+Native cycle sampling found a large read-buffer clearing cost (about 16% of
+baseline raw-ASGI user-space cycles), while wall-time stack sampling also exposed
+repeated epoll changes. The worker now reuses initialized scratch space and leaves
+an empty socket readable across requests. Buffered pipelined bytes still pause
+reads; a held application cannot make the reactor spin on its next request.
+
+Response serialization writes into the connection's reusable buffer. A later
+large-response profile still attributed about 42% of user-space cycles to copying.
+Vectored writes now pass large immutable Python bodies directly to the socket;
+partial writes immediately copy the unsent suffix into owned native memory.
+The retained implementation's bulk profile reduced copying to about 2.5% of
+user-space cycles. This avoids an intermediate copy, not the kernel's copy.
+
+CPython Task eager startup (available in the supported Python 3.12+) avoids a
+scheduler turn when the application does not need to wait. Each request still
+has its own Task and context. Custom task factories use the normal loop path.
+Already-finished tasks are cleaned up synchronously; pending tasks retain a done
+callback. Pipeline progress belongs to the outer bounded pump, with explicit
+deferred resumption when buffered work remains. It must never recurse once per
+pipelined request. A request may disappear during eager dispatch on write failure,
+so pump re-checks its active request rather than assuming one still exists.
+
+The first optimization round shared an already-completed asyncio Future for sends. Real waits still get
+their own Future. The operation budget still forces cooperative yields. Empty
+request events are constructed lazily without allocating an otherwise unused
+body queue. Parser header scratch uses httparse's safe uninitialized-header API.
+
+Two experiments were discarded: borrowed native header views did not show a
+clear benefit, and a PyCFunction vectorcall wrapper's modest improvements did not
+justify extra unsafe code and two additional context/function objects per request.
+That optimization round added neither dependencies nor unsafe blocks. A separate eager-work-budget/scope-completion experiment also failed to improve tail latency and was reverted; its patch and diagnostic runs are retained.
+
+The next bottlenecks include request dispatch and the Python application itself.
+FastAPI's baseline native CPU profile attributed roughly 45% of user-space cycles
+to CPython's evaluator alone. The server does not change application GC policy,
+skip response validation, disable fairness, or specialize for benchmark routes.
+
+Cycle percentages are samples of user-space execution, not end-to-end wall time.
+They must not be interpreted as predicted throughput gains. Raw perf reports,
+commands and sampled build metadata live in `bench/profiles`; the authoritative
+performance comparison is the repeated unprofiled run in `bench/results`.
+
+Remaining roadmap: complete HTTP conformance evidence, aggregate byte budgets,
+worker supervision and listener handoff, WebSockets via a maintained codec, then
+optional TLS/HTTP2/HTTP3 dependencies with independent protocol qualification.
+
+## Exact-release Peregrine comparison
+
+The second round reviewed the source of the installed Peregrine 1.1.7 release,
+including its native ready awaitables, header spans and reusable buffers. The
+[study](bench/profiles/peregrine-study.md) records profiles, source provenance,
+syscall counts, tests and rejected experiments. Request headers now use one
+owned block with safe ranges, response headers serialize once into bounded
+reusable storage, and decoded uploads copy straight into owned Python bytes.
+A level-triggered short read ends the current read batch instead of probing
+again for EAGAIN. Another event services later data.
+
+Completed sends now share a native stateless awaitable. Ready receives and
+fairness yields use the same native slots with per-operation state; waits still
+use Futures. CPython ownership for this small type is isolated in
+`src/completed.rs`, with no thread-bound Rust pointers or global interpreter
+references. Unlike the discarded vectorcall channel experiment, this is not a
+parallel callable/connection ownership framework. The operation quota, Task
+isolation, validation and scope isolation remain in force.
+
+## FastAPI fairness and allocation study
+
+The third round profiles the exact release binaries and the actual FastAPI worker.
+A worker-global send quota made some short requests yield behind an unrelated batch.
+The quota now belongs to each request and includes ready receives. A 16-event
+reactor batch and bounded eager starts preserve loop opportunities without making
+every response asynchronous. Custom task factories and request contexts remain intact.
+
+Scope construction uses startup-interned fixed keys, separate shallow copies of
+mutable dictionaries, borrowed common method names and a pre-sized header list.
+Completed Tasks are inspected once through result(), preserving application errors
+and cancellation. Server-generated disconnect errors have an OSError subclass so
+expected disconnects are quiet while application OSError failures remain reported.
+
+The retained changes add 48 native lines and no dependencies or unsafe code.
+Write-batching and alternative task schedulers were rejected after throughput and
+disconnect checks. Detailed profiles, rejected patches and comparisons are in
+[the FastAPI study](bench/profiles/fastapi-study.md). Native library sample shares
+are small; CPython execution includes both application code and server object/API
+work, so it is not valid to treat that entire share as unavoidable application cost.
+
+## Bounded final writes and FastAPI overhead
+
+The fourth round replaces the adaptive-batch checkpoint with sixteen-event
+cheap-work batches and at most 32 events while final flushes are queued. Small
+final responses can copy into the kernel using MSG_MORE, then push at the native poll boundary or in a bounded
+loop callback for independently resumed apps. Streaming responses retain immediate writes. A queued callback
+tries the write before arming EPOLLOUT, avoiding redundant interest changes.
+
+Native request-head scratch storage is recycled after Python owns its scope.
+Short identical header blocks share immutable pairs behind fresh mutable lists;
+the worker's cross-connection hint is weak and each connection retains only one
+bounded snapshot. Optional state is omitted only for explicit lifespan off.
+Loop methods are cached without caching the result of get_task_factory.
+
+A guarded vectorcall entry removes generic call packaging for Sender while
+keeping its PyO3 allocation, thread checks, errors and ownership. Layout checks
+fall back to PyO3's ordinary call path; type slots are initialized under the GIL.
+This adds unsafe CPython integration, so it needs independent qualification for
+each Python version. The repeated profiles, rejected experiments and precise
+limits of the results are in [the fourth-round study](bench/profiles/latency-round4-study.md).

skirr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skirr contributors
+
+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.

skirr-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: skirr
+Version: 0.1.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Requires-Dist: psutil ; extra == 'bench'
+Requires-Dist: fastapi ; extra == 'bench'
+Requires-Dist: uvloop ; extra == 'bench'
+Requires-Dist: weft-server ; extra == 'bench'
+Requires-Dist: peregrine-server ; extra == 'bench'
+Requires-Dist: uvloop>=0.22 ; extra == 'speed'
+Requires-Dist: pytest>=8 ; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.24 ; extra == 'test'
+Requires-Dist: fastapi ; extra == 'test'
+Provides-Extra: bench
+Provides-Extra: speed
+Provides-Extra: test
+License-File: LICENSE
+Summary: Experimental Linux HTTP/1 ASGI-only server
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Repository, https://gitman.io/patx/skirr
+
+# Skirr
+
+A small, experimental **ASGI-only** Rust server for Linux. Python owns the
+application's asyncio loop; Rust owns nonblocking sockets, HTTP/1 framing,
+buffering, and native ASGI send/receive objects. The native epoll descriptor is
+registered with `loop.add_reader`. There is no second async runtime or thread.
+
+This is an architecture prototype, not a production release. Profile-driven
+optimizations and same-session before/after comparisons live in
+[the latest comparison](bench/results/latency-round4-final-report.txt). Results are
+workload-specific; this is not a claim of overall superiority to other servers.
+The fourth round improves FastAPI throughput by 1.9–3.4% over its starting
+release and fixed-rate p99 by 4.4%. It does not consistently beat Peregrine on
+both FastAPI throughput and latency; some saturation p99 regressions remain.
+See [the profile and regression study](bench/profiles/latency-round4-study.md).
+
+## Build and run
+
+Requires Linux, Rust 1.88 or newer, and CPython 3.12 or newer. This initial implementation has
+been tested on CPython 3.14.4 on Linux x86-64; other supported Python versions
+and ARM64 still need qualification. Free-threaded Python is not supported.
+
+```bash
+python -m pip install .
+skirr app:app --host 127.0.0.1 --port 8000
+```
+
+`pip install '.[speed]'` installs optional uvloop. Standard asyncio also works.
+Applications use the ordinary ASGI 3 `(scope, receive, send)` interface.
+`--lifespan auto|on|off` defaults to `auto`. Only one worker is implemented;
+other worker counts fail explicitly.
+
+For development without installing the package:
+
+```bash
+python tools/build.py
+PYTHONPATH=python python -m pytest tests -q
+cargo test --lib
+```
+
+## Implemented scope
+
+- HTTP/1.0 and HTTP/1.1, sequential pipelining, fixed-length and chunked bodies.
+- Request dispatch at headers, incremental upload consumption, demand-driven
+  `100 Continue`, streaming responses, and HTTP/1.1 response trailers.
+- Native completed awaitables; Futures for blocked receive and output drain.
+- Eager task startup when no custom task factory is installed; normal factory
+  behavior is preserved. Completed tasks are cleaned up without another callback.
+- Read and write backpressure, per-callback I/O budgets and an ASGI operation
+  budget per request so immediately completed sends and receives cooperate with the loop.
+  Native event batches and eager application starts are also bounded.
+- Request identities that prevent retained channels from writing into a later
+  request, disconnect delivery, closed-send errors, and cancelled receive reuse.
+- Lifespan startup/shutdown on the serving loop, request state copies and
+  graceful drain. IPv4 and IPv6 TCP listeners.
+
+No WSGI, routing, application framework, caching, compression, or static files.
+WebSockets and other upgrades return 501. TLS, HTTP/2, HTTP/3, Unix sockets,
+proxy-header processing, worker supervision and structured access logs are not
+implemented. Informational-response extensions are not advertised. CONNECT is
+not implemented and returns 501. An HTTP/1.0 response cannot carry trailers;
+trailer events complete it without transmitting trailer fields.
+
+## Standards and limits
+
+The HTTP scope advertises ASGI 3.0 and HTTP sub-specification 2.5. Lifespan uses
+2.0. The implementation targets RFC 9110/9112 for HTTP semantics/framing.
+This describes the intended contract, not a claim of completed conformance
+certification. See [the requirements matrix](COMPLIANCE.md) for tested behavior
+and outstanding qualification. Supporting HTTP/1 does not imply HTTP/2 or HTTP/3
+support, nor support for the ASGI WebSocket protocol.
+
+Current fixed prototype limits:
+
+| Resource | Limit |
+|---|---:|
+| Request head | 32 KiB / 100 fields |
+| Decoded request body | 16 MiB |
+| Chunk framing and trailer metadata combined | 32 KiB |
+| Individual chunk-size line | 8 KiB |
+| Buffered request-body high-water mark | 64 KiB, plus one decoded segment |
+| Unconsumed wire buffer | 1 MiB |
+| Output pause / resume thresholds | 512 KiB / 64 KiB |
+| Connections | 10,000 |
+| Header deadline / keepalive idle timeout | 10 s / 5 s |
+| Stalled client I/O timeout | 30 s |
+
+Output backpressure bounds queued work between awaited sends. One application
+body message can exceed the threshold; any unsent suffix is copied into
+its output buffer. There is no aggregate worker byte budget yet. Consequently,
+the connection limit is not a sufficient production memory limit.
+
+## Architecture and dependency budget
+
+Three direct Rust dependencies: PyO3 (Python ownership/integration), httparse
+(request-head syntax), and libc (isolated socket/poller calls). Cargo.lock pins the full
+graph, including build dependencies. Python runtime dependencies are optional.
+
+- `src/http.rs`: framing without Python or sockets, plus segmentation tests.
+- `src/net.rs`: owned epoll descriptor and OS-specific socket/poller operations.
+- `src/vectorcall.rs`: guarded CPython call entry for the existing PyO3 Sender.
+- `src/completed.rs`: native ready-awaitable slots, with isolated CPython ownership.
+- `src/lib.rs`: connection ownership, I/O, ASGI objects and worker callbacks.
+
+The worker reuses one initialized read buffer. An empty socket remains armed
+between requests, avoiding two epoll changes per request; buffered pipelined
+input still pauses reads. Small writes are coalesced; large bodies use vectored
+I/O with an owned copy of any unsent suffix. Python body pointers are never
+retained after a send call. Header-name caching is capped at 512 names, each
+at most 128 bytes; application-visible mutable scope dictionaries remain separate.
+Identical short request-header blocks can share immutable tuples and bytes, with
+a fresh mutable header list per request. Snapshots are bounded to eight fields
+and 512 wire bytes per connection, with a weak hint for sharing across connections.
+Native request-head storage is reused only after Python owns the scope values.
+With explicit lifespan off, the optional state namespace is omitted; auto/on
+still provide a fresh shallow copy.
+Fixed scope keys are interned once; each request still gets separate mutable scope
+and ASGI-version dictionaries. Header spans use one owned request block. Response-header storage is reused up
+to 64 KiB per connection. Upload segments copy directly into owned Python bytes.
+Completed sends allocate no iterator, while real I/O waits still use Futures.
+Small final responses after more expensive application work copy into the kernel
+with MSG_MORE and push at the end of the bounded native callback (or a queued
+callback for independently resumed apps). Streaming sends flush
+immediately. Queued flushes do not arm EPOLLOUT until an attempted write blocks.
+- `python/skirr`: application loading, lifespan, CLI and loop orchestration.
+
+Readability takes priority over a line-count target. CPython integration still
+has overhead worth measuring: native callable dispatch, scope/message allocation,
+buffer copies, task scheduling, and done callbacks. The Sender uses a guarded vectorcall entry while retaining PyO3 ownership,
+thread checks and error/panic translation. This integration needs qualification
+on every supported Python version.
+
+Design research used pinned Weft `cec2030` and Peregrine `3f8cac1` source
+snapshots. The implementation is new Rust code; their architectural ideas are
+credited in [DESIGN.md](DESIGN.md). The latest study also reviews the exact
+Peregrine 1.1.7 release source; [profiles and findings](bench/profiles/peregrine-study.md)
+explain the retained and rejected experiments. The benchmark apps and resource-sampling
+harness were adapted from our MRHTTP benchmark tooling.
+
+## Benchmark reproduction
+
+Install the optional benchmark dependencies and `wrk`. Run from this directory:
+
+```bash
+PYTHONPATH=python python bench/compare.py --workers 1 --connections 64 \
+  --duration 5 --repeats 3 --output bench/results/my-c64
+```
+
+The default server CPU is core 0 and load-generator CPUs are 4–7; override
+`--server-cpus` and `--client-cpus` for your machine. Their sets must not overlap.
+Each result records versions, build/source hashes, CPU and memory sampling,
+worker readiness, response validation, raw wrk output and streaming latency.
+The main throughput run validates exact responses before and after load;
+it does not validate every response body during the run.
+
+These are closed-loop local microbenchmarks, not production capacity estimates.
+wrk's timeout counter also includes completed responses outside its three-second
+latency histogram. Compare that separately from connect/read/write failures.
+A separate [fixed-rate comparison](bench/results/latency-round4-final-rate20k-report.txt)
+uses wrk2 corrected histograms; do not pool those percentiles with wrk results.
+Extended soak tests, fuzzing, broader sanitizer/leak qualification,
+and broader platform testing remain required before a production release.
+
+Verification: 64 real-socket/ASGI tests pass under both standard asyncio
+and uvloop; three native framing-invariant tests pass; strict Clippy passes.
+An installable CPython 3.14 Linux wheel was built and the same 64 socket tests
+passed against that installed wheel. These checks cover the listed contracts,
+not every requirement in the HTTP specifications. A separate AddressSanitizer
+build passes the 64 cases under both loops; its embedding-host limitations and
+commands are recorded in [the sanitizer log](bench/profiles/asan-round4-final-check.txt).
+
+To reproduce the same-session before/after comparison, extract
+`bench/profiles/round4-before-source.tar.gz` into a separate directory and include
+`--servers skirr-before skirr weft peregrine --baseline /path/to/extracted`.
+The archive includes the original source and CPython 3.14 x86-64 release binary.
+Rebuild that binary when using another interpreter or architecture.
+
+The latest before/after baseline is `bench/profiles/round3-before-source.tar.gz`;
+its results are in `bench/results/latency-round4-final-report.txt`.
+The [FastAPI study](bench/profiles/fastapi-study.md) records profiling, retained
+changes, rejected prototypes, and measurement limitations. Earlier reports
+and their distinct original baseline remain available for historical comparison.
+
+For a comparable run on this laptop, the final matrices were launched with
+`powerprofilesctl launch --profile performance --appid skirr-benchmark --` before
+the Python benchmark command. This temporary hold releases on command exit;
+it is optional benchmark tooling, not a Skirr runtime dependency. CPU-frequency
+samples and the active power profile are recorded in each result. Discarded
+power-saver and mixed-clock trials remain clearly named in the results folder.
+