devzero-sandbox 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,41 @@
1
+ """DevZero self-hosted sandboxes SDK (control plane + data plane clients).
2
+
3
+ from devzero_sandbox import Client
4
+
5
+ client = Client() # DEVZERO_TOKEN, DEVZERO_DAKR_URL
6
+ sbx = client.sandboxes.create("default") # waits for ready
7
+ print(sbx.commands.run("echo hi").stdout_text)
8
+ proc = sbx.commands.run("make test", background=True)
9
+ sbx.files.write("notes.txt", "hello")
10
+ sbx.delete()
11
+
12
+ In a pod in the cluster, with no DevZero credential:
13
+
14
+ sbx = Sandbox.in_cluster("default", "sb7k2m9q4xz1")
15
+
16
+ Layers: ``sandbox`` (``Client``, ``Sandbox``), ``commands``, ``files``,
17
+ ``terminal`` (data plane, ADR-007-W13) on ``transport`` and ``auth``
18
+ (ADR-005-W11); ``connect`` and the generated ``_proto`` stub for DevZero's
19
+ ``SandboxService``; ``errors`` for every typed exception.
20
+ """
21
+
22
+ __version__ = "0.1.0"
23
+
24
+ from devzero_sandbox.commands import CommandResult, Process
25
+ from devzero_sandbox.errors import (
26
+ DevZeroSandboxError,
27
+ StreamInterrupted,
28
+ )
29
+ from devzero_sandbox.sandbox import Client, Sandbox
30
+ from devzero_sandbox.terminal import PartialSendTimeout
31
+
32
+ __all__ = [
33
+ "Client",
34
+ "CommandResult",
35
+ "DevZeroSandboxError",
36
+ "PartialSendTimeout",
37
+ "Process",
38
+ "Sandbox",
39
+ "StreamInterrupted",
40
+ "__version__",
41
+ ]
@@ -0,0 +1,104 @@
1
+ """The shell side of ``commands.run(background=True)`` (ADR-007-W13).
2
+
3
+ ``sandboxd`` (v1.0.9) kills a ``Start`` stream's process tree when the stream
4
+ closes: ``kill(-pgid)``, then a ``/proc/<pid>/task/*/children`` walk for
5
+ runtimes where group signals miss grandchildren (gVisor), then the pid
6
+ (review/upstream-k8s.md V21). A background command therefore cannot be a
7
+ descendant of the stream's process, nor share its process group, or closing
8
+ the stream (the SDK exiting, a gateway rollout, the 30 min idle limit) kills
9
+ it. The launcher below:
10
+
11
+ 1. reads its own pid from stdin: ``sandboxd`` numbers processes itself, so the
12
+ SDK learns the pid from the stream's ``init`` event and writes it back;
13
+ 2. starts the command with ``setsid`` from a subshell that exits at once, so
14
+ the command leads a new session and process group and is re-parented away
15
+ from the launcher (out of both kill strategies);
16
+ 3. sends the command's stdout and stderr to ``<dir>/<pid>.log``, its pid to
17
+ ``<dir>/<pid>.pid`` and, when it ends, its exit code to ``<dir>/<pid>.exit``
18
+ (written by rename, so a reader never sees half of it);
19
+ 4. stays as the *holder*: a stream that prints ``dz-bg:exit:<code>`` when the
20
+ exit file appears and exits with that code. While it waits it prints an
21
+ empty line every ``<heartbeat>`` seconds. The gateway ends an SSE stream
22
+ after 30 min without stdout or stderr (ADR-007 §Limits; keepalive comments
23
+ do not count, ADR-007-W8), and these lines are real process output, so a
24
+ holder for a quiet command is not cut by the idle limit.
25
+
26
+ ``watch`` mode is the holder alone, for a process another stream launched
27
+ (``attach``, or a holder re-opened after a drain). Every protocol line on
28
+ stdout starts with ``dz-bg:``; a problem is ``dz-bg:error:<code>:<text>``.
29
+ ``kill`` mode SIGKILLs the process tree and group and writes exit code 137.
30
+ """
31
+
32
+ from __future__ import annotations
33
+
34
+ # Runs as: /bin/sh -c SCRIPT dz-bg <launch|watch|kill> <dir> <heartbeat_s> [<pid>] [argv...]
35
+ SCRIPT = r"""
36
+ set -u
37
+ mode=$1 dir=$2 hb=$3
38
+ shift 3
39
+ fail() { printf 'dz-bg:error:%s:%s\n' "$1" "$2"; exit 125; }
40
+ alive() { kill -0 "$1" 2>/dev/null && ! grep -q '^[^)]*) Z' "/proc/$1/stat" 2>/dev/null; }
41
+ tree() {
42
+ for c in $(cat /proc/"$1"/task/*/children 2>/dev/null); do tree "$c"; done
43
+ kill -s KILL "$1" 2>/dev/null
44
+ }
45
+ finish() { printf '%s\n' "$2" >"$1.exit.t" && mv -f "$1.exit.t" "$1.exit"; }
46
+ case $mode in
47
+ launch)
48
+ IFS= read -r id || fail no_pid "stdin closed before the pid arrived"
49
+ case $id in ''|*[!0-9]*) fail bad_pid "not a pid: $id" ;; esac
50
+ base=$dir/$id
51
+ mkdir -p "$dir" || fail no_dir "cannot create $dir"
52
+ command -v setsid >/dev/null 2>&1 || fail no_setsid "setsid is not installed in the sandbox image"
53
+ rm -f "$base.exit" "$base.pid" "$base.exit.t" "$base.pid.t"
54
+ : >"$base.log" || fail no_log "cannot write $base.log"
55
+ ( setsid /bin/sh -c '
56
+ b=$1; shift
57
+ echo $$ >"$b.pid.t" && mv -f "$b.pid.t" "$b.pid"
58
+ "$@" >>"$b.log" 2>&1 </dev/null
59
+ c=$?
60
+ printf "%s\n" "$c" >"$b.exit.t" && mv -f "$b.exit.t" "$b.exit"
61
+ ' dz-bg-run "$base" "$@" </dev/null >/dev/null 2>&1 & )
62
+ i=0
63
+ while [ ! -s "$base.pid" ]; do
64
+ i=$((i + 1))
65
+ [ "$i" -gt 200 ] && fail no_start "the process did not start within 20s"
66
+ sleep 0.1
67
+ done
68
+ echo dz-bg:started
69
+ ;;
70
+ watch)
71
+ id=$1
72
+ base=$dir/$id
73
+ [ -s "$base.pid" ] || fail not_found "no background process $id"
74
+ ;;
75
+ kill)
76
+ id=$1
77
+ base=$dir/$id
78
+ [ -s "$base.pid" ] || exit 3
79
+ [ -e "$base.exit" ] && exit 4
80
+ p=$(cat "$base.pid")
81
+ tree "$p"
82
+ # dash wants "--" before a negative pid, busybox refuses it: try both.
83
+ kill -s KILL -- "-$p" 2>/dev/null || kill -s KILL "-$p" 2>/dev/null
84
+ [ -e "$base.exit" ] || finish "$base" 137
85
+ exit 0
86
+ ;;
87
+ *) fail bad_mode "$mode" ;;
88
+ esac
89
+ p=$(cat "$base.pid")
90
+ n=0
91
+ while [ ! -e "$base.exit" ]; do
92
+ if ! alive "$p"; then
93
+ sleep 1
94
+ [ -e "$base.exit" ] || finish "$base" 137
95
+ break
96
+ fi
97
+ sleep 1
98
+ n=$((n + 1))
99
+ if [ "$n" -ge "$hb" ]; then echo; n=0; fi
100
+ done
101
+ c=$(cat "$base.exit")
102
+ echo "dz-bg:exit:$c"
103
+ exit "$c"
104
+ """
@@ -0,0 +1 @@
1
+ """Generated from dakr/proto/sandbox/v1 by `make generate-client`; do not edit."""
@@ -0,0 +1 @@
1
+ """Generated from dakr/proto/sandbox/v1 by `make generate-client`; do not edit."""
@@ -0,0 +1 @@
1
+ """Generated from dakr/proto/sandbox/v1 by `make generate-client`; do not edit."""
@@ -0,0 +1,40 @@
1
+ # -*- coding: utf-8 -*-
2
+ # Generated by the protocol buffer compiler. DO NOT EDIT!
3
+ # NO CHECKED-IN PROTOBUF GENCODE
4
+ # source: sandbox/v1/error.proto
5
+ # Protobuf Python Version: 5.29.3
6
+ """Generated protocol buffer code."""
7
+ from google.protobuf import descriptor as _descriptor
8
+ from google.protobuf import descriptor_pool as _descriptor_pool
9
+ from google.protobuf import runtime_version as _runtime_version
10
+ from google.protobuf import symbol_database as _symbol_database
11
+ from google.protobuf.internal import builder as _builder
12
+ _runtime_version.ValidateProtobufRuntimeVersion(
13
+ _runtime_version.Domain.PUBLIC,
14
+ 5,
15
+ 29,
16
+ 3,
17
+ '',
18
+ 'sandbox/v1/error.proto'
19
+ )
20
+ # @@protoc_insertion_point(imports)
21
+
22
+ _sym_db = _symbol_database.Default()
23
+
24
+
25
+
26
+
27
+ DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x16sandbox/v1/error.proto\x12\nsandbox.v1\"\xbd\x01\n\x0cSandboxError\x12\x12\n\x04\x63ode\x18\x01 \x01(\tR\x04\x63ode\x12\x1c\n\tretryable\x18\x02 \x01(\x08R\tretryable\x12?\n\x07\x64\x65tails\x18\x03 \x03(\x0b\x32%.sandbox.v1.SandboxError.DetailsEntryR\x07\x64\x65tails\x1a:\n\x0c\x44\x65tailsEntry\x12\x10\n\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n\x05value\x18\x02 \x01(\tR\x05value:\x02\x38\x01\x62\x06proto3')
28
+
29
+ _globals = globals()
30
+ _builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
31
+ _builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'sandbox.v1.error_pb2', _globals)
32
+ if not _descriptor._USE_C_DESCRIPTORS:
33
+ DESCRIPTOR._loaded_options = None
34
+ _globals['_SANDBOXERROR_DETAILSENTRY']._loaded_options = None
35
+ _globals['_SANDBOXERROR_DETAILSENTRY']._serialized_options = b'8\001'
36
+ _globals['_SANDBOXERROR']._serialized_start=39
37
+ _globals['_SANDBOXERROR']._serialized_end=228
38
+ _globals['_SANDBOXERROR_DETAILSENTRY']._serialized_start=170
39
+ _globals['_SANDBOXERROR_DETAILSENTRY']._serialized_end=228
40
+ # @@protoc_insertion_point(module_scope)
@@ -0,0 +1,23 @@
1
+ from google.protobuf.internal import containers as _containers
2
+ from google.protobuf import descriptor as _descriptor
3
+ from google.protobuf import message as _message
4
+ from typing import ClassVar as _ClassVar, Mapping as _Mapping, Optional as _Optional
5
+
6
+ DESCRIPTOR: _descriptor.FileDescriptor
7
+
8
+ class SandboxError(_message.Message):
9
+ __slots__ = ("code", "retryable", "details")
10
+ class DetailsEntry(_message.Message):
11
+ __slots__ = ("key", "value")
12
+ KEY_FIELD_NUMBER: _ClassVar[int]
13
+ VALUE_FIELD_NUMBER: _ClassVar[int]
14
+ key: str
15
+ value: str
16
+ def __init__(self, key: _Optional[str] = ..., value: _Optional[str] = ...) -> None: ...
17
+ CODE_FIELD_NUMBER: _ClassVar[int]
18
+ RETRYABLE_FIELD_NUMBER: _ClassVar[int]
19
+ DETAILS_FIELD_NUMBER: _ClassVar[int]
20
+ code: str
21
+ retryable: bool
22
+ details: _containers.ScalarMap[str, str]
23
+ def __init__(self, code: _Optional[str] = ..., retryable: bool = ..., details: _Optional[_Mapping[str, str]] = ...) -> None: ...
@@ -0,0 +1,381 @@
1
+ # Generated by tools/gen_connect.py from sandbox/v1/service.proto. DO NOT EDIT.
2
+ # Regenerate with `make generate-client` (sandbox-sdks/python).
3
+ """Connect client stubs for package ``sandbox.v1``."""
4
+
5
+ from __future__ import annotations
6
+
7
+ from collections.abc import Iterator
8
+
9
+ from devzero_sandbox._proto.sandbox.v1 import service_pb2 as _pb
10
+ from devzero_sandbox.connect import ConnectClient
11
+
12
+ SANDBOX_SERVICE_NAME = "sandbox.v1.SandboxService"
13
+
14
+
15
+ class SandboxServiceClient:
16
+ """SandboxService is the public control-plane API for DevZero sandboxes
17
+ (ADR-003, API contract). Connect serves it as JSON over HTTP POST, so every
18
+ RPC is callable with curl; the Python SDK client is generated from it.
19
+
20
+ Callers are any principal dakr already authenticates (web session, dzu-
21
+ personal access token, dzs- team service-account token). Authorization is
22
+ by team role on the cluster's team; the minimum role is noted per RPC.
23
+
24
+ A failed RPC carries a Connect code and exactly one SandboxError detail
25
+ whose code comes from the ADR-003 error table.
26
+
27
+ Sandbox tokens are returned only by CreateSandbox and CreateSandboxToken,
28
+ never by GetSandbox, ListSandboxes or WatchSandbox.
29
+
30
+ PauseSandbox and ResumeSandbox (Phase 2) are added by the work item that
31
+ owns them. GetSandboxEndpoint and SetSandboxEndpoint author the cluster's
32
+ SandboxEndpoint/default (ADR-006): the BYO field set in Phase 1; the
33
+ managed and relay fields arrive with the items that serve those modes.
34
+ """
35
+
36
+ def __init__(self, connect: ConnectClient) -> None:
37
+ self._connect = connect
38
+
39
+ def list_sandbox_policies(
40
+ self,
41
+ request: _pb.ListSandboxPoliciesRequest,
42
+ *,
43
+ timeout_s: float | None = None,
44
+ retry: bool = False,
45
+ ) -> _pb.ListSandboxPoliciesResponse:
46
+ """ListSandboxPolicies lists the policies the caller may use, one row per
47
+ (cluster, policy), with effective limits, endpoint mode and connect
48
+ templates. Viewer.
49
+ """
50
+ return self._connect.unary(
51
+ "/sandbox.v1.SandboxService/ListSandboxPolicies",
52
+ request,
53
+ _pb.ListSandboxPoliciesResponse,
54
+ timeout_s=timeout_s,
55
+ retry=retry,
56
+ )
57
+
58
+ def create_sandbox(
59
+ self,
60
+ request: _pb.CreateSandboxRequest,
61
+ *,
62
+ timeout_s: float | None = None,
63
+ retry: bool = False,
64
+ ) -> _pb.CreateSandboxResponse:
65
+ """CreateSandbox records a sandbox and asks its cluster to create it. It
66
+ returns PHASE_PENDING unless wait_ready is set, in which case it blocks,
67
+ up to a server-bounded timeout, until the sandbox is ready or rejected.
68
+ Developer.
69
+ """
70
+ return self._connect.unary(
71
+ "/sandbox.v1.SandboxService/CreateSandbox",
72
+ request,
73
+ _pb.CreateSandboxResponse,
74
+ timeout_s=timeout_s,
75
+ retry=retry,
76
+ )
77
+
78
+ def get_sandbox(
79
+ self,
80
+ request: _pb.GetSandboxRequest,
81
+ *,
82
+ timeout_s: float | None = None,
83
+ retry: bool = False,
84
+ ) -> _pb.GetSandboxResponse:
85
+ """GetSandbox returns one sandbox. Never returns a token. Viewer."""
86
+ return self._connect.unary(
87
+ "/sandbox.v1.SandboxService/GetSandbox",
88
+ request,
89
+ _pb.GetSandboxResponse,
90
+ timeout_s=timeout_s,
91
+ retry=retry,
92
+ )
93
+
94
+ def list_sandboxes(
95
+ self,
96
+ request: _pb.ListSandboxesRequest,
97
+ *,
98
+ timeout_s: float | None = None,
99
+ retry: bool = False,
100
+ ) -> _pb.ListSandboxesResponse:
101
+ """ListSandboxes lists sandboxes, paged and filtered. Never returns tokens.
102
+ Viewer.
103
+ """
104
+ return self._connect.unary(
105
+ "/sandbox.v1.SandboxService/ListSandboxes",
106
+ request,
107
+ _pb.ListSandboxesResponse,
108
+ timeout_s=timeout_s,
109
+ retry=retry,
110
+ )
111
+
112
+ def watch_sandbox(
113
+ self,
114
+ request: _pb.WatchSandboxRequest,
115
+ *,
116
+ timeout_s: float | None = None,
117
+ retry: bool = False,
118
+ ) -> Iterator[_pb.WatchSandboxResponse]:
119
+ """WatchSandbox streams the status transitions of one sandbox, resumable
120
+ from a cursor. Viewer.
121
+ """
122
+ return self._connect.server_stream(
123
+ "/sandbox.v1.SandboxService/WatchSandbox",
124
+ request,
125
+ _pb.WatchSandboxResponse,
126
+ timeout_s=timeout_s,
127
+ retry=retry,
128
+ )
129
+
130
+ def delete_sandbox(
131
+ self,
132
+ request: _pb.DeleteSandboxRequest,
133
+ *,
134
+ timeout_s: float | None = None,
135
+ retry: bool = False,
136
+ ) -> _pb.DeleteSandboxResponse:
137
+ """DeleteSandbox revokes every live token of the sandbox, then deletes it.
138
+ Developer.
139
+ """
140
+ return self._connect.unary(
141
+ "/sandbox.v1.SandboxService/DeleteSandbox",
142
+ request,
143
+ _pb.DeleteSandboxResponse,
144
+ timeout_s=timeout_s,
145
+ retry=retry,
146
+ )
147
+
148
+ def extend_sandbox(
149
+ self,
150
+ request: _pb.ExtendSandboxRequest,
151
+ *,
152
+ timeout_s: float | None = None,
153
+ retry: bool = False,
154
+ ) -> _pb.ExtendSandboxResponse:
155
+ """ExtendSandbox moves the shutdown time, at most to the policy maxTTL. It
156
+ never mints or changes a token. Developer.
157
+ """
158
+ return self._connect.unary(
159
+ "/sandbox.v1.SandboxService/ExtendSandbox",
160
+ request,
161
+ _pb.ExtendSandboxResponse,
162
+ timeout_s=timeout_s,
163
+ retry=retry,
164
+ )
165
+
166
+ def create_sandbox_token(
167
+ self,
168
+ request: _pb.CreateSandboxTokenRequest,
169
+ *,
170
+ timeout_s: float | None = None,
171
+ retry: bool = False,
172
+ ) -> _pb.CreateSandboxTokenResponse:
173
+ """CreateSandboxToken mints an additional token for a sandbox. Developer."""
174
+ return self._connect.unary(
175
+ "/sandbox.v1.SandboxService/CreateSandboxToken",
176
+ request,
177
+ _pb.CreateSandboxTokenResponse,
178
+ timeout_s=timeout_s,
179
+ retry=retry,
180
+ )
181
+
182
+ def revoke_sandbox_token(
183
+ self,
184
+ request: _pb.RevokeSandboxTokenRequest,
185
+ *,
186
+ timeout_s: float | None = None,
187
+ retry: bool = False,
188
+ ) -> _pb.RevokeSandboxTokenResponse:
189
+ """RevokeSandboxToken revokes one token by its jti: dakr renders a new
190
+ SandboxTokenDenylist revision carrying it, and the response says whether
191
+ the cluster has applied it yet. Developer.
192
+ """
193
+ return self._connect.unary(
194
+ "/sandbox.v1.SandboxService/RevokeSandboxToken",
195
+ request,
196
+ _pb.RevokeSandboxTokenResponse,
197
+ timeout_s=timeout_s,
198
+ retry=retry,
199
+ )
200
+
201
+ def estimate_warm_pool_cost(
202
+ self,
203
+ request: _pb.EstimateWarmPoolCostRequest,
204
+ *,
205
+ timeout_s: float | None = None,
206
+ retry: bool = False,
207
+ ) -> _pb.EstimateWarmPoolCostResponse:
208
+ """EstimateWarmPoolCost returns the monthly floor cost of keeping a warm pool
209
+ of the given size and per-sandbox resources on a cluster, priced from the
210
+ node pricing dakr holds for the sandbox node policy's instance types.
211
+ Without pricing it fails with pricing_unavailable, never a zero cost.
212
+ Viewer.
213
+ """
214
+ return self._connect.unary(
215
+ "/sandbox.v1.SandboxService/EstimateWarmPoolCost",
216
+ request,
217
+ _pb.EstimateWarmPoolCostResponse,
218
+ timeout_s=timeout_s,
219
+ retry=retry,
220
+ )
221
+
222
+ def get_sandbox_policy(
223
+ self,
224
+ request: _pb.GetSandboxPolicyRequest,
225
+ *,
226
+ timeout_s: float | None = None,
227
+ retry: bool = False,
228
+ ) -> _pb.GetSandboxPolicyResponse:
229
+ """GetSandboxPolicy returns one policy as authored in DevZero, with the
230
+ RuntimeClass its node policy resolved to and the conditions from its
231
+ relayed in-cluster status (including Rejected and WithinGuardrails).
232
+ Viewer.
233
+ """
234
+ return self._connect.unary(
235
+ "/sandbox.v1.SandboxService/GetSandboxPolicy",
236
+ request,
237
+ _pb.GetSandboxPolicyResponse,
238
+ timeout_s=timeout_s,
239
+ retry=retry,
240
+ )
241
+
242
+ def create_sandbox_policy(
243
+ self,
244
+ request: _pb.CreateSandboxPolicyRequest,
245
+ *,
246
+ timeout_s: float | None = None,
247
+ retry: bool = False,
248
+ ) -> _pb.CreateSandboxPolicyResponse:
249
+ """CreateSandboxPolicy validates a new policy for one cluster, stores it and
250
+ renders it into the cluster outbox as a SandboxPolicy SandboxResource.
251
+ Admin (ADR-004).
252
+ """
253
+ return self._connect.unary(
254
+ "/sandbox.v1.SandboxService/CreateSandboxPolicy",
255
+ request,
256
+ _pb.CreateSandboxPolicyResponse,
257
+ timeout_s=timeout_s,
258
+ retry=retry,
259
+ )
260
+
261
+ def update_sandbox_policy(
262
+ self,
263
+ request: _pb.UpdateSandboxPolicyRequest,
264
+ *,
265
+ timeout_s: float | None = None,
266
+ retry: bool = False,
267
+ ) -> _pb.UpdateSandboxPolicyResponse:
268
+ """UpdateSandboxPolicy replaces the spec of an existing policy and renders
269
+ it again. The name and cluster are immutable. Admin (ADR-004).
270
+ """
271
+ return self._connect.unary(
272
+ "/sandbox.v1.SandboxService/UpdateSandboxPolicy",
273
+ request,
274
+ _pb.UpdateSandboxPolicyResponse,
275
+ timeout_s=timeout_s,
276
+ retry=retry,
277
+ )
278
+
279
+ def delete_sandbox_policy(
280
+ self,
281
+ request: _pb.DeleteSandboxPolicyRequest,
282
+ *,
283
+ timeout_s: float | None = None,
284
+ retry: bool = False,
285
+ ) -> _pb.DeleteSandboxPolicyResponse:
286
+ """DeleteSandboxPolicy deletes a policy: it leaves every listing and read at
287
+ once, and dakr renders its SandboxPolicy as ACTION_DELETE into the cluster
288
+ outbox. In-cluster the drain finalizer holds the CR (ADR-010 policy
289
+ drain): new sandboxes on it are refused at once, its warm pool scales to
290
+ zero, running sandboxes may keep running until the drain deadline (24 h
291
+ capped at the policy's max TTL), and any left then are deleted. The
292
+ managed namespace is never deleted. Deleting a policy already deleted is
293
+ not_found. Admin (ADR-004).
294
+ """
295
+ return self._connect.unary(
296
+ "/sandbox.v1.SandboxService/DeleteSandboxPolicy",
297
+ request,
298
+ _pb.DeleteSandboxPolicyResponse,
299
+ timeout_s=timeout_s,
300
+ retry=retry,
301
+ )
302
+
303
+ def get_sandbox_cluster_guardrails(
304
+ self,
305
+ request: _pb.GetSandboxClusterGuardrailsRequest,
306
+ *,
307
+ timeout_s: float | None = None,
308
+ retry: bool = False,
309
+ ) -> _pb.GetSandboxClusterGuardrailsResponse:
310
+ """GetSandboxClusterGuardrails returns the guardrails authored for one
311
+ cluster, or the installer default when none were saved. Viewer.
312
+ """
313
+ return self._connect.unary(
314
+ "/sandbox.v1.SandboxService/GetSandboxClusterGuardrails",
315
+ request,
316
+ _pb.GetSandboxClusterGuardrailsResponse,
317
+ timeout_s=timeout_s,
318
+ retry=retry,
319
+ )
320
+
321
+ def set_sandbox_cluster_guardrails(
322
+ self,
323
+ request: _pb.SetSandboxClusterGuardrailsRequest,
324
+ *,
325
+ timeout_s: float | None = None,
326
+ retry: bool = False,
327
+ ) -> _pb.SetSandboxClusterGuardrailsResponse:
328
+ """SetSandboxClusterGuardrails stores the guardrails of one cluster and
329
+ renders them into the cluster outbox as SandboxClusterGuardrails/default.
330
+ Admin (ADR-004, devzero-inc/services#12004).
331
+ """
332
+ return self._connect.unary(
333
+ "/sandbox.v1.SandboxService/SetSandboxClusterGuardrails",
334
+ request,
335
+ _pb.SetSandboxClusterGuardrailsResponse,
336
+ timeout_s=timeout_s,
337
+ retry=retry,
338
+ )
339
+
340
+ def get_sandbox_endpoint(
341
+ self,
342
+ request: _pb.GetSandboxEndpointRequest,
343
+ *,
344
+ timeout_s: float | None = None,
345
+ retry: bool = False,
346
+ ) -> _pb.GetSandboxEndpointResponse:
347
+ """GetSandboxEndpoint returns the endpoint authored for one cluster, with
348
+ its render revision and the cluster's apply outcome for that revision;
349
+ endpoint is unset while none was set. Viewer, like the guardrails read:
350
+ ListSandboxPolicies already shows every member the endpoint's mode,
351
+ hostname and visibility.
352
+ """
353
+ return self._connect.unary(
354
+ "/sandbox.v1.SandboxService/GetSandboxEndpoint",
355
+ request,
356
+ _pb.GetSandboxEndpointResponse,
357
+ timeout_s=timeout_s,
358
+ retry=retry,
359
+ )
360
+
361
+ def set_sandbox_endpoint(
362
+ self,
363
+ request: _pb.SetSandboxEndpointRequest,
364
+ *,
365
+ timeout_s: float | None = None,
366
+ retry: bool = False,
367
+ ) -> _pb.SetSandboxEndpointResponse:
368
+ """SetSandboxEndpoint replaces the endpoint of one cluster and renders it
369
+ into the cluster outbox as SandboxEndpoint/default, which tunr applies
370
+ and the operator reconciles (ADR-006). Sandboxes on the cluster then
371
+ carry connect URLs on the hostname. Phase 1 accepts mode BYO only. A set
372
+ whose render equals the latest one changes nothing and keeps its
373
+ revision. Admin (ADR-003 API contract).
374
+ """
375
+ return self._connect.unary(
376
+ "/sandbox.v1.SandboxService/SetSandboxEndpoint",
377
+ request,
378
+ _pb.SetSandboxEndpointResponse,
379
+ timeout_s=timeout_s,
380
+ retry=retry,
381
+ )