@aerol-ai/aerolvm-sdk 0.8.0 → 0.8.2

package/dist/internal/client.d.ts

@@ -1,5 +1,5 @@
 import { Image } from "../Image.js";
-import type { AddCustomDomainOptions, APITokenList, BinaryLike, BuildImageOptions, BuildImageResult, CreateAPITokenOptions, CreatedAPIToken, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, CustomDomain, CloneGeneration, CustomDomainDNSRecords, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, Failover, HealthStatus, IngressTarget, Lifecycle, GetOptions, ListOptions, MountSpecRedacted, NetworkUsage, AuditOptions, AuditPage, EgressProfile, EgressProfileList, EgressProfileOptions, EgressProfileRef, EgressRule, ListEgressProfilesOptions, NetworkLearned, NetworkPolicy, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, NetworkPolicyOptions, ListSnapshotsOptions, RegisterSnapshotOptions, SnapshotList, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule, WhoAmI } from "../types.js";
+import type { CallOptions, AddCustomDomainOptions, APITokenList, BinaryLike, BuildImageOptions, BuildImageResult, CreateAPITokenOptions, CreatedAPIToken, CreateOptions, CreateSandboxTokenOptions, RevokeSandboxTokensResult, SandboxToken, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, CustomDomain, CloneGeneration, CustomDomainDNSRecords, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, Failover, FileEvent, FileWatchHandle, FileInfo, FileList, FileMatch, UploadFileOptions, DownloadFileOptions, ListFilesOptions, DeleteFileOptions, MakeDirOptions, MoveFileOptions, CopyFileOptions, HealthStatus, IngressTarget, Lifecycle, GetOptions, ListOptions, MountSpecRedacted, NetworkUsage, AuditOptions, AuditPage, EgressProfile, EgressProfileList, EgressProfileOptions, EgressProfileRef, TeamQuota, TeamQuotaOptions, IdentityRole, IdentityRoleList, IdentityRoleOptions, ListIdentityRolesOptions, SandboxIdentity, EgressRule, ListEgressProfilesOptions, WarmPool, WarmPoolOptions, NetworkLearned, NetworkPolicy, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, NetworkPolicyOptions, ListSnapshotsOptions, CreateSnapshotOptions, RegisterSnapshotOptions, SnapshotList, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, StatusReason, Template, WasmModule, WhoAmI, WatchFilesOptions } from "../types.js";
 type FetchLike = typeof fetch;
 /**
  * The request header that selects which of a credential's teams a request
@@ -81,6 +81,8 @@ export interface APIClientConfig {
      */
     signal?: AbortSignal;
 }
+/** The entry cap `listFiles` sends when the caller gives none. */
+export declare const DEFAULT_LIST_LIMIT = 10000;
 /**
  * The header a sandbox create carries so the server can recognise a retry of
  * it. Keep in sync with clustercreate.HeaderIdempotencyKey on the server.
@@ -121,6 +123,13 @@ export declare class APIClient {
     private readonly versionPrefix;
     private readonly retryConfig;
     private readonly signal;
+    /** The client a {@link withSignal} view was made from; unset on a real client. */
+    private readonly root;
+    /**
+     * Features each sandbox's agent listed on /version (requireToolboxFeatures).
+     * Refreshed on a miss, because a restart can bring a newer agent.
+     */
+    private readonly toolboxFeatures;
     constructor(config: APIClientConfig);
     /**
      * Build a versioned API path. Pass the suffix beginning with "/" (e.g.
@@ -129,6 +138,15 @@ export declare class APIClient {
      * apiVersion option without touching call sites.
      */
     private versioned;
+    /**
+     * This client with `signal` added to its own: either one aborting ends a
+     * request and any retry wait. A per-call signal (plan S6) rides on a view
+     * like this rather than a parameter on every internal method. The view
+     * shares everything else, the per-sandbox feature cache included, and the
+     * sandboxes it returns hold the real client, so the call's signal never
+     * outlives the call. Without a signal it is this client.
+     */
+    withSignal(signal: AbortSignal | undefined): APIClient;
     create(options: CreateOptions): Promise<SandboxResource>;
     /**
      * Compile a fluent {@link Image} into a content-addressed image tag by
@@ -154,20 +172,58 @@ export declare class APIClient {
      * the wrong sandbox.
      */
     getByName(name: string, options?: GetOptions): Promise<SandboxResource | null>;
