Skip to content

Instantly share code, notes, and snippets.

@pimlock
Created September 9, 2026 17:23
Show Gist options
  • Select an option

  • Save pimlock/0181bae8a8136551040490baf88b27d3 to your computer and use it in GitHub Desktop.

Select an option

Save pimlock/0181bae8a8136551040490baf88b27d3 to your computer and use it in GitHub Desktop.
OpenShell PR #3074: HTTP response middleware state machine and channel lifecycle

HTTP response middleware state machine

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.

Two independent lifetimes

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.

Per-stage channel states

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 --> [*]
Loading

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.

Decisions and failures

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.

HTTP delivery states

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 --> [*]
Loading
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.

Buffering changes when commitment happens

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.

Terminal cleanup

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.

Source anchors

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment