@fabrika/provider-zerops 0.0.26 → 0.3.1

package/src/namespace/proxy-attempt.ts

@@ -0,0 +1,220 @@
+import { followLeaseLoss, isLeaseLoss, ProviderNamespaceError } from '@fabrika/provider-contract'
+import { encodeProxyManifestJson, FABRIKA_PROXY_MANIFEST_JSON, type ProxyManifest } from '@fabrika/proxy-core/manifest'
+import { ZEROPS_ACTIVE, ZEROPS_TERMINAL, type ZeropsApi, ZeropsApiError, type ZeropsAppVersion } from '../api'
+import type { Sleeper } from '../collaborators'
+import { prepareZeropsDescriptor } from '../descriptor'
+import { isZeropsUploadDestination } from '../source'
+import type { ZeropsSourcePort } from '../source/port'
+import { deleteVersion } from '../version-attempt'
+import { ZEROPS_NAMESPACE_IAM_ISSUER_VARIABLE, ZEROPS_NAMESPACE_IAM_KEY_VARIABLE } from './constants'
+import { verifyZeropsNamespaceProxySource } from './proxy-source'
+import type { ZeropsNamespaceProxyBuild, ZeropsNamespaceTarget } from './types'
+
+export type ZeropsProxyApi = Pick<
+	ZeropsApi,
+	'listServiceEnv' | 'putServiceEnv' | 'createAppVersion' | 'deleteAppVersion' | 'buildAndDeployAppVersion' | 'getAppVersion'
+>
+
+export interface ZeropsProxyRepublishInput {
+	readonly target: ZeropsNamespaceTarget
+	readonly manifest: ProxyManifest
+	readonly source?: ZeropsSourcePort
+	readonly api: ZeropsProxyApi
+	readonly iamUrl: string
+	readonly iamKey: string
+	/** Aborts with `lease_lost` when the namespace lease goes, and with `cancel_requested` when a deploy is cancelled. */
+	readonly signal: AbortSignal
+	readonly wait: 'started' | 'active'
+	/** Persist the target; the caller fences the write on the namespace lease. */
+	readonly checkpoint: (target: ZeropsNamespaceTarget) => Promise<void>
+	readonly boundary: () => Promise<void>
+	readonly sleep: Sleeper
+}
+
+const POLL_INTERVAL_MS = 3000
+const POLL_DEADLINE_MS = 70 * 60 * 1000
+const USER_DATA_SYNC_ATTEMPTS = 10
+const SESSION_OWNER_VARIABLE = 'FABRIKA_PROXY_SESSION_OWNER_JSON'
+
+const unresolved = (id: string): ProviderNamespaceError =>
+	new ProviderNamespaceError(`Proxy version ${id} remains unresolved; reconcile this namespace before another build`, 'proxyAttemptUnresolved', true)
+
+const digest = async (text: string): Promise<string> =>
+	Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text))), byte => byte.toString(16).padStart(2, '0')).join(
+		'',
+	)
+
+const writeProxyIam = async (input: ZeropsProxyRepublishInput, serviceId: string): Promise<void> => {
+	const { api, signal } = input
+	const variables = await api.listServiceEnv({ serviceId, signal })
+	if (variables.find(variable => variable.key === SESSION_OWNER_VARIABLE)?.content !== 'null') {
+		await api.putServiceEnv({ serviceId, key: SESSION_OWNER_VARIABLE, value: 'null', signal })
+	}
+	if (variables.find(variable => variable.key === ZEROPS_NAMESPACE_IAM_ISSUER_VARIABLE)?.content !== input.iamUrl) {
+		await api.putServiceEnv({ serviceId, key: ZEROPS_NAMESPACE_IAM_ISSUER_VARIABLE, value: input.iamUrl, signal })
+	}
+	// Secret read-back is not trustworthy, so overwrite it without inspecting its value.
+	await api.putServiceEnv({ serviceId, key: ZEROPS_NAMESPACE_IAM_KEY_VARIABLE, value: input.iamKey, signal })
+}
+
+/**
+ * Rebuild the namespace proxy with `manifest` (ADR-0044). The attempt is recorded as `proxyBuild` and never
+ * resumed: an inherited attempt not yet `triggered` is deleted, a triggered one is polled to a terminal state.
+ * A lost lease deletes nothing; a cancelled deploy leaves a triggered attempt recorded for reconciliation.
+ */
+export async function republishProxy(input: ZeropsProxyRepublishInput): Promise<ZeropsNamespaceTarget> {
+	const pin = input.target.proxySource
+	const serviceId = input.target.proxyServiceId
+	if (serviceId === undefined) throw new Error('Zerops namespace has no proxy service id')
+	await verifyZeropsNamespaceProxySource(pin)
+	const manifest = encodeProxyManifestJson(input.manifest)
+	// The attempt's identity covers the IAM configuration too, so a rotated issuer or key forces a rebuild.
+	const manifestSha256 = await digest(`${manifest}\n${input.iamUrl}\n${await digest(input.iamKey)}`)
+	let target = input.target
+
+	const save = async (next: ZeropsNamespaceTarget): Promise<void> => {
+		await input.checkpoint(next)
+		target = next
+	}
+
+	/** Observe one version until terminal; with `started`, a running build of this manifest is answer enough. */
+	const settle = async (build: ZeropsNamespaceProxyBuild): Promise<'settled' | 'running'> => {
+		const deadline = Date.now() + POLL_DEADLINE_MS
+		for (;;) {
+			await input.boundary()
+			input.signal.throwIfAborted()
+			let version: ZeropsAppVersion
+			try {
+				version = await input.api.getAppVersion({ appVersionId: build.appVersionId, signal: input.signal })
+			} catch {
+				input.signal.throwIfAborted()
+				throw unresolved(build.appVersionId)
+			}
+			if (
+				version.id !== build.appVersionId || (version.serviceStackId !== undefined && version.serviceStackId !== serviceId)
+				|| (version.projectId !== undefined && target.projectId !== undefined && version.projectId !== target.projectId)
+			) throw unresolved(build.appVersionId)
+			if (version.status !== undefined && ZEROPS_TERMINAL.has(version.status)) {
+				const active = version.status === ZEROPS_ACTIVE
+				await save({
+					...target,
+					proxyBuild: undefined,
+					...(active
+						? {
+							proxyDeployment: {
+								appVersionId: version.id,
+								repository: pin.repository,
+								commitSha: pin.commitSha,
+								descriptorSha256: pin.descriptor.sha256,
+								...(build.manifestSha256 === undefined ? {} : { manifestSha256: build.manifestSha256 }),
+							},
+						}
+						: { ready: false }),
+				})
+				if (!active) throw new ProviderNamespaceError(`Proxy version ${version.id} finished as ${version.status}`, 'proxyDeployFailed', false)
+				return 'settled'
+			}
+			if (input.wait === 'started') {
+				if (build.manifestSha256 === manifestSha256 && version.status !== 'UPLOADING') return 'running'
+				throw unresolved(build.appVersionId)
+			}
+			if (Date.now() >= deadline) throw unresolved(build.appVersionId)
+			await input.sleep(POLL_INTERVAL_MS, input.signal)
+		}
+	}
+
+	const inherited = target.proxyBuild
+	if (inherited !== undefined && !inherited.triggered) {
+		input.signal.throwIfAborted()
+		try {
+			await deleteVersion(input.api, inherited.appVersionId, input.signal)
+		} catch {
+			input.signal.throwIfAborted()
+			throw unresolved(inherited.appVersionId)
+		}
+		await save({ ...target, proxyBuild: undefined })
+	} else if (inherited !== undefined) {
+		if (await settle(inherited) === 'running') return target
+		if (inherited.manifestSha256 === manifestSha256) return target
+	}
+
+	if (input.source === undefined) throw new Error('Zerops namespace source client is required')
+	const runId = crypto.randomUUID()
+	const resolved = await input.source.resolve({
+		repository: pin.repository,
+		requestedRef: pin.commitSha,
+		expectedCommitSha: pin.commitSha,
+		descriptorSha256: pin.descriptor.sha256,
+		signal: input.signal,
+	})
+	if (resolved.commitSha !== pin.commitSha || resolved.descriptorSha256 !== pin.descriptor.sha256) {
+		throw new Error('Proxy source resolution identity mismatch')
+	}
+	await input.boundary()
+	await input.api.putServiceEnv({ serviceId, key: FABRIKA_PROXY_MANIFEST_JSON, value: manifest, signal: input.signal })
+	await writeProxyIam(input, serviceId)
+	input.signal.throwIfAborted()
+	const reserved = await input.api.createAppVersion({ serviceId, name: runId, signal: input.signal })
+	let build: ZeropsNamespaceProxyBuild = { appVersionId: reserved.id, triggered: false, manifestSha256 }
+	let accepted = false
+	try {
+		await save({ ...target, proxyBuild: build })
+		input.signal.throwIfAborted()
+		if (!isZeropsUploadDestination(reserved.uploadUrl)) throw new Error(`Proxy version ${reserved.id} has an unexpected upload destination`)
+		const uploaded = await input.source.upload({
+			repository: pin.repository,
+			commitSha: pin.commitSha,
+			descriptorSha256: pin.descriptor.sha256,
+			archive: { kind: 'platform' },
+			uploadUrl: reserved.uploadUrl,
+			signal: input.signal,
+		})
+		if (uploaded.commitSha !== pin.commitSha || uploaded.descriptorSha256 !== pin.descriptor.sha256) {
+			throw new Error('Proxy source upload identity mismatch')
+		}
+		const descriptor = prepareZeropsDescriptor(pin.descriptor.contents, 'proxy')
+		// Once triggered, only a lost lease stops the build request; a cancelled deploy leaves it to reconcile.
+		const buildSignal = followLeaseLoss(input.signal)
+		for (let attempt = 1;; attempt++) {
+			await input.boundary()
+			build = { ...build, triggered: true }
+			await save({ ...target, proxyBuild: build })
+			buildSignal.throwIfAborted()
+			try {
+				const process = await input.api.buildAndDeployAppVersion({
+					appVersionId: reserved.id,
+					zeropsYaml: descriptor.contents,
+					zeropsYamlSetup: 'proxy',
+					signal: buildSignal,
+				})
+				if (process.appVersionId !== undefined && process.appVersionId !== reserved.id) throw unresolved(reserved.id)
+				accepted = true
+				break
+			} catch (cause) {
+				buildSignal.throwIfAborted()
+				if (!(cause instanceof ZeropsApiError && cause.status === 400 && cause.code === 'userDataSyncRunning')) break
+				// A definitive refusal: the version is inert again, so a failure from here deletes it.
+				build = { ...build, triggered: false }
+				await save({ ...target, proxyBuild: build })
+				if (attempt >= USER_DATA_SYNC_ATTEMPTS) {
+					throw new ProviderNamespaceError(`Proxy version ${reserved.id}: service variables are still synchronizing`, 'userDataSyncRunning', true)
+				}
+				await input.sleep(POLL_INTERVAL_MS, input.signal)
+			}
+		}
+	} catch (cause) {
+		if (!build.triggered && !isLeaseLoss(input.signal.reason) && !isLeaseLoss(cause)) {
+			const cleanup = AbortSignal.any([followLeaseLoss(input.signal), AbortSignal.timeout(30_000)])
+			try {
+				await deleteVersion(input.api, reserved.id, cleanup)
+				await save({ ...target, proxyBuild: undefined })
+			} catch {
+				// The recorded attempt is deleted by the next owner.
+			}
+		}
+		throw cause
+	}
+	if (input.wait === 'started' && accepted) return target
+	await settle(build)
+	return target
+}

