@runblackcat/sdk 0.1.0-alpha.88 → 0.1.0-alpha.90

package/README.md

@@ -168,6 +168,12 @@ GET  /v1/sandboxes/acquisitions/{id}       -> 202 pending … -> 200 {"state":"p
 POST /v1/sandboxes/{id}/renew {ttl_secs}   -> 200 {"expires_at":…, "renewable_until":…}
 ```
 
+Add `?wait_secs=N` (held at most 55 s) to the create or the lookup to have the gateway
+hold a still-pending claim and answer as soon as it is placed or fails; the
+placed receipt carries `ports`, so there is nothing to poll and no second call.
+A claim still pending when the hold ends is answered `pending`; ask again. It
+does not apply to a `count` batch: wait on each member by `request_id`.
+
 To start many identical sandboxes, add `"count": N` (1 to 1000) to the create.
 `request_id` then names the batch and member `i` is `request_id.i`. The whole batch
 is recorded in one durable transaction and answered `202` at once, with no
@@ -187,7 +193,7 @@ sandbox.
 Backpressure is fleet capacity and the durable queue; there are no per-tenant
 quotas. A queued acquisition that waits past the queue deadline is torn down by
 the ordinary expiry reconciler. Request-rate limits are operator-set fleet state
-(`blackcat admin rate-limits get|set`): token mint and OIDC limits are on by
+(`blackcat admin rate-limits get|set`): session token-mint and OIDC limits are on by
 default, every workload limit is unlimited until set.
 
 The placer sizes the fleet from that backlog through the `CapacityProvider`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runblackcat/sdk",
-  "version": "0.1.0-alpha.88",
+  "version": "0.1.0-alpha.90",
   "description": "TypeScript SDK for the Blackcat sandbox gateway",
   "license": "Apache-2.0",
   "repository": "https://github.com/TreebeardHQ/blackcat",

package/sdk/dist/index.d.ts

@@ -33,7 +33,14 @@ export type FetchFunction = (input: RequestInfo | URL, init?: RequestInit & {
 }) => Promise<Response>;
 export interface BlackcatClientOptions {
     baseUrl: string;
+    /**
+     * A tenant API key. The gateway accepts it directly on every resource route
+     * for the tenant's own resources (limited to the key's operation set), so a
+     * trusted server-side caller needs no `tokens.mint` per call. Keep it
+     * server-side; hand less-trusted holders a minted `token` instead.
+     */
     apiKey?: string;
+    /** A capability token; preferred over `apiKey` when both are set. */
     token?: string;
     /** Capability identity and expiry, using idiomatic TypeScript names. */
     tokenId?: string;
@@ -369,8 +376,8 @@ export type CreateCapacityReservationInput = ({
      * ordinary work; a sandbox create naming it waits for one of its slots. */
     placement?: "shared" | "dedicated";
     /** With `placement: "dedicated"`, the provider shape to launch: an exact
-     * shape or a family (`c7i`) of the fleet's capacity shapes. Absent: the
-     * planner chooses. */
+     * shape or a family (`c7i`) the fleet can launch (direct EC2: the config's
+     * instance_types). Absent: the planner chooses. */
     shape?: string;
     /** Stable retry key, at most 107 ASCII letters, digits, `_` or `-`. */
     idempotency_key?: string;
@@ -406,6 +413,15 @@ export interface CapacityReservation {
     /** When the capacity must be ready (epoch milliseconds), or null. */
     needed_by: number | null;
 }
+export interface WaitOptions {
+    /**
+     * Have the gateway hold a still-pending claim for up to this many seconds
+     * and answer as soon as it is placed or fails, with its ports, instead of
+     * answering `pending` at once. The gateway holds at most 55 seconds. A claim
+     * still pending after the hold is returned as `pending`; ask again.
+     */
+    wait_secs?: number;
+}
 /**
  * Response returned by POST /v1/sandboxes (the gateway has no template field).
  * The gateway sends a `failed` receipt with HTTP 409, so `create` and
@@ -872,7 +888,7 @@ declare class SandboxesResource {
      * recover a lost response. A pending receipt is not an executable sandbox;
      * no automatic retry, new ID, or replacement allocation is synthesized here.
      */
-    create(input: CreateSandboxInput): Promise<CreateSandboxResponse>;
+    create(input: CreateSandboxInput, options?: WaitOptions): Promise<CreateSandboxResponse>;
     /**
      * Create `count` identical sandboxes under one request ID. Resolves as soon
      * as the whole batch is durably recorded; nothing waits on a restore.
@@ -882,7 +898,7 @@ declare class SandboxesResource {
     createBatch(input: CreateSandboxBatchInput): Promise<SandboxBatchResponse>;
     /** Counts by state and every member of a batch created with `createBatch`. */
     batch(requestId: string): Promise<SandboxBatchResponse>;
-    acquisition(requestId: string): Promise<CreateSandboxResponse>;
+    acquisition(requestId: string, options?: WaitOptions): Promise<CreateSandboxResponse>;
     /**
      * Fence an acquisition request ID before its create is recorded, or destroy
      * the allocation when the create has already won.

package/sdk/dist/index.js

@@ -21,6 +21,9 @@ var BLACKCAT_ERROR_CODES = {
 function withTemplate(input) {
   return { ...input, template: input.template ?? "default" };
 }
+function waitQuery({ wait_secs }) {
+  return wait_secs === undefined ? "" : `?wait_secs=${wait_secs}`;
+}
 
 class BlackcatApiError extends Error {
   status;
@@ -351,17 +354,17 @@ class TemplatesResource {
     this.client = client;
   }
   create(input) {
-    return this.client.json("POST", "/v1/templates", input, "token");
+    return this.client.json("POST", "/v1/templates", input, "either");
   }
   list() {
-    return this.client.json("GET", "/v1/templates", undefined, "token");
+    return this.client.json("GET", "/v1/templates", undefined, "either");
   }
   async uploadImage(archive, options) {
     const response = await this.client.raw("POST", "/v1/template-images", archive, "either", "application/octet-stream", false, options?.signal);
     return await response.json();
   }
   activate(id) {
-    return this.client.json("POST", `/v1/templates/${pathSegment(id)}/activate`, undefined, "token");
+    return this.client.json("POST", `/v1/templates/${pathSegment(id)}/activate`, undefined, "either");
   }
 }
 
@@ -371,13 +374,13 @@ class TemplateResourcesResource {
     this.client = client;
   }
   get(name) {
-    return this.client.json("GET", `/v1/template-resources/${pathSegment(name)}`, undefined, "token");
+    return this.client.json("GET", `/v1/template-resources/${pathSegment(name)}`, undefined, "either");
   }
   configure(name, input) {
-    return this.client.json("PUT", `/v1/template-resources/${pathSegment(name)}`, input, "token");
+    return this.client.json("PUT", `/v1/template-resources/${pathSegment(name)}`, input, "either");
   }
   delete(name) {
-    return this.client.json("DELETE", `/v1/template-resources/${pathSegment(name)}`, undefined, "token");
+    return this.client.json("DELETE", `/v1/template-resources/${pathSegment(name)}`, undefined, "either");
   }
 }
 
@@ -387,13 +390,13 @@ class TemplateBuildsResource {
     this.client = client;
   }
   create(input) {
-    return this.client.json("POST", "/v1/template-builds", input, "token");
+    return this.client.json("POST", "/v1/template-builds", input, "either");
   }
   get(id) {
-    return this.client.json("GET", `/v1/template-builds/${pathSegment(id)}`, undefined, "token");
+    return this.client.json("GET", `/v1/template-builds/${pathSegment(id)}`, undefined, "either");
   }
   retry(id) {
-    return this.client.json("POST", `/v1/template-builds/${pathSegment(id)}/retry`, undefined, "token");
+    return this.client.json("POST", `/v1/template-builds/${pathSegment(id)}/retry`, undefined, "either");
   }
 }
 
@@ -424,7 +427,7 @@ class FleetResource {
     this.client = client;
   }
   list() {
-    return this.client.json("GET", "/v1/fleet", undefined, "token");
+    return this.client.json("GET", "/v1/fleet", undefined, "either");
   }
 }
 
@@ -434,16 +437,16 @@ class ReservationsResource {
     this.client = client;
   }
   create(input) {
-    return this.client.json("POST", "/v1/capacity-reservations", input, "token");
+    return this.client.json("POST", "/v1/capacity-reservations", input, "either");
   }
   get(id) {
-    return this.client.json("GET", `/v1/capacity-reservations/${pathSegment(id)}`, undefined, "token");
+    return this.client.json("GET", `/v1/capacity-reservations/${pathSegment(id)}`, undefined, "either");
   }
   release(id) {
-    return this.client.json("DELETE", `/v1/capacity-reservations/${pathSegment(id)}`, undefined, "token");
+    return this.client.json("DELETE", `/v1/capacity-reservations/${pathSegment(id)}`, undefined, "either");
   }
   renew(id, input) {
-    return this.client.json("POST", `/v1/capacity-reservations/${pathSegment(id)}/renew`, input, "token");
+    return this.client.json("POST", `/v1/capacity-reservations/${pathSegment(id)}/renew`, input, "either");
   }
 }
 
@@ -453,34 +456,34 @@ class SandboxesResource {
     this.client = client;
   }
   list() {
-    return this.client.json("GET", "/v1/sandboxes", undefined, "token");
+    return this.client.json("GET", "/v1/sandboxes", undefined, "either");
   }
-  async create(input) {
-    return parseCreateSandboxResponse(await this.client.json("POST", "/v1/sandboxes", withTemplate(input), "token", false), input.request_id);
+  async create(input, options = {}) {
+    return parseCreateSandboxResponse(await this.client.json("POST", `/v1/sandboxes${waitQuery(options)}`, withTemplate(input), "either", false), input.request_id);
   }
   async createBatch(input) {
-    return parseSandboxBatch(await this.client.json("POST", "/v1/sandboxes", withTemplate(input), "token", false), input.request_id);
+    return parseSandboxBatch(await this.client.json("POST", "/v1/sandboxes", withTemplate(input), "either", false), input.request_id);
   }
   async batch(requestId) {
-    return parseSandboxBatch(await this.client.json("GET", `/v1/sandboxes/batches/${pathSegment(requestId)}`, undefined, "token"), requestId);
+    return parseSandboxBatch(await this.client.json("GET", `/v1/sandboxes/batches/${pathSegment(requestId)}`, undefined, "either"), requestId);
   }
-  async acquisition(requestId) {
-    return parseCreateSandboxResponse(await this.client.json("GET", `/v1/sandboxes/acquisitions/${pathSegment(requestId)}`, undefined, "token"), requestId);
+  async acquisition(requestId, options = {}) {
+    return parseCreateSandboxResponse(await this.client.json("GET", `/v1/sandboxes/acquisitions/${pathSegment(requestId)}${waitQuery(options)}`, undefined, "either", options.wait_secs === undefined ? undefined : false), requestId);
   }
   async cancelAcquisition(requestId) {
-    return parseCreateSandboxResponse(await this.client.json("DELETE", `/v1/sandboxes/acquisitions/${pathSegment(requestId)}`, undefined, "token"), requestId);
+    return parseCreateSandboxResponse(await this.client.json("DELETE", `/v1/sandboxes/acquisitions/${pathSegment(requestId)}`, undefined, "either"), requestId);
   }
   get(id) {
-    return this.client.json("GET", `/v1/sandboxes/${pathSegment(id)}`, undefined, "token");
+    return this.client.json("GET", `/v1/sandboxes/${pathSegment(id)}`, undefined, "either");
   }
   renew(id, ttl_secs) {
-    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/renew`, { ttl_secs }, "token");
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/renew`, { ttl_secs }, "either");
   }
   grantSshKey(id, input) {
-    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/ssh-keys`, input, "token");
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/ssh-keys`, input, "either");
   }
   async exec(id, input) {
-    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/exec`, input, "token", false, execDeadline(input)).then(execResult);
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/exec`, input, "either", false, execDeadline(input)).then(execResult);
   }
   async* execStream(id, input) {
     if (input.stdin !== undefined && input.stdin.length > MAX_EXEC_STDIN) {
@@ -496,7 +499,7 @@ class SandboxesResource {
       return chunk;
     };
     const decoder = new TextDecoder;
-    for await (const chunk of this.client.stream("POST", `/v1/sandboxes/${pathSegment(id)}/exec/stream`, JSON.stringify(input), "token", "application/json", true, execDeadline(input))) {
+    for await (const chunk of this.client.stream("POST", `/v1/sandboxes/${pathSegment(id)}/exec/stream`, JSON.stringify(input), "either", "application/json", true, execDeadline(input))) {
       lineBuffer += decoder.decode(chunk, { stream: true });
       const lines = lineBuffer.split(`
 `);
@@ -519,10 +522,10 @@ class SandboxesResource {
     return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/processes`, {
       ...input,
       ...input.stdin === undefined ? {} : { stdin: Array.from(input.stdin) }
-    }, "token", false, undefined, { "idempotency-key": requestId });
+    }, "either", false, undefined, { "idempotency-key": requestId });
   }
   getProcess(id, processId) {
-    return this.client.json("GET", `/v1/sandboxes/${pathSegment(id)}/processes/${pathSegment(processId)}`, undefined, "token");
+    return this.client.json("GET", `/v1/sandboxes/${pathSegment(id)}/processes/${pathSegment(processId)}`, undefined, "either");
   }
   async processLogs(id, processId, input = {}) {
     const options = typeof input === "number" ? { stdout_offset: 0, stderr_offset: 0, max_bytes: input } : input;
@@ -534,7 +537,7 @@ class SandboxesResource {
     if (options.max_bytes !== undefined)
       query.set("max_bytes", String(options.max_bytes));
     const suffix = query.size === 0 ? "" : `?${query.toString()}`;
-    const response = await this.client.json("GET", `/v1/sandboxes/${pathSegment(id)}/processes/${pathSegment(processId)}/logs${suffix}`, undefined, "token");
+    const response = await this.client.json("GET", `/v1/sandboxes/${pathSegment(id)}/processes/${pathSegment(processId)}/logs${suffix}`, undefined, "either");
     return {
       ...response,
       logs: {
@@ -545,13 +548,13 @@ class SandboxesResource {
     };
   }
   cancelProcess(id, processId) {
-    return this.client.json("DELETE", `/v1/sandboxes/${pathSegment(id)}/processes/${pathSegment(processId)}`, undefined, "token");
+    return this.client.json("DELETE", `/v1/sandboxes/${pathSegment(id)}/processes/${pathSegment(processId)}`, undefined, "either");
   }
   prepare(id, input, idempotencyKey) {
-    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/prepare`, input, "token", undefined, undefined, { "idempotency-key": idempotencyKey });
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/prepare`, input, "either", undefined, undefined, { "idempotency-key": idempotencyKey });
   }
   logs(id) {
-    return this.client.stream("GET", `/v1/sandboxes/${pathSegment(id)}/logs`, undefined, "token", undefined, true);
+    return this.client.stream("GET", `/v1/sandboxes/${pathSegment(id)}/logs`, undefined, "either", undefined, true);
   }
   async readFileChunk(id, input) {
     if (input.offset < 0 || input.length <= 0 || input.length > MAX_FILE_READ_CHUNK) {
@@ -562,7 +565,7 @@ class SandboxesResource {
       offset: String(input.offset),
       length: String(input.length)
     });
-    const response = await this.client.raw("GET", `/v1/sandboxes/${pathSegment(id)}/files/read?${query.toString()}`, undefined, "token");
+    const response = await this.client.raw("GET", `/v1/sandboxes/${pathSegment(id)}/files/read?${query.toString()}`, undefined, "either");
     const data = new Uint8Array(await response.arrayBuffer());
     const offset = Number(response.headers.get("x-blackcat-offset") ?? input.offset);
     const eof = response.headers.get("x-blackcat-eof") === "true";
@@ -613,7 +616,7 @@ class SandboxesResource {
       offset: String(input.offset),
       truncate: String(input.truncate)
     });
-    await this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/files/write?${query.toString()}`, requestBody(input.data), "token", "application/octet-stream");
+    await this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/files/write?${query.toString()}`, requestBody(input.data), "either", "application/octet-stream");
   }
   async writeFileStream(id, input) {
     const start = input.offset ?? 0;
@@ -658,28 +661,28 @@ class SandboxesResource {
     });
   }
   snapshot(id) {
-    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/snapshot`, undefined, "token");
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/snapshot`, undefined, "either");
   }
   pause(id) {
-    return this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/pause`, undefined, "token").then(() => {
+    return this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/pause`, undefined, "either").then(() => {
       return;
     });
   }
   hibernate(id, input) {
-    return this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/hibernate`, input === undefined ? undefined : JSON.stringify(input), "token", input === undefined ? undefined : "application/json", false).then(() => {
+    return this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/hibernate`, input === undefined ? undefined : JSON.stringify(input), "either", input === undefined ? undefined : "application/json", false).then(() => {
       return;
     });
   }
   resize(id, input) {
-    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/resize`, { ...input, request_id: input.request_id ?? `resize-${crypto.randomUUID()}` }, "token", false);
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/resize`, { ...input, request_id: input.request_id ?? `resize-${crypto.randomUUID()}` }, "either", false);
   }
   resume(id) {
-    return this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/resume`, undefined, "token").then(() => {
+    return this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/resume`, undefined, "either").then(() => {
       return;
     });
   }
   destroy(id) {
-    return this.client.json("DELETE", `/v1/sandboxes/${pathSegment(id)}`, undefined, "token");
+    return this.client.json("DELETE", `/v1/sandboxes/${pathSegment(id)}`, undefined, "either");
   }
 }