@molecule/api-code-sandbox-flyio 1.3.8 → 1.4.0

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-11-01T09:52:42.927Z
+Generated: 2026-11-04T14:19:55.149Z
 -->
 
 # @molecule/api-code-sandbox-flyio
@@ -484,169 +484,95 @@ Every option is also readable from an environment variable (see
 
 ```typescript
 interface FlyioConfig {
-  /**
-   * Fly API token (sent as `Authorization: Bearer <token>`). Falls back to
-   * `FLY_API_TOKEN`, then `FLY_ACCESS_TOKEN`. Required — the provider throws a
-   * named error on the first API call if none is resolvable.
-   */
+  /** Fly API token (sent as `Authorization: Bearer <token>`). */
   apiToken?: string
-  /**
-   * Machines API base URL, INCLUDING the `/v1` path segment. Defaults to
-   * `FLY_API_HOSTNAME` (with `/v1` appended when the value has no path) or
-   * `https://api.machines.dev/v1`. From inside a Fly private network the
-   * documented internal endpoint is `http://_api.internal:4280/v1`.
-   */
+  /** Machines API base URL, INCLUDING the `/v1` path segment. */
   apiUrl?: string
-  /**
-   * Fly organization slug that owns the sandbox apps. Falls back to
-   * `FLY_ORG_SLUG`, then `personal`. Required for app creation and for
-   * {@link FlyioConfig.appPerProject} listing.
-   */
+  /** Fly organization slug that owns the sandbox apps. */
   orgSlug?: string
-  /**
-   * Shared Fly app that holds every sandbox Machine. Only used when
-   * `appPerProject` is `false`. Falls back to `FLY_SANDBOX_APP`.
-   *
-   * A shared app puts every tenant on ONE 6PN private network, where each
-   * sandbox can reach every other sandbox's dev-server ports by private IPv6.
-   * That is the same cross-tenant exposure the Docker bond's `bridge` network
-   * has, so this mode is REFUSED in production.
-   */
+  /** Shared Fly app that holds every sandbox Machine. */
   appName?: string
-  /**
-   * Name prefix for the per-project Fly app when `appPerProject` is `true`
-   * (default). The app is `<appPrefix>-<sanitized projectId>`. Falls back to
-   * `FLY_SANDBOX_APP_PREFIX`, then `mol-sandbox`.
-   */
+  /** Name prefix for the per-project Fly app when `appPerProject` is `true` (default). */
   appPrefix?: string
-  /**
-   * Create one Fly app — on its own custom 6PN private network — per project,
-   * so tenants are network-isolated from each other. Defaults to `true`.
-   * Set `false` (or `FLY_SANDBOX_APP_PER_PROJECT=false`) only for a
-   * single-tenant deployment; it is refused in production.
-   */
+  /** Create one Fly app — on its own custom 6PN private network — per project, so tenants are network-isolated from each other. */
   appPerProject?: boolean
-  /**
-   * Custom 6PN network name for a per-project app. Defaults to the app name, so
-   * every project lands on its own private network. Ignored when
-   * `appPerProject` is `false`. A Fly app's network CANNOT be changed after
-   * creation.
-   */
+  /** Custom 6PN network name for a per-project app. */
   network?: string
-  /**
-   * Default Fly region for Machines and volumes (e.g. `iad`). Defaults to
-   * `iad`; `SandboxConfig.region` overrides it for one recorded project create.
-   * The API Machine's own `FLY_REGION` is never a tenant-placement fallback.
-   */
+  /** Default Fly region for Machines and volumes (e.g. `iad`). */
   region?: string
-  /**
-   * OCI image every sandbox Machine runs. Must be pullable by Fly — a tag in
-   * the org's `registry.fly.io` repository or a public registry. A LOCAL
-   * `molecule-sandbox:latest` is not reachable by Fly; push it first. Falls
-   * back to `FLY_SANDBOX_IMAGE`, then `registry.fly.io/molecule-sandbox:latest`.
-   */
+  /** OCI image every sandbox Machine runs. */
   baseImage?: string
-  /** Default vCPU count (`guest.cpus`). Defaults to 1. */
+  /** Default vCPU count (`guest.cpus`). */
   defaultCpu?: number
-  /** Default `guest.cpu_kind` — `shared` or `performance`. Defaults to `shared`. */
+  /** Default `guest.cpu_kind` — `shared` or `performance`. */
   defaultCpuKind?: string
-  /** Default memory in MB (`guest.memory_mb`). Defaults to 1024. */
+  /** Default memory in MB (`guest.memory_mb`). */
   defaultMemoryMB?: number
-  /**
-   * Size in GB of the volume created for a sandbox's `/workspace` when
-   * `SandboxConfig.volumeName` is set. Fly volumes are sized in whole GB, so the
-   * core's `resources.diskMB` is rounded UP to the next GB. Defaults to 10.
-   */
+  /** Size in GB of the volume created for a sandbox's `/workspace` when `SandboxConfig.volumeName` is set. */
   defaultVolumeGB?: number
-  /** Internal port the preview service forwards to (the Vite dev server). Defaults to 5173. */
+  /** Internal port the preview service forwards to (the Vite dev server). */
   previewPort?: number
-  /**
-   * Preview URL template. Placeholders `{app}`, `{machineId}` and `{port}` are
-   * all replaced globally. Defaults to `https://{app}.fly.dev`.
-   *
-   * For a control plane that runs on the SAME Fly 6PN, the private form
-   * `http://{machineId}.vm.{app}.internal:{port}` reaches the Machine with no
-   * public exposure at all — but it does NOT work across custom 6PNs, which is
-   * exactly what `appPerProject` creates. See the module `@remarks`.
-   */
+  /** Preview URL template. */
   previewUrlTemplate?: string
-  /**
-   * Attach a public Fly Proxy service (`80` → http, `443` → tls+http) forwarding
-   * to {@link FlyioConfig.previewPort}. Defaults to `true`. Set `false` for a
-   * fully private sandbox reached only over 6PN/Flycast.
-   */
+  /** Attach a public Fly Proxy service (`80` → http, `443` → tls+http) forwarding to {@link FlyioConfig.previewPort}. */
   publicService?: boolean
-  /**
-   * Fly Proxy idle behaviour for the preview service. Defaults to `'off'` —
-   * never idle the Machine — because the autostop timer counts the PROXY
-   * service's idle time, not the workload's, so a sandbox with nobody looking at
-   * its preview is suspended out from under a build that is still running.
-   * `suspend` is the scale-to-zero mapping (resume from a memory snapshot on the
-   * next request) and `stop` is a full stop with a cold boot on wake; opt into
-   * either deliberately.
-   *
-   * This is the provider's STEADY-STATE policy, reported as
-   * `SandboxProvider.defaultIdleAction`. A caller can override it for one sandbox
-   * with `SandboxConfig.idleAction` and restore this value afterwards with
-   * `Sandbox.setIdleAction` — which is what a production deploy does so its
-   * destination cannot suspend mid-copy.
-   */
+  /** Fly Proxy idle behaviour for the preview service. */
   autostop?: 'off' | 'stop' | 'suspend'
-  /**
-   * Allocate a shared Anycast IPv4 for a newly-created app so `<app>.fly.dev`
-   * serves traffic. Defaults to `false` (opt-in). See the module `@remarks` —
-   * the accepted `type` values for the IP-assignment endpoint are NOT enumerated
-   * in Fly's OpenAPI specification.
-   */
+  /** Allocate a shared Anycast IPv4 for a newly-created app so `<app>.fly.dev` serves traffic. */
   assignSharedIpv4?: boolean
-  /** IP type requested when {@link FlyioConfig.assignSharedIpv4} is on. Defaults to `shared_v4`. */
+  /** IP type requested when {@link FlyioConfig.assignSharedIpv4} is on. */
   ipAssignmentType?: string
-  /** Prefix for the Machine metadata keys this provider owns. Defaults to `molecule-sandbox`. */
+  /** Prefix for the Machine metadata keys this provider owns. */
   metadataPrefix?: string
-  /** Durable create-attempt ownership. Required for automatic failed-create reconciliation. */
+  /** Durable create-attempt ownership. */
   createAttemptJournal?: FlyCreateAttemptJournal
-  /** Timeout for a single Machines API request, in ms. Defaults to 30000. */
+  /** Timeout for a single Machines API request, in ms. */
   requestTimeoutMs?: number
-  /**
-   * TOTAL budget, in seconds, that `create()`/`start()`/`wake()` block waiting
-   * for the Machine to actually reach `started`. Fly's `GET .../wait` blocks
-   * for at most 60 seconds per call, so a larger budget is spent as consecutive
-   * wait rounds. Defaults to 180 — a Machine whose image is not yet cached on
-   * its host (every first boot after an image push) pulls it before starting,
-   * and that alone can exceed a single 60 s round.
-   *
-   * Without this wait, `start()` resolves the moment Fly ACCEPTS the request,
-   * and the caller's very next `exec` hits a Machine that is not running yet.
-   */
+  /** TOTAL budget, in seconds, that `create()`/`start()`/`wake()` block waiting for the Machine to actually reach `started`. */
   startTimeoutSeconds?: number
-  /**
-   * Ports a sandbox Machine may open outbound connections on. Setting this makes
-   * the provider apply a Fly **network policy** to every app it provisions;
-   * leaving it unset applies no policy at all, and `verifyEgress()` will then
-   * observe (correctly) that egress is `open`. Falls back to
-   * `FLY_SANDBOX_EGRESS_ALLOWED_PORTS` (`tcp:3128,udp:53`).
-   *
-   * Read {@link https://fly.io/docs/machines/guides-examples/network-policies/}
-   * before choosing a value, because the mechanism is narrower than it looks:
-   * rules match protocol and port ONLY — no host, no CIDR, no ranges — so this
-   * can never be a host allowlist. `tcp:443` lets a sandbox reach EVERY host on
-   * the internet that listens on 443. To get a host allowlist, allow only the
-   * port of an egress proxy you control and route sandbox traffic through it.
-   *
-   * An empty array is rejected rather than treated as "deny all": Fly documents
-   * the deny default as a consequence of an `allow` rule existing, and says
-   * nothing about a rule with no ports.
-   */
+  /** Ports a sandbox Machine may open outbound connections on. */
   egressAllowedPorts?: FlyNetworkPolicyPort[]
-  /** Name of the egress policy this provider owns on each app. Defaults to `molecule-sandbox-egress`. */
+  /** Name of the egress policy this provider owns on each app. */
   egressPolicyName?: string
-  /**
-   * Apps every sandbox must be able to reach ACROSS its per-project 6PN — the
-   * tenant Postgres cluster and the control plane's egress proxy. For each one,
-   * this provider allocates a **Flycast** private address into the project's own
-// … truncated — the full declaration is in node_modules/@molecule/api-code-sandbox-flyio/dist/types.d.ts
+  /** Apps every sandbox must be able to reach ACROSS its per-project 6PN — the tenant Postgres cluster and the control plane's egress proxy. */
+  privateServices?: FlyPrivateService[]
+  /** Per-create regional overrides for {@link FlyioConfig.privateServices}. */
+  privateServicesByRegion?: Record<string, FlyPrivateService[]>
+  /** `type` sent to `POST /apps/{app}/ip_assignments` when allocating a Flycast address. */
+  privateIpAssignmentType?: string
+  /** Literal `ip:port` targets `verifyEgress()` attempts raw TCP connections to. */
+  egressProbeTargets?: string[]
+  /** Per-connection timeout for the egress probe, in ms. */
+  egressProbeTimeoutMs?: number
+  /** Image the throwaway `verifyEgress()` probe Machine runs. */
+  egressProbeImage?: string
+  /** Bucket holding sandbox templates. */
+  templateBucket?: string
+  /** S3 endpoint for {@link FlyioConfig.templateBucket}, e.g. Tigris's `https://t3.storage.dev`. */
+  templateEndpoint?: string
+  /** Region used to sign template-store requests. */
+  templateRegion?: string
+  /** Access key for the template store. */
+  templateAccessKeyId?: string
+  /** Secret key for the template store. */
+  templateSecretAccessKey?: string
+  /** Session token for temporary template-store credentials. */
+  templateSessionToken?: string
+  /** Key prefix every template object lives under. */
+  templatePrefix?: string
+  /** Address the template bucket path-style (`https://endpoint/bucket/key`) instead of virtual-host style. */
+  templateForcePathStyle?: boolean
+  /** Lifetime of the presigned capture/restore URL handed to a sandbox, in seconds. */
+  templateUrlExpirySeconds?: number
+  /** Wall-clock budget for one capture or restore transfer, in ms. */
+  templateTransferTimeoutMs?: number
+  /** Largest template archive this provider will store, in bytes. */
+  templateMaxArchiveBytes?: number
+}
 ```
 
+_(Member comments are shortened to their first sentence to fit; the full declaration is in `node_modules/@molecule/api-code-sandbox-flyio/dist/types.d.ts`.)_
+
 #### `ProcessEnv`
 
 Environment variables the Fly.io sandbox provider reads. Every one is
@@ -1605,8 +1531,15 @@ its own 6PN: under a policy allowing only `udp:53`, `molecule-pg-tenant.flycast`
 and `molecule-api.flycast` both RESOLVED and every TCP connect to them was
 dropped; re-applying the policy with `tcp:443` opened 443 and nothing else.
 Fly's sentence is about INGRESS — a Machine's egress TOWARD a Flycast address
-
-_(description truncated — read the full text in `node_modules/@molecule/api-code-sandbox-flyio/dist/flycast.d.ts`.)_
+is filtered like any other. Drop a declared service's port and every database
+connection in the fleet goes with it.
+
+The cost of each derived port, stated plainly because a Fly policy has no
+destination field of any kind (also measured — see the `egress.ts` module
+description): the port is opened to EVERY host on the internet, not only to
+the private service it was derived for. That residual cannot be closed at this
+layer; it is named in `verifyEgress()`'s verdict and in
+`docs/sandbox-egress-enforcement.md`.
 
 ```typescript
 function mergeEgressPorts(

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EAaV,eAAe,EAGhB,MAAM,4BAA4B,CAAA;AAGnC,OAAO,EACL,YAAY,EAKb,MAAM,UAAU,CAAA;AA8BjB,OAAO,KAAK,EAEV,wBAAwB,EAEzB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAmD,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAEhG,OAAO,KAAK,EAIV,WAAW,EAUZ,MAAM,YAAY,CAAA;AAyBnB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAIjG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE5E;AAgyID;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,CAAC,EAAE,WAAW,EACpB,MAAM,CAAC,EAAE,YAAY,EACrB,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,GACzB,eAAe,GAAG,wBAAwB,CAE5C"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EAaV,eAAe,EAGhB,MAAM,4BAA4B,CAAA;AAGnC,OAAO,EACL,YAAY,EAKb,MAAM,UAAU,CAAA;AA8BjB,OAAO,KAAK,EAEV,wBAAwB,EAEzB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAmD,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAEhG,OAAO,KAAK,EAIV,WAAW,EAUZ,MAAM,YAAY,CAAA;AAyBnB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAIjG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE5E;AA4zID;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,CAAC,EAAE,WAAW,EACpB,MAAM,CAAC,EAAE,YAAY,EACrB,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,GACzB,eAAe,GAAG,wBAAwB,CAE5C"}

