@toshicloud/sdk 0.0.0-stage → 0.3.0

package/dist/run.js

@@ -0,0 +1,175 @@
+import { create } from "@bufbuild/protobuf";
+import { JobExitError } from "./errors.js";
+import { OutputEndSchema, WatchOutputRequestSchema } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import { EndReason } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import { openOutputWatch } from "./output.js";
+/**
+ * Starts a job and follows its output, as `toshi run` does: CreateJob, then
+ * WatchOutput from the first byte. A job whose create answered its output
+ * (wait_for_end was set) is returned finished.
+ */
+export async function runJob(service, retry, req, opts) {
+    const created = await service.createJob(req, opts);
+    const job = created.job;
+    if (job === undefined) {
+        throw new Error("toshi: CreateJob answered no job");
+    }
+    if (created.output !== undefined) {
+        return new FinishedRun(job, created.output);
+    }
+    const watch = await openOutputWatch(service, retry, create(WatchOutputRequestSchema, {
+        project: req.project,
+        environment: req.environment,
+        id: job.id,
+    }), opts);
+    return new LiveRun(job, watch);
+}
+/** A run whose create answered the job's output instead of a live stream. */
+class FinishedRun {
+    job;
+    output;
+    queue;
+    constructor(job, output) {
+        this.job = job;
+        this.output = output;
+    }
+    [Symbol.asyncIterator]() {
+        this.queue ??= chunksOf(this.output);
+        const queue = this.queue;
+        return {
+            next: () => {
+                const chunk = queue.shift();
+                return Promise.resolve(chunk === undefined ? { done: true, value: undefined } : { done: false, value: chunk });
+            },
+        };
+    }
+    wait() {
+        const end = create(OutputEndSchema, {
+            exitCode: this.job.status?.exitCode,
+            cancelled: this.job.status?.endReason === EndReason.CANCELLED,
+            truncated: this.output.truncated,
+        });
+        if (end.exitCode === 0) {
+            return Promise.resolve();
+        }
+        return Promise.reject(new JobExitError(this.job.id, end));
+    }
+}
+/** A run whose output the server streams while the job runs. */
+class LiveRun {
+    job;
+    watch;
+    responses;
+    queue = [];
+    end;
+    failure;
+    readerOwned = false;
+    waitPromise;
+    constructor(job, watch) {
+        this.job = job;
+        this.watch = watch;
+        this.responses = watch[Symbol.asyncIterator]();
+    }
+    [Symbol.asyncIterator]() {
+        if (this.readerOwned) {
+            throw new Error("toshi: this run already has an output reader");
+        }
+        this.readerOwned = true;
+        return {
+            next: () => this.pull(),
+            // A break ends only this reader: the job keeps running.
+            return: () => {
+                this.watch.close();
+                return Promise.resolve({ done: true, value: undefined });
+            },
+        };
+    }
+    wait() {
+        this.waitPromise ??= this.awaitOutcome();
+        return this.waitPromise;
+    }
+    async awaitOutcome() {
+        if (!this.readerOwned) {
+            // No reader owns the output: take it and drain it, so wait() never stalls.
+            this.readerOwned = true;
+            try {
+                for (;;) {
+                    const result = await this.pull();
+                    if (result.done === true) {
+                        break;
+                    }
+                }
+            }
+            catch {
+                // pull() recorded the outcome; it is reported below.
+            }
+        }
+        for (;;) {
+            if (this.failure !== undefined) {
+                throw this.failure;
+            }
+            if (this.end !== undefined) {
+                if (this.end.exitCode === 0 && !this.end.cancelled) {
+                    return;
+                }
+                throw new JobExitError(this.job.id, this.end);
+            }
+            await this.readOne();
+        }
+    }
+    async pull() {
+        for (;;) {
+            const chunk = this.queue.shift();
+            if (chunk !== undefined) {
+                return { done: false, value: chunk };
+            }
+            if (this.failure !== undefined) {
+                throw this.failure;
+            }
+            if (this.end !== undefined) {
+                return { done: true, value: undefined };
+            }
+            await this.readOne();
+        }
+    }
+    async readOne() {
+        let result;
+        try {
+            result = await this.responses.next();
+        }
+        catch (err) {
+            this.failure = err instanceof Error ? err : new Error(String(err));
+            return;
+        }
+        if (result.done === true) {
+            this.failure = new Error("toshi: the output stream ended without its end message");
+            return;
+        }
+        const message = result.value.message;
+        switch (message.case) {
+            case "stdout":
+                this.queue.push({ stream: "stdout", data: message.value });
+                return;
+            case "stderr":
+                this.queue.push({ stream: "stderr", data: message.value });
+                return;
+            case "end":
+                this.end = message.value;
+                // The watch has nothing left to send; release the RPC.
+                this.watch.close();
+                return;
+            default:
+                return;
+        }
+    }
+}
+function chunksOf(output) {
+    const chunks = [];
+    if (output.stdout.length > 0) {
+        chunks.push({ stream: "stdout", data: output.stdout });
+    }
+    if (output.stderr.length > 0) {
+        chunks.push({ stream: "stderr", data: output.stderr });
+    }
+    return chunks;
+}

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,13 @@
+import type { Client } from "@connectrpc/connect";
+import type { CallOptions } from "./client.js";
+import type { WorkloadService } from "./gen/toshi/workspace/v1/workloads_pb.js";
+import type { WaitJobRequest, WaitJobResponse, WaitSandboxRequest, WaitSandboxResponse, WaitServiceRequest, WaitServiceResponse } from "./gen/toshi/workspace/v1/workloads_pb.js";
+import type { Operation, WaitOperationRequest } from "./gen/toshi/workspace/v1/workspace_pb.js";
+/** Asks again while the job is not in a state it waits for, and returns the answer when it is. */
+export declare function waitJob(service: Client<typeof WorkloadService>, req: WaitJobRequest, opts?: CallOptions): Promise<WaitJobResponse>;
+/** Asks again while the sandbox is not in a state it waits for. */
+export declare function waitSandbox(service: Client<typeof WorkloadService>, req: WaitSandboxRequest, opts?: CallOptions): Promise<WaitSandboxResponse>;
+/** Asks again while the service is not in a state it waits for. */
+export declare function waitService(service: Client<typeof WorkloadService>, req: WaitServiceRequest, opts?: CallOptions): Promise<WaitServiceResponse>;
+/** Asks again while the operation is not done, and returns it when it is (wait.go:29-45). */
+export declare function waitOperation(service: Client<typeof WorkloadService>, req: WaitOperationRequest, opts?: CallOptions): Promise<Operation>;

