Companion note for OpenShell PR #3074, checked against commit 555ff32896a225020b670902a601707624bbadc5 on September 9, 2026. This describes the contract and runtime behavior, with conceptual state names rather than proposed Rust types.
Each middleware stage owns one response RPC stream for one upstream HTTP response. Separately, the relay owns delivery of that response to the sandbox. Closing a stage can leave delivery running. Stopping delivery ends all remaining stages.
The middleware RPC lifetime is also separate from the reusable service connection. Ending this RPC does not imply tearing down the service's shared gRPC connection.
stateDiagram-v2
[*] --> AwaitPreflight
AwaitPreflight --> Buffering: inspect whole body
AwaitPreflight --> ReadyForBody: inspect stream
AwaitPreflight --> Closed: skip / headers-only
Buffering --> AwaitBodyResult: complete body
ReadyForBody --> AwaitBodyResult: send body unit
AwaitBodyResult --> ReadyForBody: valid nonfinal pass / transform
AwaitBodyResult --> ReadyForTrailers: valid final pass / transform
ReadyForTrailers --> AwaitTrailersResult: send trailers
AwaitTrailersResult --> Closed: valid result
AwaitBodyResult --> Closed: skip_remaining
Closed --> [*]
Failure, valid block, cancellation, or disconnect can also terminate an open stage. Their effects on other stages and HTTP delivery are described below. Semantically bodyless responses omit body and trailer events.
Each exchange sends one event and waits for one corresponding result. Body sequence numbers start at 1 and are local to each stage. The handler validates the result before applying its action or mutations.
end_of_stream marks the final body unit, not the end of the RPC. A normally completing body stage receives exactly one trailers event, even when the trailers are empty, then best-effort session_end. An empty body can produce an empty final unit. The relay may also send an empty final unit after the last nonempty unit.
Closed is terminal. A closed stage receives no later body or trailer events, and the runtime never resumes that RPC for later units.
| Event | Current stage | Current input and remaining chain |
|---|---|---|
Preflight skip |
End with StageSkipped |
Continue to the next stage without mutation. |
Preflight HEADERS_ONLY |
Apply valid header mutations, then end with Normal |
Later stages run; this stage receives no body or trailers. |
Body pass_through |
Remain active | Forward this stage's input through later stages. |
Body transform |
Remain active | Forward the replacement through later stages. A present empty replacement deletes this unit. |
Body skip_remaining |
Apply its nested pass/transform action, then end with Normal |
Current output and later units continue through other stages. Only this stage is bypassed. |
| Failure with fail-open | Disable this stage for the rest of the response; end with MiddlewareFailure when possible |
Preserve the input to the failed exchange and continue through later stages. |
| Failure with fail-closed | End this stage and terminate the response session | Stop evaluation and delivery; end the other open stages. |
Valid block_delivery |
End all open stages with MiddlewareDenial |
Stop evaluation and delivery regardless of on_error. |
| Successful trailers result | Apply valid trailer mutations; end normally after chain finalization | Complete the response. |
Fail-open preserves the input to the failing stage. Suppose A transforms hello into HELLO, B fails, and C remains active. C receives HELLO. Successful earlier header mutations and body transformations remain applied. A failed trailer mutation preserves the incoming trailers and lets later stages process them.
Fail-open does not retry the failed stage on the next unit. This prevents a late result after a timeout from being interpreted as the next unit's result.
Timeouts, transport errors, unexpected result-stream closure, wrong result variants or sequence numbers, missing actions, invalid mutations, and exceeded limits follow the stage's on_error. The runtime validates the entire result, including diagnostics. An invalid result containing block_delivery is a middleware failure, not an accepted denial.
Decisions take effect in policy order. Once an earlier fail-closed failure stops evaluation, a later stage cannot override it with a block. A response block also cannot undo the upstream request, which has already run.
stateDiagram-v2
[*] --> Uncommitted
Uncommitted --> Committed: attempt final response header write
Uncommitted --> Rejected: block gives 403 / fail-closed gives 502
Committed --> Completed: body and trailers finish
Committed --> Aborted: block / fail-closed / delivery failure
Rejected --> [*]
Completed --> [*]
Aborted --> [*]
| Event | Before final-response commitment | After commitment |
|---|---|---|
| Valid block | Send canonical 403 middleware-denial response, then close downstream. | Abort delivery. |
| Fail-closed middleware failure | Send canonical 502 delivery-failure response, then close downstream. | Abort delivery. |
| Fail-open middleware failure | Continue processing; commit when ready. | Continue processing and delivery. |
An abort sends no replacement error body, terminating chunk, or error trailer. The sandbox sees an incomplete response; bytes already delivered cannot be withdrawn. The upstream connection must not be reused after a denial or terminal delivery failure. For HEAD, a canonical error response includes headers and Content-Length but no body.
Commitment starts before attempting the final header write. A write can fail after sending a prefix, so treating that failure as uncommitted could append a second HTTP response behind a partial first response. Interim responses do not commit the final response.
With streaming inspection and no whole-body stage, the PR sends final response headers before inspecting the first body unit. Even a block on the first unit therefore aborts delivery rather than returning a 403.
An active whole-body stage buffers its input and prevents final-response commitment. On normal completion, the runtime finalizes body processing and trailers before sending the approved response. Multiple stages run in policy order; the first buffering stage holds input until it can release it to later stages.
Whole-body capacity or accumulation-deadline failures follow each affected stage's on_error. Fail-open disables that stage and releases retained input through the remaining chain. Once no whole-body stage remains pending, released output can cause the relay to commit and continue streaming. Subsequent terminal failures then abort.
Body units are normalized byte units, not application messages or transport chunks. Each replacement fully accounts for its input unit. The contract does not permit middleware to hold some input bytes for a later replacement.
The implementation represents activity with an optional transport. Ending a stage takes that transport, attempts to send session_end for up to 10 ms, then drops its event sender and result stream. No acknowledgement is expected.
Terminal notification is best effort. Some preflight failure paths drop the transport directly, and cancellation can prevent notification. Middleware must clean up on RPC closure as well as on session_end. A body EOS marker alone is not sufficient for cleanup because trailers may still follow.
Policy reload, upstream disconnect, and downstream disconnect terminate the response session and close remaining stages. Those are lifecycle failures, not middleware opt-out decisions.