package/dist/provider.js

@@ -3336,6 +3336,19 @@ class FlyioSandboxProvider {
                 `${totalSeconds}s (last observed state: ${lastState ?? 'unknown'}).`,
         }), { cause: lastError });
     }
+    /**
+     * Activate an already populated Machine with one full-config update: startup command and idle
+     * policy change together. The former command keeps the workload stopped, so the update's reboot
+     * is the workload's first boot. Fly preserves parked Machines with skip_launch; startMachine
+     * explicitly wakes those and waits, and is idempotent after a running Machine's update.
+     */
+    async activate(id, options) {
+        if (!options.command.length)
+            throw new Error('A sandbox activation needs a startup command');
+        const { app, machineId } = parseSandboxId(id);
+        await this.applyIdleAction(app, machineId, options.idleAction, options.command);
+        await this.startMachine(app, machineId);
+    }
     /**
      * Applies an idle policy to a running Machine's public service, in place.
      *
@@ -3356,10 +3369,11 @@ class FlyioSandboxProvider {
      * @param app - The Fly app name.
      * @param machineId - The Fly Machine id.
      * @param action - The idle action to apply to every service.
+     * @param command - An activation command installed in the SAME update as the policy.
      * @throws {Error} When the Machine or its config cannot be read, the update is
      *   rejected, or a rebooted Machine does not come back to `started`.
      */
