@molecule/api-code-sandbox-flyio 1.0.11 → 1.0.13

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-08-05T16:24:32.555Z
+Generated: 2026-08-08T23:10:20.743Z
 -->
 
 # @molecule/api-code-sandbox-flyio
@@ -609,6 +609,13 @@ 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[]
 }
 ```
 
@@ -1125,6 +1132,10 @@ function encodePrivateRoutes(routes: Record<string, string>): string
 Executes a command on a Machine, choosing the direct or detached strategy
 based on the caller's time budget.
 
+A command too large to pass inline (over {@link FLY_EXEC_MAX_ARG_BYTES}) is
+spilled to a file via chunked writes and run from there, so there is no size
+ceiling the caller must respect.
+
 ```typescript
 function execCommand(
   rawExec: RawExec,
@@ -1751,6 +1762,20 @@ Exit status the capture script uses when `tar` failed outright (as opposed to wa
 const EXIT_TAR_FAILED: 92
 ```
 
+#### `FLY_EXEC_MAX_ARG_BYTES`
+
+Hard cap on the `sh -c <script>` argument SENT to Fly's exec endpoint. This is
+NOT the OS `MAX_ARG_STRLEN` (128 KB) — the Fly Machines exec API rejects a
+command well below that, and does so INVISIBLY: it answers `200` with
+`exit_code: 0` and an `Unhandled rejection: Rejection([PayloadTooLarge…])`
+body, so the command never runs yet reads as success. Measured against the
+live API: ~15.8 KB scripts run, ~23.7 KB are rejected. 15 KB is the safe
+ceiling; callers that move bulk data (writeFile, importFiles) chunk beneath it.
+
+```typescript
+const FLY_EXEC_MAX_ARG_BYTES: 15000
+```
+
 #### `FLY_EXEC_MAX_TIMEOUT_SECONDS`
 
 Fly's hard ceiling on the exec endpoint's `timeout` field, in seconds.

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,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;AAmzDnB;;;;;;;;;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;AA83DnB;;;;;;;;;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

@@ -82,6 +82,23 @@ const DEFAULT_PROBE_TIMEOUT_MS = 3000;
  * like `npm install`, not for un-tarring.
  */
 const IMPORT_EXTRACT_TIMEOUT_MS = 55_000;
+/**
+ * Attempts for the create's `POST /machines`, retrying the app-propagation 404
+ * (see {@link MACHINE_CREATE_RETRY_STATUSES}). Fly propagates a new app to its
+ * sub-APIs asynchronously, so `POST /apps` can return before
+ * `POST /apps/{app}/machines` sees the app — which 404s "app not found" for a
+ * few seconds. Observed live during boot on 2026-08-08 (surfaced to the user as
+ * "Failed to start sandbox"). Six attempts span the client's 1+2+4+8+16 s
+ * backoff ≈ 31 s, comfortably past the observed window.
+ */
+const MACHINE_CREATE_ATTEMPTS = 6;
+/**
+ * Retrying a `POST /machines` on 404 is SAFE precisely because "app not found"
+ * means no Machine was created — unlike a 5xx/timeout, where one might have
+ * been. So only 404 is added here, on top of the client's default retryable
+ * set; the retry cannot double-create.
+ */
+const MACHINE_CREATE_RETRY_STATUSES = [404];
 /**
  * Base64 chunk size for {@link Sandbox.importFiles}'s temp-file write. Bounded by
  * the same Fly exec payload limit as `WRITE_CHUNK_BASE64` (~15 KB, silently
@@ -90,6 +107,12 @@ const IMPORT_EXTRACT_TIMEOUT_MS = 55_000;
  * the gzip pass before transfer is what keeps that count reasonable.
  */
 const IMPORT_WRITE_CHUNK_BASE64 = 12_000;
+/**
+ * Expiry for the presigned URLs {@link Sandbox.importFiles} uses to hand an
+ * archive to the object store and back to the Machine. Short — the upload and
+ * the single download happen back-to-back.
+ */
+const IMPORT_PRESIGN_EXPIRY_SECONDS = 3600;
 /** Extra seconds allowed for the probe exec beyond its connection budget. */
 const PROBE_EXEC_HEADROOM_SECONDS = 10;
 /**
@@ -391,7 +414,7 @@ class FlyioSandboxProvider {
      */
     async destroyStaleMachines(app) {
         const managedKey = `${this.metadataPrefix}.managed`;
-        let machines = null;
+        let machines;
         try {
             machines = await this.client.request(`/apps/${app}/machines`, {
                 nullOn: [404],
@@ -791,6 +814,11 @@ class FlyioSandboxProvider {
         const machine = await this.client.request(`/apps/${app}/machines`, {
             method: 'POST',
             body: { region: this.region(), config: machineConfig },
+            // A just-created app propagates to the Machines API asynchronously, so this
+            // POST can 404 "app not found" for a few seconds. Retry the 404 (safe: no
+            // Machine is created when the app is not found) across the client's backoff.
+            attempts: MACHINE_CREATE_ATTEMPTS,
+            retryStatuses: MACHINE_CREATE_RETRY_STATUSES,
         });
         if (!machine?.id) {
             throw new Error(t('codeSandbox.flyio.error.createFailed', { app }, { defaultValue: `Fly Machine creation in app "${app}" returned no Machine id.` }));
@@ -1495,25 +1523,63 @@ class FlyioSandboxProvider {
                 const parts = [];
                 for await (const chunk of archive)
                     parts.push(Buffer.from(chunk));
-                const base64 = gzipSync(Buffer.concat(parts)).toString('base64');
-                // 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=suspend can cold-start between them — which recreates the
-                // rootfs from the image (wiping /tmp) while the ext4 volume at
-                // /workspace persists. A /tmp temp file vanished mid-import; the volume
-                // one survives.
-                const tmp = `${WORKSPACE_PATH}/.mol-import-${machineId}.tgz`;
-                const quotedTmp = shellQuote(tmp);
+                const gz = gzipSync(Buffer.concat(parts));
                 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}`,
+                            defaultValue: `Failed to import files into ${path} (${step}): ${result.stderr || result.stdout}`,
                         }));
                     }
                 };
