Skip to content

chore(core): track v0.1.9-pre.4 - #45

Closed
ai-openshell-sdk-python[bot] wants to merge 1 commit into
mainfrom
core/v0.1.9-pre.4
Closed

ai-openshell-sdk-python[bot] wants to merge 1 commit into
mainfrom
core/v0.1.9-pre.4

Conversation

@ai-openshell-sdk-python

Copy link
Copy Markdown
Contributor

Move the core pin from v0.1.8 to v0.1.9-pre.4 (prerelease).

  • Core changes: v0.1.8...v0.1.9-pre.4
  • Regenerated bindings: no generated files changed
  • E2E runs against ghcr.io/nvidia/openshell/gateway:0.1.9-pre.4
  • Files copied from core:
    • none changed

Proto changes

diff --git a/proto/supervisor_middleware.proto b/proto/supervisor_middleware.proto
index 6c0cc94..c9c12a7 100644
--- a/proto/supervisor_middleware.proto
+++ b/proto/supervisor_middleware.proto
@@ -9,9 +9,24 @@ import "google/protobuf/struct.proto";
 import "google/protobuf/duration.proto";
 import "extension.proto";
 
+// Service and RPC naming.
+//
+// A middleware implements SupervisorMiddleware and the hook services for the
+// traffic it wants to inspect, all on one endpoint. Generated servers in some
+// languages, such as Python and Go, name each handler method after the RPC
+// alone, so one object that implements several of these services can have
+// only one handler per RPC name. Every RPC name must therefore be unique across
+// all services in this package, including deprecated ones.
+//
+// To add hooks for another protocol, add a <Protocol>Hooks service. Name each
+// RPC Evaluate<Protocol><Unit>Hook, after the unit it evaluates, and its
+// messages <Protocol><Unit>HookEvent and <Protocol><Unit>HookResult. For
+// example: HttpHooks.EvaluateHttpRequestHook(stream HttpRequestHookEvent)
+// returns (stream HttpRequestHookResult).
+
 // SupervisorMiddleware discovers and configures one operator-run middleware.
