@fabrika/provider-zerops 0.9.0-dev.1 → 0.9.0-dev.11

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 (180) hide show
  1. package/package.json +17 -14
  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 +15 -1
  11. package/src/api/errors.ts +7 -3
  12. package/src/api/readers.ts +29 -0
  13. package/src/api/types.ts +52 -0
  14. package/src/api.ts +2 -0
  15. package/src/cli.ts +11 -0
  16. package/src/collaborators.ts +0 -14
  17. package/src/compile.ts +1 -1
  18. package/src/control.ts +159 -92
  19. package/src/execution.ts +45 -195
  20. package/src/index.ts +2 -0
  21. package/src/installation/admin.ts +1 -1
  22. package/src/installation/deploy-options.ts +10 -2
  23. package/src/installation/deploy.ts +241 -81
  24. package/src/installation/generated/platform-console-schema.ts +3 -0
  25. package/src/installation/generated/platform-proxy-manifest.ts +1 -1
  26. package/src/installation/guide.md +53 -19
  27. package/src/installation/hosts.ts +1 -7
  28. package/src/installation/index.ts +20 -16
  29. package/src/installation/init-options.ts +2 -1
  30. package/src/installation/install-environment.ts +47 -108
  31. package/src/installation/install-options.ts +3 -1
  32. package/src/installation/install-secrets.ts +24 -68
  33. package/src/installation/install.ts +9 -4
  34. package/src/installation/plain-credentials.ts +91 -0
  35. package/src/installation/sidecar.ts +5 -26
  36. package/src/installation/templates/README.md +13 -12
  37. package/src/installation/templates/platform.yml +3 -0
  38. package/src/installation/topology/setups.ts +17 -4
  39. package/src/installation/topology/topology.ts +33 -23
  40. package/src/installation/upgrade-options.ts +2 -2
  41. package/src/managed-env.ts +1 -174
  42. package/src/manifest.ts +14 -17
  43. package/src/namespace/claims.ts +60 -1
  44. package/src/namespace/codec.ts +17 -0
  45. package/src/namespace/errors.ts +22 -1
  46. package/src/namespace/manifest.ts +36 -23
  47. package/src/namespace/provisioning.ts +88 -114
  48. package/src/namespace/proxy-attempt.ts +14 -2
  49. package/src/namespace/proxy-reads.ts +28 -23
  50. package/src/namespace/proxy-secrets.ts +18 -5
  51. package/src/namespace/sandbox-host.ts +212 -0
  52. package/src/namespace/subdomain.ts +113 -0
  53. package/src/namespace/topology.ts +1 -1
  54. package/src/namespace/types.ts +13 -0
  55. package/src/namespace/update.ts +1 -0
  56. package/src/namespace-cli.ts +152 -0
  57. package/src/plain-credentials.ts +90 -0
  58. package/src/plan.ts +1 -6
  59. package/src/provider.ts +88 -166
  60. package/src/proxy-manifest-carrier.ts +39 -0
  61. package/src/sandbox/base-image.ts +100 -0
  62. package/src/sandbox/constants.ts +44 -0
  63. package/src/sandbox/deploy.ts +471 -0
  64. package/src/sandbox/dev-artifact.ts +206 -0
  65. package/src/sandbox/lifecycle.ts +204 -0
  66. package/src/sandbox/scripts.ts +26 -0
  67. package/src/sandbox-host.ts +28 -0
  68. package/src/source/port.ts +5 -0
  69. package/src/types.ts +6 -2
  70. package/src/zbox/client.ts +259 -0
  71. package/src/zbox/errors.ts +45 -0
  72. package/src/zbox/index.ts +22 -0
  73. package/src/zbox/types.ts +165 -0
  74. package/types/src/api/client.d.ts +5 -0
  75. package/types/src/api/errors.d.ts +26 -0
  76. package/types/src/api/polling.d.ts +41 -0
  77. package/types/src/api/readers.d.ts +1115 -0
  78. package/types/src/api/service-env-limit.d.ts +17 -0
  79. package/types/src/api/service-env-response.d.ts +23 -0
  80. package/types/src/api/types.d.ts +687 -0
  81. package/types/src/api.d.ts +6 -0
  82. package/types/src/authoring.d.ts +9 -0
  83. package/types/src/cli-args.d.ts +19 -0
  84. package/types/src/cli.d.ts +13 -0
  85. package/types/src/collaborators.d.ts +16 -0
  86. package/types/src/compile.d.ts +91 -0
  87. package/types/src/control.d.ts +51 -0
  88. package/types/src/database-budget.d.ts +38 -0
  89. package/types/src/descriptor.d.ts +28 -0
  90. package/types/src/execution.d.ts +114 -0
  91. package/types/src/exposure.d.ts +47 -0
  92. package/types/src/index.d.ts +31 -0
  93. package/types/src/installation/admin-options.d.ts +24 -0
  94. package/types/src/installation/admin.d.ts +35 -0
  95. package/types/src/installation/checker-release.d.ts +12 -0
  96. package/types/src/installation/deploy-options.d.ts +42 -0
  97. package/types/src/installation/deploy.d.ts +136 -0
  98. package/types/src/installation/generated/platform-console-schema.d.ts +2 -0
  99. package/types/src/installation/generated/platform-proxy-manifest.d.ts +2 -0
  100. package/types/src/installation/hosts.d.ts +34 -0
  101. package/types/src/installation/index.d.ts +7 -0
  102. package/types/src/installation/init-options.d.ts +38 -0
  103. package/types/src/installation/init.d.ts +60 -0
  104. package/types/src/installation/install-collaborators.d.ts +24 -0
  105. package/types/src/installation/install-environment.d.ts +63 -0
  106. package/types/src/installation/install-options.d.ts +49 -0
  107. package/types/src/installation/install-project.d.ts +13 -0
  108. package/types/src/installation/install-provisioning.d.ts +58 -0
  109. package/types/src/installation/install-secrets.d.ts +17 -0
  110. package/types/src/installation/install-token.d.ts +10 -0
  111. package/types/src/installation/install.d.ts +23 -0
  112. package/types/src/installation/installation-source.d.ts +8 -0
  113. package/types/src/installation/log.d.ts +44 -0
  114. package/types/src/installation/machine-key.d.ts +19 -0
  115. package/types/src/installation/placement-options.d.ts +11 -0
  116. package/types/src/installation/plain-credentials.d.ts +20 -0
  117. package/types/src/installation/platform-archive.d.ts +7 -0
  118. package/types/src/installation/platform-source.d.ts +8 -0
  119. package/types/src/installation/platform-upload.d.ts +3 -0
  120. package/types/src/installation/sidecar.d.ts +49 -0
  121. package/types/src/installation/source-options.d.ts +1 -0
  122. package/types/src/installation/topology/artifacts.d.ts +8 -0
  123. package/types/src/installation/topology/index.d.ts +5 -0
  124. package/types/src/installation/topology/installation-schemas.d.ts +2242 -0
  125. package/types/src/installation/topology/invariants.d.ts +23 -0
  126. package/types/src/installation/topology/setups.d.ts +59 -0
  127. package/types/src/installation/topology/topology.d.ts +153 -0
  128. package/types/src/installation/topology/validate.d.ts +11 -0
  129. package/types/src/installation/upgrade-options.d.ts +26 -0
  130. package/types/src/installation/upgrade-output.d.ts +6 -0
  131. package/types/src/installation/upgrade.d.ts +88 -0
  132. package/types/src/managed-env.d.ts +24 -0
  133. package/types/src/manifest.d.ts +199 -0
  134. package/types/src/namespace/claims.d.ts +16 -0
  135. package/types/src/namespace/codec.d.ts +352 -0
  136. package/types/src/namespace/constants.d.ts +25 -0
  137. package/types/src/namespace/errors.d.ts +25 -0
  138. package/types/src/namespace/manifest.d.ts +4 -0
  139. package/types/src/namespace/operator.d.ts +12 -0
  140. package/types/src/namespace/provisioning.d.ts +4 -0
  141. package/types/src/namespace/proxy-attempt.d.ts +39 -0
  142. package/types/src/namespace/proxy-reads.d.ts +27 -0
  143. package/types/src/namespace/proxy-secrets.d.ts +8 -0
  144. package/types/src/namespace/proxy-source.d.ts +74 -0
  145. package/types/src/namespace/sandbox-host.d.ts +23 -0
  146. package/types/src/namespace/subdomain.d.ts +43 -0
  147. package/types/src/namespace/topology.d.ts +9 -0
  148. package/types/src/namespace/types.d.ts +111 -0
  149. package/types/src/namespace/update.d.ts +6 -0
  150. package/types/src/namespace/validation.d.ts +12 -0
  151. package/types/src/namespace-cli.d.ts +2 -0
  152. package/types/src/namespace.d.ts +9 -0
  153. package/types/src/plain-credentials.d.ts +7 -0
  154. package/types/src/plan.d.ts +11 -0
  155. package/types/src/provider.d.ts +60 -0
  156. package/types/src/proxy-manifest-carrier.d.ts +37 -0
  157. package/types/src/sandbox/base-image.d.ts +28 -0
  158. package/types/src/sandbox/constants.d.ts +30 -0
  159. package/types/src/sandbox/deploy.d.ts +75 -0
  160. package/types/src/sandbox/dev-artifact.d.ts +51 -0
  161. package/types/src/sandbox/lifecycle.d.ts +27 -0
  162. package/types/src/sandbox/scripts.d.ts +11 -0
  163. package/types/src/sandbox-host.d.ts +16 -0
  164. package/types/src/schema.generated.d.ts +376 -0
  165. package/types/src/service-names.d.ts +4 -0
  166. package/types/src/service-references.d.ts +13 -0
  167. package/types/src/source/constants.d.ts +6 -0
  168. package/types/src/source/port.d.ts +65 -0
  169. package/types/src/source/types.d.ts +4 -0
  170. package/types/src/source/validation.d.ts +19 -0
  171. package/types/src/source.d.ts +2 -0
  172. package/types/src/types.d.ts +125 -0
  173. package/types/src/version-attempt.d.ts +8 -0
  174. package/types/src/zbox/client.d.ts +2 -0
  175. package/types/src/zbox/errors.d.ts +25 -0
  176. package/types/src/zbox/index.d.ts +3 -0
  177. package/types/src/zbox/types.d.ts +433 -0
  178. package/src/installation/mcp.ts +0 -102
  179. package/src/installation/proxy-manifest.ts +0 -214
  180. package/src/installation/secrets.ts +0 -78