-    async applyIdleAction(app, machineId, action) {
+    async applyIdleAction(app, machineId, action, command) {
         const machine = await this.client.request(`/apps/${app}/machines/${machineId}`, {
             nullOn: [404],
         });
@@ -3370,14 +3384,21 @@ class FlyioSandboxProvider {
             }));
         }
         const services = machine.config.services;
-        if (!services?.length)
-            return;
-        if (services.every((service) => (service.autostop ?? 'off') === action))
-            return;
+        const samePolicy = !services?.length || services.every((service) => (service.autostop ?? 'off') === action);
+        const sameCommand = !command || JSON.stringify(machine.config.init?.exec) === JSON.stringify(command);
+        if (samePolicy && sameCommand)
+            return mapMachineState(machine.state ?? 'created');
         const config = {
             ...machine.config,
-            services: services.map((service) => ({ ...service, autostop: action })),
+            ...(services
+                ? { services: services.map((service) => ({ ...service, autostop: action })) }
+                : {}),
         };
+        if (command) {
+            config.init = { ...machine.config.init, exec: [...command] };
+            delete config.init.entrypoint;
+            delete config.init.cmd;
+        }
         // A running Machine reboots to apply the config, so wait for it; a parked
         // one is updated without being started (there is nothing to wait for).
         const wasRunning = machine.state === 'started' || machine.state === 'starting';
