withruntime 0.11.2 → 0.12.0

package/dist/products/index.js

@@ -3,7 +3,7 @@ import { sandboxDesktop } from "./desktop.js";
 import { sandboxBrowser } from "./browser.js";
 import { sandboxInterpreter } from "./interpreter.js";
 import { sandboxNetwork } from "./network.js";
-import { addresses, domains, network, ports, tunnel } from "./network-products.js";
+import { domains, ips, networks, ports } from "./network-products.js";
 import { sandboxPreviews } from "./previews.js";
 import { referrals } from "./referrals.js";
 import { billing } from "./billing.js";
@@ -50,19 +50,8 @@ export const clientExtensions = {
     sso,
     domains,
     ports,
-    addresses,
-    tunnel,
-    network,
-};
-/** Canonical CLI product names share the existing factory instance. Account
- * commands such as secrets, events and billing retain their current names. */
-export const clientProductAliases = {
-    image: "images",
-    volume: "volumes",
-    job: "jobs",
-    domain: "domains",
-    port: "ports",
-    address: "addresses",
+    ips,
+    networks,
 };
 export const sandboxExtensions = {
     interpreter: sandboxInterpreter,

package/dist/products/jobs.d.ts

@@ -53,6 +53,9 @@ export type Job = {
     version: number;
     /** Unix milliseconds, or null when nothing more is scheduled. */
     nextRunAt: number | null;
+    /** When `trigger` asked for a run that has not started yet, in Unix
+     * milliseconds; null otherwise. */
+    runRequestedAt: number | null;
     /** Why the last due run could not start, retried every 30 seconds:
      * `credits` (add credit), `capacity`, `cost_cap` (maxTotalCostMicros or a
      * key's daily limit) or `permission` (the key that made the job lost it). */
@@ -68,6 +71,8 @@ export type JobRun = {
     occurrenceId: string;
     attempt: number;
     scheduledFor: number;
+    /** `manual`: a run `trigger` asked for, and its retries. */
+    trigger: "schedule" | "manual";
     resourceId: string;
     /** `unknown`: the outcome could not be observed (the sandbox stopped under
      * it). It is never retried by itself. */
@@ -159,6 +164,9 @@ export declare const JOB_LIMITS: {
 };
 /** Unix milliseconds from a Date, an ISO time or a number. */
 export declare function jobTime(at: Date | string | number): number;
+/** The API's schedule from what `create` and `reschedule` take: `{ at }`,
+ * `{ cron, timezone? }` or the raw `{ kind: ... }`. */
+export declare function jobSchedule(input: CreateJob["schedule"]): JobSchedule;
 /** The API's job body from `CreateJob`, with every default filled in and the
  * sandbox's size checked before anything is sent. */
 export declare function jobBody(input: CreateJob): Record<string, unknown>;
@@ -211,4 +219,13 @@ export declare function jobs(transport: Transport): {
     /** End the job for good and stop any run in progress. A run that already
      * finished keeps its result. Cancelling again answers the same job. */
     cancel: (id: string, options?: RequestOptions) => Promise<Job>;
+    /** Run it now, once, beside its schedule, which does not move. A paused
+     * job runs once and stays paused. While a run is starting or going it is
+     * refused with `run_in_progress`; a cancelled or finished job with
+     * `invalid_state`. The run is in `runs` with `trigger: "manual"`. */
+    trigger: (id: string, options?: RequestOptions) => Promise<Job>;
+    /** A new schedule, in any form `create` takes: `{ cron, timezone? }` or
+     * `{ at }`. The next run is the new schedule's next time; a run going
+     * finishes as it began, and a paused job stays paused. */
+    reschedule: (id: string, schedule: CreateJob["schedule"], options?: RequestOptions) => Promise<Job>;
 };

package/dist/products/jobs.js

@@ -47,25 +47,28 @@ export function jobTime(at) {
         throw invalid(`schedule.at must be a time: a Date, an ISO time such as 2026-10-01T03:00:00Z, or Unix milliseconds; got ${String(at)}.`, "schedule.at");
     return ms;
 }
-/** The API's job body from `CreateJob`, with every default filled in and the
- * sandbox's size checked before anything is sent. */
-export function jobBody(input) {
-    const s = input.schedule;
-    let schedule;
+/** The API's schedule from what `create` and `reschedule` take: `{ at }`,
+ * `{ cron, timezone? }` or the raw `{ kind: ... }`. */
+export function jobSchedule(input) {
+    const s = (input ?? {});
     if (s.kind === "once" || (s.kind === undefined && s.at !== undefined))
-        schedule = { kind: "once", at: jobTime(s.at) };
-    else if (s.kind === "cron" || (s.kind === undefined && s.cron !== undefined)) {
+        return { kind: "once", at: jobTime(s.at) };
+    if (s.kind === "cron" || (s.kind === undefined && s.cron !== undefined)) {
         const expression = String(s.expression ?? s.cron).trim();
         if (expression.split(/\s+/).length !== 5)
             throw invalid(`A cron schedule has five fields, minute hour day-of-month month day-of-week, such as "0 3 * * *"; got "${expression}".`, "schedule.cron");
-        schedule = {
+        return {
             kind: "cron",
             expression,
             ...(s.timezone === undefined ? {} : { timezone: s.timezone }),
         };
     }
-    else
-        throw invalid("schedule takes { at } or { cron }.", "schedule");
+    throw invalid("schedule takes { at } or { cron }.", "schedule");
+}
+/** The API's job body from `CreateJob`, with every default filled in and the
+ * sandbox's size checked before anything is sent. */
+export function jobBody(input) {
+    const schedule = jobSchedule(input.schedule);
     const command = Array.isArray(input.command) ? { argv: input.command } : input.command;
     if (!command?.argv?.length)
         throw invalid('command is an argv array such as ["python3", "job.py"].', "command");
@@ -186,5 +189,19 @@ export function jobs(transport) {
         /** End the job for good and stop any run in progress. A run that already
          * finished keeps its result. Cancelling again answers the same job. */
         cancel: (id, options) => verb(id, "cancel", options),
+        /** Run it now, once, beside its schedule, which does not move. A paused
+         * job runs once and stays paused. While a run is starting or going it is
+         * refused with `run_in_progress`; a cancelled or finished job with
+         * `invalid_state`. The run is in `runs` with `trigger: "manual"`. */
+        trigger: (id, options) => verb(id, "trigger", options),
+        /** A new schedule, in any form `create` takes: `{ cron, timezone? }` or
+         * `{ at }`. The next run is the new schedule's next time; a run going
+         * finishes as it began, and a paused job stays paused. */
+        reschedule: (id, schedule, options) => t.json({
+            method: "POST",
+            path: `/v1/jobs/${enc(id)}:reschedule`,
+            body: { schedule: jobSchedule(schedule) },
+            ...options,
+        }),
     };
 }

package/dist/products/logs.d.ts

@@ -0,0 +1,245 @@
+import { Page } from "../page.js";
+import type { RequestOptions, Transport } from "../transport.js";
+/** Native logsd hit_json. Nanoseconds stay strings so no precision is lost. */
+export type LogLine = {
+    time: string;
+    timeUnixNano: string;
+    severity: number;
+    severityText: string;
+    body: unknown;
+    labels: Record<string, string>;
+    attributes: Record<string, unknown>;
+    traceId: string | null;
+    spanId: string | null;
+};
+export type LogSearch = {
+    query: string;
+    start?: string;
+    end?: string;
+    limit?: number;
+    direction?: "forward" | "backward";
+    cursor?: string;
+};
+export type LogSearchResult = {
+    lines: LogLine[];
+    next?: string | null;
+    stats: {
+        ms: number;
+        blocks: number;
+        skippedByTime: number;
+        skippedByLabels: number;
+        skippedByWords: number;
+        scanned: number;
+        bytesRead: number;
+    };
+};
+export type TailGap = {
+    gap: true;
+    from: string;
+    to: string;
+};
+export type TailLine = LogLine & {
+    cursor: string;
+    gap?: false;
+};
+export type TailEvent = TailLine | TailGap;
+export type LogQuery = {
+    query: string;
+    time?: string;
+    limit?: number;
+    direction?: "forward" | "backward";
+};
+export type LogRange = Omit<LogQuery, "time"> & {
+    start?: string;
+    end?: string;
+    step?: string;
+    interval?: string;
+};
+export type LokiResult = {
+    status: "success";
+    data: ({
+        resultType: "streams";
+        result: {
+            stream: Record<string, string>;
+            values: [string, string, Record<string, string>?][];
+        }[];
+    } | {
+        resultType: "matrix";
+        result: {
+            metric: Record<string, string>;
+            values: [number, string][];
+        }[];
+    } | {
+        resultType: "vector";
+        result: {
+            metric: Record<string, string>;
+            value: [number, string];
+        }[];
+    } | {
+        resultType: "scalar";
+        result: [number, string];
+    }) & {
+        stats?: Record<string, unknown>;
+    };
+};
+export type LabelResult = {
+    status: "success";
+    data: string[];
+};
+export type ViewInput = {
+    name: string;
+    labels: Record<string, string>;
+    query: string;
+    defaultRange?: string;
+};
+export type SavedView = ViewInput & {
+    id: string;
+    state: string;
+    createdAt: string;
+};
+export type AlertInput = {
+    name: string;
+    labels: Record<string, string>;
+    query: string;
+    condition: string;
+    for: string;
+    actions: Record<string, unknown>[];
+};
+export type Alert = AlertInput & {
+    id: string;
+    state: string;
+    createdAt: string;
+};
+/** OTLP/HTTP JSON; the server validates the signal's complete OTLP schema. */
+export type OtlpLogs = {
+    resourceLogs: Record<string, unknown>[];
+};
+export type OtlpTraces = {
+    resourceSpans: Record<string, unknown>[];
+};
+export type TraceSpan = {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes?: {
+        key: string;
+        value: Record<string, unknown>;
+    }[];
+    status?: {
+        code?: number;
+        message?: string;
+    };
+};
+export type Trace = {
+    resourceSpans: {
+        resource?: {
+            attributes?: {
+                key: string;
+                value: Record<string, unknown>;
+            }[];
+        };
+        scopeSpans: {
+            spans: TraceSpan[];
+        }[];
+    }[];
+};
+export type TraceSearchResult = {
+    traces: {
+        traceID: string;
+        rootServiceName: string;
+        rootTraceName: string;
+        startTimeUnixNano: string;
+        durationMs: number;
+    }[];
+    metrics?: Record<string, unknown>;
+};
+/** Hidden until Logs launches. */
+export declare function logs(t: Transport): {
+    search: (body: LogSearch, options?: RequestOptions) => Promise<LogSearchResult>;
+    pages(input: LogSearch, options?: RequestOptions): AsyncGenerator<LogSearchResult>;
+    /** The record's cursor, not timestamp or text, identifies a line. The
+     * server replays strictly after it. An echoed boundary is ignored; two
+     * identical lines at different record positions are both delivered. */
+    tail(query: string, options?: RequestOptions & {
+        cursor?: string;
+        start?: string;
+        reconnectMs?: number;
+    }): AsyncGenerator<TailEvent>;
+    query: (query: LogQuery, options?: RequestOptions) => Promise<LokiResult>;
+    queryRange: (query: LogRange, options?: RequestOptions) => Promise<LokiResult>;
+    labels: (query?: {
+        start?: string;
+        end?: string;
+    }, options?: RequestOptions) => Promise<LabelResult>;
+    labelValues: (name: string, query?: {
+        start?: string;
+        end?: string;
+    }, options?: RequestOptions) => Promise<LabelResult>;
+    views: {
+        create: (body: ViewInput, options?: RequestOptions) => Promise<SavedView>;
+        get: (id: string, options?: RequestOptions) => Promise<SavedView>;
+        list: (query?: {
+            limit?: number;
+            cursor?: string;
+        }, options?: RequestOptions) => Promise<Page<SavedView>>;
+        update: (id: string, body: Partial<ViewInput>, options?: RequestOptions) => Promise<SavedView>;
+        delete: (id: string, options?: RequestOptions) => Promise<void>;
+    };
+    ingest: (body: OtlpLogs, options?: RequestOptions) => Promise<{
+        partialSuccess?: {
+            rejectedLogRecords?: string;
+            rejectedSpans?: string;
+            errorMessage?: string;
+        };
+    }>;
+};
+export declare function traces(t: Transport): {
+    get: (id: string, options?: RequestOptions) => Promise<Trace>;
+    search: (q: string, options?: RequestOptions) => Promise<TraceSearchResult>;
+    tags: (options?: RequestOptions) => Promise<{
+        tagNames: string[];
+    }>;
+    views: {
+        create: (body: ViewInput, options?: RequestOptions) => Promise<SavedView>;
+        get: (id: string, options?: RequestOptions) => Promise<SavedView>;
+        list: (query?: {
+            limit?: number;
+            cursor?: string;
+        }, options?: RequestOptions) => Promise<Page<SavedView>>;
+        update: (id: string, body: Partial<ViewInput>, options?: RequestOptions) => Promise<SavedView>;
+        delete: (id: string, options?: RequestOptions) => Promise<void>;
+    };
+    ingest: (body: OtlpTraces, options?: RequestOptions) => Promise<{
+        partialSuccess?: {
+            rejectedLogRecords?: string;
+            rejectedSpans?: string;
+            errorMessage?: string;
+        };
+    }>;
+};
+export declare function alerts(t: Transport): {
+    test: (id: string, options?: RequestOptions) => Promise<{
+        firing: boolean;
+        matches: number;
+    }>;
+    silence: (id: string, input: {
+        until: string;
+        reason?: string;
+    }, options?: RequestOptions) => Promise<Alert>;
+    create: (body: AlertInput, options?: RequestOptions) => Promise<Alert>;
+    get: (id: string, options?: RequestOptions) => Promise<Alert>;
+    list: (query?: {
+        limit?: number;
+        cursor?: string;
+    }, options?: RequestOptions) => Promise<Page<Alert>>;
+    update: (id: string, body: Partial<AlertInput>, options?: RequestOptions) => Promise<Alert>;
+    delete: (id: string, options?: RequestOptions) => Promise<void>;
+};
+export type ObservabilityClient = {
+    logs: ReturnType<typeof logs>;
+    traces: ReturnType<typeof traces>;
+    alerts: ReturnType<typeof alerts>;
+};

package/dist/products/logs.js

@@ -0,0 +1,274 @@
+import { RuntimeError, InvalidRequestError } from "../errors.js";
+import { Page } from "../page.js";
+const enc = encodeURIComponent;
+const protocol = (message) => new RuntimeError({
+    code: "invalid_stream",
+    status: 422,
+    message,
+    hint: "Reconnect the log tail. If this repeats, report the request to support.",
+});
+/** Shared CRUD keeps the saved log and trace views on identical contracts. */
+function resources(t, path) {
+    const list = async (query = {}, options) => {
+        const page = await t.json({
+            method: "GET",
+            path,
+            query,
+            ...options,
+        });
+        return new Page(page.data, page.nextCursor, (cursor) => list({ ...query, cursor }, options));
+    };
+    return {
+        create: (body, options) => t.json({ method: "POST", path, body, ...options }),
+        get: (id, options) => t.json({ method: "GET", path: `${path}/${enc(id)}`, ...options }),
+        list,
+        update: (id, body, options) => t.json({ method: "PUT", path: `${path}/${enc(id)}`, body, ...options }),
+        delete: (id, options) => t.json({ method: "DELETE", path: `${path}/${enc(id)}`, ...options }),
+    };
+}
+function ingest(t, path, body, options) {
+    if (new TextEncoder().encode(JSON.stringify(body)).length > 1_048_576)
+        throw new InvalidRequestError({
+            code: "payload_too_large",
+            status: 413,
+            message: "OTLP JSON exceeds 1 MiB.",
+            hint: "Split the write into smaller batches, each with its own idempotency key.",
+        });
+    return t.json({ method: "POST", path, body, ...options });
+}
+/** Parse SSE incrementally, including split UTF-8, CRLF and multi-line data.
+ * Incomplete events at disconnect are discarded and replayed from the cursor.
+ * A finite event bound prevents a broken peer from growing memory forever. */
+async function* events(stream, signal) {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "", id = "", event = "", data = [], size = 0;
+    const cancel = () => {
+        void reader.cancel(signal?.reason).catch(() => undefined);
+    };
+    if (signal?.aborted)
+        cancel();
+    else
+        signal?.addEventListener("abort", cancel, { once: true });
+    try {
+        for (;;) {
+            signal?.throwIfAborted();
+            const chunk = await reader.read().catch((cause) => {
+                signal?.throwIfAborted();
+                throw new RuntimeError({
+                    code: "tail_connection_lost",
+                    status: 503,
+                    message: "The log stream disconnected.",
+                    hint: "The SDK resumes from the last delivered cursor.",
+                    cause,
+                });
+            });
+            signal?.throwIfAborted();
+            if (chunk.done)
+                break;
+            buffer += decoder.decode(chunk.value, { stream: true });
+            for (;;) {
+                const match = /\r\n|\r|\n/.exec(buffer);
+                if (!match || (match[0] === "\r" && match.index === buffer.length - 1))
+                    break;
+                const line = buffer.slice(0, match.index);
+                buffer = buffer.slice(match.index + match[0].length);
+                size += line.length + 1;
+                if (size > 1_048_576)
+                    throw protocol("A log event exceeds 1 MiB of text.");
+                if (!line) {
+                    if (data.length)
+                        yield { id, event, data: data.join("\n") };
+                    id = "";
+                    event = "";
+                    data = [];
+                    size = 0;
+                }
+                else if (!line.startsWith(":")) {
+                    const colon = line.indexOf(":");
+                    const field = colon < 0 ? line : line.slice(0, colon);
+                    const value = colon < 0 ? "" : line.slice(colon + 1).replace(/^ /, "");
+                    if (field === "id" && !value.includes("\0"))
+                        id = value;
+                    if (field === "event")
+                        event = value;
+                    if (field === "data")
+                        data.push(value);
+                }
+            }
+            if (buffer.length + size > 1_048_576)
+                throw protocol("A log event exceeds 1 MiB of text.");
+        }
+    }
+    finally {
+        signal?.removeEventListener("abort", cancel);
+        await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+}
+function pause(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const done = () => {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        const abort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+            reject(signal?.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError"));
+        };
+        if (signal?.aborted)
+            abort();
+        else
+            signal?.addEventListener("abort", abort, { once: true });
+    });
+}
+/** Hidden until Logs launches. */
+export function logs(t) {
+    const search = (body, options) => t.json({ method: "POST", path: "/v1/logs:search", body, ...options });
+    return {
+        search,
+        async *pages(input, options) {
+            let cursor = input.cursor;
+            const seen = new Set();
+            if (cursor)
+                seen.add(cursor);
+            do {
+                const page = await search({ ...input, ...(cursor ? { cursor } : {}) }, options);
+                yield page;
+                cursor = page.next ?? undefined;
+                if (cursor && seen.has(cursor))
+                    throw protocol("Search repeated a paging cursor.");
+                if (cursor)
+                    seen.add(cursor);
+            } while (cursor);
+        },
+        /** The record's cursor, not timestamp or text, identifies a line. The
+         * server replays strictly after it. An echoed boundary is ignored; two
+         * identical lines at different record positions are both delivered. */
+        async *tail(query, options = {}) {
+            const { cursor: initial, start, reconnectMs = 250, ...request } = options;
+            let cursor = initial, failures = 0;
+            if (!Number.isFinite(reconnectMs) || reconnectMs < 0)
+                throw protocol("Reconnect delay must be a finite, nonnegative number.");
+            for (;;) {
+                request.signal?.throwIfAborted();
+                try {
+                    const stream = await t.fileStream({
+                        method: "GET",
+                        path: "/v1/logs/tail",
+                        query: { query, cursor, start },
+                        accept: "text/event-stream",
+                        ...request,
+                        timeoutMs: request.timeoutMs ?? 0,
+                        onResponse(response) {
+                            if (!response.headers.get("content-type")?.toLowerCase().startsWith("text/event-stream"))
+                                throw protocol("Log tail did not return text/event-stream.");
+                        },
+                    });
+                    for await (const event of events(stream, request.signal)) {
+                        let value;
+                        try {
+                            value = JSON.parse(event.data);
+                        }
+                        catch {
+                            throw protocol("Log tail returned invalid JSON.");
+                        }
+                        if (event.event === "error") {
+                            // A reader failure is retryable, but its resume id has not been
+                            // delivered as a line. Keep the last acknowledged line cursor.
+                            throw new RuntimeError({
+                                code: "tail_interrupted",
+                                status: 503,
+                                message: "The log reader stopped.",
+                                hint: "The SDK resumes from the last delivered cursor.",
+                            });
+                        }
+                        if (!event.id)
+                            throw protocol("Log tail event has no record cursor.");
+                        if (event.id === cursor)
+                            continue;
+                        if (event.event === "start") {
+                            // Where the server's tail begins: a reconnect before the first
+                            // line resumes here, so nothing written meanwhile is missed.
+                            cursor = event.id;
+                            continue;
+                        }
+                        if (event.event === "gap") {
+                            const gap = value;
+                            const from = gap?.from ?? cursor;
+                            const to = gap?.to ?? gap?.cursor;
+                            if (typeof from !== "string" || typeof to !== "string" || to !== event.id)
+                                throw protocol("Log tail gap has invalid cursors.");
+                            cursor = event.id;
+                            yield { gap: true, from, to };
+                        }
+                        else {
+                            const line = value;
+                            if (!line ||
+                                typeof line.timeUnixNano !== "string" ||
+                                typeof line.time !== "string" ||
+                                !line.labels ||
+                                !("body" in line))
+                                throw protocol("Log tail returned an invalid line.");
+                            cursor = event.id;
+                            yield { ...line, cursor };
+                        }
+                        failures = 0;
+                    }
+                }
+                catch (error) {
+                    request.signal?.throwIfAborted();
+                    if (error instanceof RuntimeError && !error.retryable)
+                        throw error;
+                    if (!(error instanceof RuntimeError) && !(error instanceof TypeError))
+                        throw error;
+                }
+                await pause(Math.min(10_000, Math.max(0, reconnectMs) * 2 ** Math.min(failures++, 6)), request.signal);
+            }
+        },
+        query: (query, options) => t.json({ method: "GET", path: "/v1/logs/query", query, ...options }),
+        queryRange: (query, options) => t.json({ method: "GET", path: "/v1/logs/query_range", query, ...options }),
+        labels: (query = {}, options) => t.json({ method: "GET", path: "/v1/logs/labels", query, ...options }),
+        labelValues: (name, query = {}, options) => t.json({
+            method: "GET",
+            path: `/v1/logs/labels/${enc(name)}/values`,
+            query,
+            ...options,
+        }),
+        views: resources(t, "/v1/logs/views"),
+        ingest: (body, options) => ingest(t, "/v1/logs", body, options),
+    };
+}
+export function traces(t) {
+    return {
+        get: (id, options) => t.json({ method: "GET", path: `/v1/traces/${enc(id)}`, ...options }),
+        search: (q, options) => t.json({
+            method: "GET",
+            path: "/v1/traces:search",
+            query: { q },
+            ...options,
+        }),
+        tags: (options) => t.json({ method: "GET", path: "/v1/traces/tags", ...options }),
+        views: resources(t, "/v1/traces/views"),
+        ingest: (body, options) => ingest(t, "/v1/traces", body, options),
+    };
+}
+export function alerts(t) {
+    return {
+        ...resources(t, "/v1/alerts"),
+        test: (id, options) => t.json({
+            method: "POST",
+            path: `/v1/alerts/${enc(id)}/test`,
+            body: {},
+            ...options,
+        }),
+        silence: (id, input, options) => t.json({
+            method: "POST",
+            path: `/v1/alerts/${enc(id)}/silence`,
+            body: input,
+            ...options,
+        }),
+    };
+}

package/dist/products/logs.test.d.ts

@@ -0,0 +1 @@
+export {};