Skip to content

chore(core): track v0.1.9-pre.5 - #48

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

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

Conversation

@ai-openshell-sdk-python

Copy link
Copy Markdown
Contributor

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

  • Core changes: v0.1.8...v0.1.9-pre.5
  • Regenerated bindings: 4 files changed, 290 insertions(+), 49 deletions(-)
  • E2E runs against ghcr.io/nvidia/openshell/gateway:0.1.9-pre.5
  • Files copied from core:
    • none changed

Proto changes

diff --git a/proto/README.md b/proto/README.md
index 7dd67c6..80e455a 100644
--- a/proto/README.md
+++ b/proto/README.md
@@ -72,6 +72,8 @@ identifies the service being exposed.
   wire identity and may therefore differ from declaration order.
 - Document authorization-sensitive selector variants and omission semantics on
   the containing request.
+- Give an RPC that changes gateway state a `*:write` scope and add it to the
+  audit catalog in `crates/openshell-server/src/auth/audit/catalog.rs`.
 
 ## Schema evolution
 
diff --git a/proto/openshell.proto b/proto/openshell.proto
index b40ec68..198990a 100644
--- a/proto/openshell.proto
+++ b/proto/openshell.proto
@@ -858,6 +858,28 @@ service OpenShell {
   }
 }
 
+// Application ingress consumers discover routes independently of sandbox management.
+service ServiceDiscovery {
+  // Read installed, unexpired application routes in one explicit workspace.
+  rpc GetServiceRouteSnapshot(GetServiceRouteSnapshotRequest) returns (GetServiceRouteSnapshotResponse) {
+    option (openshell.options.v1.authorization) = {
+      auth_mode: "bearer"
+      scope: "sandbox:read"
+      workspace_role: "user"
+    };
+  }
+
+  // Full replacement views; reauthorize during the bounded watch lifetime.
+  rpc WatchServiceRoutes(WatchServiceRoutesRequest) returns (stream WatchServiceRoutesResponse) {
+    option (openshell.options.v1.authorization) = {
+      auth_mode: "bearer"
+      scope: "sandbox:read"
+      workspace_role: "user"
+    };
+  }
+
+}
+
 // Optional sandbox mutations are separate from OpenShell so existing generated
 // OpenShell server implementations remain source-compatible.
 service SandboxUpdates {
@@ -4245,3 +4267,47 @@ message SupervisorServiceAdvertisement {
   // Domain actually installed by the process listener, not the gateway URL.
   string service_domain = 5;
 }
+
+// One explicit active workspace is required. Omitted and all-workspaces
+// selectors are rejected; discovery-only machine grants are separate work.
+message GetServiceRouteSnapshotRequest {
+  openshell.datamodel.v1.WorkspaceSelector workspace_scope = 1;
+}
+message GetServiceRouteSnapshotResponse {
+  ServiceRouteSnapshot snapshot = 1;
+}
+// Same workspace authorization as GetServiceRouteSnapshot. A watch sends an
+// initial replacement and later replacements, including lease-only renewal.
+// Clients reconnect/relist when the bounded stream ends and expire cached
+// routes during discovery errors; errors are not empty replacements.
+message WatchServiceRoutesRequest {
+  openshell.datamodel.v1.WorkspaceSelector workspace_scope = 1;
+}
+message WatchServiceRoutesResponse {
+  ServiceRouteSnapshot snapshot = 1;
+}
+message ServiceRouteSnapshot {
+  repeated DiscoveredServiceRoute routes = 1;
+  // Opaque equality token for this complete view, including lease expiries.
+  // No ordering across replicas or server restarts is implied.
+  string revision = 2;
+}
+// Trusted supervisor TLS endpoint. Preserve DiscoveredServiceRoute.hostname
+// as SNI and HTTP authority; this endpoint never addresses a workload port.
+message ServiceRouteEndpoint {
+  string host = 1;
+  uint32 port = 2;
+}
+// Accepted installation evidence, not application health or ingress readiness.
+message DiscoveredServiceRoute {
+  string workspace = 1;
+  string sandbox = 2;
+  // Canonical service name; empty identifies the existing unnamed service.
+  string name = 3;
+  string hostname = 4;
+  ServiceRouteEndpoint endpoint = 5;
+  // Changes on owner/backend/declaration replacement, but not lease renewal.
+  string installation_version = 6;
+  uint64 declaration_revision = 7;
+  google.protobuf.Timestamp expires_at = 8;
+}
diff --git a/proto/supervisor_host.proto b/proto/supervisor_host.proto
index 862a5e3..3195837 100644
--- a/proto/supervisor_host.proto
+++ b/proto/supervisor_host.proto
@@ -50,6 +50,7 @@ message HostGatewayMessage {
     HostRejected rejected = 2;
     AssignmentSnapshot assignments = 3;
     HostGatewayHeartbeat heartbeat = 4;
+    HostRedirect redirect = 5;
   }
 }
 
@@ -63,6 +64,11 @@ message HostHello {
   uint64 connection_epoch = 2;
   // Present when the host is a member of a supervisor pool.
   PoolMember member = 3;
+  // The gateway may answer with a HostRedirect. A host leaves it unset to be
+  // served by the replica it dialed: after two redirects in a row, or when it
+  // redials the replica that last accepted it. Hosts that predate
+  // HostRedirect never set it.
+  bool accepts_redirect = 4;
 }
 
 // One member of a supervisor pool.
@@ -90,6 +96,12 @@ message HostAccepted {
   string peer_endpoint = 3;
 }
 
+// Another gateway replica should serve the host, which dials it at once. The
+// stream ends after this message.
+message HostRedirect {
+  string peer_endpoint = 1;
+}
+
 // The gateway refuses the host; the stream ends after this message.
 message HostRejected {
   string reason = 1;
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

Showing 400 of 872 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.5 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 17, 2026 13:22
@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 17, 2026
@ai-openshell-sdk-python

Copy link
Copy Markdown
Contributor Author

Superseded by #49, which tracks core v0.1.9.

@ai-openshell-sdk-python
ai-openshell-sdk-python Bot deleted the core/v0.1.9-pre.5 branch November 17, 2026 19: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