Repository navigation
Move the core pin from v0.1.8 to v0.1.9 (stable).
- Core changes: v0.1.8...v0.1.9
- Regenerated bindings: 4 files changed, 290 insertions(+), 49 deletions(-)
- E2E runs against
ghcr.io/nvidia/openshell/gateway:0.1.9 - 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 matchesShowing 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.
Matches OpenShell core v0.1.9.