matchapi 0.1.0__tar.gz → 0.2.1__tar.gz

matchapi-0.2.1/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-10-12
+
+Package metadata only; the code is unchanged.
+
+### Changed
+
+- The PyPI description, keywords and classifiers name granian and RSGI, so the package is found by the stack it
+  runs on. The README opens with the same line.
+
+## [0.2.0] - 2026-10-12
+
+The handler is decorated and granian serves it. The framework loses its command line and its ASGI adapter;
+the handler contract, the request and the response rules are unchanged.
+
+### Changed
+
+- `@matchapi.app` over `handle`: the decorated function is an RSGI application for
+  [granian](https://github.com/emmett-framework/granian) and is still called as the function in tests. Run with
+  `granian app:handle`.
+- granian replaces uvicorn as the one dependency. HTTP/2, TLS, `--workers` and `--reload` are granian's;
+  `--reload` needs `pip install 'granian[reload]'`.
+- An exception inside a streaming response body is logged with the method and path, and the stream ends.
+
+### Removed
+
+- The `matchapi` command (`matchapi app`, `python -m matchapi`), `matchapi.main`, and the rule that found
+  `handle` or the only public function of a module.
+- The ASGI application: uvicorn, hypercorn and ASGI middleware can no longer run a matchapi service.
+
+### Added
+
+- `bench/`: the framework's share of a request, measured against a bare RSGI application and against 0.1.0 under
+  uvicorn.
+
+## [0.1.0] - 2026-10-12
+
+### Added
+
+- `Request`: method, path, `route` as `(method, *segments)`, query, headers, body and `json()`; built by hand in
+  tests.
+- `Response`, `HTTPError` and `respond()`: the rules that turn a handler's return value into a response.
+- `app(handle)`: the handler as an ASGI application; sync handlers run in the thread pool, async ones in the loop.
+- The `matchapi` command: `matchapi app` serves the module's `handle` with uvicorn; `--host`, `--port`,
+  `--workers`, `--reload`.
+
+[Unreleased]: https://github.com/troyan-dy/matchapi/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/troyan-dy/matchapi/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/troyan-dy/matchapi/releases/tag/v0.1.0

matchapi-0.2.1/CONTEXT.md

@@ -0,0 +1,36 @@
+# matchapi
+
+An HTTP service is one function, and `match` over the route replaces the router. This glossary fixes the words
+the README, the design notes and the code use for the pieces of that model.
+
+## Language
+
+**Handler**:
+The user's function `(Request) -> value`: the whole service. It is called directly in tests.
+_Avoid_: view, endpoint, controller, route function
+
+**App**:
+The handler wrapped by the `matchapi.app` decorator: the object a server runs. Calling it is calling the handler.
+_Avoid_: application object, server, service object
+
+**Request**:
+The incoming request as plain data: method, path, route, query, headers, body. No transport underneath.
+_Avoid_: scope, context
+
+**Route**:
+The tuple `(method, *segments)` that the handler's `match` is written over: `GET /users/42` is
+`("GET", "users", "42")`.
+_Avoid_: path (that is the string `/users/42`), URL, endpoint
+
+**Response**:
+What the server sends: status, headers, body. Built from the handler's return value by the response rules.
+_Avoid_: result, reply
+
+**Response rules**:
+The mapping from a handler's return value to a Response: `dict` is JSON, `str` is text, `int` is a status, a tuple
+adds status and headers, `Response` is returned as is.
+_Avoid_: serialization, rendering
+
+**Server**:
+The program that speaks HTTP and calls the app once per request: granian. Not part of matchapi.
+_Avoid_: runtime, runner, worker

{matchapi-0.1.0 → matchapi-0.2.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: matchapi
-Version: 0.1.0
-Summary: An HTTP service is one function: match replaces the router
+Version: 0.2.1
+Summary: One-function HTTP framework for granian over RSGI: match replaces the router
 Project-URL: Homepage, https://github.com/troyan-dy/matchapi
 Project-URL: Repository, https://github.com/troyan-dy/matchapi
 Project-URL: Issues, https://github.com/troyan-dy/matchapi/issues
@@ -9,8 +9,9 @@ Project-URL: Changelog, https://github.com/troyan-dy/matchapi/blob/master/CHANGE
 Author: Dmitriy Troyan
 License-Expression: MIT
 License-File: LICENSE
-Keywords: asgi,framework,http,match,microservice,pattern-matching,web,webhook
+Keywords: api,async,asyncio,framework,granian,http,json,match,microframework,microservice,pattern-matching,rest,rsgi,rust,single-file,structural-pattern-matching,web,web-framework,webhook
 Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
@@ -20,11 +21,13 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
 Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: uvicorn>=0.30
+Requires-Dist: granian>=2.8
 Description-Content-Type: text/markdown
 
 # matchapi
@@ -36,8 +39,16 @@ Description-Content-Type: text/markdown
 
 An HTTP service is one function. `match` replaces the router.
 
+A one-file Python web framework for [granian](https://github.com/emmett-framework/granian) over
+[RSGI](https://github.com/emmett-framework/granian/blob/master/docs/spec/RSGI.md), granian's native Rust-backed
+interface: no router, no middleware, no ASGI adapter. Python 3.11+.
+
 ```python
 # app.py
+import matchapi
+
+
+@matchapi.app
 async def handle(req):
     match req.route:
         case "GET", "ping":
@@ -53,11 +64,12 @@ async def handle(req):
 
 ```console
 $ pip install matchapi
-$ matchapi app
-INFO:     Started server process [62579]
-INFO:     Waiting for application startup.
-INFO:     Application startup complete.
-INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+$ granian app:handle
+[INFO] Starting granian (main PID: 505)
+[INFO] Listening at: http://127.0.0.1:8000
+[INFO] Spawning worker-1 with PID: 512
+[INFO] Started worker-1
+[INFO] Started worker-1 runtime-1
 ```
 
 ```console
@@ -67,24 +79,24 @@ $ curl localhost:8000/users/42
 {"id":42,"name":"ann"}
 $ curl -i -X POST localhost:8000/users -d '{"name": "bob"}'
 HTTP/1.1 201 Created
-date: Mon, 12 Oct 2026 00:10:08 GMT
-server: uvicorn
 content-type: application/json
 content-length: 21
+server: granian
+date: Mon, 12 Oct 2026 01:26:59 GMT
 
 {"id":7,"name":"bob"}
 $ curl -i localhost:8000/nothing
 HTTP/1.1 404 Not Found
-date: Mon, 12 Oct 2026 00:10:08 GMT
-server: uvicorn
 content-type: text/plain; charset=utf-8
 content-length: 9
+server: granian
+date: Mon, 12 Oct 2026 01:26:59 GMT
 
 Not Found
 ```
 
-No decorators, no route table, no schema classes, no dependency markers. The file above does not even import
-`matchapi`: it is a Python function that takes a request and returns a value, and it can be called like one.
+One import and one decorator; no route table, no schema classes, no dependency markers, no middleware stack. The
+decorated `handle` is still the function it was: a test calls it with a request and compares the return value.
 
 - [Why](#why)
 - [The model](#the-model)
@@ -110,7 +122,8 @@ models. A service with three endpoints pays for all of it.
 Python has had structural pattern matching since 3.10. A `match` over `(method, *segments)` is a router already:
 it binds path parameters, it falls through to a default, it nests, and the language, not a library, defines how it
 reads. matchapi is what is left of a framework once the router is gone: a `Request`, a `Response`, the rules that
-turn a return value into one, and a command that serves a module.
+turn a return value into one, and a decorator that lets [granian](https://github.com/emmett-framework/granian)
+serve the function.
 
 ## The model
 
@@ -119,6 +132,11 @@ turn a return value into one, and a command that serves a module.
 The service is a function that takes a `Request` and returns something. That is the whole contract. A function is
 easy to test, easy to compose, easy to move: two services in one process are a function that calls two others.
 
+`@matchapi.app` marks the function as the application granian runs. It changes nothing about the function:
+`handle(req)` calls it, `handle.__name__` and `handle.__doc__` are its own. The one thing that differs is
+`inspect.iscoroutinefunction(handle)`, which is `False` for the decorated object; matchapi itself never asks it,
+it looks at what a call returns.
+
 ### `req.route` is the subject of `match`
 
 `req.route` is a tuple of the method followed by the non-empty path segments: `GET /users/42` is
@@ -148,11 +166,11 @@ strings for the cases where a plain comparison reads better.
 | `path` | `str` | `"/users/42"` |
 | `route` | `tuple[str, ...]` | `("POST", "users", "42")` |
 | `query` | `dict[str, str]`, last value wins | `{"q": "x"}` |
-| `headers` | `dict[str, str]`, lower-case names | `{"content-type": "application/json"}` |
+| `headers` | `dict[str, str]`, lower-case names, last value wins | `{"content-type": "application/json"}` |
 | `body` | `bytes`, read in full before the call | `b'{"name": "bob"}'` |
 | `json()` | the body as JSON; a broken body is a 400 | `{"name": "bob"}` |
 
-There is no `scope` or stream underneath: the body is read before the handler runs, so a sync handler needs no
+There is no scope or stream underneath: the body is read before the handler runs, so a sync handler needs no
 `await`. `Request("POST", "/users", body=b"...")`
 builds one by hand, which is how a test calls the handler; `query` takes the raw string or a dict.
 
@@ -180,45 +198,35 @@ so a module-level `NOT_FOUND = Response(404, "no")` is safe to reuse.
 `{"detail": "..."}` with that status; `detail` defaults to the standard phrase. `req.json()` raises it as a 400.
 
 Any other exception is a 500 with the body `Internal Server Error`; the traceback goes to the `matchapi` logger
-together with the method and path. Nothing of the exception reaches the client.
+together with the method and path. Nothing of the exception reaches the client. An exception from the iterator of a streaming body is logged the
+same way; the status is out already, so the stream just ends. A client that leaves in the middle of a stream is
+granian's business, not an error of the handler.
 
 ### Sync or async, the same way
 
-`def handle(req)` and `async def handle(req)` are both fine. A sync handler runs in a thread pool, an async one in
-the event loop; both are served by the same uvicorn. The kind of handler is read from the result of a call, not
-from the function, so a `functools.partial`, a callable object or a compiled function all work, and a sync
-function that returns a coroutine from some branches is awaited on those.
+`def handle(req)` and `async def handle(req)` are both fine. A sync handler runs in a thread, an async one in the
+event loop. The kind of handler is read from the result of a call, not from the function, so a
+`functools.partial`, a callable object or a compiled function all work, and a sync function that returns a
+coroutine from some branches is awaited on those.
 
 ## Running
 
-```console
-$ matchapi app                      # app.py in the working directory, its function `handle`
-$ matchapi app:serve                # another function
-$ matchapi api.users                # a module in a package
-$ matchapi app --host 0.0.0.0 --port 80 --workers 4
-$ matchapi app --reload             # development
-$ python -m matchapi app            # the same command
-```
-
-Without `:function`, the command takes `handle`, and if there is none, the only public function the module defines.
-The server is uvicorn, the one dependency of the package. `--workers` and `--reload` make every process load the
-module itself.
-
-For a server of your own, `matchapi.app(handle)` is an ASGI application:
-
-```python
-# asgi.py
-import matchapi
-from app import handle
-
-app = matchapi.app(handle)
-```
+The server is [granian](https://github.com/emmett-framework/granian), the one dependency of the package; the
+decorated function is an [RSGI](https://github.com/emmett-framework/granian/blob/master/docs/spec/RSGI.md)
+application, granian's native interface.
 
 ```console
-$ uvicorn asgi:app
-$ granian --interface asgi asgi:app
+$ granian app:handle                                # app.py in the working directory, its function `handle`
+$ granian api.users:handle                          # a module in a package
+$ granian app:handle --host 0.0.0.0 --port 80 --workers 4
+$ granian app:handle --http 2                       # HTTP/2 without TLS (h2c)
+$ granian app:handle --reload                       # development; needs `pip install 'granian[reload]'`
+$ python -m granian app:handle                      # the same command
 ```
 
+`--workers` and `--reload` make every process import the module itself. The rest of the options, TLS, an event
+loop, access logs, are granian's: `granian --help`.
+
 ## Testing
 
 The handler is a function and `Request` is a constructor, so a test needs no client and no server:
@@ -252,6 +260,7 @@ line matter, `matchapi.respond(value)` turns a return value into the `Response`
 **Authorization** is a line before the `match`:
 
 ```python
+@matchapi.app
 async def handle(req):
     if req.headers.get("authorization") != f"Bearer {TOKEN}":
         return 401
@@ -262,6 +271,7 @@ async def handle(req):
 **Two services in one process** are two functions and a prefix:
 
 ```python
+@matchapi.app
 async def handle(req):
     match req.route:
         case _, "users", *rest:
@@ -277,6 +287,7 @@ async def handle(req):
 ```python
 from dataclasses import dataclass
 
+import matchapi
 from matchapi import HTTPError
 
 
@@ -286,6 +297,7 @@ class NewUser:
     age: int = 0
 
 
+@matchapi.app
 async def handle(req):
     match req.route:
         case "POST", "users":
@@ -306,18 +318,20 @@ return Response(200, (chunk for chunk in lines()))
 
 ## What matchapi does not do
 
-No router or decorators, no middleware stack, no parameter conversion from type hints, no OpenAPI, no cookies or
-sessions, no templates, no static files, no websockets, no streaming request bodies, no WSGI. Each of these is
-either a few lines in the handler or a job for an ASGI middleware wrapped around `matchapi.app(handle)`.
+No router or decorators for routes, no middleware stack, no parameter conversion from type hints, no OpenAPI, no
+cookies or sessions, no templates, no static files, no websockets, no streaming request bodies, no ASGI or WSGI.
+Each of these is either a few lines in the handler or not matchapi's job: the server is granian and the only
+interface is RSGI, so there is no middleware layer to plug into.
 
-The line is deliberate. The framework fits in one file of about 300 lines that reads in half an hour, and the
-handler stays a function that works without it.
+The line is deliberate. The framework fits in one file of about 200 lines that reads in half an hour, and the
+handler stays a function that works without a server.
 
 ## Design notes
 
 The decisions and the alternatives that were rejected are in [docs/design.md](docs/design.md): why the router
-went instead of the signature magic, why there is a command rather than an `app = ...` line, why the body is read
-before the call, why there is only ASGI, and why there is no compiled core.
+went instead of the signature magic, why a decorator rather than a command, why the body is read before the
+call, why there is only RSGI through granian, and why there is no compiled core. [CONTEXT.md](CONTEXT.md) is the
+glossary. [bench/](bench/) measures the framework's own share of a request.
 
 ## Development
 

{matchapi-0.1.0 → matchapi-0.2.1}/README.md

@@ -7,8 +7,16 @@
 
 An HTTP service is one function. `match` replaces the router.
 
+A one-file Python web framework for [granian](https://github.com/emmett-framework/granian) over
+[RSGI](https://github.com/emmett-framework/granian/blob/master/docs/spec/RSGI.md), granian's native Rust-backed
+interface: no router, no middleware, no ASGI adapter. Python 3.11+.
+
 ```python
 # app.py
+import matchapi
+
+
+@matchapi.app
 async def handle(req):
     match req.route:
         case "GET", "ping":
@@ -24,11 +32,12 @@ async def handle(req):
 
 ```console
 $ pip install matchapi
-$ matchapi app
-INFO:     Started server process [62579]
-INFO:     Waiting for application startup.
-INFO:     Application startup complete.
-INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+$ granian app:handle
+[INFO] Starting granian (main PID: 505)
+[INFO] Listening at: http://127.0.0.1:8000
+[INFO] Spawning worker-1 with PID: 512
+[INFO] Started worker-1
+[INFO] Started worker-1 runtime-1
 ```
 
 ```console
@@ -38,24 +47,24 @@ $ curl localhost:8000/users/42
 {"id":42,"name":"ann"}
 $ curl -i -X POST localhost:8000/users -d '{"name": "bob"}'
 HTTP/1.1 201 Created
-date: Mon, 12 Oct 2026 00:10:08 GMT
-server: uvicorn
 content-type: application/json
 content-length: 21
+server: granian
+date: Mon, 12 Oct 2026 01:26:59 GMT
 
 {"id":7,"name":"bob"}
 $ curl -i localhost:8000/nothing
 HTTP/1.1 404 Not Found
-date: Mon, 12 Oct 2026 00:10:08 GMT
-server: uvicorn
 content-type: text/plain; charset=utf-8
 content-length: 9
+server: granian
+date: Mon, 12 Oct 2026 01:26:59 GMT
 
 Not Found
 ```
 
-No decorators, no route table, no schema classes, no dependency markers. The file above does not even import
-`matchapi`: it is a Python function that takes a request and returns a value, and it can be called like one.
+One import and one decorator; no route table, no schema classes, no dependency markers, no middleware stack. The
+decorated `handle` is still the function it was: a test calls it with a request and compares the return value.
 
 - [Why](#why)
 - [The model](#the-model)
@@ -81,7 +90,8 @@ models. A service with three endpoints pays for all of it.
 Python has had structural pattern matching since 3.10. A `match` over `(method, *segments)` is a router already:
 it binds path parameters, it falls through to a default, it nests, and the language, not a library, defines how it
 reads. matchapi is what is left of a framework once the router is gone: a `Request`, a `Response`, the rules that
-turn a return value into one, and a command that serves a module.
+turn a return value into one, and a decorator that lets [granian](https://github.com/emmett-framework/granian)
+serve the function.
 
 ## The model
 
@@ -90,6 +100,11 @@ turn a return value into one, and a command that serves a module.
 The service is a function that takes a `Request` and returns something. That is the whole contract. A function is
 easy to test, easy to compose, easy to move: two services in one process are a function that calls two others.
 
+`@matchapi.app` marks the function as the application granian runs. It changes nothing about the function:
+`handle(req)` calls it, `handle.__name__` and `handle.__doc__` are its own. The one thing that differs is
+`inspect.iscoroutinefunction(handle)`, which is `False` for the decorated object; matchapi itself never asks it,
+it looks at what a call returns.
+
 ### `req.route` is the subject of `match`
 
 `req.route` is a tuple of the method followed by the non-empty path segments: `GET /users/42` is
@@ -119,11 +134,11 @@ strings for the cases where a plain comparison reads better.
 | `path` | `str` | `"/users/42"` |
 | `route` | `tuple[str, ...]` | `("POST", "users", "42")` |
 | `query` | `dict[str, str]`, last value wins | `{"q": "x"}` |
-| `headers` | `dict[str, str]`, lower-case names | `{"content-type": "application/json"}` |
+| `headers` | `dict[str, str]`, lower-case names, last value wins | `{"content-type": "application/json"}` |
 | `body` | `bytes`, read in full before the call | `b'{"name": "bob"}'` |
 | `json()` | the body as JSON; a broken body is a 400 | `{"name": "bob"}` |
 
-There is no `scope` or stream underneath: the body is read before the handler runs, so a sync handler needs no
+There is no scope or stream underneath: the body is read before the handler runs, so a sync handler needs no
 `await`. `Request("POST", "/users", body=b"...")`
 builds one by hand, which is how a test calls the handler; `query` takes the raw string or a dict.
 
@@ -151,45 +166,35 @@ so a module-level `NOT_FOUND = Response(404, "no")` is safe to reuse.
 `{"detail": "..."}` with that status; `detail` defaults to the standard phrase. `req.json()` raises it as a 400.
 
 Any other exception is a 500 with the body `Internal Server Error`; the traceback goes to the `matchapi` logger
-together with the method and path. Nothing of the exception reaches the client.
+together with the method and path. Nothing of the exception reaches the client. An exception from the iterator of a streaming body is logged the
+same way; the status is out already, so the stream just ends. A client that leaves in the middle of a stream is
+granian's business, not an error of the handler.
 
 ### Sync or async, the same way
 
-`def handle(req)` and `async def handle(req)` are both fine. A sync handler runs in a thread pool, an async one in
-the event loop; both are served by the same uvicorn. The kind of handler is read from the result of a call, not
-from the function, so a `functools.partial`, a callable object or a compiled function all work, and a sync
-function that returns a coroutine from some branches is awaited on those.
+`def handle(req)` and `async def handle(req)` are both fine. A sync handler runs in a thread, an async one in the
+event loop. The kind of handler is read from the result of a call, not from the function, so a
+`functools.partial`, a callable object or a compiled function all work, and a sync function that returns a
+coroutine from some branches is awaited on those.
 
 ## Running
 
-```console
-$ matchapi app                      # app.py in the working directory, its function `handle`
-$ matchapi app:serve                # another function
-$ matchapi api.users                # a module in a package
-$ matchapi app --host 0.0.0.0 --port 80 --workers 4
-$ matchapi app --reload             # development
-$ python -m matchapi app            # the same command
-```
-
-Without `:function`, the command takes `handle`, and if there is none, the only public function the module defines.
-The server is uvicorn, the one dependency of the package. `--workers` and `--reload` make every process load the
-module itself.
-
-For a server of your own, `matchapi.app(handle)` is an ASGI application:
-
-```python
-# asgi.py
-import matchapi
-from app import handle
-
-app = matchapi.app(handle)
-```
+The server is [granian](https://github.com/emmett-framework/granian), the one dependency of the package; the
+decorated function is an [RSGI](https://github.com/emmett-framework/granian/blob/master/docs/spec/RSGI.md)
+application, granian's native interface.
 
 ```console
-$ uvicorn asgi:app
-$ granian --interface asgi asgi:app
+$ granian app:handle                                # app.py in the working directory, its function `handle`
+$ granian api.users:handle                          # a module in a package
+$ granian app:handle --host 0.0.0.0 --port 80 --workers 4
+$ granian app:handle --http 2                       # HTTP/2 without TLS (h2c)
+$ granian app:handle --reload                       # development; needs `pip install 'granian[reload]'`
+$ python -m granian app:handle                      # the same command
 ```
 
+`--workers` and `--reload` make every process import the module itself. The rest of the options, TLS, an event
+loop, access logs, are granian's: `granian --help`.
+
 ## Testing
 
 The handler is a function and `Request` is a constructor, so a test needs no client and no server:
@@ -223,6 +228,7 @@ line matter, `matchapi.respond(value)` turns a return value into the `Response`
 **Authorization** is a line before the `match`:
 
 ```python
+@matchapi.app
 async def handle(req):
     if req.headers.get("authorization") != f"Bearer {TOKEN}":
         return 401
@@ -233,6 +239,7 @@ async def handle(req):
 **Two services in one process** are two functions and a prefix:
 
 ```python
+@matchapi.app
 async def handle(req):
     match req.route:
         case _, "users", *rest:
@@ -248,6 +255,7 @@ async def handle(req):
 ```python
 from dataclasses import dataclass
 
+import matchapi
 from matchapi import HTTPError
 
 
@@ -257,6 +265,7 @@ class NewUser:
     age: int = 0
 
 
+@matchapi.app
 async def handle(req):
     match req.route:
         case "POST", "users":
@@ -277,18 +286,20 @@ return Response(200, (chunk for chunk in lines()))
 
 ## What matchapi does not do
 
-No router or decorators, no middleware stack, no parameter conversion from type hints, no OpenAPI, no cookies or
-sessions, no templates, no static files, no websockets, no streaming request bodies, no WSGI. Each of these is
-either a few lines in the handler or a job for an ASGI middleware wrapped around `matchapi.app(handle)`.
+No router or decorators for routes, no middleware stack, no parameter conversion from type hints, no OpenAPI, no
+cookies or sessions, no templates, no static files, no websockets, no streaming request bodies, no ASGI or WSGI.
+Each of these is either a few lines in the handler or not matchapi's job: the server is granian and the only
+interface is RSGI, so there is no middleware layer to plug into.
 
-The line is deliberate. The framework fits in one file of about 300 lines that reads in half an hour, and the
-handler stays a function that works without it.
+The line is deliberate. The framework fits in one file of about 200 lines that reads in half an hour, and the
+handler stays a function that works without a server.
 
 ## Design notes
 
 The decisions and the alternatives that were rejected are in [docs/design.md](docs/design.md): why the router
-went instead of the signature magic, why there is a command rather than an `app = ...` line, why the body is read
-before the call, why there is only ASGI, and why there is no compiled core.
+went instead of the signature magic, why a decorator rather than a command, why the body is read before the
+call, why there is only RSGI through granian, and why there is no compiled core. [CONTEXT.md](CONTEXT.md) is the
+glossary. [bench/](bench/) measures the framework's own share of a request.
 
 ## Development
 

matchapi-0.2.1/bench/README.md

@@ -0,0 +1,46 @@
+# bench
+
+The framework's share of a request. Four servers answer the README's routes, `oha` hits each one, and the table
+is the result:
+
+- **bare RSGI, granian**: [bare.py](bare.py), an RSGI application with no framework; the ceiling, what granian
+  does alone.
+- **bare RSGI reading the body, granian**: [bare_body.py](bare_body.py), the same one with `await protocol()`
+  first, which matchapi must do because the body is read before the handler runs
+  ([design.md](../docs/design.md), D3).
+- **matchapi, granian**: [service.py](service.py), the README's service.
+- **matchapi 0.1.0, uvicorn**: [service_asgi.py](service_asgi.py), the same service as 0.1.0 wrote it, served by
+  the `matchapi` command of 0.1.0 (uvicorn, no uvloop or httptools, access log on, since the command had no flag
+  for either); installed from PyPI into a throwaway environment by `uv`.
+
+```console
+$ uv run bench/run.py                 # 10 s per server and path, 64 connections
+$ uv run bench/run.py -z 3s -c 16     # a quick look
+```
+
+Needs [oha](https://github.com/hatoo/oha) and `uv` on the PATH. The bench is not part of CI: the numbers below
+are one run on one laptop, and only the ratios between the rows mean anything.
+
+## Results
+
+Python 3.14.6, Darwin arm64, 2026-10-12; oha, 64 connections, 10s per cell, one worker.
+
+| Server | Path | Requests/s | p50 ms | p99 ms | Of the ceiling |
+|---|---|---:|---:|---:|---:|
+| bare RSGI, granian | `/ping` | 46,381 | 1.36 | 2.08 | 100% |
+| bare RSGI, granian | `/users/42` | 40,847 | 1.54 | 2.43 | 100% |
+| bare RSGI reading the body, granian | `/ping` | 26,550 | 2.38 | 3.22 | 57% |
+| bare RSGI reading the body, granian | `/users/42` | 24,841 | 2.55 | 3.57 | 61% |
+| matchapi, granian | `/ping` | 23,788 | 2.65 | 4.08 | 51% |
+| matchapi, granian | `/users/42` | 22,853 | 2.78 | 3.65 | 56% |
+| matchapi 0.1.0, uvicorn | `/ping` | 9,831 | 6.44 | 7.42 | 21% |
+| matchapi 0.1.0, uvicorn | `/users/42` | 9,580 | 6.57 | 8.84 | 23% |
+
+What the rows say:
+
+- Reading the body before the handler costs about forty percent of the ceiling on a request that has no body:
+  the one `await protocol()` is the expensive part of serving a route that answers from memory.
+- matchapi's own code, the `Request`, the `match`, the response rules, is the rest: about ten percent of a bare
+  application that reads the body the same way, a few microseconds per request. That is the share D8 of
+  [design.md](../docs/design.md) keeps an eye on.
+- 0.2.0 under granian serves about 2.4 times the requests of 0.1.0 under uvicorn. Most of that is the server.

matchapi-0.2.1/bench/bare.py

@@ -0,0 +1,16 @@
+"""A bare RSGI application with the README's routes: the ceiling, what granian does with no framework at all."""
+
+import json
+
+TEXT = [("content-type", "text/plain; charset=utf-8")]
+JSON = [("content-type", "application/json")]
+
+
+async def app(scope, protocol):
+    if scope.method == "GET" and scope.path == "/ping":
+        protocol.response_str(200, TEXT, "pong")
+    elif scope.method == "GET" and scope.path.startswith("/users/"):
+        body = json.dumps({"id": int(scope.path[7:]), "name": "ann"}, separators=(",", ":"))
+        protocol.response_bytes(200, JSON, body.encode())
+    else:
+        protocol.response_str(404, TEXT, "Not Found")

matchapi-0.2.1/bench/bare_body.py

@@ -0,0 +1,8 @@
+"""The bare RSGI application that also reads the body before answering, as matchapi must (design.md, D3)."""
+
+from bare import app as answer
+
+
+async def app(scope, protocol):
+    await protocol()
+    await answer(scope, protocol)