+    /**
+     * The caller's sandbox called `name`, created from `options` when there is
+     * none; `created` is true only when this call made it. Safe to retry and to
+     * run concurrently: names are unique per owner, so a caller that loses a
+     * race to create the name gets a 409 and reads the winner's sandbox.
+     */
+    getOrCreate(name: string, options: CreateOptions): Promise<{
+        sandbox: SandboxResource;
+        created: boolean;
+    }>;
     get(id: string, options?: GetOptions): Promise<SandboxResource>;
     start(id: string): Promise<SandboxResource>;
     stop(id: string): Promise<SandboxResource>;
-    createSnapshot(id: string, name: string): Promise<SandboxSnapshot>;
+    createSnapshot(id: string, name: string, options?: CreateSnapshotOptions): Promise<SandboxSnapshot>;
     registerSnapshot(options: RegisterSnapshotOptions): Promise<SandboxSnapshot>;
     registerSnapshotFromImage(name: string, image: Image, options?: Omit<RegisterSnapshotOptions, "name" | "image" | "dockerfileContent">): Promise<SandboxSnapshot>;
     getSnapshot(name: string): Promise<SandboxSnapshot>;
     listSnapshots(options?: ListSnapshotsOptions): Promise<SnapshotList>;
     deleteSnapshot(name: string): Promise<void>;
     destroy(id: string): Promise<void>;
+    /**
+     * Deletes every sandbox carrying all of `tags`, one at a time, after
+     * listing every page; returns the IDs now gone. A 404 counts as deleted,
+     * so the call is safe to repeat. Any other failure stops it and is thrown.
+     */
+    destroyAll(tags: Record<string, string>): Promise<string[]>;
     resize(id: string, options: ResizeOptions): Promise<SandboxResource>;
     updateLifecycle(id: string, lifecycle: Lifecycle): Promise<SandboxResource>;
+    /**
+     * Fails closed unless the sandbox's agent lists every feature. toolboxd
+     * ignores request options it does not know, so sending a newer option to an
+     * older agent would silently skip it.
+     */
+    requireToolboxFeatures(id: string, ...features: string[]): Promise<void>;
     exec(id: string, request: ExecRequest): Promise<ExecResult>;
     execStream(id: string, options: ExecStreamOptions): ExecStreamHandle;
+    /**
+     * Watch a folder in the sandbox for changes. Resolves once the watch is in
+     * place, so a change made after it resolves is reported. gVisor and
+     * Firecracker sandboxes only: the others answer 501. Not retried: a stream
+     * is opened once.
+     */
+    watchFiles(id: string, path: string, onEvent: (event: FileEvent) => void, options?: WatchFilesOptions): Promise<FileWatchHandle>;
+    /**
+     * Explains a watch whose WebSocket handshake failed. The WebSocket API
+     * hides a refused handshake's status and body, so the same request is sent
+     * again as plain HTTP: toolboxd checks the runtime, the path and its limits
+     * before the upgrade, so it answers with the real reason (501 on Docker or
+     * containerd, 404 for a missing folder, 429 at the watch limit). That GET
+     * is a diagnosis, sent once, never a retry of the stream.
+     */
+    private fileWatchRefusal;
     createSession(id: string, options: CreateSessionOptions): Promise<Session>;
     listSessions(id: string): Promise<Session[]>;
     getSession(id: string, sessionID: string): Promise<Session>;
