@fabrika/provider-zerops 0.9.0-dev.8 → 0.9.0-dev.9

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 (68) hide show
  1. package/package.json +11 -10
  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 +3 -1
  11. package/src/api/errors.ts +7 -3
  12. package/src/control.ts +150 -35
  13. package/src/execution.ts +12 -77
  14. package/src/installation/topology/setups.ts +3 -1
  15. package/src/installation/topology/topology.ts +1 -1
  16. package/src/manifest.ts +2 -7
  17. package/src/namespace/claims.ts +4 -0
  18. package/src/namespace/codec.ts +17 -0
  19. package/src/namespace/errors.ts +24 -0
  20. package/src/namespace/manifest.ts +31 -5
  21. package/src/namespace/provisioning.ts +68 -112
  22. package/src/namespace/proxy-reads.ts +16 -1
  23. package/src/namespace/proxy-secrets.ts +18 -5
  24. package/src/namespace/sandbox-host.ts +236 -0
  25. package/src/namespace/subdomain.ts +113 -0
  26. package/src/namespace/topology.ts +1 -1
  27. package/src/namespace/types.ts +11 -0
  28. package/src/namespace/update.ts +1 -0
  29. package/src/provider.ts +0 -40
  30. package/src/proxy-manifest-carrier.ts +21 -7
  31. package/src/sandbox/base-image.ts +100 -0
  32. package/src/sandbox/constants.ts +43 -0
  33. package/src/sandbox/deploy.ts +471 -0
  34. package/src/sandbox/dev-artifact.ts +206 -0
  35. package/src/sandbox/lifecycle.ts +200 -0
  36. package/src/sandbox/scripts.ts +26 -0
  37. package/src/sandbox-host.ts +31 -0
  38. package/src/source/port.ts +5 -0
  39. package/src/zbox/client.ts +267 -0
  40. package/src/zbox/errors.ts +45 -0
  41. package/src/zbox/index.ts +23 -0
  42. package/src/zbox/types.ts +168 -0
  43. package/types/src/api/errors.d.ts +3 -1
  44. package/types/src/control.d.ts +12 -1
  45. package/types/src/execution.d.ts +2 -13
  46. package/types/src/installation/topology/topology.d.ts +1 -1
  47. package/types/src/manifest.d.ts +3 -8
  48. package/types/src/namespace/codec.d.ts +18 -0
  49. package/types/src/namespace/errors.d.ts +12 -0
  50. package/types/src/namespace/proxy-reads.d.ts +6 -1
  51. package/types/src/namespace/proxy-secrets.d.ts +1 -1
  52. package/types/src/namespace/sandbox-host.d.ts +23 -0
  53. package/types/src/namespace/subdomain.d.ts +43 -0
  54. package/types/src/namespace/types.d.ts +10 -0
  55. package/types/src/provider.d.ts +0 -3
  56. package/types/src/proxy-manifest-carrier.d.ts +8 -1
  57. package/types/src/sandbox/base-image.d.ts +28 -0
  58. package/types/src/sandbox/constants.d.ts +29 -0
  59. package/types/src/sandbox/deploy.d.ts +75 -0
  60. package/types/src/sandbox/dev-artifact.d.ts +51 -0
  61. package/types/src/sandbox/lifecycle.d.ts +27 -0
  62. package/types/src/sandbox/scripts.d.ts +11 -0
  63. package/types/src/sandbox-host.d.ts +18 -0
  64. package/types/src/source/port.d.ts +5 -0
  65. package/types/src/zbox/client.d.ts +2 -0
  66. package/types/src/zbox/errors.d.ts +25 -0
  67. package/types/src/zbox/index.d.ts +3 -0
  68. package/types/src/zbox/types.d.ts +462 -0
@@ -10,6 +10,18 @@ export declare const ZEROPS_PROXY_DEPLOY_TIMEOUT = "proxyDeployTimeout";
10
10
  export declare const ZEROPS_PROXY_DEPLOY_FAILED = "proxyDeployFailed";
11
11
  export declare const ZEROPS_SUBDOMAIN_NOT_PUBLISHED = "subdomainNotPublished";
12
12
  export declare const ZEROPS_SOURCE_RATE_LIMITED = "githubRateLimited";