-                // First chunk truncates the temp file; the rest append. Each chunk is a
-                // multiple of 4 base64 chars so it decodes standalone (see writeFile).
+                // PREFERRED: upload the archive to the object store and have the Machine
+                // PULL it with a single curl. Fly's exec endpoint is rate-limited (~5/s)
+                // and caps each command near 15 KB, so streaming a multi-MB tar through
+                // it as base64 chunks triggers a 429 storm that never finishes. A
+                // presigned download is ONE request — the same pull pattern templates use
+                // (see buildRestoreCommand). Falls back to chunked exec when no store is
+                // configured (e.g. unit tests).
+                const store = provider.templateContext().store;
+                if (store) {
+                    const key = `${store.prefix}/.imports/${machineId}-${Date.now().toString(36)}${Math.floor(Math.random() * 1e9).toString(36)}.tar.gz`;
+                    try {
+                        const putUrl = await store.presignPut(key, IMPORT_PRESIGN_EXPIRY_SECONDS);
+                        const putRes = await fetch(putUrl, { method: 'PUT', body: gz });
+                        if (!putRes.ok) {
+                            throw new Error(`presigned PUT to the object store failed: ${putRes.status}`);
+                        }
+                        const getUrl = await store.presignGet(key, IMPORT_PRESIGN_EXPIRY_SECONDS);
+                        const result = await this.exec([
+                            'set -e',
+                            `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"`,
+                            'rm -f "$archive"',
+                        ].join('\n'), { timeout: IMPORT_EXTRACT_TIMEOUT_MS });
+                        // Best-effort: the temp object expires anyway, but delete it promptly.
+                        store.remove([key]).catch((error) => {
+                            logger.debug('importFiles temp object cleanup failed', { key, error });
+                        });
+                        failIfError(result, 'download');
+                        return;
+                    }
+                    catch (error) {
+                        // The store path is unavailable or failed — fall through to the
+                        // chunked-exec transport rather than failing the whole import.
+                        logger.warn('importFiles via object store failed; falling back to chunked exec', {
+                            error,
+                        });
+                    }
+                }
+                // FALLBACK: chunked base64 over exec. Only used when no object store is
+                // 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.
+                const base64 = gz.toString('base64');
+                const tmp = `${WORKSPACE_PATH}/.mol-import-${machineId}.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');

package/package.json

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