@toshicloud/sdk 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./gen/toshi/workspace/v1/workspace_pb.js";
+export * from "./gen/toshi/workspace/v1/display_pb.js";
+export * from "./gen/toshi/workspace/v1/projects_pb.js";
+export * from "./gen/toshi/workspace/v1/secrets_pb.js";
+export * from "./gen/toshi/workspace/v1/webhook_pb.js";
+export { createToshiClient } from "./client.js";
+export { ExitError, StreamLostError } from "./errors.js";
+export { defaultRetryPolicy } from "./retry.js";
+export type { RetryPolicy } from "./retry.js";
+export type { CallOptions, EventWatch, OutputChunk, OutputWatch, Process, ToshiClient, ToshiOptions, WorkloadWatch, } from "./client.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+// Generated code for the Toshi Workspace API; see src/gen/ and pin.env.
+export * from "./gen/toshi/workspace/v1/workspace_pb.js";
+export * from "./gen/toshi/workspace/v1/display_pb.js";
+export * from "./gen/toshi/workspace/v1/projects_pb.js";
+export * from "./gen/toshi/workspace/v1/secrets_pb.js";
+export * from "./gen/toshi/workspace/v1/webhook_pb.js";
+export { createToshiClient } from "./client.js";
+export { ExitError, StreamLostError } from "./errors.js";
+export { defaultRetryPolicy } from "./retry.js";

package/dist/interceptors.d.ts

@@ -0,0 +1,10 @@
+import type { Interceptor } from "@connectrpc/connect";
+import type { RetrySetting } from "./retry.js";
+/** Sends `Authorization: Bearer <token>` on every call and stream; never Toshi-Tenant (intercept.go:13-36). */
+export declare function authInterceptor(token: string): Interceptor;
+/** Fills an empty project and environment from the options; caller values win (intercept.go:38-129). */
+export declare function scopeInterceptor(project: string, environment: string): Interceptor;
+/** Puts a request key on keyed procedures and on Execute's start (retry.go:110-116, 202-231). */
+export declare function keyInterceptor(): Interceptor;
+/** Retries a unary read or keyed write after a transport loss, with full jitter (retry.go:98-186). */
+export declare function retryInterceptor(retry: RetrySetting): Interceptor;

package/dist/interceptors.js