@@ -177,8 +233,50 @@ export declare class APIClient {
     sessionLog(id: string, sessionID: string): Promise<Uint8Array>;
     sessionRecording(id: string, sessionID: string): Promise<Uint8Array>;
     attachSession(id: string, sessionID: string, options?: SessionAttachOptions): SessionAttachHandle;
-    uploadFile(id: string, targetPath: string, data: BinaryLike): Promise<void>;
-    downloadFile(id: string, targetPath: string): Promise<Uint8Array>;
+    /**
+     * Plain and atomic uploads retry on 421/429/502/503/504; `append` and
+     * `createOnly` only on 429/503, because a second send would append twice
+     * or find the first one's file.
+     */
+    uploadFile(id: string, targetPath: string, data: BinaryLike, options?: UploadFileOptions): Promise<void>;
+    /** The upload route with the write options as query, after the /version check they need. */
+    private uploadPath;
+    /**
+     * Upload from a stream a piece at a time, so a large file never sits in
+     * memory. The options are {@link uploadFile}'s. The data is read as it is
+     * sent, so the request is sent once and never retried. Needs a `fetch` that
+     * can send a streamed body (Node.js 18 and later).
+     */
+    uploadFileStream(id: string, targetPath: string, data: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>, options?: UploadFileOptions): Promise<void>;
+    /**
+     * Copy the local folder `localDir` into `remoteDir` in the sandbox (made if
+     * missing). The folder is packed as a gzipped tar and the sandbox unpacks it
+     * safely: no entry can land outside `remoteDir`. Symlinks are sent as links,
+     * hard-linked files as separate files; devices, pipes and sockets are
+     * skipped. The archive is built in memory and sent once, never retried.
+     * Node.js only.
+     */
+    uploadDir(id: string, localDir: string, remoteDir: string): Promise<void>;
+    downloadFile(id: string, targetPath: string, options?: DownloadFileOptions): Promise<Uint8Array>;
+    /**
+     * Open a file for reading a piece at a time, so a large file never sits in
+     * memory. With `maxBytes`, a larger file is refused before reading when the
+     * server states the size, and otherwise the stream errors as soon as more
+     * arrives. The request retries until the file starts to arrive.
+     */
+    downloadFileStream(id: string, targetPath: string, options?: DownloadFileOptions): Promise<ReadableStream<Uint8Array>>;
+    private toolboxPath;
+    /** Sends a body-less file call and discards a success reply. */
+    private fileCall;
+    listFiles(id: string, path: string, options?: ListFilesOptions): Promise<FileList>;
+    getFileInfo(id: string, path: string): Promise<FileInfo>;
+    fileExists(id: string, path: string): Promise<boolean>;
+    deleteFile(id: string, path: string, options?: DeleteFileOptions): Promise<void>;
+    makeDir(id: string, path: string, options?: MakeDirOptions): Promise<void>;
+    moveFile(id: string, source: string, destination: string, options?: MoveFileOptions): Promise<void>;
+    copyFile(id: string, source: string, destination: string, options?: CopyFileOptions): Promise<void>;
+    searchFiles(id: string, path: string, pattern: string): Promise<string[]>;
+    findInFiles(id: string, path: string, text: string): Promise<FileMatch[]>;
     /**
      * Publish a sandbox container port. The chosen wire protocol is selected by
      * `options.protocol` (defaults to `"http"`):
@@ -194,6 +292,20 @@ export declare class APIClient {
      */
     exposePort(id: string, port: number, options?: ExposePortOptions): Promise<ExposeResult>;
     unexposePort(id: string, port: number): Promise<void>;
+    /**
+     * Issue a signed token scoped to one sandbox (POST /v1/sandboxes/{id}/tokens).
+     * Not idempotent by nature: every call makes a new token, and the server
+     * stores none. It uses the normal retry tier: a retry after a lost answer
+     * makes a second token that nobody holds, which simply expires.
+     */
+    createSandboxToken(id: string, options: CreateSandboxTokenOptions): Promise<SandboxToken>;
+    /**
+     * Make every token issued for one sandbox so far stop working
+     * (POST /v1/sandboxes/{id}/tokens/revoke). A token issued after it works.
+     * Safe to retry: a repeated call refuses the same tokens again (plus any
+     * issued in between), so it uses the normal retry tier.
+     */
+    revokeSandboxTokens(id: string): Promise<RevokeSandboxTokensResult>;
     /**
      * Bind a custom hostname to a sandbox. The server lowercases the hostname
      * and returns the post-add list of bindings (sorted by hostname). Calling
@@ -228,6 +340,19 @@ export declare class APIClient {
     getEgressProfile(name: string): Promise<EgressProfile>;
     listEgressProfiles(options?: ListEgressProfilesOptions): Promise<EgressProfileList>;
     deleteEgressProfile(name: string): Promise<void>;
+    putWarmPool(image: string, options: WarmPoolOptions): Promise<WarmPool>;
+    getWarmPool(image: string): Promise<WarmPool>;
+    listWarmPools(): Promise<WarmPool[]>;
+    deleteWarmPool(image: string): Promise<void>;
+    putIdentityRole(tag: string, options: IdentityRoleOptions): Promise<IdentityRole>;
+    listIdentityRoles(options?: ListIdentityRolesOptions): Promise<IdentityRoleList>;
+    deleteIdentityRole(tag: string, options?: {
+        team?: string;
+    }): Promise<void>;
+    private identityRolePath;
+    putTeamQuota(team: string, options: TeamQuotaOptions): Promise<TeamQuota>;
+    getTeamQuota(team: string): Promise<TeamQuota>;
+    deleteTeamQuota(team: string): Promise<void>;
     createTemplate(options: CreateTemplateOptions): Promise<Template>;
     listTemplates(): Promise<Template[]>;
     getTemplate(id: string): Promise<Template>;
@@ -264,6 +389,7 @@ export declare class APIClient {
      * {@link retryDelayMs}). The client's `signal` ends the request and any
      * wait.
      */
+    private authHeaders;
     private request;
 }
 export declare class SandboxResource implements Sandbox {
@@ -294,35 +420,97 @@ export declare class SandboxResource implements Sandbox {
     name?: string;
     tags?: Record<string, string>;
     lastError?: string;
+    statusReason?: StatusReason;
+    exitCode?: number;
     containerCommand?: string[];
     lifecycle: Lifecycle;
     failover?: Failover;
     runtime: Sandbox["runtime"];
+    identity?: SandboxIdentity;
     protected readonly client: APIClient;
+    /**
+     * When true, leaving an `await using` block deletes the sandbox (see
+     * `[Symbol.asyncDispose]`). Off by default, so the block ends without
+     * touching it; set it here or with `destroyOnExit` on `create` and
+     * `getOrCreate`.
+     */
+    destroyOnExit: boolean;
+    private disposed;
+    /** The client for one call: the real one, or a view carrying the call's signal. */
+    private api;
     constructor(client: APIClient, sandbox: Sandbox);
-    refresh(): Promise<this>;
-    exec(command: string | ExecRequest): Promise<ExecResult>;
+    /**
+     * Called when an `await using` block holding this sandbox ends. Deletes the
+     * sandbox only when {@link destroyOnExit} is true; otherwise does nothing.
+     * A sandbox that is already gone counts as deleted, and a second call does
+     * nothing.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    refresh(call?: CallOptions): Promise<this>;
+    exec(command: string | ExecRequest, call?: CallOptions): Promise<ExecResult>;
     /**
      * Read this sandbox's clone-generation token. The token changes whenever the
      * sandbox is resumed from a snapshot. Use it to detect that a sandbox is a
      * clone (e.g. to re-run setup). It does NOT reseed in-guest PRNGs — see the
      * "Randomness in cloned sandboxes" docs page for the in-guest pattern.
      */
-    cloneGeneration(): Promise<CloneGeneration>;
+    cloneGeneration(call?: CallOptions): Promise<CloneGeneration>;
     execStream(options: ExecStreamOptions): ExecStreamHandle;
-    createSession(options: CreateSessionOptions): Promise<Session>;
-    listSessions(): Promise<Session[]>;
-    getSession(sessionID: string): Promise<Session>;
-    deleteSession(sessionID: string): Promise<void>;
-    signalSession(sessionID: string, signal: string): Promise<void>;
-    resizeSession(sessionID: string, cols: number, rows: number): Promise<void>;
-    sessionLog(sessionID: string): Promise<Uint8Array>;
-    sessionRecording(sessionID: string): Promise<Uint8Array>;
+    /**
+     * Watch a folder in this sandbox for changes; see
+     * {@link APIClient.watchFiles}. gVisor and Firecracker sandboxes only.
+     */
+    watchFiles(path: string, onEvent: (event: FileEvent) => void, options?: WatchFilesOptions): Promise<FileWatchHandle>;
+    createSession(options: CreateSessionOptions, call?: CallOptions): Promise<Session>;
+    listSessions(call?: CallOptions): Promise<Session[]>;
+    getSession(sessionID: string, call?: CallOptions): Promise<Session>;
+    deleteSession(sessionID: string, call?: CallOptions): Promise<void>;
+    signalSession(sessionID: string, signal: string, call?: CallOptions): Promise<void>;
+    resizeSession(sessionID: string, cols: number, rows: number, call?: CallOptions): Promise<void>;
+    sessionLog(sessionID: string, call?: CallOptions): Promise<Uint8Array>;
+    sessionRecording(sessionID: string, call?: CallOptions): Promise<Uint8Array>;
     attachSession(sessionID: string, options?: SessionAttachOptions): SessionAttachHandle;
-    uploadFile(targetPath: string, data: BinaryLike): Promise<void>;
-    downloadFile(targetPath: string): Promise<Uint8Array>;
-    exposePort(port: number, options?: ExposePortOptions): Promise<ExposeResult>;
-    unexposePort(port: number): Promise<void>;
+    /** Copy a local folder into the sandbox (Node.js only). See {@link APIClient.uploadDir}. */
+    uploadDir(localDir: string, remoteDir: string, call?: CallOptions): Promise<void>;
+    /** Upload a file. See {@link UploadFileOptions} for append, create-only, atomic and mode. */
+    uploadFile(targetPath: string, data: BinaryLike, options?: UploadFileOptions, call?: CallOptions): Promise<void>;
+    downloadFile(targetPath: string, options?: DownloadFileOptions, call?: CallOptions): Promise<Uint8Array>;
+    /** Read a file as a stream. See {@link APIClient.downloadFileStream}. */
+    downloadFileStream(targetPath: string, options?: DownloadFileOptions, call?: CallOptions): Promise<ReadableStream<Uint8Array>>;
+    /** Upload from a stream, sent once. See {@link APIClient.uploadFileStream}. */
+    uploadFileStream(targetPath: string, data: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>, options?: UploadFileOptions, call?: CallOptions): Promise<void>;
+    /** List a folder. See {@link ListFilesOptions}; `truncated` means more entries exist. */
+    listFiles(path: string, options?: ListFilesOptions, call?: CallOptions): Promise<FileList>;
+    /** Describe one path. A symlink is followed. */
+    getFileInfo(path: string, call?: CallOptions): Promise<FileInfo>;
+    /** Whether a path exists. A missing sandbox throws; it is not `false`. */
+    fileExists(path: string, call?: CallOptions): Promise<boolean>;
+    /** Delete a file, or a folder and its contents with `recursive: true`. */
+    deleteFile(path: string, options?: DeleteFileOptions, call?: CallOptions): Promise<void>;
+    /** Make a folder; with `parents: true`, like `mkdir -p`. */
+    makeDir(path: string, options?: MakeDirOptions, call?: CallOptions): Promise<void>;
+    /** Move or rename a file or folder. Without `overwrite`, an existing destination is refused (409). */
+    moveFile(source: string, destination: string, options?: MoveFileOptions, call?: CallOptions): Promise<void>;
+    /** Copy a file, or a folder with `recursive: true`. */
+    copyFile(source: string, destination: string, options?: CopyFileOptions, call?: CallOptions): Promise<void>;
+    /** Paths under `path` whose name matches a glob such as `*.ts`. */
+    searchFiles(path: string, pattern: string, call?: CallOptions): Promise<string[]>;
+    /** Each line under `path` that contains `text` (plain text). */
+    findInFiles(path: string, text: string, call?: CallOptions): Promise<FileMatch[]>;
+    exposePort(port: number, options?: ExposePortOptions, call?: CallOptions): Promise<ExposeResult>;
+    unexposePort(port: number, call?: CallOptions): Promise<void>;
+    /**
+     * Issue a signed token for this sandbox only, to hand to a browser or an
+     * end user. See {@link CreateSandboxTokenOptions}. Each call makes a new
+     * token; the server keeps no copy.
+     */
+    createToken(options: CreateSandboxTokenOptions, call?: CallOptions): Promise<SandboxToken>;
+    /**
+     * Make every token issued for this sandbox so far stop working, toolbox
+     * and port tokens alike. A token made after the call works. Safe to call
+     * again.
+     */
+    revokeTokens(call?: CallOptions): Promise<RevokeSandboxTokensResult>;
     /**
      * Per-sandbox custom-hostname bindings. Exposed as a namespaced accessor
      * (rather than `addCustomDomain`/`removeCustomDomain`/`listCustomDomains`
@@ -332,38 +520,39 @@ export declare class SandboxResource implements Sandbox {
      * so the closures always see the current `id` even after `refresh()`.
      */
     get customDomains(): {
-        add(hostname: string, options?: AddCustomDomainOptions): Promise<CustomDomain[]>;
-        remove(hostname: string): Promise<void>;
-        list(): Promise<CustomDomain[]>;
-        dns(): Promise<CustomDomainDNSRecords>;
+        add(hostname: string, options?: AddCustomDomainOptions, call?: CallOptions): Promise<CustomDomain[]>;
+        remove(hostname: string, call?: CallOptions): Promise<void>;
+        list(call?: CallOptions): Promise<CustomDomain[]>;
+        dns(call?: CallOptions): Promise<CustomDomainDNSRecords>;
     };
-    createSnapshot(name: string): Promise<SandboxSnapshot>;
-    start(): Promise<this>;
-    stop(): Promise<this>;
-    destroy(): Promise<void>;
-    resize(options: ResizeOptions): Promise<this>;
-    updateLifecycle(lifecycle: Lifecycle): Promise<this>;
-    getNetworkUsage(): Promise<NetworkUsage>;
-    setNetworkLimits(options: SetNetworkLimitsOptions): Promise<NetworkUsage>;
+    createSnapshot(name: string, options?: CreateSnapshotOptions, call?: CallOptions): Promise<SandboxSnapshot>;
+    start(call?: CallOptions): Promise<this>;
+    stop(call?: CallOptions): Promise<this>;
+    destroy(call?: CallOptions): Promise<void>;
+    resize(options: ResizeOptions, call?: CallOptions): Promise<this>;
+    updateLifecycle(lifecycle: Lifecycle, call?: CallOptions): Promise<this>;
+    getNetworkUsage(call?: CallOptions): Promise<NetworkUsage>;
+    setNetworkLimits(options: SetNetworkLimitsOptions, call?: CallOptions): Promise<NetworkUsage>;
     /**
      * Replaces this sandbox's egress policy while it runs. The call returns
      * once the new policy is enforced; sending the same policy again is a
      * no-op, so it is safe to retry.
      */
-    setNetworkPolicy(options: NetworkPolicyOptions): Promise<NetworkPolicy>;
+    setNetworkPolicy(options: NetworkPolicyOptions, call?: CallOptions): Promise<NetworkPolicy>;
     /**
      * Reads what this sandbox reached in learn mode and the allow list that
      * would have allowed it. A recording stays readable after the sandbox
      * switches to enforce, until it is destroyed.
      */
-    learned(): Promise<NetworkLearned>;
+    learned(call?: CallOptions): Promise<NetworkLearned>;
     /**
      * Reads this sandbox's audit log: outbound connections and egress denials
      * (`kind: "egress"`), and secret reads. Denials carry `result: "failure"`
      * and the policy `reason`.
      */
-    audit(options?: AuditOptions): Promise<AuditPage>;
+    audit(options?: AuditOptions, call?: CallOptions): Promise<AuditPage>;
     toJSON(): Sandbox;
     private apply;
 }
+export declare const WATCH_START_TIMEOUT_MS = 60000;
 export {};