@fabrika/provider-zerops 0.9.0-dev.1 → 0.9.0-dev.10

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.
Files changed (174) hide show
  1. package/package.json +17 -14
  2. package/sandbox/Dockerfile +16 -0
  3. package/sandbox/bin/postgres-auth.sh +38 -0
  4. package/sandbox/bin/reset.sh +12 -0
  5. package/sandbox/bin/run-build.sh +35 -0
  6. package/sandbox/bin/run-launcher.sh +18 -0
  7. package/sandbox/bin/start-launcher.sh +25 -0
  8. package/sandbox/bin/stop.sh +47 -0
  9. package/sandbox/init.sh +61 -0
  10. package/src/api/client.ts +15 -1
  11. package/src/api/errors.ts +7 -3
  12. package/src/api/readers.ts +29 -0
  13. package/src/api/types.ts +52 -0
  14. package/src/api.ts +2 -0
  15. package/src/cli.ts +11 -0
  16. package/src/collaborators.ts +0 -14
  17. package/src/compile.ts +1 -1
  18. package/src/control.ts +159 -92
  19. package/src/execution.ts +45 -195
  20. package/src/index.ts +2 -0
  21. package/src/installation/admin.ts +1 -1
  22. package/src/installation/deploy-options.ts +1 -2
  23. package/src/installation/deploy.ts +225 -80
  24. package/src/installation/generated/platform-console-schema.ts +3 -0
  25. package/src/installation/generated/platform-proxy-manifest.ts +1 -1
  26. package/src/installation/guide.md +48 -18
  27. package/src/installation/hosts.ts +1 -7
  28. package/src/installation/index.ts +13 -16
  29. package/src/installation/init-options.ts +2 -1
  30. package/src/installation/install-environment.ts +47 -108
  31. package/src/installation/install-options.ts +3 -1
  32. package/src/installation/install-secrets.ts +24 -68
  33. package/src/installation/install.ts +9 -4
  34. package/src/installation/sidecar.ts +5 -26
  35. package/src/installation/topology/setups.ts +17 -4
  36. package/src/installation/topology/topology.ts +32 -22
  37. package/src/installation/upgrade-options.ts +2 -2
  38. package/src/managed-env.ts +1 -174
  39. package/src/manifest.ts +4 -16
  40. package/src/namespace/claims.ts +60 -1
  41. package/src/namespace/codec.ts +17 -0
  42. package/src/namespace/errors.ts +22 -1
  43. package/src/namespace/manifest.ts +36 -23
  44. package/src/namespace/provisioning.ts +88 -114
  45. package/src/namespace/proxy-attempt.ts +14 -2
  46. package/src/namespace/proxy-reads.ts +28 -23
  47. package/src/namespace/proxy-secrets.ts +18 -5
  48. package/src/namespace/sandbox-host.ts +212 -0
  49. package/src/namespace/subdomain.ts +113 -0
  50. package/src/namespace/topology.ts +1 -1
  51. package/src/namespace/types.ts +13 -0
  52. package/src/namespace/update.ts +1 -0
  53. package/src/namespace-cli.ts +152 -0
  54. package/src/plan.ts +1 -6
  55. package/src/provider.ts +88 -166
  56. package/src/proxy-manifest-carrier.ts +39 -0
  57. package/src/sandbox/base-image.ts +100 -0
  58. package/src/sandbox/constants.ts +44 -0
  59. package/src/sandbox/deploy.ts +471 -0
  60. package/src/sandbox/dev-artifact.ts +206 -0
  61. package/src/sandbox/lifecycle.ts +204 -0
  62. package/src/sandbox/scripts.ts +26 -0
  63. package/src/sandbox-host.ts +28 -0
  64. package/src/source/port.ts +5 -0
  65. package/src/types.ts +0 -2
  66. package/src/zbox/client.ts +259 -0
  67. package/src/zbox/errors.ts +45 -0
  68. package/src/zbox/index.ts +22 -0
  69. package/src/zbox/types.ts +165 -0
  70. package/types/src/api/client.d.ts +5 -0
  71. package/types/src/api/errors.d.ts +26 -0
  72. package/types/src/api/polling.d.ts +41 -0
  73. package/types/src/api/readers.d.ts +1115 -0
  74. package/types/src/api/service-env-limit.d.ts +17 -0
  75. package/types/src/api/service-env-response.d.ts +23 -0
  76. package/types/src/api/types.d.ts +687 -0
  77. package/types/src/api.d.ts +6 -0
  78. package/types/src/authoring.d.ts +9 -0
  79. package/types/src/cli-args.d.ts +19 -0
  80. package/types/src/cli.d.ts +13 -0
  81. package/types/src/collaborators.d.ts +16 -0
  82. package/types/src/compile.d.ts +91 -0
  83. package/types/src/control.d.ts +51 -0
  84. package/types/src/database-budget.d.ts +38 -0
  85. package/types/src/descriptor.d.ts +28 -0
  86. package/types/src/execution.d.ts +114 -0
  87. package/types/src/exposure.d.ts +47 -0
  88. package/types/src/index.d.ts +31 -0
  89. package/types/src/installation/admin-options.d.ts +24 -0
  90. package/types/src/installation/admin.d.ts +35 -0
  91. package/types/src/installation/checker-release.d.ts +12 -0
  92. package/types/src/installation/deploy-options.d.ts +37 -0
  93. package/types/src/installation/deploy.d.ts +136 -0
  94. package/types/src/installation/generated/platform-console-schema.d.ts +2 -0
  95. package/types/src/installation/generated/platform-proxy-manifest.d.ts +2 -0
  96. package/types/src/installation/hosts.d.ts +34 -0
  97. package/types/src/installation/index.d.ts +7 -0
  98. package/types/src/installation/init-options.d.ts +38 -0
  99. package/types/src/installation/init.d.ts +60 -0
  100. package/types/src/installation/install-collaborators.d.ts +24 -0
  101. package/types/src/installation/install-environment.d.ts +63 -0
  102. package/types/src/installation/install-options.d.ts +49 -0
  103. package/types/src/installation/install-project.d.ts +13 -0
  104. package/types/src/installation/install-provisioning.d.ts +58 -0
  105. package/types/src/installation/install-secrets.d.ts +17 -0
  106. package/types/src/installation/install-token.d.ts +10 -0
  107. package/types/src/installation/install.d.ts +23 -0
  108. package/types/src/installation/installation-source.d.ts +8 -0
  109. package/types/src/installation/log.d.ts +44 -0
  110. package/types/src/installation/machine-key.d.ts +19 -0
  111. package/types/src/installation/placement-options.d.ts +11 -0
  112. package/types/src/installation/platform-archive.d.ts +7 -0
  113. package/types/src/installation/platform-source.d.ts +8 -0
  114. package/types/src/installation/platform-upload.d.ts +3 -0
  115. package/types/src/installation/sidecar.d.ts +49 -0
  116. package/types/src/installation/source-options.d.ts +1 -0
  117. package/types/src/installation/topology/artifacts.d.ts +8 -0
  118. package/types/src/installation/topology/index.d.ts +5 -0
  119. package/types/src/installation/topology/installation-schemas.d.ts +2242 -0
  120. package/types/src/installation/topology/invariants.d.ts +23 -0
  121. package/types/src/installation/topology/setups.d.ts +59 -0
  122. package/types/src/installation/topology/topology.d.ts +153 -0
  123. package/types/src/installation/topology/validate.d.ts +11 -0
  124. package/types/src/installation/upgrade-options.d.ts +26 -0
  125. package/types/src/installation/upgrade-output.d.ts +6 -0
  126. package/types/src/installation/upgrade.d.ts +88 -0
  127. package/types/src/managed-env.d.ts +24 -0
  128. package/types/src/manifest.d.ts +199 -0
  129. package/types/src/namespace/claims.d.ts +16 -0
  130. package/types/src/namespace/codec.d.ts +352 -0
  131. package/types/src/namespace/constants.d.ts +25 -0
  132. package/types/src/namespace/errors.d.ts +25 -0
  133. package/types/src/namespace/manifest.d.ts +4 -0
  134. package/types/src/namespace/operator.d.ts +12 -0
  135. package/types/src/namespace/provisioning.d.ts +4 -0
  136. package/types/src/namespace/proxy-attempt.d.ts +39 -0
  137. package/types/src/namespace/proxy-reads.d.ts +27 -0
  138. package/types/src/namespace/proxy-secrets.d.ts +8 -0
  139. package/types/src/namespace/proxy-source.d.ts +74 -0
  140. package/types/src/namespace/sandbox-host.d.ts +23 -0
  141. package/types/src/namespace/subdomain.d.ts +43 -0
  142. package/types/src/namespace/topology.d.ts +9 -0
  143. package/types/src/namespace/types.d.ts +111 -0
  144. package/types/src/namespace/update.d.ts +6 -0
  145. package/types/src/namespace/validation.d.ts +12 -0
  146. package/types/src/namespace-cli.d.ts +2 -0
  147. package/types/src/namespace.d.ts +9 -0
  148. package/types/src/plan.d.ts +11 -0
  149. package/types/src/provider.d.ts +60 -0
  150. package/types/src/proxy-manifest-carrier.d.ts +37 -0
  151. package/types/src/sandbox/base-image.d.ts +28 -0
  152. package/types/src/sandbox/constants.d.ts +30 -0
  153. package/types/src/sandbox/deploy.d.ts +75 -0
  154. package/types/src/sandbox/dev-artifact.d.ts +51 -0
  155. package/types/src/sandbox/lifecycle.d.ts +27 -0
  156. package/types/src/sandbox/scripts.d.ts +11 -0
  157. package/types/src/sandbox-host.d.ts +16 -0
  158. package/types/src/schema.generated.d.ts +376 -0
  159. package/types/src/service-names.d.ts +4 -0
  160. package/types/src/service-references.d.ts +13 -0
  161. package/types/src/source/constants.d.ts +6 -0
  162. package/types/src/source/port.d.ts +65 -0
  163. package/types/src/source/types.d.ts +4 -0
  164. package/types/src/source/validation.d.ts +19 -0
  165. package/types/src/source.d.ts +2 -0
  166. package/types/src/types.d.ts +119 -0
  167. package/types/src/version-attempt.d.ts +8 -0
  168. package/types/src/zbox/client.d.ts +2 -0
  169. package/types/src/zbox/errors.d.ts +25 -0
  170. package/types/src/zbox/index.d.ts +3 -0
  171. package/types/src/zbox/types.d.ts +433 -0
  172. package/src/installation/mcp.ts +0 -102
  173. package/src/installation/proxy-manifest.ts +0 -214
  174. package/src/installation/secrets.ts +0 -78