@@ -0,0 +1,159 @@
+import { ScalarType } from "@bufbuild/protobuf";
+import { backoffDelay, isTransportLoss, newRequestKey, procedurePath, retryClassFor, sleep, } from "./retry.js";
+/** Sends `Authorization: Bearer <token>` on every call and stream; never Toshi-Tenant (intercept.go:13-36). */
+export function authInterceptor(token) {
+    if (token === "") {
+        return (next) => next;
+    }
+    return (next) => async (req) => {
+        req.header.set("Authorization", `Bearer ${token}`);
+        return next(req);
+    };
+}
+/** Fills an empty project and environment from the options; caller values win (intercept.go:38-129). */
+export function scopeInterceptor(project, environment) {
+    if (project === "" && environment === "") {
+        return (next) => next;
+    }
+    return (next) => async (req) => {
+        const desc = req.method.input;
+        if (req.stream) {
+            return next({ ...req, message: fillStream(req.message, desc, project, environment) });
+        }
+        fillScope(req.message, desc, project, environment);
+        return next(req);
+    };
+}
+/** Puts a request key on keyed procedures and on Execute's start (retry.go:110-116, 202-231). */
+export function keyInterceptor() {
+    return (next) => async (req) => {
+        const desc = req.method.input;
+        if (req.stream) {
+            // Only Execute is bidirectional; its start is the one stream message that
+            // carries a request key (execute.go, intercept.go:81-94).
+            if (req.method.methodKind !== "bidi_streaming") {
+                return next(req);
+            }
+            return next({ ...req, message: fillStreamKey(req.message, desc) });
+        }
+        if (retryClassFor(procedurePath(req.service, req.method)) === "keyed") {
+            fillRequestKey(req.message, desc);
+        }
+        return next(req);
+    };
+}
+/** Retries a unary read or keyed write after a transport loss, with full jitter (retry.go:98-186). */
+export function retryInterceptor(retry) {
+    if (retry === false) {
+        return (next) => next;
+    }
+    const policy = retry;
+    return (next) => async (req) => {
+        // Streams are never retried here; the watches reconnect on their own (retry.go:135-141).
+        if (req.stream || retryClassFor(procedurePath(req.service, req.method)) === "none") {
+            return next(req);
+        }
+        // The same request object, with its key, is sent again (retry.go:118-130).
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                return await next(req);
+            }
+            catch (err) {
+                if (attempt + 1 >= policy.maxAttempts || !isTransportLoss(err)) {
+                    throw err;
+                }
+                await sleep(backoffDelay(policy, attempt), req.signal);
+            }
+        }
+    };
+}
+function fillStream(messages, desc, project, environment) {
+    return {
+        async *[Symbol.asyncIterator]() {
+            for await (const message of messages) {
+                fillScope(message, desc, project, environment);
+                yield message;
+            }
+        },
+    };
+}
+function fillStreamKey(messages, desc) {
+    return {
+        async *[Symbol.asyncIterator]() {
+            for await (const message of messages) {
+                fillRequestKey(message, desc);
+                yield message;
+            }
+        },
+    };
+}
+// Fills an empty project and, unless the message selects a shared set, an empty
+// environment (intercept.go:102-123).
+function fillScope(msg, desc, project, environment) {
+    if (project !== "") {
+        const field = stringField(desc, "project");
+        if (field !== undefined) {
+            fillIfEmpty(msg, field, project);
+        }
+    }
+    if (environment !== "" && !isShared(msg, desc)) {
+        const field = stringField(desc, "environment");
+        if (field !== undefined) {
+            fillIfEmpty(msg, field, environment);
+        }
+    }
+    for (const child of activeOneofMessages(msg, desc)) {
+        fillScope(child.message, child.desc, project, environment);
+    }
+}
+// Sets request_key on msg, or on the start message a bidi Execute request
+// carries (retry.go:202-216).
+function fillRequestKey(msg, desc) {
+    const field = stringField(desc, "request_key");
+    if (field !== undefined) {
+        const current = msg[field.localName];
+        if (current === "" || current === undefined) {
+            msg[field.localName] = newRequestKey();
+        }
+        return;
+    }
+    for (const child of activeOneofMessages(msg, desc)) {
+        fillRequestKey(child.message, child.desc);
+    }
+}
+// The active message-typed oneof values of msg; ExecuteRequest's start is one.
+function* activeOneofMessages(msg, desc) {
+    for (const field of desc.fields) {
+        if (field.fieldKind !== "message" || field.oneof === undefined) {
+            continue;
+        }
+        const group = msg[field.oneof.localName];
+        if (typeof group !== "object" || group === null) {
+            continue;
+        }
+        const oneof = group;
+        if (oneof.case !== field.localName || typeof oneof.value !== "object" || oneof.value === null) {
+            continue;
+        }
+        yield { message: oneof.value, desc: field.message };
+    }
+}
+// A singular string field by its proto name, e.g. "request_key".
+function stringField(desc, name) {
+    return desc.fields.find((field) => field.name === name && field.fieldKind === "scalar" && field.scalar === ScalarType.STRING);
+}
+// An unset proto3 string reads as "", so both it and an explicit "" are empty.
+function fillIfEmpty(msg, field, value) {
+    const current = msg[field.localName];
+    if (current === "" || current === undefined) {
+        msg[field.localName] = value;
+    }
+}
+// Whether msg selects a shared secret set (intercept.go:125-129).
+function isShared(msg, desc) {
+    const field = desc.fields.find((candidate) => candidate.name === "shared");
+    return (field !== undefined &&
+        field.fieldKind === "scalar" &&
+        field.scalar === ScalarType.BOOL &&
+        msg[field.localName] === true);
+}

package/dist/output.d.ts

@@ -0,0 +1,6 @@
+import type { Client } from "@connectrpc/connect";
+import type { CallOptions, OutputWatch } from "./client.js";
+import type { WatchOutputRequest, WorkspaceService } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import type { RetrySetting } from "./retry.js";
+/** Starts an output watch at the request's offsets, counting the bytes it hands out (output.go:14-52). */
+export declare function openOutputWatch(workspace: Client<typeof WorkspaceService>, retry: RetrySetting, req: WatchOutputRequest, opts?: CallOptions): Promise<OutputWatch>;

package/dist/output.js

@@ -0,0 +1,77 @@
+import { clone } from "@bufbuild/protobuf";
+import { WatchOutputRequestSchema } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import { READER_TAKEN, WatchState, createReader, reconnect, streamEnded } from "./stream.js";
+/** Starts an output watch at the request's offsets, counting the bytes it hands out (output.go:14-52). */
+export function openOutputWatch(workspace, retry, req, opts) {
+    const state = new WatchState("", opts?.signal);
+    const request = clone(WatchOutputRequestSchema, req);
+    let stdout = req.stdoutOffset;
+    let stderr = req.stderrOffset;
+    async function* run() {
+        let attempt = 0;
+        try {
+            for (;;) {
+                if (state.closed) {
+                    return;
+                }
+                let cause;
+                try {
+                    request.stdoutOffset = stdout;
+                    request.stderrOffset = stderr;
+                    const stream = workspace.watchOutput(request, { signal: state.signal });
+                    for await (const msg of stream) {
+                        attempt = 0;
+                        if (msg.message.case === "end") {
+                            // output.go:157-160: release the RPC before the caller sees the
+                            // end message, and never reopen after it.
+                            state.close();
+                            yield msg;
+                            return;
+                        }
+                        if (msg.message.case === "stdout") {
+                            stdout += BigInt(msg.message.value.length);
+                        }
+                        else if (msg.message.case === "stderr") {
+                            stderr += BigInt(msg.message.value.length);
+                        }
+                        yield msg;
+                    }
+                    if (state.closed) {
+                        return;
+                    }
+                    cause = streamEnded;
+                }
+                catch (err) {
+                    if (state.closed) {
+                        return;
+                    }
+                    cause = err;
+                }
+                attempt = await reconnect(retry, attempt, cause, state);
+            }
+        }
+        catch (err) {
+            if (state.closed) {
+                return;
+            }
+            throw err;
+        }
+    }
+    let reader;
+    const watch = {
+        get offsets() {
+            return { stdout, stderr };
+        },
+        close() {
+            state.close();
+        },
+        [Symbol.asyncIterator]() {
+            if (reader !== undefined) {
+                throw new Error(READER_TAKEN);
+            }
+            reader = createReader(run, () => state.close());
+            return reader;
+        },
+    };
+    return Promise.resolve(watch);
+}

package/dist/retry.d.ts

@@ -0,0 +1,42 @@
+/** How often and how long a call is retried; maxAttempts counts the first try. */
+export interface RetryPolicy {
+    readonly maxAttempts: number;
+    readonly initialBackoffMs: number;
+    readonly maxBackoffMs: number;
+}
+/** Five attempts, a 200 ms initial backoff and a 10 s cap (options.go:79-85). */
+export declare const defaultRetryPolicy: Readonly<RetryPolicy>;
+/** A resolved retry setting; false turns retries and watch reconnects off. */
+export type RetrySetting = Readonly<RetryPolicy> | false;
+/** What one procedure's retries are: a read, a keyed write, or nothing. */
+export type RetryClass = "read" | "keyed" | "none";
+/** The retry class of a generated procedure path; an unknown path is "none". */
+export declare function retryClassFor(procedure: string): RetryClass;
+/** The `/<service typeName>/<method name>` path the client keys the retry table by. */
+export declare function procedurePath(service: {
+    readonly typeName: string;
+}, method: {
+    readonly name: string;
+}): string;
+/** Fills defaults and clamps the policy; false stays false. */
+export declare function normalizeRetry(retry?: Partial<RetryPolicy> | false): RetrySetting;
+/**
+ * True only for a dropped connection or an unavailable server: Code.Unavailable,
+ * or Code.Aborted caused by one of the Node codes above (retry.go:143-147).
+ * A close that matches neither is returned to the caller, not resumed.
+ */
+export declare function isTransportLoss(err: unknown): boolean;
+/**
+ * isTransportLoss, plus a Connect stream that ended without its EndStreamResponse
+ * (connect 2.2.0 protocol-connect/transport.js:198 throws InvalidArgument with
+ * this message); that case is a lost stream, not a server refusal.
+ */
+export declare function isStreamLoss(err: unknown): boolean;
+/** A uniform jittered delay in [0, min(maxBackoffMs, initialBackoffMs * 2**attempt)]. */
+export declare function backoffDelay(policy: RetryPolicy, attempt: number): number;
+/** Sleeps, rejecting at once when the signal aborts (retry.go:186-200). */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/** The signal's reason as an error, or a Canceled ConnectError. */
+export declare function abortReason(signal: AbortSignal): Error;
+/** A 128-bit request key as 32 lowercase hex characters (retry.go:226-231). */
+export declare function newRequestKey(): string;

package/dist/retry.js

@@ -0,0 +1,213 @@
+import { Code, ConnectError } from "@connectrpc/connect";
+/** Five attempts, a 200 ms initial backoff and a 10 s cap (options.go:79-85). */
+export const defaultRetryPolicy = {
+    maxAttempts: 5,
+    initialBackoffMs: 200,
+    maxBackoffMs: 10_000,
+};
+// One entry per procedure of the five services, verbatim from the Go client's retry table.
+// A procedure missing from this table is treated as "none".
+const procedureRetryClass = {
+    "/toshi.workspace.v1.WorkspaceService/CreateWorkload": "keyed",
+    "/toshi.workspace.v1.WorkspaceService/GetWorkload": "read",
+    "/toshi.workspace.v1.WorkspaceService/ListWorkloads": "read",
+    "/toshi.workspace.v1.WorkspaceService/PatchWorkload": "keyed",
+    "/toshi.workspace.v1.WorkspaceService/DeleteWorkload": "keyed",
+    "/toshi.workspace.v1.WorkspaceService/CancelWorkload": "none",
+    "/toshi.workspace.v1.WorkspaceService/WaitWorkload": "read",
+    "/toshi.workspace.v1.WorkspaceService/WatchWorkloads": "none",
+    "/toshi.workspace.v1.WorkspaceService/WatchOutput": "none",
+    "/toshi.workspace.v1.WorkspaceService/WatchTelemetry": "none",
+    "/toshi.workspace.v1.WorkspaceService/WatchGuestLog": "none",
+    "/toshi.workspace.v1.WorkspaceService/Execute": "none",
+    "/toshi.workspace.v1.WorkspaceService/CancelExecution": "keyed",
+    "/toshi.workspace.v1.WorkspaceService/GetOperation": "read",
+    "/toshi.workspace.v1.WorkspaceService/WaitOperation": "read",
+    "/toshi.workspace.v1.WorkspaceService/ListEvents": "read",
+    "/toshi.workspace.v1.WorkspaceService/WatchEvents": "none",
+    "/toshi.workspace.v1.WorkspaceService/CreatePreviewShareLink": "none",
+    "/toshi.workspace.v1.WorkspaceService/ListPreviewShareLinks": "read",
+    "/toshi.workspace.v1.WorkspaceService/RevokePreviewShareLink": "none",
+    "/toshi.workspace.v1.WorkspaceService/StartService": "none",
+    "/toshi.workspace.v1.WorkspaceService/StopService": "none",
+    "/toshi.workspace.v1.WorkspaceService/SetServiceMode": "none",
+    "/toshi.workspace.v1.WorkspaceService/WakeService": "none",
+    "/toshi.workspace.v1.WorkspaceService/HoldService": "none",
+    "/toshi.workspace.v1.WorkspaceService/ReleaseService": "none",
+    "/toshi.workspace.v1.WorkspaceService/ListServiceRuns": "read",
+    "/toshi.workspace.v1.SecretService/CreateSecretSet": "none",
+    "/toshi.workspace.v1.SecretService/ListSecretSets": "read",
+    "/toshi.workspace.v1.SecretService/DeleteSecretSet": "none",
+    "/toshi.workspace.v1.SecretService/SetSecret": "none",
+    "/toshi.workspace.v1.SecretService/DeleteSecret": "none",
+    "/toshi.workspace.v1.SecretService/ListSecrets": "read",
+    "/toshi.workspace.v1.SecretService/ListSecretVersions": "read",
+    "/toshi.workspace.v1.SecretService/GrantSecretSet": "none",
+    "/toshi.workspace.v1.SecretService/RevokeSecretSet": "none",
+    "/toshi.workspace.v1.SecretService/ListSecretSetGrants": "read",
+    "/toshi.workspace.v1.ProjectService/ListProjects": "read",
+    "/toshi.workspace.v1.ProjectService/ListRepositories": "read",
+    "/toshi.workspace.v1.ProjectService/GetProject": "read",
+    "/toshi.workspace.v1.ProjectService/ListBranchRules": "read",
+    "/toshi.workspace.v1.ProjectService/CreateProject": "none",
+    "/toshi.workspace.v1.ProjectService/ClaimRepository": "none",
+    "/toshi.workspace.v1.ProjectService/CreateEnvironment": "none",
+    "/toshi.workspace.v1.ProjectService/DeleteEnvironment": "none",
+    "/toshi.workspace.v1.ProjectService/SetBranchRules": "none",
+    "/toshi.workspace.v1.ProjectService/CreateEmbedToken": "none",
+    "/toshi.workspace.v1.ProjectService/ListEmbedTokens": "read",
+    "/toshi.workspace.v1.ProjectService/RevokeEmbedToken": "none",
+    "/toshi.workspace.v1.WebhookService/CreateWebhookEndpoint": "keyed",
+    "/toshi.workspace.v1.WebhookService/GetWebhookEndpoint": "read",
+    "/toshi.workspace.v1.WebhookService/ListWebhookEndpoints": "read",
+    "/toshi.workspace.v1.WebhookService/UpdateWebhookEndpoint": "keyed",
+    "/toshi.workspace.v1.WebhookService/DeleteWebhookEndpoint": "keyed",
+    "/toshi.workspace.v1.WebhookService/RotateWebhookEndpointSecret": "keyed",
+    "/toshi.workspace.v1.WebhookService/ListWebhookDeliveries": "read",
+    "/toshi.workspace.v1.WebhookService/ReplayWebhookEvents": "keyed",
+    "/toshi.workspace.v1.DisplayService/OpenDisplaySession": "none",
+    "/toshi.workspace.v1.DisplayService/GetDisplaySession": "read",
+    "/toshi.workspace.v1.DisplayService/ListDisplaySessions": "read",
+    "/toshi.workspace.v1.DisplayService/CloseDisplaySession": "none",
+    "/toshi.workspace.v1.DisplayService/SendDisplayKeys": "none",
+    "/toshi.workspace.v1.DisplayService/SendDisplayPointer": "none",
+    "/toshi.workspace.v1.DisplayService/SetDisplayClipboard": "none",
+    "/toshi.workspace.v1.DisplayService/TakeDisplayScreenshot": "none",
+};
+/** The retry class of a generated procedure path; an unknown path is "none". */
+export function retryClassFor(procedure) {
+    return procedureRetryClass[procedure] ?? "none";
+}
+/** The `/<service typeName>/<method name>` path the client keys the retry table by. */
+export function procedurePath(service, method) {
+    return `/${service.typeName}/${method.name}`;
+}
+/** Fills defaults and clamps the policy; false stays false. */
+export function normalizeRetry(retry) {
+    if (retry === false) {
+        return false;
+    }
+    const merged = { ...defaultRetryPolicy, ...(retry ?? {}) };
+    return {
+        maxAttempts: Math.max(1, Math.trunc(merged.maxAttempts)),
+        initialBackoffMs: Math.max(0, merged.initialBackoffMs),
+        maxBackoffMs: Math.max(0, merged.maxBackoffMs),
+    };
+}
+// The Node system error codes connect-node 2.2.0 maps to Aborted or Unavailable
+// in node-error.js:36-51: ERR_STREAM_DESTROYED, ERR_HTTP2_INVALID_STREAM,
+// ECONNRESET (Aborted); ETIMEDOUT, ENOTFOUND, EAI_AGAIN, ECONNREFUSED (Unavailable).
+// ERR_STREAM_WRITE_AFTER_END is left out: node-error.js:23-34 maps it to Aborted
+// to say the server already answered with an error, so a retry repeats a refusal.
+// An HTTP/2 stream reset reaches us as Code.Internal with Node's
+// ERR_HTTP2_STREAM_ERROR, before connect's own reset mapping (node-error.js:105-125)
+// runs. REFUSED_STREAM says the server never processed the stream, so it is a loss,
+// as toshi-go's Unavailable for it is; every other reset code is returned.
+const nodeLossCodes = new Set([
+    "ERR_STREAM_DESTROYED",
+    "ERR_HTTP2_INVALID_STREAM",
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "ECONNREFUSED",
+]);
+// Whether the error chain carries one of those Node system error codes.
+function hasNodeLossCause(cause) {
+    let current = cause;
+    const seen = new Set();
+    while (current instanceof Error && !seen.has(current)) {
+        seen.add(current);
+        if (nodeLossCodes.has(current.code)) {
+            return true;
+        }
+        current = current.cause;
+    }
+    return false;
+}
+// Whether the error chain carries Node's report of a REFUSED_STREAM reset.
+function hasRefusedStreamCause(cause) {
+    let current = cause;
+    const seen = new Set();
+    while (current instanceof Error && !seen.has(current)) {
+        seen.add(current);
+        if (current.code === "ERR_HTTP2_STREAM_ERROR" &&
+            current.message.endsWith("NGHTTP2_REFUSED_STREAM")) {
+            return true;
+        }
+        current = current.cause;
+    }
+    return false;
+}
+/**
+ * True only for a dropped connection or an unavailable server: Code.Unavailable,
+ * or Code.Aborted caused by one of the Node codes above (retry.go:143-147).
+ * A close that matches neither is returned to the caller, not resumed.
+ */
+export function isTransportLoss(err) {
+    if (!(err instanceof ConnectError)) {
+        return false;
+    }
+    if (err.code === Code.Unavailable) {
+        return true;
+    }
+    if (err.code === Code.Internal) {
+        return hasRefusedStreamCause(err.cause);
+    }
+    return err.code === Code.Aborted && hasNodeLossCause(err.cause);
+}
+/**
+ * isTransportLoss, plus a Connect stream that ended without its EndStreamResponse
+ * (connect 2.2.0 protocol-connect/transport.js:198 throws InvalidArgument with
+ * this message); that case is a lost stream, not a server refusal.
+ */
+export function isStreamLoss(err) {
+    return (isTransportLoss(err) ||
+        (err instanceof ConnectError &&
+            err.code === Code.InvalidArgument &&
+            err.rawMessage === "protocol error: missing EndStreamResponse"));
+}
+/** A uniform jittered delay in [0, min(maxBackoffMs, initialBackoffMs * 2**attempt)]. */
+export function backoffDelay(policy, attempt) {
+    const limit = Math.min(policy.maxBackoffMs, policy.initialBackoffMs * 2 ** attempt);
+    if (limit <= 0) {
+        return 0;
+    }
+    const random = globalThis.crypto.getRandomValues(new Uint32Array(1))[0] / 2 ** 32;
+    return Math.floor(random * (limit + 1));
+}
+/** Sleeps, rejecting at once when the signal aborts (retry.go:186-200). */
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted === true) {
+            reject(abortReason(signal));
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortReason(signal));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** The signal's reason as an error, or a Canceled ConnectError. */
+export function abortReason(signal) {
+    const reason = signal.reason;
+    if (reason instanceof Error) {
+        return reason;
+    }
+    return new ConnectError("the call was cancelled", Code.Canceled);
+}
+/** A 128-bit request key as 32 lowercase hex characters (retry.go:226-231). */
+export function newRequestKey() {
+    const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
+    let key = "";
+    for (const byte of bytes) {
+        key += byte.toString(16).padStart(2, "0");
+    }
+    return key;
+}

