disk 0.8.11 → 0.8.13

package/dist/index.d.cts

@@ -148,6 +148,48 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/disks/{id}/grep": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Constant-time parallel grep over a directory on a disk
+         * @description Searches files under a directory on the disk for lines matching a
+         *     regular expression. Listing and matching are fanned out across
+         *     ephemeral exec containers, so the request finishes within the user's
+         *     time budget regardless of the size of the directory.
+         *
+         *     The user controls cost and latency with three knobs:
+         *
+         *     - `maxDurationSeconds` is the wall-clock deadline.
+         *     - `concurrency` is the maximum number of parallel grep workers.
+         *       Higher concurrency finishes larger datasets within the deadline;
+         *       the controlplane clamps to the runtime fleet's current capacity.
+         *     - `maxResults` causes the search to short-circuit after the
+         *       aggregator has collected this many matches.
+         *
+         *     With `recursive: false` only files directly under `directory` are
+         *     searched. With `recursive: true` subdirectories are walked
+         *     breadth-first and grep workers are dispatched as soon as each level
+         *     finishes listing — listing and matching overlap.
+         *
+         *     The matches returned when stopping early on `maxResults` are a sample
+         *     of whichever workers reported first, not the lexicographically first
+         *     N. The response surfaces `stoppedReason` so callers can distinguish
+         *     completion from early termination.
+         */
+        post: operations["grepDisk"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/exec": {
         parameters: {
             query?: never;
@@ -758,6 +800,108 @@ interface components {
             success: boolean;
             data: components["schemas"]["ExecDiskResult"];
         };
+        GrepDiskRequest: {
+            /**
+             * @description Directory on the disk to search, relative to the disk root.
+             *     An empty string or "/" means the disk root.
+             * @example data/logs
+             */
+            directory: string;
+            /**
+             * @description Extended regular expression (passed to `grep -E`)
+             * @example ERROR|FATAL
+             */
+            pattern: string;
+            /**
+             * @description When true, walks subdirectories breadth-first.
+             * @default false
+             */
+            recursive: boolean;
+            /**
+             * @description Wall-clock deadline for the entire request. Capped at 30
+             *     seconds because the runtime exec container itself is bounded
+             *     at ~30s; longer requests would have their workers killed
+             *     mid-scan.
+             * @default 30
+             */
+            maxDurationSeconds: number;
+            /**
+             * @description Maximum number of parallel grep workers. Higher values finish
+             *     larger datasets within the deadline but consume more runtime
+             *     capacity. The controlplane clamps this to the fleet's
+             *     currently-available capacity.
+             * @default 50
+             */
+            concurrency: number;
+            /**
+             * @description Stop scanning once the aggregator has this many matches.
+             *     Returned matches are a sample of whichever workers reported
+             *     first, not the lexicographically first N.
+             * @default 1000
+             */
+            maxResults: number;
+        };
+        GrepMatch: {
+            /**
+             * @description Path to the file (relative to the disk root).
+             * @example data/logs/2026-05-03.log
+             */
+            file: string;
+            /**
+             * @description 1-based line number where the match occurred.
+             * @example 142
+             */
+            line: number;
+            /** @description The matching line. */
+            text: string;
+        };
+        /**
+         * @description Why the search stopped.
+         *     - `completed`: every file under the directory was scanned successfully.
+         *     - `incomplete`: pipeline ran to its natural end but one or more
+         *       batches errored (invalid regex, unreadable file, runtime issue).
+         *       Results may be partial or wrong; do not rely on completeness.
+         *     - `max_results`: hit `maxResults` before scanning everything.
+         *     - `deadline`: hit `maxDurationSeconds`.
+         *     - `list_failed`: directory listing failed; partial results
+         *       may be present.
+         * @enum {string}
+         */
+        GrepStoppedReason: "completed" | "incomplete" | "max_results" | "deadline" | "list_failed";
+        GrepDiskResult: {
+            matches: components["schemas"]["GrepMatch"][];
+            stoppedReason: components["schemas"]["GrepStoppedReason"];
+            /** @description Files actually fed to a grep container. */
+            filesScanned: number;
+            /** @description Number of grep containers started for this request. */
+            containersDispatched: number;
+            /**
+             * Format: double
+             * @description Sum of per-container execution time in seconds, measured by the
+             *     runtime. Approximates billable container-seconds.
+             */
+            computeSecondsUsed: number;
+            /** @description End-to-end wall clock measured by the server. */
+            durationMs: number;
+            /**
+             * @description Wall-clock time spent enumerating files via listObjects, from
+             *     the request's start to the moment listing fully drained (or
+             *     was canceled). Listing and matching overlap, so listingMs +
+             *     grepMs typically exceeds durationMs.
+             */
+            listingMs: number;
+            /**
+             * @description Wall-clock time spent matching, from the first grep container
+             *     being dispatched to the last container reporting results. 0 if
+             *     no batches ran.
+             */
+            grepMs: number;
+        };
+        ApiResponse_GrepDisk: {
+            /** @example true */
+            success: boolean;
+            data: components["schemas"]["GrepDiskResult"];
+        };
     };
     responses: {
         /** @description Invalid or missing authentication credentials */
@@ -1119,6 +1263,37 @@ interface operations {
             };
         };
     };
