Supported Operations

The request body, target, headers, and request context.

• Allow the request unchanged.
• Deny the request with an optional reason code.
• Replace the body, up to the same payload limit as the input.
• Add, change, or remove headers.

When your service replaces the body, OpenShell checks the new body against body-aware policy, such as GraphQL, JSON-RPC, or MCP rules, before the next middleware or the external service sees it. A replacement cannot introduce an operation that policy denies.

When your service denies a request, the sandbox receives a structured error and OpenShell does not contact the external service:

{
  "error": "middleware_denied",
  "detail": "Request rejected by configured middleware",
  "policy": "api-policy",
  "middleware": "content-guard",
  "reason_code": "content_match"
}

When middleware fails, the sandbox receives error: middleware_failed instead.

A result can include an ordered list of header changes. A write change sets how it treats an existing header with the same name:

• append adds another value.
• overwrite replaces all existing values.
• skip keeps the existing values.

A remove change removes all values for the name. OpenShell protects credential, routing, framing, and connection headers, and for responses also status, authentication challenge, content coding, range, and security policy headers. Header values cannot contain control characters, and request header values cannot contain OpenShell credential placeholders.

OpenShell applies each middleware’s changes as a unit. If one change is invalid, it discards all of them and treats the result as a middleware failure.

The preflight includes the status and headers. A preflight result can skip inspection, block delivery with block_delivery, or inspect the response with one body mode:

Body inspection is unavailable for responses without a body, partial responses, compressed responses, and responses with Cache-Control: no-transform. For those, a middleware that requests body inspection fails. Interim 1xx responses pass through unchanged, and a 101 protocol upgrade skips response middleware.

• Pass the response or body piece unchanged.
• Replace the body or a body piece.
• Add, change, or remove headers, with the same rules as requests.
• Block delivery with an optional reason code.

If your service blocks the response before OpenShell starts sending it, the sandbox receives 403 Forbidden with the same middleware_denied error as a denied request. If middleware fails before then, the sandbox receives 502 Bad Gateway with error: response_delivery_failed. If delivery has already started, OpenShell aborts the response in both cases.

The external service has already handled the request, so blocking its response does not undo it, and retrying the request may repeat side effects.

A service that inspects the body also receives trailers after the body. A preflight can declare new trailer names, and the service can then add them.

After middleware changes the body, OpenShell recalculates Content-Length and framing, so your service never handles transfer encoding.

OpenShell opens one bidirectional stream to your service for each connection and sends these events:

1. A preflight before contacting the external service. Your service returns INSPECT, SKIP, or DENY. SKIP closes the middleware stream and passes all messages without inspection by that middleware. DENY rejects the upgrade.
2. A session start after the external service accepts the connection. It includes the negotiated subprotocol.
3. Each complete text message from the sandbox, in order.
4. A session end when the connection closes, sent on a best-effort basis.

Your service returns a result for each preflight and message. Session start and end are notifications that need no result. When OpenShell closes its side of the stream, finish your side of the stream too.

OpenShell reassembles fragmented messages and decompresses permessage-deflate messages before sending them, so your service always receives a complete UTF-8 text message. A replacement can be any text, including an empty string. OpenShell re-frames and, when needed, re-compresses the replacement before forwarding it.

OpenShell does not send binary messages, control frames, or messages from the external service to middleware. Binary messages pass through unchanged, and OpenShell records an unsupported_message_type coverage event. Message sequence numbers count binary messages too, so your service can see gaps between text messages.

Only middleware that declares WEBSOCKET_MESSAGE receives messages. Middleware that declares only HTTP_REQUEST still inspects the upgrade request, and OpenShell records a binding_not_selected coverage event for it.

A denied message closes the connection with code 1008. When middleware fails, OpenShell rejects the upgrade or closes the connection. With fail_open, OpenShell instead stops using that middleware for the rest of the connection.