@toshicloud/sdk 0.2.0 → 0.3.1

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

@@ -1,8 +1,13 @@
 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>;
+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(workspace: Client<typeof WorkspaceService>, req: WaitOperationRequest, opts?: CallOptions): Promise<Operation>;
+export declare function waitOperation(service: Client<typeof WorkloadService>, req: WaitOperationRequest, opts?: CallOptions): Promise<Operation>;

package/dist/wait.js

@@ -1,25 +1,37 @@
 import { abortReason } from "./retry.js";
-/** Asks again while reached is false, and returns the response when it is (wait.go:11-27). */
-export async function waitWorkload(workspace, req, opts) {
-    for (;;) {
-        throwIfAborted(opts);
-        const resp = await workspace.waitWorkload(req, opts);
-        if (resp.reached) {
-            return resp;
-        }
-    }
+/** 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(workspace, req, opts) {
+export async function waitOperation(service, req, opts) {
     for (;;) {
         throwIfAborted(opts);
-        const resp = await workspace.waitOperation(req, 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;

package/dist/watch.d.ts

@@ -1,8 +1,16 @@
 import type { Client } from "@connectrpc/connect";
-import type { CallOptions, EventWatch, WorkloadWatch } from "./client.js";
-import type { WatchEventsRequest, WatchWorkloadsRequest, WorkspaceService } from "./gen/toshi/workspace/v1/workspace_pb.js";
+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 workload watch; with an empty cursor it lists the workloads first (watch.go:40-84). */
-export declare function openWorkloadWatch(workspace: Client<typeof WorkspaceService>, retry: RetrySetting, req: WatchWorkloadsRequest, opts?: CallOptions): Promise<WorkloadWatch>;
-/** Starts an event watch; with an empty cursor it pages ListEvents as the caller iterates (watch.go:261-283). */
-export declare function openEventWatch(workspace: Client<typeof WorkspaceService>, retry: RetrySetting, req: WatchEventsRequest, opts?: CallOptions): Promise<EventWatch>;
+/** 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

@@ -1,14 +1,89 @@
 import { clone, create } from "@bufbuild/protobuf";
-import { ListEventsRequestSchema, ListWorkloadsRequestSchema, WatchEventsRequestSchema, WatchWorkloadsRequestSchema, } from "./gen/toshi/workspace/v1/workspace_pb.js";
+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 workload watch; with an empty cursor it lists the workloads first (watch.go:40-84). */
-export async function openWorkloadWatch(workspace, retry, req, opts) {
-    const state = new WatchState(req.cursor, opts?.signal);
+/** 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 (req.cursor === "") {
+    if (wire.request.cursor === "") {
         try {
-            const listed = await listWorkloads(workspace, req, state);
-            snapshot = listed.workloads;
+            const listed = await wire.list(state.signal);
+            snapshot = listed.items;
             state.cursor = listed.cursor;
         }
         catch (err) {
@@ -16,9 +91,8 @@ export async function openWorkloadWatch(workspace, retry, req, opts) {
             throw err;
         }
     }
-    const request = clone(WatchWorkloadsRequestSchema, req);
-    request.cursor = state.cursor;
-    request.keepalive = true;
+    wire.request.cursor = state.cursor;
+    wire.request.keepalive = true;
     let reader;
     return {
         get cursor() {
@@ -34,64 +108,12 @@ export async function openWorkloadWatch(workspace, retry, req, opts) {
             if (reader !== undefined) {
                 throw new Error(READER_TAKEN);
             }
-            reader = createReader(() => runWorkloads(workspace, retry, request, state), () => state.close());
-            return reader;
-        },
-    };
-}
-/** Starts an event watch; with an empty cursor it pages ListEvents as the caller iterates (watch.go:261-283). */
-export function openEventWatch(workspace, retry, req, opts) {
-    const state = new WatchState(req.cursor, opts?.signal);
-    const request = clone(WatchEventsRequestSchema, req);
-    request.keepalive = true;
-    const list = createListEventsRequest(req);
-    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(workspace, retry, request, list, listing, state), () => state.close());
+            reader = createReader(() => runWatch(wire, retry, state), () => state.close());
             return reader;
         },
     };
