@fabrika/provider-zerops 0.9.0-cloudflare.3 → 0.9.0-dev.10

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.
Files changed (69) hide show
  1. package/package.json +11 -10
  2. package/sandbox/Dockerfile +16 -0
  3. package/sandbox/bin/postgres-auth.sh +38 -0
  4. package/sandbox/bin/reset.sh +12 -0
  5. package/sandbox/bin/run-build.sh +35 -0
  6. package/sandbox/bin/run-launcher.sh +18 -0
  7. package/sandbox/bin/start-launcher.sh +25 -0
  8. package/sandbox/bin/stop.sh +47 -0
  9. package/sandbox/init.sh +61 -0
  10. package/src/api/client.ts +3 -1
  11. package/src/api/errors.ts +7 -3
  12. package/src/control.ts +150 -35
  13. package/src/execution.ts +12 -77
  14. package/src/installation/topology/setups.ts +3 -1
  15. package/src/installation/topology/topology.ts +1 -1
  16. package/src/manifest.ts +2 -7
  17. package/src/namespace/claims.ts +4 -0
  18. package/src/namespace/codec.ts +17 -0
  19. package/src/namespace/errors.ts +21 -0
  20. package/src/namespace/manifest.ts +31 -5
  21. package/src/namespace/provisioning.ts +68 -112
  22. package/src/namespace/proxy-reads.ts +16 -1
  23. package/src/namespace/proxy-secrets.ts +18 -5
  24. package/src/namespace/sandbox-host.ts +212 -0
  25. package/src/namespace/subdomain.ts +113 -0
  26. package/src/namespace/topology.ts +1 -1
  27. package/src/namespace/types.ts +11 -0
  28. package/src/namespace/update.ts +1 -0
  29. package/src/provider.ts +0 -40
  30. package/src/proxy-manifest-carrier.ts +26 -5
  31. package/src/sandbox/base-image.ts +100 -0
  32. package/src/sandbox/constants.ts +44 -0
  33. package/src/sandbox/deploy.ts +471 -0
  34. package/src/sandbox/dev-artifact.ts +206 -0
  35. package/src/sandbox/lifecycle.ts +204 -0
  36. package/src/sandbox/scripts.ts +26 -0
  37. package/src/sandbox-host.ts +28 -0
  38. package/src/source/port.ts +5 -0
  39. package/src/zbox/client.ts +259 -0
  40. package/src/zbox/errors.ts +45 -0
  41. package/src/zbox/index.ts +22 -0
  42. package/src/zbox/types.ts +165 -0
  43. package/types/src/api/errors.d.ts +3 -1
  44. package/types/src/control.d.ts +12 -1
  45. package/types/src/execution.d.ts +2 -13
  46. package/types/src/installation/topology/installation-schemas.d.ts +14 -14
  47. package/types/src/installation/topology/topology.d.ts +1 -1
  48. package/types/src/manifest.d.ts +3 -8
  49. package/types/src/namespace/codec.d.ts +18 -0
  50. package/types/src/namespace/errors.d.ts +10 -0
  51. package/types/src/namespace/proxy-reads.d.ts +6 -1
  52. package/types/src/namespace/proxy-secrets.d.ts +1 -1
  53. package/types/src/namespace/sandbox-host.d.ts +23 -0
  54. package/types/src/namespace/subdomain.d.ts +43 -0
  55. package/types/src/namespace/types.d.ts +10 -0
  56. package/types/src/provider.d.ts +0 -3
  57. package/types/src/proxy-manifest-carrier.d.ts +14 -1
  58. package/types/src/sandbox/base-image.d.ts +28 -0
  59. package/types/src/sandbox/constants.d.ts +30 -0
  60. package/types/src/sandbox/deploy.d.ts +75 -0
  61. package/types/src/sandbox/dev-artifact.d.ts +51 -0
  62. package/types/src/sandbox/lifecycle.d.ts +27 -0
  63. package/types/src/sandbox/scripts.d.ts +11 -0
  64. package/types/src/sandbox-host.d.ts +16 -0
  65. package/types/src/source/port.d.ts +5 -0
  66. package/types/src/zbox/client.d.ts +2 -0
  67. package/types/src/zbox/errors.d.ts +25 -0
  68. package/types/src/zbox/index.d.ts +3 -0
  69. package/types/src/zbox/types.d.ts +433 -0
