@fabrika/provider-zerops 0.8.1 → 0.9.0-cloudflare.1

package/src/execution.ts

@@ -2,15 +2,20 @@
 // runs. Of the authored setup only `build.base`, `build.os` and the SPA's `build.buildCommands` survive; the rest of
 // the build, the deploy gate and the whole `run` section are generated here. PURE — no network, no filesystem.
 
+import { type ContractRecipe, contractRecipe } from '@fabrika/app/build'
 import {
 	type ContractArtifact,
+	DEV_LAUNCHER_BOOTED_FILE,
+	DEV_LAUNCHER_CONFIG_FILE,
+	DEV_LAUNCHER_MODULE,
+	type DevLauncherConfig,
 	FABRIKA_CONTRACT_DIGEST,
 	FABRIKA_SOURCE_MAP_UPLOAD,
 	FABRIKA_SOURCE_MAP_UPLOAD_KEY,
 	type FrameworkVariableName,
 } from '@fabrika/auth-core'
 import type { OperationsAssetRoot, OperationsSourceMapBuildUpload } from '@fabrika/operations-contract/releases'
-import { FRAMEWORK_RELEASE_PATTERN, type JsonValue } from '@fabrika/provider-contract'
+import type { JsonValue } from '@fabrika/provider-contract'
 import packageManifest from '../package.json'
 import { renderYaml } from './compile'
 import { parseZeropsDescriptor, type PreparedZeropsDescriptor, selectZeropsDescriptorSetup } from './descriptor'
@@ -29,8 +34,7 @@ export const ZEROPS_APPLICATION_RUNTIME = 'alpine/bun@1.3'
  */
 export const FABRIKA_CHECK_VERSION: string = packageManifest.version
 
-/** The compiler the platform type-checks with. It is fetched by version, never taken from the application's lockfile. */
-export const PLATFORM_TYPESCRIPT_VERSION = '5.9.3'
+export { PLATFORM_TYPESCRIPT_VERSION } from '@fabrika/app/build'
 
 /** System packages an application may add to its runtime image, installed by the generated `run.prepareCommands`. */
 export const ZEROPS_RUNTIME_PACKAGES = ['ffmpeg', 'ghostscript', 'imagemagick', 'poppler-utils', 'vips'] as const
@@ -42,12 +46,6 @@ export interface ZeropsContractJob {
 	readonly schedule: string
 }
 
-/** The framework's file scan job (`@fabrika/app`'s `FILE_SCAN_JOB`), run every minute when a collection scans. */
-export const ZEROPS_FILE_SCAN_JOB = 'fabrika-file-scan'
-/** The framework's file sweep job (`@fabrika/app`'s `FILE_SWEEP_JOB` and its schedule), run when the contract has files. */
-export const ZEROPS_FILE_SWEEP_JOB = 'fabrika-file-sweep'
-const FILE_SWEEP_SCHEDULE = '41 * * * *'
-
 /**
  * The RAM in GB a container of a scanning application starts with: one `clamscan` over a batch peaks at about 1 GB
  * resident while it loads its signatures (measured with ClamAV 1.4), beside the application's own process.
@@ -107,13 +105,26 @@ export interface ZeropsLockedExecution {
 	readonly runtimePackages: readonly ZeropsRuntimePackage[]
 	/** Where the build uploads its source maps, without the bearer; null when Control minted no upload for the run. */
 	readonly sourceMaps: OperationsSourceMapBuildUpload | null
+	/**
+	 * Present for an environment of kind `dev` (ADR-0049): `run.start` runs the dev launcher instead of the serving
+	 * entry. The environment's kind selects it; an application never authors it.
+	 */
+	readonly dev?: ZeropsDevExecution
+}
+
+export interface ZeropsDevExecution {
+	/** The commit the bootstrap run builds: what a new container holds before the launcher's first sync. */
+	readonly head: string
 }
 
 /** The application ids the generated scripts may name: the contract's own id rule, so a script needs no quoting. */
-export const LOCKED_APP_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/
+export { CONTRACT_APP_ID_PATTERN as LOCKED_APP_ID_PATTERN } from '@fabrika/app/build'
 
 export const CONTRACT_DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/
 
