Repository navigation
Releases
Releases · ai-openshell/sdk-python
v0.1.9
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 f...v0.1.8
Move the core pin from v0.1.8-pre.5 to v0.1.8 (stable).
- Core changes: v0.1.8-pre.5...v0.1.8
- Regenerated bindings: no generated files changed
- E2E runs against
ghcr.io/nvidia/openshell/gateway:0.1.8 - Files copied from core:
- none changed
Proto changes
No changes under proto/ between v0.1.8-pre.5 and v0.1.8.
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.8.