@molecule/api-code-sandbox-flyio 1.2.4 → 1.2.6

package/dist/index.d.ts

@@ -86,6 +86,17 @@
  * setuid/setgid dropped by `--no-same-permissions` — were verified by running
  * GNU tar 1.35 against crafted archives rather than inferred from its manual.
  *
+ * **Absence vs failure: `get()` only answers `null` for a REAL absence.**
+ * `get()` (and each read shaped like it — `list()`, `find()`, `getTemplate()`)
+ * reserves `null`/`[]` for a positive not-found answer — Fly answered 404 for
+ * the app or the Machine — and THROWS for every other failure: 5xx, 429 past
+ * the client's retries, timeouts, network errors. A caller that reconciles
+ * from `null` (clearing sandbox ids, reaping Machines) must never read a
+ * transient Fly API blip as "the sandbox does not exist"; treat a rejection
+ * from these methods as "unknown", never as "gone". The thrown error carries
+ * the underlying `FlyApiError` (HTTP status, or 0 for a transport failure) as
+ * its `cause`.
+ *
  * **`sleep()` is suspend, not stop — that is the point of this bond.**
  * `sleep()` calls `POST /v1/apps/{app}/machines/{id}/suspend`, which "uses
  * Firecracker snapshots to capture the entire VM state: CPU registers, memory

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0UG;AAEH,cAAc,UAAU,CAAA;AACxB,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAE9B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAMjE;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,eAUrB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqVG;AAEH,cAAc,UAAU,CAAA;AACxB,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAE9B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAMjE;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,eAUrB,CAAA"}

package/dist/index.js

@@ -86,6 +86,17 @@
  * setuid/setgid dropped by `--no-same-permissions` — were verified by running
  * GNU tar 1.35 against crafted archives rather than inferred from its manual.
  *
+ * **Absence vs failure: `get()` only answers `null` for a REAL absence.**
+ * `get()` (and each read shaped like it — `list()`, `find()`, `getTemplate()`)
+ * reserves `null`/`[]` for a positive not-found answer — Fly answered 404 for
+ * the app or the Machine — and THROWS for every other failure: 5xx, 429 past
+ * the client's retries, timeouts, network errors. A caller that reconciles
+ * from `null` (clearing sandbox ids, reaping Machines) must never read a
+ * transient Fly API blip as "the sandbox does not exist"; treat a rejection
+ * from these methods as "unknown", never as "gone". The thrown error carries
+ * the underlying `FlyApiError` (HTTP status, or 0 for a transport failure) as
+ * its `cause`.
+ *
  * **`sleep()` is suspend, not stop — that is the point of this bond.**
  * `sleep()` calls `POST /v1/apps/{app}/machines/{id}/suspend`, which "uses
  * Firecracker snapshots to capture the entire VM state: CPU registers, memory

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAWV,eAAe,EAGhB,MAAM,4BAA4B,CAAA;AAGnC,OAAO,EAAE,YAAY,EAAgC,MAAM,UAAU,CAAA;AAwBrE,OAAO,EAAmD,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAEhG,OAAO,KAAK,EAIV,WAAW,EAUZ,MAAM,YAAY,CAAA;AA8yEnB;;;;;;;;;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,EAWV,eAAe,EAGhB,MAAM,4BAA4B,CAAA;AAGnC,OAAO,EAAE,YAAY,EAAgC,MAAM,UAAU,CAAA;AAwBrE,OAAO,EAAmD,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAEhG,OAAO,KAAK,EAIV,WAAW,EAUZ,MAAM,YAAY,CAAA;AA+2EnB;;;;;;;;;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