+/** A literal path of unreserved characters: it is written into the generated probes unquoted by any shell. */
+export const READINESS_PATH_PATTERN = /^(?:\/[A-Za-z0-9_~-][A-Za-z0-9._~-]*)+$/
+
 const byName = <T extends { readonly name: string }>(left: T, right: T): number => left.name < right.name ? -1 : left.name > right.name ? 1 : 0
 
 /**
@@ -241,31 +252,6 @@ export function lockedAuthoredBuild(entry: { readonly [key: string]: JsonValue }
 
 const SOURCE_ROOT = '/build/source'
 const RUNTIME_ROOT = '/var/www'
-const FABRIKA_BIN = './node_modules/.bin/fabrika'
-const MIGRATE_SCRIPT = 'fabrika/migrate.generated.sh'
-const VERIFY_SCRIPT = 'fabrika/verify.generated.sh'
-const START_SCRIPT = 'fabrika/start.generated.sh'
-const PLATFORM_TSCONFIG = 'fabrika/tsconfig.platform.json'
-
-/** The compiler options of the platform's type check; the application's own `tsconfig.json` and its `paths` are not read. */
-const PLATFORM_TSCONFIG_CONTENTS = JSON.stringify({
-	compilerOptions: {
-		target: 'ES2022',
-		module: 'ESNext',
-		moduleResolution: 'bundler',
-		lib: ['ES2022', 'DOM', 'DOM.Iterable'],
-		types: ['bun'],
-		strict: true,
-		noUncheckedIndexedAccess: true,
-		noImplicitOverride: true,
-		forceConsistentCasingInFileNames: true,
-		skipLibCheck: true,
-		resolveJsonModule: true,
-		isolatedModules: true,
-		noEmit: true,
-	},
-	include: ['../fabrika.contract.ts', '../src', 'entry.generated.ts'],
-})
 
 /** One `printf` writing `lines` to `path`. Each line is single-quoted, so it may hold neither `'` nor an expansion. */
 const writeFileCommand = (path: string, lines: readonly string[]): string => {
@@ -275,39 +261,6 @@ const writeFileCommand = (path: string, lines: readonly string[]): string => {
 	return `printf '%s\\n' ${lines.map((line) => `'${line}'`).join(' ')} > ${path}`
 }
 
-const migrateScript = (appId: string): readonly string[] => [
-	'#!/bin/sh',
-	'set -eu',
-	`cd ${RUNTIME_ROOT}`,
-	`FABRIKA_APP_ID=${appId} exec ${FABRIKA_BIN} db migrate`,
-]
-
-// The committed schema types must match the migrated schema and every generated isolation test must pass on a throwaway
-// schema. The build has no database, so they run at container start, after the migrations, as init commands: a failed
-// init command stops the activation, and the readiness window opens only with `run.start`, after the init commands (both
-// verified live), so a run as long as the CRM's ~3 minutes of generated cases does not race it.
-const verifyScript = (appId: string): readonly string[] => [
-	'#!/bin/sh',
-	'set -eu',
-	`cd ${RUNTIME_ROOT}`,
-	`FABRIKA_APP_ID=${appId} ${FABRIKA_BIN} db codegen --verify`,
-	`FABRIKA_APP_ID=${appId} exec ${FABRIKA_BIN} db test-isolation`,
-]
-
-const startScript: readonly string[] = ['#!/bin/sh', 'set -eu', `cd ${RUNTIME_ROOT}`, 'exec bun fabrika/entry.generated.ts']
-
-/** The scripts the build writes and every container's init commands run, in this order. */
-const initScripts = (execution: ZeropsLockedExecution): readonly { readonly path: string; readonly lines: readonly string[] }[] =>
-	execution.databaseUrl === null
-		? []
-		: [{ path: MIGRATE_SCRIPT, lines: migrateScript(execution.appId) }, { path: VERIFY_SCRIPT, lines: verifyScript(execution.appId) }]
-
-const INSTALL = 'bun install --frozen-lockfile --ignore-scripts'
-
-// After every check: a map is uploaded only for a build that can deploy. A failed upload never fails the build; the
-// provider reads the state from the report line.
-const sourceMapUpload = (release: string): string => `cd /tmp && bun x --bun -p @fabrika/check@${release} fabrika-source-maps ${SOURCE_ROOT} || true`
-
 /**
  * The upload's build variables: the destination and asset roots as a literal, and the bearer lifted from the service
  * variable the deploy wrote sensitive, so the descriptor never holds it.
@@ -319,26 +272,81 @@ const sourceMapBuildVariables = (upload: OperationsSourceMapBuildUpload): Record
 	return { [FABRIKA_SOURCE_MAP_UPLOAD]: value, [FABRIKA_SOURCE_MAP_UPLOAD_KEY]: `\${RUNTIME_${FABRIKA_SOURCE_MAP_UPLOAD_KEY}}` }
 }
 
-/**
- * The generated build commands, in order; the authored SPA commands run before all of them. The application's tests
- * run first: they are authored code, so everything after them is reinstalled, regenerated or checked again. They run
- * `--isolate`, as the application skill runs them: a test file's DOM globals otherwise leak into the next file.
- */
-export function generatedBuildCommands(execution: ZeropsLockedExecution): readonly string[] {
-	if (!LOCKED_APP_ID_PATTERN.test(execution.appId)) throw new Error('zerops: a contract application id must match [a-z0-9][a-z0-9-]*')
-	if (!FRAMEWORK_RELEASE_PATTERN.test(execution.checkRelease)) throw new Error('zerops: the checker release must be a release version')
-	return [
-		INSTALL,
-		'bun test --isolate --pass-with-no-tests',
-		`rm -rf node_modules && ${INSTALL}`,
-		`bun -e "await import('@fabrika/app/build').then((build) => build.writeGeneratedEntry('.', 'bun'))"`,
-		`cd /tmp && bun x --bun -p @fabrika/check@${execution.checkRelease} fabrika-check ${SOURCE_ROOT}`,
-		writeFileCommand(PLATFORM_TSCONFIG, [PLATFORM_TSCONFIG_CONTENTS]),
-		`cd /tmp && bun x --bun -p typescript@${PLATFORM_TYPESCRIPT_VERSION} tsc -p ${SOURCE_ROOT}/${PLATFORM_TSCONFIG}`,
-		...initScripts(execution).map((script) => writeFileCommand(script.path, script.lines)),
-		writeFileCommand(START_SCRIPT, startScript),
-		...(execution.sourceMaps === null ? [] : [sourceMapUpload(execution.checkRelease)]),
-	]
+// The readiness check is retried no sooner than every 10 s (the platform's floor), and a server is rarely listening at
+// the first attempt, one second after `run.start`. So one attempt waits for the health endpoint itself, for less than
+// the retry period; it passes only on a 2xx, like the `httpGet` it replaces. A dev container also passes once its launcher
+// reported the boot, served or failed: the launcher keeps running and reports a failed migration with its remedy.
+const readinessCommand = (path: string, dev: boolean): string => {
+	if (!READINESS_PATH_PATTERN.test(path)) throw new Error('zerops: a readiness path must be a literal path of unreserved characters')
+	const url = `http://127.0.0.1:${ZEROPS_APPLICATION_PORT}${path}`
+	const booted = dev ? `if (await Bun.file('${RUNTIME_ROOT}/${DEV_LAUNCHER_BOOTED_FILE}').exists()) process.exit(0); ` : ''
+	return `bun -e "const end = Date.now() + 9000; while (Date.now() < end) { ${booted}try { if ((await fetch('${url}', { signal: AbortSignal.timeout(2000) })).ok) process.exit(0) } catch {} await Bun.sleep(200) } process.exit(1)"`
+}
+
+/** `@fabrika/app/build`'s recipe at this installation's paths; the dev launcher checks in the runtime root. */
+const recipeOf = (execution: ZeropsLockedExecution, sourceRoot: string = SOURCE_ROOT): ContractRecipe =>
+	contractRecipe({
+		appId: execution.appId,
+		checkRelease: execution.checkRelease,
+		sourceRoot,
+		runtimeRoot: RUNTIME_ROOT,
+		// The build has no database; a container's init commands run the migrations and schema checks, and the readiness
+		// window opens only with `run.start`, after them (both verified live), so the CRM's ~3 minutes does not race it.
+		// A dev container has none: its init would run before Control says whether a reset is pending, over the schema the
+		// previous container left, so its launcher migrates and verifies after that answer.
+		database: execution.databaseUrl !== null && execution.dev === undefined,
+		sourceMaps: execution.sourceMaps !== null,
+		jobs: execution.contract.jobs,
+		files: execution.contract.files === true,
+		scan: execution.contract.scan === true,
+	})
+
+// A dev environment starts the launcher of the application's own framework release, which runs the serving entry as its
+// child. Double quotes inside: a generated file line may hold no single quote.
+const devStartScript: readonly string[] = [
+	'#!/bin/sh',
+	'set -eu',
+	`cd ${RUNTIME_ROOT}`,
+	`exec bun -e "await import(\\"${DEV_LAUNCHER_MODULE}\\").then((dev) => dev.runDevLauncher(process.env))"`,
+]
+
+/** One command writing `content` to `path` through base64: the content may hold quotes and expansions, the command none. */
+const writeBase64Command = (path: string, content: string): string => {
+	const encoded = btoa(String.fromCharCode(...new TextEncoder().encode(content)))
+	return `printf '%s' '${encoded}' | base64 -d > ${path}`
+}
+
+/** What the dev launcher reads (`DEV_LAUNCHER_CONFIG_FILE`): the platform's, written after the checks. */
+export function devLauncherConfig(execution: ZeropsLockedExecution, authoredSpa: readonly string[]): DevLauncherConfig {
+	const dev = execution.dev
+	if (dev === undefined) throw new Error('zerops: a dev launcher configuration needs a dev environment')
+	if (!/^[0-9a-f]{40}$/.test(dev.head)) throw new Error('zerops: a dev environment builds an exact commit')
+	const recipe = recipeOf(execution)
+	return {
+		format: 1,
+		appId: execution.appId,
+		head: dev.head,
+		port: ZEROPS_APPLICATION_PORT,
+		healthPath: execution.contract.readinessPath,
+		serve: recipe.serve,
+		migrate: recipe.migrate,
+		spaBuild: authoredSpa,
+		// The build's check chain, in its order, on what the container holds.
+		checks: recipeOf(execution, RUNTIME_ROOT).checks,
+	}
+}
+
+/** The generated build commands, in order; the authored SPA commands run before all of them. */
+export function generatedBuildCommands(execution: ZeropsLockedExecution, authoredSpa: readonly string[] = []): readonly string[] {
+	const recipe = recipeOf(execution)
+	return recipe.build.flatMap((step) => {
+		if ('run' in step) return [step.run]
+		if (execution.dev === undefined || step.write !== recipe.start) return [writeFileCommand(step.write, step.lines)]
+		return [
+			writeFileCommand(recipe.start, devStartScript),
+			writeBase64Command(DEV_LAUNCHER_CONFIG_FILE, JSON.stringify(devLauncherConfig(execution, authoredSpa))),
+		]
+	})
 }
 
 const sortedUnique = (values: readonly string[]): string[] => [...new Set(values)].sort()
@@ -354,16 +362,11 @@ const storageVariables = (hostname: string): Record<StorageVariable, string> =>
 })
 
 /** The crontab lines that run a job of the contract or of the framework, each on one container. */