@@ -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
+ }
@@ -0,0 +1,206 @@
1
+ // What a dev workspace sandbox runs, derived from the application's artifact: the refusals of what a sandbox cannot
2
+ // give an application, the launcher's environment and configuration, and the build script. PURE — no network.
3
+
4
+ import { contractRecipe } from '@fabrika/app/build'
5
+ import { DEV_LAUNCHER_CONFIG_FILE, type DevLauncherConfig, FABRIKA_CONTRACT_DIGEST } from '@fabrika/auth-core'
6
+ import type { JsonValue, ProviderManagedEnvironment } from '@fabrika/provider-contract'
7
+ import { parseZeropsDescriptor, selectZeropsDescriptorSetup } from '../descriptor'
8
+ import { lockedAuthoredBuild, ZEROPS_APPLICATION_PORT, type ZeropsContractRun } from '../execution'
9
+ import { isObjectStorageType } from '../exposure'
10
+ import { assertAuthoredManagedDocument } from '../managed-env'
11
+ import { applicationDatabaseOf, type FabrikaManifest } from '../manifest'
12
+ import { SANDBOX_APP_ROOT, SANDBOX_DATABASE_CONNECTIONS, SANDBOX_DATABASE_URL, SANDBOX_STATE_DIR } from './constants'
13
+
14
+ const SANDBOX = 'a dev environment runs in workspace sandboxes'
15
+
16
+ const isMapping = (value: JsonValue | undefined): value is { readonly [key: string]: JsonValue } =>
17
+ typeof value === 'object' && value !== null && !Array.isArray(value)
18
+
19
+ /** Refuse what a sandbox cannot give an application, one line each: object storage, the ClamAV scan, runtime packages. */
20
+ export function assertSandboxArtifact(
21
+ manifest: FabrikaManifest,
22
+ contract: Pick<ZeropsContractRun, 'scan'> | undefined = manifest.target.contract,
23
+ ): void {
24
+ const storage = manifest.target.importDocument.services.find((service) =>
25
+ typeof service['type'] === 'string' && isObjectStorageType(service['type'])
26
+ )
27
+ if (storage !== undefined) {
28
+ throw new Error(`zerops: ${SANDBOX}, which have no object storage; remove \`${String(storage['hostname'])}\` from the dev environment's config`)
29
+ }
30
+ if (contract?.scan === true) {
31
+ throw new Error(`zerops: ${SANDBOX}, which have no ClamAV scan; the contract scans uploads (scan: true)`)
32
+ }
33
+ const packages = manifest.target.runtimePackages ?? []
34
+ if (packages.length > 0) {
35
+ throw new Error(
36
+ `zerops: ${SANDBOX}, which install no runtime package; remove runtimePackages (${packages.join(', ')}) from the dev environment's config`,
37
+ )
38
+ }
39
+ }
40
+
41
+ /**
42
+ * Replaces each value of `values` long enough to be a credential in `text`, longest first: what the sandbox prints is
43
+ * application output, which may echo one. The launcher masks its own log the same way.
44
+ */
45
+ export function maskValues(text: string, values: readonly string[]): string {
46
+ let masked = text
47
+ for (const value of [...new Set(values)].filter((value) => value.length >= 8).sort((left, right) => right.length - left.length)) {
48
+ masked = masked.replaceAll(value, '[redacted]')
49
+ }
50
+ return masked
51
+ }
52
+
53
+ /** Refuse a handed variable or secret whose value holds a `${…}` reference, naming it and never its value. */
54
+ export function assertNoSandboxReferences(kind: 'variable' | 'secret', values: Readonly<Record<string, string>>): void {
55
+ for (const [name, value] of Object.entries(values)) {
56
+ if (value.includes('${')) throw new Error(`zerops: ${SANDBOX}, which resolve no \`\${…}\` reference; the ${kind} \`${name}\` holds one`)
57
+ }
58
+ }
59
+
60
+ export interface SandboxEnvironmentInput {
61
+ readonly artifact: FabrikaManifest
62
+ readonly secrets: Readonly<Record<string, string>>
63
+ readonly managed: ProviderManagedEnvironment
64
+ readonly contractDigest: string
65
+ }
66
+
67
+ /**
68
+ * The launcher's environment, as a Zerops deploy composes a service's: the secrets (on Zerops, sensitive service
69
+ * variables), the managed values Control handed, then the literals the generated run section carries. A declared variable
70
+ * only fills the import document, which a sandbox has none of. The local superuser stands in for the database service's,
71
+ * as the provisioning credential of the application's role family (ADR-0017).
72
+ */
73
+ export function sandboxEnvironment(input: SandboxEnvironmentInput): Record<string, string> {
74
+ assertNoSandboxReferences('secret', input.secrets)
75
+ const environment: Record<string, string> = { ...input.secrets }
76
+ for (const [name, { value }] of Object.entries(input.managed)) {
77
+ if (value !== null) environment[name] = value
78
+ }
79
+ environment['PORT'] = String(ZEROPS_APPLICATION_PORT)
80
+ environment[FABRIKA_CONTRACT_DIGEST] = input.contractDigest
81
+ if (applicationDatabaseOf(input.artifact) !== null) {
82
+ environment['FABRIKA_APP_DATABASE_URL'] = SANDBOX_DATABASE_URL
83
+ environment['FABRIKA_APP_DATABASE_CONNECTIONS'] = String(SANDBOX_DATABASE_CONNECTIONS)
84
+ }
85
+ return environment
86
+ }
87
+
88
+ const VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
89
+
90
+ /** The env file the base image's launcher script sources with `set -a`: one single-quoted assignment per variable. */
91
+ export function renderSandboxEnvFile(environment: Readonly<Record<string, string>>): string {
92
+ return Object.entries(environment).map(([name, value]) => {
93
+ if (!VARIABLE_NAME.test(name)) throw new Error(`zerops: \`${name}\` is not a variable name a shell can assign`)
94
+ if (value.includes('\u0000')) throw new Error(`zerops: the value of \`${name}\` holds a NUL byte`)
95
+ return `${name}='${value.replaceAll("'", "'\\''")}'\n`
96
+ }).join('')
97
+ }
98
+
99
+ /** The authored SPA commands of the artifact's selected setup: the only part of the authored build that survives. */
100
+ export function authoredSpaCommands(artifact: FabrikaManifest): string[] {
101
+ const parsed = parseZeropsDescriptor(artifact.target.sourceDescriptor.contents)
102
+ assertAuthoredManagedDocument(parsed.document)
103
+ const selected = selectZeropsDescriptorSetup(parsed, artifact.target.zeropsSetup)
104
+ const entries = parsed.document['zerops']
105
+ const entry = Array.isArray(entries) ? entries.find((candidate) => isMapping(candidate) && candidate['setup'] === selected) : undefined
106
+ if (!isMapping(entry)) throw new Error('zerops: descriptor requires setup entries')
107
+ return lockedAuthoredBuild(entry, selected).commands
108
+ }
109
+
110
+ export interface SandboxRecipeInput {
111
+ readonly appId: string
112
+ readonly checkRelease: string
113
+ readonly contract: ZeropsContractRun
114
+ }
115
+
116
+ /** `@fabrika/app/build`'s recipe in a sandbox: built and run in place, with no database at build, as on Zerops. */
117
+ export const sandboxRecipe = (input: SandboxRecipeInput) =>
118
+ contractRecipe({
119
+ appId: input.appId,
120
+ checkRelease: input.checkRelease,
121
+ sourceRoot: SANDBOX_APP_ROOT,
122
+ runtimeRoot: SANDBOX_APP_ROOT,
123
+ database: false,
124
+ sourceMaps: false,
125
+ jobs: input.contract.jobs,
126
+ files: input.contract.files === true,
127
+ scan: false,
128
+ })
129
+
130
+ /** What the dev launcher reads (`DEV_LAUNCHER_CONFIG_FILE`), written after the build's checks passed. */
131
+ export function sandboxLauncherConfig(
132
+ input: SandboxRecipeInput & { readonly head: string; readonly spaBuild: readonly string[] },
133
+ ): DevLauncherConfig {
134
+ if (!/^[0-9a-f]{40}$/.test(input.head)) throw new Error('zerops: a dev environment builds an exact commit')
135
+ const recipe = sandboxRecipe(input)
136
+ return {
137
+ format: 1,
138
+ appId: input.appId,
139
+ head: input.head,
140
+ port: ZEROPS_APPLICATION_PORT,
141
+ healthPath: input.contract.readinessPath,
142
+ serve: recipe.serve,
143
+ migrate: recipe.migrate,
144
+ spaBuild: input.spaBuild,
145
+ checks: recipe.checks,
146
+ }
147
+ }
148
+
149
+ export const SANDBOX_LAUNCHER_CONFIG_PATH = `${SANDBOX_APP_ROOT}/${DEV_LAUNCHER_CONFIG_FILE}`
150
+
151
+ const STEP_DIRECTORY = `${SANDBOX_STATE_DIR}/build`
152
+ const STEP_END = 'FABRIKA_BUILD_STEP_EOF'
153
+ const FILE_END = 'FABRIKA_BUILD_FILE_EOF'
154
+ const GENERATED_PATH = /^[A-Za-z0-9_][A-Za-z0-9._/-]*$/
155
+
156
+ const heredoc = (target: string, lines: readonly string[], end: string): string[] => {
157
+ if (lines.includes(end)) throw new Error('zerops: a build step holds the line that ends its here-document')
158
+ return [`cat > ${target} <<'${end}'`, ...lines, end]
159
+ }
160
+
161
+ const sha256 = (text: string): string => new Bun.CryptoHasher('sha256').update(text).digest('hex')
162
+
163
+ /** Writes `lines` to `target` through a quoted here-document, then checks the file holds exactly them. */
164
+ const verifiedHeredoc = (target: string, lines: readonly string[], end: string): string[] => [
165
+ ...heredoc(target, lines, end),
166
+ `echo '${sha256(`${lines.join('\n')}\n`)} ${target}' | sha256sum -c -s`,
167
+ ]
168
+
169
+ /**
170
+ * The generated part of the build, run as root: it writes each step to its own file (the authored SPA commands, then
171
+ * the recipe's steps), checks each was written whole, and hands over to the uploaded runner, which runs them as the
172
+ * unprivileged build user. Nothing here holds a credential.
173
+ */
174
+ export function renderSandboxBuildScript(authoredSpa: readonly string[], recipe: ReturnType<typeof sandboxRecipe>, runner: string): string {
175
+ const steps = [...authoredSpa.map((run) => ({ run })), ...recipe.build]
176
+ const lines = [
177
+ '#!/bin/sh',
178
+ '# Generated by the dev sandbox deploy.',
179
+ 'set -eu',
180
+ 'exec 2>&1',
181
+ 'umask 022',
182
+ `rm -rf ${STEP_DIRECTORY}`,
183
+ `mkdir -p ${STEP_DIRECTORY}`,
184
+ ]
185
+ for (const [index, step] of steps.entries()) {
186
+ const file = `${STEP_DIRECTORY}/${index + 1}.sh`
187
+ if ('run' in step) {
188
+ lines.push(...verifiedHeredoc(file, step.run.split('\n'), STEP_END))
189
+ } else {
190
+ if (!GENERATED_PATH.test(step.write) || step.write.includes('..')) throw new Error('zerops: a generated file path is not a plain relative path')
191
+ const slash = step.write.lastIndexOf('/')
192
+ // The file's lines sit inside the step's here-document too, so neither delimiter may appear among them.
193
+ if (step.lines.includes(STEP_END)) throw new Error('zerops: a build step holds the line that ends its here-document')
194
+ const write = [...(slash < 0 ? [] : [`mkdir -p ${step.write.slice(0, slash)}`]), ...heredoc(step.write, step.lines, FILE_END)]
195
+ lines.push(...verifiedHeredoc(file, write, STEP_END))
196
+ }
197
+ }
198
+ lines.push(`exec /bin/sh ${runner} ${steps.length}`)
199
+ return `${lines.join('\n')}\n`
200
+ }
201
+
202
+ /** One line per build step, as the run log lists them before the build starts. */
203
+ export function sandboxBuildStepLabels(authoredSpa: readonly string[], recipe: ReturnType<typeof sandboxRecipe>): string[] {
204
+ const steps = [...authoredSpa.map((run) => ({ run })), ...recipe.build]
205
+ return steps.map((step, index) => `${index + 1}: ${'run' in step ? (step.run.split('\n')[0] ?? '') : `write ${step.write}`}`)
206
+ }