@toshicloud/sdk 0.3.2 → 0.4.0

package/README.md

@@ -4,40 +4,26 @@ A TypeScript client for the Toshi Workspace API, `toshi.workspace.v1`,
 published as ES modules with type declarations.
 
 ```sh
-npm install @toshicloud/sdk @connectrpc/connect @connectrpc/connect-node
+npm install @toshicloud/sdk @connectrpc/connect
 ```
 
+The browser entry needs a transport such as `@connectrpc/connect-web`; the
+Node entry needs `@connectrpc/connect-node`. Both are peer dependencies, so
+install the ones your application uses.
+
 Versions up to 0.1.2 were published as `@toshicloud/toshi-ts`.
 
 ## Using the client
 
-`createToshiClient` takes one set of options. The transport belongs to
-the caller: the client hands its interceptors to the `transport`
-function, and that function builds a transport with them. Every call then
-gets the same token, scope and retries: the helpers below and the
-generated clients alike.
-
-In Node, with `@connectrpc/connect-node`:
+In Node, `@toshicloud/sdk/node` builds the transport and fills the server
+and the token from the environment:
 
 <!-- examples/quick-start.ts -->
 
 ```ts
-import { readFileSync } from "node:fs";
-import { createConnectTransport } from "@connectrpc/connect-node";
-import { createToshiClient } from "@toshicloud/sdk";
+import { createToshiClient } from "@toshicloud/sdk/node";
 
-const toshi = createToshiClient({
-  transport: (interceptors) =>
-    createConnectTransport({
-      baseUrl: "https://toshi.example.com",
-      httpVersion: "2",
-      interceptors,
-      // Only for a server whose certificate a private CA signed.
-      nodeOptions: { ca: readFileSync("ca.pem") },
-    }),
-  token: process.env.TOSHI_TOKEN,
-  project: "default",
-});
+const toshi = createToshiClient({ project: "default" });
 
 const { projects } = await toshi.project.listProjects({});
 console.log(projects.length);
@@ -62,14 +48,21 @@ export const toshi = createToshiClient({
 });
 ```
 
-To add interceptors of your own, put them before the client's:
-`interceptors: [...mine, ...interceptors]`.
+Interceptors of your own go before the client's. The Node entry takes
+`interceptors`; with a transport of your own, put them first:
+`interceptors: [...mine, ...interceptors]`. Each unary call enters them
+once, with its retries inside, and they never see the Authorization
+header: the client sets it on a copy of the request below them.
 
-The package reads no environment variable and no file. The token, the
-server and any CA come from the caller.
+The browser entry reads no environment variable and no file. The Node
+entry reads `TOSHI_SERVER`, `TOSHI_TOKEN`, `TOSHI_TOKEN_FILE` and
+`TOSHI_CA_FILE`; see Node options.
 
 ### Options
 
+- `tokenSource`: a function that gives each request attempt its token, so a
+  refreshed token is used without a new client; it wins over `token`. See
+  Tokens that change.
 - `token`: sent as `Authorization: Bearer <token>` on every call.
 - `project`, `environment`: fill the request's `project` and
   `environment` fields when they are empty. A value in the request wins.
@@ -77,6 +70,65 @@ server and any CA come from the caller.
 - `retry`: `{ maxAttempts, initialBackoffMs, maxBackoffMs }`, by default
   5, 200 ms and 10 s, with full jitter. `retry: false` turns off retries
   and watch reconnects.
