@toshicloud/sdk 0.3.2 → 0.5.0

package/dist/index.js

@@ -15,7 +15,11 @@ export * from "./gen/toshi/workspace/v1/hostjobs_pb.js";
 export * from "./gen/toshi/workspace/v1/hosts_pb.js";
 export * from "./gen/toshi/workspace/v1/storage_providers_pb.js";
 export * from "./gen/toshi/workspace/v1/tokens_pb.js";
+export * from "./gen/toshi/workspace/v1/products_pb.js";
+export * from "./gen/toshi/workspace/v1/discovery_pb.js";
 export * from "./gen/toshi/workspace/v1/workspace_service_pb.js";
 export { createToshiClient } from "./client.js";
-export { ExitError, JobExitError, StreamLostError } from "./errors.js";
+export { paginate } from "./paginate.js";
+export { ExitError, JobExitError, ProductError, ProductReason, StreamLostError, isProductError } from "./errors.js";
 export { defaultRetryPolicy } from "./retry.js";
+export { VERSION } from "./version.js";

package/dist/interceptors.d.ts

@@ -1,10 +1,25 @@
 import type { Interceptor } from "@connectrpc/connect";
 import type { RetrySetting } from "./retry.js";
-/** Sends `Authorization: Bearer <token>` on every call and stream; never Toshi-Tenant (intercept.go:13-36). */
-export declare function authInterceptor(token: string): Interceptor;
+/** Gives one request attempt its token; the signal is the call's. */
+export type TokenSource = (signal: AbortSignal | undefined) => string | Promise<string>;
+/**
+ * Sends `Authorization: Bearer <token>` on every call and stream, on a copy of
+ * the request: it is the innermost interceptor, so none outside it sees the
+ * header (intercept.go:13-31). Never Toshi-Tenant.
+ *
+ * With a source, the token is asked for on every attempt the innermost
+ * interceptor runs for, so a retry asks again (client.go:154-169).
+ */
+export declare function authInterceptor(token: string, source?: TokenSource): Interceptor;
 /** Fills an empty project and environment from the options; caller values win (intercept.go:38-129). */
 export declare function scopeInterceptor(project: string, environment: string): Interceptor;
 /** Puts a request key on keyed procedures and on Execute's start (retry.go:110-116, 202-231). */
 export declare function keyInterceptor(): Interceptor;
 /** Retries a unary read or keyed write after a transport loss, with full jitter (retry.go:98-186). */
 export declare function retryInterceptor(retry: RetrySetting): Interceptor;
+/**
+ * Throws a ProductError in place of a product's refusal, on a unary call and
+ * on a stream's messages. It is the outermost interceptor, so the retry and
+ * the helpers inside see the ConnectError they always did.
+ */
+export declare function productInterceptor(): Interceptor;

package/dist/interceptors.js

@@ -1,15 +1,52 @@
 import { ScalarType } from "@bufbuild/protobuf";
+import { Code, ConnectError } from "@connectrpc/connect";
 import { backoffDelay, isTransportLoss, newRequestKey, procedurePath, retryClassFor, sleep, } from "./retry.js";
-/** Sends `Authorization: Bearer <token>` on every call and stream; never Toshi-Tenant (intercept.go:13-36). */
-export function authInterceptor(token) {
+import { asProductError } from "./errors.js";
+/**
+ * Sends `Authorization: Bearer <token>` on every call and stream, on a copy of
+ * the request: it is the innermost interceptor, so none outside it sees the
+ * header (intercept.go:13-31). Never Toshi-Tenant.
+ *
+ * With a source, the token is asked for on every attempt the innermost
+ * interceptor runs for, so a retry asks again (client.go:154-169).
+ */
+export function authInterceptor(token, source) {
+    if (source !== undefined) {
+        return (next) => async (req) => {
+            const value = await sourceToken(source, req.signal);
+            const header = new Headers(req.header);
+            header.set("Authorization", `Bearer ${value}`);
+            return next({ ...req, header });
+        };
+    }
     if (token === "") {
         return (next) => next;
     }
     return (next) => async (req) => {
-        req.header.set("Authorization", `Bearer ${token}`);
-        return next(req);
+        const header = new Headers(req.header);
+        header.set("Authorization", `Bearer ${token}`);
+        return next({ ...req, header });
     };
 }
+// Asks the source for this attempt's token, trimmed; a source that throws or
+// answers empty ends the call as UNAUTHENTICATED with the source's error as the
+// cause, which is not a transport loss and so is not retried (client.go:186-201).
+async function sourceToken(source, signal) {
+    let token;
+    try {
+        token = await source(signal);
+    }
+    catch (err) {
+        throw new ConnectError(`toshi: token source: ${message(err)}`, Code.Unauthenticated, undefined, undefined, err);
+    }
+    if (token.trim() === "") {
+        throw new ConnectError("toshi: token source: empty token", Code.Unauthenticated);
+    }
+    return token.trim();
+}
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 /** Fills an empty project and environment from the options; caller values win (intercept.go:38-129). */
 export function scopeInterceptor(project, environment) {
     if (project === "" && environment === "") {
@@ -157,3 +194,31 @@ function isShared(msg, desc) {
         field.scalar === ScalarType.BOOL &&
         msg[field.localName] === true);
 }
+/**
+ * Throws a ProductError in place of a product's refusal, on a unary call and
+ * on a stream's messages. It is the outermost interceptor, so the retry and
+ * the helpers inside see the ConnectError they always did.
+ */
+export function productInterceptor() {
+    return (next) => async (req) => {
+        let res;
+        try {
+            res = await next(req);
+        }
+        catch (err) {
+            throw asProductError(err);
+        }
+        if (!res.stream) {
+            return res;
+        }
+        return { ...res, message: productStream(res.message) };
+    };
+}
+async function* productStream(messages) {
+    try {
+        yield* messages;
+    }
+    catch (err) {
+        throw asProductError(err);
+    }
+}

package/dist/node/client.d.ts

@@ -0,0 +1,35 @@
+import type { Interceptor, Transport } from "@connectrpc/connect";
+import type { ToshiClient, ToshiOptions } from "../client.js";
+/** Options for the Node entry: the root options, a built transport, and env defaults. */
+export interface NodeToshiOptions extends Omit<ToshiOptions, "transport"> {
+    /** A transport of your own; without one, connect-node over HTTP/2 to `server` is built. */
+    transport?: (interceptors: Interceptor[]) => Transport;
+    /** The control plane's base URL; defaults to TOSHI_SERVER. */
+    server?: string;
+    /**
+     * A file holding the token, trimmed; an empty file is an error. It is read
+     * again before a request when its modification time or size changed.
+     */
+    tokenFile?: string;
+    /** A PEM bundle trusted besides Node's built-in roots; defaults to TOSHI_CA_FILE. */
+    caFile?: string;
+    /** Put in front of the User-Agent, for example "myapp/1.2"; empty adds nothing. */
+    userAgent?: string;
+    /** Run before the client's scope, key, retry and auth interceptors, in this order. */
+    interceptors?: Interceptor[];
+    /** Bounds each unary call except the Wait calls, which their request's timeout bounds; streams ignore it. */
+    defaultTimeoutMs?: number;
+}
+/**
+ * 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 declare function createToshiClient(options?: NodeToshiOptions): ToshiClient;
+/** The User-Agent every Node request carries, with product in front when set. */
+export declare function userAgent(product: string): string;

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/retry.js

@@ -159,6 +159,10 @@ const procedureRetryClass = {
     "/toshi.workspace.v1.StorageProviderService/CreateStorageProvider": "none",
     "/toshi.workspace.v1.StorageProviderService/CheckStorageProvider": "none",
     "/toshi.workspace.v1.StorageProviderService/DeleteStorageProvider": "none",
+    "/toshi.workspace.v1.ProductService/ListProducts": "read",
+    "/toshi.workspace.v1.ProductService/UpdateProduct": "none",
+    "/toshi.workspace.v1.ProductService/RemoveProduct": "none",
+    "/toshi.workspace.v1.DiscoveryService/Discover": "read",
 };
 /** The retry class of a generated procedure path; an unknown path is "none". */
 export function retryClassFor(procedure) {

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();
     }