@fabrika/provider-zerops 0.0.3 → 0.0.5

package/src/manifest.ts

@@ -3,8 +3,10 @@ import type { JsonValue, ProviderCodec } from '@fabrika/provider-contract'
 import { compileImport, ENV_ISOLATION, OVERRIDE, renderYaml } from './compile'
 import type { ZeropsAppConfig, ZeropsNamespaceResourceRequirement, ZeropsProxySpec, ZeropsSharedPostgresBinding } from './types'
 
-export const FABRIKA_MANIFEST_VERSION = 2
+export const FABRIKA_MANIFEST_VERSION = 3
+export const ZEROPS_SOURCE_DESCRIPTOR_MAX_BYTES = 256 * 1024
 export const ZEROPS_SERVICE_HOSTNAME_PATTERN = /^[a-z0-9]{1,25}$/
+const SHA256_PATTERN = /^[0-9a-f]{64}$/
 
 /**
  * The one reference an app may declare for the namespace-owned PostgreSQL service.
@@ -22,6 +24,12 @@ export interface FabrikaImportDocument {
 	readonly services: ReadonlyArray<{ readonly [key: string]: JsonValue }>
 }
 
+export interface ZeropsArtifactSourceDescriptor {
+	readonly path: 'zerops.yaml'
+	readonly contents: string
+	readonly sha256: string
+}
+
 export interface FabrikaManifest {
 	manifestVersion: typeof FABRIKA_MANIFEST_VERSION
 	app: {
@@ -35,6 +43,8 @@ export interface FabrikaManifest {
 	}
 	target: {
 		platform: 'zerops'
+		/** The exact repository-root build descriptor used for this artifact. */
+		sourceDescriptor: ZeropsArtifactSourceDescriptor
 		/** The canonical document used both for resource claims and the Zerops API payload. */
 		importDocument: FabrikaImportDocument
 		deployService: string
@@ -264,6 +274,50 @@ const parseImportDocument = (value: unknown): FabrikaImportDocument => {
 	return project === undefined ? { services } : { project, services }
 }
 