package/src/namespace/proxy-source.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod'
+import { prepareZeropsDescriptor } from '../descriptor'
+import { verifyZeropsArtifactSourceDescriptor, zeropsArtifactSourceDescriptorSchema } from '../manifest'
+import { commitShaSchema, parseSourceWire, repositorySchema } from '../source/validation'
+import type { ZeropsNamespaceProxySource } from './types'
+
+export const namespaceProxySourceSchema = z.object({
+	repository: repositorySchema,
+	commitSha: commitShaSchema,
+	descriptor: zeropsArtifactSourceDescriptorSchema,
+}).strict().transform((source) => {
+	prepareZeropsDescriptor(source.descriptor.contents, 'proxy')
+	return source
+})
+
+export const decodeZeropsNamespaceProxySource = (value: unknown): ZeropsNamespaceProxySource =>
+	parseSourceWire(namespaceProxySourceSchema, value, 'Zerops namespace proxy source')
+
+export const verifyZeropsNamespaceProxySource = async (source: ZeropsNamespaceProxySource): Promise<void> => {
+	const parsed = decodeZeropsNamespaceProxySource(source)
+	await verifyZeropsArtifactSourceDescriptor(parsed.descriptor)
+}

package/src/namespace/topology.ts

@@ -0,0 +1,115 @@
+import type { ProviderDeploymentNamespace } from '@fabrika/provider-contract'
+import { compileImportYaml, compileProvisioningYaml } from '../compile'
+import type { ZeropsServiceSpec, ZeropsSourceTarget } from '../types'
+import { ZEROPS_NAMESPACE_POSTGRES_HOSTNAME, ZEROPS_NAMESPACE_PROXY_HOSTNAME } from './constants'
+import { decodeZeropsNamespaceProxySource } from './proxy-source'
+import type {
+	ZeropsNamespacePolicy,
+	ZeropsNamespacePostgres,
+	ZeropsNamespacePresetInput,
+	ZeropsNamespacePublicAccess,
+	ZeropsNamespaceTarget,
+	ZeropsNamespaceTopology,
+} from './types'
+
+export const PROXY_TYPE = 'alpine@3.21'
+
+/**
+ * The namespace-owned PostgreSQL service: the cheapest shape that runs, on EVERY environment.
+ *
+ * A profile sets the FLOOR and the tuning preset, never the cap — `oltp-hobby` and `oltp-production`
+ * share the same 8-core / 48 GB / 250 GB ceiling and the same vertical autoscaler, so the production
+ * preset does not buy headroom, it buys an idle bill. `oltp-hobby` starts at one SHARED core and
+ * 0.25 GB and grows under load; the shape is proven by a live app with dozens of tables.
+ *
+ * Keying this off `env === 'prod'` is what this default used to do, and it was wrong: most apps are
+ * small on every environment they have, and a name is not a size. HA and a bigger floor stay
+ * available and become a DELIBERATE act — `--postgres-type` and `--postgres-profile` on the namespace
+ * command — because the failure mode of over-provisioning is silent and monthly, while the failure
+ * mode of under-provisioning is visible and fixable at any time.
+ *
+ * Omitting `profile` would not be neutral: an HA service silently gets `oltp-production` (two
+ * DEDICATED cores and 4 GB per container, three containers) and a single one `oltp-staging`. Both
+ * read back off a live service.
+ */
+const defaultPostgres = (): ZeropsNamespacePostgres => ({ type: 'postgresql:single@18', profile: 'oltp-hobby' })
+
+/** A preset's project and service policy, without the proxy source pin (ADR-0045). */
+export const zeropsNamespacePolicy = (input: Omit<ZeropsNamespacePresetInput, 'proxySource'>): ZeropsNamespacePolicy => ({
+	projectName: input.projectName,
+	// `LIGHT` on every environment. An APP namespace is not the platform project — the argument for
+	// `SERIOUS` in the platform installation topology is that the platform repairs the apps project, which no app
+	// namespace does. `corePackage` is upgrade-only, so this stays the caller's explicit choice.
+	corePackage: input.corePackage ?? 'LIGHT',
+	publicAccess: input.publicAccess ?? 'custom-domain',
+	managed: true,
+	ready: false,
+	...(input.preset === 'cheap' ? { postgres: input.postgres ?? defaultPostgres() } : {}),
+})
+
+export const zeropsNamespacePreset = (input: ZeropsNamespacePresetInput): ZeropsNamespaceTarget => ({
+	proxySource: decodeZeropsNamespaceProxySource(input.proxySource),
+	...zeropsNamespacePolicy(input),
+})
+
+export const projectMarker = (namespace: ProviderDeploymentNamespace): string => `Managed by Fabrika namespace ${namespace.id} (${namespace.env}).`
+
+// Imports provision services only. The reserved upload-backed build selects the proxy setup.
+//
+// `enableSubdomainAccess` is a DECLARATION here and not a mechanism: the platform accepts it and drops it,
+// including on the service this document creates. `ensureSubdomainAccess` below is what establishes the
+// subdomain, after the proxy's first deploy. Written anyway because it is what ADR-0022's
+// `assertOnlyPublicService` reads to prove no other service is claimed public.
+const proxyService = (publicAccess: ZeropsNamespacePublicAccess): ZeropsServiceSpec => ({
+	hostname: ZEROPS_NAMESPACE_PROXY_HOSTNAME,
+	type: PROXY_TYPE,
+	priority: 10,
+	enableSubdomainAccess: publicAccess === 'zerops-subdomain',
+	// One container is a real availability trade — the proxy is the only enforcement point (ADR-0022),
+	// so a restart is a short outage rather than a rolling one — taken because it is a whole core of
+	// idle floor on every namespace, and most namespaces hold one small app. `maxContainers` is
+	// unchanged, so load still scales out.
+	minContainers: 1,
+	maxContainers: 6,
+})
+
+const postgresService = (postgres: ZeropsNamespacePostgres): ZeropsServiceSpec => ({
+	hostname: ZEROPS_NAMESPACE_POSTGRES_HOSTNAME,
+	type: postgres.type,
+	priority: 100,
+	...(postgres.profile !== undefined ? { profile: postgres.profile } : {}),
+})
+
+/** Compile the one project and its namespace-owned services without depending on private deploy code. */
+export const compileZeropsNamespaceTopology = (
+	namespace: ProviderDeploymentNamespace,
+	target: ZeropsNamespacePolicy,
+): ZeropsNamespaceTopology => {
+	const projectName = target.projectName
+	const corePackage = target.corePackage
+	const publicAccess = target.publicAccess
+	if (projectName === undefined || corePackage === undefined || publicAccess === undefined) {
+		throw new Error('Zerops namespace topology requires normalized project policy')
+	}
+	const services = (): ZeropsServiceSpec[] => [
+		...(target.postgres === undefined ? [] : [postgresService(target.postgres)]),
+		proxyService(publicAccess),
+	]
+	const source: ZeropsSourceTarget = {
+		platform: 'zerops',
+		project: {
+			name: projectName,
+			description: projectMarker(namespace),
+			corePackage,
+			tags: ['fabrika', 'namespace', namespace.id, namespace.env],
+		},
+		services,
+	}
+	const serviceSource: ZeropsSourceTarget = { platform: 'zerops', services }
+	return {
+		source,
+		createYaml: compileImportYaml({ target: source, ctx: { env: namespace.env } }).yaml,
+		servicesProvisionYaml: compileProvisioningYaml({ target: serviceSource, ctx: { env: namespace.env } }).yaml,
+		servicesSteadyYaml: compileImportYaml({ target: serviceSource, ctx: { env: namespace.env } }).yaml,
+	}
+}