@@ -69,7 +69,7 @@ import { assertTopologyInvariants } from './invariants'
69
69
  * `enableSubdomainAccess` on a service the document CREATES and then silently drops it, so the service
70
70
  * reads back `subdomainAccess: false` and stays there. The subdomain is established afterwards, by
71
71
  * `PUT /service-stack/{id}/enable-subdomain-access` on a service that already publishes an HTTP port —
72
- * which the namespace lifecycle does for itself (`ensureSubdomainAccess` in `src/namespace/provisioning.ts`)
72
+ * which the namespace lifecycle does for itself (`ensureSubdomainAccess` in `src/namespace/subdomain.ts`)
73
73
  * and which an operator applying the generated platform artifacts must do by hand; the artifact's header
74
74
  * names the call. So `true` here records the INTENT and feeds ADR-0022's `assertOnlyPublicService`; it
75
75
  * does not turn anything on.
@@ -82,22 +82,27 @@ export type PublicAccess = 'custom-domain' | 'zerops-subdomain'
82
82
  * `standard` is the production shape: HA Postgres, a separate database and bucket for Operations, and
83
83
  * enough containers that no single one is a point of failure.
84
84
  *
85
- * `light` is one project, one `postgresql:single@18` and one bucket shared by IAM, Operations, control
86
- * AND the apps deployed alongside them, at one container per service. This tier exists because the standard
85
+ * `light` is one project with two `postgresql:single@18` services — `db` for IAM and control, `operationsdb`
86
+ * for Operations — and one bucket, at one container per service. This tier exists because the standard
87
87
  * shape costs ~13 containers before a single application is deployed, which is more platform than a
88
- * small fleet — or an evaluation — can justify.
88
+ * small fleet — or an evaluation — can justify. Applications run in their own namespace projects
89
+ * (ADR-0034); a production namespace that must keep its data through a node loss asks for HA there.
89
90
  *
