@fabrika/provider-zerops 0.9.0-dev.13 → 0.9.0-dev.14
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.
- package/package.json +10 -10
- package/src/api/client.ts +8 -0
- package/src/api/readers.ts +12 -0
- package/src/api/types.ts +33 -0
- package/src/api.ts +2 -0
- package/src/build-base.ts +117 -0
- package/src/cli.ts +20 -5
- package/src/collaborators.ts +11 -0
- package/src/control.ts +3 -0
- package/src/index.ts +1 -0
- package/src/installation/admin.ts +6 -1
- package/src/installation/generated/platform-proxy-manifest.ts +80 -0
- package/src/installation/guide.md +90 -12
- package/src/installation/index.ts +9 -1
- package/src/installation/install-environment.ts +4 -0
- package/src/installation/install-options.ts +40 -0
- package/src/installation/install.ts +18 -2
- package/src/installation/templates/README.md +1 -1
- package/src/plan.ts +14 -2
- package/src/provider.ts +160 -2
- package/types/src/api/readers.d.ts +46 -1
- package/types/src/api/types.d.ts +36 -0
- package/types/src/api.d.ts +1 -1
- package/types/src/build-base.d.ts +27 -0
- package/types/src/cli.d.ts +8 -1
- package/types/src/collaborators.d.ts +9 -0
- package/types/src/index.d.ts +1 -0
- package/types/src/installation/install-environment.d.ts +3 -1
- package/types/src/installation/install-options.d.ts +3 -1
- package/types/src/installation/topology/installation-schemas.d.ts +14 -14
- package/types/src/namespace/codec.d.ts +2 -2
- package/types/src/plan.d.ts +9 -3
- package/types/src/provider.d.ts +43 -2
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fabrika/provider-zerops",
|
|
3
|
-
"version": "0.9.0-dev.
|
|
3
|
+
"version": "0.9.0-dev.14",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -45,15 +45,15 @@
|
|
|
45
45
|
},
|
|
46
46
|
"dependencies": {
|
|
47
47
|
"zod": "^3.25.76",
|
|
48
|
-
"@fabrika/app": "0.9.0-dev.
|
|
49
|
-
"@fabrika/auth": "0.9.0-dev.
|
|
50
|
-
"@fabrika/auth-core": "0.9.0-dev.
|
|
51
|
-
"@fabrika/email": "0.9.0-dev.
|
|
52
|
-
"@fabrika/iam-contract": "0.9.0-dev.
|
|
53
|
-
"@fabrika/installation-init": "0.9.0-dev.
|
|
54
|
-
"@fabrika/operations-contract": "0.9.0-dev.
|
|
55
|
-
"@fabrika/provider-contract": "0.9.0-dev.
|
|
56
|
-
"@fabrika/proxy-core": "0.9.0-dev.
|
|
48
|
+
"@fabrika/app": "0.9.0-dev.14",
|
|
49
|
+
"@fabrika/auth": "0.9.0-dev.14",
|
|
50
|
+
"@fabrika/auth-core": "0.9.0-dev.14",
|
|
51
|
+
"@fabrika/email": "0.9.0-dev.14",
|
|
52
|
+
"@fabrika/iam-contract": "0.9.0-dev.14",
|
|
53
|
+
"@fabrika/installation-init": "0.9.0-dev.14",
|
|
54
|
+
"@fabrika/operations-contract": "0.9.0-dev.14",
|
|
55
|
+
"@fabrika/provider-contract": "0.9.0-dev.14",
|
|
56
|
+
"@fabrika/proxy-core": "0.9.0-dev.14",
|
|
57
57
|
"yaml": "^2.9.1"
|
|
58
58
|
}
|
|
59
59
|
}
|
package/src/api/client.ts
CHANGED
|
@@ -6,6 +6,8 @@ import {
|
|
|
6
6
|
appVersionListSchema,
|
|
7
7
|
appVersionSchema,
|
|
8
8
|
backupConfigSchema,
|
|
9
|
+
backupFilesSchema,
|
|
10
|
+
backupStartSchema,
|
|
9
11
|
importResultSchema,
|
|
10
12
|
integrationTokenSchema,
|
|
11
13
|
logAccessSchema,
|
|
@@ -382,6 +384,12 @@ export const createZeropsApi = (options: ZeropsApiOptions): ZeropsApi => {
|
|
|
382
384
|
return readResponse('configure backup', processNilSchema, payload).process ?? null
|
|
383
385
|
},
|
|
384
386
|
|
|
387
|
+
createBackup: async ({ serviceId, tags, signal }) =>
|
|
388
|
+
readResponse('back up', backupStartSchema, await request('back up', 'POST', `/service-stack/${serviceId}/backup`, { body: { tags }, signal })),
|
|
389
|
+
|
|
390
|
+
listBackups: async ({ serviceId, signal }) =>
|
|
391
|
+
readResponse('list backups', backupFilesSchema, await request('list backups', 'GET', `/service-stack/${serviceId}/backup`, { signal })),
|
|
392
|
+
|
|
385
393
|
getService: async ({ serviceId, signal }) =>
|
|
386
394
|
readResponse('get service', serviceSchema, await request('get service', 'GET', `/service-stack/${serviceId}`, { signal })),
|
|
387
395
|
|
package/src/api/readers.ts
CHANGED
|
@@ -4,7 +4,9 @@ import type {
|
|
|
4
4
|
ZeropsAppVersion,
|
|
5
5
|
ZeropsAppVersionStatus,
|
|
6
6
|
ZeropsBackupConfig,
|
|
7
|
+
ZeropsBackupFile,
|
|
7
8
|
ZeropsBackupRetentionPolicy,
|
|
9
|
+
ZeropsBackupStart,
|
|
8
10
|
ZeropsImportResult,
|
|
9
11
|
ZeropsIntegrationToken,
|
|
10
12
|
ZeropsLogAccess,
|
|
@@ -199,6 +201,16 @@ export const backupConfigSchema = z.object({
|
|
|
199
201
|
...(retentionPolicy === null || retentionPolicy === undefined ? {} : { retentionPolicy }),
|
|
200
202
|
}))
|
|
201
203
|
|
|
204
|
+
/** A file whose tags do not parse has none: a backup is looked for by its tag, so it is never taken for one. */
|
|
205
|
+
const backupFileSchema = z.object({
|
|
206
|
+
name: z.string(),
|
|
207
|
+
metadata: z.object({ tags: z.array(z.string()).catch([]).optional() }).nullish().catch(null),
|
|
208
|
+
}).transform(({ name, metadata }): ZeropsBackupFile => ({ name, tags: metadata?.tags ?? [] }))
|
|
209
|
+
|
|
210
|
+
export const backupFilesSchema = z.object({ files: z.array(backupFileSchema).nullable() }).transform(({ files }) => files ?? [])
|
|
211
|
+
|
|
212
|
+
export const backupStartSchema = z.object({ success: z.boolean(), async: z.boolean() }) satisfies z.ZodType<ZeropsBackupStart, z.ZodTypeDef, unknown>
|
|
213
|
+
|
|
202
214
|
export const projectSchema = z.object({
|
|
203
215
|
id: idSchema,
|
|
204
216
|
name: z.string(),
|
package/src/api/types.ts
CHANGED
|
@@ -224,6 +224,25 @@ export interface ZeropsBackupConfig {
|
|
|
224
224
|
retentionPolicy?: ZeropsBackupRetentionPolicy
|
|
225
225
|
}
|
|
226
226
|
|
|
227
|
+
/**
|
|
228
|
+
* One stored backup of a managed service: `OutDtoServiceStackBackupFile`, narrowed to its `name` and the `tags` of its
|
|
229
|
+
* `metadata`. Verified live 2026-11-17: `metadata.tags` is a JSON array of strings, and the metadata keys are snake_case
|
|
230
|
+
* (`file_name`, `stack_name`), not the documented `filename` and `stackname`.
|
|
231
|
+
*/
|
|
232
|
+
export interface ZeropsBackupFile {
|
|
233
|
+
/** The moment the backup was taken, as the platform names the file. */
|
|
234
|
+
name: string
|
|
235
|
+
tags: string[]
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
/** What a backup request answers. VERIFIED AS A SHAPE: `ResponseServiceStackBackup`. */
|
|
239
|
+
export interface ZeropsBackupStart {
|
|
240
|
+
/** The backup was started, and is finished or running in the background. */
|
|
241
|
+
success: boolean
|
|
242
|
+
/** It ran past the platform's 10 s window and goes on in the background; `false` answers a finished backup. */
|
|
243
|
+
async: boolean
|
|
244
|
+
}
|
|
245
|
+
|
|
227
246
|
/** One service. VERIFIED: `ResponseServiceStack` (narrowed to the fields fabrika reads). */
|
|
228
247
|
export interface ZeropsService {
|
|
229
248
|
id: string
|
|
@@ -558,6 +577,20 @@ export interface ZeropsApi {
|
|
|
558
577
|
signal: AbortSignal
|
|
559
578
|
}): Promise<ZeropsProcess | null>
|
|
560
579
|
|
|
580
|
+
/**
|
|
581
|
+
* Back a managed service up now, under `tags`. VERIFIED AS A SHAPE: `POST /service-stack/{id}/backup`
|
|
582
|
+
* (`BackupServiceStack`), body `RequestPostServiceStackBackup`, response `ResponseServiceStackBackup`. It names no
|
|
583
|
+
* process. Verified live 2026-11-17: `async: false` answers a finished backup, listed at once; a user tag outside 1–24
|
|
584
|
+
* characters of `[A-Za-z0-9:_-]` is 400 `backupTagNameFormat`.
|
|
585
|
+
*/
|
|
586
|
+
createBackup(input: { serviceId: string; tags: string[]; signal: AbortSignal }): Promise<ZeropsBackupStart>
|
|
587
|
+
|
|
588
|
+
/**
|
|
589
|
+
* The stored backups of a managed service. VERIFIED AS A SHAPE: the `files` of `GET /service-stack/{id}/backup`
|
|
590
|
+
* (`ListBackups`). UNVERIFIED: whether a backup still running (`async: true`) is listed before it completes.
|
|
591
|
+
*/
|
|
592
|
+
listBackups(input: { serviceId: string; signal: AbortSignal }): Promise<ZeropsBackupFile[]>
|
|
593
|
+
|
|
561
594
|
// ── service-stack / project: reading state ────────────────────────────────────
|
|
562
595
|
|
|
563
596
|
/** One service by id. VERIFIED: `GET /service-stack/{id}`. */
|
package/src/api.ts
CHANGED
|
@@ -20,7 +20,9 @@ export {
|
|
|
20
20
|
type ZeropsAppVersionStatus,
|
|
21
21
|
type ZeropsAppVersionUpload,
|
|
22
22
|
type ZeropsBackupConfig,
|
|
23
|
+
type ZeropsBackupFile,
|
|
23
24
|
type ZeropsBackupRetentionPolicy,
|
|
25
|
+
type ZeropsBackupStart,
|
|
24
26
|
type ZeropsImportedService,
|
|
25
27
|
type ZeropsImportResult,
|
|
26
28
|
type ZeropsIntegrationToken,
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
// Whether the Bun of a contract application's build base reads its `bun.lock`. The platform build installs with
|
|
2
|
+
// `bun install --frozen-lockfile` on the base the selected setup names in `build.base` (ADR-0043), and a Bun older than
|
|
3
|
+
// the one that wrote the lockfile fails that install late, in a started build container, with `Unknown lockfile
|
|
4
|
+
// version`. `fabrika app build`, `app register` and the builder's deploy refuse such a base before anything deploys,
|
|
5
|
+
// from the lockfile they compile beside; a commit after registration is not checked. PURE: no filesystem.
|
|
6
|
+
|
|
7
|
+
import type { JsonValue } from '@fabrika/provider-contract'
|
|
8
|
+
import { parseZeropsDescriptor, selectZeropsDescriptorSetup } from './descriptor'
|
|
9
|
+
import { lockedAuthoredBuild, ZEROPS_APPLICATION_RUNTIME } from './execution'
|
|
10
|
+
import type { FabrikaManifest } from './manifest'
|
|
11
|
+
|
|
12
|
+
interface BunRelease {
|
|
13
|
+
readonly major: number
|
|
14
|
+
readonly minor: number
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* The oldest Bun that reads each `lockfileVersion` of a text `bun.lock` (measured: 1.1.45 reads 0 and refuses 1, 1.2
|
|
19
|
+
* and 1.3 read 1 and refuse 2, 1.4 writes 2 for a new lockfile). A version missing here is newer than every Bun this
|
|
20
|
+
* list knows. Add a row when a Bun release writes a new version.
|
|
21
|
+
*/
|
|
22
|
+
const LOCKFILE_READERS: ReadonlyMap<number, BunRelease> = new Map([
|
|
23
|
+
[0, { major: 1, minor: 1 }],
|
|
24
|
+
[1, { major: 1, minor: 2 }],
|
|
25
|
+
[2, { major: 1, minor: 4 }],
|
|
26
|
+
])
|
|
27
|
+
|
|
28
|
+
/** The oldest Bun base Zerops offers (`alpine/bun@1.3`, `ubuntu/bun@1.3`): a refusal never names an older one. */
|
|
29
|
+
const OLDEST_OFFERED_BUN: BunRelease = { major: 1, minor: 3 }
|
|
30
|
+
|
|
31
|
+
/** The newest Bun the table knows: it writes the newest `lockfileVersion` there, and reads no newer one. */
|
|
32
|
+
const NEWEST_KNOWN_BUN: BunRelease = { major: 1, minor: 4 }
|
|
33
|
+
const NEWEST_KNOWN_LOCKFILE = Math.max(...LOCKFILE_READERS.keys())
|
|
34
|
+
|
|
35
|
+
/** A Bun base with a numeric version: `bun@1.3`, `alpine/bun@1.3`, `ubuntu/bun@1.3.9`. An alias such as `@latest` is not. */
|
|
36
|
+
const BUN_BASE = /^((?:alpine|ubuntu)\/)?bun@(\d+)\.(\d+)(?:\.\d+)?$/
|
|
37
|
+
|
|
38
|
+
const atLeast = (release: BunRelease, floor: BunRelease): boolean =>
|
|
39
|
+
release.major > floor.major || (release.major === floor.major && release.minor >= floor.minor)
|
|
40
|
+
|
|
41
|
+
const named = (release: BunRelease): string => `${release.major}.${release.minor}`
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* The `lockfileVersion` of a `bun.lock`, or null when the text does not start with one. Bun writes it as the first
|
|
45
|
+
* key; the rest of the file is JSONC (trailing commas), which this never parses.
|
|
46
|
+
*/
|
|
47
|
+
export function bunLockfileVersion(text: string): number | null {
|
|
48
|
+
const unmarked = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text
|
|
49
|
+
const match = /^\s*\{\s*"lockfileVersion"\s*:\s*(\d+)\s*[,}]/.exec(unmarked)
|
|
50
|
+
return match?.[1] === undefined ? null : Number(match[1])
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** The build base of the manifest's selected setup, and whether the application named it or the platform's default applies. */
|
|
54
|
+
export interface ZeropsBuildBase {
|
|
55
|
+
readonly setup: string
|
|
56
|
+
/** Each base the build image is made of; empty for an application without a contract, whose build is its own. */
|
|
57
|
+
readonly bases: readonly string[]
|
|
58
|
+
readonly authored: boolean
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
const isSetup = (value: JsonValue, setup: string): value is { readonly [key: string]: JsonValue } =>
|
|
62
|
+
typeof value === 'object' && value !== null && !Array.isArray(value) && value['setup'] === setup
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* The bases the platform build of a contract application runs on, read as `renderLockedSetup` reads them: the selected
|
|
66
|
+
* setup's `build.base`, or the platform's runtime when it names none. The platform does not generate the build of an
|
|
67
|
+
* application without a contract, so it has none here.
|
|
68
|
+
*/
|
|
69
|
+
export function zeropsBuildBase(manifest: FabrikaManifest): ZeropsBuildBase {
|
|
70
|
+
const parsed = parseZeropsDescriptor(manifest.target.sourceDescriptor.contents)
|
|
71
|
+
const setup = selectZeropsDescriptorSetup(parsed, manifest.target.zeropsSetup)
|
|
72
|
+
const entries = parsed.document['zerops']
|
|
73
|
+
const entry = Array.isArray(entries) ? entries.find((candidate) => isSetup(candidate, setup)) : undefined
|
|
74
|
+
if (manifest.target.contract === undefined || entry === undefined) return { setup, bases: [], authored: false }
|
|
75
|
+
const base = lockedAuthoredBuild(entry, setup).base
|
|
76
|
+
if (base === null) return { setup, bases: [ZEROPS_APPLICATION_RUNTIME], authored: false }
|
|
77
|
+
return { setup, bases: typeof base === 'string' ? [base] : base, authored: true }
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Why the build cannot install from a `bun.lock` of this text, or null when it can or when that cannot be known: a
|
|
82
|
+
* lockfile without a readable version, or a base that is not a Bun release with a numeric version (an alias such as
|
|
83
|
+
* `alpine/bun@latest`, or another runtime).
|
|
84
|
+
*/
|
|
85
|
+
export function buildBaseLockfileRefusal(lockfile: string, build: ZeropsBuildBase): string | null {
|
|
86
|
+
const version = bunLockfileVersion(lockfile)
|
|
87
|
+
if (version === null) return null
|
|
88
|
+
const reader = LOCKFILE_READERS.get(version)
|
|
89
|
+
for (const base of build.bases) {
|
|
90
|
+
const match = BUN_BASE.exec(base)
|
|
91
|
+
if (match === null) continue
|
|
92
|
+
const bun = { major: Number(match[2]), minor: Number(match[3]) }
|
|
93
|
+
const where = build.authored
|
|
94
|
+
? `build.base \`${base}\` of zerops.yaml setup \`${build.setup}\``
|
|
95
|
+
: `\`${base}\`, the base of zerops.yaml setup \`${build.setup}\`, which names no build.base`
|
|
96
|
+
const install = `the platform build runs \`bun install --frozen-lockfile\` on ${where}`
|
|
97
|
+
if (reader === undefined) {
|
|
98
|
+
// A Bun newer than every known one may read it; only a known one is refused.
|
|
99
|
+
if (atLeast(NEWEST_KNOWN_BUN, bun)) {
|
|
100
|
+
const known = `Bun ${named(NEWEST_KNOWN_BUN)} reads up to lockfileVersion ${NEWEST_KNOWN_LOCKFILE}`
|
|
101
|
+
return `bun.lock has lockfileVersion ${version}, newer than any Bun base this release knows (${known}), and ${install}; set build.base to the Bun release that wrote bun.lock (\`bun --version\`)`
|
|
102
|
+
}
|
|
103
|
+
continue
|
|
104
|
+
}
|
|
105
|
+
if (!atLeast(bun, reader)) {
|
|
106
|
+
const remedy = `${match[1] ?? ''}bun@${named(atLeast(reader, OLDEST_OFFERED_BUN) ? reader : OLDEST_OFFERED_BUN)}`
|
|
107
|
+
return `bun.lock has lockfileVersion ${version}, which Bun ${
|
|
108
|
+
named(bun)
|
|
109
|
+
} cannot read, and ${install}; set build.base: ${remedy}, or regenerate bun.lock with Bun ${named(bun)}, which resolves every dependency afresh`
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
return null
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/** Why the manifest's build cannot install from a `bun.lock` of this text, or null; what every compile runs. */
|
|
116
|
+
export const lockfileBuildBaseRefusal = (manifest: FabrikaManifest, lockfile: string): string | null =>
|
|
117
|
+
buildBaseLockfileRefusal(lockfile, zeropsBuildBase(manifest))
|
package/src/cli.ts
CHANGED
|
@@ -5,6 +5,7 @@ import { open } from 'node:fs/promises'
|
|
|
5
5
|
import { resolve } from 'node:path'
|
|
6
6
|
import { z } from 'zod'
|
|
7
7
|
import { isZeropsAppConfig } from './authoring'
|
|
8
|
+
import { lockfileBuildBaseRefusal } from './build-base'
|
|
8
9
|
import { parseZeropsCliArgs } from './cli-args'
|
|
9
10
|
import {
|
|
10
11
|
compileFabrikaManifest,
|
|
@@ -78,17 +79,31 @@ export interface ZeropsManifestBuildOptions {
|
|
|
78
79
|
readonly env: string
|
|
79
80
|
}
|
|
80
81
|
|
|
81
|
-
|
|
82
|
+
/**
|
|
83
|
+
* Refuse a build base whose Bun cannot read the repository-root `bun.lock`, which the platform build installs from with
|
|
84
|
+
* `--frozen-lockfile`. Without a `bun.lock` there is nothing to compare; Control refuses a commit without one. `command`
|
|
85
|
+
* names what ran, as the refusal's prefix.
|
|
86
|
+
*/
|
|
87
|
+
export const assertBuildBaseReadsLockfile = async (manifest: FabrikaManifest, command: string, root: string = process.cwd()): Promise<void> => {
|
|
88
|
+
const lockfile = Bun.file(resolve(root, 'bun.lock'))
|
|
89
|
+
if (!(await lockfile.exists())) return
|
|
90
|
+
const refusal = lockfileBuildBaseRefusal(manifest, await lockfile.text())
|
|
91
|
+
if (refusal !== null) throw new Error(`${command}: ${refusal}`)
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
const compileManifest = async (options: ZeropsManifestBuildOptions, command: string): Promise<FabrikaManifest> => {
|
|
82
95
|
const config = await loadConfig(options.config)
|
|
83
96
|
const sourceDescriptor = await readZeropsSourceDescriptor()
|
|
84
|
-
|
|
97
|
+
const manifest = compileFabrikaManifest(config, options.env, sourceDescriptor)
|
|
98
|
+
await assertBuildBaseReadsLockfile(manifest, command)
|
|
99
|
+
return manifest
|
|
85
100
|
}
|
|
86
101
|
|
|
87
102
|
const serializeManifest = (manifest: FabrikaManifest): string => `${JSON.stringify(manifest, null, '\t')}\n`
|
|
88
103
|
|
|
89
|
-
/** The exact text `build` writes to `fabrika.manifest.json`, produced in memory and written nowhere. */
|
|
104
|
+
/** The exact text `build` writes to `fabrika.manifest.json`, produced in memory and written nowhere: what `app register` sends. */
|
|
90
105
|
export const buildZeropsManifestText = async (options: ZeropsManifestBuildOptions): Promise<string> =>
|
|
91
|
-
serializeManifest(await compileManifest(options))
|
|
106
|
+
serializeManifest(await compileManifest(options, 'fabrika app register'))
|
|
92
107
|
|
|
93
108
|
export const runZeropsCli = async (argv: readonly string[]): Promise<void> => {
|
|
94
109
|
const args = parseZeropsCliArgs(argv)
|
|
@@ -102,7 +117,7 @@ export const runZeropsCli = async (argv: readonly string[]): Promise<void> => {
|
|
|
102
117
|
if (args.env === undefined || args.env === '') {
|
|
103
118
|
throw new Error('`build` requires --env=<env>')
|
|
104
119
|
}
|
|
105
|
-
const manifest = await compileManifest({ config: args.config, env: args.env })
|
|
120
|
+
const manifest = await compileManifest({ config: args.config, env: args.env }, 'fabrika app build')
|
|
106
121
|
const output = resolve(process.cwd(), args.output)
|
|
107
122
|
await Bun.write(output, serializeManifest(manifest))
|
|
108
123
|
console.info(`wrote ${output} (${manifestServiceHostnames(manifest).length} service(s))`)
|
package/src/collaborators.ts
CHANGED
|
@@ -5,6 +5,15 @@ import type { ZeropsRuntimeTarget } from './types'
|
|
|
5
5
|
|
|
6
6
|
export type Sleeper = (ms: number, signal: AbortSignal) => Promise<void>
|
|
7
7
|
|
|
8
|
+
/** Elapsed time and the per-request timeouts measured on it. */
|
|
9
|
+
export interface ZeropsClock {
|
|
10
|
+
now(): number
|
|
11
|
+
/** A signal that aborts `ms` from now. */
|
|
12
|
+
timeout(ms: number): AbortSignal
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
export const systemClock: ZeropsClock = { now: () => Date.now(), timeout: (ms) => AbortSignal.timeout(ms) }
|
|
16
|
+
|
|
8
17
|
export const defaultSleep: Sleeper = (ms, signal) =>
|
|
9
18
|
new Promise<void>((resolve) => {
|
|
10
19
|
if (signal.aborted) {
|
|
@@ -29,6 +38,8 @@ export interface ZeropsCollaborators {
|
|
|
29
38
|
/** Raises the Operations alert for a refused activation; best-effort. */
|
|
30
39
|
alertExposure: ExposureAlerter
|
|
31
40
|
sleep: Sleeper
|
|
41
|
+
/** The clock the database backup's wait runs on; the system clock when absent. */
|
|
42
|
+
clock?: ZeropsClock
|
|
32
43
|
}
|
|
33
44
|
|
|
34
45
|
export type ZeropsCollaboratorFactory = (target: ZeropsRuntimeTarget) => ZeropsCollaborators
|
package/src/control.ts
CHANGED
|
@@ -475,6 +475,9 @@ export const createZeropsControlProvider = (options: ZeropsControlProviderOption
|
|
|
475
475
|
artifact,
|
|
476
476
|
...(input.environment.access === undefined ? {} : { access: input.environment.access }),
|
|
477
477
|
...(input.artifactUpload === undefined ? {} : { artifactUpload: input.artifactUpload }),
|
|
478
|
+
...(input.backupBeforeMigrations === undefined
|
|
479
|
+
? {}
|
|
480
|
+
: { backupBeforeMigrations: { migrations: input.backupBeforeMigrations.migrations, runId: input.runId } }),
|
|
478
481
|
dryRun: input.dryRun,
|
|
479
482
|
signal: input.signal,
|
|
480
483
|
events: input.events,
|
package/src/index.ts
CHANGED
|
@@ -40,6 +40,7 @@ export type {
|
|
|
40
40
|
} from './api'
|
|
41
41
|
export { defineApp, isZeropsAppConfig, useSharedPostgres, zeropsSharedServiceHostname, zeropsSharedServicePrefix } from './authoring'
|
|
42
42
|
export type { ZeropsAuthoredAppConfig } from './authoring'
|
|
43
|
+
export { lockfileBuildBaseRefusal } from './build-base'
|
|
43
44
|
export { parseZeropsCliArgs } from './cli-args'
|
|
44
45
|
export type { ZeropsCliArgs } from './cli-args'
|
|
45
46
|
export { defaultSleep, defaultZeropsCollaborators } from './collaborators'
|
|
@@ -96,7 +96,7 @@ const report = (result: FirstAdministratorResult, log: AdminLog): void => {
|
|
|
96
96
|
* The one place the enrollment URL is ever written, and it is written once.
|
|
97
97
|
*
|
|
98
98
|
* A URL that sets a password is a credential: it goes to stdout on a line of its own, is stored
|
|
99
|
-
* nowhere, and is not repeated. The
|
|
99
|
+
* nowhere, and is not repeated. The other outcomes carry no URL at all and say what was found.
|
|
100
100
|
*/
|
|
101
101
|
const announceEnrollment = (result: FirstAdministratorResult, log: AdminLog, print: (line: string) => void): void => {
|
|
102
102
|
if (result.enrollment.state === 'already-set') {
|
|
@@ -104,6 +104,11 @@ const announceEnrollment = (result: FirstAdministratorResult, log: AdminLog, pri
|
|
|
104
104
|
log.info('Sign in at the console. A forgotten password is a reset, which the Access plane issues to a signed-in administrator.')
|
|
105
105
|
return
|
|
106
106
|
}
|
|
107
|
+
if (result.enrollment.state === 'single-sign-on') {
|
|
108
|
+
log.ok('this installation offers no password, so no enrollment was issued')
|
|
109
|
+
log.info(`Sign in at the console with single sign-on as ${result.email}: the identity provider must vouch for that address.`)
|
|
110
|
+
return
|
|
111
|
+
}
|
|
107
112
|
if (result.enrollment.state === 'outstanding') {
|
|
108
113
|
log.warn(`an enrollment is already outstanding — a second one was NOT issued. Pass ${REISSUE_FLAG} to replace it if the first expired unopened`)
|
|
109
114
|
return
|
|
@@ -308,6 +308,46 @@ export const PLATFORM_PROXY_MANIFEST_TEMPLATE: PlatformProxyManifestTemplate = {
|
|
|
308
308
|
admission: null,
|
|
309
309
|
oauth: null,
|
|
310
310
|
},
|
|
311
|
+
{
|
|
312
|
+
id: 'github-handoff',
|
|
313
|
+
kind: 'protocol',
|
|
314
|
+
method: 'GET',
|
|
315
|
+
path: '/api/source/github/handoff/:connectionId',
|
|
316
|
+
callers: [],
|
|
317
|
+
requirement: null,
|
|
318
|
+
admission: null,
|
|
319
|
+
oauth: null,
|
|
320
|
+
},
|
|
321
|
+
{
|
|
322
|
+
id: 'github-handoff-open',
|
|
323
|
+
kind: 'protocol',
|
|
324
|
+
method: 'POST',
|
|
325
|
+
path: '/api/source/github/handoff/:connectionId',
|
|
326
|
+
callers: [],
|
|
327
|
+
requirement: null,
|
|
328
|
+
admission: null,
|
|
329
|
+
oauth: null,
|
|
330
|
+
},
|
|
331
|
+
{
|
|
332
|
+
id: 'github-handoff-callback',
|
|
333
|
+
kind: 'protocol',
|
|
334
|
+
method: 'GET',
|
|
335
|
+
path: '/api/source/github/handoff-callback',
|
|
336
|
+
callers: [],
|
|
337
|
+
requirement: null,
|
|
338
|
+
admission: null,
|
|
339
|
+
oauth: null,
|
|
340
|
+
},
|
|
341
|
+
{
|
|
342
|
+
id: 'github-handoff-setup',
|
|
343
|
+
kind: 'protocol',
|
|
344
|
+
method: 'GET',
|
|
345
|
+
path: '/api/source/github/handoff-setup/:connectionId',
|
|
346
|
+
callers: [],
|
|
347
|
+
requirement: null,
|
|
348
|
+
admission: null,
|
|
349
|
+
oauth: null,
|
|
350
|
+
},
|
|
311
351
|
{
|
|
312
352
|
id: 'rpc',
|
|
313
353
|
kind: 'service',
|
|
@@ -513,6 +553,46 @@ export const PLATFORM_PROXY_MANIFEST_TEMPLATE: PlatformProxyManifestTemplate = {
|
|
|
513
553
|
admission: null,
|
|
514
554
|
oauth: null,
|
|
515
555
|
},
|
|
556
|
+
{
|
|
557
|
+
id: 'github-handoff',
|
|
558
|
+
kind: 'protocol',
|
|
559
|
+
method: 'GET',
|
|
560
|
+
path: '/api/source/github/handoff/:connectionId',
|
|
561
|
+
callers: [],
|
|
562
|
+
requirement: null,
|
|
563
|
+
admission: null,
|
|
564
|
+
oauth: null,
|
|
565
|
+
},
|
|
566
|
+
{
|
|
567
|
+
id: 'github-handoff-open',
|
|
568
|
+
kind: 'protocol',
|
|
569
|
+
method: 'POST',
|
|
570
|
+
path: '/api/source/github/handoff/:connectionId',
|
|
571
|
+
callers: [],
|
|
572
|
+
requirement: null,
|
|
573
|
+
admission: null,
|
|
574
|
+
oauth: null,
|
|
575
|
+
},
|
|
576
|
+
{
|
|
577
|
+
id: 'github-handoff-callback',
|
|
578
|
+
kind: 'protocol',
|
|
579
|
+
method: 'GET',
|
|
580
|
+
path: '/api/source/github/handoff-callback',
|
|
581
|
+
callers: [],
|
|
582
|
+
requirement: null,
|
|
583
|
+
admission: null,
|
|
584
|
+
oauth: null,
|
|
585
|
+
},
|
|
586
|
+
{
|
|
587
|
+
id: 'github-handoff-setup',
|
|
588
|
+
kind: 'protocol',
|
|
589
|
+
method: 'GET',
|
|
590
|
+
path: '/api/source/github/handoff-setup/:connectionId',
|
|
591
|
+
callers: [],
|
|
592
|
+
requirement: null,
|
|
593
|
+
admission: null,
|
|
594
|
+
oauth: null,
|
|
595
|
+
},
|
|
516
596
|
{
|
|
517
597
|
id: 'rpc',
|
|
518
598
|
kind: 'service',
|
|
@@ -16,15 +16,19 @@ message that names the flag or the variable to set. Read the message: it names t
|
|
|
16
16
|
|
|
17
17
|
**Ask the human for these first.** You cannot produce them, and each one blocks a later step:
|
|
18
18
|
|
|
19
|
-
| What
|
|
20
|
-
|
|
|
21
|
-
| A Zerops PERSONAL access token of a client OWNER, generated in the Zerops GUI
|
|
22
|
-
| A verified Zerops account (credit topped up once); an unverified one owns ONE project
|
|
23
|
-
| A `gh` login allowed to create a repository in the organization that owns it
|
|
24
|
-
| The administrator's e-mail address, and the human to open the enrollment URL
|
|
25
|
-
| For a PRIVATE application repository: the GitHub App connected in the console
|
|
26
|
-
| The fabrika release tag to install, for example `v0.4.3` (a branch is refused)
|
|
27
|
-
| The
|
|
19
|
+
| What | Needed at |
|
|
20
|
+
| ---------------------------------------------------------------------------------------- | ---------- |
|
|
21
|
+
| A Zerops PERSONAL access token of a client OWNER, generated in the Zerops GUI | step 1 |
|
|
22
|
+
| A verified Zerops account (credit topped up once); an unverified one owns ONE project | step 5 |
|
|
23
|
+
| A `gh` login allowed to create a repository in the organization that owns it | step 3 |
|
|
24
|
+
| The administrator's e-mail address, and the human to open the enrollment URL | step 2 |
|
|
25
|
+
| For a PRIVATE application repository: the GitHub App connected in the console | step 5 |
|
|
26
|
+
| The fabrika release tag to install, for example `v0.4.3` (a branch is refused) | steps 1, 3 |
|
|
27
|
+
| The five decisions below | steps 1, 5 |
|
|
28
|
+
| Single sign-on only: the identity provider's issuer, client id and secret, and its admin | steps 1, 2 |
|
|
29
|
+
|
|
30
|
+
The identity provider's admin is whoever can register the redirect URI that step 1 prints at its end; single sign-on
|
|
31
|
+
fails until it is registered.
|
|
28
32
|
|
|
29
33
|
Every namespace is a Zerops project of its own, so the first one fails with `clientProjectCountLimitExceededTopUp`
|
|
30
34
|
on an unverified account (observed 2026-10-15).
|
|
@@ -95,6 +99,12 @@ container (a deploy raises the floor of an application with a database to 0.5 GB
|
|
|
95
99
|
every environment. `SERIOUS` adds $10 per namespace and a highly available balancer in front of its proxy,
|
|
96
100
|
and it can never be downgraded again.
|
|
97
101
|
|
|
102
|
+
**5. Sign-in method** (`platform install --auth-methods`, step 1). Free either way. `password` (the default)
|
|
103
|
+
needs nothing else: each person sets a password from an enrollment link. `oidc,password` adds single sign-on through
|
|
104
|
+
the organization's OpenID Connect identity provider beside it, and `oidc` alone removes passwords. Single sign-on
|
|
105
|
+
needs the provider's client (see Before you start). Who it admits is step 4 of "Turn on single sign-on" below,
|
|
106
|
+
which also turns it on or off later by hand.
|
|
107
|
+
|
|
98
108
|
## Secrets: rules for an agent
|
|
99
109
|
|
|
100
110
|
- Every credential is read from the ENVIRONMENT ONLY. No command takes one as a flag.
|
|
@@ -156,6 +166,13 @@ fabrika platform install --provider=zerops --create-project --client-id=<clientI
|
|
|
156
166
|
provider's variables from their own `0600` files. `fabrika platform install --provider=zerops --help` lists the
|
|
157
167
|
providers and their variables, each named after its provider (for Resend `FABRIKA_EMAIL_RESEND_API_KEY`). They have no flag. The install writes the set on `iam` and `control`, the credentials sensitive. They
|
|
158
168
|
are the human's own, so they are not copied into the secrets file.
|
|
169
|
+
- Sign-in is password only unless `--auth-methods` says otherwise. For single sign-on from the start, add
|
|
170
|
+
`--auth-methods=oidc,password --oidc-issuer=<issuer URL> --oidc-client-id=<client id>` and export
|
|
171
|
+
`FABRIKA_IAM_OIDC_CLIENT_SECRET` from its own `0600` file; it has no flag. The install writes the client on `iam`,
|
|
172
|
+
the secret sensitive and not into the secrets file. The IAM host exists only once pass 1 has run, so the log
|
|
173
|
+
ends with a `REGISTER THE REDIRECT URI` box: register that URI at the identity provider. `--auth-methods=oidc`
|
|
174
|
+
turns password sign-in off, and step 2 then admits the administrator without an enrollment. To add single sign-on later, see
|
|
175
|
+
"Turn on single sign-on" below.
|
|
159
176
|
|
|
160
177
|
**Check.** The log ends with the `Hand off` step: where the credentials are, `The console answers at
|
|
161
178
|
https://<console host>`, and an `ADMIT YOURSELF` box that holds the step 2 command with `--iam-host` filled
|
|
@@ -172,7 +189,9 @@ in. The secrets file exists with mode `0600`. The three hosts are printed earlie
|
|
|
172
189
|
Without a mail provider it prints one enrollment URL and the time it expires. Nothing is e-mailed then, so
|
|
173
190
|
do not tell the human to wait for a message. The URL is a credential: give it to the human only, and do not
|
|
174
191
|
log it. The human opens it, sets a password and signs in at the console origin. With a mail provider, IAM
|
|
175
|
-
e-mails the enrollment instead, and the command reports the address and the expiry.
|
|
192
|
+
e-mails the enrollment instead, and the command reports the address and the expiry. On an installation without
|
|
193
|
+
passwords (`--auth-methods=oidc`) it issues no enrollment: it reports that the administrator signs in with single
|
|
194
|
+
sign-on and exits 0. The identity provider must vouch for the same e-mail address.
|
|
176
195
|
|
|
177
196
|
The URL is valid for ONE HOUR. Hand it over at once. A re-run creates nothing new: while the enrollment is
|
|
178
197
|
unused it only reports that one is outstanding, and it never prints the URL again. To get a new URL, after
|
|
@@ -267,6 +286,17 @@ included, is the tag's version: `bun pm ls --all | grep @fabrika/`. Releases up
|
|
|
267
286
|
`@fabrika/*` dependencies by a range, so a transitive one can still resolve a later patch of that line. Then
|
|
268
287
|
install the newest patch instead (step 6 upgrades an installation).
|
|
269
288
|
|
|
289
|
+
**Build on a Bun that reads `bun.lock`.** The platform build runs `bun install --frozen-lockfile` on the
|
|
290
|
+
`build.base` of the application's `zerops.yaml` (`alpine/bun@1.3` when it names none), and an older Bun cannot
|
|
291
|
+
read a newer lockfile. A `bun.lock` that Bun 1.4 creates or regenerates has `"lockfileVersion": 2` (Bun 1.4 keeps
|
|
292
|
+
an existing version 1 lockfile at 1), which Bun 1.3 refuses, so the build fails with
|
|
293
|
+
`Unknown lockfile version ... lockfile is frozen`. Read the version with `head -2 bun.lock`. Versions 0 and 1 build
|
|
294
|
+
on `alpine/bun@1.3`, the oldest Bun base Zerops offers; version 2 needs `alpine/bun@1.4` or later. Raise
|
|
295
|
+
`build.base` to `alpine/bun@1.4`, or regenerate `bun.lock` with the base's Bun (delete it and run `bun install` with
|
|
296
|
+
Bun 1.3), which resolves every dependency afresh. `fabrika app build` and `app register` refuse a base that cannot
|
|
297
|
+
read the lockfile and name the one to use. They read the `bun.lock` beside them when they run: a lockfile
|
|
298
|
+
regenerated after registration is not checked, and only the build itself fails on it.
|
|
299
|
+
|
|
270
300
|
1. **Create a namespace** with the preset and core package the human chose (see Decisions). Without a
|
|
271
301
|
custom domain bound to its proxy, pass `--public-access=zerops-subdomain`; the default is
|
|
272
302
|
`custom-domain`, which serves no host until you bind one.
|
|
@@ -340,8 +370,18 @@ install the newest patch instead (step 6 upgrades an installation).
|
|
|
340
370
|
`deploy interrupted: …; run the deploy again` lost Control mid-run, typically to step 3's workflow
|
|
341
371
|
redeploying it: deploy again once Control is back.
|
|
342
372
|
|
|
343
|
-
|
|
344
|
-
|
|
373
|
+
`source resolve failed (descriptor_mismatch): zerops.yaml at commit <sha> has sha256 <a>, expected sha256
|
|
374
|
+
<b>` means the `zerops.yaml` at the deployed commit is not the one the environment's manifest was built
|
|
375
|
+
from. Deploying again fails the same way. Either side can be the newer one:
|
|
376
|
+
- The manifest is newer: it was built from a `zerops.yaml` that is not pushed yet. Commit and push it (or
|
|
377
|
+
deploy the ref that has it), and deploy again. Do not rebuild the manifest from the older commit: that
|
|
378
|
+
drops the change, and the next deploy succeeds without it.
|
|
379
|
+
- The commit is newer: `zerops.yaml` changed (its `build.base`, say) after the manifest was built. From a
|
|
380
|
+
checkout of that commit, rebuild the manifest (`fabrika app build --env=<name>`, plus `--config` if the
|
|
381
|
+
app uses another config), send it with `control apps environments put`, and deploy again.
|
|
382
|
+
|
|
383
|
+
The log line prints the `put` command with the environment's stored domain and trigger ref: `put` clears
|
|
384
|
+
either one when the flag is left out.
|
|
345
385
|
|
|
346
386
|
On an environment named `prod`, a change that widens access waits for a person to approve it in the
|
|
347
387
|
console before it deploys.
|
|
@@ -427,6 +467,44 @@ Without a transport, a contract whose job declares `mailer: 'installation'` stil
|
|
|
427
467
|
its jobs see that mail is not available and leave their messages queued, and after step 5 the next run sends them. On
|
|
428
468
|
0.7 or newer the relay accepts and holds the messages, and Control sends them once it has a transport.
|
|
429
469
|
|
|
470
|
+
## Turn on single sign-on
|
|
471
|
+
|
|
472
|
+
An installation signs people in with a password unless it was installed with `--auth-methods`. To add sign-in through
|
|
473
|
+
an OpenID Connect identity provider to an existing installation:
|
|
474
|
+
|
|
475
|
+
No `fabrika` command does this, and none undoes it: `platform deploy` and `platform upgrade` write none of the variables
|
|
476
|
+
below and remove none, so what you set survives every later deploy and upgrade. `install` cannot be re-run.
|
|
477
|
+
|
|
478
|
+
1. At the identity provider, create a web application client and register its redirect URI as
|
|
479
|
+
`https://<IAM host>/auth/callback`, with the IAM host from step 1. Note the issuer URL (IAM reads
|
|
480
|
+
`<issuer>/.well-known/openid-configuration`), the client id and the client secret.
|
|
481
|
+
2. Set these variables on the `iam` service, in the Zerops GUI or with `zcli`. The `OIDC_*` names carry no `FABRIKA_IAM_`
|
|
482
|
+
prefix: they are the names IAM reads.
|
|
483
|
+
|
|
484
|
+
| Variable | Value |
|
|
485
|
+
| ------------------------------ | ----------------------------------------------------------------------- |
|
|
486
|
+
| `FABRIKA_IAM_OIDC_ENABLED` | `true` |
|
|
487
|
+
| `FABRIKA_IAM_PASSWORD_ENABLED` | `true` keeps password sign-in beside single sign-on, `false` removes it |
|
|
488
|
+
| `OIDC_ISSUER` | the issuer URL |
|
|
489
|
+
| `OIDC_CLIENT_ID` | the client id |
|
|
490
|
+
| `OIDC_CLIENT_SECRET` | the client secret, stored SENSITIVE |
|
|
491
|
+
|
|
492
|
+
A readable `OIDC_CLIENT_SECRET` is read by every member of the project, and `platform deploy` refuses to run while it
|
|
493
|
+
is readable. A variable already stored readable does not become sensitive through `zops env set --sensitive`: delete
|
|
494
|
+
it and add it again as a secret one in the GUI.
|
|
495
|
+
3. Restart `iam`. It reads these at boot, and with `FABRIKA_IAM_OIDC_ENABLED=true` it refuses to start while any of the
|
|
496
|
+
three `OIDC_*` is missing, which takes sign-in down: read its log until it serves again. The sign-in page then
|
|
497
|
+
offers single sign-on beside the password form, or, with password off, goes straight to the provider.
|
|
498
|
+
4. Single sign-on admits only someone IAM already knows: an invited address or an existing user, matched by the e-mail
|
|
499
|
+
the provider verified. Anyone else is refused (`not_admitted`). The first sign-in links the person to the provider's
|
|
500
|
+
subject. With password off, `platform admin` admits the address and grants it the admin role without an enrollment;
|
|
501
|
+
that person signs in with single sign-on. The Zerops installer offers no domain-wide admission (Cloudflare's
|
|
502
|
+
`--human-email-domains`): to admit everyone of a domain without an invitation, set `HUMAN_EMAIL_DOMAINS` on `iam` to
|
|
503
|
+
a JSON array such as `["example.com"]` (unprefixed, like the `OIDC_*` names) and restart it.
|
|
504
|
+
|
|
505
|
+
To turn single sign-on off again, set `FABRIKA_IAM_OIDC_ENABLED=false` with `FABRIKA_IAM_PASSWORD_ENABLED=true` and
|
|
506
|
+
restart `iam`; it refuses to start with both off.
|
|
507
|
+
|
|
430
508
|
## When something fails
|
|
431
509
|
|
|
432
510
|
- Every refusal names its flag or variable. Fix that one value and re-run. `init`, `admin`, `deploy` and
|