@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,259 @@
1
+ import type { z } from 'zod'
2
+ import { isZboxNotFound, ZboxApiError, zboxErrorCode, zboxOperationErrorCode, ZboxOperationFailed } from './errors'
3
+ import {
4
+ type ZboxAwaitOptions,
5
+ zboxBaseListSchema,
6
+ type ZboxBody,
7
+ type ZboxClient,
8
+ type ZboxClientOptions,
9
+ zboxExecResultSchema,
10
+ type ZboxOperation,
11
+ zboxOperationSchema,
12
+ type ZboxSandbox,
13
+ zboxSandboxListSchema,
14
+ zboxSandboxSchema,
15
+ zboxSessionSchema,
16
+ zboxSpawnSchema,
17
+ zboxSuccessSchema,
18
+ zboxWorkspaceSchema,
19
+ } from './types'
20
+
21
+ /** Box cuts a request off at 60 s; giving up first leaves the error ours to name. */
22
+ const REQUEST_TIMEOUT_MS = 55_000
23
+
24
+ /** The longest `waitSeconds` Box honours. */
25
+ const MAX_WAIT_SECONDS = 30
26
+
27
+ /** How long a create, park, wake or delete may take before the client stops waiting. Measured: all under 2 s. */
28
+ const OPERATION_DEADLINE_MS = 120_000
29
+
30
+ interface CallInit {
31
+ json?: unknown
32
+ body?: ZboxBody
33
+ idempotencyKey?: string
34
+ signal: AbortSignal | undefined
35
+ }
36
+
37
+ export const createZboxClient = (options: ZboxClientOptions): ZboxClient => {
38
+ const base = `${options.baseUrl.replace(/\/+$/, '')}/api/rest`
39
+ const doFetch = options.fetch ?? fetch
40
+ const nextIdempotencyKey = options.idempotencyKey ?? (() => crypto.randomUUID())
41
+
42
+ const errorBody = async (response: Response): Promise<unknown> => {
43
+ try {
44
+ return JSON.parse(await response.text())
45
+ } catch {
46
+ return null
47
+ }
48
+ }
49
+
50
+ const call = async <Result>(
51
+ operation: string,
52
+ method: string,
53
+ path: string,
54
+ init: CallInit,
55
+ read: (response: Response) => Promise<Result>,
56
+ ): Promise<Result> => {
57
+ init.signal?.throwIfAborted()
58
+ const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS)
59
+ const signal = init.signal === undefined ? timeout : AbortSignal.any([init.signal, timeout])
60
+ const headers: Record<string, string> = { authorization: `Bearer ${options.apiKey}`, accept: 'application/json' }
61
+ if (init.idempotencyKey !== undefined) {
62
+ headers['idempotency-key'] = init.idempotencyKey
63
+ }
64
+ let body: string | ZboxBody | undefined
65
+ if (init.json !== undefined) {
66
+ headers['content-type'] = 'application/json'
67
+ body = JSON.stringify(init.json)
68
+ } else if (init.body !== undefined) {
69
+ headers['content-type'] = 'application/octet-stream'
70
+ body = init.body
71
+ }
72
+ try {
73
+ const response = await doFetch(`${base}${path}`, { method, headers, body, signal })
74
+ if (!response.ok) {
75
+ throw new ZboxApiError(operation, response.status, zboxErrorCode(response.status, await errorBody(response)))
76
+ }
77
+ return await read(response)
78
+ } catch (error) {
79
+ if (error instanceof ZboxApiError) throw error
80
+ init.signal?.throwIfAborted()
81
+ // The fetch error is dropped: its text is the runtime's, and nothing here may echo a request.
82
+ throw new ZboxApiError(operation, 0, timeout.aborted ? 'timeout' : 'unreachable')
83
+ }
84
+ }
85
+
86
+ const json = <Output>(operation: string, schema: z.ZodType<Output, z.ZodTypeDef, unknown>) => async (response: Response): Promise<Output> => {
87
+ let value: unknown
88
+ try {
89
+ value = JSON.parse(await response.text())
90
+ } catch {
91
+ throw new ZboxApiError(operation, response.status, 'unreadable')
92
+ }
93
+ const parsed = schema.safeParse(value)
94
+ if (!parsed.success) {
95
+ throw new ZboxApiError(operation, response.status, 'unreadable')
96
+ }
97
+ return parsed.data
98
+ }
99
+
100
+ const bytes = async (response: Response): Promise<Uint8Array> => new Uint8Array(await response.arrayBuffer())
101
+
102
+ const sandboxPath = (id: string, suffix = ''): string => `/sandbox/${encodeURIComponent(id)}${suffix}`
103
+
104
+ const getOperation = (id: string, waitSeconds: number, signal?: AbortSignal): Promise<ZboxOperation> => {
105
+ const wait = Math.max(0, Math.min(MAX_WAIT_SECONDS, Math.floor(waitSeconds)))
106
+ return call(
107
+ 'get operation',
108
+ 'GET',
109
+ `/operation/${encodeURIComponent(id)}?waitSeconds=${wait}`,
110
+ { signal },
111
+ json('get operation', zboxOperationSchema),
112
+ )
113
+ }
114
+
115
+ const awaitOperation = async (operation: ZboxOperation, awaitOptions: ZboxAwaitOptions): Promise<ZboxOperation> => {
116
+ const startedAt = Date.now()
117
+ let current = operation
118
+ while (true) {
119
+ if (current.status === 'FINISHED') return current
120
+ if (current.status === 'FAILED') {
121
+ throw new ZboxOperationFailed(current.kind, current.id, zboxOperationErrorCode(current.error))
122
+ }
123
+ awaitOptions.signal?.throwIfAborted()
124
+ const remainingMs = awaitOptions.deadlineMs - (Date.now() - startedAt)
125
+ if (remainingMs <= 0) {
126
+ throw new ZboxApiError(`await ${current.kind} operation`, 0, 'timeout')
127
+ }
128
+ current = await getOperation(current.id, Math.max(1, Math.min(MAX_WAIT_SECONDS, Math.floor(remainingMs / 1000))), awaitOptions.signal)
129
+ }
130
+ }
131
+
132
+ const getSandbox = (id: string, signal?: AbortSignal): Promise<ZboxSandbox> =>
133
+ call('get sandbox', 'GET', sandboxPath(id), { signal }, json('get sandbox', zboxSandboxSchema))
134
+
135
+ const sandboxOperation = async (operation: string, id: string, suffix: string, payload: unknown, signal?: AbortSignal): Promise<ZboxOperation> => {
136
+ const started = await call(
137
+ operation,
138
+ 'POST',
139
+ sandboxPath(id, suffix),
140
+ { json: payload, idempotencyKey: nextIdempotencyKey(), signal },
141
+ json(operation, zboxOperationSchema),
142
+ )
143
+ return awaitOperation(started, { signal, deadlineMs: OPERATION_DEADLINE_MS })
144
+ }
145
+
146
+ return {
147
+ getWorkspace: (signal) => call('get workspace', 'GET', '/workspace', { signal }, json('get workspace', zboxWorkspaceSchema)),
148
+
149
+ pullBase: ({ imageRef, name }, signal) =>
150
+ call(
151
+ 'pull base',
152
+ 'POST',
153
+ '/base',
154
+ { json: { imageRef, name }, idempotencyKey: nextIdempotencyKey(), signal },
155
+ json('pull base', zboxOperationSchema),
156
+ ),
157
+
158
+ buildBase: ({ context, name }, signal) =>
159
+ call('build base', 'POST', `/base-build?name=${encodeURIComponent(name)}`, { body: context, signal }, json('build base', zboxOperationSchema)),
160
+
161
+ listBases: async (signal) => (await call('list bases', 'GET', '/base-list', { signal }, json('list bases', zboxBaseListSchema))).items,
162
+
163
+ getOperation,
164
+
165
+ awaitOperation,
166
+
167
+ createSandbox: async (input, signal) => {
168
+ const spawn = await call(
169
+ 'create sandbox',
170
+ 'POST',
171
+ '/sandbox',
172
+ {
173
+ json: {
174
+ name: input.name,
175
+ baseDigest: input.baseDigest,
176
+ cpus: input.cpus,
177
+ memoryBytes: input.memoryBytes,
178
+ diskBytes: input.diskBytes,
179
+ networkMode: input.networkMode,
180
+ integrations: [],
181
+ launch: { entrypoint: input.launch.entrypoint, cmd: input.launch.cmd, workingDir: input.launch.workingDir },
182
+ policy: {
183
+ ingress: {
184
+ ports: input.ports.map(({ port, access, wakeOnRequest }) => ({ port, access, protocol: 'HTTP', wakeOnRequest })),
185
+ },
186
+ secrets: { mode: 'NONE' },
187
+ },
188
+ waitSeconds: MAX_WAIT_SECONDS,
189
+ },
190
+ idempotencyKey: input.idempotencyKey,
191
+ signal,
192
+ },
193
+ json('create sandbox', zboxSpawnSchema),
194
+ )
195
+ const [created, ...others] = spawn.sandboxes
196
+ if (created === undefined || others.length > 0) {
197
+ throw new ZboxApiError('create sandbox', 200, 'unreadable')
198
+ }
199
+ const operation = await awaitOperation(spawn.operation, { signal, deadlineMs: OPERATION_DEADLINE_MS })
200
+ // A create answered before it finished carries the CREATING row; read the final one.
201
+ const sandbox = spawn.operation.status === 'FINISHED' ? created : await getSandbox(created.id, signal)
202
+ return { operation, sandbox }
203
+ },
204
+
205
+ getSandbox,
206
+
207
+ findSandboxByName: async (name, signal) => {
208
+ const list = await call('list sandboxes', 'GET', '/sandbox-list', { signal }, json('list sandboxes', zboxSandboxListSchema))
209
+ // Box refuses a create whose name a live sandbox holds, so at most one live sandbox matches.
210
+ return list.items.find((sandbox) => sandbox.name === name) ?? null
211
+ },
212
+
213
+ deleteSandbox: async (id, idempotencyKey, signal) => {
214
+ let started: ZboxOperation
215
+ try {
216
+ started = await call('delete sandbox', 'DELETE', sandboxPath(id), { idempotencyKey, signal }, json('delete sandbox', zboxOperationSchema))
217
+ } catch (error) {
218
+ if (isZboxNotFound(error) && error.code === 'sandboxNotFound') return
219
+ throw error
220
+ }
221
+ await awaitOperation(started, { signal, deadlineMs: OPERATION_DEADLINE_MS })
222
+ },
223
+
224
+ park: (id, { memory }, signal) => sandboxOperation('park sandbox', id, '/park', { memory }, signal),
225
+
226
+ wake: (id, signal) => sandboxOperation('wake sandbox', id, '/wake', {}, signal),
227
+
228
+ exec: (id, { command, workingDir, timeoutSeconds }, signal) =>
229
+ call('exec', 'POST', sandboxPath(id, '/exec'), { json: { command, workingDir, timeoutSeconds }, signal }, json('exec', zboxExecResultSchema)),
230
+
231
+ startProcess: (id, { command, workingDir }, signal) =>
232
+ call('start process', 'POST', sandboxPath(id, '/process'), { json: { command, workingDir }, signal }, json('start process', zboxSessionSchema)),
233
+
234
+ getSession: (id, signal) => call('get session', 'GET', `/session/${encodeURIComponent(id)}`, { signal }, json('get session', zboxSessionSchema)),
235
+
236
+ sessionOutput: (id, signal) => call('get session output', 'GET', `/session/${encodeURIComponent(id)}/output`, { signal }, bytes),
237
+
238
+ putFile: async (id, path, body, putOptions) => {
239
+ const mode = putOptions?.mode === undefined ? '' : `&mode=${encodeURIComponent(putOptions.mode)}`
240
+ await call(
241
+ 'put file',
242
+ 'PUT',
243
+ sandboxPath(id, `/file?path=${encodeURIComponent(path)}${mode}`),
244
+ { body, signal: putOptions?.signal },
245
+ json('put file', zboxSuccessSchema),
246
+ )
247
+ },
248
+
249
+ getFile: async (id, path, signal) => {
250
+ try {
251
+ return await call('get file', 'GET', sandboxPath(id, `/file?path=${encodeURIComponent(path)}`), { signal }, bytes)
252
+ } catch (error) {
253
+ // Only a missing PATH is an absent file; a missing sandbox stays an error.
254
+ if (isZboxNotFound(error) && error.code === 'pathNotFound') return null
255
+ throw error
256
+ }
257
+ },
258
+ }
259
+ }
@@ -0,0 +1,45 @@
1
+ import { z } from 'zod'
2
+
3
+ /** A Box error code is a fixed identifier; anything else in that slot is body text and must not reach a message. */
4
+ const BOX_CODE = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/
5
+
6
+ const codeSchema = z.string().regex(BOX_CODE).optional().catch(undefined)
7
+ // Live answers wrap the error (`{ error: { code } }`); the OpenAPI `Error` schema is the bare `{ code }`.
8
+ const errorBodySchema = z
9
+ .object({ code: codeSchema, error: z.object({ code: codeSchema }).optional().catch(undefined) })
10
+ .catch({ code: undefined, error: undefined })
11
+
12
+ /**
13
+ * A failed Box Workspace API call. `code` is Box's `error.code` when the body was Box's error JSON, `http_<status>`
14
+ * when it was not, or one of the client's own: `unreadable` (a success body that does not parse), `timeout`,
15
+ * `unreachable` (status 0 for the last two). The message names the operation and nothing the server sent beyond
16
+ * the code: a body is the server's text, and a message may reach a log.
17
+ */
18
+ export class ZboxApiError extends Error {
19
+ constructor(readonly operation: string, readonly status: number, readonly code: string) {
20
+ super(`zbox: ${operation} failed (${status === 0 ? code : `${status} ${code}`})`)
21
+ this.name = 'ZboxApiError'
22
+ }
23
+ }
24
+
25
+ /** An asynchronous Box operation that ended FAILED. `code` is Box's error only when it is an identifier. */
26
+ export class ZboxOperationFailed extends Error {
27
+ constructor(readonly kind: string, readonly operationId: string, readonly code: string | null) {
28
+ super(`zbox: ${kind} operation ${operationId} failed${code === null ? '' : ` (${code})`}`)
29
+ this.name = 'ZboxOperationFailed'
30
+ }
31
+ }
32
+
33
+ export const zboxErrorCode = (status: number, body: unknown): string => {
34
+ const parsed = errorBodySchema.parse(body)
35
+ return parsed.error?.code ?? parsed.code ?? `http_${status}`
36
+ }
37
+
38
+ export const zboxOperationErrorCode = (error: string | null): string | null => error !== null && BOX_CODE.test(error) ? error : null
39
+
40
+ export const isZboxNotFound = (error: unknown): error is ZboxApiError => error instanceof ZboxApiError && error.status === 404
41
+
42
+ export const isZboxWorkspaceFull = (error: unknown): error is ZboxApiError => error instanceof ZboxApiError && error.code === 'workspaceFull'
43
+
44
+ /** An upload over the workspace's body limit; nginx answers it with an HTML page, so only the status identifies it. */
45
+ export const isZboxTooLarge = (error: unknown): error is ZboxApiError => error instanceof ZboxApiError && error.status === 413
@@ -0,0 +1,22 @@
1
+ export { createZboxClient } from './client'
2
+ export { isZboxNotFound, isZboxTooLarge, isZboxWorkspaceFull, ZboxApiError, ZboxOperationFailed } from './errors'
3
+ export type {
4
+ ZboxAwaitOptions,
5
+ ZboxBase,
6
+ ZboxBody,
7
+ ZboxClient,
8
+ ZboxClientOptions,
9
+ ZboxCreateSandboxInput,
10
+ ZboxExecInput,
11
+ ZboxExecResult,
12
+ ZboxFetch,
13
+ ZboxIngressPort,
14
+ ZboxLaunch,
15
+ ZboxNetworkMode,
16
+ ZboxOperation,
17
+ ZboxPortAccess,
18
+ ZboxProcessInput,
19
+ ZboxSandbox,
20
+ ZboxSession,
21
+ ZboxWorkspace,
22
+ } from './types'
@@ -0,0 +1,165 @@
1
+ import { z } from 'zod'
2
+
3
+ // Each schema reads only the fields the provider uses; Box adds fields freely and they are ignored.
4
+
5
+ const nullableString = z
6
+ .string()
7
+ .nullish()
8
+ .transform((value) => value ?? null)
9
+
10
+ export const zboxOperationSchema = z.object({
11
+ id: z.string().min(1),
12
+ sandboxId: nullableString,
13
+ kind: z.string().min(1),
14
+ status: z.enum(['PENDING', 'RUNNING', 'FINISHED', 'FAILED']),
15
+ error: nullableString,
16
+ })
17
+ export type ZboxOperation = z.infer<typeof zboxOperationSchema>
18
+
19
+ export const zboxSandboxSchema = z.object({
20
+ id: z.string().min(1),
21
+ name: nullableString,
22
+ status: z.enum(['CREATING', 'RUNNING', 'PARKING', 'PARKED', 'WAKING', 'FORKING', 'RESTORING', 'FAILED', 'TERMINATED', 'ARCHIVED']),
23
+ baseDigest: z.string(),
24
+ hosts: z.array(
25
+ z.object({
26
+ port: z.number().int(),
27
+ access: z.string(),
28
+ url: z.string(),
29
+ }),
30
+ ),
31
+ policyGeneration: z.number().int(),
32
+ })
33
+ export type ZboxSandbox = z.infer<typeof zboxSandboxSchema>
34
+
35
+ export const zboxSandboxListSchema = z.object({ items: z.array(zboxSandboxSchema) })
36
+
37
+ export const zboxSpawnSchema = z.object({ operation: zboxOperationSchema, sandboxes: z.array(zboxSandboxSchema) })
38
+
39
+ export const zboxWorkspaceSchema = z.object({ version: z.string() })
40
+ export type ZboxWorkspace = z.infer<typeof zboxWorkspaceSchema>
41
+
42
+ export const zboxBaseSchema = z.object({
43
+ digest: z.string().min(1),
44
+ name: nullableString,
45
+ imageRef: z.string(),
46
+ status: z.enum(['PULLING', 'FLATTENING', 'READY', 'FAILED', 'DELETED']),
47
+ })
48
+ export type ZboxBase = z.infer<typeof zboxBaseSchema>
49
+
50
+ export const zboxBaseListSchema = z.object({ items: z.array(zboxBaseSchema) })
51
+
52
+ export const zboxExecResultSchema = z.object({
53
+ stdout: z.string(),
54
+ stderr: z.string(),
55
+ exitCode: z
56
+ .number()
57
+ .int()
58
+ .nullish()
59
+ .transform((value) => value ?? null),
60
+ timedOut: z.boolean(),
61
+ stdoutTruncated: z.boolean(),
62
+ stderrTruncated: z.boolean(),
63
+ })
64
+ export type ZboxExecResult = z.infer<typeof zboxExecResultSchema>
65
+
66
+ export const zboxSessionSchema = z.object({
67
+ id: z.string().min(1),
68
+ status: z.enum(['OPEN', 'CLOSED', 'FAILED']),
69
+ exitCode: z
70
+ .number()
71
+ .int()
72
+ .nullish()
73
+ .transform((value) => value ?? null),
74
+ hasOutput: z.boolean(),
75
+ })
76
+ export type ZboxSession = z.infer<typeof zboxSessionSchema>
77
+
78
+ export const zboxSuccessSchema = z.object({ success: z.literal(true) })
79
+
80
+ export type ZboxNetworkMode = 'AIRGAPPED' | 'PROJECT' | 'INTERNET' | 'PROJECT_INTERNET'
81
+ export type ZboxPortAccess = 'PROJECT' | 'MEMBERS' | 'TICKET' | 'TOKEN' | 'PUBLIC'
82
+
83
+ export interface ZboxIngressPort {
84
+ port: number
85
+ access: ZboxPortAccess
86
+ wakeOnRequest: boolean
87
+ }
88
+
89
+ /** No `env`: a credential reaches a sandbox only in the root-only file a deploy writes through the file API. */
90
+ export interface ZboxLaunch {
91
+ entrypoint?: string[]
92
+ cmd?: string[]
93
+ workingDir?: string
94
+ }
95
+
96
+ export interface ZboxCreateSandboxInput {
97
+ name: string
98
+ baseDigest: string
99
+ cpus: number
100
+ memoryBytes: number
101
+ /** Box refuses a create whose disk does not fit the workspace's data volume, and its default can exceed a small one. */
102
+ diskBytes: number
103
+ networkMode: ZboxNetworkMode
104
+ launch: ZboxLaunch
105
+ ports: ZboxIngressPort[]
106
+ /** Reused on a retry so Box answers the first create instead of making a second sandbox. */
107
+ idempotencyKey: string
108
+ }
109
+
110
+ /** No `env`, for the same reason as `ZboxLaunch`. */
111
+ export interface ZboxExecInput {
112
+ command: string[]
113
+ workingDir?: string
114
+ timeoutSeconds?: number
115
+ }
116
+
117
+ export interface ZboxProcessInput {
118
+ command: string[]
119
+ workingDir?: string
120
+ }
121
+
122
+ export type ZboxBody = Uint8Array<ArrayBuffer> | ReadableStream<Uint8Array>
123
+
124
+ export type ZboxFetch = (
125
+ input: string,
126
+ init: { method: string; headers: Record<string, string>; body?: string | ZboxBody; signal: AbortSignal },
127
+ ) => Promise<Response>
128
+
129
+ export interface ZboxClientOptions {
130
+ /** The API origin; requests go to `<baseUrl>/api/rest/…`. */
131
+ baseUrl: string
132
+ /** The Workspace API key, sent as `Authorization: Bearer`. Never logged. */
133
+ apiKey: string
134
+ fetch?: ZboxFetch
135
+ /** Generates the `Idempotency-Key` of a call whose caller supplied none. */
136
+ idempotencyKey?: () => string
137
+ }
138
+
139
+ export interface ZboxAwaitOptions {
140
+ signal?: AbortSignal
141
+ /** Milliseconds from now after which waiting gives up. */
142
+ deadlineMs: number
143
+ }
144
+
145
+ export interface ZboxClient {
146
+ getWorkspace(signal?: AbortSignal): Promise<ZboxWorkspace>
147
+ pullBase(input: { imageRef: string; name: string }, signal?: AbortSignal): Promise<ZboxOperation>
148
+ buildBase(input: { context: ZboxBody; name: string }, signal?: AbortSignal): Promise<ZboxOperation>
149
+ listBases(signal?: AbortSignal): Promise<ZboxBase[]>
150
+ getOperation(id: string, waitSeconds: number, signal?: AbortSignal): Promise<ZboxOperation>
151
+ awaitOperation(operation: ZboxOperation, options: ZboxAwaitOptions): Promise<ZboxOperation>
152
+ createSandbox(input: ZboxCreateSandboxInput, signal?: AbortSignal): Promise<{ operation: ZboxOperation; sandbox: ZboxSandbox }>
153
+ getSandbox(id: string, signal?: AbortSignal): Promise<ZboxSandbox>
154
+ findSandboxByName(name: string, signal?: AbortSignal): Promise<ZboxSandbox | null>
155
+ deleteSandbox(id: string, idempotencyKey: string, signal?: AbortSignal): Promise<void>
156
+ park(id: string, input: { memory: boolean }, signal?: AbortSignal): Promise<ZboxOperation>
157
+ wake(id: string, signal?: AbortSignal): Promise<ZboxOperation>
158
+ exec(id: string, input: ZboxExecInput, signal?: AbortSignal): Promise<ZboxExecResult>
159
+ startProcess(id: string, input: ZboxProcessInput, signal?: AbortSignal): Promise<ZboxSession>
160
+ getSession(id: string, signal?: AbortSignal): Promise<ZboxSession>
161
+ sessionOutput(id: string, signal?: AbortSignal): Promise<Uint8Array>
162
+ /** `mode` is the octal file mode (Box defaults to 0644). */
163
+ putFile(id: string, path: string, body: ZboxBody, options?: { mode?: string; signal?: AbortSignal }): Promise<void>
164
+ getFile(id: string, path: string, signal?: AbortSignal): Promise<Uint8Array | null>
165
+ }
@@ -6,7 +6,9 @@ export declare const isAppVersionNotFoundResponse: (value: unknown) => boolean;
6
6
  export declare class ZeropsApiError extends Error {
7
7
  readonly status: number;
8
8
  readonly code: string;
9
- constructor(message: string, status: number, code: string);
9
+ /** The codes of an `errorList` answer's entries: the platform reports several refusals of one request there. */
10
+ readonly listedCodes: readonly string[];
11
+ constructor(message: string, status: number, code: string, listedCodes?: readonly string[]);
10
12
  }
