withruntime 0.11.1 → 0.12.0

package/dist/identity.d.ts

@@ -25,3 +25,6 @@ export declare function identityToken(input: {
     lifetimeSeconds?: number;
     signal?: AbortSignal;
 }): Promise<IdentityToken>;
+/** Headers for a call to the website's connect API: this sandbox's identity
+ * token, or none outside a sandbox or when one cannot be had. Never throws. */
+export declare function sandboxIdentityHeaders(): Promise<Record<string, string>>;

package/dist/identity.js

@@ -55,3 +55,30 @@ export async function identityToken(input) {
         });
     return body;
 }
+/** The header and audience the website keys its per-network limits on
+ * (apps/cloud-web/src/lib/limit-key.ts): inside a sandbox, Runtime's own
+ * sign-in calls count against this sandbox, not the address every sandbox on
+ * its host shares. */
+const LIMIT_HEADER = "x-runtime-sandbox-identity";
+const LIMIT_AUDIENCE = "https://withruntime.com/limits";
+let limitToken;
+/** Headers for a call to the website's connect API: this sandbox's identity
+ * token, or none outside a sandbox or when one cannot be had. Never throws. */
+export async function sandboxIdentityHeaders() {
+    if (limitToken && Date.now() < limitToken.until)
+        return { [LIMIT_HEADER]: limitToken.token };
+    if (!(await requestCredentials()))
+        return {};
+    try {
+        const issued = await identityToken({
+            audience: LIMIT_AUDIENCE,
+            signal: AbortSignal.timeout(3_000),
+        });
+        // Renewed a minute before it lapses, so a slow call never carries a dead one.
+        limitToken = { token: issued.token, until: Date.parse(issued.expiresAt) - 60_000 };
+        return { [LIMIT_HEADER]: issued.token };
+    }
+    catch {
+        return {};
+    }
+}

package/dist/images/index.d.ts

@@ -0,0 +1,9 @@
+/** `withruntime/images`: Images alone. Custom images to start sandboxes from.
+ *
+ *   import { images } from "withruntime/images";
+ *   const client = images(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type * from "../products/images.js";
+/** `runtime.images` of a client made with `options`. */
+export declare function images(options?: RuntimeOptions): Runtime["images"];

package/dist/images/index.js

@@ -0,0 +1,10 @@
+/** `withruntime/images`: Images alone. Custom images to start sandboxes from.
+ *
+ *   import { images } from "withruntime/images";
+ *   const client = images(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+/** `runtime.images` of a client made with `options`. */
+export function images(options) {
+    return new Runtime(options).images;
+}

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export type { Volume, VolumeBackup, CreateVolume, VolumeAttachment } from "./pro
 export type { CreateJob, Job, JobCompute, JobDefinition, JobLogs, JobRun, JobRunState, JobSchedule, } from "./products/jobs.js";
 export type { CheckedDomain, DnsRecord, Domain, EgressAddress, TcpPort, Tunnel as PrivateTunnel, TunnelPeer, TunnelPeerCreated, SetUpstreamProxy, UpstreamProxy, } from "./products/network-products.js";
 export type { PrivateNetwork } from "./products/private-network.js";
+export type { SignedRequests } from "./products/signed-requests.js";
 export { verifyWebhook, WebhookVerificationError, type MetricPoint, type MetricRange, type OtelExport, type RuntimeEvent, type SandboxMetrics, type Webhook, type WebhookDelivery, type WebhookEventType, } from "./products/observability.js";
 export { Snapshots, type Snapshot, type SnapshotOptions } from "./snapshots.js";
 export { Transport, VERSION, apiOrigin, type RequestOptions, type Call } from "./transport.js";

package/dist/ips/index.d.ts

@@ -0,0 +1,9 @@
+/** `withruntime/ips`: IPs alone. Dedicated outbound addresses every sandbox of the account sends from.
+ *
+ *   import { ips } from "withruntime/ips";
+ *   const client = ips(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type { EgressAddress, NetworkFunding } from "../products/network-products.js";
+/** `runtime.ips` of a client made with `options`. */
+export declare function ips(options?: RuntimeOptions): Runtime["ips"];

package/dist/ips/index.js

