@molecule/api-code-sandbox-flyio 1.0.5 → 1.0.7

package/dist/api.d.ts

@@ -57,6 +57,13 @@ export interface FlyRequestOptions {
      * Used for idempotent deletes and existence checks (`[404]`).
      */
     nullOn?: number[];
+    /**
+     * Extra HTTP statuses to treat as transient (retry) beyond the default
+     * `429`/`5xx`. The exec endpoint passes `[404]`: a machine-not-found for a
+     * Machine we just created and are actively driving is Fly API inconsistency
+     * under exec-burst load, not a real absence, so it is worth repeating.
+     */
+    retryStatuses?: number[];
 }
 /**
  * Decides whether a failed attempt is worth repeating.

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAgBH;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;;;;OAOG;gBAED,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAgBhC;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0DAA0D;IAC1D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAQhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAoBjE;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,KAAK,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IAC/B,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtC;AAED;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;IAErD;;;OAGG;gBACS,OAAO,EAAE,mBAAmB;IASxC;;;;;;;;;;OAUG;IACG,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CA4EnF"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAgBH;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;;;;OAOG;gBAED,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAgBhC;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0DAA0D;IAC1D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAQhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAoBjE;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,KAAK,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IAC/B,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtC;AAED;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;IAErD;;;OAGG;gBACS,OAAO,EAAE,mBAAmB;IASxC;;;;;;;;;;OAUG;IACG,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CA8EnF"}

package/dist/api.js

@@ -210,7 +210,8 @@ export class FlyApiClient {
             finally {
                 clearTimeout(timer);
             }
-            if (!isRetryableStatus(status) || attempt === attempts)
+            const retryable = isRetryableStatus(status) || (options.retryStatuses?.includes(status) ?? false);
+            if (!retryable || attempt === attempts)
                 break;
             const delay = retryDelayMs(attempt, retryAfter);
             logger.warn(`Fly API transient failure on ${method} ${path} — retrying`, {

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAUV,eAAe,EAEhB,MAAM,4BAA4B,CAAA;AAGnC,OAAO,EAAE,YAAY,EAAgC,MAAM,UAAU,CAAA;AAsBrE,OAAO,EAAmD,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAEhG,OAAO,KAAK,EAEV,WAAW,EAUZ,MAAM,YAAY,CAAA;AAwpDnB;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,CAAC,EAAE,WAAW,EACpB,MAAM,CAAC,EAAE,YAAY,EACrB,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,GACzB,eAAe,CAEjB"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAUV,eAAe,EAEhB,MAAM,4BAA4B,CAAA;AAGnC,OAAO,EAAE,YAAY,EAAgC,MAAM,UAAU,CAAA;AAsBrE,OAAO,EAAmD,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAEhG,OAAO,KAAK,EAEV,WAAW,EAUZ,MAAM,YAAY,CAAA;AAuyDnB;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,CAAC,EAAE,WAAW,EACpB,MAAM,CAAC,EAAE,YAAY,EACrB,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,GACzB,eAAe,CAEjB"}

package/dist/provider.js

@@ -7,6 +7,7 @@
  * @module
  */
 import { createHash } from 'node:crypto';
+import { gzipSync } from 'node:zlib';
 import { getLogger } from '@molecule/api-bond';
 import { t } from '@molecule/api-i18n';
 import { FlyApiClient, FlyApiError, normalizeApiUrl } from './api.js';
@@ -71,6 +72,24 @@ const PROBE_MEMORY_MB = 256;
 const PROBE_LIFETIME_SECONDS = 300;
 /** Default per-connection timeout for the egress probe, in ms. */
 const DEFAULT_PROBE_TIMEOUT_MS = 3000;
