You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 0c69f86
Browse filesBrowse the repository at this point in the historyBrowse files
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]>
Copy file name to clipboardExpand all lines: docs/extensibility/supervisor-middleware/configure.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -173,7 +173,7 @@ The map key, such as `content-guard`, is the entry's stable identity in logs. Ea
173
173
174
174
### Mix HTTP Hook Versions
175
175
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`.
Copy file name to clipboardExpand all lines: docs/extensibility/supervisor-middleware/operations.mdx
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -99,7 +99,7 @@ OpenShell removes body modes that cannot safely inspect or transform the message
99
99
| Bodyless response, partial response, or `Cache-Control: no-transform`| Not applicable | No body modes |
100
100
| Declared length exceeds the stage's payload limit | No WHOLE_BODY | No WHOLE_BODY |
101
101
|`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 |
103
103
104
104
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.
105
105
@@ -129,12 +129,12 @@ HTTP hooks always fail closed. The gateway rejects `on_error: fail_open` for the
129
129
130
130
| Result | Before forwarding starts | After forwarding starts |
131
131
| --- | --- | --- |
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. |
133
133
| Request failure |`403 Forbidden`, `error: middleware_failed`| Close the upstream connection before the request completes. |
134
134
| Response `block_delivery`|`403 Forbidden`, `error: middleware_denied`| Abort response delivery without an error body. |
135
135
| Response failure |`502 Bad Gateway`, `error: response_delivery_failed`| Abort response delivery without an error body. |
136
136
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:
Copy file name to clipboardExpand all lines: docs/how-it-works/gateways/configuration.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -801,7 +801,7 @@ The gateway connects to every registered service and validates `Describe` before
801
801
802
802
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.
803
803
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.
805
805
806
806
`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.
Copy file name to clipboardExpand all lines: docs/observability/logging.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -252,7 +252,7 @@ An upstream that the proxy cannot reach returns `502 Bad Gateway`:
252
252
253
253
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).
254
254
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.
256
256
257
257
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.
0 commit comments