@runblackcat/sdk 0.1.0-alpha.77 → 0.1.0-alpha.79

package/package.json

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

package/sdk/dist/index.d.ts

@@ -328,6 +328,10 @@ export interface SandboxBatch {
     counts: Partial<Record<SandboxBatchMemberState, number>>;
     members: SandboxBatchMember[];
 }
+export type SandboxBatchResponse = SandboxBatch | {
+    request_id: string;
+    state: "prevented";
+};
 export interface SandboxLeaseInput {
     /** Initial lease duration, between 60 seconds and 24 hours. */
     ttl_secs: number;
@@ -351,6 +355,10 @@ export type CreateCapacityReservationInput = ({
     memory_mib: number;
     /** How long to hold the reservation, between 1 second and 4 hours. */
     ttl_secs: number;
+    /** Defaults to `consumable`; `reusable` returns each slot after confirmed destruction. */
+    mode?: "consumable" | "reusable";
+    /** Stable retry key, at most 107 ASCII letters, digits, `_` or `-`. */
+    idempotency_key?: string;
 };
 export interface CapacityReservation {
     id: string;
@@ -361,10 +369,13 @@ export interface CapacityReservation {
     /** The template resource this reservation follows, or null when pinned. */
     template_resource: string | null;
     count: number;
+    mode: "consumable" | "reusable";
     vcpus: number;
     memory_mib: number;
     /** Slots consumed by an actual sandbox create. */
     claimed: number;
+    /** Current slot occupancy for reusable reservations; zero otherwise. */
+    occupied: number;
     /** Slots bound to a specific node and not yet claimed. */
     bound: number;
     /** Bound slots whose node already has the template warm. */
@@ -379,6 +390,9 @@ export interface CapacityReservation {
  * retryable under a new request id rather than a protocol fault.
  */
 export type CreateSandboxResponse = {
+    request_id: string;
+    state: "prevented";
+} | ({
     request_id: string;
     id: string;
     tier: "boot" | "warm_pool" | "restore";
@@ -402,7 +416,11 @@ export type CreateSandboxResponse = {
     state: "failed";
     node: null;
     error: string;
-});
+} | {
+    state: "destroyed";
+    node: string | null;
+    error: string;
+}));
 /**
  * Restore phase breakdown a node reported for a checkpoint launch (Proposal
  * F, docs/restore-performance.md). `phase_ms` mirrors the node's own
@@ -731,7 +749,7 @@ declare const MAX_PROCESS_STDIN: number;
 declare const MAX_EXEC_STDIN: number;
 export declare function epochMillis(value: unknown, field: string): number;
 export declare function parseCreateSandboxResponse(value: unknown, requestId: string): CreateSandboxResponse;
-export declare function parseSandboxBatch(value: unknown, requestId: string): SandboxBatch;
+export declare function parseSandboxBatch(value: unknown, requestId: string): SandboxBatchResponse;
 export declare function assertSecureBlackcatGatewayUrl(baseUrl: string): void;
 declare class GatewayClient {
     readonly baseUrl: string;
@@ -811,6 +829,10 @@ declare class ReservationsResource {
     /** Release early. Unclaimed slots free immediately; bound nodes then fall
      * back to the normal empty-worker scale-in grace period. */
     release(id: string): Promise<CapacityReservation>;
+    renew(id: string, input: {
+        ttl_secs: number;
+        idempotency_key: string;
+    }): Promise<CapacityReservation>;
 }
 declare class SandboxesResource {
     private readonly client;
@@ -829,10 +851,15 @@ declare class SandboxesResource {
      * Repeat the exact request to recover a lost response: member IDs are
      * stable. Poll `batch` for counts by state, or a member with `acquisition`.
      */
-    createBatch(input: CreateSandboxBatchInput): Promise<SandboxBatch>;
+    createBatch(input: CreateSandboxBatchInput): Promise<SandboxBatchResponse>;
     /** Counts by state and every member of a batch created with `createBatch`. */
-    batch(requestId: string): Promise<SandboxBatch>;
+    batch(requestId: string): Promise<SandboxBatchResponse>;
     acquisition(requestId: string): Promise<CreateSandboxResponse>;
+    /**
+     * Fence an acquisition request ID before its create is recorded, or destroy
+     * the allocation when the create has already won.
+     */
+    cancelAcquisition(requestId: string): Promise<CreateSandboxResponse>;
     get(id: string): Promise<Sandbox>;
     /** Extend the soft expiry without moving the immutable hard deadline. */
     renew(id: string, ttl_secs: number): Promise<RenewSandboxResponse>;

package/sdk/dist/index.js

@@ -91,7 +91,10 @@ function parseCreateSandboxResponse(value, requestId) {
     throw new BlackcatProtocolError("sandbox create receipt is malformed or belongs to another request");
   }
   const row = value;
-  if (row.request_id !== requestId || typeof row.id !== "string" || row.id.length === 0 || !["boot", "warm_pool", "restore"].includes(String(row.tier)) || !["placed", "pending", "failed"].includes(String(row.state)) || row.state === "placed" && typeof row.node !== "string" || row.state === "pending" && row.node !== null && typeof row.node !== "string" || row.state === "failed" && (row.node !== null || typeof row.error !== "string") || !isSystemTime(row.expires_at) || !isSystemTime(row.renewable_until)) {
+  if (row.request_id === requestId && row.state === "prevented") {
+    return value;
+  }
+  if (row.request_id !== requestId || typeof row.id !== "string" || row.id.length === 0 || !["boot", "warm_pool", "restore"].includes(String(row.tier)) || !["placed", "pending", "failed", "destroyed"].includes(String(row.state)) || row.state === "placed" && typeof row.node !== "string" || row.state === "pending" && row.node !== null && typeof row.node !== "string" || row.state === "failed" && (row.node !== null || typeof row.error !== "string") || row.state === "destroyed" && (row.node !== null && typeof row.node !== "string" || typeof row.error !== "string") || !isSystemTime(row.expires_at) || !isSystemTime(row.renewable_until)) {
     throw new BlackcatProtocolError("sandbox create receipt is malformed or belongs to another request");
   }
   return value;
@@ -102,6 +105,9 @@ function parseSandboxBatch(value, requestId) {
   if (typeof value !== "object" || value === null || Array.isArray(value))
     throw malformed();
   const row = value;
+  if (row.request_id === requestId && row.state === "prevented") {
+    return value;
+  }
   if (row.request_id !== requestId || typeof row.count !== "number" || typeof row.counts !== "object" || row.counts === null || !Array.isArray(row.members) || row.members.length !== row.count || !row.members.every((member) => {
     const m = member;
     return typeof m === "object" && m !== null && typeof m.request_id === "string" && typeof m.id === "string" && BATCH_STATES.includes(String(m.state));
@@ -436,6 +442,9 @@ class ReservationsResource {
   release(id) {
     return this.client.json("DELETE", `/v1/capacity-reservations/${pathSegment(id)}`, undefined, "token");
   }
+  renew(id, input) {
+    return this.client.json("POST", `/v1/capacity-reservations/${pathSegment(id)}/renew`, input, "token");
+  }
 }
 
 class SandboxesResource {
@@ -458,6 +467,9 @@ class SandboxesResource {
   async acquisition(requestId) {
     return parseCreateSandboxResponse(await this.client.json("GET", `/v1/sandboxes/acquisitions/${pathSegment(requestId)}`, undefined, "token"), requestId);
   }
+  async cancelAcquisition(requestId) {
+    return parseCreateSandboxResponse(await this.client.json("DELETE", `/v1/sandboxes/acquisitions/${pathSegment(requestId)}`, undefined, "token"), requestId);
+  }
   get(id) {
     return this.client.json("GET", `/v1/sandboxes/${pathSegment(id)}`, undefined, "token");
   }