@@ -1043,8 +1043,22 @@ class FlyioSandboxProvider {
     }
     /**
      * Retrieves an existing sandbox by its composite `<app>:<machineId>` id.
+     *
+     * `null` is reserved for a POSITIVE answer that the sandbox is gone: Fly
+     * answered 404 for the app or the Machine (the client's `nullOn: [404]`
+     * resolves that before this method sees an error), or the id is not in
+     * `<app>:<machineId>` form at all. Every OTHER failure — 5xx, 429, a timeout,
+     * a network error, anything the API call can still throw after its retries —
+     * THROWS. That split is the core's absence contract, and it is load-bearing:
+     * a caller that reconciles from `null` (clearing sandbox ids, reaping
+     * Machines) must never read a transient Fly blip as "the sandbox does not
+     * exist" — on 2026-10-07 exactly that orphaned live Machines that kept
+     * billing with no row left to name them.
      * @param id - The sandbox id returned by `create`.
-     * @returns The sandbox, or `null` when the id is malformed or the Machine is gone.
+     * @returns The sandbox, or `null` when the id is malformed or Fly positively
+     *   answered that the app or Machine does not exist.
+     * @throws {Error} When the lookup itself failed — with `cause` carrying the
+     *   `FlyApiError`. The Machine may still exist; this is not an absence answer.
      */
     async get(id) {
         let app;
@@ -1066,8 +1080,15 @@ class FlyioSandboxProvider {
             return this.buildSandbox(app, machine.id, mapMachineState(machine.state ?? 'created'));
         }
         catch (error) {
-            logger.debug('Failed to get Fly Machine', { id, error });
-            return null;
+            // NOT an absence. Returning null here made molecule.dev's loss-recorder
+            // clear the sandbox ids of projects whose Machines were still running
+            // (2026-10-07, two leaked 2 vCPU / 4 GB Machines). Say the lookup failed
+            // and keep the cause, so the caller retries or surfaces it instead.
+            throw new Error(t('codeSandbox.flyio.error.getFailed', { id }, {
+                defaultValue: `Cannot read Fly sandbox "${id}": the Fly API lookup failed, so whether it exists ` +
+                    'is UNKNOWN — the Machine may still be running. This is not an absence answer; ' +
+                    'retry or surface the error rather than treating the sandbox as gone.',
+            }), { cause: error });
         }
     }
     /**
@@ -1692,7 +1713,12 @@ class FlyioSandboxProvider {
      *
      * A Machine that is already `started` may reject a redundant start. Rather
      * than pattern-matching an error string, the state is re-read and the call
-     * treated as successful when the Machine is in fact running.
+     * treated as successful when the Machine is in fact running. A Machine still
+     * `starting` (its own start lost to a concurrent one — the proxy's autostart
+     * racing a `wake()`) is NOT that case: only `waitForStarted` may end this
+     * call, or it resolves against a Machine that is still booting and the
+     * caller's first `exec` fails with 412 "machine not running" — the exact
+     * failure this method's wait exists to prevent.
      * @param app - The Fly app name.
      * @param machineId - The Fly Machine id.
      */
@@ -1704,7 +1730,7 @@ class FlyioSandboxProvider {
             const machine = await this.client
                 .request(`/apps/${app}/machines/${machineId}`, { nullOn: [404] })
                 .catch(() => null);
-            if (machine && (machine.state === 'started' || machine.state === 'starting')) {
+            if (machine?.state === 'started') {
                 logger.debug('Fly Machine start rejected but the Machine is already running', {
                     app,
                     machineId,
@@ -1712,7 +1738,9 @@ class FlyioSandboxProvider {
                 });
                 return;
             }
-            throw error;
+            if (machine?.state !== 'starting')
+                throw error;
+            logger.debug('Fly Machine start rejected but the Machine is already starting — waiting for started', { app, machineId });
         }
         await this.waitForStarted(app, machineId);
     }
@@ -1837,10 +1865,12 @@ class FlyioSandboxProvider {
                         throw new Error(t('codeSandbox.flyio.error.writeFailed', { path, error: result.stderr }, { defaultValue: `Failed to write ${path}: ${result.stderr}` }));
                     }
                 };