@@ -0,0 +1,16 @@
1
+ /** The hostname of a namespace's dev sandbox host: a Zerops Box Workspace, which runs one sandbox per MCP workspace. */
2
+ export declare const SANDBOX_HOST_HOSTNAME = "zbox";
3
+ /** The type an import declares. */
4
+ export declare const SANDBOX_HOST_TYPE = "zbox@1";
5
+ /** The type the platform reads back for it (measured live): the OS-qualified form of `SANDBOX_HOST_TYPE`. */
6
+ export declare const SANDBOX_HOST_SERVICE_TYPE = "ubuntu/zbox@1";
7
+ /** The Box API port. Control reaches it over the service's public subdomain, with the key Fabrika generated for it. */
8
+ export declare const SANDBOX_HOST_API_PORT = 8080;
9
+ /** The Box router port: the namespace proxy reaches a sandbox's project-only application port here, by Host. */
10
+ export declare const SANDBOX_HOST_ROUTER_PORT = 8081;
11
+ /** The service variable Box reads its API key from; Fabrika writes it sensitive and never reads it back. */
12
+ export declare const SANDBOX_HOST_KEY_VARIABLE = "ZBOX_WORKSPACE_API_KEY";
13
+ /** The dial address of the Box router from the namespace proxy. */
14
+ export declare const SANDBOX_UPSTREAM = "zbox:8081";
15
+ /** The Host the namespace proxy sends the Box router to reach a sandbox's application port: the bare form, no domain. */
16
+ export declare function sandboxUpstreamHost(sandboxId: string): string;
@@ -36,6 +36,11 @@ export interface ZeropsSourceUploadInput {
36
36
  readonly archive: ZeropsSourceArchive;
37
37
  /** A credential in transit: never logged, persisted, or returned in an error. */
38
38
  readonly uploadUrl: string;
39
+ /**
40
+ * Present for a dev sandbox: `uploadUrl` is the sandbox host's file endpoint for one sandbox, and the PUT carries this
41
+ * bearer. A credential in transit, like `uploadUrl`.
42
+ */
43
+ readonly uploadBearer?: string;
39
44
  readonly signal: AbortSignal;
40
45
  }