90
- * Sharing is safe rather than merely cheap, and that is a property of the code, not of this comment:
91
+ * Operations gets its own database, not a schema beside IAM's, because Zerops backs up a whole service on
92
+ * one schedule: identity and deploy state is worth an hourly dump, error history is not, and only two
93
+ * services can carry two schedules. It also keeps Operations' high-volume writes off the identity path.
91
94
  *
92
- * • The three services' table names do not intersect (IAM 10, Operations 24, control 16), and
93
- * ADR-0017 already gives each its own migration ledger and advisory lock, so one database holds
94
- * all three without coordination.
95
+ * Sharing the rest is safe rather than merely cheap, and that is a property of the code, not of this comment:
96
+ *
97
+ * • IAM's and control's table names do not intersect, and ADR-0017 gives each its own migration ledger
98
+ * and advisory lock, so one database holds both without coordination. A light installation created
99
+ * before Operations moved out still holds all three in `db`, which the same property covers.
95
100
  * • Their blob keys are prefix-disjoint — control writes `runs/`, Operations writes `events/`,
96
101
  * `dead/` and `source-maps/` — so one bucket cannot collide.
97
102
  *
98
- * What `light` genuinely gives up is FAILURE-DOMAIN isolation: Operations' high-volume error history
99
- * now shares capacity with the identity path, and losing the one database loses all three services.
100
- * That is the trade, and it is why `standard` remains the default rather than the special case.
103
+ * What `light` genuinely gives up is AVAILABILITY and DURABILITY: one container per service, and a
104
+ * single-node database loses everything since its last backup when its node fails (Zerops has no
105
+ * point-in-time recovery). That is the trade, and it is why `standard` remains the default rather than the special case.
101
106
  */
102
107
  export type PlatformTier = 'standard' | 'light'
103
108
 
