@molecule/api-code-sandbox-flyio 1.2.3 → 1.2.5

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-16T14:04:35.624Z
+Generated: 2026-10-08T03:25:09.946Z
 -->
 
 # @molecule/api-code-sandbox-flyio
@@ -2145,6 +2145,17 @@ refused, a leading `/` stripped, a write through a symlink refused, and
 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

@@ -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;AA20EnB;;;;;;;;;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 });
         }
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-code-sandbox-flyio",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "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.2",
-    "@molecule/api-code-sandbox": "1.2.1",
+    "@molecule/api-code-sandbox": "1.3.0",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
     "vitest": "4.1.11"