@fabrika/provider-zerops 0.9.0-dev.11 → 0.9.0-dev.12

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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fabrika/provider-zerops",
3
- "version": "0.9.0-dev.11",
3
+ "version": "0.9.0-dev.12",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",
@@ -39,21 +39,21 @@
39
39
  }
40
40
  },
41
41
  "scripts": {
42
- "typecheck": "tsc --noEmit",
42
+ "typecheck": "tsrs --build tsconfig.test.json",
43
43
  "test": "bun test",
44
44
  "gen:schema": "bun scripts/generate-zerops-types.ts"
45
45
  },
46
46
  "dependencies": {
47
47
  "zod": "^3.25.76",
48
- "@fabrika/app": "0.9.0-dev.11",
49
- "@fabrika/auth": "0.9.0-dev.11",
50
- "@fabrika/auth-core": "0.9.0-dev.11",
51
- "@fabrika/email": "0.9.0-dev.11",
52
- "@fabrika/iam-contract": "0.9.0-dev.11",
53
- "@fabrika/installation-init": "0.9.0-dev.11",
54
- "@fabrika/operations-contract": "0.9.0-dev.11",
55
- "@fabrika/provider-contract": "0.9.0-dev.11",
56
- "@fabrika/proxy-core": "0.9.0-dev.11",
48
+ "@fabrika/app": "0.9.0-dev.12",
49
+ "@fabrika/auth": "0.9.0-dev.12",
50
+ "@fabrika/auth-core": "0.9.0-dev.12",
51
+ "@fabrika/email": "0.9.0-dev.12",
52
+ "@fabrika/iam-contract": "0.9.0-dev.12",
53
+ "@fabrika/installation-init": "0.9.0-dev.12",
54
+ "@fabrika/operations-contract": "0.9.0-dev.12",
55
+ "@fabrika/provider-contract": "0.9.0-dev.12",
56
+ "@fabrika/proxy-core": "0.9.0-dev.12",
57
57
  "yaml": "^2.9.1"
58
58
  }
59
59
  }
@@ -383,6 +383,15 @@ forwarding a caller's `px_` key to the application (`docs/reference/deployment-n
383
383
  service variable, which Zerops caps at about 32 KB: when a deploy fails with `serviceEnvValueTooLarge`, this is
384
384
  the fix, and it also accepts a namespace in `failed`.
385
385
 
386
+ The platform services install only the workspace packages (`bun install --frozen-lockfile --filter './packages/*'`
387
+ in the generated `zerops.yaml`), not the repository's own tooling. An installation from before that change keeps the
388
+ tooling in each service's cached `node_modules`, because neither the filtered install nor a changed build command
389
+ clears the Zerops build cache. Nothing fails without clearing it. To shrink the artifacts of `iam`, `control` and
390
+ `operations` by about 160 MB each, invalidate their build cache once (service → Pipelines & CI/CD Settings →
391
+ Invalidate build cache); the next deploy of each builds clean. The platform `proxy` and each namespace's `proxy`
392
+ deploy no `node_modules`, so only their build cache would shrink; invalidating it is optional and costs one full
393
+ build of Caddy.
394
+
386
395
  ## Set or rotate the mail transport
387
396
 
388
397
  The installation's mail transport lives on the `iam` and `control` services. Zerops is its record (ADR-0004),
@@ -392,24 +401,30 @@ existing installation, change the provider, or rotate a key:
392
401
  No `fabrika` command does this: `platform upgrade` and `platform deploy` write no `FABRIKA_EMAIL_*` and remove
393
402
  none, and `install` cannot be re-run.
394
403
 
