@toshicloud/sdk 0.0.0-stage → 0.3.0

package/dist/client.js

@@ -0,0 +1,92 @@
+import { create } from "@bufbuild/protobuf";
+import { createClient } from "@connectrpc/connect";
+import { executeCommand } from "./execute.js";
+import { ArtifactService, ArtifactUploadService } from "./gen/toshi/workspace/v1/artifacts_pb.js";
+import { ChannelService } from "./gen/toshi/workspace/v1/channels_pb.js";
+import { DisplayService } from "./gen/toshi/workspace/v1/display_pb.js";
+import { ProjectService } from "./gen/toshi/workspace/v1/projects_pb.js";
+import { RecordingService } from "./gen/toshi/workspace/v1/recordings_pb.js";
+import { SecretService } from "./gen/toshi/workspace/v1/secrets_pb.js";
+import { VolumeService } from "./gen/toshi/workspace/v1/volumes_pb.js";
+import { WebhookService } from "./gen/toshi/workspace/v1/webhook_pb.js";
+import { CancelJobRequestSchema, CreateJobRequestSchema, CreateSandboxRequestSchema, CreateServiceRequestSchema, DeleteJobRequestSchema, DeleteSandboxRequestSchema, DeleteServiceRequestSchema, GetJobRequestSchema, GetSandboxRequestSchema, GetServiceRequestSchema, ListJobsRequestSchema, ListSandboxesRequestSchema, ListServicesRequestSchema, UpdateJobRequestSchema, UpdateSandboxRequestSchema, UpdateServiceRequestSchema, WaitJobRequestSchema, WaitSandboxRequestSchema, WaitServiceRequestSchema, WatchJobsRequestSchema, WatchSandboxesRequestSchema, WatchServicesRequestSchema, WorkloadService, } from "./gen/toshi/workspace/v1/workloads_pb.js";
+import { ExecuteStartSchema, HoldServiceRequestSchema, ListServiceRunsRequestSchema, ReleaseServiceRequestSchema, SetServiceModeRequestSchema, StartServiceRequestSchema, StopServiceRequestSchema, WaitOperationRequestSchema, WakeServiceRequestSchema, WatchEventsRequestSchema, WatchOutputRequestSchema, } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import { openOutputWatch } from "./output.js";
+import { authInterceptor, keyInterceptor, retryInterceptor, scopeInterceptor } from "./interceptors.js";
+import { normalizeRetry } from "./retry.js";
+import { openEventWatch, openJobWatch, openSandboxWatch, openServiceWatch } from "./watch.js";
+import { runJob } from "./run.js";
+import { waitJob, waitOperation, waitSandbox, waitService } from "./wait.js";
+/**
+ * Creates the client: one normalized retry setting, the auth, scope, key and
+ * retry interceptors (auth outermost, retry innermost), one transport for every
+ * client and helper.
+ *
+ * Since 0.2.0 the public contract is WorkloadService, not WorkspaceService: its
+ * calls are grouped by the type they name under `workload`, and the generated
+ * client is not handed out whole.
+ */
+export function createToshiClient(options) {
+    const retry = normalizeRetry(options.retry);
+    const interceptors = [
+        authInterceptor(options.token ?? ""),
+        scopeInterceptor(options.project ?? "", options.environment ?? ""),
+        keyInterceptor(),
+        retryInterceptor(retry),
+    ];
+    const transport = options.transport(interceptors);
+    const workloadService = createClient(WorkloadService, transport);
+    return {
+        project: createClient(ProjectService, transport),
+        secret: createClient(SecretService, transport),
+        webhook: createClient(WebhookService, transport),
+        display: createClient(DisplayService, transport),
+        channel: createClient(ChannelService, transport),
+        recording: createClient(RecordingService, transport),
+        volume: createClient(VolumeService, transport),
+        artifact: createClient(ArtifactService, transport),
+        artifactUpload: createClient(ArtifactUploadService, transport),
+        workload: {
+            jobs: {
+                create: (req, opts) => workloadService.createJob(req, opts),
+                get: (req, opts) => workloadService.getJob(req, opts),
+                list: (req, opts) => workloadService.listJobs(req, opts),
+                update: (req, opts) => workloadService.updateJob(req, opts),
+                delete: (req, opts) => workloadService.deleteJob(req, opts),
+                cancel: (req, opts) => workloadService.cancelJob(req, opts),
+                wait: (req, opts) => waitJob(workloadService, create(WaitJobRequestSchema, req), opts),
+                watch: (req, opts) => openJobWatch(workloadService, retry, create(WatchJobsRequestSchema, req), opts),
+                watchOutput: (req, opts) => openOutputWatch(workloadService, retry, create(WatchOutputRequestSchema, req), opts),
+            },
+            sandboxes: {
+                create: (req, opts) => workloadService.createSandbox(req, opts),
+                get: (req, opts) => workloadService.getSandbox(req, opts),
+                list: (req, opts) => workloadService.listSandboxes(req, opts),
+                update: (req, opts) => workloadService.updateSandbox(req, opts),
+                delete: (req, opts) => workloadService.deleteSandbox(req, opts),
+                wait: (req, opts) => waitSandbox(workloadService, create(WaitSandboxRequestSchema, req), opts),
+                watch: (req, opts) => openSandboxWatch(workloadService, retry, create(WatchSandboxesRequestSchema, req), opts),
+                execute: (start, opts) => executeCommand(workloadService, start, opts),
+            },
+            services: {
+                create: (req, opts) => workloadService.createService(req, opts),
+                get: (req, opts) => workloadService.getService(req, opts),
+                list: (req, opts) => workloadService.listServices(req, opts),
+                update: (req, opts) => workloadService.updateService(req, opts),
+                delete: (req, opts) => workloadService.deleteService(req, opts),
+                wait: (req, opts) => waitService(workloadService, create(WaitServiceRequestSchema, req), opts),
+                watch: (req, opts) => openServiceWatch(workloadService, retry, create(WatchServicesRequestSchema, req), opts),
+                start: (req, opts) => workloadService.startService(req, opts),
+                stop: (req, opts) => workloadService.stopService(req, opts),
+                setMode: (req, opts) => workloadService.setServiceMode(req, opts),
+                release: (req, opts) => workloadService.releaseService(req, opts),
+                wake: (req, opts) => workloadService.wakeService(req, opts),
+                hold: (req, opts) => workloadService.holdService(req, opts),
+                listRuns: (req, opts) => workloadService.listServiceRuns(req, opts),
+            },
+            waitOperation: (req, opts) => waitOperation(workloadService, create(WaitOperationRequestSchema, req), opts),
+            watchEvents: (req, opts) => openEventWatch(workloadService, retry, create(WatchEventsRequestSchema, req), opts),
+        },
+        run: (req, opts) => runJob(workloadService, retry, create(CreateJobRequestSchema, req), opts),
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,28 @@
+import type { ExecutionExit, OutputEnd } from "./gen/toshi/workspace/v1/workspace_pb.js";
+/** A command that ended non-zero, or was cancelled before it had a status (errors.go:9-26). */
+export declare class ExitError extends Error {
+    /** The execution the exit belongs to. */
+    readonly executionId: string;
+    /** The execution's exit message. */
+    readonly exit: ExecutionExit;
+    constructor(executionId: string, exit: ExecutionExit);
+}
+/** A job `run` started that did not exit 0. */
+export declare class JobExitError extends Error {
+    /** The job's id. */
+    readonly jobId: string;
+    /** The job's end-of-output message. */
+    readonly end: OutputEnd;
+    constructor(jobId: string, end: OutputEnd);
+}
+/**
+ * An Execute stream that ended before its exit message; stdin cannot be replayed
+ * (errors.go:28-49). The cause is the error that ended the stream.
+ */
+export declare class StreamLostError extends Error {
+    /** Empty when the stream was lost before the start was acknowledged. */
+    readonly executionId: string;
+    /** The request key of the start, so the caller may start again deliberately. */
+    readonly requestKey: string;
+    constructor(executionId: string, requestKey: string, cause?: unknown);
+}

package/dist/errors.js

@@ -0,0 +1,77 @@
+/** A command that ended non-zero, or was cancelled before it had a status (errors.go:9-26). */
+export class ExitError extends Error {
+    /** The execution the exit belongs to. */
+    executionId;
+    /** The execution's exit message. */
+    exit;
+    constructor(executionId, exit) {
+        super(exitMessage(executionId, exit));
+        this.name = "ExitError";
+        this.executionId = executionId;
+        this.exit = exit;
+    }
+}
+/** A job `run` started that did not exit 0. */
+export class JobExitError extends Error {
+    /** The job's id. */
+    jobId;
+    /** The job's end-of-output message. */
+    end;
+    constructor(jobId, end) {
+        super(jobMessage(jobId, end));
+        this.name = "JobExitError";
+        this.jobId = jobId;
+        this.end = end;
+    }
+}
+function jobMessage(jobId, end) {
+    if (end.cancelled) {
+        return `toshi: job ${jobId} was cancelled`;
+    }
+    if (end.exitCode === undefined) {
+        return `toshi: job ${jobId} ended without an exit status`;
+    }
+    return `toshi: job ${jobId} exited with status ${end.exitCode}`;
+}
+function exitMessage(executionId, exit) {
+    if (exit.cancelled) {
+        return `toshi: execution ${executionId} was cancelled`;
+    }
+    if (exit.exitCode === undefined) {
+        return `toshi: execution ${executionId} ended without an exit status`;
+    }
+    return `toshi: execution ${executionId} exited with status ${exit.exitCode}`;
+}
+/**
+ * An Execute stream that ended before its exit message; stdin cannot be replayed
+ * (errors.go:28-49). The cause is the error that ended the stream.
+ */
+export class StreamLostError extends Error {
+    /** Empty when the stream was lost before the start was acknowledged. */
+    executionId;
+    /** The request key of the start, so the caller may start again deliberately. */
+    requestKey;
+    constructor(executionId, requestKey, cause) {
+        super(lostMessage(executionId, requestKey, cause), cause === undefined ? undefined : { cause });
+        this.name = "StreamLostError";
+        this.executionId = executionId;
+        this.requestKey = requestKey;
+    }
+}
+function lostMessage(executionId, requestKey, cause) {
+    const detail = cause === undefined ? "" : `: ${describe(cause)}`;
+    if (executionId === "") {
+        return `toshi: execution stream lost before the start was acknowledged (request key ${requestKey})${detail}`;
+    }
+    return `toshi: execution ${executionId} stream lost (request key ${requestKey})${detail}`;
+}
+// The way Go's %v would print it, without stringifying an object as [object Object].
+function describe(cause) {
+    if (cause instanceof Error) {
+        return cause.message;
+    }
+    if (typeof cause === "string" || typeof cause === "number" || typeof cause === "boolean") {
+        return String(cause);
+    }
+    return "the stream ended";
+}

package/dist/execute.d.ts

@@ -0,0 +1,7 @@
+import type { MessageInitShape } from "@bufbuild/protobuf";
+import type { Client } from "@connectrpc/connect";
+import type { CallOptions, Process } from "./client.js";
+import { ExecuteStartSchema } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import type { WorkloadService } from "./gen/toshi/workspace/v1/workloads_pb.js";
+/** Starts a command and returns its process; the only export of this module. */
+export declare function executeCommand(service: Client<typeof WorkloadService>, start: MessageInitShape<typeof ExecuteStartSchema> | undefined, opts?: CallOptions): Promise<Process>;

package/dist/execute.js

@@ -0,0 +1,380 @@
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { createWritableIterable } from "@connectrpc/connect/protocol";
+import { ExitError, StreamLostError } from "./errors.js";
+import { isStreamLoss } from "./retry.js";
+import { ExecuteRequestSchema, ExecuteStartSchema, } from "./gen/toshi/workspace/v1/workspace_pb.js";
+// The largest standard-input frame Execute sends (execute.go:14-16).
+const STDIN_CHUNK = 64 << 10;
+const BROWSER_MESSAGE = 'toshi: Execute needs a Node transport over HTTP/2 (@connectrpc/connect-node with httpVersion "2"); a browser cannot open a bidirectional stream';
+/** Starts a command and returns its process; the only export of this module. */
+export async function executeCommand(service, start, opts) {
+    // G3: the browser check runs before any message or transport work, and reads
+    // process only through globalThis so src/ needs no Node import.
+    const nodeProcess = globalThis.process;
+    if (typeof nodeProcess?.versions?.node !== "string") {
+        throw new Error(BROWSER_MESSAGE);
+    }
+    if (start == null) {
+        throw new Error("toshi: Execute needs a start message");
+    }
+    const startMessage = create(ExecuteStartSchema, start);
+    const abort = new AbortController();
+    const signal = opts?.signal;
+    const requests = createWritableIterable();
+    const requestIterator = requests[Symbol.asyncIterator]();
+    const input = {
+        [Symbol.asyncIterator]: () => requestIterator,
+    };
+    // The handshake and, after it, the process both answer to the caller's signal.
+    const owner = {};
+    const onAbort = () => {
+        if (owner.process === undefined) {
+            abort.abort();
+            return;
+        }
+        owner.process.cancel();
+    };
+    // A signal that is already aborted starts nothing.
+    if (signal?.aborted === true) {
+        throw cancelledError();
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const finishHandshake = () => {
+        signal?.removeEventListener("abort", onAbort);
+    };
+    const responses = service.execute(input, { signal: abort.signal });
+    const responseIterator = responses[Symbol.asyncIterator]();
+    // Send the start and read the answer together: the request stream only moves
+    // while the call is running. The created message is the one the interceptors
+    // fill with scope and key, as fillRequestKey does (execute.go:26-27).
+    const startRequest = {
+        message: { case: "start", value: startMessage },
+    };
+    let first;
+    try {
+        const firstRead = responseIterator.next();
+        void firstRead.catch(() => undefined);
+        // The write resolves only once the request stream is read past the frame,
+        // and a server may answer the start without reading again, so both are
+        // awaited together: the first answer is the start's acknowledgement.
+        const startSent = requests.write(startRequest);
+        first = await Promise.race([firstRead, startSent.then(() => firstRead)]);
+        // A failure after the first answer is the stream's loss, reported by the
+        // output reader, not by the start's write.
+        void startSent.catch(() => undefined);
+    }
+    catch (err) {
+        finishHandshake();
+        closeRequest(requestIterator, err);
+        closeResponse(responseIterator);
+        abort.abort();
+        // A caller's own abort is a cancellation, not a lost server stream.
+        if (signal !== undefined && signal.aborted) {
+            throw cancelledError();
+        }
+        throw beforeStarted(err, readRequestKey(startMessage));
+    }
+    const message = first.done === true ? undefined : first.value.message;
+    if (message === undefined || message.case !== "started") {
+        const failure = message === undefined
+            ? new StreamLostError("", readRequestKey(startMessage), new Error("toshi: the Execute stream ended before its started message"))
+            : new Error("toshi: the Execute stream did not answer with a started message");
+        finishHandshake();
+        closeRequest(requestIterator, failure);
+        closeResponse(responseIterator);
+        abort.abort();
+        throw failure;
+    }
+    const process = new ExecuteProcess(message.value.executionId, readRequestKey(startMessage), requests, requestIterator, responseIterator, abort, signal, onAbort);
+    owner.process = process;
+    return process;
+}
+function deferred() {
+    let settle = () => undefined;
+    const promise = new Promise((resolve) => {
+        settle = resolve;
+    });
+    return { promise, resolve: (value) => settle(value) };
+}
+function cancelledError() {
+    return new ConnectError("the call was cancelled", Code.Canceled);
+}
+/**
+ * Before started, a ConnectError is the server's answer and goes back
+ * unchanged; anything else is a lost stream (execute.go:30-46).
+ */
+function beforeStarted(err, requestKey) {
+    if (err instanceof ConnectError && !isStreamLoss(err)) {
+        return err;
+    }
+    return new StreamLostError("", requestKey, err);
+}
+/** The key the start carried, including one the client's interceptor filled. */
+function readRequestKey(start) {
+    return start.requestKey;
+}
+function closeRequest(iterator, reason) {
+    try {
+        void iterator.throw?.(reason)?.catch(() => undefined);
+    }
+    catch {
+        // the request stream is already gone
+    }
+}
+function closeResponse(iterator) {
+    try {
+        void iterator.return?.()?.catch(() => undefined);
+    }
+    catch {
+        // the response stream is already gone
+    }
+}
+/**
+ * One execution started by Execute. It reads the response only when its output
+ * is pulled or wait() drains it, so a stalled reader stalls the server's
+ * stream rather than buffering without bound.
+ */
+class ExecuteProcess {
+    executionId;
+    requestKey;
+    requests;
+    requestIterator;
+    responses;
+    abort;
+    signal;
+    onSignalAbort;
+    terminalSignal = deferred();
+    queue = [];
+    terminal;
+    readerOwned = false;
+    waitPromise;
+    writeChain = Promise.resolve();
+    writing = false;
+    stdinClosed = false;
+    closePromise;
+    constructor(executionId, requestKey, requests, requestIterator, responses, abort, signal, onSignalAbort) {
+        this.executionId = executionId;
+        this.requestKey = requestKey;
+        this.requests = requests;
+        this.requestIterator = requestIterator;
+        this.responses = responses;
+        this.abort = abort;
+        this.signal = signal;
+        this.onSignalAbort = onSignalAbort;
+        if (signal?.aborted === true) {
+            this.cancel();
+        }
+    }
+    [Symbol.asyncIterator]() {
+        if (this.readerOwned) {
+            throw new Error("toshi: this process already has an output reader");
+        }
+        this.readerOwned = true;
+        return {
+            next: () => this.pull(),
+            // A break aborts the local stream; wait() then reports Canceled.
+            return: () => {
+                this.cancel();
+                return Promise.resolve({ done: true, value: undefined });
+            },
+        };
+    }
+    /**
+     * Sends stdin in frames of at most 64 KiB and resolves once the last frame
+     * was consumed. One write at a time: a write while another is pending is
+     * refused, so the client holds at most one caller buffer and one frame.
+     */
+    write(data) {
+        if (this.terminal !== undefined) {
+            return Promise.reject(this.closedReason());
+        }
+        if (this.stdinClosed) {
+            return Promise.reject(new Error("toshi: standard input is closed"));
+        }
+        if (this.writing) {
+            return Promise.reject(new Error("toshi: a write is still pending; await it before writing again"));
+        }
+        this.writing = true;
+        const run = (typeof data === "string" ? this.sendText(data) : this.sendFrames(data)).finally(() => {
+            this.writing = false;
+        });
+        this.writeChain = run.catch(() => undefined);
+        return run;
+    }
+    /** Sends close_stdin once, after a pending write; later writes are refused (execute.go:243-256). */
+    closeStdin() {
+        if (this.closePromise !== undefined) {
+            return this.closePromise;
+        }
+        this.stdinClosed = true;
+        const run = this.writeChain.then(() => {
+            if (this.terminal !== undefined) {
+                return;
+            }
+            // Not awaited: the frame is consumed only when the request stream is read
+            // past it, and the server stops reading after close_stdin.
+            const sent = this.requests.write({ message: { case: "closeStdin", value: true } });
+            void sent.catch(() => undefined);
+        });
+        this.closePromise = run;
+        return run;
+    }
+    /** The process's outcome; the same promise on every call. */
+    wait() {
+        this.waitPromise ??= this.awaitOutcome();
+        return this.waitPromise;
+    }
+    /** Ends the process as cancelled: early break and an aborted call signal. */
+    cancel() {
+        this.finish({ kind: "cancelled", error: cancelledError() });
+    }
+    async sendFrames(bytes) {
+        for (let offset = 0; offset < bytes.length; offset += STDIN_CHUNK) {
+            const end = Math.min(offset + STDIN_CHUNK, bytes.length);
+            // Copied, as the sender copies each chunk (execute.go:227).
+            const frame = bytes.slice(offset, end);
+            await this.requests.write({ message: { case: "stdin", value: frame } });
+        }
+    }
+    // Encodes one frame at a time, so a long string is never copied whole.
+    async sendText(text) {
+        const encoder = new TextEncoder();
+        let rest = text;
+        while (rest.length > 0) {
+            const frame = new Uint8Array(STDIN_CHUNK);
+            const { read, written } = encoder.encodeInto(rest, frame);
+            rest = rest.slice(read);
+            await this.requests.write({ message: { case: "stdin", value: frame.subarray(0, written) } });
+        }
+    }
+    async awaitOutcome() {
+        if (!this.readerOwned && this.terminal === undefined) {
+            // No reader owns the output: take it and drain it, so wait() never stalls on unread output.
+            this.readerOwned = true;
+            try {
+                for (;;) {
+                    const result = await this.pull();
+                    if (result.done === true) {
+                        break;
+                    }
+                }
+            }
+            catch {
+                // pull() recorded the terminal outcome; it is reported below.
+            }
+        }
+        await this.terminalSignal.promise;
+        const terminal = this.terminal;
+        if (terminal === undefined) {
+            throw cancelledError();
+        }
+        switch (terminal.kind) {
+            case "exit":
+                if (terminal.error !== undefined) {
+                    throw terminal.error;
+                }
+                return;
+            default:
+                throw terminal.error;
+        }
+    }
+    async pull() {
+        for (;;) {
+            const chunk = this.queue.shift();
+            if (chunk !== undefined) {
+                return { done: false, value: chunk };
+            }
+            if (this.terminal !== undefined) {
+                return this.terminalResult();
+            }
+            await this.readOne();
+        }
+    }
+    terminalResult() {
+        const terminal = this.terminal;
+        if (terminal === undefined || terminal.kind === "exit") {
+            return { done: true, value: undefined };
+        }
+        throw terminal.error;
+    }
+    async readOne() {
+        const next = this.responses.next();
+        // Losing the race must not leave an unhandled rejection behind: both
+        // branches below are attached before the race settles.
+        const raced = await Promise.race([
+            next.then((result) => ({ kind: "message", result }), (error) => ({ kind: "error", error })),
+            this.terminalSignal.promise.then(() => ({ kind: "terminal" })),
+        ]);
+        if (raced.kind === "terminal") {
+            return;
+        }
+        if (raced.kind === "error") {
+            // After started, every end before the exit message is a lost stream
+            // (execute.go:113-118).
+            this.finish({ kind: "lost", error: this.lost(raced.error) });
+            return;
+        }
+        if (raced.result.done === true) {
+            this.finish({
+                kind: "lost",
+                error: this.lost(new Error("toshi: the Execute stream ended without an exit message")),
+            });
+            return;
+        }
+        this.handle(raced.result.value);
+    }
+    handle(response) {
+        const message = response.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 "exit":
+                this.finishExit(message.value);
+                return;
+            default:
+                // A repeated started is ignored, as the receive switch does (execute.go:107-127).
+                return;
+        }
+    }
+    lost(cause) {
+        return new StreamLostError(this.executionId, this.requestKey, cause);
+    }
+    finishExit(exit) {
+        // Only a zero exit code is success; an absent one never is (execute.go:197-204).
+        const ok = exit.exitCode === 0;
+        this.finish({
+            kind: "exit",
+            exit,
+            error: ok ? undefined : new ExitError(this.executionId, exit),
+        });
+    }
+    finish(terminal) {
+        if (this.terminal !== undefined) {
+            return;
+        }
+        this.terminal = terminal;
+        this.terminalSignal.resolve();
+        if (this.signal !== undefined) {
+            this.signal.removeEventListener("abort", this.onSignalAbort);
+        }
+        // Closing the request side rejects pending writes (execute.go:131-151).
+        closeRequest(this.requestIterator, this.closedReason());
+        this.abort.abort();
+        closeResponse(this.responses);
+    }
+    closedReason() {
+        const terminal = this.terminal;
+        if (terminal === undefined) {
+            return cancelledError();
+        }
+        if (terminal.kind === "exit") {
+            return terminal.error ?? new Error("toshi: the execution has ended");
+        }
+        return terminal.error;
+    }
+}