@@ -0,0 +1,10 @@
+/** `withruntime/ips`: IPs alone. Dedicated outbound addresses every sandbox of the account sends from.
+ *
+ *   import { ips } from "withruntime/ips";
+ *   const client = ips(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+/** `runtime.ips` of a client made with `options`. */
+export function ips(options) {
+    return new Runtime(options).ips;
+}

package/dist/jobs/index.d.ts

@@ -0,0 +1,9 @@
+/** `withruntime/jobs`: Jobs alone. A command in a fresh sandbox, once or on a schedule.
+ *
+ *   import { jobs } from "withruntime/jobs";
+ *   const client = jobs(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type * from "../products/jobs.js";
+/** `runtime.jobs` of a client made with `options`. */
+export declare function jobs(options?: RuntimeOptions): Runtime["jobs"];

package/dist/jobs/index.js

@@ -0,0 +1,10 @@
+/** `withruntime/jobs`: Jobs alone. A command in a fresh sandbox, once or on a schedule.
+ *
+ *   import { jobs } from "withruntime/jobs";
+ *   const client = jobs(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+/** `runtime.jobs` of a client made with `options`. */
+export function jobs(options) {
+    return new Runtime(options).jobs;
+}

package/dist/keys.js

@@ -5,6 +5,7 @@ import { promisify } from "node:util";
 import { connectionOrigins } from "./credentials.js";
 import { RuntimeError } from "./errors.js";
 import { named } from "./cli-name.js";
