@toshicloud/sdk 0.3.1 → 0.4.0

package/dist/node/client.js

@@ -0,0 +1,178 @@
+import { readFileSync, statSync } from "node:fs";
+import { versions } from "node:process";
+import { rootCertificates } from "node:tls";
+import { createConnectTransport } from "@connectrpc/connect-node";
+import { createToshiClient as createRootClient } from "../client.js";
+import { VERSION } from "../version.js";
+/**
+ * Creates a Node client. Without a transport of its own it builds one with
+ * connect-node over HTTP/2, takes the server from `server` or TOSHI_SERVER and
+ * the token from `tokenSource`, `token`, `tokenFile`, TOSHI_TOKEN or
+ * TOSHI_TOKEN_FILE.
+ *
+ * The User-Agent is "toshi-ts/<version> (node/<node version>)", with
+ * `userAgent` in front when it is set. Connect exports no version constant, so
+ * its name is not part of the string.
+ */
+export function createToshiClient(options = {}) {
+    const custom = options.transport;
+    const resolved = resolveToken(options, custom !== undefined);
+    const agent = userAgent(options.userAgent ?? "");
+    const outer = (interceptors) => [
+        ...(options.interceptors ?? []),
+        userAgentInterceptor(agent),
+        ...interceptors,
+    ];
+    let transport = custom;
+    if (transport === undefined) {
+        const server = resolveServer(options.server);
+        const caFile = resolveCAFile(options.caFile);
+        const ca = caFile === undefined ? undefined : caBundle(caFile);
+        transport = (interceptors) => createConnectTransport({
+            baseUrl: server,
+            httpVersion: "2",
+            interceptors: outer(interceptors),
+            ...(ca === undefined ? {} : { nodeOptions: { ca } }),
+        });
+    }
+    else {
+        const transportOfCaller = transport;
+        transport = (interceptors) => transportOfCaller(outer(interceptors));
+    }
+    return createRootClient({
+        ...options,
+        transport,
+        token: resolved.token,
+        tokenSource: resolved.tokenSource,
+    });
+}
+/** The User-Agent every Node request carries, with product in front when set. */
+export function userAgent(product) {
+    const base = `toshi-ts/${VERSION} (node/${versions.node})`;
+    return product === "" ? base : `${product} ${base}`;
+}
+function userAgentInterceptor(agent) {
+    return (next) => async (req) => {
+        const header = new Headers(req.header);
+        header.set("User-Agent", agent);
+        return next({ ...req, header });
+    };
+}
+function resolveServer(given) {
+    const server = given !== undefined && given !== "" ? given : env("TOSHI_SERVER");
+    if (server === undefined) {
+        throw new Error("toshi: no server: use the server option or set TOSHI_SERVER");
+    }
+    return server;
+}
+// resolveToken picks the token by the documented precedence: the source, the
+// option, the option's file, TOSHI_TOKEN, then TOSHI_TOKEN_FILE
+// (client.go:154-169). A token file is read here, so a missing or empty one
+// fails createToshiClient; the source reads it again when it changes. With a
+// transport of the caller's and no token anywhere, it returns nothing instead
+// of refusing.
+function resolveToken(options, optional) {
+    if (options.tokenSource !== undefined) {
+        return { tokenSource: options.tokenSource };
+    }
+    const token = options.token?.trim() ?? "";
+    if (token !== "") {
+        return { token };
+    }
+    if (options.tokenFile !== undefined && options.tokenFile !== "") {
+        return { tokenSource: fileTokenSource(options.tokenFile) };
+    }
+    const fromEnv = env("TOSHI_TOKEN")?.trim() ?? "";
+    if (fromEnv !== "") {
+        return { token: fromEnv };
+    }
+    const envFile = env("TOSHI_TOKEN_FILE");
+    if (envFile !== undefined) {
+        return { tokenSource: fileTokenSource(envFile) };
+    }
+    if (optional) {
+        return {};
+    }
+    throw new Error("toshi: no token: use the tokenSource, token or tokenFile option, or set TOSHI_TOKEN or TOSHI_TOKEN_FILE");
+}
+// fileTokenSource returns a source over a token file whose first read happens
+// now, so a missing or empty file still fails createToshiClient.
+function fileTokenSource(path) {
+    const file = new TokenFile(path);
+    return () => file.read();
+}
+// TokenFile is a token file read again when its modification time or size
+// changed since the last read (client.go:203-249).
+class TokenFile {
+    #path;
+    #token = "";
+    #modTimeNs = 0n;
+    #size = -1n;
+    constructor(path) {
+        this.#path = path;
+        this.read();
+    }
+    // read returns the file's token, reading the file again when it changed. It
+    // stats before reading, so a change made in between is read next time. After
+    // a failure the next call reads the file again.
+    read() {
+        let stats;
+        try {
+            stats = statSync(this.#path, { bigint: true });
+        }
+        catch (err) {
+            this.#size = -1n;
+            throw new Error(`toshi: read token file ${this.#path}: ${message(err)}`, { cause: err });
+        }
+        if (stats.mtimeNs === this.#modTimeNs && stats.size === this.#size) {
+            return this.#token;
+        }
+        try {
+            this.#token = readTokenFile(this.#path);
+        }
+        catch (err) {
+            this.#size = -1n;
+            throw err;
+        }
+        this.#modTimeNs = stats.mtimeNs;
+        this.#size = stats.size;
+        return this.#token;
+    }
+}
+function resolveCAFile(given) {
+    if (given !== undefined && given !== "") {
+        return given;
+    }
+    return env("TOSHI_CA_FILE");
+}
+function readTokenFile(path) {
+    let contents;
+    try {
+        contents = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        throw new Error(`toshi: read token file ${path}: ${message(err)}`, { cause: err });
+    }
+    const token = contents.trim();
+    if (token === "") {
+        throw new Error(`toshi: token file ${path} is empty`);
+    }
+    return token;
+}
+// The bundle is trusted besides the built-in roots, as the Go client trusts the
+// system pool besides the file (client.go:206-237).
+function caBundle(path) {
+    try {
+        return [...rootCertificates, readFileSync(path, "utf8")];
+    }
+    catch (err) {
+        throw new Error(`toshi: read CA file ${path}: ${message(err)}`, { cause: err });
+    }
+}
+function env(name) {
+    const value = process.env[name];
+    return value === undefined || value === "" ? undefined : value;
+}
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/node/index.d.ts

@@ -0,0 +1,3 @@
+export * from "../index.js";
+export { createToshiClient } from "./client.js";
+export type { NodeToshiOptions } from "./client.js";

package/dist/node/index.js

@@ -0,0 +1,4 @@
+// The Node entry: everything the root entry exports, with a createToshiClient
+// that also builds a connect-node transport and reads the TOSHI_* variables.
+export * from "../index.js";
+export { createToshiClient } from "./client.js";

package/dist/output.js

@@ -1,9 +1,10 @@
 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";
+import { timeoutError } from "./timeout.js";
 /** Starts an output watch at the request's offsets, counting the bytes it hands out (output.go:14-52). */
 export function openOutputWatch(service, retry, req, opts) {
-    const state = new WatchState("", opts?.signal);
+    const state = new WatchState("", opts?.signal, opts?.timeoutMs);
     const request = clone(WatchOutputRequestSchema, req);
     let stdout = req.stdoutOffset;
     let stderr = req.stderrOffset;
@@ -20,6 +21,7 @@ export function openOutputWatch(service, retry, req, opts) {
                     request.stderrOffset = stderr;
                     const stream = service.watchOutput(request, { signal: state.signal });
                     for await (const msg of stream) {
+                        state.markOpen();
                         attempt = 0;
                         if (msg.message.case === "end") {
                             // output.go:157-160: release the RPC before the caller sees the
@@ -45,6 +47,9 @@ export function openOutputWatch(service, retry, req, opts) {
                     if (state.closed) {
                         return;
                     }
+                    if (state.timedOut) {
+                        throw timeoutError(state.timeoutMs);
+                    }
                     cause = err;
                 }
                 attempt = await reconnect(retry, attempt, cause, state);

package/dist/paginate.d.ts

@@ -0,0 +1,36 @@
+import type { CallOptions } from "./client.js";
+/** A List request: it may name the page to read first. */
+export interface PageRequest {
+    /** From an earlier response's nextPageToken; empty for the first page. */
+    pageToken?: string | undefined;
+}
+/** A List response: it names the page after it. */
+export interface PageResponse {
+    /** Empty on the last page. */
+    readonly nextPageToken: string;
+}
+/**
+ * Yields every item of a page-at-a-time list call, one page after another.
+ *
+ * `call` is a service client's list method, and `items` picks a response's
+ * items:
+ *
+ * ```ts
+ * for await (const project of paginate(
+ *   {},
+ *   (req, opts) => toshi.project.listProjects(req, opts),
+ *   (resp) => resp.projects,
+ * )) {
+ *   console.log(project.name);
+ * }
+ * ```
+ *
+ * `paginate` sends a copy of `req`, so the caller's request keeps its fields
+ * and a `pageToken` it set resumes from that page. It reads each response's
+ * `nextPageToken` and sends it as the next request's `pageToken`. The
+ * iteration ends after a page whose `nextPageToken` is empty, when the loop
+ * breaks, or after an error, which the `for await` throws once and then ends.
+ * `opts` goes to every page, so `timeoutMs` bounds each page and not the
+ * whole iteration.
+ */
+export declare function paginate<Req extends PageRequest, Resp extends PageResponse, Item>(req: Req, call: (req: Req, opts?: CallOptions) => Promise<Resp>, items: (resp: Resp) => readonly Item[], opts?: CallOptions): AsyncGenerator<Item, void, undefined>;

package/dist/paginate.js

@@ -0,0 +1,37 @@
+/**
+ * Yields every item of a page-at-a-time list call, one page after another.
+ *
+ * `call` is a service client's list method, and `items` picks a response's
+ * items:
+ *
+ * ```ts
+ * for await (const project of paginate(
+ *   {},
+ *   (req, opts) => toshi.project.listProjects(req, opts),
+ *   (resp) => resp.projects,
+ * )) {
+ *   console.log(project.name);
+ * }
+ * ```
+ *
+ * `paginate` sends a copy of `req`, so the caller's request keeps its fields
+ * and a `pageToken` it set resumes from that page. It reads each response's
+ * `nextPageToken` and sends it as the next request's `pageToken`. The
+ * iteration ends after a page whose `nextPageToken` is empty, when the loop
+ * breaks, or after an error, which the `for await` throws once and then ends.
+ * `opts` goes to every page, so `timeoutMs` bounds each page and not the
+ * whole iteration.
+ */
+export async function* paginate(req, call, items, opts) {
+    const page = { ...req };
+    for (;;) {
+        const resp = await call(page, opts);
+        for (const item of items(resp)) {
+            yield item;
+        }
+        if (!resp.nextPageToken) {
+            return;
+        }
+        page.pageToken = resp.nextPageToken;
+    }
+}

package/dist/run.js

@@ -3,13 +3,14 @@ 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";
+import { runWithDeadline } from "./timeout.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 created = await runWithDeadline(opts, (callOpts) => service.createJob(req, callOpts));
     const job = created.job;
     if (job === undefined) {
         throw new Error("toshi: CreateJob answered no job");
@@ -21,7 +22,7 @@ export async function runJob(service, retry, req, opts) {
         project: req.project,
         environment: req.environment,
         id: job.id,
-    }), opts);
+    }), opts === undefined ? undefined : { ...opts, timeoutMs: undefined });
     return new LiveRun(job, watch);
 }
 /** A run whose create answered the job's output instead of a live stream. */