+- `defaultTimeoutMs`: bounds each unary call except the Wait calls,
+  which their request's timeout bounds; streams ignore it.
+
+A call may set `timeoutMs` instead: it bounds the whole call, retries
+included, and on a watch it bounds the open. It composes with `signal`.
+
+### Node options
+
+`@toshicloud/sdk/node` builds a connect-node transport over HTTP/2 and
+fills what is missing from the environment:
+
+- `server`, else `TOSHI_SERVER`: the control plane's URL. Without either,
+  the client refuses to start.
+- `tokenSource`, `token`, `tokenFile`, `TOSHI_TOKEN`, `TOSHI_TOKEN_FILE`, in
+  that order. A token file is trimmed, and an empty file is an error.
+- `caFile`, else `TOSHI_CA_FILE`: a PEM bundle trusted besides Node's
+  built-in roots.
+- `userAgent`: put in front of the User-Agent, for example "myapp/1.2".
+- `interceptors`: run before the client's own, in the order given.
+- `defaultTimeoutMs`: bounds each unary call except the Wait calls,
+  which their request's timeout bounds; streams ignore it.
+- `transport`: a transport of your own; then `server` and `caFile` are not
+  required.
+
+Every request carries `User-Agent: toshi-ts/<version> (node/<node
+version>)`, with `userAgent` and one space in front when it is set. The
+root entry sends no User-Agent: browsers own it.
+
+### Tokens that change
+
+`tokenSource` gives the client a function it calls for the token of every
+request attempt, so a token that is refreshed, for example from a secret
+manager, is used without a new client. It wins over every other token
+option. The client asks it once per attempt, a retry included, and may
+ask it concurrently, so it must be fast: keep the token somewhere and
+refresh it outside the call. A source that throws, or that answers an
+empty token, fails the call with `UNAUTHENTICATED`, with the error as the
+cause, and the call is not retried.
+
+<!-- examples/token-source.ts -->
+
+```ts
+// A token a refresh loop replaces; the client asks for it on every call.
+let token = "first-token";
+
+export const toshi = createToshiClient({
+  project: "default",
+  tokenSource: () => token,
+});
+
+export function rotate(next: string): void {
+  token = next;
+}
+```
+
+A token file, from `tokenFile` or `TOSHI_TOKEN_FILE`, is read again
+before a request when its modification time or size has changed, so a
+rotated token, such as a Kubernetes projected service account token, is
+picked up without a new client.
 
 ### The client's shape
 
@@ -102,6 +154,43 @@ const { job } = await toshi.workload.jobs.get({ id: jobs[0].id });
 console.log(job?.id);
 ```
 
+### Lists
+
+`workload.jobs.all`, `workload.sandboxes.all`, `workload.services.all`,
+`workload.services.allRuns` and `workload.allEvents` take the request their
+`list` method takes and yield every item, one page after another. Each
+response's `nextPageToken` becomes the next request's `pageToken`, and a
+`pageToken` in the request resumes from that page. A service with no
+`all` method is one `paginate` call away: it takes the list call and a
+function that picks a response's items.
+
+<!-- examples/lists.ts -->
+
+```ts
+import { paginate } from "@toshicloud/sdk";
+
+import { toshi } from "./client.js";
+
+// Every job that matches the request, one page after another.
+for await (const job of toshi.workload.jobs.all({ pageSize: 10 })) {
+  console.log(job.id);
+}
+
+// A service with no all() method: paginate takes its list call and items.
+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 the request, so the caller's request keeps its
+fields. Every page is a call of its own, so `opts` goes to each one, and
+`timeoutMs` bounds a page and not the whole iteration. An error throws once
+and ends the iteration; leaving the loop sends no further request.
+
 ### Retries
 
 The client retries a read, and a write that carries a request key, when
@@ -216,6 +305,35 @@ await run.wait(); // rejects with JobExitError on a non-zero exit
 Stopping the loop stops only the output stream: the job keeps running,
 and `workload.jobs.cancel` ends it.
 
+## Testing with `@toshicloud/sdk/test`
+
+`createFake()` serves the whole Workspace API in memory: no server, no port,
+nothing to close, and no Node module, so it runs in the same runtimes as the
+client. `fake.client()` returns a `ToshiClient` wired to it, with the token
+`test-token` and the scope `default`/`production`, which is enough to drive
+`run`, the watchers and the generated clients from a test.
+
+<!-- examples/testing.ts -->
+
+```ts
+import { createFake } from "@toshicloud/sdk/test";
+
+const fake = createFake();
+fake.job("job-1").stdout("deployed\n").exitCode(0);
+
+const toshi = fake.client();
+const run = await toshi.run({ spec: { command: { argv: ["./deploy.sh"] } } });
+for await (const chunk of run) {
+  process[chunk.stream].write(chunk.data);
+}
+await run.wait();
+```
+
+`fake.on(method, impl)` replaces the state machine for one method with a hook
+typed by that method: one call for unary, server-stream and bidirectional
+methods alike. `fake.calls()` returns every call the fake received, oldest
+first, with the procedure, the request and the headers.
+
 ## Generated code
 
 `src/gen/toshi/workspace/v1/` is generated by

package/dist/client.d.ts

@@ -18,21 +18,32 @@ import { WorkspaceService } from "./gen/toshi/workspace/v1/workspace_service_pb.
 import { CancelJobRequestSchema, CreateJobRequestSchema, CreateSandboxRequestSchema, CreateServiceRequestSchema, DeleteJobRequestSchema, DeleteSandboxRequestSchema, DeleteServiceRequestSchema, GetJobRequestSchema, GetSandboxRequestSchema, GetServiceRequestSchema, ListJobsRequestSchema, ListSandboxesRequestSchema, ListServicesRequestSchema, UpdateJobRequestSchema, UpdateSandboxRequestSchema, UpdateServiceRequestSchema, WaitJobRequestSchema, WaitSandboxRequestSchema, WaitServiceRequestSchema, WatchJobsRequestSchema, WatchSandboxesRequestSchema, WatchServicesRequestSchema } from "./gen/toshi/workspace/v1/workloads_pb.js";
 import type { CancelJobResponse, CreateJobResponse, CreateSandboxResponse, CreateServiceResponse, DeleteJobResponse, DeleteSandboxResponse, DeleteServiceResponse, GetJobResponse, GetSandboxResponse, GetServiceResponse, ListJobsResponse, ListSandboxesResponse, ListServicesResponse, UpdateJobResponse, UpdateSandboxResponse, UpdateServiceResponse, WaitJobResponse, WaitSandboxResponse, WaitServiceResponse, WatchJobsResponse, WatchSandboxesResponse, WatchServicesResponse } from "./gen/toshi/workspace/v1/workloads_pb.js";
 import { ExecuteStartSchema, GetOperationRequestSchema, HoldServiceRequestSchema, ListEventsRequestSchema, ListServiceRunsRequestSchema, ReleaseServiceRequestSchema, SetServiceModeRequestSchema, StartServiceRequestSchema, StopServiceRequestSchema, WaitOperationRequestSchema, WakeServiceRequestSchema, WatchEventsRequestSchema, WatchOutputRequestSchema } from "./gen/toshi/workspace/v1/workspace_pb.js";
-import type { GetOperationResponse, HoldServiceResponse, Job, ListEventsResponse, ListServiceRunsResponse, Operation, ReleaseServiceResponse, Sandbox, Service, SetServiceModeResponse, StartServiceResponse, StopServiceResponse, WakeServiceResponse, WatchEventsResponse, WatchOutputResponse } from "./gen/toshi/workspace/v1/workspace_pb.js";
+import type { Event, GetOperationResponse, HoldServiceResponse, Job, ListEventsResponse, ListServiceRunsResponse, Operation, ReleaseServiceResponse, Sandbox, Service, ServiceRun, SetServiceModeResponse, StartServiceResponse, StopServiceResponse, WakeServiceResponse, WatchEventsResponse, WatchOutputResponse } from "./gen/toshi/workspace/v1/workspace_pb.js";
 import type { RetryPolicy } from "./retry.js";
 /** How the client is configured; the caller builds the transport. */
 export interface ToshiOptions {
     /** Builds the caller's transport (connect-node or connect-web) with the client's interceptors. */
     transport: (interceptors: Interceptor[]) => Transport;
     token?: string;
+    /**
+     * Gives each request attempt its token, so a refreshed token is used without
+     * a new client; it wins over `token` and a retry asks it again. A source that
+     * throws or answers an empty token ends the call with Code.Unauthenticated,
+     * with its error as the cause, and the call is not retried.
+     */
+    tokenSource?: (signal: AbortSignal | undefined) => string | Promise<string>;
     project?: string;
     environment?: string;
     /** false turns off retries and watch reconnects. */
     retry?: Partial<RetryPolicy> | false;
+    /** Bounds each unary call except the Wait calls, which their request's timeout bounds; streams ignore it. */
+    defaultTimeoutMs?: number;
 }
 /** Per-call options. */
 export interface CallOptions {
     signal?: AbortSignal;
+    /** Bounds the whole call, retries included; on a watch, the open. */
+    timeoutMs?: number;
 }
 /** One client per Workspace API service, plus the helpers that live on top of them. */
 export interface ToshiClient {
@@ -63,6 +74,8 @@ export interface WorkloadClient {
     waitOperation(req: MessageInitShape<typeof WaitOperationRequestSchema>, opts?: CallOptions): Promise<Operation>;
     /** Lists the events after a cursor, a page at a time; `watchEvents` is the live form. */
     listEvents(req: MessageInitShape<typeof ListEventsRequestSchema>, opts?: CallOptions): Promise<ListEventsResponse>;
+    /** Yields every event listEvents lists, following the page token from one page to the next. */
+    allEvents(req: MessageInitShape<typeof ListEventsRequestSchema>, opts?: CallOptions): AsyncIterable<Event>;
     watchEvents(req: MessageInitShape<typeof WatchEventsRequestSchema>, opts?: CallOptions): Promise<EventWatch>;
     /** Returns one operation: the id a long call hands back, asked for again. */
     getOperation(req: MessageInitShape<typeof GetOperationRequestSchema>, opts?: CallOptions): Promise<GetOperationResponse>;
@@ -72,6 +85,8 @@ export interface JobsClient {
     create(req: MessageInitShape<typeof CreateJobRequestSchema>, opts?: CallOptions): Promise<CreateJobResponse>;
     get(req: MessageInitShape<typeof GetJobRequestSchema>, opts?: CallOptions): Promise<GetJobResponse>;
     list(req: MessageInitShape<typeof ListJobsRequestSchema>, opts?: CallOptions): Promise<ListJobsResponse>;
+    /** Yields every job that matches every filter that is set, following the page token from one page to the next. */
+    all(req: MessageInitShape<typeof ListJobsRequestSchema>, opts?: CallOptions): AsyncIterable<Job>;
     update(req: MessageInitShape<typeof UpdateJobRequestSchema>, opts?: CallOptions): Promise<UpdateJobResponse>;
     delete(req: MessageInitShape<typeof DeleteJobRequestSchema>, opts?: CallOptions): Promise<DeleteJobResponse>;
     cancel(req: MessageInitShape<typeof CancelJobRequestSchema>, opts?: CallOptions): Promise<CancelJobResponse>;
@@ -84,6 +99,8 @@ export interface SandboxesClient {
     create(req: MessageInitShape<typeof CreateSandboxRequestSchema>, opts?: CallOptions): Promise<CreateSandboxResponse>;
     get(req: MessageInitShape<typeof GetSandboxRequestSchema>, opts?: CallOptions): Promise<GetSandboxResponse>;
     list(req: MessageInitShape<typeof ListSandboxesRequestSchema>, opts?: CallOptions): Promise<ListSandboxesResponse>;
+    /** Yields every sandbox that matches every filter that is set, following the page token from one page to the next. */
+    all(req: MessageInitShape<typeof ListSandboxesRequestSchema>, opts?: CallOptions): AsyncIterable<Sandbox>;
     update(req: MessageInitShape<typeof UpdateSandboxRequestSchema>, opts?: CallOptions): Promise<UpdateSandboxResponse>;
     delete(req: MessageInitShape<typeof DeleteSandboxRequestSchema>, opts?: CallOptions): Promise<DeleteSandboxResponse>;
     wait(req: MessageInitShape<typeof WaitSandboxRequestSchema>, opts?: CallOptions): Promise<WaitSandboxResponse>;
@@ -95,6 +112,8 @@ export interface ServicesClient {
     create(req: MessageInitShape<typeof CreateServiceRequestSchema>, opts?: CallOptions): Promise<CreateServiceResponse>;
     get(req: MessageInitShape<typeof GetServiceRequestSchema>, opts?: CallOptions): Promise<GetServiceResponse>;
     list(req: MessageInitShape<typeof ListServicesRequestSchema>, opts?: CallOptions): Promise<ListServicesResponse>;
+    /** Yields every service that matches every filter that is set, following the page token from one page to the next. */
+    all(req: MessageInitShape<typeof ListServicesRequestSchema>, opts?: CallOptions): AsyncIterable<Service>;
     update(req: MessageInitShape<typeof UpdateServiceRequestSchema>, opts?: CallOptions): Promise<UpdateServiceResponse>;
     delete(req: MessageInitShape<typeof DeleteServiceRequestSchema>, opts?: CallOptions): Promise<DeleteServiceResponse>;
     wait(req: MessageInitShape<typeof WaitServiceRequestSchema>, opts?: CallOptions): Promise<WaitServiceResponse>;
@@ -106,6 +125,8 @@ export interface ServicesClient {
     wake(req: MessageInitShape<typeof WakeServiceRequestSchema>, opts?: CallOptions): Promise<WakeServiceResponse>;
     hold(req: MessageInitShape<typeof HoldServiceRequestSchema>, opts?: CallOptions): Promise<HoldServiceResponse>;
     listRuns(req: MessageInitShape<typeof ListServiceRunsRequestSchema>, opts?: CallOptions): Promise<ListServiceRunsResponse>;
+    /** Yields every run listRuns returns, the newest first, following the page token from one page to the next. */
+    allRuns(req: MessageInitShape<typeof ListServiceRunsRequestSchema>, opts?: CallOptions): AsyncIterable<ServiceRun>;
 }
 /** A live stream of a job's changes. */
 export interface JobWatch extends AsyncIterable<WatchJobsResponse> {
@@ -160,9 +181,9 @@ export interface JobRun extends AsyncIterable<OutputChunk> {
     wait(): Promise<void>;
 }
 /**
- * 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.
+ * Creates the client: one normalized retry setting, the scope, key, retry and
+ * auth interceptors (scope outermost, auth innermost, so no interceptor sees
+ * the Authorization header), one transport for every client and helper.
  *
  * Since 0.2.0 the workload calls are grouped by the type they name under
  * `workload`; every other service, WorkspaceService's included, is handed out

package/dist/client.js

@@ -19,15 +19,17 @@ import { WorkspaceService } from "./gen/toshi/workspace/v1/workspace_service_pb.
 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, GetOperationRequestSchema, HoldServiceRequestSchema, ListEventsRequestSchema, ListServiceRunsRequestSchema, ReleaseServiceRequestSchema, SetServiceModeRequestSchema, StartServiceRequestSchema, StopServiceRequestSchema, WaitOperationRequestSchema, WakeServiceRequestSchema, WatchEventsRequestSchema, WatchOutputRequestSchema, } from "./gen/toshi/workspace/v1/workspace_pb.js";
 import { openOutputWatch } from "./output.js";
+import { paginate } from "./paginate.js";
 import { authInterceptor, keyInterceptor, retryInterceptor, scopeInterceptor } from "./interceptors.js";
 import { normalizeRetry } from "./retry.js";
+import { withDefaultUnaryTimeout } from "./timeout.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.
+ * Creates the client: one normalized retry setting, the scope, key, retry and
+ * auth interceptors (scope outermost, auth innermost, so no interceptor sees
+ * the Authorization header), one transport for every client and helper.
  *
  * Since 0.2.0 the workload calls are grouped by the type they name under
  * `workload`; every other service, WorkspaceService's included, is handed out
@@ -36,12 +38,12 @@ import { waitJob, waitOperation, waitSandbox, waitService } from "./wait.js";
 export function createToshiClient(options) {
     const retry = normalizeRetry(options.retry);
     const interceptors = [
-        authInterceptor(options.token ?? ""),
         scopeInterceptor(options.project ?? "", options.environment ?? ""),
         keyInterceptor(),
         retryInterceptor(retry),
+        authInterceptor(options.token ?? "", options.tokenSource),
     ];
-    const transport = options.transport(interceptors);
+    const transport = withDefaultUnaryTimeout(options.transport(interceptors), options.defaultTimeoutMs);
     const workloadService = createClient(WorkloadService, transport);
     return {
         project: createClient(ProjectService, transport),
@@ -58,6 +60,7 @@ export function createToshiClient(options) {
                 create: (req, opts) => workloadService.createJob(req, opts),
                 get: (req, opts) => workloadService.getJob(req, opts),
                 list: (req, opts) => workloadService.listJobs(req, opts),
+                all: (req, opts) => paginate(req, workloadService.listJobs, (resp) => resp.jobs, opts),
                 update: (req, opts) => workloadService.updateJob(req, opts),
                 delete: (req, opts) => workloadService.deleteJob(req, opts),
                 cancel: (req, opts) => workloadService.cancelJob(req, opts),
@@ -69,6 +72,7 @@ export function createToshiClient(options) {
                 create: (req, opts) => workloadService.createSandbox(req, opts),
                 get: (req, opts) => workloadService.getSandbox(req, opts),
                 list: (req, opts) => workloadService.listSandboxes(req, opts),
+                all: (req, opts) => paginate(req, workloadService.listSandboxes, (resp) => resp.sandboxes, opts),
                 update: (req, opts) => workloadService.updateSandbox(req, opts),
                 delete: (req, opts) => workloadService.deleteSandbox(req, opts),
                 wait: (req, opts) => waitSandbox(workloadService, create(WaitSandboxRequestSchema, req), opts),
@@ -79,6 +83,7 @@ export function createToshiClient(options) {
                 create: (req, opts) => workloadService.createService(req, opts),
                 get: (req, opts) => workloadService.getService(req, opts),
                 list: (req, opts) => workloadService.listServices(req, opts),
+                all: (req, opts) => paginate(req, workloadService.listServices, (resp) => resp.services, opts),
                 update: (req, opts) => workloadService.updateService(req, opts),
                 delete: (req, opts) => workloadService.deleteService(req, opts),
                 wait: (req, opts) => waitService(workloadService, create(WaitServiceRequestSchema, req), opts),
@@ -90,9 +95,11 @@ export function createToshiClient(options) {
                 wake: (req, opts) => workloadService.wakeService(req, opts),
                 hold: (req, opts) => workloadService.holdService(req, opts),
                 listRuns: (req, opts) => workloadService.listServiceRuns(req, opts),
+                allRuns: (req, opts) => paginate(req, workloadService.listServiceRuns, (resp) => resp.runs, opts),
             },
             waitOperation: (req, opts) => waitOperation(workloadService, create(WaitOperationRequestSchema, req), opts),
             listEvents: (req, opts) => workloadService.listEvents(req, opts),
+            allEvents: (req, opts) => paginate(req, workloadService.listEvents, (resp) => resp.events, opts),
             watchEvents: (req, opts) => openEventWatch(workloadService, retry, create(WatchEventsRequestSchema, req), opts),
             getOperation: (req, opts) => workloadService.getOperation(req, opts),
         },

package/dist/execute.js

@@ -3,6 +3,7 @@ import { Code, ConnectError } from "@connectrpc/connect";
 import { createWritableIterable } from "@connectrpc/connect/protocol";
 import { ExitError, StreamLostError } from "./errors.js";
 import { isStreamLoss } from "./retry.js";
+import { startDeadline, timeoutError } from "./timeout.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;
@@ -35,13 +36,24 @@ export async function executeCommand(service, start, opts) {
         }
         owner.process.cancel();
     };
+    // A timeout bounds the handshake only; the process outlives it.
+    const deadline = startDeadline(opts?.timeoutMs, opts?.signal);
+    const onDeadline = () => {
+        if (owner.process === undefined) {
+            abort.abort(deadline?.signal.reason);
+        }
+    };
     // A signal that is already aborted starts nothing.
     if (signal?.aborted === true) {
+        deadline?.clear();
         throw cancelledError();
     }
     signal?.addEventListener("abort", onAbort, { once: true });
+    deadline?.signal.addEventListener("abort", onDeadline, { once: true });
     const finishHandshake = () => {
         signal?.removeEventListener("abort", onAbort);
+        deadline?.signal.removeEventListener("abort", onDeadline);
+        deadline?.clear();
     };
     const responses = service.execute(input, { signal: abort.signal });
     const responseIterator = responses[Symbol.asyncIterator]();
@@ -73,6 +85,9 @@ export async function executeCommand(service, start, opts) {
         if (signal !== undefined && signal.aborted) {
             throw cancelledError();
         }
+        if (deadline?.timedOut === true) {
+            throw timeoutError(opts?.timeoutMs);
+        }
         throw beforeStarted(err, readRequestKey(startMessage));
     }
     const message = first.done === true ? undefined : first.value.message;

package/dist/index.d.ts

@@ -16,7 +16,10 @@ 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/workspace_service_pb.js";
 export { createToshiClient } from "./client.js";
+export { paginate } from "./paginate.js";
 export { ExitError, JobExitError, StreamLostError } from "./errors.js";
 export { defaultRetryPolicy } from "./retry.js";
+export { VERSION } from "./version.js";
+export type { PageRequest, PageResponse } from "./paginate.js";
 export type { RetryPolicy } from "./retry.js";
 export type { CallOptions, EventWatch, JobRun, JobWatch, JobsClient, OutputChunk, OutputWatch, Process, SandboxWatch, SandboxesClient, ServiceWatch, ServicesClient, ToshiClient, ToshiOptions, WorkloadClient, } from "./client.js";

package/dist/index.js

@@ -17,5 +17,7 @@ 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/workspace_service_pb.js";
 export { createToshiClient } from "./client.js";
+export { paginate } from "./paginate.js";
 export { ExitError, JobExitError, StreamLostError } from "./errors.js";
 export { defaultRetryPolicy } from "./retry.js";
+export { VERSION } from "./version.js";

package/dist/interceptors.d.ts

@@ -1,7 +1,16 @@
 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). */

package/dist/interceptors.js

@@ -1,15 +1,51 @@
 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) {
+/**
+ * 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 === "") {

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;