withruntime 0.8.4 → 0.10.0

package/dist/products/volumes.d.ts

@@ -10,6 +10,16 @@ export type Volume = {
     labels: Record<string, string>;
     region: string;
     sizeMiB: number;
+    /** Fixed at creation; shared disks support concurrent writers. */
+    shared?: boolean;
+    resize?: {
+        id: string;
+        operationId: string;
+        sizeMiB: number;
+        state: "pending" | "running" | "completed" | "failed";
+        generation: number;
+        error: string | null;
+    } | null;
     filesystem: "ext4";
     usedMiB: number | null;
     measuredAt: string | null;
@@ -24,6 +34,8 @@ export type Volume = {
     /** The backup this volume was restored from, if any. */
     restoredFrom: string | null;
     attachments: {
+        id?: string;
+        state?: VolumeAttachment["state"];
         sandboxId: string;
         mode: "rw" | "snapshot";
         path: string;
@@ -34,6 +46,8 @@ export type Volume = {
     readyAt: string | null;
 };
 export type CreateVolume = {
+    /** Available where shared disks are enabled. Fixed at creation. */
+    shared?: boolean;
     /** Required unless restoring: a restore is the backup's size. */
     sizeMiB?: number;
     /** A ready backup to restore into the new volume, on any host in its region. */
@@ -42,6 +56,18 @@ export type CreateVolume = {
     labels?: Record<string, string>;
     region?: string;
 };
+export type VolumeAttachment = {
+    id: string;
+    volumeId: string;
+    sandboxId: string;
+    path: string;
+    mode: "rw";
+    state: "attaching" | "active" | "detaching" | "detached";
+    generation: number;
+    error: string | null;
+    attachedAt: string;
+    changedAt: string;
+};
 export type VolumeBackupState = "pending" | "ready" | "failed" | "deleting" | "deleted";
 /** A point-in-time copy of a volume, kept off its host. */
 export type VolumeBackup = {
@@ -78,6 +104,22 @@ export declare function volumes(t: Transport): {
         limit?: number;
         cursor?: string;
     }, options?: RequestOptions) => Promise<Page<Volume>>;
+    /** Grow a detached ordinary disk; wait up to 10 s for the operation. */
+    resize: (id: string, input: {
+        sizeMiB: number;
+    }, options?: RequestOptions & {
+        wait?: number;
+    }) => Promise<Volume>;
+    attach: (id: string, input: {
+        sandboxId: string;
+        path: string;
+    }, options?: RequestOptions & {
+        wait?: number;
+    }) => Promise<VolumeAttachment>;
+    detach: (id: string, attachmentId: string, options?: RequestOptions & {
+        wait?: number;
+    }) => Promise<VolumeAttachment>;
+    getAttachment: (id: string, attachmentId: string, options?: RequestOptions) => Promise<VolumeAttachment>;
     delete: (id: string, options?: RequestOptions) => Promise<Volume>;
     /** Back a volume up now, off its host, and wait (up to a minute, or
      * `wait` seconds) for it to be ready. */

package/dist/products/volumes.js

@@ -29,6 +29,42 @@ export function volumes(t) {
         create: (input, options) => t.json({ method: "POST", path: "/v1/volumes", body: input, wait: 10, ...options }),
         get,
         list,
+        /** Grow a detached ordinary disk; wait up to 10 s for the operation. */
+        resize: (id, input, options = {}) => {
+            const { wait = 10, ...rest } = options;
+            return t.json({
+                method: "POST",
+                path: `/v1/volumes/${enc(id)}:resize`,
+                body: input,
+                wait,
+                ...rest,
+            });
+        },
+        attach: (id, input, options = {}) => {
+            const { wait = 10, ...rest } = options;
+            return t.json({
+                method: "POST",
+                path: `/v1/volumes/${enc(id)}:attach`,
+                body: input,
+                wait,
+                ...rest,
+            });
+        },
+        detach: (id, attachmentId, options = {}) => {
+            const { wait = 10, ...rest } = options;
+            return t.json({
+                method: "POST",
+                path: `/v1/volumes/${enc(id)}/attachments/${enc(attachmentId)}:detach`,
+                body: {},
+                wait,
+                ...rest,
+            });
+        },
+        getAttachment: (id, attachmentId, options) => t.json({
+            method: "GET",
+            path: `/v1/volumes/${enc(id)}/attachments/${enc(attachmentId)}`,
+            ...options,
+        }),
         delete: (id, options) => t.json({
             method: "POST",
             path: `/v1/volumes/${enc(id)}:delete`,

package/dist/products/watch.d.ts

@@ -1,5 +1,5 @@
 import type { RequestOptions, Transport } from "../transport.js";
-export type FileEventType = "create" | "write" | "remove" | "rename" | "chmod";
+export type FileEventType = "create" | "write" | "remove" | "rename" | "chmod" | "access";
 export type FileEvent = {
     type: FileEventType;
     /** Absolute path in the sandbox. */
@@ -23,7 +23,7 @@ export type WatchNotice = {
 };
 export type WatchOptions = Omit<RequestOptions, "timeoutMs"> & {
     recursive?: boolean;
-    /** Only these event types; all five by default. */
+    /** Only these event types; the five mutation types by default; access is opt-in. */
     events?: FileEventType[];
     /** Globs relative to the path: only matching paths are reported. */
     include?: string[];
@@ -31,7 +31,7 @@ export type WatchOptions = Omit<RequestOptions, "timeoutMs"> & {
     exclude?: string[];
     /** Events are gathered this long and delivered together. Default 100. */
     batchMs?: number;
-    /** The watch ends by itself after running this long. Default 1 hour. */
+    /** The watch ends by itself after running this long. Default 1 hour; 0 runs until stopped or the sandbox ends. */
     timeoutMs?: number;
     maxWatches?: number;
     /** A batch at a time, rather than one call per event. */
@@ -49,6 +49,16 @@ export type WatchInfo = {
     processId: string;
     state: string;
     startedAt: number;
+    /** Its changes go to the account's webhooks as `sandbox.files.changed`. */
+    webhook?: boolean;
+};
+/** A watch whose changes Runtime sends to the account's webhooks. */
+export type WebhookWatchOptions = Omit<WatchOptions, "onBatch" | "onNotice" | "onExit" | "timeoutMs"> & {
+    /** The watch ends by itself after running this long; 0 (the default here)
+     * runs until stopped or the sandbox ends. */
+    timeoutMs?: number;
+    /** Its own id, 1 to 40 lowercase letters, digits or dashes. */
+    id?: string;
 };
 /** A running watch. Events arrive through the callbacks until `stop()`. */
 export declare class WatchHandle {
@@ -65,7 +75,9 @@ export declare class WatchHandle {
     get done(): Promise<void>;
     /** Start delivering again from where it left off, after a pause. */
     resume(): void;
-    /** Stop the watch in the sandbox, and stop delivering. */
+    /** Stop the watch in the sandbox. What changed before the stop is still
+     * delivered: the watch reports it and ends, and this returns once that has
+     * arrived (at most 5 s). Called from inside a callback, it stops at once. */
     stop(options?: RequestOptions): Promise<void>;
     /** @internal */
     begin(): this;
@@ -85,6 +97,15 @@ export declare function sandboxWatches(t: Transport, sandboxId: string): {
         lostBytes: number;
         ended: boolean;
     }>;
+    /** Starts a watch whose changes Runtime sends to the account's webhooks
+     * as `sandbox.files.changed` events, with nothing reading it here:
+     *
+     *   await sbx.files.watches.webhook("/workspace/app", { recursive: true });
+     *
+     * Runs until stopped (timeoutMs 0) unless given a timeout. */
+    webhook: (path: string, input?: WebhookWatchOptions) => Promise<WatchInfo & {
+        cursor: number;
+    }>;
     stop: (id: string, options?: RequestOptions) => Promise<{
         stopped: boolean;
     }>;

package/dist/products/watch.js

@@ -1,3 +1,5 @@
+import { WEBHOOK_WATCH_TIMEOUT_MS } from "../api-defaults.js";
+import { RuntimeError } from "../errors.js";
 /** A running watch. Events arrive through the callbacks until `stop()`. */
 export class WatchHandle {
     t;
@@ -8,7 +10,15 @@ export class WatchHandle {
     onEvent;
     cursor;
     #stopped = false;
+    /** stop() was called: deliver what the watch reports until its end. */
+    #stopping = false;
+    #stopPending;
+    #remoteStop;
+    /** Callbacks under way. */
+    #delivering = 0;
+    #exitNotified = false;
     #following;
+    #followingActive = false;
     #abort = new AbortController();
     constructor(t, base, id, path, cursor, options, onEvent) {
         this.t = t;
@@ -25,24 +35,84 @@ export class WatchHandle {
     }
     /** Start delivering again from where it left off, after a pause. */
     resume() {
-        if (this.#stopped)
+        if (this.#stopped || this.#stopping)
             throw new Error("This watch was stopped");
+        if (this.#followingActive)
+            throw new Error("This watch is already delivering");
         this.#abort = new AbortController();
         this.begin();
     }
-    /** Stop the watch in the sandbox, and stop delivering. */
+    /** Stop the watch in the sandbox. What changed before the stop is still
+     * delivered: the watch reports it and ends, and this returns once that has
+     * arrived (at most 5 s). Called from inside a callback, it stops at once. */
     async stop(options) {
         if (this.#stopped)
             return;
+        if (this.#stopping) {
+            // Even a callback must observe whether the remote delete succeeded.
+            // It cannot join the drain, which is waiting for that callback to finish.
+            await this.#remoteStop;
+            if (this.#delivering === 0)
+                await this.#stopPending;
+            else
+                this.#finishLocalStop();
+            return;
+        }
+        this.#stopping = true;
+        this.#remoteStop = (async () => await this.t.json({
+            method: "DELETE",
+            path: `${this.base}/${encodeURIComponent(this.id)}`,
+            ...options,
+        }))();
+        const pending = this.#finishStop(this.#remoteStop);
+        this.#stopPending = pending;
+        try {
+            await pending;
+        }
+        finally {
+            if (this.#stopPending === pending) {
+                this.#stopPending = undefined;
+                this.#remoteStop = undefined;
+            }
+        }
+    }
+    async #finishStop(remote) {
+        try {
+            await remote;
+        }
+        catch (error) {
+            // A failed delete does not prove the remote watch stopped. Close local
+            // delivery, but let the caller observe the failure and retry the delete.
+            this.#abort.abort();
+            this.#stopping = false;
+            throw error;
+        }
+        // Inside a callback, #following is awaiting the caller: waiting for it
+        // here would make that callback await itself.
+        if (this.#following && this.#delivering === 0) {
+            let timer;
+            await Promise.race([
+                this.#following.catch(() => undefined),
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, 5_000);
+                }),
+            ]);
+            clearTimeout(timer);
+        }
+        this.#finishLocalStop();
+    }
+    #finishLocalStop() {
         this.#stopped = true;
         this.#abort.abort();
-        await this.t
-            .json({ method: "DELETE", path: `${this.base}/${encodeURIComponent(this.id)}`, ...options })
-            .catch(() => undefined);
-        await this.#following?.catch(() => undefined);
-        this.options.onExit?.("stopped");
+        this.#notifyExit("stopped");
+    }
+    #notifyExit(reason) {
+        if (this.#exitNotified)
+            return;
+        this.#exitNotified = true;
+        this.options.onExit?.(reason);
     }
-    async #follow() {
+    async #follow(abort) {
         for (;;) {
             let next = "exit";
             try {
@@ -50,32 +120,52 @@ export class WatchHandle {
                     method: "GET",
                     path: `${this.base}/${encodeURIComponent(this.id)}/events`,
                     query: { cursor: this.cursor, follow: true },
-                    signal: this.#abort.signal,
+                    signal: abort.signal,
                     timeoutMs: 150_000,
                 })) {
                     this.cursor = event.cursor ?? this.cursor;
                     if (event.k === "events") {
-                        if (this.options.onBatch)
-                            await this.options.onBatch(event.events);
-                        if (this.onEvent)
-                            for (const item of event.events)
-                                await this.onEvent(item);
+                        this.#delivering++;
+                        try {
+                            if (this.options.onBatch)
+                                await this.options.onBatch(event.events);
+                            if (this.#stopped)
+                                return;
+                            if (this.onEvent)
+                                for (const item of event.events) {
+                                    await this.onEvent(item);
+                                    if (this.#stopped)
+                                        return;
+                                }
+                        }
+                        finally {
+                            this.#delivering--;
+                        }
                     }
                     else if (event.k === "continue")
                         next = "continue";
                     else if (event.k === "end" || event.k === "paused") {
+                        // A paused callback may resume immediately. Retire this reader
+                        // before invoking it, without letting its finalizer retire the new one.
+                        this.#followingActive = false;
                         if (!this.#stopped)
-                            this.options.onExit?.(event.k === "paused" ? "paused" : event.reason);
+                            this.#notifyExit(event.k === "paused" ? "paused" : event.reason);
                         return;
                     }
                     else if (event.k === "failure")
-                        throw new Error(`${event.code}: ${event.message}`);
+                        throw new RuntimeError({
+                            code: event.code,
+                            status: event.status ?? 0,
+                            message: event.message,
+                            ...(event.hint ? { hint: event.hint } : {}),
+                            ...(event.requestId ? { requestId: event.requestId } : {}),
+                        });
                     else
                         this.options.onNotice?.(event);
                 }
             }
             catch (error) {
-                if (this.#stopped || this.#abort.signal.aborted)
+                if (this.#stopped || abort.signal.aborted)
                     return;
                 throw error;
             }
@@ -85,7 +175,15 @@ export class WatchHandle {
     }
     /** @internal */
     begin() {
-        this.#following = this.#follow();
+        if (this.#followingActive)
+            throw new Error("This watch is already delivering");
+        this.#exitNotified = false;
+        this.#followingActive = true;
+        const abort = this.#abort;
+        this.#following = this.#follow(abort).finally(() => {
+            if (this.#abort === abort)
+                this.#followingActive = false;
+        });
         // An error surfaces through `done`; nothing is left unhandled meanwhile.
         this.#following.catch(() => undefined);
         return this;
@@ -126,6 +224,22 @@ export function sandboxWatches(t, sandboxId) {
             query: { cursor, ...(input.waitMs !== undefined ? { waitMs: input.waitMs } : {}) },
             ...options,
         }),
+        /** Starts a watch whose changes Runtime sends to the account's webhooks
+         * as `sandbox.files.changed` events, with nothing reading it here:
+         *
+         *   await sbx.files.watches.webhook("/workspace/app", { recursive: true });
+         *
+         * Runs until stopped (timeoutMs 0) unless given a timeout. */
+        webhook: (path, input = {}) => {
+            const { idempotencyKey, signal, timeoutMs, ...rest } = input;
+            return t.json({
+                method: "POST",
+                path: base,
+                body: { path, ...rest, timeoutMs: timeoutMs ?? WEBHOOK_WATCH_TIMEOUT_MS, webhook: true },
+                ...(idempotencyKey ? { idempotencyKey } : {}),
+                ...(signal ? { signal } : {}),
+            });
+        },
         stop: (id, options) => t.json({
             method: "DELETE",
             path: `${base}/${encodeURIComponent(id)}`,

package/dist/proxy.js

@@ -72,7 +72,9 @@ export function routeFor(target, env = processEnv()) {
         parsed = new URL(proxy);
     }
     catch {
-        throw invalidProxy(found.name, found.value, "is not an address");
+        // A malformed address cannot be parsed reliably enough to remove its
+        // credentials. Keep the variable name, never its untrusted value.
+        throw invalidProxy(found.name, "invalid address", "is not an address");
     }
     if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
         throw invalidProxy(found.name, `${parsed.protocol}//${parsed.host}`, "is not an HTTP proxy");