13
+ /** A dev sandbox entry would be published to a namespace whose pinned proxy cannot parse one. */
14
+ export declare const ZEROPS_PROXY_SANDBOXES_UNSUPPORTED = "proxySandboxesUnsupported";
15
+ /** A sandbox host was asked of a namespace that serves no custom domain, which a dev environment's wildcard needs. */
16
+ export declare const ZEROPS_SANDBOX_HOST_UNSUPPORTED = "sandboxHostUnsupported";
17
+ /** The Box API did not accept the namespace's key after the service restarted with it. */
18
+ export declare const ZEROPS_SANDBOX_HOST_KEY_REFUSED = "sandboxHostKeyRefused";
19
+ /** The Box API answered a request that carried no key, even after a restart with the namespace's key. */
20
+ export declare const ZEROPS_SANDBOX_HOST_API_OPEN = "sandboxHostApiOpen";
21
+ /** A dev environment an older release registered with its own Zerops service, which runs in no sandbox. */
22
+ export declare const ZEROPS_DEV_TARGET_RETIRED = "devTargetRetired";
23
+ /** The sandbox host already routes the proxy's sandbox domain in the other form. */
24
+ export declare const ZEROPS_SANDBOX_HOST_DOMAIN_FORM = "sandboxHostDomainForm";
13
25
  export declare const namespaceError: (code: string, message: string, retryable: boolean, detail?: string) => ProviderNamespaceError;
14
26
  /** Every namespace lifecycle failure leaves this provider as one typed, coded error. */
15
27
  export declare const asNamespaceError: (cause: unknown, mode: "provision" | "reconcile" | "update" | "claim check") => ProviderNamespaceError;
@@ -1,4 +1,4 @@
1
- import type { ProviderApprovedAccess } from '@fabrika/provider-contract';
1
+ import { type ProviderApprovedAccess } from '@fabrika/provider-contract';
2
2
  import { type OlderProxyReaders } from '@fabrika/proxy-core/manifest';
3
3
  import type { ZeropsNamespaceProxySource } from './types';
4
4
  export type { OlderProxyReader, OlderProxyReaders } from '@fabrika/proxy-core/manifest';
