@fabrika/provider-zerops 0.9.0-dev.8 → 0.9.0-dev.9

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 (68) 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 +24 -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 +236 -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 +21 -7
  31. package/src/sandbox/base-image.ts +100 -0
  32. package/src/sandbox/constants.ts +43 -0
  33. package/src/sandbox/deploy.ts +471 -0
  34. package/src/sandbox/dev-artifact.ts +206 -0
  35. package/src/sandbox/lifecycle.ts +200 -0
  36. package/src/sandbox/scripts.ts +26 -0
  37. package/src/sandbox-host.ts +31 -0
  38. package/src/source/port.ts +5 -0
  39. package/src/zbox/client.ts +267 -0
  40. package/src/zbox/errors.ts +45 -0
  41. package/src/zbox/index.ts +23 -0
  42. package/src/zbox/types.ts +168 -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/topology.d.ts +1 -1
  47. package/types/src/manifest.d.ts +3 -8
  48. package/types/src/namespace/codec.d.ts +18 -0
  49. package/types/src/namespace/errors.d.ts +12 -0
  50. package/types/src/namespace/proxy-reads.d.ts +6 -1
  51. package/types/src/namespace/proxy-secrets.d.ts +1 -1
  52. package/types/src/namespace/sandbox-host.d.ts +23 -0
  53. package/types/src/namespace/subdomain.d.ts +43 -0
  54. package/types/src/namespace/types.d.ts +10 -0
  55. package/types/src/provider.d.ts +0 -3
  56. package/types/src/proxy-manifest-carrier.d.ts +8 -1
  57. package/types/src/sandbox/base-image.d.ts +28 -0
  58. package/types/src/sandbox/constants.d.ts +29 -0
  59. package/types/src/sandbox/deploy.d.ts +75 -0
  60. package/types/src/sandbox/dev-artifact.d.ts +51 -0
  61. package/types/src/sandbox/lifecycle.d.ts +27 -0
  62. package/types/src/sandbox/scripts.d.ts +11 -0
  63. package/types/src/sandbox-host.d.ts +18 -0
  64. package/types/src/source/port.d.ts +5 -0
  65. package/types/src/zbox/client.d.ts +2 -0
  66. package/types/src/zbox/errors.d.ts +25 -0
  67. package/types/src/zbox/index.d.ts +3 -0
  68. package/types/src/zbox/types.d.ts +462 -0