@@ -188,9 +193,9 @@ export const platformTopology = (options: TopologyOptions): ProjectTopology => {
188
193
  hostname: 'db',
189
194
  // HA is encoded in the TYPE. The deprecated `mode` field is not merely avoided here — it
190
195
  // is absent from `ZeropsServiceSpec`, so it cannot be written. One database serves both
191
- // IAM and the control plane; they are separate schemas in it, not separate services,
192
- // because a second HA Postgres triples the cost of the isolation the private network
193
- // already gives us.
196
+ // IAM and the control plane; both use its default schema with disjoint tables and their own
197
+ // migration ledgers (ADR-0017), not separate services, because a second HA Postgres triples
198
+ // the cost of the isolation the private network already gives us.
194
199
  type: 'postgresql:ha@18',
195
200
  // The identity and control-plane database: every login, every token mint, every run's
196
201
  // state. `oltp-production` is also what an HA service gets by DEFAULT — stated here so
@@ -315,10 +320,9 @@ const lightPlatformTopology = (options: TopologyOptions, publicAccess: PublicAcc
315
320
  // that creates the project. Same shape as `compileZeropsNamespaceTopology` in `src/namespace/topology.ts`.
316
321
  const services = (): ZeropsServiceSpec[] => [
317
322
  {
318
- // ONE database for IAM, control, Operations and every app in this project. Which schema each
319
- // one gets is not expressed here — it is `FABRIKA_*_DATABASE_URL`, written per installation
320
- // through the env API, because this same repository-root `zerops.yaml` serves both tiers and
321
- // a `${operationsdb_connectionString}` baked into it would name a service `light` does not have.
323
+ // IAM and control. Which schema each one gets is not expressed here — it is `FABRIKA_*_DATABASE_URL`,
324
+ // written per installation through the env API, because this same repository-root `zerops.yaml`
325
+ // serves both tiers.
322
326
  hostname: 'db',
323
327
  type: 'postgresql:single@18',
324
328
  // `oltp-hobby`, written out because a default is not a choice — this type's default is
@@ -326,15 +330,21 @@ const lightPlatformTopology = (options: TopologyOptions, publicAccess: PublicAcc
326
330
  //
327
331
  // A floor is not headroom. Every PostgreSQL profile shares the same 8-core / 48 GB / 250 GB
328
332
  // ceiling and the same vertical autoscaler, so `oltp-staging` does not let this service grow
329
- // any further than `oltp-hobby` does — it only pre-pays for memory the tier is idle on. That
330
- // this single service holds IAM, control, Operations and the apps beside them is an argument
331
- // about the ceiling, which is unchanged.
333
+ // any further than `oltp-hobby` does — it only pre-pays for memory the tier is idle on.
332
334
  //
333
335
  // An installation that wants a specific floor sets one on the service — `minRam` accepts a
334
336
  // float — which is where a per-installation value belongs (ADR-0004), not in this document.
335
337
  profile: 'oltp-hobby',
336
338
  priority: 100,
337
339
  },
340
+ {
341
+ // Operations' own database: its own backup schedule (the Zerops default, daily) and its own
342
+ // capacity, off the identity path. Same type and profile as `db`, for the same reasons.
343
+ hostname: 'operationsdb',
344
+ type: 'postgresql:single@18',
345
+ profile: 'oltp-hobby',
346
+ priority: 100,
347
+ },
338
348
  {
339
349
  // ONE bucket. Prefix-disjoint by construction: `runs/` (control) vs `events/`, `dead/` and
340
350
  // `source-maps/` (Operations).
@@ -367,7 +377,7 @@ const lightPlatformTopology = (options: TopologyOptions, publicAccess: PublicAcc
367
377
  platform: 'zerops',
368
378
  project: {
369
379
  name: 'platform',
370
- description: 'fabrika light tier: control plane, Operations, IAM, the auth proxy and the apps they serve, on shared data services.',
380
+ description: 'fabrika light tier: control plane, Operations, IAM and the auth proxy, on single-node data services.',
371
381
  corePackage: 'LIGHT',
372
382
  tags: ['fabrika', 'platform', 'light', options.env],
373
383
  },
@@ -8,8 +8,8 @@
8
8
  // The pin is checked BEFORE anything leaves this machine: `assertPinnedTag` refuses a branch or a SHA
9
9
  // (ADR-0025) without a network call, so `--to=main` fails on the spot rather than after a clone.
10
10
 
11
- import { describeArgument, readFlag } from '@fabrika/installation-init'
12
- import { assertPinnedTag, defaultCheckoutDir } from './sidecar'
11
+ import { assertPinnedTag, describeArgument, readFlag } from '@fabrika/installation-init'
12
+ import { defaultCheckoutDir } from './sidecar'
13
13
 
14
14
  /** Where the sidecar repository this command edits is found. */
15
15
  export type UpgradeSidecar =
@@ -1,18 +1,5 @@
1
- import {
2
- FRAMEWORK_VARIABLE_PREFIXES,
3
- type FrameworkVariableName,
4
- frameworkVariableReference,
5
- isConnectKeyVariable,
6
- isConnectUrlVariable,
7
- isEmailTransportVariable,
8
- isFrameworkVariableName,
9
- isPlatformTransportVariable,
10
- isWorkloadKeyVariable,
11
- PLATFORM_RECEIVERS,
12
- platformTransportVariables,
13
- } from '@fabrika/auth-core'
1
+ import { frameworkVariableReference, isFrameworkVariableName } from '@fabrika/auth-core'
14
2
  import type { JsonValue } from '@fabrika/provider-contract'
15
- import { z } from 'zod'
16
3
  import { renderYaml } from './compile'
17
4
  import {
18
5
  assertOwnRunWhenExtending,
@@ -22,166 +9,6 @@ import {
22
9
  selectZeropsDescriptorSetup,
23
10
  } from './descriptor'
24
11
 
25
- /** The framework-only names Control hands every Zerops deploy; the rest of the list is the provider's own. */
26
- export type ManagedKey = Extract<
27
- FrameworkVariableName,
28
- | 'FABRIKA_RELEASE'
29
- | 'FABRIKA_OPERATIONS_DSN'
30
- | 'FABRIKA_IAM_ISSUER'
31
- | 'FABRIKA_IAM_APP_ID'
32
- | 'FABRIKA_APP_ID'
33
- | 'FABRIKA_ENVIRONMENT'
34
- | 'FABRIKA_SERVICE_KEY'
35
- | 'FABRIKA_PROXY_SECRET'
36
- | 'FABRIKA_IAM_RPC_URL'
37
- | 'FABRIKA_IAM_RPC_KEY'
38
- | 'FABRIKA_APP_ORIGIN'
39
- | 'FABRIKA_TOKEN_KEYS'
40
- >
41
-
42
- export const MANAGED_KEYS: readonly ManagedKey[] = [
43
- 'FABRIKA_RELEASE',
44
- 'FABRIKA_OPERATIONS_DSN',
45
- 'FABRIKA_IAM_ISSUER',
46
- 'FABRIKA_IAM_APP_ID',
47
- 'FABRIKA_APP_ID',
48
- 'FABRIKA_ENVIRONMENT',
49
- 'FABRIKA_SERVICE_KEY',
50
- 'FABRIKA_PROXY_SECRET',
51
- 'FABRIKA_IAM_RPC_URL',
52
- 'FABRIKA_IAM_RPC_KEY',
53
- 'FABRIKA_APP_ORIGIN',
54
- 'FABRIKA_TOKEN_KEYS',
55
- ]
56
-
57
- /** The managed keys written as service variables; `FABRIKA_RELEASE` travels only in the execution descriptor (ADR-0044). */
58
- export const SERVICE_MANAGED_KEYS: readonly Exclude<ManagedKey, 'FABRIKA_RELEASE'>[] = [
59
- 'FABRIKA_OPERATIONS_DSN',
60
- 'FABRIKA_IAM_ISSUER',
61
- 'FABRIKA_IAM_APP_ID',
62
- 'FABRIKA_APP_ID',
63
- 'FABRIKA_ENVIRONMENT',
64
- 'FABRIKA_SERVICE_KEY',
65
- 'FABRIKA_PROXY_SECRET',
66
- 'FABRIKA_IAM_RPC_URL',
67
- 'FABRIKA_IAM_RPC_KEY',
68
- 'FABRIKA_APP_ORIGIN',
69
- 'FABRIKA_TOKEN_KEYS',
70
- ]
71
-
72
- /** The managed keys that carry a credential, written sensitive and therefore never compared. */
73
- export const SENSITIVE_MANAGED_KEYS: ReadonlySet<ManagedKey> = new Set<ManagedKey>([
74
- 'FABRIKA_OPERATIONS_DSN',
75
- 'FABRIKA_SERVICE_KEY',
76
- 'FABRIKA_PROXY_SECRET',
77
- 'FABRIKA_IAM_RPC_KEY',
78
- 'FABRIKA_TOKEN_KEYS',
79
- ])
80
-
81
- const PLATFORM_URL_VARIABLES: ReadonlySet<string> = new Set(PLATFORM_RECEIVERS.map((receiver) => platformTransportVariables(receiver).url))
82
-
83
- /**
84
- * A workload, connect or platform transport key and every mail transport variable are written sensitive; a connect or
85
- * platform transport URL is an origin.
86
- */
87
- export const isSensitiveFamilyVariable = (name: string): boolean => !isConnectUrlVariable(name) && !PLATFORM_URL_VARIABLES.has(name)
88
-
89
- export type ManagedValues = Record<ManagedKey, string | null>
90
-
91
- const managedValuesSchema = z.object({
92
- FABRIKA_RELEASE: z.string().nullable(),
93
- FABRIKA_OPERATIONS_DSN: z.string().nullable(),
94
- FABRIKA_IAM_ISSUER: z.string().nullable(),
95
- FABRIKA_IAM_APP_ID: z.string().nullable(),
96
- FABRIKA_APP_ID: z.string().nullable(),
97
- FABRIKA_ENVIRONMENT: z.string().nullable(),
98
- FABRIKA_SERVICE_KEY: z.string().nullable(),
99
- FABRIKA_PROXY_SECRET: z.string().nullable(),
100
- // IAM's membership transport (ADR-0022 rule 6): its public origin and this environment's key, or both null.
101
- FABRIKA_IAM_RPC_URL: z.string().nullable(),
102
- FABRIKA_IAM_RPC_KEY: z.string().nullable(),
103
- // The environment's canonical origin (`ctx.url`), or null when it has no public origin.
104
- FABRIKA_APP_ORIGIN: z.string().nullable(),
105
- // The keys of the application's signed tokens, or null when its contract declares no token purpose.
106
- FABRIKA_TOKEN_KEYS: z.string().nullable(),
107
- }).strict()
108
-
109
- export function parseManagedValues(value: unknown): ManagedValues {
110
- const result = managedValuesSchema.safeParse(value)
111
- if (!result.success) throw new Error('zerops: managed environment must name exactly the twelve managed keys')
112
- return result.data
113
- }
114
-
115
- /**
116
- * What Control hands a deploy: the twelve managed keys, the key of each job and webhook of the approved contract, the
117
- * key and owner origin of each connector import, and the installation's mail transport when a job sends through it.
118
- */
119
- export interface ManagedEnvironment {
120
- readonly values: ManagedValues
121
- /**
122
- * `FABRIKA_<KIND>_<NAME>_KEY` → the workload's `px_` key, `FABRIKA_CONNECT_<IMPORT>_KEY` / `_URL`, each
123
- * `FABRIKA_EMAIL_*` of the installation's mail transport, and `FABRIKA_PLATFORM_<RECEIVER>_URL` / `_KEY`.
124
- */
125
- readonly familyVariables: Readonly<Record<string, string>>
126
- }
127
-
128
- const keySchema = z.string().startsWith('px_').min(4)
129
- const mailValueSchema = z.string().min(1)
130
- const originSchema = (schemes: readonly string[]) =>
131
- z.string().refine((value) => {
132
- try {
133
- const url = new URL(value)
134
- return url.origin === value && schemes.includes(url.protocol)
135
- } catch {
136
- return false
137
- }
138
- })
139
- const connectOriginSchema = originSchema(['https:'])
140
- // Control's public origin is http in the local stack (`http://control.fabrika.localhost:18080`).
141
- const platformOriginSchema = originSchema(['http:', 'https:'])
142
-
143
- export function parseManagedEnvironment(value: Readonly<Record<string, string | null>>): ManagedEnvironment {
144
- const managed: Record<string, string | null> = {}
145
- const familyVariables: Record<string, string> = {}
146
- for (const [name, entry] of Object.entries(value)) {
147
- if (!isFrameworkFamilyVariable(name)) {
148
- managed[name] = entry
149
- continue
150
- }
151
- if (isEmailTransportVariable(name)) {
152
- const parsed = mailValueSchema.safeParse(entry)
153
- if (!parsed.success) throw new Error(`zerops: ${name} must not be empty`)
154
- familyVariables[name] = parsed.data
155
- continue
156
- }
157
- if (isPlatformTransportVariable(name)) {
158
- const address = PLATFORM_URL_VARIABLES.has(name)
159
- const parsed = (address ? platformOriginSchema : keySchema).safeParse(entry)
160
- if (!parsed.success) throw new Error(`zerops: ${name} must be ${address ? 'an http(s) origin' : 'a px_ key'}`)
161
- familyVariables[name] = parsed.data
162
- continue
163
- }
164
- const origin = isConnectUrlVariable(name)
165
- if (!origin && !isWorkloadKeyVariable(name) && !isConnectKeyVariable(name)) {
166
- throw new Error(`zerops: ${name} is not a variable a deploy writes`)
167
- }
168
- const parsed = (origin ? connectOriginSchema : keySchema).safeParse(entry)
169
- if (!parsed.success) {
170
- throw new Error(`zerops: ${name} must be ${origin ? 'an https origin' : 'a px_ key'}`)
171
- }
172
- familyVariables[name] = parsed.data
173
- }
174
- return { values: parseManagedValues(managed), familyVariables }
175
- }
176
-
177
- /**
178
- * A service variable only the platform writes per workload, import, platform receiver or the installation's mail
179
- * transport: a stale one is removed when the deploy no longer hands it.
180
- */
181
- export function isFrameworkFamilyVariable(name: string): boolean {
182
- return FRAMEWORK_VARIABLE_PREFIXES.some((prefix) => name.startsWith(prefix))
183
- }
184
-
185
12
  const refuse = (): never => {
186
13
  throw new Error('zerops: application configuration uses a Fabrika-managed environment name')
187
14
  }
package/src/manifest.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { CONTRACT_JOB_NAME_PATTERN, CRON_SCHEDULE_PATTERN } from '@fabrika/app/build'
1
2
  import { appSchemaSchema } from '@fabrika/auth'
2
3
  import { type AppSchema, type ContractArtifact, contractDigest, isDigest } from '@fabrika/auth-core'
3
4
  import type { OperationsSourceMapBuildUpload } from '@fabrika/operations-contract/releases'
@@ -17,7 +18,6 @@ import {
17
18
  zeropsAssetRoots,
18
19
  type ZeropsContractRun,
19
20
  zeropsContractRun,
20
- type ZeropsDevExecution,
21
21
  type ZeropsLockedExecution,
22
22
  type ZeropsRuntimePackage,
23
23
  } from './execution'
@@ -312,13 +312,10 @@ const importDocumentSchema = z.object({ project: importProjectSchema.optional(),
312
312
  /** The import document a manifest carries: every service already holds the ADR-0004 invariants. */
313
313
  export type FabrikaManifestImportDocument = z.infer<typeof importDocumentSchema>
314
314
 
315
- const JOB_NAME = /^[A-Za-z][A-Za-z0-9_]*$/
316
- const CRON_SCHEDULE = /^[0-9*/,-]+(?: [0-9*/,-]+){4}$/
317
-
318
315
  const contractRunSchema = z.object({
319
316
  digest: z.string().regex(CONTRACT_DIGEST_PATTERN),
320
317
  readinessPath: z.string().regex(READINESS_PATH_PATTERN),
321
- jobs: z.array(z.object({ name: z.string().regex(JOB_NAME), schedule: z.string().regex(CRON_SCHEDULE) }).strict()),
318
+ jobs: z.array(z.object({ name: z.string().regex(CONTRACT_JOB_NAME_PATTERN), schedule: z.string().regex(CRON_SCHEDULE_PATTERN) }).strict()),
322
319
  files: z.literal(true).optional(),
323
320
  scan: z.literal(true).optional(),
324
321
  }).strict()
@@ -476,11 +473,8 @@ export const lockedExecutionOf = (manifest: FabrikaManifest): ZeropsLockedExecut
476
473
  }
477
474
  }
478
475
 
479
- /**
480
- * What Control lets a provider publish for one environment (`ProviderEnvironment.access`), and, for an environment of
481
- * kind `dev`, the commit its bootstrap builds.
482
- */
483
- export type ZeropsAccess = Pick<ProviderEnvironment, 'access'> & { readonly dev?: ZeropsDevExecution }
476
+ /** What Control lets a provider publish for one environment (`ProviderEnvironment.access`). */
477
+ export type ZeropsAccess = Pick<ProviderEnvironment, 'access'>
484
478
 
485
479
  /**
486
480
  * The execution descriptor's lock-down at deploy (ADR-0050): Control's approved contract decides it, not the artifact,
@@ -509,7 +503,6 @@ export function lockedExecutionFor(
509
503
  storageHostname: applicationStorageHostname(manifest.target.importDocument.services),
510
504
  runtimePackages: manifest.target.runtimePackages ?? [],
511
505
  sourceMaps: artifactUpload === undefined ? null : sourceMapUpload(artifactUpload, access.contract),
512
- ...(granted.dev === undefined ? {} : { dev: granted.dev }),
513
506
  }
514
507
  }
515
508
 
@@ -526,11 +519,6 @@ const sourceMapUpload = (upload: NonNullable<ProviderDeployInput['artifactUpload
526
519
  assetRoots: zeropsAssetRoots(contract),
527
520
  })
528
521
 
529
- /** The IAM schema a deploy, cancel or reconcile applies: the approved contract's. `undefined` reconciles nothing. */
530
- export function approvedSchemaOf(granted: ZeropsAccess): AppSchema | undefined {
531
- return granted.access?.schema
532
- }
533
-
534
522
  export const manifestServiceHostnames = (manifest: FabrikaManifest): string[] =>
535
523
  manifest.target.importDocument.services.map((service) => service.hostname)
536
524
 
@@ -1,15 +1,24 @@
1
- import type { ProviderDeploymentNamespace, ProviderRegistration } from '@fabrika/provider-contract'
1
+ import type {
2
+ ProviderClaimedResource,
3
+ ProviderClaimedResourcesInput,
4
+ ProviderDeploymentNamespace,
5
+ ProviderRegistration,
6
+ } from '@fabrika/provider-contract'
2
7
  import { isProxyHost } from '@fabrika/proxy-core/manifest'
8
+ import { type ZeropsApi, ZeropsApiError } from '../api'
3
9
  import { assertFabrikaManifestCoordinates, manifestServiceHostnames, zeropsArtifactCodec } from '../manifest'
10
+ import { SANDBOX_HOST_HOSTNAME } from '../sandbox-host'
4
11
  import { zeropsSharedServicePrefix } from '../service-names'
5
12
  import { decodeEnvelope } from './codec'
6
13
  import { ZEROPS_NAMESPACE_POSTGRES_HOSTNAME, ZEROPS_NAMESPACE_PROXY_HOSTNAME } from './constants'
14
+ import { asNamespaceError } from './errors'
7
15
 
8
16
  export const namespaceResourceClaims = (namespace: ProviderDeploymentNamespace): string[] => {
9
17
  const target = decodeEnvelope(namespace.target)
10
18
  return [
11
19
  `service:${ZEROPS_NAMESPACE_PROXY_HOSTNAME}`,
12
20
  ...(target.postgres === undefined ? [] : [`service:${ZEROPS_NAMESPACE_POSTGRES_HOSTNAME}`]),
21
+ ...(target.sandboxHost === undefined ? [] : [`service:${SANDBOX_HOST_HOSTNAME}`]),
13
22
  ]
14
23
  }
15
24
 
@@ -33,6 +42,8 @@ export const registrationResourceClaims = (registration: ProviderRegistration):
33
42
  appId: registration.app.id,
34
43
  env: registration.environment.env,
35
44
  })
45
+ // A dev environment owns no Zerops service: each workspace runs in a sandbox of the namespace's own sandbox host.
46
+ if (registration.environment.kind === 'dev') return []
36
47
  // A proxy target is routed by HOST, so a registration with no domain has nothing the proxy can serve:
37
48
  // refuse it here, where nothing has been created yet, instead of at the first deploy's manifest compile.
38
49
  if (manifest.target.proxy !== undefined) {
@@ -75,3 +86,51 @@ export const registrationResourceClaims = (registration: ProviderRegistration):
75
86
  }
76
87
  return hostnames.map((hostname) => `service:${hostname}`).sort()
77
88
  }
89
+
90
+ /**
91
+ * The platform's answer for a project that does not exist, a deleted one included. A project the token holds no grant
92
+ * on answers `403 insufficientPermissions` instead (zerops-platform.md), so this never reads an unreachable one as gone.
93
+ */
94
+ export const ZEROPS_PROJECT_NOT_FOUND = 'projectNotFound'
95
+
96
+ const SERVICE_CLAIM_PREFIX = 'service:'
97
+
98
+ /**
99
+ * Whether each claimed service still exists in the namespace's project. Gone means the project reads `projectNotFound`,
100
+ * or it exists and has no service under the claimed hostname. Any other answer, a key that names no service, or a
101
+ * namespace that never recorded its project throws: Control then releases nothing.
102
+ */
103
+ export const claimedResources = async (
104
+ api: Pick<ZeropsApi, 'getProject' | 'findService'>,
105
+ input: ProviderClaimedResourcesInput,
106
+ ): Promise<ProviderClaimedResource[]> => {
107
+ try {
108
+ const services = input.resourceKeys.map((resourceKey) => {
109
+ const hostname = resourceKey.startsWith(SERVICE_CLAIM_PREFIX) ? resourceKey.slice(SERVICE_CLAIM_PREFIX.length) : ''
110
+ if (hostname === '') throw new Error(`Zerops cannot tell whether claimed resource \`${resourceKey}\` exists`)
111
+ return { resourceKey, hostname }
112
+ })
113
+ const projectId = decodeEnvelope(input.namespace.target).projectId
114
+ // An interrupted first provision can leave a project its marker names but the target does not.
115
+ if (projectId === undefined) {
116
+ throw new Error(`Zerops namespace \`${input.namespace.id}\` records no project, so its services cannot be read back`)
117
+ }
118
+ if (!(await projectExists(api, projectId, input.signal))) return services.map(({ resourceKey }) => ({ resourceKey, exists: false }))
119
+ return await Promise.all(services.map(async ({ resourceKey, hostname }) => ({
120
+ resourceKey,
121
+ exists: (await api.findService({ projectId, hostname, signal: input.signal })) !== null,
122
+ })))
123
+ } catch (cause) {
124
+ throw asNamespaceError(cause, 'claim check')
125
+ }
126
+ }
127
+
128
+ export const projectExists = async (api: Pick<ZeropsApi, 'getProject'>, projectId: string, signal: AbortSignal): Promise<boolean> => {
129
+ try {
130
+ await api.getProject({ projectId, signal })
131
+ return true
132
+ } catch (error) {
133
+ if (error instanceof ZeropsApiError && error.code === ZEROPS_PROJECT_NOT_FOUND) return false
134
+ throw error
135
+ }
136
+ }
@@ -42,6 +42,21 @@ const singlePostgresSchema = z.object({
42
42
  profile: z.enum(['oltp-hobby', 'oltp-staging', 'oltp-production', 'olap-production', 'writeheavy-production']).optional(),
43
43
  })
44
44
 
45
+ /** The Box API origin is exactly an `https:` origin: the key is sent there as a bearer. */
46
+ const isHttpsOrigin = (value: string): boolean => {
47
+ try {
48
+ const url = new URL(value)
49
+ return url.protocol === 'https:' && url.origin === value
50
+ } catch {
51
+ return false
52
+ }
53
+ }
54
+
55
+ const sandboxHostSchema = z.object({
56
+ serviceId: z.string().min(1),
57
+ apiOrigin: z.string().refine(isHttpsOrigin),
58
+ }).strict()
59
+
45
60
  export const postgresSchema = z.discriminatedUnion('type', [haPostgresSchema, singlePostgresSchema]).transform((value) => {
46
61
  if (value.profile === undefined) delete value.profile
47
62
  return value
@@ -63,6 +78,7 @@ const namespaceTargetShape = z.object({
63
78
  proxyBaselineSequence: z.number().int().min(-1).optional(),
64
79
  proxyAppVersionId: z.string().min(1).optional(),
65
80
  proxyHosts: z.array(z.object({ host: z.string().min(1), port: z.number().int().positive() })).optional(),
81
+ sandboxHost: sandboxHostSchema.optional(),
66
82
  ready: z.boolean().optional(),
67
83
  })
68
84
 
@@ -120,6 +136,7 @@ export const zeropsNamespaceTargetCodec: ProviderCodec<ZeropsNamespaceTarget> =
120
136
  ...(target.proxyBaselineSequence !== undefined ? { proxyBaselineSequence: target.proxyBaselineSequence } : {}),
121
137
  ...(target.proxyAppVersionId !== undefined ? { proxyAppVersionId: target.proxyAppVersionId } : {}),
122
138
  ...(target.proxyHosts === undefined ? {} : { proxyHosts: target.proxyHosts.map((entry) => ({ host: entry.host, port: entry.port })) }),
139
+ ...(target.sandboxHost === undefined ? {} : { sandboxHost: { serviceId: target.sandboxHost.serviceId, apiOrigin: target.sandboxHost.apiOrigin } }),
123
140
  ...(target.ready !== undefined ? { ready: target.ready } : {}),
124
141
  }),
125
142
  decode: (payload) => {
@@ -1,6 +1,7 @@
1
1
  import { ProviderNamespaceError } from '@fabrika/provider-contract'
2
2
  import { ZeropsApiError, ZeropsServiceEnvValueTooLargeError } from '../api'
3
3
  import { ZeropsSourceRateLimitedError } from '../source/port'
4
+ import { ZboxApiError, ZboxOperationFailed } from '../zbox'
4
5
 
5
6
  /**
6
7
  * Lifecycle codes this provider defines where the platform has none of its own. They are an
@@ -19,6 +20,21 @@ export const ZEROPS_SUBDOMAIN_NOT_PUBLISHED = 'subdomainNotPublished'
19
20
 
20
21
  export const ZEROPS_SOURCE_RATE_LIMITED = 'githubRateLimited'
21
22
 
23
+ /** A dev sandbox entry would be published to a namespace whose pinned proxy cannot parse one. */
24
+ export const ZEROPS_PROXY_SANDBOXES_UNSUPPORTED = 'proxySandboxesUnsupported'
25
+
26
+ /** A sandbox host was asked of a namespace that serves no custom domain, which a dev environment's wildcard needs. */
27
+ export const ZEROPS_SANDBOX_HOST_UNSUPPORTED = 'sandboxHostUnsupported'
28
+
29
+ /** The Box API did not accept the namespace's key after the service restarted with it. */
30
+ export const ZEROPS_SANDBOX_HOST_KEY_REFUSED = 'sandboxHostKeyRefused'
31
+
32
+ /** The Box API answered a request that carried no key, even after a restart with the namespace's key. */
33
+ export const ZEROPS_SANDBOX_HOST_API_OPEN = 'sandboxHostApiOpen'
34
+
35
+ /** A dev environment an older release registered with its own Zerops service, which runs in no sandbox. */
36
+ export const ZEROPS_DEV_TARGET_RETIRED = 'devTargetRetired'
37
+
22
38
  export const namespaceError = (code: string, message: string, retryable: boolean, detail?: string): ProviderNamespaceError =>
23
39
  new ProviderNamespaceError(message, code, retryable, detail)
24
40
 
@@ -42,12 +58,17 @@ const splitApiMessage = (message: string, code: string): { summary: string; deta
42
58
  }
43
59
 
44
60
  /** Every namespace lifecycle failure leaves this provider as one typed, coded error. */
45
- export const asNamespaceError = (cause: unknown, mode: 'provision' | 'reconcile' | 'update'): ProviderNamespaceError => {
61
+ export const asNamespaceError = (cause: unknown, mode: 'provision' | 'reconcile' | 'update' | 'claim check'): ProviderNamespaceError => {
46
62
  if (cause instanceof ProviderNamespaceError) return cause
47
63
  // The same value is refused again on every retry; only a smaller manifest or a new carrier fixes it.
48
64
  if (cause instanceof ZeropsServiceEnvValueTooLargeError) return namespaceError(cause.code, cause.message, false)
49
65
  // The limit resets on its own: the namespace stays `provisioning` and the cron's reconcile retries it.
50
66
  if (cause instanceof ZeropsSourceRateLimitedError) return namespaceError(ZEROPS_SOURCE_RATE_LIMITED, cause.message, true)
67
+ // The message is the operation, the status and Box's code only: Box echoes request data in its bodies.
68
+ if (cause instanceof ZboxApiError) {
69
+ return namespaceError(cause.code, cause.message, cause.status === 0 || cause.status === 429 || cause.status >= 500)
70
+ }
71
+ if (cause instanceof ZboxOperationFailed) return namespaceError(cause.code ?? 'zboxOperationFailed', cause.message, false)
51
72
  if (cause instanceof ZeropsApiError) {
52
73
  const { summary, detail } = splitApiMessage(cause.message, cause.code)
53
74
  return namespaceError(
@@ -1,15 +1,43 @@
1
1
  import { appEnvironmentId } from '@fabrika/auth-core'
2
2
  import { decodeEnvelope, type ProviderNamespaceMember } from '@fabrika/provider-contract'
3
- import { isCrossOrigin, isPolicyOrigin, MAX_CROSS_ORIGINS } from '@fabrika/proxy-core/headers'
4
- import { contractProxyTable, type ProxyManifest } from '@fabrika/proxy-core/manifest'
3
+ import { contractProxyEntry, contractProxyTable, devSandboxEntryId, type ProxyManifest } from '@fabrika/proxy-core/manifest'
5
4
  import { assertFabrikaManifestCoordinates, zeropsArtifactCodec } from '../manifest'
5
+ import { SANDBOX_UPSTREAM } from '../sandbox-host'
6
6
 
7
7
  /** Compile every public member of one deployment namespace into its strict proxy manifest. */
8
8
  export function compileNamespaceProxyManifest(namespaceId: string, members: readonly ProviderNamespaceMember[]): ProxyManifest {
9
9
  const apps: ProxyManifest['apps'] = []
10
10
  const ids = new Set<string>()
11
11
  const hosts = new Set<string>()
12
+ const claim = (id: string, host: string): void => {
13
+ if (ids.has(id)) throw new Error(`duplicate proxy app id \`${id}\` in deployment namespace ${namespaceId}`)
14
+ if (hosts.has(host)) throw new Error(`duplicate proxy host \`${host}\` in deployment namespace ${namespaceId}`)
15
+ ids.add(id)
16
+ hosts.add(host)
17
+ }
12
18
  for (const member of members) {
19
+ // A dev member is served only through its workspaces' sandboxes, each behind the namespace's own sandbox host; its
20
+ // upstream is never the artifact's, so the artifact is not decoded.
21
+ if (member.devSandboxes !== undefined) {
22
+ const audience = appEnvironmentId(member.appId, member.env)
23
+ for (const sandbox of member.devSandboxes) {
24
+ const id = devSandboxEntryId(member.appId, sandbox.workspaceId)
25
+ const host = sandbox.host.toLowerCase()
26
+ claim(id, host)
27
+ apps.push(contractProxyEntry({
28
+ id,
29
+ audience,
30
+ hosts: [host],
31
+ upstream: SANDBOX_UPSTREAM,
32
+ upstreamHost: sandbox.upstreamHost,
33
+ scheme: 'https',
34
+ table: contractProxyTable(sandbox.access.contract, sandbox.access.contractDigest),
35
+ ...(member.operationsOrigin === undefined ? {} : { operationsOrigin: member.operationsOrigin }),
36
+ ...(member.crossOrigins === undefined ? {} : { crossOrigins: member.crossOrigins }),
37
+ }))
38
+ }
39
+ continue
40
+ }
13
41
  // Only Control decides what routes a member (ADR-0050): its approved contract's endpoint table. A member without
14
42
  // one is not routed, and its artifact is not decoded, so a legacy one cannot stop the others' republish.
15
43
  const access = member.access
@@ -24,33 +52,18 @@ export function compileNamespaceProxyManifest(namespaceId: string, members: read
24
52
  const host = member.domain.toLowerCase()
25
53
  // The proxy mints for the IAM application id of this environment (ADR-0022 rule 6).
26
54
  const id = appEnvironmentId(member.appId, member.env)
27
- if (ids.has(id)) throw new Error(`duplicate proxy app id \`${id}\` in deployment namespace ${namespaceId}`)
28
- if (hosts.has(host)) throw new Error(`duplicate proxy host \`${host}\` in deployment namespace ${namespaceId}`)
29
- ids.add(id)
30
- hosts.add(host)
31
- const operationsOrigin = member.operationsOrigin
32
- if (operationsOrigin !== undefined && !isPolicyOrigin(operationsOrigin, ['https:', 'http:'])) {
33
- throw new Error(`Zerops proxy target ${member.appId}/${member.env} has an Operations ingest origin that is not an http(s) origin`)
34
- }
35
- const crossOrigins = member.crossOrigins ?? []
36
- if (
37
- crossOrigins.length > MAX_CROSS_ORIGINS
38
- || new Set(crossOrigins).size !== crossOrigins.length
39
- || crossOrigins.some((origin) => !isCrossOrigin(origin) || new URL(origin).hostname === host)
40
- ) {
41
- throw new Error(`Zerops proxy target ${member.appId}/${member.env} has a cross-origin list the proxy manifest refuses`)
42
- }
43
- apps.push({
55
+ claim(id, host)
56
+ apps.push(contractProxyEntry({
44
57
  id,
45
58
  hosts: [host],
46
59
  upstream: proxy.upstream,
47
60
  // A Zerops public domain is always served over the project's TLS-terminating L7 balancer, so the
48
61
  // browser speaks https even though the proxy itself is reached over plain HTTP (ADR-0022).
49
62
  scheme: 'https',
50
- ...contractProxyTable(access.contract, access.contractDigest),
51
- ...(operationsOrigin === undefined ? {} : { operationsOrigin }),
52
- ...(crossOrigins.length === 0 ? {} : { crossOrigins: [...crossOrigins] }),
53
- })
63
+ table: contractProxyTable(access.contract, access.contractDigest),
64
+ ...(member.operationsOrigin === undefined ? {} : { operationsOrigin: member.operationsOrigin }),
65
+ ...(member.crossOrigins === undefined ? {} : { crossOrigins: member.crossOrigins }),
66
+ }))
54
67
  }
55
68
  return { apps }
56
69
  }