package/src/namespace/types.ts

@@ -0,0 +1,114 @@
+import type { ProviderNamespaceHost } from '@fabrika/provider-contract'
+import type { ZeropsApi, ZeropsProjectMode } from '../api'
+import type { Sleeper } from '../collaborators'
+import type { ZeropsArtifactSourceDescriptor } from '../manifest'
+import type { ZeropsSourceRepository } from '../source'
+import type { ZeropsSourcePort } from '../source/port'
+import type { ZeropsSourceTarget } from '../types'
+
+export type ZeropsNamespacePublicAccess = 'custom-domain' | 'zerops-subdomain'
+
+export interface ZeropsNamespaceProxySource {
+	readonly repository: ZeropsSourceRepository
+	readonly commitSha: string
+	readonly descriptor: ZeropsArtifactSourceDescriptor
+}
+
+/** The proxy attempt in flight (ADR-0044): a version not `triggered` is deleted, a triggered one is polled. */
+export interface ZeropsNamespaceProxyBuild {
+	readonly appVersionId: string
+	readonly triggered: boolean
+	readonly manifestSha256?: string
+}
+
+export interface ZeropsNamespaceProxyDeployment {
+	readonly manifestSha256?: string
+	readonly appVersionId: string
+	readonly repository: ZeropsSourceRepository
+	readonly commitSha: string
+	readonly descriptorSha256: string
+}
+
+export type ZeropsNamespacePostgres =
+	| {
+		readonly type: 'postgresql:ha@18'
+		readonly profile?: 'oltp-staging' | 'oltp-production' | 'oltp-enterprise' | 'olap-production' | 'writeheavy-production'
+	}
+	| {
+		readonly type: 'postgresql:single@18'
+		readonly profile?: 'oltp-hobby' | 'oltp-staging' | 'oltp-production' | 'olap-production' | 'writeheavy-production'
+	}
+
+/**
+ * Provider-owned namespace state. Optional fields are durable progress checkpoints; values that are
+ * absent are resolved by `normalize()` before a mutation starts.
+ */
+export interface ZeropsNamespaceTarget {
+	readonly proxySource: ZeropsNamespaceProxySource
+	readonly proxyBuild?: ZeropsNamespaceProxyBuild
+	readonly proxyDeployment?: ZeropsNamespaceProxyDeployment
+	readonly projectName?: string
+	readonly corePackage?: ZeropsProjectMode
+	readonly publicAccess?: ZeropsNamespacePublicAccess
+	readonly postgres?: ZeropsNamespacePostgres
+	readonly managed?: boolean
+	readonly projectId?: string
+	readonly proxyServiceId?: string
+	readonly postgresServiceId?: string
+	readonly proxyConfigured?: boolean
+	readonly proxyBaselineSequence?: number
+	readonly proxyAppVersionId?: string
+	/** The hosts the published proxy answers on, recorded once so a namespace read needs no platform call. */
+	readonly proxyHosts?: readonly ProviderNamespaceHost[]
+	readonly ready?: boolean
+}
+
+export type ZeropsNamespacePolicy = Omit<ZeropsNamespaceTarget, 'proxySource'>
+
+export interface NormalizedZeropsNamespaceTarget extends ZeropsNamespaceTarget {
+	readonly projectName: string
+	readonly corePackage: ZeropsProjectMode
+	readonly publicAccess: ZeropsNamespacePublicAccess
+	readonly managed: boolean
+	readonly ready: boolean
+}
+
+export interface ZeropsNamespaceOptions {
+	readonly proxySource: ZeropsNamespaceProxySource
+	readonly source?: ZeropsSourcePort
+	readonly clientId: string
+	/** Public IAM origin reachable from an app project. */
+	readonly iamUrl: string
+	/** Same credential IAM receives as `FABRIKA_IAM_PROXY_KEY`. */
+	readonly iamKey: string
+	readonly api: ZeropsApi
+	readonly sleep?: Sleeper
+}
+
+export interface ZeropsNamespaceTopology {
+	readonly source: ZeropsSourceTarget
+	readonly createYaml: string
+	readonly servicesProvisionYaml: string
+	readonly servicesSteadyYaml: string
+}
+
+export interface ZeropsNamespacePresetInput {
+	readonly proxySource: ZeropsNamespaceProxySource
+	readonly preset: 'cheap' | 'mid' | 'full'
+	readonly env: string
+	readonly projectName: string
+	readonly corePackage?: ZeropsProjectMode
+	readonly publicAccess?: ZeropsNamespacePublicAccess
+	readonly postgres?: ZeropsNamespacePostgres
+}
+
+export interface ZeropsNamespaceOperatorOptions {
+	readonly proxySource: ZeropsNamespaceProxySource
+}
+
+export interface ZeropsNamespacePlanOptions {
+	readonly projectName?: string
+	readonly corePackage?: ZeropsProjectMode
+	readonly publicAccess?: ZeropsNamespacePublicAccess
+	readonly postgres?: ZeropsNamespacePostgres
+}