41
46
  export interface ZeropsSourceUploadResult {
@@ -0,0 +1,2 @@
1
+ import { type ZboxClient, type ZboxClientOptions } from './types';
2
+ export declare const createZboxClient: (options: ZboxClientOptions) => ZboxClient;
@@ -0,0 +1,25 @@
1
+ /**
2
+ * A failed Box Workspace API call. `code` is Box's `error.code` when the body was Box's error JSON, `http_<status>`
3
+ * when it was not, or one of the client's own: `unreadable` (a success body that does not parse), `timeout`,
4
+ * `unreachable` (status 0 for the last two). The message names the operation and nothing the server sent beyond
5
+ * the code: a body is the server's text, and a message may reach a log.
6
+ */
7
+ export declare class ZboxApiError extends Error {
8
+ readonly operation: string;
9
+ readonly status: number;
10
+ readonly code: string;
11
+ constructor(operation: string, status: number, code: string);
12
+ }
13
+ /** An asynchronous Box operation that ended FAILED. `code` is Box's error only when it is an identifier. */
14
+ export declare class ZboxOperationFailed extends Error {
15
+ readonly kind: string;
16
+ readonly operationId: string;
17
+ readonly code: string | null;
18
+ constructor(kind: string, operationId: string, code: string | null);
19
+ }
20
+ export declare const zboxErrorCode: (status: number, body: unknown) => string;
21
+ export declare const zboxOperationErrorCode: (error: string | null) => string | null;
22
+ export declare const isZboxNotFound: (error: unknown) => error is ZboxApiError;
23
+ export declare const isZboxWorkspaceFull: (error: unknown) => error is ZboxApiError;
24
+ /** An upload over the workspace's body limit; nginx answers it with an HTML page, so only the status identifies it. */
25
+ export declare const isZboxTooLarge: (error: unknown) => error is ZboxApiError;
@@ -0,0 +1,3 @@
1
+ export { createZboxClient } from './client';
2
+ export { isZboxNotFound, isZboxTooLarge, isZboxWorkspaceFull, ZboxApiError, ZboxOperationFailed } from './errors';
3
+ export type { ZboxAwaitOptions, ZboxBase, ZboxBody, ZboxClient, ZboxClientOptions, ZboxCreateSandboxInput, ZboxExecInput, ZboxExecResult, ZboxFetch, ZboxIngressPort, ZboxLaunch, ZboxNetworkMode, ZboxOperation, ZboxPortAccess, ZboxProcessInput, ZboxSandbox, ZboxSession, ZboxWorkspace, } from './types';
@@ -0,0 +1,433 @@
1
+ import { z } from 'zod';
2
+ export declare const zboxOperationSchema: z.ZodObject<{
3
+ id: z.ZodString;
4
+ sandboxId: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodString>>, string | null, string | null | undefined>;
5
+ kind: z.ZodString;
6
+ status: z.ZodEnum<["PENDING", "RUNNING", "FINISHED", "FAILED"]>;
7
+ error: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodString>>, string | null, string | null | undefined>;
8
+ }, "strip", z.ZodTypeAny, {
9
+ kind: string;
10
+ status: "FINISHED" | "FAILED" | "PENDING" | "RUNNING";
11
+ id: string;
12
+ error: string | null;
13
+ sandboxId: string | null;
14
+ }, {
15
+ kind: string;
16
+ status: "FINISHED" | "FAILED" | "PENDING" | "RUNNING";
17
+ id: string;
18
+ error?: string | null | undefined;
19
+ sandboxId?: string | null | undefined;
20
+ }>;
21
+ export type ZboxOperation = z.infer<typeof zboxOperationSchema>;
22
+ export declare const zboxSandboxSchema: z.ZodObject<{
23
+ id: z.ZodString;
24
+ name: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodString>>, string | null, string | null | undefined>;
25
+ status: z.ZodEnum<["CREATING", "RUNNING", "PARKING", "PARKED", "WAKING", "FORKING", "RESTORING", "FAILED", "TERMINATED", "ARCHIVED"]>;
26
+ baseDigest: z.ZodString;
27
+ hosts: z.ZodArray<z.ZodObject<{
28
+ port: z.ZodNumber;
29
+ access: z.ZodString;
30
+ url: z.ZodString;
31
+ }, "strip", z.ZodTypeAny, {
32
+ access: string;
33
+ url: string;
34
+ port: number;
35
+ }, {
36
+ access: string;
37
+ url: string;
38
+ port: number;
39
+ }>, "many">;
40
+ policyGeneration: z.ZodNumber;
41
+ }, "strip", z.ZodTypeAny, {
42
+ name: string | null;
43
+ status: "FAILED" | "CREATING" | "RUNNING" | "PARKING" | "PARKED" | "WAKING" | "FORKING" | "RESTORING" | "TERMINATED" | "ARCHIVED";
44
+ id: string;
45
+ hosts: {
46
+ access: string;
47
+ url: string;
48
+ port: number;
49
+ }[];
50
+ baseDigest: string;
51
+ policyGeneration: number;
52
+ }, {
53
+ status: "FAILED" | "CREATING" | "RUNNING" | "PARKING" | "PARKED" | "WAKING" | "FORKING" | "RESTORING" | "TERMINATED" | "ARCHIVED";
54
+ id: string;
55
+ hosts: {
56
+ access: string;
57
+ url: string;
58
+ port: number;
59
+ }[];
60
+ baseDigest: string;
61
+ policyGeneration: number;
62
+ name?: string | null | undefined;
63
+ }>;
64
+ export type ZboxSandbox = z.infer<typeof zboxSandboxSchema>;
65
+ export declare const zboxSandboxListSchema: z.ZodObject<{
66
+ items: z.ZodArray<z.ZodObject<{
67
+ id: z.ZodString;
68
+ name: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodString>>, string | null, string | null | undefined>;
69
+ status: z.ZodEnum<["CREATING", "RUNNING", "PARKING", "PARKED", "WAKING", "FORKING", "RESTORING", "FAILED", "TERMINATED", "ARCHIVED"]>;
70
+ baseDigest: z.ZodString;
71
+ hosts: z.ZodArray<z.ZodObject<{
72
+ port: z.ZodNumber;
73
+ access: z.ZodString;
74
+ url: z.ZodString;
75
+ }, "strip", z.ZodTypeAny, {
76
+ access: string;
77
+ url: string;
78
+ port: number;
79
+ }, {
80
+ access: string;
81
+ url: string;
82
+ port: number;
83
+ }>, "many">;
84
+ policyGeneration: z.ZodNumber;
85
+ }, "strip", z.ZodTypeAny, {
86
+ name: string | null;
87
+ status: "FAILED" | "CREATING" | "RUNNING" | "PARKING" | "PARKED" | "WAKING" | "FORKING" | "RESTORING" | "TERMINATED" | "ARCHIVED";
88
+ id: string;
89
+ hosts: {
90
+ access: string;
91
+ url: string;
92
+ port: number;
93
+ }[];
94
+ baseDigest: string;
95
+ policyGeneration: number;
96
+ }, {
97
+ status: "FAILED" | "CREATING" | "RUNNING" | "PARKING" | "PARKED" | "WAKING" | "FORKING" | "RESTORING" | "TERMINATED" | "ARCHIVED";
98
+ id: string;
99
+ hosts: {
100
+ access: string;
101
+ url: string;
102
+ port: number;
103
+ }[];
104
+ baseDigest: string;
105
+ policyGeneration: number;
106
+ name?: string | null | undefined;
107
+ }>, "many">;
108
+ }, "strip", z.ZodTypeAny, {
109
+ items: {
110
+ name: string | null;
111
+ status: "FAILED" | "CREATING" | "RUNNING" | "PARKING" | "PARKED" | "WAKING" | "FORKING" | "RESTORING" | "TERMINATED" | "ARCHIVED";
112
+ id: string;
113
+ hosts: {
114
+ access: string;
115
+ url: string;
116
+ port: number;
117
+ }[];
118
+ baseDigest: string;
119
+ policyGeneration: number;
120
+ }[];
121
+ }, {
122
+ items: {
123
+ status: "FAILED" | "CREATING" | "RUNNING" | "PARKING" | "PARKED" | "WAKING" | "FORKING" | "RESTORING" | "TERMINATED" | "ARCHIVED";
124
+ id: string;
125
+ hosts: {
126
+ access: string;
127
+ url: string;
128
+ port: number;
129
+ }[];
130
+ baseDigest: string;
131
+ policyGeneration: number;
132
+ name?: string | null | undefined;
133
+ }[];
134
+ }>;
135
+ export declare const zboxSpawnSchema: z.ZodObject<{
136
+ operation: z.ZodObject<{
137
+ id: z.ZodString;
138
+ sandboxId: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodString>>, string | null, string | null | undefined>;
139
+ kind: z.ZodString;
140
+ status: z.ZodEnum<["PENDING", "RUNNING", "FINISHED", "FAILED"]>;
141
+ error: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodString>>, string | null, string | null | undefined>;
142
+ }, "strip", z.ZodTypeAny, {
143
+ kind: string;
144
+ status: "FINISHED" | "FAILED" | "PENDING" | "RUNNING";
145
+ id: string;
146
+ error: string | null;
147
+ sandboxId: string | null;
148
+ }, {
149
+ kind: string;
150
+ status: "FINISHED" | "FAILED" | "PENDING" | "RUNNING";
151
+ id: string;
152
+ error?: string | null | undefined;
153
+ sandboxId?: string | null | undefined;
154
+ }>;
155
+ sandboxes: z.ZodArray<z.ZodObject<{
156
+ id: z.ZodString;
157
+ name: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodString>>, string | null, string | null | undefined>;
158
+ status: z.ZodEnum<["CREATING", "RUNNING", "PARKING", "PARKED", "WAKING", "FORKING", "RESTORING", "FAILED", "TERMINATED", "ARCHIVED"]>;
159
+ baseDigest: z.ZodString;
160
+ hosts: z.ZodArray<z.ZodObject<{
161
+ port: z.ZodNumber;
162
+ access: z.ZodString;
163
+ url: z.ZodString;
164
+ }, "strip", z.ZodTypeAny, {
165
+ access: string;
166
+ url: string;
167
+ port: number;
168
+ }, {
169
+ access: string;
170
+ url: string;
171
+ port: number;
172
+ }>, "many">;
173
+ policyGeneration: z.ZodNumber;
174
+ }, "strip", z.ZodTypeAny, {
175
+ name: string | null;
176
+ status: "FAILED" | "CREATING" | "RUNNING" | "PARKING" | "PARKED" | "WAKING" | "FORKING" | "RESTORING" | "TERMINATED" | "ARCHIVED";
177
+ id: string;
178
+ hosts: {
179
+ access: string;
180
+ url: string;
181
+ port: number;
182
+ }[];
183
+ baseDigest: string;
184
+ policyGeneration: number;
185
+ }, {
186
+ status: "FAILED" | "CREATING" | "RUNNING" | "PARKING" | "PARKED" | "WAKING" | "FORKING" | "RESTORING" | "TERMINATED" | "ARCHIVED";
187
+ id: string;
188
+ hosts: {
189
+ access: string;
190
+ url: string;
191
+ port: number;
192
+ }[];
193
+ baseDigest: string;
194
+ policyGeneration: number;
195
+ name?: string | null | undefined;
196
+ }>, "many">;
197
+ }, "strip", z.ZodTypeAny, {
198
+ operation: {
199
+ kind: string;
200
+ status: "FINISHED" | "FAILED" | "PENDING" | "RUNNING";
201
+ id: string;
202
+ error: string | null;
203
+ sandboxId: string | null;
204
+ };
205
+ sandboxes: {
206
+ name: string | null;
207
+ status: "FAILED" | "CREATING" | "RUNNING" | "PARKING" | "PARKED" | "WAKING" | "FORKING" | "RESTORING" | "TERMINATED" | "ARCHIVED";
208
+ id: string;
209
+ hosts: {
210
+ access: string;
211
+ url: string;
212
+ port: number;
213
+ }[];
214
+ baseDigest: string;
215
+ policyGeneration: number;
216
+ }[];
217
+ }, {
218
+ operation: {
219
+ kind: string;
220
+ status: "FINISHED" | "FAILED" | "PENDING" | "RUNNING";
221
+ id: string;
222
+ error?: string | null | undefined;
223
+ sandboxId?: string | null | undefined;
224
+ };
225
+ sandboxes: {
226
+ status: "FAILED" | "CREATING" | "RUNNING" | "PARKING" | "PARKED" | "WAKING" | "FORKING" | "RESTORING" | "TERMINATED" | "ARCHIVED";
227
+ id: string;
228
+ hosts: {
229
+ access: string;
230
+ url: string;
231
+ port: number;
232
+ }[];
233
+ baseDigest: string;
234
+ policyGeneration: number;
235
+ name?: string | null | undefined;
236
+ }[];
237
+ }>;
238
+ export declare const zboxWorkspaceSchema: z.ZodObject<{
239
+ version: z.ZodString;
240
+ }, "strip", z.ZodTypeAny, {
241
+ version: string;
242
+ }, {
243
+ version: string;
244
+ }>;
245
+ export type ZboxWorkspace = z.infer<typeof zboxWorkspaceSchema>;
246
+ export declare const zboxBaseSchema: z.ZodObject<{
247
+ digest: z.ZodString;
248
+ name: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodString>>, string | null, string | null | undefined>;
249
+ imageRef: z.ZodString;
250
+ status: z.ZodEnum<["PULLING", "FLATTENING", "READY", "FAILED", "DELETED"]>;
251
+ }, "strip", z.ZodTypeAny, {
252
+ name: string | null;
253
+ status: "FAILED" | "DELETED" | "PULLING" | "FLATTENING" | "READY";
254
+ digest: string;
255
+ imageRef: string;
256
+ }, {
257
+ status: "FAILED" | "DELETED" | "PULLING" | "FLATTENING" | "READY";
258
+ digest: string;
259
+ imageRef: string;
260
+ name?: string | null | undefined;
261
+ }>;
262
+ export type ZboxBase = z.infer<typeof zboxBaseSchema>;
263
+ export declare const zboxBaseListSchema: z.ZodObject<{
264
+ items: z.ZodArray<z.ZodObject<{
265
+ digest: z.ZodString;
266
+ name: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodString>>, string | null, string | null | undefined>;
267
+ imageRef: z.ZodString;
268
+ status: z.ZodEnum<["PULLING", "FLATTENING", "READY", "FAILED", "DELETED"]>;
269
+ }, "strip", z.ZodTypeAny, {
270
+ name: string | null;
271
+ status: "FAILED" | "DELETED" | "PULLING" | "FLATTENING" | "READY";
272
+ digest: string;
273
+ imageRef: string;
274
+ }, {
275
+ status: "FAILED" | "DELETED" | "PULLING" | "FLATTENING" | "READY";
276
+ digest: string;
277
+ imageRef: string;
278
+ name?: string | null | undefined;
279
+ }>, "many">;
280
+ }, "strip", z.ZodTypeAny, {
281
+ items: {
282
+ name: string | null;
283
+ status: "FAILED" | "DELETED" | "PULLING" | "FLATTENING" | "READY";
284
+ digest: string;
285
+ imageRef: string;
286
+ }[];
287
+ }, {
288
+ items: {
289
+ status: "FAILED" | "DELETED" | "PULLING" | "FLATTENING" | "READY";
290
+ digest: string;
291
+ imageRef: string;
292
+ name?: string | null | undefined;
293
+ }[];
294
+ }>;
295
+ export declare const zboxExecResultSchema: z.ZodObject<{
296
+ stdout: z.ZodString;
297
+ stderr: z.ZodString;
298
+ exitCode: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodNumber>>, number | null, number | null | undefined>;
299
+ timedOut: z.ZodBoolean;
300
+ stdoutTruncated: z.ZodBoolean;
301
+ stderrTruncated: z.ZodBoolean;
302
+ }, "strip", z.ZodTypeAny, {
303
+ stdout: string;
304
+ stderr: string;
305
+ exitCode: number | null;
306
+ timedOut: boolean;
307
+ stdoutTruncated: boolean;
308
+ stderrTruncated: boolean;
309
+ }, {
310
+ stdout: string;
311
+ stderr: string;
312
+ timedOut: boolean;
313
+ stdoutTruncated: boolean;
314
+ stderrTruncated: boolean;
315
+ exitCode?: number | null | undefined;
316
+ }>;
317
+ export type ZboxExecResult = z.infer<typeof zboxExecResultSchema>;
318
+ export declare const zboxSessionSchema: z.ZodObject<{
319
+ id: z.ZodString;
320
+ status: z.ZodEnum<["OPEN", "CLOSED", "FAILED"]>;
321
+ exitCode: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodNumber>>, number | null, number | null | undefined>;
322
+ hasOutput: z.ZodBoolean;
323
+ }, "strip", z.ZodTypeAny, {
324
+ status: "FAILED" | "OPEN" | "CLOSED";
325
+ id: string;
326
+ exitCode: number | null;
327
+ hasOutput: boolean;
328
+ }, {
329
+ status: "FAILED" | "OPEN" | "CLOSED";
330
+ id: string;
331
+ hasOutput: boolean;
332
+ exitCode?: number | null | undefined;
333
+ }>;
334
+ export type ZboxSession = z.infer<typeof zboxSessionSchema>;
335
+ export declare const zboxSuccessSchema: z.ZodObject<{
336
+ success: z.ZodLiteral<true>;
337
+ }, "strip", z.ZodTypeAny, {
338
+ success: true;
339
+ }, {
340
+ success: true;
341
+ }>;
342
+ export type ZboxNetworkMode = 'AIRGAPPED' | 'PROJECT' | 'INTERNET' | 'PROJECT_INTERNET';
343
+ export type ZboxPortAccess = 'PROJECT' | 'MEMBERS' | 'TICKET' | 'TOKEN' | 'PUBLIC';
344
+ export interface ZboxIngressPort {
345
+ port: number;
346
+ access: ZboxPortAccess;
347
+ wakeOnRequest: boolean;
348
+ }
349
+ /** No `env`: a credential reaches a sandbox only in the root-only file a deploy writes through the file API. */
350
+ export interface ZboxLaunch {
351
+ entrypoint?: string[];
352
+ cmd?: string[];
353
+ workingDir?: string;
354
+ }
355
+ export interface ZboxCreateSandboxInput {
356
+ name: string;
357
+ baseDigest: string;
358
+ cpus: number;
359
+ memoryBytes: number;
360
+ /** Box refuses a create whose disk does not fit the workspace's data volume, and its default can exceed a small one. */
361
+ diskBytes: number;
362
+ networkMode: ZboxNetworkMode;
363
+ launch: ZboxLaunch;
364
+ ports: ZboxIngressPort[];
365
+ /** Reused on a retry so Box answers the first create instead of making a second sandbox. */
366
+ idempotencyKey: string;
367
+ }
368
+ /** No `env`, for the same reason as `ZboxLaunch`. */
369
+ export interface ZboxExecInput {
370
+ command: string[];
371
+ workingDir?: string;
372
+ timeoutSeconds?: number;
373
+ }
374
+ export interface ZboxProcessInput {
375
+ command: string[];
376
+ workingDir?: string;
377
+ }
378
+ export type ZboxBody = Uint8Array<ArrayBuffer> | ReadableStream<Uint8Array>;
379
+ export type ZboxFetch = (input: string, init: {
380
+ method: string;
381
+ headers: Record<string, string>;
382
+ body?: string | ZboxBody;
383
+ signal: AbortSignal;
384
+ }) => Promise<Response>;
385
+ export interface ZboxClientOptions {
386
+ /** The API origin; requests go to `<baseUrl>/api/rest/…`. */
387
+ baseUrl: string;
388
+ /** The Workspace API key, sent as `Authorization: Bearer`. Never logged. */
389
+ apiKey: string;
390
+ fetch?: ZboxFetch;
391
+ /** Generates the `Idempotency-Key` of a call whose caller supplied none. */
392
+ idempotencyKey?: () => string;
393
+ }
394
+ export interface ZboxAwaitOptions {
395
+ signal?: AbortSignal;
396
+ /** Milliseconds from now after which waiting gives up. */
397
+ deadlineMs: number;
398
+ }
399
+ export interface ZboxClient {
400
+ getWorkspace(signal?: AbortSignal): Promise<ZboxWorkspace>;
401
+ pullBase(input: {
402
+ imageRef: string;
403
+ name: string;
404
+ }, signal?: AbortSignal): Promise<ZboxOperation>;
405
+ buildBase(input: {
406
+ context: ZboxBody;
407
+ name: string;
408
+ }, signal?: AbortSignal): Promise<ZboxOperation>;
409
+ listBases(signal?: AbortSignal): Promise<ZboxBase[]>;
410
+ getOperation(id: string, waitSeconds: number, signal?: AbortSignal): Promise<ZboxOperation>;
411
+ awaitOperation(operation: ZboxOperation, options: ZboxAwaitOptions): Promise<ZboxOperation>;
412
+ createSandbox(input: ZboxCreateSandboxInput, signal?: AbortSignal): Promise<{
413
+ operation: ZboxOperation;
414
+ sandbox: ZboxSandbox;
415
+ }>;
416
+ getSandbox(id: string, signal?: AbortSignal): Promise<ZboxSandbox>;
417
+ findSandboxByName(name: string, signal?: AbortSignal): Promise<ZboxSandbox | null>;
418
+ deleteSandbox(id: string, idempotencyKey: string, signal?: AbortSignal): Promise<void>;
419
+ park(id: string, input: {
420
+ memory: boolean;
421
+ }, signal?: AbortSignal): Promise<ZboxOperation>;
422
+ wake(id: string, signal?: AbortSignal): Promise<ZboxOperation>;
423
+ exec(id: string, input: ZboxExecInput, signal?: AbortSignal): Promise<ZboxExecResult>;
424
+ startProcess(id: string, input: ZboxProcessInput, signal?: AbortSignal): Promise<ZboxSession>;
425
+ getSession(id: string, signal?: AbortSignal): Promise<ZboxSession>;
426
+ sessionOutput(id: string, signal?: AbortSignal): Promise<Uint8Array>;
427
+ /** `mode` is the octal file mode (Box defaults to 0644). */
428
+ putFile(id: string, path: string, body: ZboxBody, options?: {
429
+ mode?: string;
430
+ signal?: AbortSignal;
431
+ }): Promise<void>;
432
+ getFile(id: string, path: string, signal?: AbortSignal): Promise<Uint8Array | null>;
433
+ }