# 0042: Explicit, bounded streaming request bodies

- Status: Accepted
- Date: 2026-08-27
- Supersedes: none
- Related: [ADR 0015](0015-static-module-http-routing-and-runtime-lifecycle.md),
  [ADR 0017](0017-public-request-perimeter-hardening.md),
  [ADR 0030](0030-host-provided-module-object-storage.md),
  [ADR 0031](0031-direct-object-delivery.md)

## Context

ADR 0017 gave every public route an enforced request-body ceiling and capped a module route at
1 MiB, with an explicit note that "large media transfer belongs to a future dedicated storage
design, never to widening this ceiling."

The storage design arrived — ADR 0030 gave modules a scoped object store, ADR 0031 took Ekklesia out
of the *read* path with signed delivery URLs — and it did not solve the *write* path. ADR 0031
deliberately declined to offer signed write URLs, so the only way bytes reach a module's bucket is
through that module's own HTTP route. That route is capped at 1 MiB, and an ordinary photograph is
not 1 MiB. A church uploading a slide for a lobby screen cannot, today, get the file in.

Two properties of the existing implementation also need naming, because they are what the change has
to preserve and what it has to fix:

- The pinned body-limit middleware **fully buffers** any body with no declared `Content-Length`
  before deciding. At 1 MiB that is a bounded, acceptable cost. At image sizes it would mean the
  platform holding every concurrent upload in memory.
- With a declared `Content-Length` within the limit it *counts nothing at all*, trusting the header.
  Node's HTTP framing makes that safe today, but it is trust the platform does not need to extend.

## Decision

Extend the existing route contract. There is no second HTTP system, no upload endpoint, no signed
write URL, and no new middleware stack — one route declaration, one limiter, one `413`.

### A route declares how its body reaches it

`ModuleRouteDefinitionInput` gains one optional field:

```ts
http.route({
  method: "POST",
  path: "/uploads",
  permission: "signage.slides.write",
  maxBodyBytes: 33_554_432,
  bodyMode: "streamed",
  handler,
});
```

- **`buffered`** (the default, and what every route written before this meant) — the platform reads
  and counts the whole body **before** the handler runs, so the handler is promised a fully
  available, bounded body and an oversized request is rejected before any authorization or handler
  work happens. Ceiling: 1 MiB, unchanged.
- **`streamed`** — the platform counts bytes **as the handler consumes them** and never materializes
  the body. Ceiling: 32 MiB.

The mode is **explicit rather than inferred from the size**. Inferring it — "over 1 MiB means
streamed" — would mean an author who raised a limit silently changed how their own handler receives
its body, and when a `413` can arrive relative to their own code. That is exactly the class of
invisible change this repository refuses.

Omitting the field means `buffered`, so no existing route changed behaviour, and the canonical parsed
form always carries a mode so nothing downstream re-applies the default or disagrees about it.

### The ceilings, and why 32 MiB

`MODULE_ROUTE_MAX_BODY_BYTES_CEILING` stays at 1 MiB for buffered bodies: a body the platform
materializes is a body the platform is holding, and 1 MiB is the most a JSON request has any business
being.

`MODULE_ROUTE_STREAMED_MAX_BODY_BYTES_CEILING` is 32 MiB, sized to hold one 25 MiB image plus bounded
overhead — a multipart envelope, its boundaries and part headers, and room for a client that pads. It
is also `MODULE_ROUTE_ABSOLUTE_MAX_BODY_BYTES`: **no route, in any mode, may declare or accept a
larger single request body, and no unbounded option exists anywhere in the contract.** A route
declaring more than its mode's ceiling fails registration, exactly as an over-ceiling value always
has.

The unit is deliberately **one file per request**. A UI offering twenty images issues twenty
individually bounded requests, each of which the platform can reject cheaply and each of which fails
alone; a 500 MiB aggregate request would make one bad byte waste everything already sent, and nothing
in this contract can express one.

### Enforcement, in one limiter

