@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
@@ -0,0 +1,111 @@
1
+ import type { ProviderNamespaceHost } from '@fabrika/provider-contract';
2
+ import type { ZeropsApi, ZeropsProjectMode } from '../api';
3
+ import type { Sleeper } from '../collaborators';
4
+ import type { ZeropsArtifactSourceDescriptor } from '../manifest';
5
+ import type { ZeropsSourceRepository } from '../source';
6
+ import type { ZeropsSourcePort } from '../source/port';
7
+ import type { ZeropsSourceTarget } from '../types';
8
+ import type { ZboxFetch } from '../zbox';
9
+ export type ZeropsNamespacePublicAccess = 'custom-domain' | 'zerops-subdomain';
10
+ export interface ZeropsNamespaceProxySource {
11
+ readonly repository: ZeropsSourceRepository;
12
+ readonly commitSha: string;
13
+ readonly descriptor: ZeropsArtifactSourceDescriptor;
14
+ }
15
+ /** The proxy attempt in flight (ADR-0044): a version not `triggered` is deleted, a triggered one is polled. */
16
+ export interface ZeropsNamespaceProxyBuild {
17
+ readonly appVersionId: string;
18
+ readonly triggered: boolean;
19
+ readonly manifestSha256?: string;
20
+ }
21
+ export interface ZeropsNamespaceProxyDeployment {
22
+ readonly manifestSha256?: string;
23
+ readonly appVersionId: string;
24
+ readonly repository: ZeropsSourceRepository;
25
+ readonly commitSha: string;
26
+ readonly descriptorSha256: string;
27
+ }
28
+ export type ZeropsNamespacePostgres = {
29
+ readonly type: 'postgresql:ha@18';
30
+ readonly profile?: 'oltp-staging' | 'oltp-production' | 'oltp-enterprise' | 'olap-production' | 'writeheavy-production';
31
+ } | {
32
+ readonly type: 'postgresql:single@18';
33
+ readonly profile?: 'oltp-hobby' | 'oltp-staging' | 'oltp-production' | 'olap-production' | 'writeheavy-production';
34
+ };
35
+ /**
36
+ * Provider-owned namespace state. Optional fields are durable progress checkpoints; values that are
37
+ * absent are resolved by `normalize()` before a mutation starts.
38
+ */
39
+ export interface ZeropsNamespaceTarget {
40
+ readonly proxySource: ZeropsNamespaceProxySource;
41
+ readonly proxyBuild?: ZeropsNamespaceProxyBuild;
42
+ readonly proxyDeployment?: ZeropsNamespaceProxyDeployment;
43
+ readonly projectName?: string;
44
+ readonly corePackage?: ZeropsProjectMode;
45
+ readonly publicAccess?: ZeropsNamespacePublicAccess;
46
+ readonly postgres?: ZeropsNamespacePostgres;
47
+ readonly managed?: boolean;
48
+ readonly projectId?: string;
49
+ readonly proxyServiceId?: string;
50
+ readonly postgresServiceId?: string;
51
+ readonly proxyConfigured?: boolean;
52
+ readonly proxyBaselineSequence?: number;
53
+ readonly proxyAppVersionId?: string;
54
+ /** The hosts the published proxy answers on, recorded once so a namespace read needs no platform call. */
55
+ readonly proxyHosts?: readonly ProviderNamespaceHost[];
56
+ /** The namespace's dev sandbox host, recorded once provisioned; absent while no dev environment uses the namespace. */
57
+ readonly sandboxHost?: ZeropsNamespaceSandboxHost;
58
+ readonly ready?: boolean;
59
+ }
60
+ export interface ZeropsNamespaceSandboxHost {
61
+ readonly serviceId: string;
62
+ /** The Box API origin: the service's public subdomain for `SANDBOX_HOST_API_PORT`. */
63
+ readonly apiOrigin: string;
64
+ }
65
+ export type ZeropsNamespacePolicy = Omit<ZeropsNamespaceTarget, 'proxySource'>;
66
+ export interface NormalizedZeropsNamespaceTarget extends ZeropsNamespaceTarget {
67
+ readonly projectName: string;
68
+ readonly corePackage: ZeropsProjectMode;
69
+ readonly publicAccess: ZeropsNamespacePublicAccess;
70
+ readonly managed: boolean;
71
+ readonly ready: boolean;
72
+ }
73
+ export interface ZeropsNamespaceOptions {
74
+ readonly proxySource: ZeropsNamespaceProxySource;
75
+ readonly source?: ZeropsSourcePort;
76
+ readonly clientId: string;
77
+ /** Public IAM origin reachable from an app project. */
78
+ readonly iamUrl: string;
79
+ /** Same credential IAM receives as `FABRIKA_IAM_PROXY_KEY`. */
80
+ readonly iamKey: string;
81
+ /** The installation's own project, which no namespace may create into or adopt. Absent until `platform deploy` writes it. */
82
+ readonly installationProjectId?: string;
83
+ readonly api: ZeropsApi;
84
+ /** The transport of the sandbox host's Box API; absent, the global `fetch`. */
85
+ readonly zboxFetch?: ZboxFetch;
86
+ readonly sleep?: Sleeper;
87
+ }
88
+ export interface ZeropsNamespaceTopology {
89
+ readonly source: ZeropsSourceTarget;
90
+ readonly createYaml: string;
91
+ readonly servicesProvisionYaml: string;
92
+ readonly servicesSteadyYaml: string;
93
+ }
94
+ export interface ZeropsNamespacePresetInput {
95
+ readonly proxySource: ZeropsNamespaceProxySource;
96
+ readonly preset: 'cheap' | 'mid' | 'full';
97
+ readonly env: string;
98
+ readonly projectName: string;
99
+ readonly corePackage?: ZeropsProjectMode;
100
+ readonly publicAccess?: ZeropsNamespacePublicAccess;
101
+ readonly postgres?: ZeropsNamespacePostgres;
102
+ }
103
+ export interface ZeropsNamespaceOperatorOptions {
104
+ readonly proxySource: ZeropsNamespaceProxySource;
105
+ }
106
+ export interface ZeropsNamespacePlanOptions {
107
+ readonly projectName?: string;
108
+ readonly corePackage?: ZeropsProjectMode;
109
+ readonly publicAccess?: ZeropsNamespacePublicAccess;
110
+ readonly postgres?: ZeropsNamespacePostgres;
111
+ }
@@ -0,0 +1,6 @@
1
+ import { type ProviderNamespaceUpdates } from '@fabrika/provider-contract';
2
+ import type { ZeropsNamespaceOptions } from './types';
3
+ /** The plan field of a re-pin, which moves only the stored target; the reconcile core queues rebuilds the proxy. */
4
+ export declare const ZEROPS_PROXY_SOURCE_FIELD = "proxySource";
5
+ /** Move a ready namespace's PostgreSQL service to another profile — the one field Zerops changes in place. */
6
+ export declare const createZeropsNamespaceUpdates: (options: ZeropsNamespaceOptions) => ProviderNamespaceUpdates;
@@ -0,0 +1,12 @@
1
+ import type { ZeropsService } from '../api';
2
+ /**
3
+ * The profile a service is checked against. `declared` is what the stored target says. `changingTo` is
4
+ * set only while an update moves the service, and `unconfirmed` while it retries an earlier update whose
5
+ * outcome is unknown: a live service already on either reads as the change in progress, not as drift.
6
+ */
7
+ export interface ZeropsExpectedProfile {
8
+ readonly declared?: string;
9
+ readonly changingTo?: string;
10
+ readonly unconfirmed?: string;
11
+ }
12
+ export declare const validateService: (service: ZeropsService, projectId: string, expectedBase: string, adopting: boolean, expectedPublic?: boolean, expectedProfile?: ZeropsExpectedProfile) => void;
@@ -0,0 +1,2 @@
1
+ import type { NamespaceCli } from '@fabrika/provider-contract/app-cli';
2
+ export declare const zeropsNamespaceCli: NamespaceCli;
@@ -0,0 +1,9 @@
1
+ export { zeropsNamespaceTargetCodec } from './namespace/codec';
2
+ export { ZEROPS_NAMESPACE_IAM_ISSUER_VARIABLE, ZEROPS_NAMESPACE_IAM_KEY_VARIABLE, ZEROPS_NAMESPACE_POSTGRES_HOSTNAME, ZEROPS_NAMESPACE_PROXY_HOSTNAME, ZEROPS_NAMESPACE_SUBDOMAIN_VARIABLE, ZEROPS_SHARED_POSTGRES_CONNECTION_STRING, } from './namespace/constants';
3
+ export { ZEROPS_NAMESPACE_CANCELLED, ZEROPS_NAMESPACE_LIFECYCLE, ZEROPS_PROXY_DEPLOY_FAILED, ZEROPS_PROXY_DEPLOY_TIMEOUT, ZEROPS_SUBDOMAIN_NOT_PUBLISHED, } from './namespace/errors';
4
+ export { createZeropsNamespaceOperator } from './namespace/operator';
5
+ export { createZeropsNamespaceCapabilities } from './namespace/provisioning';
6
+ export { republishProxy, type ZeropsProxyApi, type ZeropsProxyRepublishInput } from './namespace/proxy-attempt';
7
+ export { decodeZeropsNamespaceProxySource, verifyZeropsNamespaceProxySource } from './namespace/proxy-source';
8
+ export { compileZeropsNamespaceTopology, zeropsNamespacePreset } from './namespace/topology';
9
+ export type { ZeropsNamespaceOperatorOptions, ZeropsNamespaceOptions, ZeropsNamespacePlanOptions, ZeropsNamespacePostgres, ZeropsNamespacePresetInput, ZeropsNamespaceProxyBuild, ZeropsNamespaceProxyDeployment, ZeropsNamespaceProxySource, ZeropsNamespacePublicAccess, ZeropsNamespaceTarget, ZeropsNamespaceTopology, } from './namespace/types';
@@ -0,0 +1,11 @@
1
+ import { type FabrikaManifest } from './manifest';
2
+ export type ZeropsStepKind = 'apply-import' | 'verify-exposure' | 'write-service-env' | 'raise-start-memory' | 'size-database' | 'reserve-version' | 'upload-source' | 'trigger-build' | 'await-version';
3
+ export interface ZeropsStep {
4
+ readonly id: string;
5
+ readonly kind: ZeropsStepKind;
6
+ readonly description: string;
7
+ }
8
+ /** Resolve the one declared service that receives this repository's code. */
9
+ export declare const resolveDeployHostname: (manifest: FabrikaManifest) => string;
10
+ /** Build the provider-owned deploy order without touching the platform. */
11
+ export declare const buildZeropsPlan: (manifest: FabrikaManifest) => readonly ZeropsStep[];
@@ -0,0 +1,60 @@
1
+ import { type OperationsSourceMapUploadState } from '@fabrika/operations-contract/releases';
2
+ import { type DeployStepResult, type ProviderApprovedAccess, type ProviderDeployInput, type ProviderManagedEnvironment, type ProviderRunEvents } from '@fabrika/provider-contract';
3
+ import { type ZeropsService } from './api';
4
+ import { type ZeropsCollaboratorFactory, type ZeropsCollaborators } from './collaborators';
5
+ import { type FabrikaImportDocument, type FabrikaManifest } from './manifest';
6
+ import type { ZeropsRuntimeTarget } from './types';
7
+ export declare const CANCELLED = "deploy cancelled";
8
+ export interface ZeropsDeployRun {
9
+ readonly appId: string;
10
+ readonly env: string;
11
+ readonly secrets: Readonly<Record<string, string>>;
12
+ readonly vars: Readonly<Record<string, string>>;
13
+ /** Platform-owned runtime configuration, separate from operator-managed application vars. */
14
+ readonly managedEnvironment: ProviderManagedEnvironment;
15
+ readonly target: ZeropsRuntimeTarget;
16
+ readonly artifact: FabrikaManifest;
17
+ /** Control's approved access for the environment (ADR-0050); the lock-down and the IAM schema come from it. */
18
+ readonly access?: ProviderApprovedAccess;
19
+ /** The run-scoped source-map destination Control minted; the build uploads to it. */
20
+ readonly artifactUpload?: ProviderDeployInput['artifactUpload'];
21
+ readonly dryRun: boolean;
22
+ readonly signal: AbortSignal;
23
+ readonly events: ProviderRunEvents;
24
+ }
25
+ export interface ZeropsDeployResult {
26
+ readonly appId: string;
27
+ readonly env: string;
28
+ readonly status: 'succeeded' | 'failed';
29
+ readonly steps: readonly DeployStepResult[];
30
+ /** Whether the build's source maps reached Operations; absent when the run had no upload to make. */
31
+ readonly artifactState?: OperationsSourceMapUploadState;
32
+ }
33
+ /** A run stops waiting for its version this long after it started. Zerops' own pipeline limit is 1 hour. */
34
+ export declare const ZEROPS_VERSION_DEADLINE_MS: number;
35
+ /**
36
+ * Resolve the manifest's declared variables INTO THE DOCUMENT — never into the rendered YAML, where a
37
+ * value carrying a quote or a newline would be read as structure and could add a service or turn
38
+ * `envIsolation` off. Only variables the manifest declares resolve; every other placeholder fails the
39
+ * deploy, and so does a value that names a service outside the app (Zerops resolves `${host_KEY}`
40
+ * regardless of isolation). The document is re-checked here because this is the last point it is an object.
41
+ */
42
+ export declare function interpolateManifest(document: FabrikaImportDocument, declared: readonly string[], values: Record<string, string>, ownHostnames: readonly string[]): FabrikaImportDocument;
43
+ /** What raising a minimum RAM calls; the deploy's collaborators, and the live platform-facts probe of the same path. */
44
+ export interface MinRamRaise {
45
+ zerops: Pick<ZeropsCollaborators, 'api' | 'sleep'>;
46
+ signal: AbortSignal;
47
+ }
48
+ /**
49
+ * Sets `service`'s minimum RAM to `minRam` and answers the minimum it reads back. It sends the custom autoscaling it
50
+ * read WHOLE with only that field changed: the platform resets every field a request leaves out.
51
+ */
52
+ export declare const raiseMinRam: (env: MinRamRaise, service: ZeropsService, hostname: string, minRam: number, need: string) => Promise<number>;
53
+ /**
54
+ * Build a Zerops deployer over a specific collaborator FACTORY. Production passes the real one; tests pass
55
+ * `() => fakes`, which is the whole testability property — one seam, all of this driver's effects.
56
+ *
57
+ * A factory rather than a bundle because the Zerops client is authenticated with a token that lives on the
58
+ * run's target, so it cannot be constructed once at module load the way Cloudflare's bundle is.
59
+ */
60
+ export declare const createZeropsDeployer: (collaborators?: ZeropsCollaboratorFactory) => (run: ZeropsDeployRun) => Promise<ZeropsDeployResult>;
@@ -0,0 +1,37 @@
1
+ /** The path of the proxy manifest in the build archive: the archive's one data file (ADR-0045), read by the proxy build. */
2
+ export declare const ZEROPS_PROXY_MANIFEST_PATH = "proxy.manifest.json";
3
+ /**
4
+ * How a proxy build receives its manifest.
5
+ *
6
+ * - `environment`: the build lifts `FABRIKA_PROXY_MANIFEST_JSON` from the service and writes it to the file, as every
7
+ * release before the archive carrier did. A namespace pinned to such a commit keeps its descriptor (ADR-0045), so it
8
+ * gets the variable, bound by the Zerops value limit.
9
+ * - `archive`: the build reads the file the uploaded archive carries.
10
+ */
11
+ export type ZeropsProxyManifestCarrier = 'environment' | 'archive';
12
+ /**
13
+ * The carrier a descriptor's proxy setup reads. Decided by the build section Zerops applies (the selected setup's, else
14
+ * the nearest one it `extends`): a lifted `FABRIKA_PROXY_MANIFEST_JSON` would overwrite an archived file, so it wins.
15
+ */
16
+ export declare const zeropsProxyManifestCarrier: (descriptorContents: string, setup?: string) => ZeropsProxyManifestCarrier;
17
+ /** The build variable that marks a proxy source whose manifest parser knows `brand` (ADR-0066). */
18
+ export declare const FABRIKA_PROXY_MANIFEST_BRAND = "FABRIKA_PROXY_MANIFEST_BRAND";
19
+ /** The build variable that marks a proxy source whose manifest parser knows a dev sandbox entry's `audience` and `upstreamHost`. */
20
+ export declare const FABRIKA_PROXY_MANIFEST_SANDBOXES = "FABRIKA_PROXY_MANIFEST_SANDBOXES";
21
+ /**
22
+ * The value a source that serves dev sandboxes declares. `2`: its sandbox hop also drops the `X-Forwarded-For` Caddy adds,
23
+ * which the Box router refuses on a `project` port; a `1` source parses the entries but every request to them fails.
24
+ */
25
+ export declare const FABRIKA_PROXY_MANIFEST_SANDBOXES_VALUE = "2";
26
+ /**
27
+ * Whether a pinned descriptor's proxy reads a manifest that carries the installation's client logo. An older parser
28
+ * refuses the unknown key and fails the build, so a namespace kept on such a pin gets no logo and keeps the fabrika
29
+ * mark until it is re-pinned (`--proxy-source=current`).
30
+ */
31
+ export declare const zeropsProxyAcceptsBrand: (descriptorContents: string, setup?: string) => boolean;
32
+ /**
33
+ * Whether a pinned descriptor's proxy serves dev sandbox entries. An older parser refuses their `audience` and
34
+ * `upstreamHost` and fails the build, and a `1` source reaches no sandbox, so a namespace on either pin serves no
35
+ * sandbox until it is re-pinned.
36
+ */
37
+ export declare const zeropsProxyAcceptsSandboxes: (descriptorContents: string, setup?: string) => boolean;
@@ -0,0 +1,28 @@
1
+ import type { Sleeper } from '../collaborators';
2
+ import { type ZboxClient } from '../zbox';
3
+ /** Every file of the build context; nothing else in the directory is sent. The scripts under `bin/` ship with each deploy. */
4
+ export declare const SANDBOX_BASE_CONTEXT_FILES: readonly ["Dockerfile", "init.sh"];
5
+ /** The first 12 hex of a sha256 over named files: the same bytes give the same version on every installation. */
6
+ export declare function contentVersion(files: Readonly<Record<string, Uint8Array>>): string;
7
+ /** Reads `names` from the directory `relative` to the package's `sandbox/`. */
8
+ export declare function readSandboxFiles(relative: string, names: readonly string[]): Promise<Record<string, Uint8Array>>;
9
+ export interface SandboxBaseContext {
10
+ /** `fabrika-dev-<first 12 hex of the context's sha256>`. */
11
+ readonly name: string;
12
+ readonly files: Readonly<Record<string, Uint8Array>>;
13
+ }
14
+ /** The name of the base a context builds: the same bytes name the same base on every installation. */
15
+ export declare function sandboxBaseName(files: Readonly<Record<string, Uint8Array>>): string;
16
+ /** The context this package ships. */
17
+ export declare function readSandboxBaseContext(): Promise<SandboxBaseContext>;
18
+ /** The context as the plain tar archive `POST /base-build` takes. */
19
+ export declare function sandboxBaseArchive(context: SandboxBaseContext): Promise<Uint8Array<ArrayBuffer>>;
20
+ export interface EnsureSandboxBaseOptions {
21
+ readonly signal: AbortSignal;
22
+ readonly sleep: Sleeper;
23
+ }
24
+ /**
25
+ * The digest of the context's base on the sandbox host: the one it holds READY, or one this call builds. A base that
26
+ * FAILED is refused rather than rebuilt over, so the failure is seen once instead of retried on every workspace.
27
+ */
28
+ export declare function ensureSandboxBase(client: ZboxClient, context: SandboxBaseContext, options: EnsureSandboxBaseOptions): Promise<string>;
@@ -0,0 +1,30 @@
1
+ /** The application root inside a sandbox: what a deploy extracts the source into and the launcher runs from. */
2
+ export declare const SANDBOX_APP_ROOT = "/app";
3
+ /** State that survives a re-bootstrap, which replaces only the application root. */
4
+ export declare const SANDBOX_STATE_DIR = "/var/lib/fabrika";
5
+ /** The launcher's environment, written 0600 through the file API: the one way a credential reaches a sandbox process. */
6
+ export declare const SANDBOX_ENV_FILE = "/var/lib/fabrika/env";
7
+ /** The generated build script; it holds no credential, and the build reads none. */
8
+ export declare const SANDBOX_BUILD_SCRIPT = "/var/lib/fabrika/build.sh";
9
+ /** Where the source archive lands before it is extracted. */
10
+ export declare const SANDBOX_SOURCE_ARCHIVE = "/tmp/fabrika-source.tar.gz";
11
+ /** The base image's PID 1: PostgreSQL, then the launcher when a deploy left one. Every other script is uploaded. */
12
+ export declare const SANDBOX_INIT_COMMAND: readonly string[];
13
+ /** Where each deploy uploads the helper scripts, one directory per version; `current` names the one in use. */
14
+ export declare const SANDBOX_BIN_DIR = "/var/lib/fabrika/bin";
15
+ export declare const SANDBOX_BIN_POINTER = "/var/lib/fabrika/bin/current";
16
+ /** The launcher's output, which only root reads. */
17
+ export declare const SANDBOX_LAUNCHER_LOG = "/var/lib/fabrika/launcher.log";
18
+ /**
19
+ * The database the launcher provisions with: the sandbox's local superuser. The deploy writes it without a password;
20
+ * `run-launcher.sh` adds the password, which stays in the sandbox in a file only root reads.
21
+ */
22
+ export declare const SANDBOX_DATABASE_URL = "postgres://postgres@127.0.0.1:5432/postgres";
23
+ /** The local superuser's password, which `postgres-auth.sh` generates and `run-launcher.sh` adds to that URL. */
24
+ export declare const SANDBOX_DATABASE_PASSWORD_FILE = "/var/lib/fabrika/postgres-password";
25
+ /** The connections each process opens: one launcher, one application and a migration share a local PostgreSQL of 100. */
26
+ export declare const SANDBOX_DATABASE_CONNECTIONS = 10;
27
+ /** The size of one workspace sandbox. */
28
+ export declare const SANDBOX_CPUS = 2;
29
+ export declare const SANDBOX_MEMORY_BYTES: number;
30
+ export declare const SANDBOX_DISK_BYTES: number;
@@ -0,0 +1,75 @@
1
+ import { type DeployStepResult, type JsonValue, type ProviderApprovedAccess, type ProviderManagedEnvironment, type ProviderRunEvents } from '@fabrika/provider-contract';
2
+ import type { Sleeper } from '../collaborators';
3
+ import type { FabrikaManifest } from '../manifest';
4
+ import type { ZeropsSourcePort, ZeropsSourcePrivateBinding } from '../source/port';
5
+ import type { ZeropsSourceRepository } from '../source/types';
6
+ import type { ZboxClient } from '../zbox';
7
+ import { type SandboxScripts } from './scripts';
8
+ /** How long the launcher has to report its boot: the readiness window of a Zerops dev container. */
9
+ export declare const SANDBOX_BOOT_DEADLINE_MS = 180000;
10
+ /** The run checkpoint of a sandbox deploy: credential-free coordinates, read back only to settle the run failed. */
11
+ export interface ZeropsSandboxRunState {
12
+ readonly sandboxId: string;
13
+ readonly runId: string;
14
+ readonly buildSessionId?: string;
15
+ }
16
+ export declare const sandboxExternalId: (state: Pick<ZeropsSandboxRunState, "sandboxId" | "runId">) => string;
17
+ /** The sandbox checkpoint recorded for exactly this external id, or null. */
18
+ export declare function parseSandboxCheckpoint(input: {
19
+ readonly providerState?: JsonValue;
20
+ readonly externalId: string;
21
+ }): ZeropsSandboxRunState | null;
22
+ export interface ZeropsSandboxDeployRun {
23
+ readonly appId: string;
24
+ readonly env: string;
25
+ readonly runId: string;
26
+ readonly artifact: FabrikaManifest;
27
+ readonly access: ProviderApprovedAccess | undefined;
28
+ readonly vars: Readonly<Record<string, string>>;
29
+ readonly secrets: Readonly<Record<string, string>>;
30
+ readonly managedEnvironment: ProviderManagedEnvironment;
31
+ /** Absent on a dry run, which resolves no source. */
32
+ readonly source?: {
33
+ readonly repository: ZeropsSourceRepository;
34
+ readonly commitSha: string;
35
+ readonly privateBinding?: ZeropsSourcePrivateBinding;
36
+ };
37
+ readonly sandbox: {
38
+ readonly sandboxId: string;
39
+ /** The sandbox host's API origin; the source upload goes to its file endpoint. */
40
+ readonly apiOrigin: string;
41
+ /** A credential in transit: the bearer of the source upload. Never logged, persisted or put in an argument. */
42
+ readonly sandboxKey: string;
43
+ };
44
+ readonly client: ZboxClient;
45
+ readonly sourcePort: ZeropsSourcePort;
46
+ readonly sleep: Sleeper;
47
+ readonly dryRun: boolean;
48
+ readonly signal: AbortSignal;
49
+ readonly events: ProviderRunEvents;
50
+ /** The helper scripts to upload; the ones this package ships unless a test passes others. */
51
+ readonly scripts?: SandboxScripts;
52
+ }
53
+ export interface ZeropsSandboxDeployResult {
54
+ readonly status: 'succeeded' | 'failed';
55
+ readonly steps: readonly DeployStepResult[];
56
+ }
57
+ /** The source's file endpoint for one sandbox, written exactly as a URL parser writes it (Control compares). */
58
+ export declare const sandboxSourceUploadUrl: (apiOrigin: string, sandboxId: string) => string;
59
+ /**
60
+ * Relays a session's cumulative output: only the bytes past what it relayed. A read that no longer holds the relayed
61
+ * bytes where they were (the host cut its buffer) is reported once per cut and relaying resumes at its end.
62
+ */
63
+ export declare class SessionOutputRelay {
64
+ private readonly log;
65
+ private relayed;
66
+ private window;
67
+ private readonly lines;
68
+ constructor(log: (line: string) => void, secrets: readonly string[]);
69
+ /** How many bytes the session has produced, as far as this relay knows. */
70
+ get size(): number;
71
+ accept(output: Uint8Array): void;
72
+ flush(): void;
73
+ }
74
+ /** Deploy one workspace's sandbox. Refusals throw before any step; a step failure fails the run. */
75
+ export declare function deploySandbox(run: ZeropsSandboxDeployRun): Promise<ZeropsSandboxDeployResult>;
@@ -0,0 +1,51 @@
1
+ import { type DevLauncherConfig } from '@fabrika/auth-core';
2
+ import type { ProviderManagedEnvironment } from '@fabrika/provider-contract';
3
+ import { type ZeropsContractRun } from '../execution';
4
+ import { type FabrikaManifest } from '../manifest';
5
+ /** Refuse what a sandbox cannot give an application, one line each: object storage, the ClamAV scan, runtime packages. */
6
+ export declare function assertSandboxArtifact(manifest: FabrikaManifest, contract?: Pick<ZeropsContractRun, 'scan'> | undefined): void;
7
+ /**
8
+ * Replaces each value of `values` long enough to be a credential in `text`, longest first: what the sandbox prints is
9
+ * application output, which may echo one. The launcher masks its own log the same way.
10
+ */
11
+ export declare function maskValues(text: string, values: readonly string[]): string;
12
+ /** Refuse a handed variable or secret whose value holds a `${…}` reference, naming it and never its value. */
13
+ export declare function assertNoSandboxReferences(kind: 'variable' | 'secret', values: Readonly<Record<string, string>>): void;
14
+ export interface SandboxEnvironmentInput {
15
+ readonly artifact: FabrikaManifest;
16
+ readonly secrets: Readonly<Record<string, string>>;
17
+ readonly managed: ProviderManagedEnvironment;
18
+ readonly contractDigest: string;
19
+ }
20
+ /**
21
+ * The launcher's environment, as a Zerops deploy composes a service's: the secrets (on Zerops, sensitive service
22
+ * variables), the managed values Control handed, then the literals the generated run section carries. A declared variable
23
+ * only fills the import document, which a sandbox has none of. The local superuser stands in for the database service's,
24
+ * as the provisioning credential of the application's role family (ADR-0017).
25
+ */
26
+ export declare function sandboxEnvironment(input: SandboxEnvironmentInput): Record<string, string>;
27
+ /** The env file the base image's launcher script sources with `set -a`: one single-quoted assignment per variable. */
28
+ export declare function renderSandboxEnvFile(environment: Readonly<Record<string, string>>): string;
29
+ /** The authored SPA commands of the artifact's selected setup: the only part of the authored build that survives. */
30
+ export declare function authoredSpaCommands(artifact: FabrikaManifest): string[];
31
+ export interface SandboxRecipeInput {
32
+ readonly appId: string;
33
+ readonly checkRelease: string;
34
+ readonly contract: ZeropsContractRun;
35
+ }
36
+ /** `@fabrika/app/build`'s recipe in a sandbox: built and run in place, with no database at build, as on Zerops. */
37
+ export declare const sandboxRecipe: (input: SandboxRecipeInput) => import("@fabrika/app/build").ContractRecipe;
38
+ /** What the dev launcher reads (`DEV_LAUNCHER_CONFIG_FILE`), written after the build's checks passed. */
39
+ export declare function sandboxLauncherConfig(input: SandboxRecipeInput & {
40
+ readonly head: string;
41
+ readonly spaBuild: readonly string[];
42
+ }): DevLauncherConfig;
43
+ export declare const SANDBOX_LAUNCHER_CONFIG_PATH = "/app/fabrika/dev.generated.json";
44
+ /**
45
+ * The generated part of the build, run as root: it writes each step to its own file (the authored SPA commands, then
46
+ * the recipe's steps), checks each was written whole, and hands over to the uploaded runner, which runs them as the
47
+ * unprivileged build user. Nothing here holds a credential.
48
+ */
49
+ export declare function renderSandboxBuildScript(authoredSpa: readonly string[], recipe: ReturnType<typeof sandboxRecipe>, runner: string): string;
50
+ /** One line per build step, as the run log lists them before the build starts. */
51
+ export declare function sandboxBuildStepLabels(authoredSpa: readonly string[], recipe: ReturnType<typeof sandboxRecipe>): string[];
@@ -0,0 +1,27 @@
1
+ import { type ProviderDevSandboxes, type ProviderEnvironment } from '@fabrika/provider-contract';
2
+ import type { Sleeper } from '../collaborators';
3
+ import { type ZboxClient, type ZboxSandbox } from '../zbox';
4
+ import { type SandboxBaseContext } from './base-image';
5
+ /** The sandbox name of a workspace: what `ensure` finds it again by. */
6
+ export declare function sandboxName(workspaceId: string): string;
7
+ /** A deterministic `Idempotency-Key` in UUID form: the same delete after a lost answer gets Box's first answer. */
8
+ export declare function sandboxIdempotencyKey(...parts: readonly string[]): string;
9
+ /** A full sandbox host is the operator's to relieve, so it surfaces as the contract's capacity code. */
10
+ export declare function withSandboxCapacity<T>(run: () => Promise<T>): Promise<T>;
11
+ export interface ZeropsDevSandboxesOptions {
12
+ /** The Box client of the environment's namespace sandbox host, authenticated with `sandboxKey`. */
13
+ /** Null while the namespace has no sandbox host yet. */
14
+ readonly client: (environment: ProviderEnvironment, sandboxKey: string) => ZboxClient | null;
15
+ /** Refuses an environment whose placement cannot serve a workspace sandbox; see `ProviderDevSandboxes.admit`. */
16
+ readonly admit: (environment: ProviderEnvironment) => void;
17
+ readonly sleep: Sleeper;
18
+ /** Where `ensure` says it replaced a dead sandbox: the seam has no run log outside a run. */
19
+ readonly log: (line: string) => void;
20
+ /** The base image's build context; the one this package ships unless a test passes another. */
21
+ readonly baseContext?: () => Promise<SandboxBaseContext>;
22
+ }
23
+ /** Wait out a transition; answers the sandbox in a settled state. */
24
+ export declare function settledSandbox(client: ZboxClient, sandbox: ZboxSandbox, sleep: Sleeper, signal: AbortSignal): Promise<ZboxSandbox>;
25
+ /** The sandbox running: a parked one is woken, a transition waited out. */
26
+ export declare function runningSandbox(client: ZboxClient, sandboxId: string, sleep: Sleeper, signal: AbortSignal): Promise<ZboxSandbox>;
27
+ export declare function createZeropsDevSandboxes(options: ZeropsDevSandboxesOptions): ProviderDevSandboxes;
@@ -0,0 +1,11 @@
1
+ export declare const SANDBOX_SCRIPT_FILES: readonly ["postgres-auth.sh", "reset.sh", "run-build.sh", "run-launcher.sh", "start-launcher.sh", "stop.sh"];
2
+ export type SandboxScript = (typeof SANDBOX_SCRIPT_FILES)[number];
3
+ export interface SandboxScripts {
4
+ readonly version: string;
5
+ readonly files: Readonly<Record<string, Uint8Array>>;
6
+ /** The absolute path of a script of this version inside a sandbox. */
7
+ path(script: SandboxScript): string;
8
+ }
9
+ export declare function sandboxScripts(files: Readonly<Record<string, Uint8Array>>): SandboxScripts;
10
+ /** The scripts this package ships. */
11
+ export declare function readSandboxScripts(): Promise<SandboxScripts>;
@@ -0,0 +1,16 @@
1
+ /** The hostname of a namespace's dev sandbox host: a Zerops Box Workspace, which runs one sandbox per MCP workspace. */
2
+ export declare const SANDBOX_HOST_HOSTNAME = "zbox";
3
+ /** The type an import declares. */
4
+ export declare const SANDBOX_HOST_TYPE = "zbox@1";
5
+ /** The type the platform reads back for it (measured live): the OS-qualified form of `SANDBOX_HOST_TYPE`. */
6
+ export declare const SANDBOX_HOST_SERVICE_TYPE = "ubuntu/zbox@1";
7
+ /** The Box API port. Control reaches it over the service's public subdomain, with the key Fabrika generated for it. */
8
+ export declare const SANDBOX_HOST_API_PORT = 8080;
9
+ /** The Box router port: the namespace proxy reaches a sandbox's project-only application port here, by Host. */
10
+ export declare const SANDBOX_HOST_ROUTER_PORT = 8081;
11
+ /** The service variable Box reads its API key from; Fabrika writes it sensitive and never reads it back. */
12
+ export declare const SANDBOX_HOST_KEY_VARIABLE = "ZBOX_WORKSPACE_API_KEY";
13
+ /** The dial address of the Box router from the namespace proxy. */
14
+ export declare const SANDBOX_UPSTREAM = "zbox:8081";
15
+ /** The Host the namespace proxy sends the Box router to reach a sandbox's application port: the bare form, no domain. */
16
+ export declare function sandboxUpstreamHost(sandboxId: string): string;