@@ -3394,6 +3415,7 @@ class FlyioSandboxProvider {
         });
         if (wasRunning)
             await this.waitForStarted(app, machineId);
+        return wasRunning ? 'running' : mapMachineState(machine.state ?? 'created');
     }
     /**
      * Builds the `Sandbox` facade for one Machine.
@@ -3442,11 +3464,10 @@ class FlyioSandboxProvider {
             /**
              * Applies an idle policy to this Machine's public service (see
              * {@link FlyioSandboxProvider.applyIdleAction} for the endpoint and the
-             * reboot it costs). Resolves with the Machine running again.
+             * reboot it costs). A parked Machine stays parked; a rebooted Machine is running again.
              */
             async setIdleAction(action) {
-                await provider.applyIdleAction(app, machineId, action);
-                this.status = 'running';
+                this.status = await provider.applyIdleAction(app, machineId, action);
             },
             async exec(command, opts) {
                 return await execCommand(exec, command, opts, WORKSPACE_PATH);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-code-sandbox-flyio",
-  "version": "1.3.8",
+  "version": "1.4.0",
   "description": "Fly.io Machines (Firecracker microVM) code sandbox provider",
   "type": "module",
   "main": "dist/index.js",
@@ -31,7 +31,7 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "@molecule/api-bond": "1.0.4",
-    "@molecule/api-code-sandbox": "1.5.1",
+    "@molecule/api-code-sandbox": "1.7.0",
     "@types/node": "26.6.5",
     "typescript": "6.0.3",
     "vitest": "4.1.12"