package/dist/stream.d.ts

@@ -0,0 +1,21 @@
+import type { RetrySetting } from "./retry.js";
+/** The one-reader guard every watch shares. */
+export declare const READER_TAKEN = "toshi: this watch already has a reader";
+export declare const streamEnded: Error;
+interface AsyncGeneratorFactory<T> {
+    (): AsyncGenerator<T, void, undefined>;
+}
+export declare function createReader<T>(start: AsyncGeneratorFactory<T>, close: () => void): AsyncIterableIterator<T>;
+export declare function reconnect(retry: RetrySetting, attempt: number, cause: unknown, state: WatchState): Promise<number>;
+export declare class WatchState {
+    /** The caller-visible resume point; the output watch passes "" and ignores it. */
+    cursor: string;
+    closed: boolean;
+    readonly signal: AbortSignal;
+    private readonly controller;
+    private readonly caller;
+    private readonly onCallerAbort;
+    constructor(initialCursor: string, caller: AbortSignal | undefined);
+    close(): void;
+}
+export {};

package/dist/stream.js

@@ -0,0 +1,84 @@
+import { abortReason, backoffDelay, isStreamLoss, sleep } from "./retry.js";
+/** The one-reader guard every watch shares. */
+export const READER_TAKEN = "toshi: this watch already has a reader";
+// watch.go:473-476, output.go:120-127: a stream that ends without its end
+// message is a loss, so it is retried like one and reported with Go's wording
+// once no attempt remains.
+export const streamEnded = new Error("toshi: stream ended without an error");
+// connect's generated client exposes only next() (promise-client.ts:201-215), so
+// the watch owns the release: close() aborts the controller, and the reader's
+// return() does the same before ending the iteration.
+export function createReader(start, close) {
+    const generator = start();
+    return {
+        // Every end, an error included, releases the watch: a rejected next() is
+        // not followed by return(), so the caller's abort listener goes here.
+        next() {
+            return generator.next().then((result) => {
+                if (result.done === true) {
+                    close();
+                }
+                return result;
+            }, (err) => {
+                close();
+                throw err;
+            });
+        },
+        async return() {
+            close();
+            await generator.return(undefined);
+            return { done: true, value: undefined };
+        },
+        [Symbol.asyncIterator]() {
+            return this;
+        },
+    };
+}
+// watch.go:104-118, output.go:74-86: maxAttempts - 1 reconnects in a row, the
+// same jittered backoff, and the count reset by every message received. Anything
+// that is not a lost stream ends the iteration with that error.
+export async function reconnect(retry, attempt, cause, state) {
+    const lost = cause === streamEnded || isStreamLoss(cause);
+    if (retry === false || !lost || attempt >= retry.maxAttempts - 1) {
+        throw cause;
+    }
+    await sleep(backoffDelay(retry, attempt), state.signal);
+    return attempt + 1;
+}
+// Owns the AbortController that cancels the open RPC, a pending next() and any
+// backoff sleep; close() is the local end, an abort of the caller's signal is an
+// error for the caller (watch.go:221-233, output.go:194-206).
+export class WatchState {
+    /** The caller-visible resume point; the output watch passes "" and ignores it. */
+    cursor;
+    closed = false;
+    signal;
+    controller = new AbortController();
+    caller;
+    onCallerAbort = () => {
+        if (this.caller !== undefined) {
+            this.controller.abort(abortReason(this.caller));
+        }
+    };
+    constructor(initialCursor, caller) {
+        this.cursor = initialCursor;
+        this.caller = caller;
+        this.signal = this.controller.signal;
+        if (caller !== undefined) {
+            if (caller.aborted) {
+                this.onCallerAbort();
+            }
+            else {
+                caller.addEventListener("abort", this.onCallerAbort, { once: true });
+            }
+        }
+    }
+    close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.caller?.removeEventListener("abort", this.onCallerAbort);
+        this.controller.abort();
+    }
+}

package/dist/wait.d.ts

@@ -0,0 +1,8 @@
+import type { Client } from "@connectrpc/connect";
+import type { CallOptions } from "./client.js";
+import type { WorkspaceService } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import type { Operation, WaitOperationRequest, WaitWorkloadRequest, WaitWorkloadResponse } from "./gen/toshi/workspace/v1/workspace_pb.js";
+/** Asks again while reached is false, and returns the response when it is (wait.go:11-27). */
+export declare function waitWorkload(workspace: Client<typeof WorkspaceService>, req: WaitWorkloadRequest, opts?: CallOptions): Promise<WaitWorkloadResponse>;
+/** Asks again while the operation is not done, and returns it when it is (wait.go:29-45). */
+export declare function waitOperation(workspace: Client<typeof WorkspaceService>, req: WaitOperationRequest, opts?: CallOptions): Promise<Operation>;