withruntime 0.11.2 → 0.14.0

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/network-products.d.ts

@@ -129,9 +129,9 @@ export declare function ports(t: Transport): {
         deleted: true;
     }>;
 };
-/** `runtime.addresses`: a dedicated outbound address every sandbox of the
+/** `runtime.ips`: a dedicated outbound address every sandbox of the
  * account sends from, for allow-lists. */
-export declare function addresses(t: Transport): {
+export declare function ips(t: Transport): {
     reserve: (input?: {
         family?: 4 | 6;
     }, options?: RequestOptions) => Promise<EgressAddress>;
@@ -142,8 +142,8 @@ export declare function addresses(t: Transport): {
         deleted: true;
     }>;
 };
-/** `runtime.tunnel`: a WireGuard tunnel from your own network into your sandboxes. */
-export declare function tunnel(t: Transport): {
+/** `runtime.networks.wireguard`: a WireGuard tunnel from your own network into your sandboxes. */
+export declare function wireguard(t: Transport): {
     get: (options?: RequestOptions) => Promise<Tunnel>;
     /** Idempotent: returns the tunnel you have. */
     create: (input?: {
@@ -186,15 +186,39 @@ export type SetUpstreamProxy = {
      * every connection when absent. 1 to 16. */
     hosts?: string[];
 };
-/** `runtime.network`: the network settings of the whole account.
+/** `runtime.networks`: the networks of the whole account: the WireGuard
+ * tunnel in, your sandboxes reaching each other, and the proxy out.
  *
- *   await runtime.network.upstreamProxy.set({ url: "http://proxy.example.com:3128" });
+ *   await runtime.networks.upstreamProxy.set({ url: "http://proxy.example.com:3128" });
  *
  * `upstreamProxy`: after Runtime's own rules allow a connection, the host
  * reaches it with CONNECT through your proxy, so your proxy's controls and
  * logs apply. A proxy that refuses or cannot be reached fails the connection
  * (upstream-proxy-failed); nothing goes around it. Needs a kept top-up. */
-export declare function network(t: Transport): {
+export declare function networks(t: Transport): {
+    /** The WireGuard tunnel from your own network into your sandboxes. */
+    wireguard: {
+        get: (options?: RequestOptions) => Promise<Tunnel>;
+        /** Idempotent: returns the tunnel you have. */
+        create: (input?: {
+            subnet?: string;
+        }, options?: RequestOptions) => Promise<Tunnel>;
+        delete: (options?: RequestOptions) => Promise<{
+            id: string;
+            deleted: true;
+        }>;
+        /** Leave publicKey out and Runtime generates the pair; the private key is
+         * then in `config`, shown once. */
+        addPeer: (input: {
+            name: string;
+            publicKey?: string;
+            routes?: string[];
+        }, options?: RequestOptions) => Promise<TunnelPeerCreated>;
+        rotatePeer: (peerId: string, input?: {
+            publicKey?: string;
+        }, options?: RequestOptions) => Promise<TunnelPeerCreated>;
+        removePeer: (peerId: string, options?: RequestOptions) => Promise<Tunnel>;
+    };
     /** Your sandboxes reaching each other by name (`private-network.ts`). */
     private: {
         get: (options?: RequestOptions) => Promise<import("./private-network.js").PrivateNetwork>;
@@ -202,6 +226,13 @@ export declare function network(t: Transport): {
             enabled: boolean;
         }, options?: RequestOptions) => Promise<import("./private-network.js").PrivateNetwork>;
     };
+    /** Your sandboxes' requests signed as Runtime's agents (`signed-requests.ts`). */
+    signedRequests: {
+        get: (options?: RequestOptions) => Promise<import("./signed-requests.js").SignedRequests>;
+        set: (input: {
+            enabled: boolean;
+        }, options?: RequestOptions) => Promise<import("./signed-requests.js").SignedRequests>;
+    };
     upstreamProxy: {
         /** Send outbound connections through your proxy, replacing any set before. */
         set: (input: SetUpstreamProxy, options?: RequestOptions) => Promise<UpstreamProxy & {