@fabrika/provider-zerops 0.0.3 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/provider-zerops",
-	"version": "0.0.3",
+	"version": "0.0.5",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -32,9 +32,9 @@
 		"gen:schema": "bun scripts/generate-zerops-types.ts"
 	},
 	"dependencies": {
-		"@fabrika/auth": "^0.0.3",
-		"@fabrika/auth-core": "^0.0.3",
-		"@fabrika/provider-contract": "^0.0.3",
-		"@fabrika/proxy-contract": "^0.0.3"
+		"@fabrika/auth": "^0.0.5",
+		"@fabrika/auth-core": "^0.0.5",
+		"@fabrika/provider-contract": "^0.0.5",
+		"@fabrika/proxy-contract": "^0.0.5"
 	}
 }

package/src/api.ts

@@ -62,6 +62,13 @@ export interface ZeropsAppVersion {
 	build?: { startDate?: string; endDate?: string; pipelineStart?: string; pipelineFinish?: string; pipelineFailed?: string }
 }
 
+/** The credential-bearing result of reserving one upload-backed application version. */
+export interface ZeropsAppVersionUpload {
+	id: string
+	/** Presigned object-storage destination. Never log it or include it in an error. */
+	uploadUrl: string
+}
+
 /** An asynchronous platform operation. VERIFIED: `OutDtoProcess`. */
 export interface ZeropsProcess {
 	id: string
@@ -268,10 +275,10 @@ export interface ZeropsLogLine {
  * case cancellation was added for, and an abandoned run must not keep an HTTP request alive.
  *
  * WIDER THAN THE DRIVER, on purpose. The driver uses four of these; the rest are the CONTROL PLANE's
- * Zerops surface — `putServiceEnv`/`listServiceEnv` for the edit-time secret writes that ADR-0004 says are
- * not a deploy step, `importProject` for creating a managed project, and `getAppVersion`/`latestAppVersion`
- * for the startup reconciliation of in-flight runs that ADR-0003 makes a requirement. One client, so there
- * is one place the Zerops contract is written down.
+ * Zerops surface — the service-env methods for the edit-time secret writes that ADR-0004 says are not a
+ * deploy step, `importProject` for creating a managed project, and `getAppVersion`/`latestAppVersion` for
+ * the startup reconciliation of in-flight runs that ADR-0003 makes a requirement. One client, so there is
+ * one place the Zerops contract is written down.
  *
  * NOTE WHAT IS ABSENT. There is no method that writes a PROJECT-level environment variable. That is not
  * an oversight and must not be "completed": project-level variables are injected into every service in the
@@ -329,6 +336,27 @@ export interface ZeropsApi {
 		signal: AbortSignal
 	}): Promise<ZeropsProcess | null>
 
+	/**
+	 * Reserve an upload-backed application version. VERIFIED: `POST /service-stack/{id}/app-version`,
+	 * optional body `{ name }`, response `ResponsePostAppVersion`.
+	 */
+	createAppVersion(input: { serviceId: string; name?: string; signal: AbortSignal }): Promise<ZeropsAppVersionUpload>
+
+	/**
+	 * Build and deploy an application version whose source archive has already been uploaded. VERIFIED:
+	 * `PUT /app-version/{id}/build-and-deploy`, required body `{ zeropsYaml }` and optional
+	 * `zeropsYamlSetup`.
+	 */
+	buildAndDeployAppVersion(input: {
+		appVersionId: string
+		zeropsYaml: string
+		zeropsYamlSetup?: string
+		signal: AbortSignal
+	}): Promise<ZeropsProcess>
+
+	/** Delete an application version, including an untriggered upload reservation. VERIFIED: `DELETE /app-version/{id}`. */
+	deleteAppVersion(input: { appVersionId: string; signal: AbortSignal }): Promise<void>
+
 	/** One application version's current state — the poll target. VERIFIED: `GET /app-version/{id}`. */
 	getAppVersion(input: { appVersionId: string; signal: AbortSignal }): Promise<ZeropsAppVersion>
 
@@ -420,6 +448,16 @@ export interface ZeropsApi {
 	 */
 	listServiceEnv(input: { serviceId: string; signal: AbortSignal }): Promise<ZeropsServiceEnv[]>
 
+	/**
+	 * Create ONE service-level variable only when the key is absent.
+	 * VERIFIED: `POST /service-stack/{id}/user-data`, body `{ key, content }`.
+	 *
+	 * Unlike `putServiceEnv`, a duplicate is an error and is never followed by a read or update. Error
+	 * details are intentionally unavailable because both the request and an upstream response can contain
+	 * the secret value.
+	 */
+	createServiceEnv(input: { serviceId: string; key: string; value: string; signal: AbortSignal }): Promise<void>
+
 	/**
 	 * Create-or-update ONE service-level variable — the only way fabrika ever writes a secret, and it is
 	 * addressed BY SERVICE so ADR-0004's invariant cannot be violated by calling it.
@@ -745,6 +783,8 @@ const apiError = (label: string, status: number, body: unknown, redactDetail: bo
 export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 	const base = (options.baseUrl ?? ZEROPS_API_BASE).replace(/\/+$/, '')
 	const doFetch = options.fetchImpl ?? fetch
+	const abortError = (): DOMException => new DOMException('The operation was aborted', 'AbortError')
+	const isAbortError = (error: unknown): boolean => error instanceof Error && error.name === 'AbortError'
 
 	const request = async (
 		label: string,
@@ -754,26 +794,56 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 		 * `redactDetail` drops the server's message from the thrown error, keeping only its code. Set it on
 		 * any call whose BODY carries a secret value: a validation error can quote what it rejected, and an
 		 * error that echoes a secret into a deploy log is a leak whichever end wrote it.
+		 * `omitErrorResponseDetails` also drops the code for upload flows whose response may carry a
+		 * credential; nothing from that response body may reach an error.
 		 */
-		init: { body?: unknown; signal: AbortSignal; redactDetail?: boolean },
+		init: { body?: unknown; signal: AbortSignal; redactDetail?: boolean; omitErrorResponseDetails?: boolean },
 	): Promise<unknown> => {
+		if (init.signal.aborted) {
+			throw abortError()
+		}
 		const headers: Record<string, string> = { authorization: `Bearer ${options.token}`, accept: 'application/json' }
 		if (init.body !== undefined) {
 			headers['content-type'] = 'application/json'
 		}
-		const response = await doFetch(`${base}${path}`, {
-			method,
-			headers,
-			body: init.body === undefined ? undefined : JSON.stringify(init.body),
-			signal: init.signal,
-		})
-		const payload: unknown = await response.json().catch(() => null)
+		let response: Response
+		try {
+			response = await doFetch(`${base}${path}`, {
+				method,
+				headers,
+				body: init.body === undefined ? undefined : JSON.stringify(init.body),
+				signal: init.signal,
+			})
+		} catch (error) {
+			if (init.signal.aborted || isAbortError(error)) throw abortError()
+			throw error
+		}
+		let payload: unknown
+		try {
+			payload = await response.json()
+		} catch (error) {
+			if (init.signal.aborted || isAbortError(error)) throw abortError()
+			payload = null
+		}
 		if (!response.ok) {
+			if (init.omitErrorResponseDetails === true) {
+				throw new ZeropsApiError(`zerops: ${label} failed (${response.status})`, response.status, '')
+			}
 			throw apiError(label, response.status, payload, init.redactDetail === true)
 		}
 		return payload
 	}
 
+	const invalidResponse = (label: string): Error => new Error(`zerops: ${label} returned an invalid response`)
+
+	const requiredString = (payload: unknown, key: string, label: string): string => {
+		const value = str(payload, key)
+		if (value === undefined || value.trim() === '') {
+			throw invalidResponse(label)
+		}
+		return value
+	}
+
 	const readImportResult = (payload: unknown): ZeropsImportResult => ({
 		projectId: str(payload, 'projectId') ?? '',
 		projectName: str(payload, 'projectName'),
@@ -844,6 +914,48 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 			return process === undefined || process === null ? null : readProcess(process)
 		},
 
+		createAppVersion: async ({ serviceId, name, signal }) => {
+			const body = name === undefined ? {} : { name }
+			const payload = await request('create app-version', 'POST', `/service-stack/${serviceId}/app-version`, {
+				body,
+				signal,
+				omitErrorResponseDetails: true,
+			})
+			const responseServiceId = requiredString(payload, 'serviceStackId', 'create app-version')
+			if (responseServiceId !== serviceId) {
+				throw invalidResponse('create app-version')
+			}
+			return {
+				id: requiredString(payload, 'id', 'create app-version'),
+				uploadUrl: requiredString(payload, 'uploadUrl', 'create app-version'),
+			}
+		},
+
+		buildAndDeployAppVersion: async ({ appVersionId, zeropsYaml, zeropsYamlSetup, signal }) => {
+			const body = zeropsYamlSetup === undefined ? { zeropsYaml } : { zeropsYaml, zeropsYamlSetup }
+			const payload = await request('build and deploy app-version', 'PUT', `/app-version/${appVersionId}/build-and-deploy`, {
+				body,
+				signal,
+				omitErrorResponseDetails: true,
+			})
+			const processId = requiredString(payload, 'id', 'build and deploy app-version')
+			const responseAppVersionId = str(prop(payload, 'appVersion'), 'id')
+			if (responseAppVersionId !== undefined && (responseAppVersionId.trim() === '' || responseAppVersionId !== appVersionId)) {
+				throw invalidResponse('build and deploy app-version')
+			}
+			return { ...readProcess(payload), id: processId, appVersionId }
+		},
+
+		deleteAppVersion: async ({ appVersionId, signal }) => {
+			const payload = await request('delete app-version', 'DELETE', `/app-version/${appVersionId}`, {
+				signal,
+				omitErrorResponseDetails: true,
+			})
+			if (prop(payload, 'success') !== true) {
+				throw invalidResponse('delete app-version')
+			}
+		},
+
 		getAppVersion: async ({ appVersionId, signal }) =>
 			readAppVersion(await request('get app-version', 'GET', `/app-version/${appVersionId}`, { signal })),
 
@@ -904,6 +1016,19 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
 
 		listServiceEnv,
 
+		createServiceEnv: async ({ serviceId, key, value, signal }) => {
+			try {
+				await request('create-only service env', 'POST', `/service-stack/${serviceId}/user-data`, {
+					body: { key, content: value },
+					signal,
+					omitErrorResponseDetails: true,
+				})
+			} catch (error) {
+				if (error instanceof Error && error.name === 'AbortError') throw error
+				throw new Error('zerops: create-only service env failed')
+			}
+		},
+
 		putServiceEnv: async ({ serviceId, key, value, signal }) => {
 			// `redactDetail` on both writes: this is the one place a secret VALUE is in the request body.
 			try {

package/src/cli.ts

@@ -1,8 +1,15 @@
 #!/usr/bin/env bun
+import { constants } from 'node:fs'
+import { open } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { isZeropsAppConfig } from './authoring'
 import { parseZeropsCliArgs } from './cli-args'
-import { compileFabrikaManifest, manifestServiceHostnames } from './manifest'
+import {
+	compileFabrikaManifest,
+	createZeropsArtifactSourceDescriptor,
+	manifestServiceHostnames,
+	ZEROPS_SOURCE_DESCRIPTOR_MAX_BYTES,
+} from './manifest'
 import { runZeropsNamespaceCommand } from './namespace-command'
 import type { ZeropsAppConfig } from './types'
 
@@ -47,6 +54,38 @@ const loadConfig = async (path: string): Promise<ZeropsAppConfig> => {
 	return config
 }
 
+export const readZeropsSourceDescriptor = async (root: string = process.cwd()) => {
+	const path = resolve(root, 'zerops.yaml')
+	const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK).catch((error: unknown) => {
+		if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+			throw new Error(`Missing repository-root Zerops source descriptor: ${path}`)
+		}
+		if (error instanceof Error && 'code' in error && error.code === 'ELOOP') {
+			throw new Error(`Repository-root Zerops source descriptor must not be a symlink: ${path}`)
+		}
+		throw error
+	})
+	try {
+		const metadata = await file.stat()
+		if (!metadata.isFile()) {
+			throw new Error(`Repository-root Zerops source descriptor must be a regular file: ${path}`)
+		}
+		if (metadata.size > ZEROPS_SOURCE_DESCRIPTOR_MAX_BYTES) {
+			throw new Error(`Zerops source descriptor exceeds ${ZEROPS_SOURCE_DESCRIPTOR_MAX_BYTES} bytes: ${path}`)
+		}
+		const bytes = await file.readFile()
+		let contents: string
+		try {
+			contents = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes)
+		} catch {
+			throw new Error(`Zerops source descriptor is not valid UTF-8: ${path}`)
+		}
+		return await createZeropsArtifactSourceDescriptor(contents)
+	} finally {
+		await file.close()
+	}
+}
+
 export const runZeropsCli = async (argv: readonly string[]): Promise<void> => {
 	const args = parseZeropsCliArgs(argv)
 	if (args.help || args.command === undefined) {
@@ -68,7 +107,8 @@ export const runZeropsCli = async (argv: readonly string[]): Promise<void> => {
 		throw new Error('`build` requires --env=<env>')
 	}
 	const config = await loadConfig(args.config)
-	const manifest = compileFabrikaManifest(config, args.env)
+	const sourceDescriptor = await readZeropsSourceDescriptor()
+	const manifest = compileFabrikaManifest(config, args.env, sourceDescriptor)
 	const output = resolve(process.cwd(), args.output)
 	await Bun.write(output, `${JSON.stringify(manifest, null, '\t')}\n`)
 	console.info(`wrote ${output} (${manifestServiceHostnames(manifest).length} service(s))`)

package/src/codec.ts

@@ -1,5 +1,5 @@
 import type { JsonValue, ProviderCodec } from '@fabrika/provider-contract'
-import type { ZeropsRuntimeTarget } from './types'
+import type { ZeropsRuntimeSource, ZeropsRuntimeTarget } from './types'
 
 const field = (payload: JsonValue, key: string): JsonValue | undefined => {
 	if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
@@ -27,24 +27,82 @@ const optionalString = (payload: JsonValue, key: string): string | undefined =>
 	return value
 }
 
+const IMMUTABLE_GIT_OBJECT = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/
+
+const object = (value: JsonValue | undefined, label: string): { readonly [key: string]: JsonValue } => {
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+		throw new Error(`${label} must be an object`)
+	}
+	return value
+}
+
+const runtimeSource = (payload: JsonValue): ZeropsRuntimeSource | undefined => {
+	const value = field(payload, 'source')
+	if (value === undefined) return undefined
+	const source = object(value, 'Zerops target source')
+	const repository = object(source['repository'], 'Zerops target source repository')
+	const allowedSourceKeys = ['runId', 'repository', 'commitSha', 'githubInstallationId']
+	const allowedRepositoryKeys = ['owner', 'name']
+	if (Object.keys(source).some((key) => !allowedSourceKeys.includes(key))) {
+		throw new Error('Zerops target source contains an unknown field')
+	}
+	if (Object.keys(repository).some((key) => !allowedRepositoryKeys.includes(key))) {
+		throw new Error('Zerops target source repository contains an unknown field')
+	}
+	const installation = source['githubInstallationId']
+	if (installation !== undefined && (typeof installation !== 'number' || !Number.isSafeInteger(installation) || installation <= 0)) {
+		throw new Error('Zerops target source githubInstallationId must be a positive safe integer')
+	}
+	const commitSha = requiredString(source, 'commitSha')
+	if (!IMMUTABLE_GIT_OBJECT.test(commitSha)) {
+		throw new Error('Zerops target source commitSha must be an exact lowercase Git object id')
+	}
+	return {
+		runId: requiredString(source, 'runId'),
+		repository: {
+			owner: requiredString(repository, 'owner'),
+			name: requiredString(repository, 'name'),
+		},
+		commitSha,
+		...(installation === undefined ? {} : { githubInstallationId: installation }),
+	}
+}
+
 export const zeropsTargetCodec: ProviderCodec<ZeropsRuntimeTarget> = {
-	version: 1,
+	version: 2,
 	encode: (target) => ({
 		projectId: target.projectId,
 		serviceId: target.serviceId,
 		accessToken: target.accessToken,
-		...(target.buildFromGit !== undefined ? { buildFromGit: target.buildFromGit } : {}),
+		...(target.source === undefined
+			? {}
+			: {
+				source: {
+					runId: target.source.runId,
+					repository: { owner: target.source.repository.owner, name: target.source.repository.name },
+					commitSha: target.source.commitSha,
+					...(target.source.githubInstallationId === undefined ? {} : { githubInstallationId: target.source.githubInstallationId }),
+				},
+			}),
 		...(target.apiBaseUrl !== undefined ? { apiBaseUrl: target.apiBaseUrl } : {}),
 		...(target.propustkaUrl !== undefined ? { propustkaUrl: target.propustkaUrl } : {}),
 		...(target.adminKey !== undefined ? { adminKey: target.adminKey } : {}),
 	}),
-	decode: (payload) => ({
-		projectId: requiredString(payload, 'projectId'),
-		serviceId: requiredString(payload, 'serviceId'),
-		accessToken: requiredString(payload, 'accessToken'),
-		...(optionalString(payload, 'buildFromGit') !== undefined ? { buildFromGit: optionalString(payload, 'buildFromGit') } : {}),
-		...(optionalString(payload, 'apiBaseUrl') !== undefined ? { apiBaseUrl: optionalString(payload, 'apiBaseUrl') } : {}),
-		...(optionalString(payload, 'propustkaUrl') !== undefined ? { propustkaUrl: optionalString(payload, 'propustkaUrl') } : {}),
-		...(optionalString(payload, 'adminKey') !== undefined ? { adminKey: optionalString(payload, 'adminKey') } : {}),
-	}),
+	decode: (payload) => {
+		const target = object(payload, 'Zerops target')
+		const allowedKeys = ['projectId', 'serviceId', 'accessToken', 'source', 'apiBaseUrl', 'propustkaUrl', 'adminKey']
+		if (Object.keys(target).some((key) => !allowedKeys.includes(key))) {
+			throw new Error('Zerops target contains an unknown field')
+		}
+		const source = runtimeSource(payload)
+		return {
+			projectId: requiredString(payload, 'projectId'),
+			serviceId: requiredString(payload, 'serviceId'),
+			accessToken: requiredString(payload, 'accessToken'),
+			...(source === undefined ? {} : { source }),
+			...(optionalString(payload, 'apiBaseUrl') !== undefined ? { apiBaseUrl: optionalString(payload, 'apiBaseUrl') } : {}),
+			...(optionalString(payload, 'propustkaUrl') !== undefined ? { propustkaUrl: optionalString(payload, 'propustkaUrl') } : {}),
+			...(optionalString(payload, 'adminKey') !== undefined ? { adminKey: optionalString(payload, 'adminKey') } : {}),
+		}
+	},
 }

package/src/collaborators.ts

@@ -1,6 +1,7 @@
 import { reconcileSchema } from '@fabrika/auth'
 import type { SchemaReconciler } from '@fabrika/provider-contract'
 import { createZeropsApi, type ZeropsApi } from './api'
+import type { ZeropsSourceClient } from './source'
 import type { ZeropsRuntimeTarget } from './types'
 
 export type Sleeper = (ms: number, signal: AbortSignal) => Promise<void>
@@ -24,6 +25,10 @@ export const defaultSleep: Sleeper = (ms, signal) =>
 
 export interface ZeropsCollaborators {
 	api: ZeropsApi
+	/** Injected by the Zerops control composition; dry runs do not require it. */
+	source?: ZeropsSourceClient
+	/** Independently bounds best-effort source cancellation without delaying Zerops cleanup. */
+	sourceCancelSleep?: Sleeper
 	reconcileSchema: SchemaReconciler
 	sleep: Sleeper
 }