@@ -0,0 +1,267 @@
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
+ putDomains: (domains, signal) =>
150
+ call(
151
+ 'put workspace domains',
152
+ 'PUT',
153
+ '/workspace/domains',
154
+ { json: { domains: domains.map(({ domain, form }) => ({ domain, form })) }, signal },
155
+ json('put workspace domains', zboxWorkspaceSchema),
156
+ ),
157
+
158
+ pullBase: ({ imageRef, name }, signal) =>
159
+ call(
160
+ 'pull base',
161
+ 'POST',
162
+ '/base',
163
+ { json: { imageRef, name }, idempotencyKey: nextIdempotencyKey(), signal },
164
+ json('pull base', zboxOperationSchema),
165
+ ),
166
+
167
+ buildBase: ({ context, name }, signal) =>
168
+ call('build base', 'POST', `/base-build?name=${encodeURIComponent(name)}`, { body: context, signal }, json('build base', zboxOperationSchema)),
169
+
170
+ listBases: async (signal) => (await call('list bases', 'GET', '/base-list', { signal }, json('list bases', zboxBaseListSchema))).items,
171
+
172
+ getOperation,
173
+
174
+ awaitOperation,
175
+
176
+ createSandbox: async (input, signal) => {
177
+ const spawn = await call(
178
+ 'create sandbox',
179
+ 'POST',
180
+ '/sandbox',
181
+ {
182
+ json: {
183
+ name: input.name,
184
+ baseDigest: input.baseDigest,
185
+ cpus: input.cpus,
186
+ memoryBytes: input.memoryBytes,
187
+ networkMode: input.networkMode,
188
+ integrations: [],
189
+ launch: { entrypoint: input.launch.entrypoint, cmd: input.launch.cmd, workingDir: input.launch.workingDir },
190
+ policy: {
191
+ ingress: {
192
+ ports: input.ports.map(({ port, access, wakeOnRequest }) => ({ port, access, protocol: 'HTTP', wakeOnRequest })),
193
+ },
194
+ secrets: { mode: 'NONE' },
195
+ },
196
+ waitSeconds: MAX_WAIT_SECONDS,
197
+ },
198
+ idempotencyKey: input.idempotencyKey,
199
+ signal,
200
+ },
201
+ json('create sandbox', zboxSpawnSchema),
202
+ )
203
+ const [created, ...others] = spawn.sandboxes
204
+ if (created === undefined || others.length > 0) {
205
+ throw new ZboxApiError('create sandbox', 200, 'unreadable')
206
+ }
207
+ const operation = await awaitOperation(spawn.operation, { signal, deadlineMs: OPERATION_DEADLINE_MS })
208
+ // A create answered before it finished carries the CREATING row; read the final one.
209
+ const sandbox = spawn.operation.status === 'FINISHED' ? created : await getSandbox(created.id, signal)
210
+ return { operation, sandbox }
211
+ },
212
+
213
+ getSandbox,
214
+
215
+ findSandboxByName: async (name, signal) => {
216
+ const list = await call('list sandboxes', 'GET', '/sandbox-list', { signal }, json('list sandboxes', zboxSandboxListSchema))
217
+ // Box refuses a create whose name a live sandbox holds, so at most one live sandbox matches.
218
+ return list.items.find((sandbox) => sandbox.name === name) ?? null
219
+ },
220
+
221
+ deleteSandbox: async (id, idempotencyKey, signal) => {
222
+ let started: ZboxOperation
223
+ try {
224
+ started = await call('delete sandbox', 'DELETE', sandboxPath(id), { idempotencyKey, signal }, json('delete sandbox', zboxOperationSchema))
225
+ } catch (error) {
226
+ if (isZboxNotFound(error) && error.code === 'sandboxNotFound') return
227
+ throw error
228
+ }
229
+ await awaitOperation(started, { signal, deadlineMs: OPERATION_DEADLINE_MS })
230
+ },
231
+
232
+ park: (id, { memory }, signal) => sandboxOperation('park sandbox', id, '/park', { memory }, signal),
233
+
234
+ wake: (id, signal) => sandboxOperation('wake sandbox', id, '/wake', {}, signal),
235
+
236
+ exec: (id, { command, workingDir, timeoutSeconds }, signal) =>
237
+ call('exec', 'POST', sandboxPath(id, '/exec'), { json: { command, workingDir, timeoutSeconds }, signal }, json('exec', zboxExecResultSchema)),
238
+
239
+ startProcess: (id, { command, workingDir }, signal) =>
240
+ call('start process', 'POST', sandboxPath(id, '/process'), { json: { command, workingDir }, signal }, json('start process', zboxSessionSchema)),
241
+
242
+ getSession: (id, signal) => call('get session', 'GET', `/session/${encodeURIComponent(id)}`, { signal }, json('get session', zboxSessionSchema)),
243
+
244
+ sessionOutput: (id, signal) => call('get session output', 'GET', `/session/${encodeURIComponent(id)}/output`, { signal }, bytes),
245
+
246
+ putFile: async (id, path, body, putOptions) => {
247
+ const mode = putOptions?.mode === undefined ? '' : `&mode=${encodeURIComponent(putOptions.mode)}`
248
+ await call(
249
+ 'put file',
250
+ 'PUT',
251
+ sandboxPath(id, `/file?path=${encodeURIComponent(path)}${mode}`),
252
+ { body, signal: putOptions?.signal },
253
+ json('put file', zboxSuccessSchema),
254
+ )
255
+ },
256
+
257
+ getFile: async (id, path, signal) => {
258
+ try {
259
+ return await call('get file', 'GET', sandboxPath(id, `/file?path=${encodeURIComponent(path)}`), { signal }, bytes)
260
+ } catch (error) {
261
+ // Only a missing PATH is an absent file; a missing sandbox stays an error.
262
+ if (isZboxNotFound(error) && error.code === 'pathNotFound') return null
263
+ throw error
264
+ }
265
+ },
266
+ }
267
+ }
@@ -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: Box echoes request env and launch env in its bodies.
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,23 @@
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
+ ZboxDomain,
11
+ ZboxExecInput,
12
+ ZboxExecResult,
13
+ ZboxFetch,
14
+ ZboxIngressPort,
15
+ ZboxLaunch,
16
+ ZboxNetworkMode,
17
+ ZboxOperation,
18
+ ZboxPortAccess,
19
+ ZboxProcessInput,
20
+ ZboxSandbox,
21
+ ZboxSession,
22
+ ZboxWorkspace,
23
+ } from './types'
@@ -0,0 +1,168 @@
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
+ const zboxDomainSchema = z.object({ domain: z.string().min(1), form: z.enum(['DASH', 'DOT']) })
40
+ export type ZboxDomain = z.infer<typeof zboxDomainSchema>
41
+
42
+ export const zboxWorkspaceSchema = z.object({ version: z.string(), domains: z.array(zboxDomainSchema) })
43
+ export type ZboxWorkspace = z.infer<typeof zboxWorkspaceSchema>
44
+
45
+ export const zboxBaseSchema = z.object({
46
+ digest: z.string().min(1),
47
+ name: nullableString,
48
+ imageRef: z.string(),
49
+ status: z.enum(['PULLING', 'FLATTENING', 'READY', 'FAILED', 'DELETED']),
50
+ })
51
+ export type ZboxBase = z.infer<typeof zboxBaseSchema>
52
+
53
+ export const zboxBaseListSchema = z.object({ items: z.array(zboxBaseSchema) })
54
+
55
+ export const zboxExecResultSchema = z.object({
56
+ stdout: z.string(),
57
+ stderr: z.string(),
58
+ exitCode: z
59
+ .number()
60
+ .int()
61
+ .nullish()
62
+ .transform((value) => value ?? null),
63
+ timedOut: z.boolean(),
64
+ stdoutTruncated: z.boolean(),
65
+ stderrTruncated: z.boolean(),
66
+ })
67
+ export type ZboxExecResult = z.infer<typeof zboxExecResultSchema>
68
+
69
+ // The session's `command` echoes the env it ran with, so it is never read.
70
+ export const zboxSessionSchema = z.object({
71
+ id: z.string().min(1),
72
+ status: z.enum(['OPEN', 'CLOSED', 'FAILED']),
73
+ exitCode: z
74
+ .number()
75
+ .int()
76
+ .nullish()
77
+ .transform((value) => value ?? null),
78
+ hasOutput: z.boolean(),
79
+ })
80
+ export type ZboxSession = z.infer<typeof zboxSessionSchema>
81
+
82
+ export const zboxSuccessSchema = z.object({ success: z.literal(true) })
83
+
84
+ export type ZboxNetworkMode = 'AIRGAPPED' | 'PROJECT' | 'INTERNET' | 'PROJECT_INTERNET'
85
+ export type ZboxPortAccess = 'PROJECT' | 'MEMBERS' | 'TICKET' | 'TOKEN' | 'PUBLIC'
86
+
87
+ export interface ZboxIngressPort {
88
+ port: number
89
+ access: ZboxPortAccess
90
+ wakeOnRequest: boolean
91
+ }
92
+
93
+ /** No `env`: Box echoes launch env in its answers, so credentials reach a sandbox only through the file API. */
94
+ export interface ZboxLaunch {
95
+ entrypoint?: string[]
96
+ cmd?: string[]
97
+ workingDir?: string
98
+ }
99
+
100
+ export interface ZboxCreateSandboxInput {
101
+ name: string
102
+ baseDigest: string
103
+ cpus: number
104
+ memoryBytes: number
105
+ networkMode: ZboxNetworkMode
106
+ launch: ZboxLaunch
107
+ ports: ZboxIngressPort[]
108
+ /** Reused on a retry so Box answers the first create instead of making a second sandbox. */
109
+ idempotencyKey: string
110
+ }
111
+
112
+ /** No `env`, for the same reason as `ZboxLaunch`. */
113
+ export interface ZboxExecInput {
114
+ command: string[]
115
+ workingDir?: string
116
+ timeoutSeconds?: number
117
+ }
118
+
119
+ export interface ZboxProcessInput {
120
+ command: string[]
121
+ workingDir?: string
122
+ }
123
+
124
+ export type ZboxBody = Uint8Array<ArrayBuffer> | ReadableStream<Uint8Array>
125
+
126
+ export type ZboxFetch = (
127
+ input: string,
128
+ init: { method: string; headers: Record<string, string>; body?: string | ZboxBody; signal: AbortSignal },
129
+ ) => Promise<Response>
130
+
131
+ export interface ZboxClientOptions {
132
+ /** The API origin; requests go to `<baseUrl>/api/rest/…`. */
133
+ baseUrl: string
134
+ /** The Workspace API key, sent as `Authorization: Bearer`. Never logged. */
135
+ apiKey: string
136
+ fetch?: ZboxFetch
137
+ /** Generates the `Idempotency-Key` of a call whose caller supplied none. */
138
+ idempotencyKey?: () => string
139
+ }
140
+
141
+ export interface ZboxAwaitOptions {
142
+ signal?: AbortSignal
143
+ /** Milliseconds from now after which waiting gives up. */
144
+ deadlineMs: number
145
+ }
146
+
147
+ export interface ZboxClient {
148
+ getWorkspace(signal?: AbortSignal): Promise<ZboxWorkspace>
149
+ putDomains(domains: ZboxDomain[], signal?: AbortSignal): Promise<ZboxWorkspace>
150
+ pullBase(input: { imageRef: string; name: string }, signal?: AbortSignal): Promise<ZboxOperation>
151
+ buildBase(input: { context: ZboxBody; name: string }, signal?: AbortSignal): Promise<ZboxOperation>
152
+ listBases(signal?: AbortSignal): Promise<ZboxBase[]>
153
+ getOperation(id: string, waitSeconds: number, signal?: AbortSignal): Promise<ZboxOperation>
154
+ awaitOperation(operation: ZboxOperation, options: ZboxAwaitOptions): Promise<ZboxOperation>
155
+ createSandbox(input: ZboxCreateSandboxInput, signal?: AbortSignal): Promise<{ operation: ZboxOperation; sandbox: ZboxSandbox }>
156
+ getSandbox(id: string, signal?: AbortSignal): Promise<ZboxSandbox>
157
+ findSandboxByName(name: string, signal?: AbortSignal): Promise<ZboxSandbox | null>
158
+ deleteSandbox(id: string, idempotencyKey: string, signal?: AbortSignal): Promise<void>
159
+ park(id: string, input: { memory: boolean }, signal?: AbortSignal): Promise<ZboxOperation>
160
+ wake(id: string, signal?: AbortSignal): Promise<ZboxOperation>
161
+ exec(id: string, input: ZboxExecInput, signal?: AbortSignal): Promise<ZboxExecResult>
162
+ startProcess(id: string, input: ZboxProcessInput, signal?: AbortSignal): Promise<ZboxSession>
163
+ getSession(id: string, signal?: AbortSignal): Promise<ZboxSession>
164
+ sessionOutput(id: string, signal?: AbortSignal): Promise<Uint8Array>
165
+ /** `mode` is the octal file mode (Box defaults to 0644). */
166
+ putFile(id: string, path: string, body: ZboxBody, options?: { mode?: string; signal?: AbortSignal }): Promise<void>
167
+ getFile(id: string, path: string, signal?: AbortSignal): Promise<Uint8Array | null>
168
+ }
@@ -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. */
@@ -12,7 +12,7 @@ import { type ZeropsImportDocument, type ZeropsNamespacePostgres, type ZeropsSou
12
12
  * `enableSubdomainAccess` on a service the document CREATES and then silently drops it, so the service
13
13
  * reads back `subdomainAccess: false` and stays there. The subdomain is established afterwards, by
14
14
  * `PUT /service-stack/{id}/enable-subdomain-access` on a service that already publishes an HTTP port —
15
- * which the namespace lifecycle does for itself (`ensureSubdomainAccess` in `src/namespace/provisioning.ts`)
15
+ * which the namespace lifecycle does for itself (`ensureSubdomainAccess` in `src/namespace/subdomain.ts`)
16
16
  * and which an operator applying the generated platform artifacts must do by hand; the artifact's header
17
17
  * names the call. So `true` here records the INTENT and feeds ADR-0022's `assertOnlyPublicService`; it
18
18
  * does not turn anything on.
@@ -1,7 +1,7 @@
1
1
  import { type AppSchema } from '@fabrika/auth-core';
2
2
  import type { JsonValue, ProviderCodec, ProviderDeployInput, ProviderEnvironment } from '@fabrika/provider-contract';
3
3
  import { z } from 'zod';
4
- import { type ZeropsContractRun, type ZeropsDevExecution, type ZeropsLockedExecution, type ZeropsRuntimePackage } from './execution';
4
+ import { type ZeropsContractRun, type ZeropsLockedExecution, type ZeropsRuntimePackage } from './execution';
5
5
  import type { ZeropsAppConfig, ZeropsNamespaceResourceRequirement, ZeropsProxySpec } from './types';
6
6
  export declare const FABRIKA_MANIFEST_VERSION = 3;
7
7
  export declare const ZEROPS_SOURCE_DESCRIPTOR_MAX_BYTES: number;
@@ -179,13 +179,8 @@ export declare const applicationDatabaseOf: (manifest: FabrikaManifest) => Appli
179
179
  * The manifest is the one this release's `fabrika app build` wrote, so its build checks with this release.
180
180
  */
181
181
  export declare const lockedExecutionOf: (manifest: FabrikaManifest) => ZeropsLockedExecution | null;
182
- /**
183
- * What Control lets a provider publish for one environment (`ProviderEnvironment.access`), and, for an environment of
184
- * kind `dev`, the commit its bootstrap builds.
185
- */
186
- export type ZeropsAccess = Pick<ProviderEnvironment, 'access'> & {
187
- readonly dev?: ZeropsDevExecution;
188
- };
182
+ /** What Control lets a provider publish for one environment (`ProviderEnvironment.access`). */
183
+ export type ZeropsAccess = Pick<ProviderEnvironment, 'access'>;
189
184
  /**
190
185
  * The execution descriptor's lock-down at deploy (ADR-0050): Control's approved contract decides it, not the artifact,
191
186
  * so a configuration cannot drop it. Without an approved contract nothing deploys outside a dry run.
@@ -134,6 +134,16 @@ export declare const namespaceUpdatePayloadSchema: z.ZodObject<{
134
134
  port: number;
135
135
  host: string;
136
136
  }>, "many">>>;
137
+ sandboxHost: z.ZodOptional<z.ZodOptional<z.ZodObject<{
138
+ serviceId: z.ZodString;
139
+ apiOrigin: z.ZodEffects<z.ZodString, string, string>;
140
+ }, "strict", z.ZodTypeAny, {
141
+ serviceId: string;
142
+ apiOrigin: string;
143
+ }, {
144
+ serviceId: string;
145
+ apiOrigin: string;
146
+ }>>>;
137
147
  ready: z.ZodOptional<z.ZodOptional<z.ZodBoolean>>;
138
148
  } & {
139
149
  postgres: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
@@ -274,6 +284,10 @@ export declare const namespaceUpdatePayloadSchema: z.ZodObject<{
274
284
  port: number;
275
285
  host: string;
276
286
  }[] | undefined;
287
+ sandboxHost?: {
288
+ serviceId: string;
289
+ apiOrigin: string;
290
+ } | undefined;
277
291
  ready?: boolean | undefined;
278
292
  }, {
279
293
  corePackage?: "LIGHT" | "SERIOUS" | undefined;
@@ -324,6 +338,10 @@ export declare const namespaceUpdatePayloadSchema: z.ZodObject<{
324
338
  port: number;
325
339
  host: string;
326
340
  }[] | undefined;
341
+ sandboxHost?: {
342
+ serviceId: string;
343
+ apiOrigin: string;
344
+ } | undefined;
327
345
  ready?: boolean | undefined;
328
346
  }>;
329
347
  export declare const zeropsNamespaceTargetCodec: ProviderCodec<ZeropsNamespaceTarget>;