+import { sandboxIdentityHeaders } from "./identity.js";
 import { describeRoute, envFetch } from "./proxy.js";
 const KEY = /^rtcloud_([a-f0-9-]{36})_[A-Za-z0-9_-]{43}$/;
 /** How often to ask whether the owner has answered. The website answers
@@ -79,6 +80,7 @@ export async function createKey(request, env, options = {}) {
                 headers: {
                     "content-type": "application/json",
                     ...(key ? { authorization: `Bearer ${key}` } : {}),
+                    ...(await sandboxIdentityHeaders()),
                 },
                 body: JSON.stringify(body),
             });

package/dist/login.js

@@ -5,6 +5,7 @@ import { promisify } from "node:util";
 import { me, named } from "./cli-name.js";
 import { Runtime } from "./client.js";
 import { checkBrowserOrigins, connectionOrigins, connectionStore } from "./credentials.js";
+import { sandboxIdentityHeaders } from "./identity.js";
 import { describeRoute, envFetch } from "./proxy.js";
 class ConnectionError extends Error {
     status;
@@ -80,6 +81,7 @@ function connection(env, options) {
                 headers: {
                     "content-type": "application/json",
                     ...(key ? { authorization: `Bearer ${key}` } : {}),
+                    ...(await sandboxIdentityHeaders()),
                 },
                 body: JSON.stringify(body ?? {}),
             });

package/dist/machine.d.ts

@@ -0,0 +1,189 @@
+import { RuntimeError } from "./errors.js";
+import { Page } from "./page.js";
+import type { Snapshot, SnapshotOptions } from "./snapshots.js";
+import type { RequestOptions, Transport } from "./transport.js";
+import type { KeepAliveOptions } from "./types.js";
+/** One machine product: the API serves it at /v1/<plural>, and its errors
+ * call one of it by `noun`. */
+export type MachineProduct = {
+    readonly plural: string;
+    readonly noun: string;
+};
+/** What every machine's record carries for the verbs shared here. */
+export type MachineState = "starting" | "running" | "pausing" | "paused" | "resuming" | "stopping" | "stopped";
+export type MachineInfo = {
+    id: string;
+    state: MachineState;
+    expiresAt: string;
+    endsAt?: string | null;
+    start?: unknown;
+    /** True when getOrCreate found the name already held. */
+    reused?: boolean;
+    /** True when the answer repeats an earlier call under the same idempotency key. */
+    replayed?: boolean;
+};
+/** Any other call's request options, as the caller gave them: `timeoutMs` is
+ * the call's whole deadline, and 0 turns it off. */
+export declare function requestOnly(options: RequestOptions): RequestOptions;
+/** DELETE /v1/<plural>/{id}, for `machine.delete()` and the product's
+ * `delete(id)`. */
+export declare function deleteMachine<Deleted>(product: MachineProduct, t: Transport, id: string, options?: RequestOptions): Promise<Deleted>;
+/** One page of a product's list, and the pages after it. */
+export declare function machinePage<M, Info>(product: MachineProduct, t: Transport, wrap: (t: Transport, info: Info) => M, body: {
+    data: Info[];
+    nextCursor: string | null;
+}, query: Record<string, unknown>, options?: RequestOptions): Page<M>;
+export declare abstract class Machine<Info extends MachineInfo, Settings extends object, Deleted> implements AsyncDisposable {
+    #private;
+    constructor(product: MachineProduct, transport: Transport, info: Info);
+    get id(): string;
+    /** What the API last said about this sandbox. `refresh()` asks again. */
+    get info(): Info;
+    get state(): Info["state"];
+    refresh(options?: RequestOptions): Promise<this>;
+    /** Waits (server-side, no polling) until the sandbox reaches `state`. */
+    waitFor(state: "running" | "paused" | "stopped", options?: {
+        timeoutSeconds?: number;
+    } & RequestOptions): Promise<this>;
+    stop(options?: RequestOptions & {
+        wait?: boolean;
+    }): Promise<this>;
+    pause(options?: RequestOptions & {
+        wait?: boolean;
+    }): Promise<this>;
+    /** Deletes it for good: stops it if it runs or is paused, deletes its disk
+     * and paused memory, revokes its previews and ports, and removes it from
+     * lists. Its snapshots, usage and audit entries stay. Deleting it again
+     * answers the same. */
+    delete(options?: RequestOptions): Promise<Deleted>;
+    /** Carries on a paused sandbox; for one with a time limit,
+     * `timeoutSeconds` is its new one. */
+    wake(options?: RequestOptions & {
+        wait?: boolean;
+        timeoutSeconds?: number;
+    }): Promise<this>;
+    /** More time before its time limit ends (at most an hour ahead of now). A
+     * sandbox with no time limit needs none: the call answers at once and
+     * changes nothing. */
+    extend(seconds: number, options?: RequestOptions): Promise<this>;
+    /** Changes its name, labels, automatic wake, idle pause or persistence;
+     * fields left out stay as they are. `persistent: true` keeps it running
+     * while credit lasts (paid only). */
+    update(settings: Settings, options?: RequestOptions): Promise<this>;
+    /** Moves it to another image (id, name, name:tag or name@version), keeping
+     * its id, /workspace (its home: dotfiles, pip --user and npm -g installs),
+     * volumes, environment, name and previews. Its processes restart, and
+     * everything else on its old disk (sudo installs, apt packages, /etc) is
+     * lost; snapshot it first to keep everything. A running sandbox is paused
+     * first. A switch that fails is undone (`switch_undone`), the sandbox on
+     * its old image with nothing lost. Charged as a wake. `keep` is optional:
+     * "workspace" is the only value, and it is sent either way, so an API from
+     * before it was optional accepts the call too. */
+    switchImage(image: string, options?: RequestOptions & {
+        keep?: "workspace";
+    }): Promise<this>;
+    /** Gives it more or fewer vCPUs or more or less memory by a restart: its id,
+     * whole disk, volumes, environment, name and previews stay, and its
+     * programs stop (snapshot it first to keep its memory too). A running sandbox is paused, or stopped if it is
+     * persistent, and comes back running at the new size on the same server; a
+     * paused or stopped one is started. Memory bills on the new size from then.
+     * Refused, with nothing changed, when the server has no room
+     * (`no_capacity`), above your quota or the 2 vCPU and 4 GiB without credit, or
+     * while a snapshot or fork of it is being taken. `restart` is optional:
+     * true is the only value, and it is sent either way, so an API from before
+     * it was optional accepts the call too. */
+    resize(size: {
+        vcpu?: number;
+        memoryMiB?: number;
+    }, options?: RequestOptions & {
+        restart?: true;
+    }): Promise<this>;
+    /** Keeps a sandbox with a time limit running past it, in the background,
+     * until stop() or the returned function ends it: every `everySeconds` (60)
+     * it extends the limit so that `marginSeconds` (600) remain, never more
+     * than the hour ahead the API allows. A sandbox with no time limit
+     * (`endsAt` null) needs none, and is only watched. Running time is billed
+     * as it is used. A paused sandbox is left paused (a request wakes it,
+     * unless autoWake is off); a stopped one ends the loop. It does not keep a
+     * Node or Bun process alive by itself. */
+    keepAlive(options?: KeepAliveOptions): () => void;
+    /** Days a paused sandbox is kept before deletion (1 to 365), or `null` to
+     * keep it while your account has credit. */
+    setRetention(days: number | null, options?: RequestOptions): Promise<this>;
+    /** Keeps this sandbox's whole machine (files, memory, running processes) as
+     * a snapshot to start new sandboxes from. A running sandbox is paused for
+     * the moment it takes, then woken; a paused one stays paused. Past
+     * `timeoutMs` (ten minutes unless given) mid-capture, it stays paused and
+     * the error names the snapshot. */
+    snapshot(options?: SnapshotOptions & RequestOptions): Promise<Snapshot>;
+    /** Starts a stopped persistent sandbox again from its disk (memory is not kept). */
+    restart(options?: RequestOptions & {
+        wait?: boolean;
+    }): Promise<this>;
+    /** The end of an `await using` block. A sandbox this client created is
+     * deleted, as E2B's block kills it, unless it was created with
+     * `keep: true`; one it found with `get` or `getOrCreate` is stopped, which
+     * keeps its disk. */
+    [Symbol.asyncDispose](): Promise<void>;
+    toJSON(): Info;
+}
+/** How a product's `create` waits when every slot without credit, the account's quota
+ * or the region is full. */
+export type CreateOptions = RequestOptions & {
+    /** How long to keep retrying a refusal that clears by itself. Default: the
+     * client's, two minutes; 0 fails at once. */
+    waitForCapacityMs?: number;
+    /** Called before each wait, with the refusal and the milliseconds until the
+     * next try: to tell a person why nothing has happened yet. */
+    onCapacityWait?: (refusal: RuntimeError, waitMs: number) => void;
+};
+/** A machine product's collection: `runtime.<product>`. */
+export declare abstract class Machines<M extends Machine<Info, object, Deleted>, Info extends MachineInfo, Create extends {
+    name?: string;
+    getOrCreate?: boolean;
+    keep?: boolean;
+}, Deleted> {
+    #private;
+    constructor(product: MachineProduct, t: Transport, wrap: (t: Transport, info: Info) => M);
+    /** Creates a sandbox and waits until it is running. Every field is optional:
+     * with none you get the included usage while it lasts, the default region and a
+     * 2 vCPU / 4 GiB machine from a warm template. `wait: false` returns at once.
+     * When every slot without credit or the account's quota is taken, it waits for one to
+     * free, up to `waitForCapacityMs` (the client's, two minutes by default). */
+    create(input?: Create & {
+        wait?: boolean;
+    }, options?: CreateOptions): Promise<M>;
+    /** The sandbox named `name` in this account, ready to use: running as it
+     * is, woken if it is paused, restarted if it is stopped and persistent, or
+     * created with `input` when no sandbox has the name. `sandbox.info.reused`
+     * says which. The other fields apply only when it is created. */
+    getOrCreate(name: string, input?: Omit<Create, "name" | "getOrCreate"> & {
+        wait?: boolean;
+    }, options?: CreateOptions): Promise<M>;
+    get(id: string, options?: RequestOptions): Promise<M>;
+    /** Deletes a sandbox for good, by id, without reading it first: see
+     * `sandbox.delete()`. Deleting it again answers the same. */
+    delete(id: string, options?: RequestOptions): Promise<Deleted>;
+    /** Live sandboxes, oldest first. Await for a page, or `for await` over all.
+     * Request options apply to the initial request and every subsequent page. */
+    list(filter?: {
+        state?: Info["state"][];
+        includeStopped?: boolean;
+        /** Every label must match. */
+        labels?: Record<string, string>;
+        name?: string;
+        limit?: number;
+    }, options?: RequestOptions): Promise<Page<M>>;
+    /** Stops every live sandbox whose labels all match, eight at a time, and
+     * says which stopped and which failed; one failure does not stop the rest.
+     * Needs at least one label, so stopping everything is never one call. */
+    stopAll(filter: {
+        labels: Record<string, string>;
+    }, options?: RequestOptions): Promise<{
+        stopped: string[];
+        failed: {
+            id: string;
+            error: unknown;
+        }[];
+    }>;
+}