@@ -20,3 +20,8 @@ export interface PlatformProxies {
20
20
  * namespace proxy, which then has nothing to compare.
21
21
  */
22
22
  export declare function assertNamespaceProxyReads(namespace: string, access: ProviderApprovedAccess | undefined, pinned: ZeropsNamespaceProxySource, platform: PlatformProxies | undefined): void;
23
+ /**
24
+ * Refuses dev sandbox entries for a namespace whose pinned proxy cannot parse their `audience` and `upstreamHost`: its
25
+ * strict parser would fail the proxy build. The row and CSP judges above see neither field, so this marker is their gate.
26
+ */
27
+ export declare function assertNamespaceProxyAcceptsSandboxes(namespace: string, pinned: ZeropsNamespaceProxySource): void;
@@ -2,7 +2,7 @@ import type { ProviderNamespaceMember } from '@fabrika/provider-contract';
2
2
  import { type ProxyManifest } from '@fabrika/proxy-core/manifest';
3
3
  /**
4
4
  * The proxy service variables a manifest needs: for each contract application, the secret Caddy sends it
5
- * (ADR-0022 rule 5), keyed by `proxySecretVariable`. A contract member without a secret is refused, because
5
+ * (ADR-0022 rule 5), keyed by `proxySecretVariable`. A contract entry without a secret is refused, because
6
6
  * its application would refuse every request the proxy sends.
7
7
  */
8
8
  export declare function namespaceProxySecrets(manifest: ProxyManifest, members: readonly ProviderNamespaceMember[]): ReadonlyMap<string, string>;
@@ -0,0 +1,23 @@
1
+ import { type ZeropsApi } from '../api';
2
+ import { type Sleeper } from '../collaborators';
3
+ import { type ZboxFetch } from '../zbox';
4
+ import type { NormalizedZeropsNamespaceTarget, ZeropsNamespaceSandboxHost } from './types';
5
+ export type ZeropsSandboxHostApi = Pick<ZeropsApi, 'listProjectServices' | 'importServices' | 'getProcess' | 'getService' | 'putServiceEnv' | 'startService' | 'stopService' | 'enableSubdomainAccess' | 'listServiceEnv'>;
6
+ export interface ZeropsSandboxHostInput {
7
+ readonly namespaceId: string;
8
+ readonly target: NormalizedZeropsNamespaceTarget;
9
+ /** The Box API key Control composed from its vault; written to the service, sent as a bearer, never read back. */
10
+ readonly sandboxKey: string;
11
+ readonly api: ZeropsSandboxHostApi;
12
+ readonly zboxFetch?: ZboxFetch;
13
+ readonly sleep?: Sleeper;
14
+ readonly signal: AbortSignal;
15
+ }
16
+ /** A sandbox host on a `zerops-subdomain` namespace is refused: a dev environment's wildcard needs a custom domain. */
17
+ export declare const assertSandboxHostAllowed: (namespaceId: string, target: NormalizedZeropsNamespaceTarget) => void;
18
+ /**
19
+ * Bring the namespace's sandbox host to what a dev environment needs: the `zbox` service, its key, its API subdomain,
20
+ * and the DOT domain the namespace proxy routes sandboxes by. Each step decides by reading back, so a reconcile
21
+ * converges a host any earlier attempt left half done and changes nothing on a complete one.
22
+ */
23
+ export declare const ensureSandboxHost: (input: ZeropsSandboxHostInput) => Promise<ZeropsNamespaceSandboxHost>;
@@ -0,0 +1,43 @@
1
+ import type { ProviderNamespaceHost } from '@fabrika/provider-contract';
2
+ import { type ZeropsApi } from '../api';
3
+ import { type Sleeper } from '../collaborators';
4
+ /**
5
+ * One host per published HTTP port, out of the newline-separated URLs the platform writes.
6
+ *
7
+ * The form is `<hostname>-<hash>-<port>.<region>.zerops.app` (e.g. `proxy-2ec8-8080`). Read as URLs
8
+ * rather than split on `-`, so a hostname whose own first label ends in digits cannot be misread; a line
9
+ * that is not a URL, or whose first label carries no trailing port — the single portless line a proxy
10
+ * that has never deployed publishes — is skipped rather than guessed at.
11
+ */
12
+ export declare const parseZeropsSubdomainHosts: (value: string) => ProviderNamespaceHost[];
13
+ /** The hosts a service publishes, off the platform-owned `zeropsSubdomain` variable; none while it names none. */
14
+ export declare const readSubdomainHosts: (api: Pick<ZeropsApi, "listServiceEnv">, serviceId: string, signal: AbortSignal) => Promise<ProviderNamespaceHost[]>;
15
+ export interface SubdomainAccessInput {
16
+ readonly api: Pick<ZeropsApi, 'getService' | 'enableSubdomainAccess'>;
17
+ readonly serviceId: string;
18
+ /** Names the service in a refusal, e.g. `Zerops namespace proxy`. */
19
+ readonly label: string;
20
+ /** What is missing when the subdomain stays off, e.g. `the namespace has no public entry point`. */
21
+ readonly consequence: string;
22
+ readonly sleep?: Sleeper;
23
+ readonly signal: AbortSignal;
24
+ }
25
+ /**
26
+ * Publish a service on its `*.zerops.app` subdomain — the ONE thing the import document cannot do.
27
+ *
28
+ * `enableSubdomainAccess: true` is accepted by the import and then silently dropped, on a service the
29
+ * document CREATES as much as on one `override` leaves alone; a service imported with it reads back
30
+ * `subdomainAccess: false` for ever. The subdomain is established by
31
+ * `PUT /service-stack/{id}/enable-subdomain-access` and by nothing else, and that call needs a DEPLOYED
32
+ * HTTP port.
33
+ *
34
+ * It runs on RECONCILE too, so a subdomain someone turned off in the GUI comes back, and it either
35
+ * observes `subdomainAccess === true` or throws naming what is missing.
36
+ *
37
+ * The decision is the READ-BACK, never the call returning. On an already-published service the platform
38
+ * answers 2xx and then fails the process it handed back — live-verified — so a 2xx proves nothing.
39
+ *
40
+ * The HTTP ports lag the service's ACTIVE version, so `serviceStackIsNotHttp` is retried for a bounded
41
+ * window (`enableSubdomainAccessWhenHttp`) before it fails the namespace.
42
+ */
43
+ export declare const ensureSubdomainAccess: (input: SubdomainAccessInput) => Promise<void>;
@@ -5,6 +5,7 @@ import type { ZeropsArtifactSourceDescriptor } from '../manifest';
5
5
  import type { ZeropsSourceRepository } from '../source';
6
6
  import type { ZeropsSourcePort } from '../source/port';
7
7
  import type { ZeropsSourceTarget } from '../types';
8
+ import type { ZboxFetch } from '../zbox';
8
9
  export type ZeropsNamespacePublicAccess = 'custom-domain' | 'zerops-subdomain';
9
10
  export interface ZeropsNamespaceProxySource {
10
11
  readonly repository: ZeropsSourceRepository;
@@ -52,8 +53,15 @@ export interface ZeropsNamespaceTarget {
52
53
  readonly proxyAppVersionId?: string;
53
54
  /** The hosts the published proxy answers on, recorded once so a namespace read needs no platform call. */
54
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;
55
58
  readonly ready?: boolean;
56
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
+ }
57
65
  export type ZeropsNamespacePolicy = Omit<ZeropsNamespaceTarget, 'proxySource'>;
58
66
  export interface NormalizedZeropsNamespaceTarget extends ZeropsNamespaceTarget {
59
67
  readonly projectName: string;
@@ -73,6 +81,8 @@ export interface ZeropsNamespaceOptions {
73
81
  /** The installation's own project, which no namespace may create into or adopt. Absent until `platform deploy` writes it. */
74
82
  readonly installationProjectId?: string;
75
83
  readonly api: ZeropsApi;
84
+ /** The transport of the sandbox host's Box API; absent, the global `fetch`. */
85
+ readonly zboxFetch?: ZboxFetch;
76
86
  readonly sleep?: Sleeper;
77
87
  }
78
88
  export interface ZeropsNamespaceTopology {
@@ -2,7 +2,6 @@ import { type OperationsSourceMapUploadState } from '@fabrika/operations-contrac
2
2
  import { type DeployStepResult, type ProviderApprovedAccess, type ProviderDeployInput, type ProviderManagedEnvironment, type ProviderRunEvents } from '@fabrika/provider-contract';
3
3
  import { type ZeropsService } from './api';
4
4
  import { type ZeropsCollaboratorFactory, type ZeropsCollaborators } from './collaborators';
5
- import { type ZeropsDevExecution } from './execution';
6
5
  import { type FabrikaImportDocument, type FabrikaManifest } from './manifest';
7
6
  import type { ZeropsRuntimeTarget } from './types';
8
7
  export declare const CANCELLED = "deploy cancelled";
@@ -19,8 +18,6 @@ export interface ZeropsDeployRun {
19
18
  readonly access?: ProviderApprovedAccess;
20
19
  /** The run-scoped source-map destination Control minted; the build uploads to it. */
21
20
  readonly artifactUpload?: ProviderDeployInput['artifactUpload'];
22
- /** Present for an environment of kind `dev`: the launcher starts instead of the serving entry, on one container. */
23
- readonly dev?: ZeropsDevExecution;
24
21
  readonly dryRun: boolean;
25
22
  readonly signal: AbortSignal;
26
23
  readonly events: ProviderRunEvents;
@@ -16,9 +16,16 @@ export type ZeropsProxyManifestCarrier = 'environment' | 'archive';
16
16
  export declare const zeropsProxyManifestCarrier: (descriptorContents: string, setup?: string) => ZeropsProxyManifestCarrier;
17
17
  /** The build variable that marks a proxy source whose manifest parser knows `brand` (ADR-0066). */
18
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";
19
21
  /**
20
22
  * Whether a pinned descriptor's proxy reads a manifest that carries the installation's client logo. An older parser
21
23
  * refuses the unknown key and fails the build, so a namespace kept on such a pin gets no logo and keeps the fabrika
22
- * mark until it is re-pinned (`--proxy-source=current`). Decided by the build section Zerops applies, as the carrier is.
24
+ * mark until it is re-pinned (`--proxy-source=current`).
23
25
  */
24
26
  export declare const zeropsProxyAcceptsBrand: (descriptorContents: string, setup?: string) => boolean;
27
+ /**
28
+ * Whether a pinned descriptor's proxy reads dev sandbox entries. An older parser refuses their `audience` and
29
+ * `upstreamHost` and fails the build, so a namespace on such a pin serves no sandbox until it is re-pinned.
30
+ */
31
+ 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,29 @@
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;
@@ -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,18 @@
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 DOT-form Box domain a sandbox port is routed by. Only the project network uses it, so it needs no DNS. */
14
+ export declare const SANDBOX_HOST_DOMAIN = "sandbox.fabrika.internal";
15
+ /** The dial address of the Box router from the namespace proxy. */
16
+ export declare const SANDBOX_UPSTREAM = "zbox:8081";
17
+ /** The Host the namespace proxy sends the Box router to reach a sandbox's application port. */
18
+ export declare function sandboxUpstreamHost(sandboxId: string): string;
@@ -36,6 +36,11 @@ export interface ZeropsSourceUploadInput {
36
36
  readonly archive: ZeropsSourceArchive;
37
37
  /** A credential in transit: never logged, persisted, or returned in an error. */
38
38
  readonly uploadUrl: string;
39
+ /**
40
+ * Present for a dev sandbox: `uploadUrl` is the sandbox host's file endpoint for one sandbox, and the PUT carries this
41
+ * bearer. A credential in transit, like `uploadUrl`.
42
+ */
43
+ readonly uploadBearer?: string;
39
44
  readonly signal: AbortSignal;
40
45
  }
41
46
  export interface ZeropsSourceUploadResult {
@@ -0,0 +1,2 @@
1
+ import { type ZboxClient, type ZboxClientOptions } from './types';
2
+ export declare const createZboxClient: (options: ZboxClientOptions) => ZboxClient;
@@ -0,0 +1,25 @@
1
+ /**
2
+ * A failed Box Workspace API call. `code` is Box's `error.code` when the body was Box's error JSON, `http_<status>`
3
+ * when it was not, or one of the client's own: `unreadable` (a success body that does not parse), `timeout`,
4
+ * `unreachable` (status 0 for the last two). The message names the operation and nothing the server sent beyond
5
+ * the code: Box echoes request env and launch env in its bodies.
6
+ */
7
+ export declare class ZboxApiError extends Error {
8
+ readonly operation: string;
9
+ readonly status: number;
10
+ readonly code: string;
11
+ constructor(operation: string, status: number, code: string);
12
+ }
13
+ /** An asynchronous Box operation that ended FAILED. `code` is Box's error only when it is an identifier. */
14
+ export declare class ZboxOperationFailed extends Error {
15
+ readonly kind: string;
16
+ readonly operationId: string;
17
+ readonly code: string | null;
18
+ constructor(kind: string, operationId: string, code: string | null);
19
+ }
20
+ export declare const zboxErrorCode: (status: number, body: unknown) => string;
21
+ export declare const zboxOperationErrorCode: (error: string | null) => string | null;
22
+ export declare const isZboxNotFound: (error: unknown) => error is ZboxApiError;
23
+ export declare const isZboxWorkspaceFull: (error: unknown) => error is ZboxApiError;
24
+ /** An upload over the workspace's body limit; nginx answers it with an HTML page, so only the status identifies it. */
25
+ export declare const isZboxTooLarge: (error: unknown) => error is ZboxApiError;
@@ -0,0 +1,3 @@
1
+ export { createZboxClient } from './client';
2
+ export { isZboxNotFound, isZboxTooLarge, isZboxWorkspaceFull, ZboxApiError, ZboxOperationFailed } from './errors';
3
+ export type { ZboxAwaitOptions, ZboxBase, ZboxBody, ZboxClient, ZboxClientOptions, ZboxCreateSandboxInput, ZboxDomain, ZboxExecInput, ZboxExecResult, ZboxFetch, ZboxIngressPort, ZboxLaunch, ZboxNetworkMode, ZboxOperation, ZboxPortAccess, ZboxProcessInput, ZboxSandbox, ZboxSession, ZboxWorkspace, } from './types';