+const parseSourceDescriptor = (value: unknown): ZeropsArtifactSourceDescriptor => {
+	if (value === undefined) {
+		throw new Error('invalid fabrika manifest Zerops source descriptor')
+	}
+	const raw = jsonObject(value, 'Zerops source descriptor')
+	const unknownKeys = Object.keys(raw).filter((key) => key !== 'path' && key !== 'contents' && key !== 'sha256')
+	if (unknownKeys.length > 0) {
+		throw new Error(`invalid fabrika manifest Zerops source descriptor field \`${unknownKeys[0]}\``)
+	}
+	const contents = raw['contents']
+	const sha256 = raw['sha256']
+	if (
+		raw['path'] !== 'zerops.yaml'
+		|| typeof contents !== 'string'
+		|| contents === ''
+		|| new TextEncoder().encode(contents).byteLength > ZEROPS_SOURCE_DESCRIPTOR_MAX_BYTES
+		|| typeof sha256 !== 'string'
+		|| !SHA256_PATTERN.test(sha256)
+	) {
+		throw new Error('invalid fabrika manifest Zerops source descriptor')
+	}
+	return { path: 'zerops.yaml', contents, sha256 }
+}
+
+export const createZeropsArtifactSourceDescriptor = async (contents: string): Promise<ZeropsArtifactSourceDescriptor> => {
+	const bytes = new TextEncoder().encode(contents)
+	if (bytes.byteLength === 0) {
+		throw new Error('Zerops source descriptor must not be empty')
+	}
+	if (bytes.byteLength > ZEROPS_SOURCE_DESCRIPTOR_MAX_BYTES) {
+		throw new Error(`Zerops source descriptor exceeds ${ZEROPS_SOURCE_DESCRIPTOR_MAX_BYTES} bytes`)
+	}
+	const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', bytes))
+	const sha256 = Array.from(digest, (byte) => byte.toString(16).padStart(2, '0')).join('')
+	return { path: 'zerops.yaml', contents, sha256 }
+}
+
+export const verifyZeropsArtifactSourceDescriptor = async (descriptor: ZeropsArtifactSourceDescriptor): Promise<void> => {
+	const actual = await createZeropsArtifactSourceDescriptor(descriptor.contents)
+	if (actual.sha256 !== descriptor.sha256) {
+		throw new Error('Zerops artifact source descriptor digest mismatch')
+	}
+}
+
 export const manifestServiceHostnames = (manifest: FabrikaManifest): string[] =>
 	manifest.target.importDocument.services.map((service) => {
 		const hostname = service['hostname']
@@ -312,6 +366,7 @@ export function parseFabrikaManifest(value: unknown, expected: ManifestExpectati
 	}
 
 	const rawTarget = prop(value, 'target')
+	const sourceDescriptor = parseSourceDescriptor(prop(rawTarget, 'sourceDescriptor'))
 	const rawImportDocument = prop(rawTarget, 'importDocument')
 	const deployService = nonEmptyString(rawTarget, 'deployService')
 	if (
@@ -372,6 +427,7 @@ export function parseFabrikaManifest(value: unknown, expected: ManifestExpectati
 		},
 		target: {
 			platform: 'zerops',
+			sourceDescriptor,
 			importDocument,
 			deployService,
 			...(zeropsSetup !== null ? { zeropsSetup } : {}),
@@ -381,7 +437,7 @@ export function parseFabrikaManifest(value: unknown, expected: ManifestExpectati
 	}
 }
 
-export function compileFabrikaManifest(config: ZeropsAppConfig, env: string): FabrikaManifest {
+export function compileFabrikaManifest(config: ZeropsAppConfig, env: string, sourceDescriptor: ZeropsArtifactSourceDescriptor): FabrikaManifest {
 	if (config.target.services === undefined) {
 		throw new Error('fabrika app build requires a source Zerops config')
 	}
@@ -414,6 +470,7 @@ export function compileFabrikaManifest(config: ZeropsAppConfig, env: string): Fa
 			},
 			target: {
 				platform: 'zerops',
+				sourceDescriptor,
 				importDocument: parseImportDocument(document),
 				deployService,
 				...(config.target.zeropsSetup !== undefined ? { zeropsSetup: config.target.zeropsSetup } : {}),
@@ -436,7 +493,7 @@ export function compileFabrikaManifest(config: ZeropsAppConfig, env: string): Fa
 
 /** Provider artifact codec. Its envelope version and manifest payload version advance independently. */
 export const zeropsArtifactCodec: ProviderCodec<FabrikaManifest> = {
-	version: 2,
+	version: 3,
 	encode: jsonValue,
 	decode: (payload) => parseFabrikaManifest(payload),
 }

package/src/provider.ts

@@ -10,12 +10,27 @@
 // cancel the build it started rather than leaving it running.
 
 import { createProvider, type ProviderDeploySession, type ProviderModule, type TypedProviderRun } from '@fabrika/provider-contract'
-import { ZEROPS_ACTIVE, ZEROPS_TERMINAL, type ZeropsAppVersion, type ZeropsLogAccess } from './api'
+import {
+	ZEROPS_ACTIVE,
+	ZEROPS_PROCESS_FINISHED,
+	ZEROPS_PROCESS_TERMINAL,
+	ZEROPS_TERMINAL,
+	ZeropsApiError,
+	type ZeropsAppVersion,
+	type ZeropsLogAccess,
+	type ZeropsProcess,
+} from './api'
 import { zeropsTargetCodec } from './codec'
-import { defaultZeropsCollaborators, type ZeropsCollaboratorFactory, type ZeropsCollaborators } from './collaborators'
-import { type FabrikaManifest, manifestServiceHostnames, renderFabrikaImportYaml, zeropsArtifactCodec } from './manifest'
+import { defaultSleep, defaultZeropsCollaborators, type ZeropsCollaboratorFactory, type ZeropsCollaborators } from './collaborators'
+import {
+	type FabrikaManifest,
+	manifestServiceHostnames,
+	renderFabrikaImportYaml,
+	verifyZeropsArtifactSourceDescriptor,
+	zeropsArtifactCodec,
+} from './manifest'
 import { buildZeropsPlan, resolveDeployHostname, type ZeropsJobSpec, type ZeropsPlan } from './plan'
-import type { ZeropsRuntimeTarget } from './types'
+import type { ZeropsRunState, ZeropsRuntimeSource, ZeropsRuntimeTarget } from './types'
 
 export const CANCELLED = 'deploy cancelled'
 
@@ -27,6 +42,12 @@ const POLL_INTERVAL_MS = 3000
 /** Give up after this long. Zerops' own pipeline limit is 1 hour; we allow a little slack past it. */
 const POLL_TIMEOUT_MS = 70 * 60 * 1000
 
+/** Delay before deciding whether an ambiguous build trigger remained pre-trigger. */
+const BUILD_TRIGGER_CONSISTENCY_MS = 10_000
+
+/** Source cancellation cannot hold Zerops cleanup hostage. */
+const SOURCE_CANCEL_TIMEOUT_MS = 5000
+
 /** Abandon the step if the run was cancelled. Checked before every real mutation and each poll iteration. */
 const assertRunning = (signal: AbortSignal): void => {
 	if (signal.aborted) {
@@ -74,7 +95,52 @@ interface StepEnv {
 	signal: AbortSignal
 	dryRun: boolean
 	/** Set by `trigger-deploy`, read by `await-deploy` — the only state that crosses a step boundary. */
-	state: { appVersionId?: string }
+	state: { appVersionId?: string; processId?: string }
+}
+
+const runState = (
+	appVersionId: string,
+	phase: Exclude<ZeropsRunState['phase'], 'build_triggered'>,
+): Exclude<ZeropsRunState, { phase: 'build_triggered' }> => ({ appVersionId, phase })
+
+const buildTriggeredState = (
+	appVersionId: string,
+	processId?: string,
+): Extract<ZeropsRunState, { phase: 'build_triggered' }> => ({
+	appVersionId,
+	phase: 'build_triggered',
+	...(processId === undefined ? {} : { processId }),
+})
+
+const requireSource = (env: StepEnv): { runtime: ZeropsRuntimeSource; client: NonNullable<ZeropsCollaborators['source']> } => {
+	const runtime = env.run.target.source
+	const client = env.zerops.source
+	if (runtime === undefined || client === undefined) {
+		throw new Error('zerops: upload-backed deploy requires source coordinates and a source client')
+	}
+	return { runtime, client }
+}
+
+const cancelSourceBestEffort = async (env: StepEnv, source: ZeropsRuntimeSource, appVersionId: string): Promise<void> => {
+	const client = env.zerops.source
+	if (client === undefined) return
+	const sourceController = new AbortController()
+	const timeoutController = new AbortController()
+	const cancel = Promise.resolve()
+		.then(() => client.cancel({ runId: source.runId, appVersionId, signal: sourceController.signal }))
+		.catch(() => {})
+	const timeout = Promise.resolve()
+		.then(() => (env.zerops.sourceCancelSleep ?? defaultSleep)(SOURCE_CANCEL_TIMEOUT_MS, timeoutController.signal))
+		.then(() => sourceController.abort())
+		.catch(() => {})
+	await Promise.race([cancel, timeout])
+	timeoutController.abort()
+	sourceController.abort()
+}
+
+const cleanupPreTriggerVersion = async (env: StepEnv, source: ZeropsRuntimeSource, appVersionId: string): Promise<void> => {
+	await cancelSourceBestEffort(env, source, appVersionId)
+	await env.zerops.api.deleteAppVersion({ appVersionId, signal: AbortSignal.timeout(5000) })
 }
 
 /**
@@ -83,7 +149,7 @@ interface StepEnv {
  * Deliberately FAILURE-TOLERANT: the log service's protocol is the one shape in this driver nobody could
  * verify against a document (see `ZeropsApi.readBuildLog`). An unverified endpoint must never be able to
  * fail a deploy, so a broken guess degrades to "no lines relayed" and the run still succeeds or fails on
- * `/app-version` status alone.
+ * the platform's process and app-version statuses.
  *
  * Relay is pull-based (ADR-0003), so each poll re-reads a window that overlaps the last one; `seen` keeps
  * the run log from repeating itself. Two genuinely identical lines with no timestamp collapse into one —
@@ -119,13 +185,14 @@ const openLog = async (env: StepEnv): Promise<ZeropsLogAccess | null> => {
 }
 
 /**
- * Poll `/app-version` until the version reaches a terminal state, relaying the build log as it goes.
+ * Poll the trigger process and `/app-version` until the version reaches a terminal state, relaying the
+ * build log as it goes. The process is optional because the trigger response may omit its id.
  *
  * A run cancelled here asks Zerops to cancel the BUILD too. That is not tidiness: the platform is running
  * the work, so abandoning the poll loop without telling it leaves a build container burning through the
  * pipeline's hour.
  */
-const awaitVersion = async (env: StepEnv, appVersionId: string): Promise<void> => {
+const awaitVersion = async (env: StepEnv, appVersionId: string, processId: string | undefined): Promise<void> => {
 	const { zerops, signal, log } = env
 	const access = await openLog(env)
 	const seen = new Set<string>()
@@ -138,13 +205,30 @@ const awaitVersion = async (env: StepEnv, appVersionId: string): Promise<void> =
 			await zerops.api.cancelBuild({ appVersionId, signal: AbortSignal.timeout(5000) }).catch(() => {})
 			throw new Error(CANCELLED)
 		}
-		const version = await zerops.api.getAppVersion({ appVersionId, signal })
+		let process: ZeropsProcess | undefined
+		let version: ZeropsAppVersion
+		try {
+			process = processId === undefined ? undefined : await zerops.api.getProcess({ processId, signal })
+			version = await zerops.api.getAppVersion({ appVersionId, signal })
+		} catch {
+			log(`  ${appVersionId}: status observation unavailable; retrying`)
+			if (Date.now() > deadline) {
+				throw new Error(`zerops: timed out after ${Math.round(POLL_TIMEOUT_MS / 60000)}m waiting for app-version ${appVersionId}`)
+			}
+			await zerops.sleep(POLL_INTERVAL_MS, signal)
+			continue
+		}
 		if (version.status !== previous) {
 			log(`  ${appVersionId}: ${version.status ?? 'unknown'}`)
 			previous = version.status
 		}
 		await relayLog(env, access, seen)
 
+		if (process?.status !== undefined && ZEROPS_PROCESS_TERMINAL.has(process.status) && process.status !== ZEROPS_PROCESS_FINISHED) {
+			throw new Error(
+				`zerops: pipeline process ${process.id} is ${process.status} while app-version ${appVersionId} is ${version.status ?? 'in an unknown state'}`,
+			)
+		}
 		if (version.status !== undefined && ZEROPS_TERMINAL.has(version.status)) {
 			if (version.status === ZEROPS_ACTIVE) {
 				return
@@ -180,37 +264,93 @@ const runStep = async (spec: ZeropsJobSpec, env: StepEnv): Promise<void> => {
 		}
 
 		case 'trigger-deploy': {
-			const source = target.buildFromGit === undefined ? "the service's configured Git integration" : target.buildFromGit
 			if (dryRun) {
-				log(`  [dry-run] would trigger the Zerops pipeline for service ${target.serviceId} (${env.deployHostname}) from ${source}`)
+				log(`  [dry-run] would create an app version, upload the resolved repository snapshot, and trigger build+deploy for service ${target.serviceId}`)
 				return
 			}
 			assertRunning(signal)
-			const zeropsSetup = artifact.target.zeropsSetup
-			const process = await zerops.api.triggerPipeline({
-				serviceId: target.serviceId,
-				buildFromGit: target.buildFromGit,
-				zeropsSetup,
-				signal,
-			})
-			// The trigger response's app-version id is optional on the wire, so resolve the version we just
-			// created rather than depending on it — and fail loudly if there is none, since awaiting a
-			// version we cannot name would silently watch someone else's deploy.
-			const version = process?.appVersionId !== undefined
-				? { id: process.appVersionId }
-				: await zerops.api.latestAppVersion({ serviceId: target.serviceId, signal })
-			if (version === null || version.id === '') {
-				throw new Error(`zerops: pipeline triggered for service ${target.serviceId} but no app-version could be resolved`)
-			}
+			const source = requireSource(env)
+			await verifyZeropsArtifactSourceDescriptor(artifact.target.sourceDescriptor)
+			const version = await zerops.api.createAppVersion({ serviceId: target.serviceId, name: source.runtime.runId, signal })
 			state.appVersionId = version.id
-			await run.events.externalId(version.id)
-			log(`  triggered: app-version ${version.id} (build+deploy is ONE platform-side operation)`)
+			let buildTriggerRequested = false
+			try {
+				await run.events.externalId(version.id, runState(version.id, 'version_created'))
+				const uploaded = await source.client.upload({
+					runId: source.runtime.runId,
+					appVersionId: version.id,
+					repository: source.runtime.repository,
+					commitSha: source.runtime.commitSha,
+					...(source.runtime.githubInstallationId === undefined
+						? {}
+						: { githubInstallationId: source.runtime.githubInstallationId }),
+					uploadUrl: version.uploadUrl,
+					descriptor: {
+						path: artifact.target.sourceDescriptor.path,
+						sha256: artifact.target.sourceDescriptor.sha256,
+					},
+					signal,
+				})
+				if (
+					uploaded.runId !== source.runtime.runId
+					|| uploaded.appVersionId !== version.id
+					|| uploaded.commitSha !== source.runtime.commitSha
+					|| uploaded.descriptorSha256 !== artifact.target.sourceDescriptor.sha256
+				) {
+					throw new Error('zerops: source upload returned different coordinates')
+				}
+				await run.events.checkpoint(runState(version.id, 'source_uploaded'))
+				await verifyZeropsArtifactSourceDescriptor(artifact.target.sourceDescriptor)
+				await run.events.checkpoint(runState(version.id, 'build_trigger_requested'))
+				buildTriggerRequested = true
+				let process: ZeropsProcess
+				try {
+					process = await zerops.api.buildAndDeployAppVersion({
+						appVersionId: version.id,
+						zeropsYaml: artifact.target.sourceDescriptor.contents,
+						...(artifact.target.zeropsSetup === undefined ? {} : { zeropsYamlSetup: artifact.target.zeropsSetup }),
+						signal,
+					})
+				} catch (error) {
+					if (error instanceof ZeropsApiError && error.status >= 400 && error.status < 500) {
+						await cleanupPreTriggerVersion(env, source.runtime, version.id)
+						throw error
+					}
+					let observed: ZeropsAppVersion | undefined
+					try {
+						await zerops.sleep(BUILD_TRIGGER_CONSISTENCY_MS, signal)
+						observed = await zerops.api.getAppVersion({ appVersionId: version.id, signal })
+					} catch {
+						log(`  ${version.id}: build-trigger observation unavailable; continuing to poll`)
+						return
+					}
+					if (observed.id === version.id && observed.status === 'UPLOADING') {
+						await cleanupPreTriggerVersion(env, source.runtime, version.id)
+						throw error
+					}
+					if (observed.id === version.id && observed.status !== undefined) {
+						await run.events.checkpoint(buildTriggeredState(version.id)).catch(() => {})
+						log(`  recovered accepted build trigger for app-version ${version.id}`)
+					} else {
+						log(`  ${version.id}: build-trigger state is not known yet; continuing to poll`)
+					}
+					return
+				}
+				state.processId = process.id
+				await run.events.checkpoint(buildTriggeredState(version.id, process.id)).catch(() => {})
+				log(`  triggered: app-version ${version.id} (build+deploy is ONE platform-side operation)`)
+			} catch (error) {
+				if (!buildTriggerRequested) {
+					await cleanupPreTriggerVersion(env, source.runtime, version.id)
+				}
+				throw error
+			}
 			return
 		}
 
 		case 'await-deploy': {
 			if (dryRun) {
-				log('  [dry-run] would poll /app-version until it is ACTIVE and relay the build log')
+				log('  [dry-run] would poll the pipeline process when available and /app-version until it is ACTIVE, relaying the build log')
 				return
 			}
 			const appVersionId = state.appVersionId
@@ -218,7 +358,7 @@ const runStep = async (spec: ZeropsJobSpec, env: StepEnv): Promise<void> => {
 				throw new Error('zerops: await-deploy has no app-version to watch (trigger-deploy did not run)')
 			}
 			assertRunning(signal)
-			await awaitVersion(env, appVersionId)
+			await awaitVersion(env, appVersionId, state.processId)
 			return
 		}