Repository navigation
Expand file tree
/
Copy pathsupervisor_host.proto
More file actions
205 lines (185 loc) · 8.04 KB
/
Copy pathsupervisor_host.proto
File metadata and controls
205 lines (185 loc) · 8.04 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0
syntax = "proto3";
package openshell.supervisor.host.v1;
import "google/protobuf/duration.proto";
import "options.proto";
// Private contract between a gateway and the supervisor process it shares
// among its sandboxes. It is a version-locked deployment protocol, not a
// public API: the gateway, the Kubernetes compute driver, and the shared
// supervisor are released together, and no SDK generates bindings for it.
//
// The supervisor host opens one Attach stream, identifies itself, and keeps
// the stream for its lifetime. The gateway owns the desired set of sandbox
// instances and sends it as complete snapshots; the host reconciles its
// registry to each snapshot and reports what it observes. Disconnecting
// never stops hosted instances; only a later snapshot that omits them does.
//
// A host that names a pool member in its hello belongs to a supervisor pool
// (high availability). The gateway places each instance on one member, sends
// each member only the instances it owns, and moves an instance only when its
// owner fails or leaves. A pool host releases an instance a snapshot omits
// without stopping its workload; only `stop_routes` stops workloads.
service SupervisorHost {
// Supervisor-initiated assignment stream. Only the gateway-minted
// supervisor token may call it.
rpc Attach(stream HostMessage) returns (stream HostGatewayMessage) {
option (openshell.options.v1.authorization) = {
auth_mode: "supervisor"
};
}
}
// Envelope for host-to-gateway messages.
message HostMessage {
oneof payload {
HostHello hello = 1;
HostStatus status = 2;
HostHeartbeat heartbeat = 3;
}
}
// Envelope for gateway-to-host messages.
message HostGatewayMessage {
oneof payload {
HostAccepted accepted = 1;
HostRejected rejected = 2;
AssignmentSnapshot assignments = 3;
HostGatewayHeartbeat heartbeat = 4;
}
}
// First message of every stream.
message HostHello {
// Identifies one host process (for example a boot id). A reconnect from the
// same process keeps it; a restarted process has a new one.
string instance_id = 1;
// Counter the host increments for every connection of one instance_id, so
// the gateway can order reconnects.
uint64 connection_epoch = 2;
// Present when the host is a member of a supervisor pool.
PoolMember member = 3;
}
// One member of a supervisor pool.
message PoolMember {
reserved 2;
reserved "member_uid";
// Opaque, stable logical member ID. One process serves a member at a time;
// HostHello.instance_id identifies that process.
string member_id = 1;
// Address (IP:port) of the member's routed runtime listener, reachable from
// sandbox runtimes. Other members redirect sandbox runtimes here for the
// instances this member owns.
string runtime_address = 3;
}
// The gateway accepted the host and will send assignment snapshots.
message HostAccepted {
// Scopes every snapshot revision and status report of this stream.
string session_id = 1;
google.protobuf.Duration heartbeat_interval = 2;
}
// The gateway refuses the host; the stream ends after this message.
message HostRejected {
string reason = 1;
}
// Complete desired set of sandbox instances. Each snapshot replaces the
// previous one; an instance absent from a snapshot must stop, except on a
// pool host, which releases it without stopping its workload.
message AssignmentSnapshot {
// Monotonic within the session, starting at 1.
uint64 revision = 1;
repeated SandboxInstanceAssignment instances = 2;
// The host is a pool member: release omitted instances instead of
// stopping them, and stop only the routes listed in `stop_routes`.
bool pool = 3;
// Pool hosts only: routes whose sandbox is stopping or deleted; the host
// stops their workloads if it still hosts them.
repeated string stop_routes = 4;
// Pool hosts only: where each instance placed in the pool is supervised,
// so a sandbox runtime that reaches this host is redirected to its owner.
repeated RouteOwner route_directory = 5;
// Pool hosts only: routes this host's process owns whose launch material
// this gateway replica has not loaded yet. The host keeps supervising them
// unchanged; it neither releases nor stops them, and starts nothing for
// them.
repeated string keep_routes = 6;
// Pool hosts only: how long, in whole seconds, a sandbox runtime keeps its
// workload frozen after losing this host's supervision before terminating
// it. The host offers it to each instance's runtime when it attaches;
// absent keeps the runtime default.
google.protobuf.Duration recovery_timeout = 7;
}
// The pool member that supervises one route.
message RouteOwner {
string route = 1;
// Runtime listener address (IP:port) of the owning member.
string runtime_address = 2;
}
// One running generation of a stable Sandbox resource, assigned to the host.
message SandboxInstanceAssignment {
// Route handle the sandbox runtime names; the instance's key on the host.
string route = 1;
string sandbox_id = 2;
// Runtime generation this assignment launches. Never reused.
string generation = 3;
// Trusted launch material for the generation: the JSON-encoded sandbox
// instance registration (runtime descriptor, gateway-issued credentials,
// proxy CA, main process). Never logged or forwarded.
bytes launch_material = 4 [(openshell.options.v1.secret) = true];
// Present when the host supervises the instance under a later ownership
// term than its launch: it replaces the previous owner with these
// credentials and adopts the running workload.
SandboxInstanceTakeover takeover = 5;
}
// Credentials of one ownership term after the launch term. The gateway
// advanced the sandbox's credential epoch to `auth_epoch` before granting it,
// which revoked every credential of earlier terms. A term is identified by
// `auth_epoch` and `supervisor_instance_id`: each gateway replica mints its
// own credentials for it, and may mint them again, so a host that already
// supervises the term keeps doing so whatever credentials arrive. A term sent
// without credentials (empty `grant`) was minted by another gateway replica;
// a host that does not supervise it yet waits for credentials.
message SandboxInstanceTakeover {
uint64 auth_epoch = 1;
// Supervisor process identity the runtime pins for this term.
string supervisor_instance_id = 2;
// Gateway-signed takeover grant presented when attaching to the runtime.
string grant = 3 [(openshell.options.v1.secret) = true];
string gateway_token = 4 [(openshell.options.v1.secret) = true];
int64 gateway_expires_at = 5;
string sandbox_token = 6 [(openshell.options.v1.secret) = true];
int64 sandbox_expires_at = 7;
}
// Everything the host observes, sent after reconciling each snapshot and
// whenever an instance changes.
message HostStatus {
// Highest snapshot revision of this session the host has reconciled to;
// 0 before the first one.
uint64 applied_revision = 1;
// Every hosted instance, including ones that ended but are still being
// removed.
repeated SandboxInstanceStatus instances = 2;
// A pool host is shutting down: the gateway moves its instances to other
// members at once. Its workloads keep running.
bool leaving = 3;
}
// Lifecycle phase of a hosted sandbox instance.
enum SandboxInstancePhase {
SANDBOX_INSTANCE_PHASE_UNSPECIFIED = 0;
SANDBOX_INSTANCE_PHASE_STARTING = 1;
SANDBOX_INSTANCE_PHASE_SUPERVISING = 2;
SANDBOX_INSTANCE_PHASE_STOPPING = 3;
SANDBOX_INSTANCE_PHASE_EXITED = 4;
SANDBOX_INSTANCE_PHASE_FAILED = 5;
}
// Observed state of one hosted sandbox instance.
message SandboxInstanceStatus {
string route = 1;
string sandbox_id = 2;
SandboxInstancePhase phase = 3;
// The gateway currently accepts this instance's supervision session.
bool ready = 4;
// Workload exit code; meaningful only for EXITED.
int32 exit_code = 5;
// Sanitized failure; meaningful only for FAILED.
string error = 6;
}
message HostHeartbeat {}
message HostGatewayHeartbeat {}