-const jobCrontab = (contract: ZeropsContractRun): { readonly timing: string; readonly command: string; readonly allContainers: boolean }[] => [
-	...contract.jobs.map((job) => ({ timing: job.schedule, command: `${FABRIKA_BIN} job run ${job.name}`, allContainers: false })),
-	...(contract.files === true
-		? [{ timing: FILE_SWEEP_SCHEDULE, command: `${FABRIKA_BIN} job run ${ZEROPS_FILE_SWEEP_JOB}`, allContainers: false }]
-		: []),
-	...(contract.scan === true ? [{ timing: '* * * * *', command: `${FABRIKA_BIN} job run ${ZEROPS_FILE_SCAN_JOB}`, allContainers: false }] : []),
-]
+const jobCrontab = (execution: ZeropsLockedExecution): { readonly timing: string; readonly command: string; readonly allContainers: boolean }[] =>
+	recipeOf(execution).jobs.map((job) => ({ timing: job.schedule, command: job.command, allContainers: false }))
 
 /** How many job processes the crontab may run at once, each opening the application's database. */
-export const zeropsJobProcesses = (contract: ZeropsContractRun): number => jobCrontab(contract).length
+export const zeropsJobProcesses = (execution: ZeropsLockedExecution): number => jobCrontab(execution).length
 
 /** The commands every container runs before `run.start`, in order; any failure stops the activation. */
 export function generatedInitCommands(execution: ZeropsLockedExecution): string[] {
@@ -371,7 +374,7 @@ export function generatedInitCommands(execution: ZeropsLockedExecution): string[
 		// A container starts from the prepared image, whose signatures are as old as its build; a failed refresh leaves
 		// them to the daily one, and the scanner refuses signatures older than three days, so the scan fails closed.
 		...(execution.contract.scan === true ? [`${FRESHCLAM} || echo 'fabrika: freshclam did not refresh the malware signatures'`] : []),
-		...initScripts(execution).map((script) => `sh ${RUNTIME_ROOT}/${script.path}`),
+		...recipeOf(execution).init.map((path) => `sh ${RUNTIME_ROOT}/${path}`),
 	]
 }
 