package/dist/wait.js

@@ -0,0 +1,41 @@
+import { abortReason } from "./retry.js";
+/** Asks again while the job is not in a state it waits for, and returns the answer when it is. */
+export function waitJob(service, req, opts) {
+    return waitReached(() => service.waitJob(req, opts), opts);
+}
+/** Asks again while the sandbox is not in a state it waits for. */
+export function waitSandbox(service, req, opts) {
+    return waitReached(() => service.waitSandbox(req, opts), opts);
+}
+/** Asks again while the service is not in a state it waits for. */
+export function waitService(service, req, opts) {
+    return waitReached(() => service.waitService(req, opts), opts);
+}
+/** Asks again while the operation is not done, and returns it when it is (wait.go:29-45). */
+export async function waitOperation(service, req, opts) {
+    for (;;) {
+        throwIfAborted(opts);
+        const resp = await service.waitOperation(req, opts);
+        const op = resp.operation;
+        if (op !== undefined && op.done) {
+            return op;
+        }
+    }
+}
+// The three waits share one loop: each answers reached when the state arrived.
+async function waitReached(call, opts) {
+    for (;;) {
+        throwIfAborted(opts);
+        const resp = await call();
+        if (resp.reached) {
+            return resp;
+        }
+    }
+}
+// wait.go:16-18: the caller's context ends the loop with its own error.
+function throwIfAborted(opts) {
+    const signal = opts?.signal;
+    if (signal?.aborted === true) {
+        throw abortReason(signal);
+    }
+}

package/dist/watch.d.ts

@@ -0,0 +1,16 @@
+import type { Client } from "@connectrpc/connect";
+import type { CallOptions, EventWatch, JobWatch, SandboxWatch, ServiceWatch } from "./client.js";
+import type { WatchJobsRequest, WatchSandboxesRequest, WatchServicesRequest, WorkloadService } from "./gen/toshi/workspace/v1/workloads_pb.js";
+import type { WatchEventsRequest } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import type { RetrySetting } from "./retry.js";
+/** Starts a job watch; with an empty cursor it lists the jobs first. */
+export declare function openJobWatch(service: Client<typeof WorkloadService>, retry: RetrySetting, req: WatchJobsRequest, opts?: CallOptions): Promise<JobWatch>;
+/** Starts a sandbox watch; with an empty cursor it lists the sandboxes first. */
+export declare function openSandboxWatch(service: Client<typeof WorkloadService>, retry: RetrySetting, req: WatchSandboxesRequest, opts?: CallOptions): Promise<SandboxWatch>;
+/** Starts a service watch; with an empty cursor it lists the services first. */
+export declare function openServiceWatch(service: Client<typeof WorkloadService>, retry: RetrySetting, req: WatchServicesRequest, opts?: CallOptions): Promise<ServiceWatch>;
+/**
+ * Starts an event watch; with an empty cursor it pages the event log as the
+ * caller iterates. Every message it yields is the stream's response.
+ */
+export declare function openEventWatch(service: Client<typeof WorkloadService>, retry: RetrySetting, req: WatchEventsRequest, opts?: CallOptions): Promise<EventWatch>;

