@fabrika/provider-zerops 0.9.0-dev.7 → 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,43 @@
1
+ // The paths a dev workspace sandbox's base image and its deploy agree on. The base image's scripts
2
+ // (`packages/provider-zerops/sandbox/`) spell the same paths; a change here changes them there too.
3
+
4
+ /** The application root inside a sandbox: what a deploy extracts the source into and the launcher runs from. */
5
+ export const SANDBOX_APP_ROOT = '/app'
6
+
7
+ /** State that survives a re-bootstrap, which replaces only the application root. */
8
+ export const SANDBOX_STATE_DIR = '/var/lib/fabrika'
9
+
10
+ /** The launcher's environment, written 0600 through the file API: the one way a credential reaches a sandbox process. */
11
+ export const SANDBOX_ENV_FILE = `${SANDBOX_STATE_DIR}/env`
12
+
13
+ /** The generated build script; it holds no credential, and the build reads none. */
14
+ export const SANDBOX_BUILD_SCRIPT = `${SANDBOX_STATE_DIR}/build.sh`
15
+
16
+ /** Where the source archive lands before it is extracted. */
17
+ export const SANDBOX_SOURCE_ARCHIVE = '/tmp/fabrika-source.tar.gz'
18
+
19
+ /** The base image's PID 1: PostgreSQL, then the launcher when a deploy left one. Every other script is uploaded. */
20
+ export const SANDBOX_INIT_COMMAND: readonly string[] = ['/bin/sh', '/usr/local/lib/fabrika/init.sh']
21
+
22
+ /** Where each deploy uploads the helper scripts, one directory per version; `current` names the one in use. */
23
+ export const SANDBOX_BIN_DIR = `${SANDBOX_STATE_DIR}/bin`
24
+ export const SANDBOX_BIN_POINTER = `${SANDBOX_BIN_DIR}/current`
25
+
26
+ /** The launcher's output, which only root reads. */
27
+ export const SANDBOX_LAUNCHER_LOG = `${SANDBOX_STATE_DIR}/launcher.log`
28
+
29
+ /**
30
+ * The database the launcher provisions with: the sandbox's local superuser. The deploy writes it without a password;
31
+ * `run-launcher.sh` adds the password, which stays in the sandbox in a file only root reads.
32
+ */
33
+ export const SANDBOX_DATABASE_URL = 'postgres://postgres@127.0.0.1:5432/postgres'
34
+
35
+ /** The local superuser's password, which `postgres-auth.sh` generates and `run-launcher.sh` adds to that URL. */
36
+ export const SANDBOX_DATABASE_PASSWORD_FILE = `${SANDBOX_STATE_DIR}/postgres-password`
37
+
38
+ /** The connections each process opens: one launcher, one application and a migration share a local PostgreSQL of 100. */
39
+ export const SANDBOX_DATABASE_CONNECTIONS = 10
40
+
41
+ /** The size of one workspace sandbox. */
42
+ export const SANDBOX_CPUS = 2
43
+ export const SANDBOX_MEMORY_BYTES = 2 * 1024 * 1024 * 1024
@@ -0,0 +1,471 @@
1
+ // The deploy of a `dev` environment into one workspace's sandbox (ADR-0049): a plan of its own, separate from the Zerops
2
+ // build. The sandbox keeps its id for the workspace's life, so a re-bootstrap rebuilds inside it. Recovery never resumes
3
+ // (ADR-0044): a run whose invocation is lost settles failed, and the workspace binds again.
4
+
5
+ import { DEV_LAUNCHER_BOOTED_FILE } from '@fabrika/auth-core'
6
+ import {
7
+ type DeployStepResult,
8
+ isLeaseLoss,
9
+ type JsonValue,
10
+ type ProviderApprovedAccess,
11
+ ProviderInvocationAbort,
12
+ type ProviderManagedEnvironment,
13
+ type ProviderRunEvents,
14
+ runSteps,
15
+ } from '@fabrika/provider-contract'
16
+ import { z } from 'zod'
17
+ import type { Sleeper } from '../collaborators'
18
+ import { zeropsContractRun } from '../execution'
19
+ import type { FabrikaManifest } from '../manifest'
20
+ import type { ZeropsSourcePort, ZeropsSourcePrivateBinding } from '../source/port'
21
+ import type { ZeropsSourceRepository } from '../source/types'
22
+ import type { ZboxClient, ZboxExecResult } from '../zbox'
23
+ import {
24
+ SANDBOX_APP_ROOT,
25
+ SANDBOX_BIN_DIR,
26
+ SANDBOX_BIN_POINTER,
27
+ SANDBOX_BUILD_SCRIPT,
28
+ SANDBOX_DATABASE_PASSWORD_FILE,
29
+ SANDBOX_ENV_FILE,
30
+ SANDBOX_LAUNCHER_LOG,
31
+ SANDBOX_SOURCE_ARCHIVE,
32
+ } from './constants'
33
+ import {
34
+ assertNoSandboxReferences,
35
+ assertSandboxArtifact,
36
+ authoredSpaCommands,
37
+ maskValues,
38
+ renderSandboxBuildScript,
39
+ renderSandboxEnvFile,
40
+ SANDBOX_LAUNCHER_CONFIG_PATH,
41
+ sandboxBuildStepLabels,
42
+ sandboxEnvironment,
43
+ sandboxLauncherConfig,
44
+ sandboxRecipe,
45
+ } from './dev-artifact'
46
+ import { runningSandbox } from './lifecycle'
47
+ import { readSandboxScripts, SANDBOX_SCRIPT_FILES, type SandboxScripts } from './scripts'
48
+
49
+ /** How long the build may run: the recipe's install, tests, `tsc` and checker; measured ≈8 s warm. */
50
+ const BUILD_DEADLINE_MS = 30 * 60_000
51
+ const BUILD_POLL_MS = 1_000
52
+
53
+ /** How long the launcher has to report its boot: the readiness window of a Zerops dev container. */
54
+ export const SANDBOX_BOOT_DEADLINE_MS = 180_000
55
+ const BOOT_POLL_MS = 2_000
56
+
57
+ /** Box cuts an exec off at 60 s. */
58
+ const EXEC_TIMEOUT_SECONDS = 55
59
+
60
+ const BOOTED_PATH = `${SANDBOX_APP_ROOT}/${DEV_LAUNCHER_BOOTED_FILE}`
61
+
62
+ /** The run checkpoint of a sandbox deploy: credential-free coordinates, read back only to settle the run failed. */
63
+ export interface ZeropsSandboxRunState {
64
+ readonly sandboxId: string
65
+ readonly runId: string
66
+ readonly buildSessionId?: string
67
+ }
68
+
69
+ const sandboxCheckpointSchema = z.object({
70
+ sandboxId: z.string().min(1),
71
+ runId: z.string().min(1),
72
+ buildSessionId: z.string().min(1).optional(),
73
+ }).strict()
74
+
75
+ export const sandboxExternalId = (state: Pick<ZeropsSandboxRunState, 'sandboxId' | 'runId'>): string => `sandbox:${state.sandboxId}:${state.runId}`
76
+
77
+ /** The sandbox checkpoint recorded for exactly this external id, or null. */
78
+ export function parseSandboxCheckpoint(input: { readonly providerState?: JsonValue; readonly externalId: string }): ZeropsSandboxRunState | null {
79
+ const parsed = sandboxCheckpointSchema.safeParse(input.providerState)
80
+ return parsed.success && sandboxExternalId(parsed.data) === input.externalId ? parsed.data : null
81
+ }
82
+
83
+ const encodeCheckpoint = (state: ZeropsSandboxRunState): JsonValue => ({
84
+ sandboxId: state.sandboxId,
85
+ runId: state.runId,
86
+ ...(state.buildSessionId === undefined ? {} : { buildSessionId: state.buildSessionId }),
87
+ })
88
+
89
+ export interface ZeropsSandboxDeployRun {
90
+ readonly appId: string
91
+ readonly env: string
92
+ readonly runId: string
93
+ readonly artifact: FabrikaManifest
94
+ readonly access: ProviderApprovedAccess | undefined
95
+ readonly vars: Readonly<Record<string, string>>
96
+ readonly secrets: Readonly<Record<string, string>>
97
+ readonly managedEnvironment: ProviderManagedEnvironment
98
+ /** Absent on a dry run, which resolves no source. */
99
+ readonly source?: {
100
+ readonly repository: ZeropsSourceRepository
101
+ readonly commitSha: string
102
+ readonly privateBinding?: ZeropsSourcePrivateBinding
103
+ }
104
+ readonly sandbox: {
105
+ readonly sandboxId: string
106
+ /** The sandbox host's API origin; the source upload goes to its file endpoint. */
107
+ readonly apiOrigin: string
108
+ /** A credential in transit: the bearer of the source upload. Never logged, persisted or put in an argument. */
109
+ readonly sandboxKey: string
110
+ }
111
+ readonly client: ZboxClient
112
+ readonly sourcePort: ZeropsSourcePort
113
+ readonly sleep: Sleeper
114
+ readonly dryRun: boolean
115
+ readonly signal: AbortSignal
116
+ readonly events: ProviderRunEvents
117
+ /** The helper scripts to upload; the ones this package ships unless a test passes others. */
118
+ readonly scripts?: SandboxScripts
119
+ }
120
+
121
+ export interface ZeropsSandboxDeployResult {
122
+ readonly status: 'succeeded' | 'failed'
123
+ readonly steps: readonly DeployStepResult[]
124
+ }
125
+
126
+ type SandboxStepId =
127
+ | 'wake-sandbox'
128
+ | 'install-scripts'
129
+ | 'stop-previous'
130
+ | 'upload-source'
131
+ | 'build'
132
+ | 'write-env'
133
+ | 'write-launcher-config'
134
+ | 'start-launcher'
135
+ | 'await-boot'
136
+
137
+ // The environment is written only after the build: the build runs the application's own code, which never sees it.
138
+ const SANDBOX_STEPS: readonly { readonly id: SandboxStepId; readonly description: string }[] = [
139
+ { id: 'wake-sandbox', description: "wake the workspace's sandbox" },
140
+ { id: 'install-scripts', description: 'upload the helper scripts of this release' },
141
+ { id: 'stop-previous', description: 'stop the previous launcher and build, delete the launcher environment, secure the database' },
142
+ { id: 'upload-source', description: 'upload the commit and swap it into the application root' },
143
+ { id: 'build', description: 'run the build and its checks as the unprivileged build user' },
144
+ { id: 'write-env', description: 'write the launcher environment (0600)' },
145
+ { id: 'write-launcher-config', description: 'write the dev launcher configuration' },
146
+ { id: 'start-launcher', description: 'start the dev launcher' },
147
+ { id: 'await-boot', description: 'wait for the launcher to report its boot' },
148
+ ]
149
+
150
+ /** A cancel stops the step; a lost lease stops it too, and leaves the sandbox to the next owner untouched. */
151
+ const assertRunning = (signal: AbortSignal): void => {
152
+ if (!signal.aborted) return
153
+ if (signal.reason instanceof ProviderInvocationAbort) throw signal.reason
154
+ throw new ProviderInvocationAbort('cancel_requested')
155
+ }
156
+
157
+ /** The source's file endpoint for one sandbox, written exactly as a URL parser writes it (Control compares). */
158
+ export const sandboxSourceUploadUrl = (apiOrigin: string, sandboxId: string): string =>
159
+ `${apiOrigin.replace(/\/+$/, '')}/api/rest/sandbox/${sandboxId}/file?path=${SANDBOX_SOURCE_ARCHIVE}`
160
+
161
+ /** Replaces the application root with the archive's tree; state outside it (PGDATA, the env file) is kept. */
162
+ const EXTRACT_SOURCE = [
163
+ '/bin/sh',
164
+ '-c',
165
+ `set -eu; rm -rf ${SANDBOX_APP_ROOT}.next ${SANDBOX_APP_ROOT}.prev; mkdir ${SANDBOX_APP_ROOT}.next; `
166
+ + `tar -xzf ${SANDBOX_SOURCE_ARCHIVE} -C ${SANDBOX_APP_ROOT}.next; rm -f ${SANDBOX_SOURCE_ARCHIVE}; `
167
+ + `if [ -e ${SANDBOX_APP_ROOT} ]; then mv ${SANDBOX_APP_ROOT} ${SANDBOX_APP_ROOT}.prev; fi; `
168
+ + `mv ${SANDBOX_APP_ROOT}.next ${SANDBOX_APP_ROOT}; rm -rf ${SANDBOX_APP_ROOT}.prev`,
169
+ ]
170
+
171
+ const lastLines = (text: string, count: number): string[] => text.split('\n').map((line) => line.trim()).filter((line) => line !== '').slice(-count)
172
+
173
+ /** One bounded command in the sandbox; a non-zero exit fails the step with the command's last lines. */
174
+ const execOrThrow = async (run: ZeropsSandboxDeployRun, what: string, command: readonly string[]): Promise<ZboxExecResult> => {
175
+ const result = await run.client.exec(run.sandbox.sandboxId, { command: [...command], timeoutSeconds: EXEC_TIMEOUT_SECONDS }, run.signal)
176
+ if (result.timedOut) throw new Error(`zerops: ${what} did not finish within ${EXEC_TIMEOUT_SECONDS} s`)
177
+ if (result.exitCode !== 0) {
178
+ const output = lastLines(`${result.stdout}\n${result.stderr}`, 3).join(' / ')
179
+ throw new Error(`zerops: ${what} failed with exit code ${result.exitCode ?? 'none'}${output === '' ? '' : `: ${output}`}`)
180
+ }
181
+ return result
182
+ }
183
+
184
+ /** Splits relayed bytes into whole lines, each masked; a trailing partial line waits for the next read. */
185
+ class LineRelay {
186
+ private readonly decoder = new TextDecoder()
187
+ private partial = ''
188
+ constructor(private readonly log: (line: string) => void, private readonly secrets: readonly string[]) {}
189
+
190
+ push(bytes: Uint8Array): void {
191
+ const lines = (this.partial + this.decoder.decode(bytes, { stream: true })).split('\n')
192
+ this.partial = lines.pop() ?? ''
193
+ for (const line of lines) this.emit(line.replace(/\r$/, ''))
194
+ }
195
+
196
+ flush(): void {
197
+ const rest = this.partial + this.decoder.decode()
198
+ this.partial = ''
199
+ if (rest !== '') this.emit(rest)
200
+ }
201
+
202
+ private emit(line: string): void {
203
+ this.log(` │ ${maskValues(line, this.secrets)}`)
204
+ }
205
+ }
206
+
207
+ /** The bytes last relayed that a new read must still hold at the same offset; a bounded check of a cumulative buffer. */
208
+ const RELAY_WINDOW_BYTES = 4096
209
+
210
+ const sameBytes = (left: Uint8Array, right: Uint8Array): boolean =>
211
+ left.byteLength === right.byteLength && left.every((byte, index) => byte === right[index])
212
+
213
+ /**
214
+ * Relays a session's cumulative output: only the bytes past what it relayed. A read that no longer holds the relayed
215
+ * bytes where they were (the host cut its buffer) is reported once per cut and relaying resumes at its end.
216
+ */
217
+ export class SessionOutputRelay {
218
+ private relayed = 0
219
+ private window: Uint8Array = new Uint8Array()
220
+ private readonly lines: LineRelay
221
+
222
+ constructor(private readonly log: (line: string) => void, secrets: readonly string[]) {
223
+ this.lines = new LineRelay(log, secrets)
224
+ }
225
+
226
+ /** How many bytes the session has produced, as far as this relay knows. */
227
+ get size(): number {
228
+ return this.relayed
229
+ }
230
+
231
+ accept(output: Uint8Array): void {
232
+ const held = output.byteLength >= this.relayed && sameBytes(output.subarray(this.relayed - this.window.byteLength, this.relayed), this.window)
233
+ if (held) {
234
+ this.lines.push(output.subarray(this.relayed))
235
+ } else {
236
+ this.lines.flush()
237
+ this.log(' [warn] build output was truncated by the sandbox host; relaying what follows')
238
+ }
239
+ this.relayed = output.byteLength
240
+ this.window = output.slice(Math.max(0, output.byteLength - RELAY_WINDOW_BYTES))
241
+ }
242
+
243
+ flush(): void {
244
+ this.lines.flush()
245
+ }
246
+ }
247
+
248
+ /** The output endpoint answers the whole buffer, so a large one is read less often. */
249
+ const buildPollMs = (outputBytes: number): number =>
250
+ outputBytes < 256 * 1024 ? BUILD_POLL_MS : outputBytes < 4 * 1024 * 1024 ? 3 * BUILD_POLL_MS : 10 * BUILD_POLL_MS
251
+
252
+ interface DeployContext {
253
+ readonly run: ZeropsSandboxDeployRun
254
+ readonly scripts: SandboxScripts
255
+ /** Every value a log line must not show: the environment's and the sandbox key. */
256
+ readonly secrets: readonly string[]
257
+ }
258
+
259
+ /** Best-effort: the run is already giving up, and a refused or slow stop must not replace the reason. */
260
+ const stopBuildQuietly = async ({ run, scripts }: DeployContext): Promise<void> => {
261
+ await run.client.exec(
262
+ run.sandbox.sandboxId,
263
+ { command: ['/bin/sh', scripts.path('stop.sh'), 'build'], timeoutSeconds: EXEC_TIMEOUT_SECONDS },
264
+ AbortSignal.timeout(30_000),
265
+ ).catch(() => undefined)
266
+ }
267
+
268
+ /**
269
+ * Runs the build as one detached process (an exec is cut off at 60 s) and relays its output into the run log. A cancel
270
+ * stops the build; a lost lease leaves it.
271
+ */
272
+ const runBuild = async (context: DeployContext, script: string, checkpoint: ZeropsSandboxRunState): Promise<void> => {
273
+ const { run, secrets } = context
274
+ const { client, signal, events } = run
275
+ const sandboxId = run.sandbox.sandboxId
276
+ await client.putFile(sandboxId, SANDBOX_BUILD_SCRIPT, new TextEncoder().encode(script), { mode: '0700', signal })
277
+ assertRunning(signal)
278
+ const session = await client.startProcess(sandboxId, { command: ['/bin/sh', SANDBOX_BUILD_SCRIPT], workingDir: SANDBOX_APP_ROOT }, signal)
279
+ await events.checkpoint(encodeCheckpoint({ ...checkpoint, buildSessionId: session.id }))
280
+ const relay = new SessionOutputRelay(events.log, secrets)
281
+ const deadline = Date.now() + BUILD_DEADLINE_MS
282
+ let relayFailed = false
283
+ const relayOutput = async (): Promise<void> => {
284
+ try {
285
+ relay.accept(await client.sessionOutput(session.id, signal))
286
+ } catch {
287
+ if (signal.aborted) return
288
+ if (!relayFailed) events.log(' [warn] the build output could not be read; the build continues')
289
+ relayFailed = true
290
+ }
291
+ }
292
+ try {
293
+ for (;;) {
294
+ const crossed: unknown = await events.boundary().then(() => null, (error: unknown) => error)
295
+ if (isLeaseLoss(crossed)) throw crossed
296
+ assertRunning(signal)
297
+ await relayOutput()
298
+ let state: Awaited<ReturnType<ZboxClient['getSession']>> | null = null
299
+ try {
300
+ state = await client.getSession(session.id, signal)
301
+ } catch {
302
+ assertRunning(signal)
303
+ events.log(' build status unavailable; retrying')
304
+ }
305
+ if (state !== null && state.status !== 'OPEN') {
306
+ await relayOutput()
307
+ relay.flush()
308
+ if (state.exitCode === 0) return
309
+ throw new Error(`zerops: the build failed with exit code ${state.exitCode ?? 'none'}`)
310
+ }
311
+ if (Date.now() > deadline) {
312
+ await stopBuildQuietly(context)
313
+ throw new Error(`zerops: the build did not finish within ${BUILD_DEADLINE_MS / 60_000} minutes; it was stopped`)
314
+ }
315
+ await run.sleep(buildPollMs(relay.size), signal)
316
+ }
317
+ } catch (error) {
318
+ if (signal.aborted && !isLeaseLoss(signal.reason)) await stopBuildQuietly(context)
319
+ throw error
320
+ }
321
+ }
322
+
323
+ const LAUNCHER_LOG_LINES = 10
324
+
325
+ const awaitBoot = async ({ run, secrets }: DeployContext): Promise<void> => {
326
+ const deadline = Date.now() + SANDBOX_BOOT_DEADLINE_MS
327
+ for (;;) {
328
+ assertRunning(run.signal)
329
+ if ((await run.client.getFile(run.sandbox.sandboxId, BOOTED_PATH, run.signal)) !== null) return
330
+ if (Date.now() > deadline) {
331
+ const logged = await run.client.getFile(run.sandbox.sandboxId, SANDBOX_LAUNCHER_LOG, run.signal).catch(() => null)
332
+ // The launcher's database URL carries a password Control never handed: masked too, or the tail is not shown.
333
+ const password = await run.client.getFile(run.sandbox.sandboxId, SANDBOX_DATABASE_PASSWORD_FILE, run.signal).then(
334
+ (bytes) => bytes === null ? '' : new TextDecoder().decode(bytes).trim(),
335
+ () => null,
336
+ )
337
+ const tail = logged === null || password === null
338
+ ? []
339
+ : lastLines(maskValues(new TextDecoder().decode(logged), [...secrets, password]), LAUNCHER_LOG_LINES)
340
+ throw new Error(
341
+ `zerops: the dev launcher did not report its boot within ${SANDBOX_BOOT_DEADLINE_MS / 1000} s${
342
+ tail.length === 0 ? '' : `; its log ends: ${tail.join(' | ')}`
343
+ }`,
344
+ )
345
+ }
346
+ await run.sleep(BOOT_POLL_MS, run.signal)
347
+ }
348
+ }
349
+
350
+ /** Uploads this release's helper scripts under their version, then points `current` at them. */
351
+ const installScripts = async ({ run, scripts }: DeployContext): Promise<void> => {
352
+ const sandboxId = run.sandbox.sandboxId
353
+ const directory = `${SANDBOX_BIN_DIR}/${scripts.version}`
354
+ await execOrThrow(run, 'creating the script directory', [
355
+ '/bin/sh',
356
+ '-c',
357
+ `set -eu; mkdir -p ${directory}; chmod 700 ${SANDBOX_BIN_DIR} ${directory}`,
358
+ ])
359
+ for (const name of SANDBOX_SCRIPT_FILES) {
360
+ const content = scripts.files[name]
361
+ if (content === undefined) throw new Error(`zerops: the sandbox script ${name} is missing from this package`)
362
+ await run.client.putFile(sandboxId, scripts.path(name), new Uint8Array(content), { mode: '0700', signal: run.signal })
363
+ }
364
+ // Last, so a cold boot never starts a half-uploaded version.
365
+ await run.client.putFile(sandboxId, SANDBOX_BIN_POINTER, new TextEncoder().encode(`${scripts.version}\n`), { mode: '0600', signal: run.signal })
366
+ }
367
+
368
+ /** Deploy one workspace's sandbox. Refusals throw before any step; a step failure fails the run. */
369
+ export async function deploySandbox(run: ZeropsSandboxDeployRun): Promise<ZeropsSandboxDeployResult> {
370
+ const { artifact, access, events, signal, dryRun } = run
371
+ if (artifact.app.id !== run.appId || artifact.app.env !== run.env) throw new Error('zerops: the artifact names another environment')
372
+ if (access === undefined && !dryRun) throw new Error('zerops: Control approved no access for this environment')
373
+ const contract = access === undefined ? artifact.target.contract : zeropsContractRun(access.contract, access.contractDigest)
374
+ if (contract === undefined) throw new Error('zerops: a dev environment runs a contract application')
375
+ assertSandboxArtifact(artifact, contract)
376
+ assertNoSandboxReferences('variable', run.vars)
377
+ const environment = sandboxEnvironment({
378
+ artifact,
379
+ secrets: run.secrets,
380
+ managed: run.managedEnvironment,
381
+ contractDigest: access?.contractDigest ?? contract.digest,
382
+ })
383
+ const spa = authoredSpaCommands(artifact)
384
+ const recipeInput = access === undefined ? null : { appId: artifact.app.id, checkRelease: access.checker, contract }
385
+ const recipe = recipeInput === null ? null : sandboxRecipe(recipeInput)
386
+ const sandboxId = run.sandbox.sandboxId
387
+ // It is written into the upload URL unescaped, as Control's destination check reads it.
388
+ if (!/^[a-z0-9]{1,32}$/.test(sandboxId)) throw new Error('zerops: a sandbox id is lower-case letters and digits')
389
+ const context: DeployContext = {
390
+ run,
391
+ scripts: run.scripts ?? await readSandboxScripts(),
392
+ secrets: [...Object.values(environment), run.sandbox.sandboxKey],
393
+ }
394
+ const { scripts } = context
395
+ const checkpoint: ZeropsSandboxRunState = { sandboxId, runId: run.runId }
396
+ if (!dryRun) {
397
+ if (run.source === undefined) throw new Error('zerops: a sandbox deploy needs the resolved source')
398
+ await events.externalId(sandboxExternalId(checkpoint), encodeCheckpoint(checkpoint))
399
+ }
400
+ const log = events.log
401
+ const step = async (id: SandboxStepId): Promise<void> => {
402
+ await events.boundary()
403
+ assertRunning(signal)
404
+ if (dryRun) {
405
+ log(` [dry-run] would ${SANDBOX_STEPS.find((candidate) => candidate.id === id)?.description ?? id} in sandbox ${sandboxId}`)
406
+ return
407
+ }
408
+ const source = run.source
409
+ if (source === undefined || recipeInput === null || recipe === null) {
410
+ throw new Error('zerops: a sandbox deploy needs the resolved source and approved access')
411
+ }
412
+ switch (id) {
413
+ case 'wake-sandbox': {
414
+ const sandbox = await runningSandbox(run.client, sandboxId, run.sleep, signal)
415
+ log(` sandbox ${sandbox.id} is running on base ${sandbox.baseDigest}`)
416
+ return
417
+ }
418
+ case 'install-scripts': {
419
+ await installScripts(context)
420
+ log(` scripts ${scripts.version}`)
421
+ return
422
+ }
423
+ case 'stop-previous': {
424
+ await execOrThrow(run, 'stopping the previous launcher and build', ['/bin/sh', scripts.path('reset.sh')])
425
+ return
426
+ }
427
+ case 'upload-source': {
428
+ const uploaded = await run.sourcePort.upload({
429
+ repository: source.repository,
430
+ commitSha: source.commitSha,
431
+ descriptorSha256: artifact.target.sourceDescriptor.sha256,
432
+ archive: { kind: 'application', ...(source.privateBinding === undefined ? {} : { privateBinding: source.privateBinding }) },
433
+ uploadUrl: sandboxSourceUploadUrl(run.sandbox.apiOrigin, sandboxId),
434
+ uploadBearer: run.sandbox.sandboxKey,
435
+ signal,
436
+ })
437
+ if (uploaded.commitSha !== source.commitSha || uploaded.descriptorSha256 !== artifact.target.sourceDescriptor.sha256) {
438
+ throw new Error('zerops: source upload returned different coordinates')
439
+ }
440
+ await execOrThrow(run, 'extracting the source', EXTRACT_SOURCE)
441
+ log(` ${source.commitSha} is the application root (${uploaded.entryCount} entries)`)
442
+ return
443
+ }
444
+ case 'build': {
445
+ for (const label of sandboxBuildStepLabels(spa, recipe)) log(` ${label}`)
446
+ await runBuild(context, renderSandboxBuildScript(spa, recipe, scripts.path('run-build.sh')), checkpoint)
447
+ return
448
+ }
449
+ case 'write-env': {
450
+ await run.client.putFile(sandboxId, SANDBOX_ENV_FILE, new TextEncoder().encode(renderSandboxEnvFile(environment)), { mode: '0600', signal })
451
+ log(` ${Object.keys(environment).length} variable(s): ${Object.keys(environment).join(', ')}`)
452
+ return
453
+ }
454
+ case 'write-launcher-config': {
455
+ const config = sandboxLauncherConfig({ ...recipeInput, head: source.commitSha, spaBuild: spa })
456
+ await run.client.putFile(sandboxId, SANDBOX_LAUNCHER_CONFIG_PATH, new TextEncoder().encode(JSON.stringify(config)), { signal })
457
+ return
458
+ }
459
+ case 'start-launcher': {
460
+ await execOrThrow(run, 'starting the launcher', ['/bin/sh', scripts.path('start-launcher.sh')])
461
+ return
462
+ }
463
+ case 'await-boot': {
464
+ await awaitBoot(context)
465
+ log(' the launcher reported its boot')
466
+ return
467
+ }
468
+ }
469
+ }
470
+ return runSteps(SANDBOX_STEPS, { appId: run.appId, env: run.env, dryRun, signal, log }, (spec) => step(spec.id))
471
+ }