package/dist/stream.d.ts

@@ -12,10 +12,17 @@ export declare class WatchState {
     cursor: string;
     closed: boolean;
     readonly signal: AbortSignal;
+    /** The open timeout, when the caller set one. */
+    readonly timeoutMs: number | undefined;
+    /** Whether the open timeout fired rather than the caller's signal. */
+    timedOut: boolean;
     private readonly controller;
     private readonly caller;
+    private timer;
     private readonly onCallerAbort;
-    constructor(initialCursor: string, caller: AbortSignal | undefined);
+    constructor(initialCursor: string, caller: AbortSignal | undefined, timeoutMs?: number);
+    /** The first message arrived: the watch is open, and the timeout no longer applies. */
+    markOpen(): void;
     close(): void;
 }
 export {};

package/dist/stream.js

@@ -1,4 +1,5 @@
 import { abortReason, backoffDelay, isStreamLoss, sleep } from "./retry.js";
+import { timeoutError } from "./timeout.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
@@ -47,22 +48,29 @@ export async function reconnect(retry, attempt, cause, state) {
 }
 // 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).
+// error for the caller (watch.go:221-233, output.go:194-206). A timeout ends the
+// open only: the first message calls markOpen and clears it.
 export class WatchState {
     /** The caller-visible resume point; the output watch passes "" and ignores it. */
     cursor;
     closed = false;
     signal;
+    /** The open timeout, when the caller set one. */
+    timeoutMs;
+    /** Whether the open timeout fired rather than the caller's signal. */
+    timedOut = false;
     controller = new AbortController();
     caller;
+    timer;
     onCallerAbort = () => {
         if (this.caller !== undefined) {
             this.controller.abort(abortReason(this.caller));
         }
     };
-    constructor(initialCursor, caller) {
+    constructor(initialCursor, caller, timeoutMs) {
         this.cursor = initialCursor;
         this.caller = caller;
+        this.timeoutMs = timeoutMs;
         this.signal = this.controller.signal;
         if (caller !== undefined) {
             if (caller.aborted) {
@@ -72,12 +80,26 @@ export class WatchState {
                 caller.addEventListener("abort", this.onCallerAbort, { once: true });
             }
         }
+        if (timeoutMs !== undefined && !this.controller.signal.aborted) {
+            this.timer = setTimeout(() => {
+                this.timedOut = true;
+                this.controller.abort(timeoutError(timeoutMs));
+            }, timeoutMs);
+        }
+    }
+    /** The first message arrived: the watch is open, and the timeout no longer applies. */
+    markOpen() {
+        if (this.timer !== undefined) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
     }
     close() {
         if (this.closed) {
             return;
         }
         this.closed = true;
+        this.markOpen();
         this.caller?.removeEventListener("abort", this.onCallerAbort);
         this.controller.abort();
     }

package/dist/test/fake.d.ts

@@ -0,0 +1,88 @@
+import type { DescMethod, Message } from "@bufbuild/protobuf";
+import type { Interceptor, MethodImpl, Transport } from "@connectrpc/connect";
+import type { ToshiClient, ToshiOptions } from "../client.js";
+import { JobState, SandboxState } from "../gen/toshi/workspace/v1/workspace_pb.js";
+/** The token `client` sends. */
+export declare const testToken = "test-token";
+/** One call the fake received. */
+export interface Call {
+    /** The procedure the client called, for example `/toshi.workspace.v1.WorkloadService/CreateJob`. */
+    readonly procedure: string;
+    /** The message the client sent. A bidirectional stream's call is recorded when its first message arrives. */
+    readonly request: Message;
+    /** The request headers the client sent. */
+    readonly header: Headers;
+}
+/** A job of the fake, and what it answers about it. */
+export interface FakeJob {
+    /** Sets the state the fake reports for the job. */
+    state(state: JobState): FakeJob;
+    /** Sets the standard output WatchOutput streams. */
+    stdout(stdout: string): FakeJob;
+    /** Sets the standard error WatchOutput streams. */
+    stderr(stderr: string): FakeJob;
+    /** Ends the job with code: the state is ENDED and the end reason EXITED. */
+    exitCode(code: number): FakeJob;
+}
+/** A sandbox of the fake, and what it answers about it. */
+export interface FakeSandbox {
+    /** Sets the state the fake reports for the sandbox. */
+    state(state: SandboxState): FakeSandbox;
+}
+/** What Execute answers in one sandbox. */
+export interface FakeExecution {
+    /** Sets the standard output Execute streams. */
+    stdout(stdout: string): FakeExecution;
+    /** Sets the standard error Execute streams. */
+    stderr(stderr: string): FakeExecution;
+    /** Sets the exit code the execution ends with. */
+    exitCode(code: number): FakeExecution;
+}
+/** A fake Toshi, built with `createFake`. */
+export interface Fake {
+    /**
+     * Builds the in-memory transport the client uses, with the interceptors it
+     * is handed. Pass it as `createToshiClient({ transport: fake.transport })`.
+     */
+    readonly transport: (interceptors: Interceptor[]) => Transport;
+    /**
+     * Returns the job with this id. A job the fake has not created yet is what
+     * the next CreateJob answers with. It is running until the test sets its
+     * state or its exit code.
+     */
+    job(id: string): FakeJob;
+    /**
+     * Returns the sandbox with this id. A sandbox the fake has not created yet
+     * is what the next CreateSandbox answers with. It is running until the test
+     * sets its state.
+     */
+    sandbox(id: string): FakeSandbox;
+    /**
+     * Returns what Execute answers in a sandbox: an empty command that exits 0
+     * until the test sets its output or its exit code. The sandbox is registered
+     * too, so a later GetSandbox finds it.
+     */
+    execute(sandboxId: string): FakeExecution;
+    /**
+     * Answers a method instead of the state machine. The implementation is typed
+     * by the method, as `router.rpc` is: one call for unary, server-stream and
+     * bidirectional methods. A method from outside the Workspace API throws.
+     */
+    on<M extends DescMethod>(method: M, impl: MethodImpl<M>): Fake;
+    /** Returns every call the fake received, oldest first. */
+    calls(): readonly Call[];
+    /**
+     * Returns a client wired to the fake: the token `testToken`, the scope
+     * default/production, and a retry policy that answers at once. options
+     * change any of that, and are applied last.
+     */
+    client(options?: FakeOptions): ToshiClient;
+}
+/** The options `client` takes: ToshiOptions without the transport, which the fake supplies. */
+export type FakeOptions = Omit<ToshiOptions, "transport">;
+/** Creates a fake Toshi: an in-memory Workspace API and the state its calls answer from. */
+export declare function createFake(): Fake;
+/** The procedures the state machine answers. The coverage test holds it against the API. */
+export declare const answeredProcedures: readonly DescMethod[];
+/** The methods the state machine does not answer, for the coverage test's comparison. */
+export declare const hookOnlyProcedures: readonly DescMethod[];