Skip to content

Commit 0c69f86

Browse files
committed
docs(middleware): align HTTP hooks contract wording with review feedback
State how zero-limit HTTP hooks bindings interact with the operator payload limit, align the HTTP/1.0 DUPLEX rule with the proto, document the 403 for a DUPLEX request denied after upstream output starts, and make failure_code wording consistent across the docs. Signed-off-by: Piotr Mlocek <[email protected]>
1 parent d390ce1 commit 0c69f86

5 files changed

Lines changed: 14 additions & 9 deletions

File tree

‎docs/extensibility/supervisor-middleware/configure.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -173,7 +173,7 @@ The map key, such as `content-guard`, is the entry's stable identity in logs. Ea
173173

174174
### Mix HTTP Hook Versions
175175

176-
Each HTTP request or response runs through middleware of one [HTTP hook version](/extensibility/supervisor-middleware/operations#http). The gateway rejects a policy in which two entries whose endpoint selectors may overlap use different HTTP hook versions for the same operation, requests or responses. To fix it, separate the selectors or move both services to the same hook version. If a chain still mixes hook versions at runtime, OpenShell blocks the traffic with the reason `middleware_hook_versions_mixed`.
176+
Each HTTP request or response runs through middleware of one [HTTP hook version](/extensibility/supervisor-middleware/operations#http). The gateway rejects a policy in which two entries whose endpoint selectors may overlap use different HTTP hook versions for the same operation, requests or responses. To fix it, separate the selectors or move both services to the same hook version. If a chain still mixes hook versions at runtime, OpenShell blocks the traffic with `error: middleware_failed` and `failure_code: middleware_hook_versions_mixed`.
177177

178178
## Choose Failure Behavior
179179

‎docs/extensibility/supervisor-middleware/operations.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ OpenShell removes body modes that cannot safely inspect or transform the message
9999
| Bodyless response, partial response, or `Cache-Control: no-transform` | Not applicable | No body modes |
100100
| Declared length exceeds the stage's payload limit | No WHOLE_BODY | No WHOLE_BODY |
101101
| `text/event-stream` or `multipart/x-mixed-replace` | No additional restriction | No WHOLE_BODY |
102-
| Request or response is not HTTP/1.1 | No additional restriction | No DUPLEX |
102+
| HTTP/1.0 is involved and the response cannot be chunked | No additional restriction | No DUPLEX |
103103

104104
A WHOLE_BODY body that exceeds the selected limit fails closed. OpenShell does not switch it to DUPLEX. If no mode suits your service, continue without inspection or deny the message with a reason code that says why.
105105

@@ -129,12 +129,12 @@ HTTP hooks always fail closed. The gateway rejects `on_error: fail_open` for the
129129

130130
| Result | Before forwarding starts | After forwarding starts |
131131
| --- | --- | --- |
132-
| Request `deny` | `403 Forbidden`, `error: middleware_denied` | Close the upstream connection before the request completes. |
132+
| Request `deny` | `403 Forbidden`, `error: middleware_denied` | Close the upstream connection before the request completes. The sandbox still receives `403 Forbidden`, `error: middleware_denied`, and OpenShell relays no upstream response. |
133133
| Request failure | `403 Forbidden`, `error: middleware_failed` | Close the upstream connection before the request completes. |
134134
| Response `block_delivery` | `403 Forbidden`, `error: middleware_denied` | Abort response delivery without an error body. |
135135
| Response failure | `502 Bad Gateway`, `error: response_delivery_failed` | Abort response delivery without an error body. |
136136

137-
Denials include the policy entry's `middleware` name and the validated `reason_code`, if supplied. Failures include a platform-owned `failure_code` and identify the failed stage when known:
137+
Denials include the policy entry's `middleware` name and the validated `reason_code`, if supplied. Both `middleware_failed` and `response_delivery_failed` bodies include a platform-owned `failure_code` and identify the failed stage when known:
138138

139139
| `failure_code` | Cause |
140140
| --- | --- |

‎docs/how-it-works/gateways/configuration.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -801,7 +801,7 @@ The gateway connects to every registered service and validates `Describe` before
801801

802802
Startup also requires compatible [extension protocol metadata](/extensibility/overview#protocol-negotiation). Upgrade legacy gateways and operator-run services together during a coordinated outage; neither mixed legacy/current pairing is supported. A service rejects a gateway that omits peer metadata, and a gateway rejects a service that omits metadata, uses another protocol major, or requires unsupported gateway capabilities. Protected `GetGatewayInfo` and `openshell gateway info` report the resulting non-secret snapshot.
803803

804-
`max_payload_bytes` limits how much payload the service inspects at once: an HTTP body or body unit, a replacement body, or a WebSocket text message. It applies to every binding the registration authorizes. The value must be at most 4 MiB and no larger than any of those bindings advertises; OpenShell rejects larger values instead of clamping them. Binary WebSocket messages pass through without inspection, so the limit does not apply to them. Configure middleware gRPC servers to accept messages of at least 4 MiB plus 293 KiB so a maximum-size payload and its protobuf envelope fit.
804+
`max_payload_bytes` limits how much payload the service inspects at once: an HTTP body or body unit, a replacement body, or a WebSocket text message. It applies to every binding the registration authorizes. The value must be at most 4 MiB and no larger than any of those bindings advertises, except that HTTP-hooks bindings advertising 0 are excluded from that comparison and always get no body modes; OpenShell rejects larger values instead of clamping them. Binary WebSocket messages pass through without inspection, so the limit does not apply to them. Configure middleware gRPC servers to accept messages of at least 4 MiB plus 293 KiB so a maximum-size payload and its protobuf envelope fit.
805805

806806
`timeout` is the operator-configured service-wide RPC timeout. It accepts the same compact duration syntax as gateway interceptors: an integer followed by `ms` or `s`, such as `500ms` or `2s`. Values must be between `10ms` and `30s`, inclusive. Omit the field to use the 500 ms platform default. A binding may advertise a shorter `timeout` in the `Describe` manifest, but it cannot extend the operator-configured deadline; OpenShell uses the smaller value. OpenShell validates both levels before accepting the service. The operator-configured service timeout applies to `Describe` and `ValidateConfig`. The effective binding timeout applies to HTTP request evaluation, HTTP response preflight and unit exchanges, WebSocket preflight, and each WebSocket message. Accepted streaming protocols have no connection-wide RPC deadline.
807807

‎docs/observability/logging.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -252,7 +252,7 @@ An upstream that the proxy cannot reach returns `502 Bad Gateway`:
252252

253253
The `error` field is a short machine-readable code (`policy_denied`, `middleware_denied`, `middleware_failed`, `ssrf_denied`, `upstream_unreachable`, `unsupported_l7_protocol`, `token_grant_failed`, or `request_timeout` with `408` when the sandbox stops sending a request body that streaming middleware holds). The `detail` field is a human-readable explanation suitable for display in an agent transcript. The optional `reason` field, when present, provides the specific denial cause from the policy engine (for example, which binary was not allowed or which rule was missing).
254254

255-
For L7 REST policy denials, the body also includes structured policy fields such as `method`, `path`, `rule_missing`, and `next_steps`. When the policy advisor is enabled, the body also includes `agent_guidance`, a short plain-language instruction telling the agent to read `/etc/openshell/skills/policy_advisor.md`, propose the narrowest rule through `http://policy.local/v1/proposals`, wait for `policy_reloaded: true`, and retry. A middleware denial instead identifies the policy-local config in `middleware` and can include a validated `reason_code`. A fail-closed runtime failure uses `middleware_failed` with platform-owned text. Under [HTTP hooks](/extensibility/supervisor-middleware/operations#failures), it also carries a platform-owned `failure_code` and, when one stage failed, its `middleware`. Both middleware responses omit `rule_missing`, `next_steps`, and `agent_guidance` because no policy rule is missing.
255+
For L7 REST policy denials, the body also includes structured policy fields such as `method`, `path`, `rule_missing`, and `next_steps`. When the policy advisor is enabled, the body also includes `agent_guidance`, a short plain-language instruction telling the agent to read `/etc/openshell/skills/policy_advisor.md`, propose the narrowest rule through `http://policy.local/v1/proposals`, wait for `policy_reloaded: true`, and retry. A middleware denial instead identifies the policy-local config in `middleware` and can include a validated `reason_code`. A fail-closed runtime failure uses `middleware_failed` with platform-owned text. Under [HTTP hooks](/extensibility/supervisor-middleware/operations#failures), it and `response_delivery_failed` also carry a platform-owned `failure_code` and, when one stage failed, its `middleware`. Both middleware responses omit `rule_missing`, `next_steps`, and `agent_guidance` because no policy rule is missing.
256256

257257
A failed [dynamic token grant](/how-it-works/providers/profiles#token-grant-failures) returns `502 Bad Gateway` with an `x-openshell-request-id` header. The forward proxy body is `{"error":"token_grant_failed","detail":"dynamic token grant failed"}`; L7 relays send an empty body. Neither states the cause, so give the request ID to someone who can read the sandbox.
258258

‎proto/supervisor_middleware.proto‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,9 @@ message MiddlewareBinding {
119119
// Required for payload-bearing operations. An HTTP binding of a service that
120120
// requires the HTTP hooks capability may leave this zero: OpenShell
121121
// then offers it no body modes, so it can only continue or deny at
122-
// preflight.
122+
// preflight. Such a binding is excluded from the comparison with the
123+
// registration's operator-configured max_payload_bytes; every other binding
124+
// uses the operator limit, which cannot exceed what that binding advertises.
123125
uint64 max_payload_bytes = 3;
124126
// Optional binding-specific RPC timeout. Empty uses the operator-configured
125127
// service timeout, or the 500ms platform default when that is also omitted.
@@ -386,8 +388,8 @@ message HttpPreflightResult {
386388
// Content-Range, and request headers omitted because they carry a credential
387389
// placeholder. OpenShell does not update integrity headers such
388390
// as ETag, Content-MD5, or Content-Digest when a body changes: a stage that
389-
// changes the body removes them or writes new values, typically in its late
390-
// head mutations. Limited to 64
391+
// changes the body removes them or writes new values, typically in
392+
// HttpWholeBodyResult.header_mutations or HttpOutputStart.header_mutations. Limited to 64
391393
// operations, 32 KiB of name/value data, and 64 KiB encoded.
392394
repeated HeaderMutation header_mutations = 3;
393395
MiddlewareDiagnostics diagnostics = 4;
@@ -494,6 +496,9 @@ message HttpFinish {
494496
// 403 middleware denial with the validated reason_code. A message already
495497
// partly delivered stays incomplete: OpenShell withholds its terminating chunk
496498
// or final byte, trailers, and any error body, and closes that connection.
499+
// A DUPLEX request denied after its output has started upstream aborts the
500+
// upstream request, relays no upstream response, and still answers the
501+
// sandbox with the canonical 403 middleware denial.
497502
// A stage that cannot inspect an HTTP message, such as a body in a format it
498503
// does not understand, denies it with a reason_code that says so.
499504
message HttpDenial {

0 commit comments

Comments
 (0)