feat(middleware): define HTTP response pre-return interface

[pimlock]

Summary

Define the public HTTP_RESPONSE/PRE_RETURN contract without enabling response processing in the proxy. This lets reviewers evaluate the protobuf lifecycle, naming, extensibility, and transport shape independently from the runtime implementation.

The proposed stream begins with a preflight action, uses lockstep pass-through or transform actions for body units, marks the final unit with end_of_stream, and ends with a shared middleware session-end reason plus typed protocol-error detail.

API interaction examples

See HTTP response pre-return middleware API interaction examples for whole-body, streaming, skip, and block-delivery exchanges, failure scenarios, and an illustrative Rust/tonic middleware implementation.

Related Issue

Part of #2691

Changes

• Add the bidirectional HttpResponsePreReturn.Evaluate service with preflight, body unit, body result, and terminal event messages.
• Preflight returns skip, inspect, or block_delivery; body results return pass_through or transform. OpenShell tells each stage which body modes it may select and whether it may defer bytes across units.
• The final body unit carries end_of_stream. Response trailers are deferred from V1 with field numbers reserved.
• Share MiddlewareSessionEnd and its reason enum across streaming middleware APIs, with disconnects split by direction and typed protocol-error detail.
• Accept the HTTP_RESPONSE/PRE_RETURN manifest binding and add in-process and remote gRPC stream interfaces.
• Compile the content-guard example in lint and branch checks.

Breaking changes

WebSocketSessionEndReason and WebSocketSessionEnd are replaced by the shared MiddlewareSessionEndReason and MiddlewareSessionEnd. NORMAL_CLOSE is now NORMAL, UPSTREAM_REJECTED is now UPSTREAM_FAILURE, and PEER_DISCONNECT is split into DOWNSTREAM_DISCONNECT and UPSTREAM_DISCONNECT. Enum numbers are unchanged, so binary wire compatibility is preserved; generated symbols and JSON names change. This lands in the pre-0.1.0 window.

Testing

• mise run pre-commit passes
• mise run test passes
• Unit tests added/updated
• E2E tests added/updated, deferred to feat(network): inspect HTTP responses before return #3074

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated, deferred to docs(middleware): document response pre-return workflow #3075

Stack

1. feat(middleware): broaden HTTP header mutation authority #3072 - shared header mutation authority
2. feat(middleware): define HTTP response pre-return interface #3073 - response protobuf and transport interface
3. feat(network): inspect HTTP responses before return #3074 - response runtime, relay integration, and existing example
4. docs(middleware): document response pre-return workflow #3075 - documentation and middleware guide reorganization

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.