@molecule/api-code-sandbox-flyio 1.2.10 → 1.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +11 -11
- package/dist/exec.d.ts.map +1 -1
- package/dist/exec.js +114 -8
- package/dist/provider.d.ts.map +1 -1
- package/dist/provider.js +86 -4
- package/dist/types.d.ts +6 -0
- package/dist/types.d.ts.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -3,15 +3,11 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
|
3
3
|
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
4
|
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
5
|
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
-
Generated: 2026-10-
|
|
6
|
+
Generated: 2026-10-17T03:41:21.100Z
|
|
7
7
|
-->
|
|
8
8
|
|
|
9
9
|
# @molecule/api-code-sandbox-flyio
|
|
10
10
|
|
|
11
|
-
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
12
|
-
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
13
|
-
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
14
|
-
|
|
15
11
|
Fly.io Machines code-sandbox provider for molecule.dev.
|
|
16
12
|
|
|
17
13
|
Runs each sandbox as a Fly Machine — a Firecracker microVM — managed over the
|
|
@@ -20,6 +16,10 @@ SCALE-TO-ZERO: `sleep()` maps to Fly's `suspend`, which snapshots the microVM's
|
|
|
20
16
|
memory to disk, and a suspended Machine bills for storage only. Waking is a
|
|
21
17
|
resume from that snapshot rather than a cold boot.
|
|
22
18
|
|
|
19
|
+
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
20
|
+
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
21
|
+
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
22
|
+
|
|
23
23
|
## Quick Start
|
|
24
24
|
|
|
25
25
|
```typescript
|
|
@@ -384,6 +384,12 @@ interface FlyioConfig {
|
|
|
384
384
|
* `suspend` is the scale-to-zero mapping (resume from a memory snapshot on the
|
|
385
385
|
* next request) and `stop` is a full stop with a cold boot on wake; opt into
|
|
386
386
|
* either deliberately.
|
|
387
|
+
*
|
|
388
|
+
* This is the provider's STEADY-STATE policy, reported as
|
|
389
|
+
* `SandboxProvider.defaultIdleAction`. A caller can override it for one sandbox
|
|
390
|
+
* with `SandboxConfig.idleAction` and restore this value afterwards with
|
|
391
|
+
* `Sandbox.setIdleAction` — which is what a production deploy does so its
|
|
392
|
+
* destination cannot suspend mid-copy (m103, 2026-10-17).
|
|
387
393
|
*/
|
|
388
394
|
autostop?: 'off' | 'stop' | 'suspend'
|
|
389
395
|
/**
|
|
@@ -440,12 +446,6 @@ interface FlyioConfig {
|
|
|
440
446
|
* Falls back to `FLY_SANDBOX_PRIVATE_SERVICES` (`<app>:<port>` pairs).
|
|
441
447
|
*
|
|
442
448
|
* Without this, a project with a database DOES NOT WORK on Fly: per-project
|
|
443
|
-
* 6PNs are what stop tenants reaching each other, and the same isolation stops
|
|
444
|
-
* a sandbox reaching the database it is supposed to use. Flycast is the only
|
|
445
|
-
* mechanism Fly documents that grants ONE directed edge without exposing
|
|
446
|
-
* anything publicly — see the `flycast.ts` module description.
|
|
447
|
-
*
|
|
448
|
-
* The declared PORT is load-bearing twice: it is unioned into
|
|
449
449
|
// … truncated — the full declaration is in node_modules/@molecule/api-code-sandbox-flyio/dist/types.d.ts
|
|
450
450
|
```
|
|
451
451
|
|
package/dist/exec.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../src/exec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AAGzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAKjD;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,KAAK,CAAA;AAE9C;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAA;AAW5C;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAAkB,CAAA;
|
|
1
|
+
{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../src/exec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AAGzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAKjD;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,KAAK,CAAA;AAE9C;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAA;AAW5C;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAAkB,CAAA;AA6BxD;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAA;AAY5C;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAEzC,0FAA0F;AAC1F,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAA;AAE7F;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,UAAU,CAiBlE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,UAAU,EAAE,MAAM,GACjB,MAAM,CAGR;AAmDD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,UAAU,CAAC,CAqBrB"}
|
package/dist/exec.js
CHANGED
|
@@ -49,6 +49,24 @@ const DEFAULT_TIMEOUT_MS = 600_000;
|
|
|
49
49
|
* would try to materialize the whole thing in one response body.
|
|
50
50
|
*/
|
|
51
51
|
export const MAX_CAPTURED_OUTPUT_BYTES = 5 * 1024 * 1024;
|
|
52
|
+
/**
|
|
53
|
+
* Decoded bytes read per exec call when collecting a detached command's output.
|
|
54
|
+
*
|
|
55
|
+
* Fly documents NO output ceiling for the Machines API: the exec response's
|
|
56
|
+
* `flydv1.ExecResponse` schema types `stdout` and `stderr` as plain,
|
|
57
|
+
* unconstrained strings (https://docs.machines.dev/openapi.json). The live API
|
|
58
|
+
* still returns SHORT output with `exit_code: 0` once a response is large —
|
|
59
|
+
* measured 2026-10-18 in production (X1 flash-m175): one read of a
|
|
60
|
+
* 1,421,432-byte database file came back 897,144 bytes long, exactly one
|
|
61
|
+
* 512 KiB slice missing, with no error at all. So the collector asks for no
|
|
62
|
+
* more than this per response and checks every response's decoded length
|
|
63
|
+
* against what it asked for, shrinking the request when the transport cuts it.
|
|
64
|
+
*/
|
|
65
|
+
const COLLECT_CHUNK_BYTES = 128 * 1024;
|
|
66
|
+
/** Smallest chunk a shortened response is re-read with, before giving up. */
|
|
67
|
+
const MIN_COLLECT_CHUNK_BYTES = 16 * 1024;
|
|
68
|
+
/** Read attempts per chunk before the collection is reported as truncated. */
|
|
69
|
+
const COLLECT_ATTEMPTS = 4;
|
|
52
70
|
/**
|
|
53
71
|
* Base64 chunk size for spilling a large script to a file, comfortably under
|
|
54
72
|
* {@link FLY_EXEC_MAX_ARG_BYTES} once the `printf … | base64 -d` wrapper is added.
|
|
@@ -188,6 +206,96 @@ export async function execCommand(rawExec, command, opts, defaultCwd) {
|
|
|
188
206
|
}
|
|
189
207
|
return await execDetached(rawExec, script, budgetMs);
|
|
190
208
|
}
|
|
209
|
+
/**
|
|
210
|
+
* Sizes of a detached run's two output spool files, in bytes. A file the
|
|
211
|
+
* command never created reads as 0.
|
|
212
|
+
* @param rawExec - Transport callback issuing one Fly exec call.
|
|
213
|
+
* @param outPath - Absolute path of the stdout spool.
|
|
214
|
+
* @param errPath - Absolute path of the stderr spool.
|
|
215
|
+
* @returns Both byte counts.
|
|
216
|
+
* @throws {Error} When the sizes cannot be read at all.
|
|
217
|
+
*/
|
|
218
|
+
async function spoolSizes(rawExec, outPath, errPath) {
|
|
219
|
+
const sizes = toExecResult(await rawExec([
|
|
220
|
+
'sh',
|
|
221
|
+
'-c',
|
|
222
|
+
`stat -c %s ${outPath} 2>/dev/null || echo 0; stat -c %s ${errPath} 2>/dev/null || echo 0`,
|
|
223
|
+
], CONTROL_EXEC_TIMEOUT_SECONDS));
|
|
224
|
+
if (sizes.exitCode !== 0) {
|
|
225
|
+
throw new Error(`Failed to inspect the detached command's output files: ${sizes.stderr || sizes.stdout}`);
|
|
226
|
+
}
|
|
227
|
+
const [out, err] = sizes.stdout
|
|
228
|
+
.trim()
|
|
229
|
+
.split('\n')
|
|
230
|
+
.map((value) => Number(value.trim()));
|
|
231
|
+
return {
|
|
232
|
+
stdout: Number.isFinite(out) ? out : 0,
|
|
233
|
+
stderr: Number.isFinite(err) ? err : 0,
|
|
234
|
+
};
|
|
235
|
+
}
|
|
236
|
+
/**
|
|
237
|
+
* Reads `size` bytes of a spool file back through exec in LENGTH-CHECKED
|
|
238
|
+
* chunks, shrinking the chunk whenever a response comes back short.
|
|
239
|
+
*
|
|
240
|
+
* One raw `head -c 5 MiB` of the spool is the shape that lost a whole slice of
|
|
241
|
+
* a database in production (see {@link COLLECT_CHUNK_BYTES}): Fly truncated
|
|
242
|
+
* the response and still reported success. Every chunk here is verified against
|
|
243
|
+
* the number of bytes asked for, retried at half the size when it is short (a
|
|
244
|
+
* truncating transport cuts at a response size, so a smaller request survives
|
|
245
|
+
* it), and a chunk that will not arrive whole fails the collection by name
|
|
246
|
+
* instead of returning silently shortened output.
|
|
247
|
+
*
|
|
248
|
+
* The bytes are base64-encoded on the Machine and decoded here as BYTES, so a
|
|
249
|
+
* chunk boundary falling inside a multi-byte UTF-8 character cannot corrupt it.
|
|
250
|
+
* @param rawExec - Transport callback issuing one Fly exec call.
|
|
251
|
+
* @param path - Absolute path of the spool file.
|
|
252
|
+
* @param size - Bytes to collect (already capped by the caller).
|
|
253
|
+
* @returns The collected text.
|
|
254
|
+
* @throws {Error} When a chunk cannot be read whole from the transport.
|
|
255
|
+
*/
|
|
256
|
+
async function collectSpool(rawExec, path, size) {
|
|
257
|
+
const parts = [];
|
|
258
|
+
let chunkBytes = COLLECT_CHUNK_BYTES;
|
|
259
|
+
for (let offset = 0; offset < size;) {
|
|
260
|
+
let received = null;
|
|
261
|
+
let want = 0;
|
|
262
|
+
let receivedBytes = 0;
|
|
263
|
+
for (let attempt = 1; attempt <= COLLECT_ATTEMPTS; attempt++) {
|
|
264
|
+
want = Math.min(chunkBytes, size - offset);
|
|
265
|
+
const read = toExecResult(await rawExec(['sh', '-c', `tail -c +${offset + 1} ${path} 2>/dev/null | head -c ${want} | base64 -w0`], CONTROL_EXEC_TIMEOUT_SECONDS));
|
|
266
|
+
if (read.exitCode !== 0) {
|
|
267
|
+
throw new Error(`Failed to read the detached command's output back: ${read.stderr || read.stdout}`);
|
|
268
|
+
}
|
|
269
|
+
const decoded = Buffer.from(read.stdout.trim(), 'base64');
|
|
270
|
+
receivedBytes = decoded.length;
|
|
271
|
+
if (decoded.length === want) {
|
|
272
|
+
received = decoded;
|
|
273
|
+
break;
|
|
274
|
+
}
|
|
275
|
+
// Short: the transport cut this response. Ask for less, so the next
|
|
276
|
+
// attempt fits under whatever its ceiling turns out to be.
|
|
277
|
+
const nextChunkBytes = Math.max(MIN_COLLECT_CHUNK_BYTES, Math.floor(want / 2));
|
|
278
|
+
logger.warn('Fly returned a short output read; retrying in a smaller chunk', {
|
|
279
|
+
path,
|
|
280
|
+
offset,
|
|
281
|
+
want,
|
|
282
|
+
received: decoded.length,
|
|
283
|
+
nextChunkBytes,
|
|
284
|
+
attempt,
|
|
285
|
+
});
|
|
286
|
+
chunkBytes = nextChunkBytes;
|
|
287
|
+
}
|
|
288
|
+
if (received === null) {
|
|
289
|
+
throw new Error(`The detached command's output could not be collected: the Fly exec transport ` +
|
|
290
|
+
`returned ${receivedBytes} of ${want} bytes at offset ${offset} of ${path}, over ` +
|
|
291
|
+
`${COLLECT_ATTEMPTS} reads with the chunk shrunk to ${chunkBytes} bytes. The command ` +
|
|
292
|
+
'itself finished; this is an output-collection (transport) failure — run it again.');
|
|
293
|
+
}
|
|
294
|
+
parts.push(received);
|
|
295
|
+
offset += want;
|
|
296
|
+
}
|
|
297
|
+
return Buffer.concat(parts).toString('utf8');
|
|
298
|
+
}
|
|
191
299
|
/**
|
|
192
300
|
* Runs a script detached inside the Machine and polls for its completion.
|
|
193
301
|
*
|
|
@@ -235,14 +343,12 @@ async function execDetached(rawExec, script, budgetMs) {
|
|
|
235
343
|
break;
|
|
236
344
|
}
|
|
237
345
|
}
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
const
|
|
244
|
-
const stdout = separator === -1 ? collect.stdout : collect.stdout.slice(0, separator);
|
|
245
|
-
const stderr = separator === -1 ? '' : collect.stdout.slice(separator + '\n__MOL_STDERR__\n'.length);
|
|
346
|
+
// Collect the spools in length-checked chunks BEFORE any cleanup: a single
|
|
347
|
+
// raw read of a large stdout is exactly what came back shortened (exit 0)
|
|
348
|
+
// in production, and the spool is the only copy there is.
|
|
349
|
+
const sizes = await spoolSizes(rawExec, outPath, errPath);
|
|
350
|
+
const stdout = await collectSpool(rawExec, outPath, Math.min(sizes.stdout, MAX_CAPTURED_OUTPUT_BYTES));
|
|
351
|
+
const stderr = await collectSpool(rawExec, errPath, Math.min(sizes.stderr, MAX_CAPTURED_OUTPUT_BYTES));
|
|
246
352
|
if (rc === null) {
|
|
247
353
|
// Still running at the deadline. The bookkeeping files are deliberately NOT
|
|
248
354
|
// removed — the process owns them and will keep writing.
|
package/dist/provider.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,
|
|
1
|
+
{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAYV,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;AAkBnB;;;;;;;;;;;;;;;;;;;;;;;;;;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;AAkyFD;;;;;;;;;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
CHANGED
|
@@ -293,6 +293,15 @@ const PROBE_EXEC_HEADROOM_SECONDS = 10;
|
|
|
293
293
|
*/
|
|
294
294
|
class FlyioSandboxProvider {
|
|
295
295
|
name = 'flyio';
|
|
296
|
+
/**
|
|
297
|
+
* The idle policy a sandbox gets when its own create does not name one — this
|
|
298
|
+
* provider's configured `autostop` (`FLY_PRODUCTION_AUTOSTOP` for production
|
|
299
|
+
* hosting). {@link SandboxConfig.idleAction} overrides it per Machine, and
|
|
300
|
+
* {@link Sandbox.setIdleAction} puts it back, which is how a deploy keeps its
|
|
301
|
+
* destination awake through a multi-minute copy and then returns the Machine
|
|
302
|
+
* to the app's real cost policy.
|
|
303
|
+
*/
|
|
304
|
+
defaultIdleAction;
|
|
296
305
|
config;
|
|
297
306
|
client;
|
|
298
307
|
metadataPrefix;
|
|
@@ -315,6 +324,7 @@ class FlyioSandboxProvider {
|
|
|
315
324
|
*/
|
|
316
325
|
constructor(config = {}, client, store) {
|
|
317
326
|
this.config = config;
|
|
327
|
+
this.defaultIdleAction = config.autostop ?? 'off';
|
|
318
328
|
this.metadataPrefix = config.metadataPrefix ?? DEFAULT_METADATA_PREFIX;
|
|
319
329
|
if (store !== undefined)
|
|
320
330
|
this.templateStoreCache = store;
|
|
@@ -410,10 +420,14 @@ class FlyioSandboxProvider {
|
|
|
410
420
|
* instead driven by the consumer's own per-tier hibernation loop, which calls
|
|
411
421
|
* `sleep()`/`hibernate()` — the same provider-agnostic mechanism the Docker
|
|
412
422
|
* bond relies on. An operator who wants Fly-native scale-to-zero can still opt
|
|
413
|
-
* in with `config.autostop: 'suspend'
|
|
423
|
+
* in with `config.autostop: 'suspend'`, and a caller can override it for ONE
|
|
424
|
+
* Machine with {@link SandboxConfig.idleAction} (a production deploy keeps its
|
|
425
|
+
* destination `'off'` until the artifact has landed and the app is healthy).
|
|
426
|
+
* @param action - The idle action for this Machine's service; defaults to the
|
|
427
|
+
* provider's configured policy.
|
|
414
428
|
* @returns The service definition, or `undefined`.
|
|
415
429
|
*/
|
|
416
|
-
previewService() {
|
|
430
|
+
previewService(action = this.defaultIdleAction) {
|
|
417
431
|
if (this.config.publicService === false)
|
|
418
432
|
return undefined;
|
|
419
433
|
return {
|
|
@@ -424,7 +438,7 @@ class FlyioSandboxProvider {
|
|
|
424
438
|
{ port: 443, handlers: ['tls', 'http'] },
|
|
425
439
|
],
|
|
426
440
|
autostart: true,
|
|
427
|
-
autostop:
|
|
441
|
+
autostop: action,
|
|
428
442
|
min_machines_running: 0,
|
|
429
443
|
};
|
|
430
444
|
}
|
|
@@ -1161,7 +1175,7 @@ class FlyioSandboxProvider {
|
|
|
1161
1175
|
// rootfs and only durable state pays the volume's small-file IO cost.
|
|
1162
1176
|
machineConfig.mounts = [{ volume: volumeId, path: config.volumeMountPath ?? WORKSPACE_PATH }];
|
|
1163
1177
|
}
|
|
1164
|
-
const service = this.previewService();
|
|
1178
|
+
const service = this.previewService(config.idleAction);
|
|
1165
1179
|
if (service)
|
|
1166
1180
|
machineConfig.services = [service];
|
|
1167
1181
|
const machine = await this.client.request(`/apps/${app}/machines`, {
|
|
@@ -2127,6 +2141,65 @@ class FlyioSandboxProvider {
|
|
|
2127
2141
|
`${totalSeconds}s (last observed state: ${lastState ?? 'unknown'}).`,
|
|
2128
2142
|
}), { cause: lastError });
|
|
2129
2143
|
}
|
|
2144
|
+
/**
|
|
2145
|
+
* Applies an idle policy to a running Machine's public service, in place.
|
|
2146
|
+
*
|
|
2147
|
+
* Fly's update endpoint takes the ENTIRE Machine config — "we don't support
|
|
2148
|
+
* partial updates" — and "If the Machine is running and the request is
|
|
2149
|
+
* successful, it will reboot" (verified against
|
|
2150
|
+
* https://docs.fly.io/machines/api/machines-resource, 2026-10-17). So this
|
|
2151
|
+
* re-reads the Machine, changes only each service's `autostop`, and waits for
|
|
2152
|
+
* the Machine to reach `started` again before resolving: the caller's next act
|
|
2153
|
+
* is to run commands in it. A Machine that ALREADY has the policy is left
|
|
2154
|
+
* alone — the reboot is a real cost, not a formality — and one that is not
|
|
2155
|
+
* running is updated with `skip_launch` so changing a parked Machine's policy
|
|
2156
|
+
* does not wake it.
|
|
2157
|
+
*
|
|
2158
|
+
* A Machine with no services has no proxy in front of it and therefore no
|
|
2159
|
+
* idle policy; that is a supported shape (a private sandbox), not an error.
|
|
2160
|
+
*
|
|
2161
|
+
* @param app - The Fly app name.
|
|
2162
|
+
* @param machineId - The Fly Machine id.
|
|
2163
|
+
* @param action - The idle action to apply to every service.
|
|
2164
|
+
* @throws {Error} When the Machine or its config cannot be read, the update is
|
|
2165
|
+
* rejected, or a rebooted Machine does not come back to `started`.
|
|
2166
|
+
*/
|
|
2167
|
+
async applyIdleAction(app, machineId, action) {
|
|
2168
|
+
const machine = await this.client.request(`/apps/${app}/machines/${machineId}`, {
|
|
2169
|
+
nullOn: [404],
|
|
2170
|
+
});
|
|
2171
|
+
if (!machine?.config) {
|
|
2172
|
+
throw new Error(t('codeSandbox.flyio.error.idlePolicyUnreadable', { machineId }, {
|
|
2173
|
+
defaultValue: `Cannot change the idle policy of Fly Machine ${machineId}: its config could not be ` +
|
|
2174
|
+
'read, so the Machine is left exactly as it is.',
|
|
2175
|
+
}));
|
|
2176
|
+
}
|
|
2177
|
+
const services = machine.config.services;
|
|
2178
|
+
if (!services?.length)
|
|
2179
|
+
return;
|
|
2180
|
+
if (services.every((service) => (service.autostop ?? 'off') === action))
|
|
2181
|
+
return;
|
|
2182
|
+
const config = {
|
|
2183
|
+
...machine.config,
|
|
2184
|
+
services: services.map((service) => ({ ...service, autostop: action })),
|
|
2185
|
+
};
|
|
2186
|
+
// A running Machine reboots to apply the config, so wait for it; a parked
|
|
2187
|
+
// one is updated without being started (there is nothing to wait for).
|
|
2188
|
+
const wasRunning = machine.state === 'started' || machine.state === 'starting';
|
|
2189
|
+
await this.client.request(`/apps/${app}/machines/${machineId}`, {
|
|
2190
|
+
method: 'POST',
|
|
2191
|
+
body: {
|
|
2192
|
+
config,
|
|
2193
|
+
// Immutable, but the update body is a whole Machine description; send
|
|
2194
|
+
// back what was read rather than letting Fly infer them.
|
|
2195
|
+
...(machine.name ? { name: machine.name } : {}),
|
|
2196
|
+
...(machine.region ? { region: machine.region } : {}),
|
|
2197
|
+
...(wasRunning ? {} : { skip_launch: true }),
|
|
2198
|
+
},
|
|
2199
|
+
});
|
|
2200
|
+
if (wasRunning)
|
|
2201
|
+
await this.waitForStarted(app, machineId);
|
|
2202
|
+
}
|
|
2130
2203
|
/**
|
|
2131
2204
|
* Builds the `Sandbox` facade for one Machine.
|
|
2132
2205
|
* @param app - The Fly app name.
|
|
@@ -2171,6 +2244,15 @@ class FlyioSandboxProvider {
|
|
|
2171
2244
|
await provider.startMachine(app, machineId);
|
|
2172
2245
|
this.status = 'running';
|
|
2173
2246
|
},
|
|
2247
|
+
/**
|
|
2248
|
+
* Applies an idle policy to this Machine's public service (see
|
|
2249
|
+
* {@link FlyioSandboxProvider.applyIdleAction} for the endpoint and the
|
|
2250
|
+
* reboot it costs). Resolves with the Machine running again.
|
|
2251
|
+
*/
|
|
2252
|
+
async setIdleAction(action) {
|
|
2253
|
+
await provider.applyIdleAction(app, machineId, action);
|
|
2254
|
+
this.status = 'running';
|
|
2255
|
+
},
|
|
2174
2256
|
async exec(command, opts) {
|
|
2175
2257
|
return await execCommand(exec, command, opts, WORKSPACE_PATH);
|
|
2176
2258
|
},
|
package/dist/types.d.ts
CHANGED
|
@@ -111,6 +111,12 @@ export interface FlyioConfig {
|
|
|
111
111
|
* `suspend` is the scale-to-zero mapping (resume from a memory snapshot on the
|
|
112
112
|
* next request) and `stop` is a full stop with a cold boot on wake; opt into
|
|
113
113
|
* either deliberately.
|
|
114
|
+
*
|
|
115
|
+
* This is the provider's STEADY-STATE policy, reported as
|
|
116
|
+
* `SandboxProvider.defaultIdleAction`. A caller can override it for one sandbox
|
|
117
|
+
* with `SandboxConfig.idleAction` and restore this value afterwards with
|
|
118
|
+
* `Sandbox.setIdleAction` — which is what a production deploy does so its
|
|
119
|
+
* destination cannot suspend mid-copy (m103, 2026-10-17).
|
|
114
120
|
*/
|
|
115
121
|
autostop?: 'off' | 'stop' | 'suspend';
|
|
116
122
|
/**
|
package/dist/types.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gGAAgG;IAChG,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,kFAAkF;IAClF,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,kEAAkE;IAClE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,6FAA6F;IAC7F,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/api-code-sandbox-flyio",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.3.1",
|
|
4
4
|
"description": "Fly.io Machines (Firecracker microVM) code sandbox provider",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -31,7 +31,7 @@
|
|
|
31
31
|
"license": "Apache-2.0",
|
|
32
32
|
"devDependencies": {
|
|
33
33
|
"@molecule/api-bond": "1.0.2",
|
|
34
|
-
"@molecule/api-code-sandbox": "1.
|
|
34
|
+
"@molecule/api-code-sandbox": "1.4.0",
|
|
35
35
|
"@types/node": "26.1.2",
|
|
36
36
|
"typescript": "6.0.3",
|
|
37
37
|
"vitest": "4.1.11"
|