The platform's own limiter replaces the buffering dependency. It is the same code for both modes and
differs only in *when* it counts:

1. A declared `Content-Length` above the limit is refused synchronously — before authorization,
   before the handler, before a single body byte is read. That is the cheap rejection an ordinary
   too-large upload takes. A malformed or contradictory header is treated as *absent* rather than as
   a rejection, because the byte counting bounds the request either way and refusing could only turn
   a legitimate request away.
2. `buffered`: bytes are counted as they arrive and the request is rejected the moment the running
   total passes the limit — so a lying or absent `Content-Length` is bounded by what actually
   arrived rather than by what was claimed, which the previous implementation did not do. At most
   the route's own declared allowance is ever held.
3. `streamed`: the body is wrapped in a counting transform and handed to the handler. The moment the
   total passes the limit the stream errors, the source is cancelled, and the response is replaced
   with the same sanitized `413` — **even if the handler caught the error and answered anyway**. A
   limit a handler can swallow is not a limit.

A body no handler read is cancelled after the request, so an abandoned upload releases its socket
rather than draining. An aborted upload surfaces as an ordinary failed request, never a `413`:
nothing exceeded a limit.

Ordering is unchanged and remains deliberate: trusted-origin check, then the body contract, then
permission evaluation, then the handler. In `streamed` mode no body byte is read until the handler
reads it and the handler runs only after authorization succeeds, so an unauthorized caller can never
push an upload through the platform at all — strictly better than the buffered path.

Timeouts stay where they were: the server's own `headersTimeout`/`requestTimeout`. A slow upload is a
slow *request*, and the platform already has one answer for that rather than a second per-route one.

### What a module author must know

In `streamed` mode a `413` can arrive **after** the handler has started. A handler that persists as
it reads must be prepared for a partially consumed upload — write to a temporary key and commit only
after the read completes. The platform cannot do that for the module, because only the module knows
what a partial write means to its own data.

## Consequences

- An ordinary image upload works, through the route contract a module already had, with the platform
  holding none of it.
- The buffered path now counts bytes it previously trusted a header for, closing a gap rather than
  opening one.
- Every existing route and every existing test is unchanged: the default is the old behaviour, and
  the `413` contract, ordering, and sanitization are identical.
- `apps/api` owns ~60 lines of stream plumbing it previously delegated. That is the price of a
  limiter that neither buffers a large body nor can be swallowed by a handler, and it is enforced by
  tests rather than by reading the dependency's source.
- Media larger than 32 MiB — a video — still has no path in. That is deliberate and named below.

## Alternatives

- **Raise the single ceiling to 32 MiB.** Rejected: every existing route would silently gain the
  ability to have 32 MiB buffered in memory on its behalf, and `await request.json()` in a module
  handler would stop being a bounded operation.
- **Infer streaming from `maxBodyBytes`.** Rejected: it makes a size change silently change delivery
  semantics and error timing for the author's own code.
- **A separate upload endpoint or second HTTP system.** Rejected: a second route table, a second
  authorization path, a second CORS and origin policy, and a second failure vocabulary, to solve
  something the existing route contract can express with one field.
- **Signed write URLs to object storage.** Deliberately still deferred (ADR 0031). A signed write URL
  is a bearer capability to *create* an object, which needs quota, content-type, and lifecycle
  answers this pass does not have — and a module that wants to validate, transform, or authorize per
  byte cannot use one anyway.
- **Let the handler enforce its own limit.** Rejected: a limit enforced by the party being protected
  against is not a limit, and every module would reimplement it slightly differently.
- **Trust `Content-Length` in streamed mode.** Rejected: the running byte count costs nothing and
  removes the need to reason about framing at all.

## Deferred

Signed write URLs, resumable or chunked multi-request uploads, per-module or per-installation upload
quotas, content-type or magic-byte validation, virus scanning, image transformation, progress
reporting, and any body larger than the absolute ceiling — a video pipeline is its own design, not a
larger number here.