+    grepDisk: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Disk ID (format `dsk-{16 hex chars}`) */
+                id: components["parameters"]["DiskId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["GrepDiskRequest"];
+            };
+        };
+        responses: {
+            /** @description Grep completed (possibly stopped early) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiResponse_GrepDisk"];
+                };
+            };
+            400: components["responses"]["ValidationError"];
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+            500: components["responses"]["InternalError"];
+        };
+    };
     exec: {
         parameters: {
             query?: never;
@@ -1260,6 +1435,9 @@ type CreateApiTokenRequest = components["schemas"]["CreateApiTokenRequest"];
 type ApiTokenResponse = components["schemas"]["ApiTokenResponse"];
 type ExecDiskResult = components["schemas"]["ExecDiskResult"];
 type ExecRequest = components["schemas"]["ExecRequest"];
+type GrepDiskResult = components["schemas"]["GrepDiskResult"];
+type GrepMatch = components["schemas"]["GrepMatch"];
+type GrepStoppedReason = components["schemas"]["GrepStoppedReason"];
 type DiskStatus = DiskResponse["status"];
 
 interface MountOptions {
@@ -1269,6 +1447,112 @@ interface MountOptions {
     insecure?: boolean;
 }
 type ExecResult = ExecDiskResult;
+type GrepResult = GrepDiskResult;
+
+interface GrepOptions {
+    /**
+     * Directory on the disk to search, relative to the disk root. An empty
+     * string or "/" means the disk root.
+     */
+    directory: string;
+    /** Extended regular expression (passed to `grep -E`). */
+    pattern: string;
+    /** Walk subdirectories breadth-first. Defaults to false. */
+    recursive?: boolean;
+    /** Wall-clock deadline for the entire request. Defaults to 30s. */
+    maxDurationSeconds?: number;
+    /**
+     * Maximum number of parallel grep workers. Higher values finish larger
+     * datasets within the deadline but consume more runtime capacity. The
+     * controlplane clamps this to the fleet's currently-available capacity.
+     * Defaults to 50.
+     */
+    concurrency?: number;
+    /**
+     * Stop scanning once the aggregator has this many matches. Returned
+     * matches are a sample of whichever workers reported first, not the
+     * lexicographically first N. Defaults to 1000.
+     */
+    maxResults?: number;
+}
+interface ShareUrlOptions {
+    /**
+     * Lifetime of the URL in seconds — any positive integer, up to 604800
+     * (7 days). Defaults to 86400 (24 hours).
+     */
+    expiresIn?: number;
+}
+interface ShareUrlResult {
+    /** Public, signed, time-limited URL that downloads the file. */
+    url: string;
+    /** Lifetime of the URL in seconds. */
+    expiresIn: number;
+}
+interface ListObjectsOptions {
+    /**
+     * List the entire subtree under the prefix. When false (the default), only
+     * the immediate level is returned — direct objects in `objects` and
+     * subdirectory prefixes in `commonPrefixes`, like listing a single directory.
+     * When true, every key under the prefix is returned flat (and
+     * `commonPrefixes` is empty).
+     */
+    recursive?: boolean;
+    /**
+     * Return only the first page instead of auto-paginating. By default
+     * listObjects follows continuation tokens until the listing is exhausted and
+     * returns every matching key. With `singlePage: true` it makes one request
+     * and the result carries `isTruncated` / `nextContinuationToken` so you can
+     * page manually (pass the token back via `continuationToken`).
+     */
+    singlePage?: boolean;
+    /**
+     * Stop after this many objects total (only meaningful when auto-paginating).
+     * The result's `isTruncated` is true if the cap cut the listing short.
+     */
+    limit?: number;
+    /** Start listing from this continuation token (from a prior `nextContinuationToken`). */
+    continuationToken?: string;
+    /** Return keys lexicographically after this one. */
+    startAfter?: string;
+}
+interface S3Object {
+    /** Object key (path on the disk). */
+    key: string;
+    /** Size in bytes. */
+    size: number;
+    /** Entity tag (quoted MD5 for single-part objects). */
+    etag?: string;
+    /** Last-modified time, if reported by the server. */
+    lastModified?: Date;
+}
+interface PutObjectResult {
+    /** Entity tag the server assigned (quoted, per S3 — e.g. `"\"abc123\""`). */
+    etag?: string;
+}
+interface ObjectMetadata {
+    /** Size in bytes. */
+    size: number;
+    /** Entity tag (quoted MD5 for single-part objects). */
+    etag?: string;
+    /** MIME type the object was stored with, if any. */
+    contentType?: string;
+    /** Last-modified time, if reported by the server. */
+    lastModified?: Date;
+}
+interface ListObjectsResult {
+    /** Objects in this page. */
+    objects: S3Object[];
+    /** Directory-like prefixes rolled up by `delimiter` (empty if no delimiter). */
+    commonPrefixes: string[];
+    /** True if more keys exist beyond this page. */
+    isTruncated: boolean;
+    /** Token to pass as `continuationToken` to fetch the next page. */
+    nextContinuationToken?: string;
+    /** Number of keys returned in this page. */
+    keyCount: number;
+    /** The prefix the listing was filtered by, echoed back by the server. */
+    prefix?: string;
+}
 declare class Disk {
     readonly id: string;
     readonly name: string;
@@ -1290,8 +1574,10 @@ declare class Disk {
     private readonly _client;
     /** @internal */
     private readonly _archilRegion;
+    /** Base URL for the S3-compatible API (port 9000 ingress). Empty if unset. */
+    private readonly _s3BaseUrl;
     /** @internal */
-    constructor(data: DiskResponse, client: ApiClient, archilRegion: string);
+    constructor(data: DiskResponse, client: ApiClient, archilRegion: string, s3BaseUrl?: string);
     toJSON(): DiskResponse;
     addUser(user: DiskUser): Promise<AuthorizedUser>;
     removeUser(userType: "token" | "awssts", identifier: string): Promise<void>;
@@ -1310,6 +1596,108 @@ declare class Disk {
      * Blocks until the command completes and returns stdout, stderr, and exit code.
      */
     exec(command: string): Promise<ExecResult>;
+    /**
+     * Constant-time parallel grep across files on this disk. Listing and
+     * matching are fanned out across ephemeral exec containers; the request
+     * finishes within the supplied time budget regardless of dataset size.
+     *
+     * The returned `stoppedReason` says whether the search ran to completion
+     * or short-circuited on `maxResults` / `maxDurationSeconds`. When
+     * stopping early, the matches returned are a sample (whichever workers
+     * reported first), not the lexicographically first N.
+     */
+    grep(opts: GrepOptions): Promise<GrepResult>;
+    /**
+     * Create a signed, time-limited URL that lets anyone download a single file
+     * from this disk without authentication. The returned URL embeds a
+     * cryptographically signed token carrying the disk, the file's key, and an
+     * expiry — share it directly; no API key is needed to redeem it.
+     *
+     * @param key   Path to the file on the disk (e.g. "reports/2026-01/data.pdf").
+     * @param opts  `expiresIn` sets the URL lifetime in seconds (any positive
+     *              integer, max 604800 = 7 days). Defaults to 24h.
+     */
+    share(key: string, opts?: ShareUrlOptions): Promise<ShareUrlResult>;
+    /**
+     * Read an object from the disk via the S3-compatible GetObject API and return
+     * its full contents as bytes. Throws `ArchilS3Error` if the object does not
+     * exist (status 404, code "NoSuchKey") or the request is rejected; use
+     * `headObject`/`objectExists` to check existence without throwing.
+     *
+     * @param key  Path on the disk (e.g. "reports/2026-01/data.json")
+     */
+    getObject(key: string): Promise<Uint8Array>;
+    /**
+     * Fetch an object's metadata (size, etag, content type, last-modified) without
+     * downloading its contents, via the S3-compatible HeadObject API. Returns
+     * `null` if the object does not exist.
+     *
+     * @param key  Path on the disk (e.g. "reports/2026-01/data.json")
+     */
+    headObject(key: string): Promise<ObjectMetadata | null>;
+    /** Whether an object exists on the disk (a HeadObject that maps 404 → false). */
+    objectExists(key: string): Promise<boolean>;
+    /**
+     * Write an object to the disk using the S3-compatible PutObject API. Faster
+     * than exec for large files — no container overhead, no command-length limits.
+     * Returns the entity tag the server assigned.
+     *
+     * @param key          Path on the disk (e.g. "reports/2026-01/data.json")
+     * @param body         Contents as a string, Uint8Array/Buffer, or ArrayBuffer
+     * @param contentType  MIME type (default: "application/octet-stream")
+     */
+    putObject(key: string, body: string | Uint8Array | ArrayBuffer, contentType?: string): Promise<PutObjectResult>;
+    /**
+     * Delete an object from the disk via the S3-compatible DeleteObject API.
+     * Idempotent: deleting a key that doesn't exist resolves successfully, per
+     * S3 semantics.
+     *
+     * @param key  Path on the disk (e.g. "project/dist/server.cjs")
+     */
+    deleteObject(key: string): Promise<void>;
+    /**
+     * List objects on the disk via the S3-compatible ListObjectsV2 API. By
+     * default this follows continuation tokens until the listing is exhausted and
+     * returns every matching key. Use `limit` to cap the total, `singlePage` for a
+     * single request, or {@link listObjectsPages} to stream pages without loading
+     * everything into memory.
+     *
+     * @param prefix  Only return keys beginning with this prefix (omit for all).
+     * @param opts    Listing and pagination options.
+     */
+    listObjects(prefix?: string, opts?: ListObjectsOptions): Promise<ListObjectsResult>;
+    /**
+     * Yield ListObjectsV2 pages lazily, following continuation tokens. A
+     * memory-friendly way to process a large listing without materializing it:
+     *
+     * ```ts
+     * for await (const page of disk.listObjectsPages("logs/")) {
+     *   for (const obj of page.objects) process(obj);
+     * }
+     * ```
+     *
+     * @param prefix  Only return keys beginning with this prefix (omit for all).
+     * @param opts    Listing options (`limit` / `singlePage` are ignored here —
+     *                control your own loop).
+     */
+    listObjectsPages(prefix?: string, opts?: ListObjectsOptions): AsyncGenerator<ListObjectsResult>;
+    /** Fetch a single ListObjectsV2 page. @internal */
+    private _listObjectsPage;
+    /**
+     * Send a single request to the disk's S3-compatible endpoint. This reuses the
+     * control-plane client purely for its credential and transport — the same
+     * `Authorization` header is sent and verified by the same code server-side —
+     * pointed at the S3 host. Returns the response status and fully-buffered body
+     * so callers can inspect both regardless of the verb used.
+     *
+     * The S3 routes (`/{diskId}/{key}` for objects, `/{diskId}` for the bucket)
+     * are not part of the typed control-plane API, so the path and per-request
+     * options are passed untyped. An empty `key` targets the bucket itself (used
+     * by listObjects).
+     *
+     * @internal
+     */
+    private _s3Request;
     /**
      * Connect to this disk's data plane via the native ArchilClient.
      *
@@ -1335,7 +1723,9 @@ declare class Disks {
     /** @internal */
     private readonly _region;
     /** @internal */
-    constructor(client: ApiClient, region: string);
+    private readonly _s3BaseUrl?;
+    /** @internal */
+    constructor(client: ApiClient, region: string, s3BaseUrl?: string);
     list(opts?: ListDisksOptions): Promise<Disk[]>;
     get(id: string): Promise<Disk>;
     /**
@@ -1370,6 +1760,12 @@ interface ArchilOptions {
     region?: string;
     /** Override the control plane base URL (useful for testing). */
     baseUrl?: string;
+    /**
+     * Override the S3-compatible API base URL used by Disk#getObject /
+     * putObject / deleteObject. Falls back to ARCHIL_S3_BASE_URL, then to the
+     * control plane URL with its `control.` hostname prefix swapped for `s3.`.
+     */
+    s3BaseUrl?: string;
 }
 /**
  * Options that apply to a single mounted disk in an exec request.
@@ -1424,11 +1820,46 @@ declare class Archil {
     exec(opts: ExecOptions): Promise<ExecDiskResult>;
 }
 
-declare class ArchilApiError extends Error {
+/**
+ * Base class for every error the SDK throws. Catch with `instanceof ArchilError`
+ * to handle control-plane and S3 failures uniformly; `status` is the HTTP status
+ * code and `code` a machine-readable error code when the server provided one.
+ */
+declare class ArchilError extends Error {
+    /** HTTP status code associated with the failure. */
     readonly status: number;
+    /** Machine-readable error code (e.g. an S3 code like "NoSuchKey"), if known. */
     readonly code?: string;
     constructor(message: string, status: number, code?: string);
 }
+/** Error from the control-plane REST API. */
+declare class ArchilApiError extends ArchilError {
+    constructor(message: string, status: number, code?: string);
+}
+/**
+ * Error from the S3-compatible object API (getObject/putObject/deleteObject/
+ * headObject/listObjects). The gateway returns an S3-style XML `<Error>` body;
+ * this surfaces its parts as structured fields (`status`, `code`, `requestId`)
+ * rather than a raw blob, while keeping the full body on `raw` for debugging.
+ */
+declare class ArchilS3Error extends ArchilError {
+    /** S3 request id, if the gateway returned one. */
+    readonly requestId?: string;
+    /** Raw response body (the XML document), for debugging. */
+    readonly raw: string;
+    constructor(opts: {
+        operation: string;
+        statusCode: number;
+        statusText?: string;
+        code?: string;
+        message?: string;
+        requestId?: string;
+        raw: string;
+    });
+}
+
+declare const VERSION: string;
+declare const USER_AGENT: string;
 
 declare function configure(options: ArchilOptions): void;
 declare function createDisk(req: CreateDiskRequest): Promise<CreateDiskResult>;
@@ -1446,4 +1877,4 @@ declare function deleteApiKey(id: string): Promise<void>;
  */
 declare function exec(opts: ExecOptions): Promise<ExecDiskResult>;
 
-export { type ApiTokenResponse, Archil, ArchilApiError, type ArchilOptions, type AuthorizedUser, type AwsStsUser, type AzureBlobMount, type ConnectedClient, type CreateApiTokenRequest, type CreateDiskRequest, type CreateDiskResult, Disk, type DiskMetrics, type DiskResponse, type DiskStatus, type DiskUser, Disks, type ExecMount, type ExecMountSpec, type ExecOptions, type ExecRequest, type ExecResult, type GCSMount, type ListDisksOptions, type ListTokensOptions, type MountConfig, type MountConfigResponse, type MountOptions, type MountResponse, type R2Mount, type S3CompatibleMount, type S3Mount, type TokenUser, Tokens, configure, createApiKey, createDisk, deleteApiKey, exec, getDisk, listApiKeys, listDisks };
+export { type ApiTokenResponse, Archil, ArchilApiError, ArchilError, type ArchilOptions, ArchilS3Error, type AuthorizedUser, type AwsStsUser, type AzureBlobMount, type ConnectedClient, type CreateApiTokenRequest, type CreateDiskRequest, type CreateDiskResult, Disk, type DiskMetrics, type DiskResponse, type DiskStatus, type DiskUser, Disks, type ExecMount, type ExecMountSpec, type ExecOptions, type ExecRequest, type ExecResult, type GCSMount, type GrepMatch, type GrepOptions, type GrepResult, type GrepStoppedReason, type ListDisksOptions, type ListObjectsOptions, type ListObjectsResult, type ListTokensOptions, type MountConfig, type MountConfigResponse, type MountOptions, type MountResponse, type ObjectMetadata, type PutObjectResult, type R2Mount, type S3CompatibleMount, type S3Mount, type S3Object, type ShareUrlOptions, type ShareUrlResult, type TokenUser, Tokens, USER_AGENT, VERSION, configure, createApiKey, createDisk, deleteApiKey, exec, getDisk, listApiKeys, listDisks };