395
- 1. Set the same `FABRIKA_EMAIL_*` variables on BOTH `iam` and `control`, in the Zerops GUI or with `zcli`:
396
- `FABRIKA_EMAIL_PROVIDER`, `FABRIKA_EMAIL_FROM`, optionally `FABRIKA_EMAIL_FROM_NAME`, and the provider's
397
- variables. Store the credentials (every variable `fabrika platform install --provider=zerops --help` marks secret) as SENSITIVE variables: a readable
398
- one is read by every member of the project, and `platform deploy` refuses to run while one is readable. A
399
- variable already stored readable does not become sensitive through `zops env set --sensitive`, which leaves
400
- an existing variable as it was: delete it and add it again as a secret one in the GUI. Delete the variables of a
401
- provider you leave.
402
- 2. Restart `iam` and `control`. Each reads the transport at boot. IAM refuses to start on an invalid one.
403
- Control starts, logs a line that names the invalid variables, and refuses every deploy that needs the transport
404
- until you fix them and restart it.
405
- 3. Redeploy every environment whose contract uses `installation` mail and whose application pins a framework release
404
+ 1. Pick a provider the RUNNING release accepts. The installation runs the tag in its sidecar's `fabrika.ref`; from a
405
+ checkout of that tag, `fabrika platform install --provider=zerops --help` lists the accepted providers on its
406
+ `--email-provider` line, and each provider's variables below it. A provider that only a newer release accepts needs
407
+ `platform upgrade --to=<that tag>` first: IAM refuses to start on a provider its release does not know.
408
+ 2. Set the `FABRIKA_EMAIL_*` variables on `control` first, in the Zerops GUI or with `zcli`: `FABRIKA_EMAIL_PROVIDER`,
409
+ `FABRIKA_EMAIL_FROM`, optionally `FABRIKA_EMAIL_FROM_NAME`, and the provider's variables. Store the credentials
410
+ (every variable that help marks secret) as SENSITIVE variables: a readable one is read by every member of the
411
+ project, and `platform deploy` refuses to run while one is readable. A variable already stored readable does not
412
+ become sensitive through `zops env set --sensitive`, which leaves an existing variable as it was: delete it and add
413
+ it again as a secret one in the GUI. Delete the variables of a provider you leave.
414
+ 3. Restart `control` and read its log. Control starts either way; an invalid transport prints
415
+ `control: the installation's mail transport is invalid, …` naming the invalid variables, and every deploy that needs
416
+ the transport is refused. Fix the values and restart until no such line appears.
417
+ 4. Only then set the same variables on `iam` as in step 2 (credentials SENSITIVE, the old provider's variables deleted)
418
+ and restart it. IAM reads the transport at boot and refuses to start on an invalid one, so an `iam` restart with
419
+ values Control has not accepted takes sign-in down.
420
+ 5. Redeploy every environment whose contract uses `installation` mail and whose application pins a framework release
406
421
  older than 0.7. Such an application holds its own copy of the transport and gets the new one only at its next
407
422
  deploy. Until then it sends with the old one, and a revoked key fails its mail with `provider_unauthorized`. An
408
- application on 0.7 or newer sends through Control's relay, which uses the new transport once step 2 restarted
423
+ application on 0.7 or newer sends through Control's relay, which uses the new transport once step 3 restarted
409
424
  Control: it needs no redeploy.
410
425
 
411
426
  Without a transport, a contract whose job declares `mailer: 'installation'` still deploys. On a release older than 0.7
412
- its jobs see that mail is not available and leave their messages queued, and after step 3 the next run sends them. On
427
+ its jobs see that mail is not available and leave their messages queued, and after step 5 the next run sends them. On
413
428
  0.7 or newer the relay accepts and holds the messages, and Control sends them once it has a transport.
414
429
 
415
430
  ## When something fails
@@ -160,6 +160,12 @@ const READINESS_IMMEDIATE: Omit<ZeropsReadinessCheckSpec, 'httpGet' | 'exec'> =
160
160
  */
161
161
  const WORKSPACE_DEPLOY_FILES = ['package.json', 'bun.lock', 'node_modules', 'packages']
162
162
 
163
+ /**
164
+ * The install of every platform service: the workspace packages, without the root package's own tooling (checkers,
165
+ * linters, browsers), which no service builds or runs with. The quotes keep the build shell from expanding the glob.
166
+ */
167
+ const WORKSPACE_INSTALL = "bun install --frozen-lockfile --filter './packages/*'"
168
+
163
169
  /**
164
170
  * The IAM service — identity, tokens, audit, and the private admin API.
165
171
  *
@@ -192,7 +198,7 @@ const iam: ZeropsYamlSetupSpec = {
192
198
  build: {
193
199
  // Bun on Alpine. `build.os` is deprecated in the published schema — the OS is part of the base id.
194
200
  base: ['alpine/bun@1.3'],
195
- buildCommands: ['bun install --frozen-lockfile'],
201
+ buildCommands: [WORKSPACE_INSTALL],
196
202
  deployFiles: WORKSPACE_DEPLOY_FILES,
197
203
  cache: ['node_modules'],
198
204
  },
@@ -265,7 +271,7 @@ const control: ZeropsYamlSetupSpec = {
265
271
  setup: 'control',
266
272
  build: {
267
273
  base: ['alpine/bun@1.3'],
268
- buildCommands: ['bun install --frozen-lockfile', 'bun run --filter @fabrika/dashboard build'],
274
+ buildCommands: [WORKSPACE_INSTALL, 'bun run --filter @fabrika/dashboard build'],
269
275
  deployFiles: WORKSPACE_DEPLOY_FILES,
270
276
  cache: ['node_modules'],
271
277
  },
@@ -307,7 +313,7 @@ const operations: ZeropsYamlSetupSpec = {
307
313
  setup: 'operations',
308
314
  build: {
309
315
  base: ['alpine/bun@1.3'],
310
- buildCommands: ['bun install --frozen-lockfile'],
316
+ buildCommands: [WORKSPACE_INSTALL],
311
317
  deployFiles: WORKSPACE_DEPLOY_FILES,
312
318
  cache: ['node_modules'],
313
319
  },
@@ -412,7 +418,7 @@ const proxy: ZeropsYamlSetupSpec = {
412
418
  // CGO off makes the binary static, which is what lets it run on Alpine/musl.
413
419
  prepareCommands: ['CGO_ENABLED=0 GOBIN=/tmp/gobin go install github.com/caddyserver/caddy/v2/cmd/caddy@v2.10.2'],
414
420
  buildCommands: [
415
- 'bun install --frozen-lockfile',
421
+ WORKSPACE_INSTALL,
416
422
  // The archive's data file (see the header). Missing/malformed JSON fails the build; an empty app list
417
423
  // emits only deny/404 routes.
418
424
  `bun run packages/proxy/src/generate-config.ts ./proxy.manifest.json ./caddy.json --auth-upstream 127.0.0.1:9000 --listen ${
@@ -13,6 +13,12 @@ import { decodeEnvelope } from './codec'
13
13
  import { ZEROPS_NAMESPACE_POSTGRES_HOSTNAME, ZEROPS_NAMESPACE_PROXY_HOSTNAME } from './constants'
14
14
  import { asNamespaceError } from './errors'
15
15
 
16
+ /** Refused for an app service whatever the target records now: any namespace may add a sandbox host later. */
17
+ const RESERVED_HOSTNAMES: ReadonlySet<string> = new Set([ZEROPS_NAMESPACE_PROXY_HOSTNAME, SANDBOX_HOST_HOSTNAME])
18
+
19
+ /** A shared namespace also keeps `postgres`, because adopting its project refuses an undeclared `postgres` service. */
20
+ const SHARED_RESERVED_HOSTNAMES: ReadonlySet<string> = new Set([...RESERVED_HOSTNAMES, ZEROPS_NAMESPACE_POSTGRES_HOSTNAME])
21
+
16
22
  export const namespaceResourceClaims = (namespace: ProviderDeploymentNamespace): string[] => {
17
23
  const target = decodeEnvelope(namespace.target)
18
24
  return [
@@ -70,13 +76,17 @@ export const registrationResourceClaims = (registration: ProviderRegistration):
70
76
  }
71
77
  }
72
78
  const hostnames = manifestServiceHostnames(manifest)
79
+ const shared = namespace.exclusiveAppId === undefined
80
+ const reserved = shared ? SHARED_RESERVED_HOSTNAMES : RESERVED_HOSTNAMES
73
81
  for (const hostname of hostnames) {
74
- const key = `service:${hostname}`
75
- if (namespaceClaims.has(key)) {
76
- throw new Error(`Zerops service hostname \`${hostname}\` is reserved by the namespace`)
82
+ if (namespaceClaims.has(`service:${hostname}`) || reserved.has(hostname)) {
83
+ throw new Error(
84
+ `Zerops service hostname \`${hostname}\` is reserved by the namespace: rename the service `
85
+ + '(docs/reference/deployment-namespaces.md, "Renaming a reserved service")',
86
+ )
77
87
  }
78
88
  }
79
- if (namespace.exclusiveAppId === undefined) {
89
+ if (shared) {
80
90
  const prefix = zeropsSharedServicePrefix(registration.app.id)
81
91
  for (const hostname of hostnames) {
82
92
  if (!hostname.startsWith(prefix) || hostname.length === prefix.length) {
@@ -1,5 +1,10 @@
1
1
  import { appEnvironmentId } from '@fabrika/auth-core'
2
- import { decodeEnvelope, type ProviderNamespaceMember } from '@fabrika/provider-contract'
2
+ import {
3
+ decodeEnvelope,
4
+ type ProviderApprovedAccess,
5
+ type ProviderNamespaceMember,
6
+ type ProviderNamespaceMemberRouting,
7
+ } from '@fabrika/provider-contract'
3
8
  import { contractProxyEntry, contractProxyTable, devSandboxEntryId, type ProxyManifest } from '@fabrika/proxy-core/manifest'
4
9
  import { assertFabrikaManifestCoordinates, zeropsArtifactCodec } from '../manifest'
5
10
  import { SANDBOX_UPSTREAM } from '../sandbox-host'
@@ -22,7 +27,7 @@ export function compileNamespaceProxyManifest(namespaceId: string, members: read
22
27
  const audience = appEnvironmentId(member.appId, member.env)
23
28
  for (const sandbox of member.devSandboxes) {
24
29
  const id = devSandboxEntryId(member.appId, sandbox.workspaceId)
25
- const host = sandbox.host.toLowerCase()
30
+ const host = sandboxHost(sandbox)
26
31
  claim(id, host)
27
32
  apps.push(contractProxyEntry({
28
33
  id,
@@ -38,25 +43,16 @@ export function compileNamespaceProxyManifest(namespaceId: string, members: read
38
43
  }
39
44
  continue
40
45
  }
41
- // Only Control decides what routes a member (ADR-0050): its approved contract's endpoint table. A member without
42
- // one is not routed, and its artifact is not decoded, so a legacy one cannot stop the others' republish.
43
- const access = member.access
44
- if (access === undefined) continue
45
- const manifest = decodeEnvelope('artifact', 'zerops', member.artifact, zeropsArtifactCodec)
46
- assertFabrikaManifestCoordinates(manifest.app, { appId: member.appId, env: member.env })
47
- const proxy = manifest.target.proxy
48
- if (proxy === undefined) continue
49
- if (member.domain === undefined || member.domain === '') {
50
- throw new Error(`Zerops proxy target ${member.appId}/${member.env} requires a public domain`)
51
- }
52
- const host = member.domain.toLowerCase()
46
+ const routed = routedContractMember(member)
47
+ if (routed === undefined) continue
48
+ const { host, upstream, access } = routed
53
49
  // The proxy mints for the IAM application id of this environment (ADR-0022 rule 6).
54
50
  const id = appEnvironmentId(member.appId, member.env)
55
51
  claim(id, host)
56
52
  apps.push(contractProxyEntry({
57
53
  id,
58
54
  hosts: [host],
59
- upstream: proxy.upstream,
55
+ upstream,
60
56
  // A Zerops public domain is always served over the project's TLS-terminating L7 balancer, so the
61
57
  // browser speaks https even though the proxy itself is reached over plain HTTP (ADR-0022).
62
58
  scheme: 'https',
@@ -67,3 +63,33 @@ export function compileNamespaceProxyManifest(namespaceId: string, members: read
67
63
  }
68
64
  return { apps }
69
65
  }
66
+
67
+ /**
68
+ * The hosts the namespace proxy routes one member on, lower-cased: a dev member's workspace sandbox hosts, otherwise its
69
+ * domain once Control approved a contract for a manifest with a proxy target. The compiler above routes by the same rule.
70
+ */
71
+ export function namespaceMemberHosts(member: ProviderNamespaceMemberRouting): string[] {
72
+ if (member.devSandboxes !== undefined) return member.devSandboxes.map(sandboxHost)
73
+ const routed = routedContractMember(member)
74
+ return routed === undefined ? [] : [routed.host]
75
+ }
76
+
77
+ const sandboxHost = (sandbox: { readonly host: string }): string => sandbox.host.toLowerCase()
78
+
79
+ /** A member that is not a dev member, routed on its domain; undefined when the proxy does not route it. */
80
+ function routedContractMember(
81
+ member: ProviderNamespaceMemberRouting,
82
+ ): { readonly host: string; readonly upstream: string; readonly access: ProviderApprovedAccess } | undefined {
83
+ // Only Control decides what routes a member (ADR-0050): its approved contract's endpoint table. A member without
84
+ // one is not routed, and its artifact is not decoded, so a legacy one cannot stop the others' republish.
85
+ const access = member.access
86
+ if (access === undefined) return undefined
87
+ const manifest = decodeEnvelope('artifact', 'zerops', member.artifact, zeropsArtifactCodec)
88
+ assertFabrikaManifestCoordinates(manifest.app, { appId: member.appId, env: member.env })
89
+ const proxy = manifest.target.proxy
90
+ if (proxy === undefined) return undefined
91
+ if (member.domain === undefined || member.domain === '') {
92
+ throw new Error(`Zerops proxy target ${member.appId}/${member.env} requires a public domain`)
93
+ }
94
+ return { host: member.domain.toLowerCase(), upstream: proxy.upstream, access }
95
+ }
@@ -13,7 +13,7 @@ import { claimedResources, namespaceResourceClaims, projectExists, registrationR
13
13
  import { checkpoint, decodeEnvelope, normalizedNamespace, normalizeTarget } from './codec'
14
14
  import { ZEROPS_NAMESPACE_POSTGRES_HOSTNAME, ZEROPS_NAMESPACE_PROXY_HOSTNAME } from './constants'
15
15
  import { asNamespaceError, namespaceError } from './errors'
16
- import { compileNamespaceProxyManifest } from './manifest'
16
+ import { compileNamespaceProxyManifest, namespaceMemberHosts } from './manifest'
17
17
  import { createZeropsNamespaceOperator } from './operator'
18
18
  import { republishProxy } from './proxy-attempt'
19
19
  import { assertNamespaceProxyAcceptsSandboxes } from './proxy-reads'
@@ -445,6 +445,7 @@ export const createZeropsNamespaceCapabilities = (options: ZeropsNamespaceOption
445
445
  provision: (input) => mutateNamespace(input, options, 'provision'),
446
446
  reconcile: (input) => mutateNamespace(input, options, 'reconcile'),
447
447
  republish: (input) => republishNamespace(input, options),
448
+ memberHosts: namespaceMemberHosts,
448
449
  claimedResources: (input) => claimedResources(options.api, input),
449
450
  updates: createZeropsNamespaceUpdates(options),
450
451
  operator: createZeropsNamespaceOperator({ proxySource: options.proxySource }),
@@ -128,11 +128,11 @@ export declare const namespaceUpdatePayloadSchema: z.ZodObject<{
128
128
  host: z.ZodString;
129
129
  port: z.ZodNumber;
130
130
  }, "strip", z.ZodTypeAny, {
131
- port: number;
132
131
  host: string;
133
- }, {
134
132
  port: number;
133
+ }, {
135
134
  host: string;
135
+ port: number;
136
136
  }>, "many">>>;
137
137
  sandboxHost: z.ZodOptional<z.ZodOptional<z.ZodObject<{
138
138
  serviceId: z.ZodString;
@@ -281,8 +281,8 @@ export declare const namespaceUpdatePayloadSchema: z.ZodObject<{
281
281
  proxyBaselineSequence?: number | undefined;
282
282
  proxyAppVersionId?: string | undefined;
283
283
  proxyHosts?: {
284
- port: number;
285
284
  host: string;
285
+ port: number;
286
286
  }[] | undefined;
287
287
  sandboxHost?: {
288
288
  serviceId: string;
@@ -335,8 +335,8 @@ export declare const namespaceUpdatePayloadSchema: z.ZodObject<{
335
335
  proxyBaselineSequence?: number | undefined;
336
336
  proxyAppVersionId?: string | undefined;
337
337
  proxyHosts?: {
338
- port: number;
339
338
  host: string;
339
+ port: number;
340
340
  }[] | undefined;
341
341
  sandboxHost?: {
342
342
  serviceId: string;
@@ -1,4 +1,9 @@
1
- import { type ProviderNamespaceMember } from '@fabrika/provider-contract';
1
+ import { type ProviderNamespaceMember, type ProviderNamespaceMemberRouting } from '@fabrika/provider-contract';
2
2
  import { type ProxyManifest } from '@fabrika/proxy-core/manifest';
3
3
  /** Compile every public member of one deployment namespace into its strict proxy manifest. */
4
4
  export declare function compileNamespaceProxyManifest(namespaceId: string, members: readonly ProviderNamespaceMember[]): ProxyManifest;
5
+ /**
6
+ * The hosts the namespace proxy routes one member on, lower-cased: a dev member's workspace sandbox hosts, otherwise its
7
+ * domain once Control approved a contract for a manifest with a proxy target. The compiler above routes by the same rule.
8
+ */
9
+ export declare function namespaceMemberHosts(member: ProviderNamespaceMemberRouting): string[];