-    return Promise.resolve(watch);
-}
-// watch.go:65-84: every page of the list returns the event log's position.
-async function listWorkloads(workspace, req, state) {
-    const list = createListWorkloadsRequest(req);
-    const workloads = [];
-    for (;;) {
-        const page = await workspace.listWorkloads(list, { signal: state.signal });
-        workloads.push(...page.workloads);
-        if (page.nextPageToken === "") {
-            return { workloads, cursor: page.cursor };
-        }
-        list.pageToken = page.nextPageToken;
-    }
 }
-function createListWorkloadsRequest(req) {
-    return create(ListWorkloadsRequestSchema, {
-        project: req.project,
-        environment: req.environment,
-        kinds: req.kinds,
-    });
-}
-function createListEventsRequest(req) {
-    return create(ListEventsRequestSchema, {
-        project: req.project,
-        environment: req.environment,
-        workloadId: req.workloadId,
-    });
-}
-async function* runWorkloads(workspace, retry, request, state) {
+async function* runWatch(wire, retry, state) {
     let attempt = 0;
     try {
         for (;;) {
@@ -100,20 +122,21 @@ async function* runWorkloads(workspace, retry, request, state) {
             }
             let cause;
             try {
-                request.cursor = state.cursor;
-                const stream = workspace.watchWorkloads(request, { signal: state.signal });
-                for await (const msg of stream) {
+                wire.request.cursor = state.cursor;
+                for await (const message of wire.watch(state.signal)) {
                     attempt = 0;
-                    if (msg.keepalive !== undefined) {
-                        if (msg.keepalive.cursor !== "") {
-                            state.cursor = msg.keepalive.cursor;
+                    const keepalive = wire.keepalive(message);
+                    if (keepalive !== undefined) {
+                        if (keepalive.cursor !== "") {
+                            state.cursor = keepalive.cursor;
                         }
                         continue;
                     }
-                    if (msg.cursor !== "") {
-                        state.cursor = msg.cursor;
+                    const cursor = wire.cursor(message);
+                    if (cursor !== "") {
+                        state.cursor = cursor;
                     }
-                    yield msg;
+                    yield message;
                 }
                 if (state.closed) {
                     return;
@@ -136,14 +159,45 @@ async function* runWorkloads(workspace, retry, request, state) {
         throw err;
     }
 }
-async function* runEvents(workspace, retry, request, list, listingAtStart, state) {
+/**
+ * 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;
-    // watch.go:305-317: 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 consumed.
+    // 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 (;;) {
@@ -161,14 +215,14 @@ async function* runEvents(workspace, retry, request, list, listingAtStart, state
                             state.cursor = event.cursor;
                             resume = event.cursor;
                         }
-                        yield event;
+                        yield create(WatchEventsResponseSchema, { event });
                         continue;
                     }
-                    const listed = await workspace.listEvents(list, { signal: state.signal });
+                    const listed = await service.listEvents(list, { signal: state.signal });
                     page = listed.events;
                     pageIndex = 0;
                     if (listed.cursor !== "") {
-                        list.cursor = listed.cursor;
+                        list.pageToken = listed.cursor;
                     }
                     if (page.length > 0) {
                         continue;
@@ -180,10 +234,9 @@ async function* runEvents(workspace, retry, request, list, listingAtStart, state
                     continue;
                 }
                 request.cursor = resume;
-                const stream = workspace.watchEvents(request, { signal: state.signal });
-                for await (const msg of stream) {
+                for await (const message of service.watchEvents(request, { signal: state.signal })) {
                     attempt = 0;
-                    const keepalive = msg.keepalive;
+                    const keepalive = message.keepalive;
                     if (keepalive !== undefined) {
                         if (keepalive.cursor !== "") {
                             state.cursor = keepalive.cursor;
@@ -191,7 +244,7 @@ async function* runEvents(workspace, retry, request, list, listingAtStart, state
                         }
                         continue;
                     }
-                    const event = msg.event;
+                    const event = message.event;
                     if (event === undefined) {
                         continue;
                     }
@@ -199,7 +252,7 @@ async function* runEvents(workspace, retry, request, list, listingAtStart, state
                         state.cursor = event.cursor;
                         resume = event.cursor;
                     }
-                    yield event;
+                    yield message;
                 }
                 if (state.closed) {
                     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toshicloud/sdk",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "TypeScript client for the Toshi Workspace API",
   "license": "Apache-2.0",
   "packageManager": "pnpm@12.15.0+sha512.b3951d6d6ff4a9f13dc7cf56cd28d2b8eb37dbcc9c68e52e1e1191873ea9f82a017287ab50baadc5ccc494f036c67c0e47eb13608c2fa36f47711b61ea128e61",