package/dist/watch.js

@@ -0,0 +1,277 @@
+import { clone, create } from "@bufbuild/protobuf";
+import { ListJobsRequestSchema, ListSandboxesRequestSchema, ListServicesRequestSchema, WatchJobsRequestSchema, WatchSandboxesRequestSchema, WatchServicesRequestSchema, } from "./gen/toshi/workspace/v1/workloads_pb.js";
+import { ListEventsRequestSchema, WatchEventsRequestSchema, WatchEventsResponseSchema, } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import { READER_TAKEN, WatchState, createReader, reconnect, streamEnded } from "./stream.js";
+/** Starts a job watch; with an empty cursor it lists the jobs first. */
+export function openJobWatch(service, retry, req, opts) {
+    const request = clone(WatchJobsRequestSchema, req);
+    return openWatch({
+        request,
+        list: async (signal) => {
+            const list = create(ListJobsRequestSchema, {
+                project: request.project,
+                environment: request.environment,
+            });
+            const items = [];
+            for (;;) {
+                const page = await service.listJobs(list, { signal });
+                items.push(...page.jobs);
+                if (page.nextPageToken === "") {
+                    return { items, cursor: page.cursor };
+                }
+                list.pageToken = page.nextPageToken;
+            }
+        },
+        watch: (signal) => service.watchJobs(request, { signal }),
+        cursor: (message) => message.cursor,
+        keepalive: (message) => message.keepalive,
+    }, retry, opts);
+}
+/** Starts a sandbox watch; with an empty cursor it lists the sandboxes first. */
+export function openSandboxWatch(service, retry, req, opts) {
+    const request = clone(WatchSandboxesRequestSchema, req);
+    return openWatch({
+        request,
+        list: async (signal) => {
+            const list = create(ListSandboxesRequestSchema, {
+                project: request.project,
+                environment: request.environment,
+            });
+            const items = [];
+            for (;;) {
+                const page = await service.listSandboxes(list, { signal });
+                items.push(...page.sandboxes);
+                if (page.nextPageToken === "") {
+                    return { items, cursor: page.cursor };
+                }
+                list.pageToken = page.nextPageToken;
+            }
+        },
+        watch: (signal) => service.watchSandboxes(request, { signal }),
+        cursor: (message) => message.cursor,
+        keepalive: (message) => message.keepalive,
+    }, retry, opts);
+}
+/** Starts a service watch; with an empty cursor it lists the services first. */
+export function openServiceWatch(service, retry, req, opts) {
+    const request = clone(WatchServicesRequestSchema, req);
+    return openWatch({
+        request,
+        list: async (signal) => {
+            const list = create(ListServicesRequestSchema, {
+                project: request.project,
+                environment: request.environment,
+            });
+            const items = [];
+            for (;;) {
+                const page = await service.listServices(list, { signal });
+                items.push(...page.services);
+                if (page.nextPageToken === "") {
+                    return { items, cursor: page.cursor };
+                }
+                list.pageToken = page.nextPageToken;
+            }
+        },
+        watch: (signal) => service.watchServices(request, { signal }),
+        cursor: (message) => message.cursor,
+        keepalive: (message) => message.keepalive,
+    }, retry, opts);
+}
+async function openWatch(wire, retry, opts) {
+    const state = new WatchState(wire.request.cursor, opts?.signal);
+    let snapshot;
+    if (wire.request.cursor === "") {
+        try {
+            const listed = await wire.list(state.signal);
+            snapshot = listed.items;
+            state.cursor = listed.cursor;
+        }
+        catch (err) {
+            state.close();
+            throw err;
+        }
+    }
+    wire.request.cursor = state.cursor;
+    wire.request.keepalive = true;
+    let reader;
+    return {
+        get cursor() {
+            return state.cursor;
+        },
+        get snapshot() {
+            return snapshot;
+        },
+        close() {
+            state.close();
+        },
+        [Symbol.asyncIterator]() {
+            if (reader !== undefined) {
+                throw new Error(READER_TAKEN);
+            }
+            reader = createReader(() => runWatch(wire, retry, state), () => state.close());
+            return reader;
+        },
+    };
+}
+async function* runWatch(wire, retry, state) {
+    let attempt = 0;
+    try {
+        for (;;) {
+            if (state.closed) {
+                return;
+            }
+            let cause;
+            try {
+                wire.request.cursor = state.cursor;
+                for await (const message of wire.watch(state.signal)) {
+                    attempt = 0;
+                    const keepalive = wire.keepalive(message);
+                    if (keepalive !== undefined) {
+                        if (keepalive.cursor !== "") {
+                            state.cursor = keepalive.cursor;
+                        }
+                        continue;
+                    }
+                    const cursor = wire.cursor(message);
+                    if (cursor !== "") {
+                        state.cursor = cursor;
+                    }
+                    yield message;
+                }
+                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;
+    }
+}
+/**
+ * Starts an event watch; with an empty cursor it pages the event log as the
+ * caller iterates. Every message it yields is the stream's response.
+ */
+export function openEventWatch(service, retry, req, opts) {
+    const state = new WatchState(req.cursor, opts?.signal);
+    const request = clone(WatchEventsRequestSchema, req);
+    request.keepalive = true;
+    const list = create(ListEventsRequestSchema, {
+        project: req.project,
+        environment: req.environment,
+        workloadId: req.workloadId,
+    });
+    const listing = req.cursor === "";
+    let reader;
+    const watch = {
+        get cursor() {
+            return state.cursor;
+        },
+        close() {
+            state.close();
+        },
+        [Symbol.asyncIterator]() {
+            if (reader !== undefined) {
+                throw new Error(READER_TAKEN);
+            }
+            reader = createReader(() => runEvents(service, retry, request, list, listing, state), () => state.close());
+            return reader;
+        },
+    };
+    return Promise.resolve(watch);
+}
+async function* runEvents(service, retry, request, list, listingAtStart, state) {
+    let attempt = 0;
+    let page = [];
+    let pageIndex = 0;
+    let listing = listingAtStart;
+    // Resume is the position the next stream opens at, separate from the cursor
+    // the caller sees, which only moves on events handed out and keepalives read.
+    let resume = state.cursor;
+    try {
+        for (;;) {
+            if (state.closed) {
+                return;
+            }
+            let cause;
+            try {
+                if (listing) {
+                    if (pageIndex < page.length) {
+                        const event = page[pageIndex];
+                        pageIndex += 1;
+                        attempt = 0;
+                        if (event.cursor !== "") {
+                            state.cursor = event.cursor;
+                            resume = event.cursor;
+                        }
+                        yield create(WatchEventsResponseSchema, { event });
+                        continue;
+                    }
+                    const listed = await service.listEvents(list, { signal: state.signal });
+                    page = listed.events;
+                    pageIndex = 0;
+                    if (listed.cursor !== "") {
+                        list.pageToken = listed.cursor;
+                    }
+                    if (page.length > 0) {
+                        continue;
+                    }
+                    if (listed.cursor !== "") {
+                        resume = listed.cursor;
+                    }
+                    listing = false;
+                    continue;
+                }
+                request.cursor = resume;
+                for await (const message of service.watchEvents(request, { signal: state.signal })) {
+                    attempt = 0;
+                    const keepalive = message.keepalive;
+                    if (keepalive !== undefined) {
+                        if (keepalive.cursor !== "") {
+                            state.cursor = keepalive.cursor;
+                            resume = keepalive.cursor;
+                        }
+                        continue;
+                    }
+                    const event = message.event;
+                    if (event === undefined) {
+                        continue;
+                    }
+                    if (event.cursor !== "") {
+                        state.cursor = event.cursor;
+                        resume = event.cursor;
+                    }
+                    yield message;
+                }
+                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;
+    }
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@toshicloud/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "TypeScript client for the Toshi Workspace API",
+  "license": "Apache-2.0",
+  "packageManager": "pnpm@12.15.0+sha512.b3951d6d6ff4a9f13dc7cf56cd28d2b8eb37dbcc9c68e52e1e1191873ea9f82a017287ab50baadc5ccc494f036c67c0e47eb13608c2fa36f47711b61ea128e61",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.22 <25"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/toshicloud/toshi-ts.git"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run --coverage",
+    "generate": "scripts/generate.sh",
+    "prepack": "pnpm run build"
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "^2.16.0",
+    "@connectrpc/connect": "^2.2.0"
+  },
+  "devDependencies": {
+    "@connectrpc/connect-node": "2.2.0",
+    "@eslint/js": "10.0.1",
+    "@types/node": "26.6.5",
+    "@vitest/coverage-v8": "5.0.5",
+    "eslint": "10.13.0",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.72.0",
+    "vitest": "5.0.5"
+  }
+}