+/**
+ * Timeout for the `tar -xzf` step of {@link Sandbox.importFiles}. Extraction is
+ * I/O-bound and fast even for a few-hundred-MB tree, so this stays within the
+ * direct-exec budget (`DIRECT_EXEC_BUDGET_SECONDS`, 55 s) rather than tipping
+ * into the detached poll path, which exists for genuinely long-running commands
+ * like `npm install`, not for un-tarring.
+ */
+const IMPORT_EXTRACT_TIMEOUT_MS = 55_000;
+/**
+ * Base64 chunk size for {@link Sandbox.importFiles}'s temp-file write. Larger
+ * than `WRITE_CHUNK_BASE64` (which is tuned for small single files) so a
+ * multi-megabyte scaffold moves in fewer exec calls — each exec spends Fly's
+ * per-action rate-limit budget, and a burst of small chunks trips 429s (and, on
+ * a busy API, transient 404s). Kept well under the 128 KB `MAX_ARG_STRLEN`
+ * ceiling once the `printf … | base64 -d` wrapper and `buildScript` prefix are
+ * added.
+ */
+const IMPORT_WRITE_CHUNK_BASE64 = 100_000;
 /** Extra seconds allowed for the probe exec beyond its connection budget. */
 const PROBE_EXEC_HEADROOM_SECONDS = 10;
 /**
@@ -352,6 +371,52 @@ class FlyioSandboxProvider {
         }
         return {};
     }
+    /**
+     * Destroys any Machine already in this project's app before a fresh create.
+     *
+     * A create that fails after the Machine exists — a mid-scaffold error, a
+     * retried queue job — leaves a Machine holding the app's single-attach volume.
+     * The next create's `POST /machines` then fails with `412 volume already
+     * claimed by machine <id>`, and the project can never recover on its own. The
+     * app is one-per-project and holds exactly one sandbox, so any managed Machine
+     * still here is a stale partial: destroy it (force covers running/suspended) to
+     * free the volume and make create idempotent per project.
+     * @param app - The Fly app name.
+     */
+    async destroyStaleMachines(app) {
+        const managedKey = `${this.metadataPrefix}.managed`;
+        let machines = null;
+        try {
+            machines = await this.client.request(`/apps/${app}/machines`, {
+                nullOn: [404],
+            });
+        }
+        catch (error) {
+            // A listing we cannot read is not proof the app is empty. A hidden Machine
+            // would fail the create with 412 regardless, so surface it and fall
+            // through rather than pretend the app is clean.
+            logger.warn('Could not list Machines before create; a stale Machine may still hold the volume', { app, error });
+            return;
+        }
+        for (const machine of Array.isArray(machines) ? machines : []) {
+            if (machine.config?.metadata?.[managedKey] !== 'true')
+                continue;
+            try {
+                await this.client.request(`/apps/${app}/machines/${machine.id}?force=true`, {
+                    method: 'DELETE',
+                    nullOn: [404],
+                });
+                logger.info('Destroyed a stale Machine before re-creating the sandbox', {
+                    app,
+                    machineId: machine.id,
+                });
+            }
+            catch (error) {
+                logger.warn('Failed to destroy a stale Machine before create; create may fail with ' +
+                    '412 volume already claimed', { app, machineId: machine.id, error });
+            }
+        }
+    }
     /**
      * Allocates ONE Flycast private address on a target app, for this project's
      * network.
@@ -662,6 +727,11 @@ class FlyioSandboxProvider {
         assertPrivateRoutesForEnv(config.env, this.privateServices());
         const app = this.resolveApp(config.projectId);
         const privateRoutes = await this.ensureApp(app);
+        // Clear any stale Machine from a prior failed/partial create before
+        // provisioning — otherwise it still holds the app's single-attach volume and
+        // `POST /machines` fails with `412 volume already claimed`. Makes create
+        // idempotent so a retried queue job (or a user re-clicking Start) recovers.
+        await this.destroyStaleMachines(app);
         const metadata = {
             [`${this.metadataPrefix}.projectId`]: config.projectId,
             [`${this.metadataPrefix}.managed`]: 'true',
@@ -1208,6 +1278,10 @@ class FlyioSandboxProvider {
                 // The API's own timeout bounds the command; allow the HTTP request a
                 // little longer so the transport never fires first.
                 timeoutMs: (timeoutSeconds + 15) * 1000,
+                // A 404 on a Machine we created and are actively driving (e.g. the
+                // exec burst importFiles issues) is Fly API inconsistency under load,
+                // not a real absence — retry it alongside the default 429/5xx.
+                retryStatuses: [404],
             });
             return response ?? {};
         };
@@ -1395,6 +1469,45 @@ class FlyioSandboxProvider {
                     throw new Error(t('codeSandbox.flyio.error.deleteFailed', { path, error: result.stderr }, { defaultValue: `Failed to delete ${path}: ${result.stderr}` }));
                 }
             },
+            /**
+             * Streams a POSIX tar archive into the Machine and extracts it at `path`.
+             *
+             * The Fly Machines exec endpoint is a single request/response with no
+             * stdin, so the archive cannot be piped to `tar` directly. It is buffered,
+             * gzipped (fewer bytes = fewer exec round trips over the base64 channel),
+             * written to a temp file in `WRITE_CHUNK_BASE64`-sized pieces the same way
+             * `writeFile` does, then extracted.
+             *
+             * Ownership and setuid/setgid bits are NOT restored (`--no-same-owner
+             * --no-same-permissions`): the archive is caller/tenant-authored data, and
+             * honoring its mode bits is a privilege-escalation vector in whatever boots
+             * it next — see the {@link Sandbox.importFiles} contract.
+             * @param path - Absolute destination path inside the Machine.
+             * @param archive - POSIX tar byte stream to extract there.
+             */
+            async importFiles(path, archive) {
+                const parts = [];
+                for await (const chunk of archive)
+                    parts.push(Buffer.from(chunk));
+                const base64 = gzipSync(Buffer.concat(parts)).toString('base64');
+                const tmp = `/tmp/mol-import-${machineId}.tgz`;
+                const quotedTmp = shellQuote(tmp);
+                const quotedPath = shellQuote(path);
+                const failIfError = (result, step) => {
+                    if (result.exitCode !== 0) {
+                        throw new Error(t('codeSandbox.flyio.error.importFailed', { path, step, error: result.stderr }, {
+                            defaultValue: `Failed to import files into ${path} (${step}): ${result.stderr}`,
+                        }));
+                    }
+                };
+                // First chunk truncates the temp file; the rest append. Each chunk is a
+                // multiple of 4 base64 chars so it decodes standalone (see writeFile).
+                failIfError(await this.exec(`printf %s ${shellQuote(base64.slice(0, IMPORT_WRITE_CHUNK_BASE64))} | base64 -d > ${quotedTmp}`, { timeout: FILE_OP_TIMEOUT_MS }), 'write');
+                for (let i = IMPORT_WRITE_CHUNK_BASE64; i < base64.length; i += IMPORT_WRITE_CHUNK_BASE64) {
+                    failIfError(await this.exec(`printf %s ${shellQuote(base64.slice(i, i + IMPORT_WRITE_CHUNK_BASE64))} | base64 -d >> ${quotedTmp}`, { timeout: FILE_OP_TIMEOUT_MS }), 'write');
+                }
+                failIfError(await this.exec(`mkdir -p ${quotedPath} && tar -xzf ${quotedTmp} -C ${quotedPath} --no-same-owner --no-same-permissions && rm -f ${quotedTmp}`, { timeout: IMPORT_EXTRACT_TIMEOUT_MS }), 'extract');
+            },
             getPreviewUrl(port) {
                 return provider.renderPreviewUrl(app, machineId, port);
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-code-sandbox-flyio",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Fly.io Machines (Firecracker microVM) code sandbox provider",
   "type": "module",
   "main": "dist/index.js",