-                // Chunked for the same reason as the Docker provider: the whole command
-                // is one `sh -c` argument, capped at MAX_ARG_STRLEN (128 KB). Each chunk
-                // is a multiple of 4 base64 characters (= 3 decoded bytes) so it decodes
-                // standalone and the bytes concatenate exactly.
+                // Chunked for the same reason as WRITE_CHUNK_BASE64 above: the whole
+                // command is one argument to Fly's exec API, which silently rejects
+                // anything over ~15 KB (FLY_EXEC_MAX_ARG_BYTES) — NOT the OS
+                // MAX_ARG_STRLEN (128 KB) a Docker-based provider is bounded by. Each
+                // chunk is a multiple of 4 base64 characters (= 3 decoded bytes) so it
+                // decodes standalone and the bytes concatenate exactly.
                 failIfError(await this.exec(`mkdir -p "$(dirname ${quoted})" && printf %s ${shellQuote(base64.slice(0, WRITE_CHUNK_BASE64))} | base64 -d > ${quoted}`, { timeout: FILE_OP_TIMEOUT_MS }));
                 for (let i = WRITE_CHUNK_BASE64; i < base64.length; i += WRITE_CHUNK_BASE64) {
                     failIfError(await this.exec(`printf %s ${shellQuote(base64.slice(i, i + WRITE_CHUNK_BASE64))} | base64 -d >> ${quoted}`, { timeout: FILE_OP_TIMEOUT_MS }));
@@ -1937,6 +1967,14 @@ class FlyioSandboxProvider {
                     try {
                         const putUrl = await store.presignPut(key, IMPORT_PRESIGN_EXPIRY_SECONDS);
                         const putRes = await fetch(putUrl, { method: 'PUT', body: gz });
+                        // The PUT's body is never read (a presigned store answers an empty
+                        // 2xx or a short error document): release it on EVERY path, or the
+                        // connection stays stranded in the pool until GC reclaims it — the
+                        // same release every other discarded response body here gets.
+                        await putRes.body?.cancel().catch((_error) => {
+                            // Best-effort release only; the fallback decision below runs on
+                            // the already-known status.
+                        });
                         if (!putRes.ok) {
                             throw new Error(`presigned PUT to the object store failed: ${putRes.status}`);
                         }
@@ -1946,7 +1984,12 @@ class FlyioSandboxProvider {
                             `mkdir -p ${quotedPath}`,
                             'archive=$(mktemp /tmp/mol-import-XXXXXX.tar.gz)',
                             `curl --fail-with-body -sS --retry 3 --retry-connrefused -o "$archive" ${shellQuote(getUrl)}`,
-                            `tar -C ${quotedPath} --no-same-owner --no-same-permissions -xzf "$archive"`,
+                            // The archive is removed whether the extract SUCCEEDS or fails:
+                            // `&& rm` after tar (under `set -e`) left every failed extract's
+                            // download behind in the sandbox's /tmp until the Machine died.
+                            // The `|| { }` guard keeps `set -e` from aborting before the
+                            // cleanup and re-raises the real exit code.
+                            `tar -C ${quotedPath} --no-same-owner --no-same-permissions -xzf "$archive" || { rc=$?; rm -f "$archive"; exit $rc; }`,
                             'rm -f "$archive"',
                         ].join('\n'), { timeout: IMPORT_EXTRACT_TIMEOUT_MS });
                         // Best-effort: the temp object expires anyway, but delete it promptly.
@@ -1968,15 +2011,26 @@ class FlyioSandboxProvider {
                 // configured. The temp tar lives on the WORKSPACE VOLUME, not /tmp — the
                 // chunked write and the extract are separate exec calls and a Machine
                 // with autostop can cold-start between them, wiping /tmp (rootfs) while
-                // the ext4 volume at /workspace persists.
+                // the ext4 volume at /workspace persists. The name is unique per call
+                // (same shape as the store path's key): a fixed, machineId-only name
+                // made two concurrent imports to one sandbox interleave their `>>`
+                // appends into ONE file, so each extracted a mix of both archives.
                 const base64 = gz.toString('base64');
-                const tmp = `${WORKSPACE_PATH}/.mol-import-${machineId}.tgz`;
+                const tmp = `${WORKSPACE_PATH}/.mol-import-${machineId}-${Date.now().toString(36)}${Math.floor(Math.random() * 1e9).toString(36)}.tgz`;
                 const quotedTmp = shellQuote(tmp);
                 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');
+                failIfError(await this.exec(
+                // The temp archive is removed whether the extract SUCCEEDS or fails:
+                // `&& rm` after tar left a failed extract's multi-MB archive behind
+                // on the WORKSPACE VOLUME — the durable path this fallback
+                // deliberately writes to — until the next import overwrote it.
+                // `; rc=$?; rm …; exit $rc` cleans up unconditionally and still
+                // reports tar's real exit code (the same shape exec.ts's script
+                // spill uses).
+                `mkdir -p ${quotedPath} && tar -xzf ${quotedTmp} -C ${quotedPath} --no-same-owner --no-same-permissions; rc=$?; rm -f ${quotedTmp}; exit $rc`, { 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.2.4",
+  "version": "1.2.6",
   "description": "Fly.io Machines (Firecracker microVM) code sandbox provider",
   "type": "module",
   "main": "dist/index.js",