11
13
  /**
12
14
  * The platform's code for "this service publishes no HTTP port", the answer `enableSubdomainAccess` gives
@@ -6,8 +6,11 @@ import { type ZeropsNamespaceProxySource } from './namespace';
6
6
  import { type OlderProxyReaders } from './namespace/proxy-reads';
7
7
  import type { ZeropsSourcePort } from './source/port';
8
8
  import type { ZeropsRunState } from './types';
9
+ import { type ZboxFetch } from './zbox';
9
10
  /** Provider coordinates that are safe to persist. Credentials are composed only for a live run. */
10
- export interface ZeropsStoredTarget {
11
+ export type ZeropsStoredTarget = ZeropsServiceTarget | ZeropsDevSandboxesTarget;
12
+ /** An environment served by its own Zerops service. */
13
+ export interface ZeropsServiceTarget {
11
14
  serviceId: string;
12
15
  /**
13
16
  * The object-storage service ids the first registration's collision-refusing import created: the creation evidence
@@ -15,6 +18,10 @@ export interface ZeropsStoredTarget {
15
18
  */
16
19
  createdBuckets?: string[];
17
20
  }
21
+ /** A `dev` environment: it has no service, and each MCP workspace runs in a sandbox of the namespace's sandbox host. */
22
+ export interface ZeropsDevSandboxesTarget {
23
+ kind: 'devSandboxes';
24
+ }
18
25
  export declare const zeropsStoredTargetCodec: ProviderCodec<ZeropsStoredTarget>;
19
26
  export interface ZeropsControlProviderOptions {
20
27
  readonly accessToken: string;
@@ -33,6 +40,10 @@ export interface ZeropsControlProviderOptions {
33
40
  /** The manifest parsers of the older releases' proxies, which a namespace pinned to an older source may run. */
34
41
  readonly olderProxies: OlderProxyReaders;
35
42
  };
43
+ /** The transport of the sandbox host API; tests pass a fake. */
44
+ readonly zboxFetch?: ZboxFetch;
45
+ /** Where a provider event outside a run is reported (a dev sandbox replaced); the process's stderr by default. */
46
+ readonly log?: (line: string) => void;
36
47
  }
37
48
  /** The run checkpoint (ADR-0044), or null for anything else — an older shape included. */
38
49
  export declare const parseZeropsCheckpoint: (value: unknown) => ZeropsRunState | null;
@@ -1,4 +1,4 @@
1
- import { type ContractArtifact, type DevLauncherConfig } from '@fabrika/auth-core';
1
+ import { type ContractArtifact } from '@fabrika/auth-core';
2
2
  import type { OperationsAssetRoot, OperationsSourceMapBuildUpload } from '@fabrika/operations-contract/releases';
3
3
  import type { JsonValue } from '@fabrika/provider-contract';
4
4
  import { type PreparedZeropsDescriptor } from './descriptor';
@@ -67,15 +67,6 @@ export interface ZeropsLockedExecution {
67
67
  readonly runtimePackages: readonly ZeropsRuntimePackage[];
68
68
  /** Where the build uploads its source maps, without the bearer; null when Control minted no upload for the run. */
69
69
  readonly sourceMaps: OperationsSourceMapBuildUpload | null;
70
- /**
71
- * Present for an environment of kind `dev` (ADR-0049): `run.start` runs the dev launcher instead of the serving
72
- * entry. The environment's kind selects it; an application never authors it.
73
- */
74
- readonly dev?: ZeropsDevExecution;
75
- }
76
- export interface ZeropsDevExecution {
77
- /** The commit the bootstrap run builds: what a new container holds before the launcher's first sync. */
78
- readonly head: string;
79
70
  }
80
71
  /** The application ids the generated scripts may name: the contract's own id rule, so a script needs no quoting. */
81
72
  export { CONTRACT_APP_ID_PATTERN as LOCKED_APP_ID_PATTERN } from '@fabrika/app/build';
@@ -106,10 +97,8 @@ interface AuthoredBuild {
106
97
  export declare function lockedAuthoredBuild(entry: {
107
98
  readonly [key: string]: JsonValue;
108
99
  }, setup: string): AuthoredBuild;
109
- /** What the dev launcher reads (`DEV_LAUNCHER_CONFIG_FILE`): the platform's, written after the checks. */
110
- export declare function devLauncherConfig(execution: ZeropsLockedExecution, authoredSpa: readonly string[]): DevLauncherConfig;
111
100
  /** The generated build commands, in order; the authored SPA commands run before all of them. */
112
- export declare function generatedBuildCommands(execution: ZeropsLockedExecution, authoredSpa?: readonly string[]): readonly string[];
101
+ export declare function generatedBuildCommands(execution: ZeropsLockedExecution): readonly string[];
113
102
  /** How many job processes the crontab may run at once, each opening the application's database. */
114
103
  export declare const zeropsJobProcesses: (execution: ZeropsLockedExecution) => number;
115
104
  /** The commands every container runs before `run.start`, in order; any failure stops the activation. */