@@ -396,7 +399,7 @@ export function renderLockedSetup(
 	const scan = contract.scan === true
 	const packages = sortedUnique([...execution.runtimePackages, ...(scan ? [SCANNER_PACKAGE] : [])])
 	// Every container keeps its own signatures; one scan pass at a time holds the job's lease.
-	const crontab = [...jobCrontab(contract), ...(scan ? [{ timing: FRESHCLAM_SCHEDULE, command: FRESHCLAM, allContainers: true }] : [])]
+	const crontab = [...jobCrontab(execution), ...(scan ? [{ timing: FRESHCLAM_SCHEDULE, command: FRESHCLAM, allContainers: true }] : [])]
 	const initCommands = generatedInitCommands(execution)
 	const prepareCommands = packages.length === 0 ? [] : [`sudo apk add --no-cache ${packages.join(' ')}`, ...(scan ? [FRESHCLAM] : [])]
 	return {
@@ -404,21 +407,29 @@ export function renderLockedSetup(
 		build: {
 			base: authored.base ?? [ZEROPS_APPLICATION_RUNTIME],
 			...(authored.os === null ? {} : { os: authored.os }),
-			buildCommands: [...authored.commands, ...generatedBuildCommands(execution)],
+			buildCommands: [...authored.commands, ...generatedBuildCommands(execution, authored.commands)],
 			...(execution.sourceMaps === null ? {} : { envVariables: sourceMapBuildVariables(execution.sourceMaps) }),
 			deployFiles: ['./'],
 			cache: ['node_modules'],
 		},
 		deploy: {
-			readinessCheck: { httpGet: probe, retryPeriod: '10s', failureTimeout: '180s' },
+			readinessCheck: {
+				exec: { command: readinessCommand(contract.readinessPath, execution.dev !== undefined) },
+				retryPeriod: '10s',
+				failureTimeout: '180s',
+			},
 		},
 		run: {
 			base: ZEROPS_APPLICATION_RUNTIME,
 			...(prepareCommands.length === 0 ? {} : { prepareCommands }),
 			...(initCommands.length === 0 ? {} : { initCommands }),
-			start: `sh ${RUNTIME_ROOT}/${START_SCRIPT}`,
+			start: `sh ${RUNTIME_ROOT}/${recipeOf(execution).start}`,
 			ports: [{ port: ZEROPS_APPLICATION_PORT, httpSupport: true }],
-			healthCheck: { httpGet: probe, execPeriod: '10s', disconnectTimeout: '30s', recoveryTimeout: '10s', failureTimeout: '120s' },
+			// A dev container keeps its launcher running while the application it respawns fails: Zerops restarting it
+			// would only boot the same failing head again.
+			...(execution.dev === undefined
+				? { healthCheck: { httpGet: probe, execPeriod: '10s', disconnectTimeout: '30s', recoveryTimeout: '10s', failureTimeout: '120s' } }
+				: {}),
 			...(crontab.length === 0 ? {} : { crontab }),
 			envVariables,
 		},

package/src/index.ts

@@ -18,6 +18,8 @@ export type {
 	ZeropsAppVersion,
 	ZeropsAppVersionStatus,
 	ZeropsAppVersionUpload,
+	ZeropsBackupConfig,
+	ZeropsBackupRetentionPolicy,
 	ZeropsImportedService,
 	ZeropsImportResult,
 	ZeropsIntegrationToken,

package/src/installation/admin.ts

@@ -15,10 +15,10 @@ import {
 	ensureFirstAdministrator,
 	type FirstAdministratorApi,
 	type FirstAdministratorResult,
+	platformOrigin,
 } from '@fabrika/installation-init'
 import type { PlatformAdminInput } from './admin-options'
 import { REISSUE_FLAG } from './admin-options'
-import { platformOrigin } from './hosts'
 import { MACHINE_KEY_NEXT_STEP_TITLE, machineKeyNextStepLines } from './machine-key'
 
 /**

package/src/installation/deploy-options.ts

@@ -12,8 +12,7 @@
 // The command is unattended by construction: nothing here prompts, and a missing required value is an
 // error naming both the flag and the variable that would supply it.
 
-import { describeArgument, readEnv, requiredSetting, setting } from '@fabrika/installation-init'
-import { type McpClient, parseMcpClientsJson } from './mcp'
+import { describeArgument, type McpClient, parseMcpClientsJson, readEnv, requiredSetting, setting } from '@fabrika/installation-init'
 import { parsePlatformHosts, parsePlatformScheme } from './placement-options'
 import { readInstallationSourceDir } from './source-options'