-// It evaluates HTTP requests and WebSocket messages before credentials.
-// Phase-specific services share the same registration.
+// It evaluates legacy HTTP requests and WebSocket messages.
+// Hook-specific services share the same registration and endpoint.
 service SupervisorMiddleware {
   // Describe returns the service manifest and declared bindings.
   rpc Describe(MiddlewareDescribeRequest) returns (MiddlewareManifest);
@@ -19,9 +34,14 @@ service SupervisorMiddleware {
   // ValidateConfig checks service-specific configuration for one binding.
   rpc ValidateConfig(ValidateConfigRequest) returns (ValidateConfigResponse);
 
+  // Deprecated: legacy HTTP hooks, removed in 0.2.0. Use
+  // HttpHooks.EvaluateHttpRequestHook.
   // EvaluateHttpRequest returns an allow, deny, or mutation decision for one
-  // buffered HTTP request.
-  rpc EvaluateHttpRequest(HttpRequestEvaluation) returns (HttpRequestResult);
+  // buffered HTTP request. OpenShell calls it for the HTTP_REQUEST bindings of
+  // a service that does not require the HTTP hooks capability.
+  rpc EvaluateHttpRequest(HttpRequestEvaluation) returns (HttpRequestResult) {
+    option deprecated = true;
+  }
 
   // EvaluateWebSocketSession opens one ordered, phase-specific stream for a
   // single middleware stage and WebSocket upgrade attempt. The current
@@ -34,20 +54,50 @@ service SupervisorMiddleware {
       returns (stream WebSocketSessionEventResult);
 }
 
+// HttpHooks evaluates HTTP messages for one operator-run middleware.
+// It shares SupervisorMiddleware's registration, discovery, configuration, and
+// endpoint. Each invocation serves one binding phase, carried in its preflight.
+service HttpHooks {
+  // HTTP hooks for requests. OpenShell calls it for the HTTP_REQUEST
+  // bindings of a service whose manifest lists
+  // openshell.supervisor-middleware.http-hooks in
+  // extension.required_capabilities. Peers that predate HTTP hooks
+  // reject such a service at Describe. One stream per request and middleware
+  // stage. The first event is a request preflight.
+  rpc EvaluateHttpRequestHook(stream HttpRequestHookEvent)
+      returns (stream HttpRequestHookResult);
+
+  // HTTP hooks for responses, for the HTTP_RESPONSE bindings of a
+  // service that requires the HTTP hooks capability. One stream per
+  // response and middleware stage. The first event is a preflight of the
+  // response head.
+  rpc EvaluateHttpResponseHook(stream HttpResponseHookEvent)
+      returns (stream HttpResponseHookResult);
+}
+
 message MiddlewareDescribeRequest {
   // Gateway or supervisor protocol metadata. Middleware must reject unmet
   // requirements before accepting traffic.
   openshell.extension.v1.PeerMetadata gateway = 1;
 }
 
+// Deprecated: legacy HTTP hooks, removed in 0.2.0. Use
+// HttpHooks.EvaluateHttpResponseHook.
 // HttpResponsePreReturn evaluates one response for one middleware stage before
-// OpenShell returns it to the sandbox.
+// OpenShell returns it to the sandbox. OpenShell calls it for the HTTP_RESPONSE
+// bindings of a service that does not require the HTTP hooks
+// capability.
 service HttpResponsePreReturn {
+  option deprecated = true;
+
+  // Deprecated: legacy HTTP hooks, removed in 0.2.0.
   // Evaluate starts with preflight and may continue with selected body units
   // and trailers. A body unit marked end_of_stream ends body inspection, not
   // the event stream. Trailers and one best-effort session_end may follow.
   rpc Evaluate(stream HttpResponseEvent)
-      returns (stream HttpResponseEventResult);
+      returns (stream HttpResponseEventResult) {
+    option deprecated = true;
+  }
 }
 
 // MiddlewareManifest describes one middleware service and its bindings.
@@ -81,7 +131,12 @@ message MiddlewareBinding {
   // Supported phase.
   SupervisorMiddlewarePhase phase = 2;
   // Maximum request body, WebSocket message, or response body unit/replacement.
-  // Required for payload-bearing operations.
+  // Required for payload-bearing operations. An HTTP binding of a service that
+  // requires the HTTP hooks capability may leave this zero: OpenShell
+  // then offers it no body modes, so it can only continue or deny at
+  // preflight. Such a binding is excluded from the comparison with the
+  // registration's operator-configured max_payload_bytes; every other binding
+  // uses the operator limit, which cannot exceed what that binding advertises.
   uint64 max_payload_bytes = 3;
   // Optional binding-specific RPC timeout. Empty uses the operator-configured
   // service timeout, or the 500ms platform default when that is also omitted.
@@ -106,8 +161,383 @@ message ValidateConfigResponse {
   string reason = 2;
 }
 
+// HTTP hooks. One ordered event in a HttpHooks.EvaluateHttpRequestHook
+// stream. Preflight is always first and sees the preceding stage's completed
+// output headers. An inspect result is followed by begin
+// and exactly one body lifecycle: whole_body for WHOLE_BODY, or input_chunk
+// events ending with input_end for DUPLEX. session_end is best effort and has
+// no result.
+message HttpRequestHookEvent {
+  oneof event {
+    HttpRequestHookPreflight preflight = 1;
+    HttpBegin begin = 2;
+    HttpWholeBody whole_body = 3;
+    HttpInputChunk input_chunk = 4;
+    HttpInputEnd input_end = 5;
+    MiddlewareSessionEnd session_end = 6;
+  }
+}
+
+// HTTP hooks. One ordered event in a HttpHooks.EvaluateHttpResponseHook
+// stream, in the order HttpRequestHookEvent describes.
+message HttpResponseHookEvent {
+  oneof event {
+    HttpResponseHookPreflight preflight = 1;
+    HttpBegin begin = 2;
+    HttpWholeBody whole_body = 3;
+    HttpInputChunk input_chunk = 4;
+    HttpInputEnd input_end = 5;
+    MiddlewareSessionEnd session_end = 6;
+  }
+}
+
+// HTTP hooks. One ordered result in a HttpHooks.EvaluateHttpRequestHook
+// stream. Preflight requires preflight_result or deny. WHOLE_BODY ends with
+// whole_body_result or deny. DUPLEX sends output_start before any
+// output_chunk, even for an empty output, and ends with finish or deny. An
+// unset or unknown result fails the exchange closed.
+//
+// A service may close its result stream right after the result that ends its
+// part in the exchange (continue_without_body, whole_body_result, finish, or
+// deny), or keep it open until session_end. OpenShell accepts both.
+message HttpRequestHookResult {
+  oneof result {
+    HttpPreflightResult preflight_result = 1;
+    HttpWholeBodyResult whole_body_result = 2;
+    HttpOutputStart output_start = 3;
+    HttpOutputChunk output_chunk = 4;
+    HttpFinish finish = 5;
+    HttpDenial deny = 6;
+  }
+}
+
+// HTTP hooks. One ordered result in a HttpHooks.EvaluateHttpResponseHook
+// stream, under the rules HttpRequestHookResult describes, with
+// block_delivery instead of deny. Blocking delivery does not undo the
+// request already handled by the external service.
+message HttpResponseHookResult {
+  oneof result {
+    HttpPreflightResult preflight_result = 1;
+    HttpWholeBodyResult whole_body_result = 2;
+    HttpOutputStart output_start = 3;
+    HttpOutputChunk output_chunk = 4;
+    HttpFinish finish = 5;
+    HttpDenial block_delivery = 6;
+  }
+}
+
+// HTTP hooks body lifecycle a stage selects at preflight.
+enum HttpBodyMode {
+  HTTP_BODY_MODE_UNSPECIFIED = 0;
+  // One complete body and one terminal result. OpenShell holds the body in
+  // memory, up to the selected max_body_bytes. A larger body, such as a
+  // chunked body without a declared length, fails the exchange; OpenShell
+  // does not fall back to DUPLEX.
+  HTTP_BODY_MODE_WHOLE_BODY = 1;
+  // Independent ordered input and output streams. The stage returns every
+  // output byte and owns any working storage. No total time limit, and no
+  // total size limit unless limits.max_output_body_bytes is set.
+  HTTP_BODY_MODE_DUPLEX = 2;
+}
+
+// Why OpenShell does not offer a body mode for a message.
+enum HttpBodyUnavailableReason {
+  HTTP_BODY_UNAVAILABLE_REASON_UNSPECIFIED = 0;
+  // The response has no body: the request method is HEAD, or the status is
+  // 1xx, 204, or 304.
+  HTTP_BODY_UNAVAILABLE_REASON_BODYLESS = 1;
+  // The response carries part of a representation: status 206, a
+  // Content-Range header, or multipart/byteranges content.
+  HTTP_BODY_UNAVAILABLE_REASON_PARTIAL = 2;
+  // Cache-Control no-transform forbids changing the response body.
+  HTTP_BODY_UNAVAILABLE_REASON_NO_TRANSFORM = 3;
+  // The request or response body has a content coding other than identity.
+  // Middleware would only see the encoded bytes. The sandbox chooses a
+  // request's coding, so a stage that must see request bodies denies an
+  // encoded one. When a response stage may select a body mode, OpenShell
+  // sends Accept-Encoding: identity upstream, so an encoded response means
+  // the upstream ignored it.
+  HTTP_BODY_UNAVAILABLE_REASON_ENCODED = 4;
+  // The declared body length exceeds the stage's payload limit.
+  HTTP_BODY_UNAVAILABLE_REASON_OVER_LIMIT = 5;
+  // The response is open-ended, such as text/event-stream or
+  // multipart/x-mixed-replace, and has no complete body to buffer.
+  HTTP_BODY_UNAVAILABLE_REASON_OPEN_ENDED = 6;
+  // The client could not detect a truncated response body, because the
+  // client request or the response status line uses HTTP/1.0 and the
+  // response cannot be chunked.
+  HTTP_BODY_UNAVAILABLE_REASON_TRUNCATION_UNDETECTABLE = 7;
+}
+
+// A body mode a preflight does not offer, and why.
+message HttpBodyModeUnavailable {
+  HttpBodyMode mode = 1;
+  HttpBodyUnavailableReason reason = 2;
+}
+
+// HTTP hook preflight for one request stage: what is evaluated, the
+// body modes offered, and limits.
+message HttpRequestHookPreflight {
+  // A request after network-policy admission and before credentials.
+  HttpRequestPreflightHead request = 1;
+  // Phase of the HTTP_REQUEST binding this stream serves: PRE_CREDENTIALS.
+  SupervisorMiddlewarePhase phase = 2;
+  // Sandbox, request, and originating process identity. Limited to 4 KiB
+  // encoded.
+  RequestContext context = 3;
+  // Built-in middleware name or operator-owned registration name.
+  string middleware_name = 4;
+  // Validated service configuration. Limited to 64 KiB encoded.
+  google.protobuf.Struct config = 5;
+  // Body modes this request is eligible for. Empty permits only
+  // continue_without_body or deny. When no permitted mode suits the stage,
+  // it continues or denies, with a reason_code saying why.
+  repeated HttpBodyMode permitted_body_modes = 6;
+  // One entry for each body mode that permitted_body_modes omits, with the
+  // rule that removed it. Empty when the binding's max_payload_bytes is 0,
+  // which offers no body mode.
+  repeated HttpBodyModeUnavailable unavailable_body_modes = 7;
+  HttpBodyLimits limits = 8;
+  // Declared length of this stage's input, when known from the original
+  // framing or the preceding stage's output. Unset when that length is unknown.
+  optional uint64 declared_body_bytes = 9;
+}
+
+// HTTP hook preflight for one response stage: what is evaluated, the
+// body modes offered, and limits.
+message HttpResponseHookPreflight {
+  // A final upstream response before it reaches the sandbox.
+  HttpResponsePreflightHead response = 1;
+  // Phase of the HTTP_RESPONSE binding this stream serves: PRE_RETURN.
+  SupervisorMiddlewarePhase phase = 2;
+  // Sandbox, request, and originating process identity. request_id matches
+  // the request preflights of the request this response answers. Limited to
+  // 4 KiB encoded.
+  RequestContext context = 3;
+  // Built-in middleware name or operator-owned registration name.
+  string middleware_name = 4;
+  // Validated service configuration. Limited to 64 KiB encoded.
+  google.protobuf.Struct config = 5;
+  // Body modes this response is eligible for. Empty permits only
+  // continue_without_body or block_delivery. When no permitted mode suits the
+  // stage, it continues or blocks delivery, with a reason_code saying why.
+  repeated HttpBodyMode permitted_body_modes = 6;
+  // One entry for each body mode that permitted_body_modes omits, with the
+  // rule that removed it. A stage can tell a bodyless response, which it may
+  // let continue, from a body it cannot inspect. Empty when the binding's
+  // max_payload_bytes is 0, which offers no body mode.
+  repeated HttpBodyModeUnavailable unavailable_body_modes = 7;
+  HttpBodyLimits limits = 8;
+  // Declared length of this stage's input, when known from the original
+  // framing or the preceding stage's output. Unset when that length is unknown.
+  optional uint64 declared_body_bytes = 9;
+}
+
+// Request head after network-policy admission and before credentials.
+message HttpRequestPreflightHead {
+  // Admitted destination and request target. Limited to 32 KiB encoded.
+  HttpRequestTarget target = 1;
+  // Request headers after all earlier stages' mutations, in wire order.
+  // Repeated names stay separate. Credential, routing, framing, and hop-by-hop
+  // headers are omitted, as is every header with a name that carries an
+  // OpenShell credential placeholder in any of its values. Limited to 128
+  // lines and 64 KiB encoded.
+  repeated HttpHeader headers = 2;
+}
+
+// Final upstream response head before delivery to the sandbox.
+message HttpResponsePreflightHead {
+  // Admitted request target with a redacted query. Limited to 32 KiB encoded.
+  HttpRequestTarget target = 1;
+  // Final non-informational upstream status. Upgrades are not evaluated.
+  uint32 status_code = 2;
+  // Response headers after all earlier stages' mutations, in wire order.
+  // Credential, routing, and hop-by-hop headers are omitted. Limited to 128
+  // lines and 64 KiB encoded.
+  repeated HttpHeader headers = 3;
+  // Headers of the request this response answers, as the request middleware
+  // chain forwarded them: after every request stage's mutations and before
+  // OpenShell adds credentials or makes its own forwarding changes, such as
+  // sending Accept-Encoding: identity. In wire order, with the omissions and
+  // limits of HttpRequestPreflightHead.headers.
+  repeated HttpHeader request_headers = 4;
+}
+
+// Limits for one stage exchange. max_whole_body_bytes is 0 unless WHOLE_BODY
+// is permitted, and max_chunk_bytes is 0 when no body mode is permitted.
+// DUPLEX has no total deadline, and no total byte cap unless
+// max_output_body_bytes is set. WHOLE_BODY has 2 minutes to receive, process,
+// and deliver one body, and each body exchange is also bounded by the binding
+// timeout.
+message HttpBodyLimits {
+  // Largest input_chunk and output_chunk payload.
+  uint64 max_chunk_bytes = 1;
+  // Largest WHOLE_BODY input and replacement.
+  uint64 max_whole_body_bytes = 2;
+  // DUPLEX middleware-stall timeout. A DUPLEX stage fails when it does not
+  // accept the next input within this duration, or returns nothing within
+  // this duration after input_end. Time the sandbox or upstream takes to
+  // produce input does not count. OpenShell uses 30 seconds.
+  google.protobuf.Duration idle_timeout = 3;
+  // Largest request body OpenShell forwards after every stage, set when
+  // DUPLEX is permitted and OpenShell holds the complete output before it
+  // contacts the upstream, such as to sign it. Output beyond it fails the
+  // message with body_over_limit. Unset when the output streams without a
+  // total cap.
+  optional uint64 max_output_body_bytes = 4;
+}
+
+// Preflight decision. To deny, return deny (requests) or block_delivery
+// (responses) instead, including when the stage cannot inspect the message.
+message HttpPreflightResult {
+  oneof decision {
+    // Let the message continue without this stage seeing its body.
+    HttpContinue continue_without_body = 1;
+    // Inspect the body in one permitted mode.
+    HttpInspect inspect = 2;
+  }
+  // Ordered head mutations, applied to this stage's input before begin.
+  // The next stage sees these and this stage's body-time mutations together.
+  // Only visible end-to-end headers may change. Credential, routing, framing,
+  // and hop-by-hop headers are protected, as are Content-Encoding, response
+  // Content-Range, and request headers omitted because they carry a credential
+  // placeholder. OpenShell does not update integrity headers such
+  // as ETag, Content-MD5, or Content-Digest when a body changes: a stage that
+  // changes the body removes them or writes new values, typically in
+  // HttpWholeBodyResult.header_mutations or HttpOutputStart.header_mutations. Limited to 64
+  // operations, 32 KiB of name/value data, and 64 KiB encoded.
+  repeated HeaderMutation header_mutations = 3;
+  MiddlewareDiagnostics diagnostics = 4;
+}
+
+// The body bypasses this stage but remains eligible for later stages.
+message HttpContinue {}
+
+// Selects one permitted body mode.
+message HttpInspect {
+  oneof mode {
+    HttpWholeBodyMode whole_body = 1;
+    HttpDuplexMode duplex = 2;
+  }
+}
+
+message HttpWholeBodyMode {
+  // Positive and no larger than the offered max_whole_body_bytes. The cap
+  // applies separately to the input and the replacement.
+  uint64 max_body_bytes = 1;
+}
+
+// DUPLEX makes the stage responsible for all output from accepted preflight.
+message HttpDuplexMode {}
+
+// Starts the selected body lifecycle.
+message HttpBegin {
+  // The preflight head plus this stage's preflight mutations. Earlier
+  // stages have already finalized these headers; later stages cannot change
+  // this stage's input. Mutations in whole_body_result or output_start apply
+  // on top of this head before the next stage receives its preflight.
+  repeated HttpHeader headers = 1;
+}
+
+// WHOLE_BODY input: exactly one complete body, possibly empty.
+message HttpWholeBody {
+  bytes data = 1;

Showing 400 of 741 lines; see the full compare.

Before merging

  • CI and E2E must pass. If the SDK needs changes for this core version, push them to this branch.
  • Pre-release pins are not released; a newer pre-release proposal replaces this one.

Move the core pin from v0.1.8 to v0.1.9-pre.4 and regenerate the bindings.

Signed-off-by: ai-openshell-sdk-python[bot] <354503561+ai-openshell-sdk-python[bot]@users.noreply.github.com>
@ai-openshell-sdk-python
ai-openshell-sdk-python Bot requested review from a team as code owners November 16, 2026 13:43
@ai-openshell-sdk-python ai-openshell-sdk-python Bot added core-bump Update proposal that moves the core pin to a newer NVIDIA/OpenShell release tag prerelease The core tag of this update proposal is a pre-release labels Nov 16, 2026
@ai-openshell-sdk-python

Copy link
Copy Markdown
Contributor Author

Superseded by #48, which tracks core v0.1.9-pre.5.

@ai-openshell-sdk-python
ai-openshell-sdk-python Bot deleted the core/v0.1.9-pre.4 branch November 17, 2026 13:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

core-bump Update proposal that moves the core pin to a newer NVIDIA/OpenShell release tag prerelease The core tag of this update proposal is a pre-release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants