@toshicloud/sdk 0.3.2 → 0.5.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,14 +70,73 @@ 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
 
 The client has one field per Workspace API service: `project`, `secret`,
 `webhook`, `display`, `channel`, `recording`, `volume`, `artifact`,
 `artifactUpload`, `workspace`, `hostJob`, `host`, `token`, `auditEvent`,
-`filler` and `storageProvider`, each holding that service's generated
-client.
+`filler`, `storageProvider`, `product` and `discovery`, each holding that
+service's generated client.
 `workload` holds `WorkloadService`'s calls, grouped by the type they
 name: `workload.jobs`, `workload.sandboxes` and `workload.services`, one
 method for each call (`create`, `get`, `list`, `update`, `delete`,
@@ -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,13 +305,83 @@ 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.
 
+## Products that are off
+
+A call for a product that is off for the workspace, or that turns on an
+outside product without accepting the access it asks for, rejects with a
+`ProductError`, `wait`, the watches and `execute` included.
+`isProductError(err)` tells it apart. It is still a `ConnectError` with the
+same `code`, and it has the product's ID (`product`), the `reason`
+(`ProductReason.NotInstalled`, `Disabled`, `NotEntitled`, `TurnedOff` or
+`AccessNotAccepted`), the setting that turns the product on (`feature`,
+such as `runners.enabled`), how far a product the deployment disables has
+wound down (`state`) and, for `AccessNotAccepted`, the access to accept
+(`access`).
+
+<!-- examples/product-error.ts -->
+
+```ts
+
+// Turning an outside product on installs it, and the API asks the caller to
+// accept the access it wants first.
+const enable = { id: "acme_ci", enabled: true, acceptedAccess: [] as string[] };
+try {
+  try {
+    await toshi.product.updateProduct(enable);
+  } catch (err) {
+    if (!isProductError(err) || err.reason !== ProductReason.AccessNotAccepted) {
+      throw err;
+    }
+    console.log(err.product, err.reason, err.access);
+    // Accept exactly the access the product asks for.
+    await toshi.product.updateProduct({ ...enable, acceptedAccess: err.access });
+  }
+} catch (err) {
+  if (!isProductError(err)) {
+    throw err;
+  }
+  // Off for the workspace: say which product and why.
+  console.log(err.product, err.reason, err.feature);
+}
+```
+
+## 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
 [`protoc-gen-es`](https://github.com/bufbuild/protobuf-es) from the protos
 in `proto/toshi/workspace/v1` of the
 [toshi-api](https://github.com/toshicloud/toshi-api) repository, one
-`*_pb.ts` file per proto. The generated code is committed and imports
+`*_pb.ts` file per proto, and `src/gen/toshi/permission_pb.ts` from
+`proto/toshi/permission.proto`, which they import. The generated code is committed and imports
 only `@bufbuild/protobuf`, so installing the package needs no generator.
 
 `pin.env` names the toshi-api commit (or, once one exists, the release

package/dist/client.d.ts

@@ -3,10 +3,12 @@ import type { Client, Interceptor, Transport } from "@connectrpc/connect";
 import { ArtifactService, ArtifactUploadService } from "./gen/toshi/workspace/v1/artifacts_pb.js";
 import { AuditEventService } from "./gen/toshi/workspace/v1/audit_events_pb.js";
 import { ChannelService } from "./gen/toshi/workspace/v1/channels_pb.js";
+import { DiscoveryService } from "./gen/toshi/workspace/v1/discovery_pb.js";
 import { DisplayService } from "./gen/toshi/workspace/v1/display_pb.js";
 import { FillerService } from "./gen/toshi/workspace/v1/fillers_pb.js";
 import { HostJobService } from "./gen/toshi/workspace/v1/hostjobs_pb.js";
 import { HostService } from "./gen/toshi/workspace/v1/hosts_pb.js";
+import { ProductService } from "./gen/toshi/workspace/v1/products_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";
@@ -18,21 +20,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 {
@@ -53,6 +66,8 @@ export interface ToshiClient {
     readonly auditEvent: Client<typeof AuditEventService>;
     readonly filler: Client<typeof FillerService>;
     readonly storageProvider: Client<typeof StorageProviderService>;
+    readonly product: Client<typeof ProductService>;
+    readonly discovery: Client<typeof DiscoveryService>;
     run(req: MessageInitShape<typeof CreateJobRequestSchema>, opts?: CallOptions): Promise<JobRun>;
 }
 /** WorkloadService's calls, grouped by the type they name. */
@@ -63,6 +78,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 +89,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 +103,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 +116,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 +129,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 +185,10 @@ 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 product, scope, key,
+ * retry and auth interceptors (product outermost, so a product's refusal
+ * reaches the caller as a ProductError; 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

@@ -4,10 +4,12 @@ import { executeCommand } from "./execute.js";
 import { ArtifactService, ArtifactUploadService } from "./gen/toshi/workspace/v1/artifacts_pb.js";
 import { AuditEventService } from "./gen/toshi/workspace/v1/audit_events_pb.js";
 import { ChannelService } from "./gen/toshi/workspace/v1/channels_pb.js";
+import { DiscoveryService } from "./gen/toshi/workspace/v1/discovery_pb.js";
 import { DisplayService } from "./gen/toshi/workspace/v1/display_pb.js";
 import { FillerService } from "./gen/toshi/workspace/v1/fillers_pb.js";
 import { HostJobService } from "./gen/toshi/workspace/v1/hostjobs_pb.js";
 import { HostService } from "./gen/toshi/workspace/v1/hosts_pb.js";
+import { ProductService } from "./gen/toshi/workspace/v1/products_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";
@@ -19,15 +21,18 @@ 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 { authInterceptor, keyInterceptor, retryInterceptor, scopeInterceptor } from "./interceptors.js";
+import { paginate } from "./paginate.js";
+import { authInterceptor, keyInterceptor, productInterceptor, 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 product, scope, key,
+ * retry and auth interceptors (product outermost, so a product's refusal
+ * reaches the caller as a ProductError; 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 +41,13 @@ import { waitJob, waitOperation, waitSandbox, waitService } from "./wait.js";
 export function createToshiClient(options) {
     const retry = normalizeRetry(options.retry);
     const interceptors = [
-        authInterceptor(options.token ?? ""),
+        productInterceptor(),
         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 +64,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 +76,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 +87,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 +99,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),
         },
@@ -104,5 +115,7 @@ export function createToshiClient(options) {
         auditEvent: createClient(AuditEventService, transport),
         filler: createClient(FillerService, transport),
         storageProvider: createClient(StorageProviderService, transport),
+        product: createClient(ProductService, transport),
+        discovery: createClient(DiscoveryService, transport),
     };
 }

package/dist/errors.d.ts

@@ -1,3 +1,4 @@
+import { ConnectError } from "@connectrpc/connect";
 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 {
@@ -26,3 +27,49 @@ export declare class StreamLostError extends Error {
     readonly requestKey: string;
     constructor(executionId: string, requestKey: string, cause?: unknown);
 }
+/** Why the API refused a call for a product: the reason of the refusal's ErrorInfo detail. */
+export type ProductReason = "PRODUCT_NOT_INSTALLED" | "PRODUCT_DISABLED" | "PRODUCT_NOT_ENTITLED" | "PRODUCT_TURNED_OFF" | "ACCESS_NOT_ACCEPTED";
+/** The reasons a call is refused for a product. */
+export declare const ProductReason: {
+    /** The deployment's build does not include the product; the code is Unimplemented. */
+    readonly NotInstalled: "PRODUCT_NOT_INSTALLED";
+    /** The deployment turned the product off; the code is FailedPrecondition. */
+    readonly Disabled: "PRODUCT_DISABLED";
+    /** The workspace's entitlements leave the product out; the code is PermissionDenied. */
+    readonly NotEntitled: "PRODUCT_NOT_ENTITLED";
+    /**
+     * The workspace's settings turn the product off, or an outside product's
+     * installation is turned off; the code is FailedPrecondition.
+     */
+    readonly TurnedOff: "PRODUCT_TURNED_OFF";
+    /**
+     * Turning an outside product on installs it, and the call did not accept the
+     * access it asks for; the code is FailedPrecondition.
+     */
+    readonly AccessNotAccepted: "ACCESS_NOT_ACCEPTED";
+};
+/**
+ * The API's refusal of a call for a product: one that is off for the
+ * workspace, or an outside product whose access the call did not accept.
+ * Every call the client makes throws it in place of the ConnectError, wait,
+ * watch and execute included. It is a ConnectError, so `instanceof
+ * ConnectError` and `code` read as before; test for it with
+ * {@link isProductError}.
+ */
+export declare class ProductError extends ConnectError {
+    /** The product's ID, such as `runners`. */
+    readonly product: string;
+    readonly reason: ProductReason;
+    /** The setting that turns the product on, such as `runners.enabled`; empty for ACCESS_NOT_ACCEPTED. */
+    readonly feature: string;
+    /** How far a product the deployment disables has wound down: `no_new_work`, `draining` or `stopped`; empty otherwise. */
+    readonly state: string;
+    /** The access an outside product asks for, for ACCESS_NOT_ACCEPTED: accept exactly this list to install it. */
+    readonly access: string[];
+    constructor(err: ConnectError, reason: ProductReason, metadata: ReadonlyMap<string, string>);
+    static [Symbol.hasInstance](v: unknown): boolean;
+}
+/** Reports whether err is a product's refusal. */
+export declare function isProductError(err: unknown): err is ProductError;
+/** err as a ProductError when it is a product's refusal, and err unchanged otherwise. */
+export declare function asProductError(err: unknown): unknown;