@cloudbitmaps/s3 0.21.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbitmaps/s3",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "S3 and S3-compatible storage (R2, MinIO, Ceph, Wasabi, B2) for CloudBitmaps",
   "keywords": [
     "cloudbitmaps",
@@ -40,7 +40,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -53,7 +54,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": ">=3.700.0 <4",
-    "@cloudbitmaps/core": "^0.21.0"
+    "@cloudbitmaps/core": "0.23.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/dist/aws-errors.d.ts

@@ -1,13 +0,0 @@
-export declare function httpStatus(err: unknown): number | undefined;
-export declare function errorName(err: unknown): string | undefined;
-/** A lower-level transport code (e.g. `ECONNRESET`) — the Node networking layer sets `code`. */
-export declare function errorCode(err: unknown): string | undefined;
-/** The AWS SDK v3 tags retryable errors with a `$retryable` object (throttling faults carry `.throttling`). */
-export declare function isSdkRetryable(err: unknown): boolean;
-/** Any 5xx is a server-side fault that's safe to retry (the request didn't deterministically fail). */
-export declare function isServerSide(err: unknown): boolean;
-/**
- * A dropped/timed-out connection — transient by nature; a retry on a fresh connection usually succeeds. The SDK's
- * transport error names, the codes Node gives a failed connection ({@link isTransportFault}), and the messages above.
- */
-export declare function isNetworkOrTimeout(err: unknown): boolean;

package/dist/bounded-body.d.ts

@@ -1,15 +0,0 @@
-/** The `GetObject` response body, narrowed to the parts used. */
-type ResponseBody = {
-    transformToByteArray?: () => Promise<Uint8Array>;
-    [Symbol.asyncIterator]?: () => AsyncIterator<unknown>;
-    destroy?: () => void;
-} | undefined;
-/** Destroy a response body left unread, which releases its connection; a body with no `destroy` is left alone. */
-export declare function destroyBody(body: unknown): void;
-/**
- * The body's bytes, at most `maxBytes` of them. `oversize` builds the typed error thrown when the count passes
- * `maxBytes`, or when the response advertises more than that before a byte is read; any other failure of the stream
- * propagates as it is.
- */
-export declare function readBounded(body: ResponseBody, maxBytes: number, oversize: () => Error, advertised?: number): Promise<Uint8Array>;
-export {};

package/dist/client-probe.d.ts

@@ -1,36 +0,0 @@
-import type { S3Client } from '@aws-sdk/client-s3';
-/** What a client does with the requests the registry sends. */
-export interface ClientFacts {
-    /** The host a request to the bucket is addressed to, as the client resolves it now. */
-    readonly host: string;
-    /** Whether a `DeleteObject` given `IfMatch` goes out with an `If-Match` header. */
-    readonly sendsDeleteIfMatch: boolean;
-    /** Whether a `PutObject` given `IfMatch` goes out with an `If-Match` header: the registry's compare-and-swap. */
-    readonly sendsPutIfMatch: boolean;
-    /** Whether a `PutObject` given `IfNoneMatch` goes out with an `If-None-Match` header: the registry's create. */
-    readonly sendsPutIfNoneMatch: boolean;
-}
-/** A key no registry row or generation can hold; the probe's requests are never sent, so it is never used. */
-export declare const PROBE_KEY = "cloudbitmaps-probe";
-/**
- * What `client` does with a conditional `DeleteObject` and `PutObject` to `bucket`, or `undefined` when it cannot be
- * found out. Never throws, never sends a request, and never runs anything the caller added to `client`.
- */
-export declare function probeClient(client: S3Client, bucket: string): Promise<ClientFacts | undefined>;
-/**
- * Whether a `DeleteObject` may rely on `If-Match`, for the registry's row delete and the storage half's conditional
- * delete alike: `explicit` when the caller set it, but never for an SDK seen not to send the header; otherwise only
- * when the client resolves to an AWS S3 host, which applies the precondition, and `false` until the client has been
- * asked, since an S3-compatible store (MinIO, for one) can accept the header and ignore it.
- */
-export declare function appliesDeleteIfMatch(explicit: boolean | undefined, facts: ClientFacts | undefined): boolean;
-/**
- * Whether `hostname` is an AWS S3 host, by its structure: under an AWS domain, with a label that names S3 (`s3`,
- * `s3-fips`, an access point's, a multi-region access point's `s3-global`, Object Lambda's, an Outpost's, a dash-joined
- * `s3-<region>`, a directory bucket's `s3express-…`), followed only by what S3's hosts put there: `dualstack`, a
- * region and `vpce`, in that order. Anything may come before it (a bucket, an access point, a VPC endpoint id). So
- * the FIPS, dual-stack, access-point and VPC interface forms all count, and another AWS service's host whose name
- * starts with `s3` does not: a load balancer, an API Gateway, a website endpoint. A host of any other domain is not,
- * whatever it speaks: a store behind one has to be vouched for by the caller.
- */
-export declare function isAwsS3Host(hostname: string): boolean;

package/dist/defined.d.ts

@@ -1,8 +0,0 @@
-/**
- * `values` without the entries that are `undefined`, typed as optional properties, so a constructor can pass on the
- * options it was given: `exactOptionalPropertyTypes` refuses `{ x: undefined }` for an optional `x`, and a sub-driver
- * must see an option the caller left out as absent.
- */
-export declare function defined<T extends Record<string, unknown>>(values: T): {
-    [K in keyof T]?: Exclude<T[K], undefined>;
-};

package/dist/read-timeout.d.ts

@@ -1,11 +0,0 @@
-/** Validate a caller's `readTimeoutMs`, defaulting it: an integer from 0 (no timeout) to {@link MAX_TIMER_MS}. */
-export declare function resolveReadTimeoutMs(value: number | undefined): number;
-/** The options a timed read passes to its `client.send`: the abort signal, or nothing when the timeout is off. */
-export type ReadSendOptions = {
-    readonly abortSignal: AbortSignal;
-} | undefined;
-/**
- * Run `read` under a `timeoutMs` timer (`0`: none). `read` passes `options` to its `client.send` and reads the body
- * before it returns, so the timer covers both. The timer is cleared when the read settles.
- */
-export declare function timedRead<T>(operation: 'GetObject' | 'HeadObject', timeoutMs: number, read: (options: ReadSendOptions) => Promise<T>): Promise<T>;

package/dist/registry.d.ts

@@ -1,118 +0,0 @@
-/**
- * `S3RegistryDriver` — an {@link IRegistryDriver} over S3-compatible object storage.
- *
- * Lets a **read-mostly deployment run on S3 alone** — storage `.crbm` generations + the registry in one bucket,
- * no separate database. The protocol (an ABA-safe OCC token, the delete and its tombstone, the bounded retry, the key
- * layout) lives once in {@link ObjectStoreRegistry}; this file is only the I/O calls S3 makes, so the S3, GCS
- * and Azure registries cannot drift from one another.
- *
- * **A delete removes the row for good** with a `DeleteObject` under `If-Match: <etag>`, sent once like the writes,
- * when `conditionalDelete` is on. By default it is on when the host the client resolves is an AWS S3 host, whichever way
- * the endpoint was set (a constructor `endpoint`, `AWS_ENDPOINT_URL_S3`, `AWS_ENDPOINT_URL`, the shared config file), and
- * off for any other, since an S3-compatible store may accept the header and ignore it (MinIO does). The client is asked
- * once, before the registry's first request, and the SDK is checked to send the header at all ({@link probeClient}).
- *
- * **The atomic swap is offloaded to S3's conditional writes** (GA Nov 2024): `If-None-Match: *` for
- * create-only and `If-Match: <etag>` for compare-and-swap, so a concurrent writer between our read and our
- * PUT loses with a `412` → {@link WriteConflictError}. Each conditional PUT is sent once, with the SDK's retry off
- * for it ({@link sendOnce}), so a `412` means another write got there first, never this one meeting itself after a
- * lost response. A transient failure reaches the caller as {@link TransientError}: the write may or may not have
- * landed, and the caller re-reads the row to learn where it stands. Reads are strongly consistent (S3, since 2020),
- * satisfying the registry's `strongRead` contract, and each can be timed as the storage driver's are ({@link timedRead}):
- * with `readTimeoutMs` set, a row's `GetObject` that has not finished, body included, after it throws
- * {@link TransientError}. It is off by default, and the writes and listings are never timed. The client is **injected**, exactly like {@link S3StorageDriver}.
- *
- * **Deployment requirements** (a backend/policy that violates these silently corrupts the registry):
- * - The backend **must honor `If-Match`** (AWS S3; recent MinIO). One that returns ETags but ignores the
- *   precondition degrades compare-and-swap to last-write-wins → lost `currentGen` swaps. Verified against
- *   real S3 semantics by the MinIO integration lane.
- * - The IAM principal needs **`s3:ListBucket`** on the bucket. Without it, `GetObject` on a missing key
- *   returns `403` (not `404`), so the "absent segment → `null`" contract (and `create`'s bootstrap read)
- *   breaks — and `list()` needs it regardless.
- * - **Do not apply an S3 lifecycle-expiration rule to the `registry/` prefix that expires a current version**
- *   (`NoncurrentVersionExpiration` is safe). See {@link ObjectStoreRegistry}.
- */
-import { ObjectStoreRegistry } from '@cloudbitmaps/core/driver-kit';
-import type { ObjectRegistryStore, ObjectRow } from '@cloudbitmaps/core/driver-kit';
-import { type S3Client } from '@aws-sdk/client-s3';
-interface S3RegistryDriverOptions {
-    /** A constructed S3 client (point its `endpoint` at MinIO for local/integration use). */
-    readonly client: S3Client;
-    /** Target bucket (must already exist). */
-    readonly bucket: string;
-    /** Optional key prefix under which all registry objects live (e.g. `cloudbitmaps/`). */
-    readonly prefix?: string;
-    /** Injected clock for `createdAt`/`updatedAt`; defaults to `Date.now`. */
-    readonly now?: () => number;
-    /**
-     * How long one read of a row — its `GetObject`, the body included — may take before it is abandoned and throws
-     * `TransientError`, in ms. `0`, the default, sets no timeout. Must be a non-negative safe integer no larger than
-     * 2,147,483,647. Writes and listings are not timed.
-     *
-     * The clock starts when the read is handed to the SDK, so it also counts the time the read waits for one of the
-     * client's sockets (128 by default on the client the store builds, 50 on the SDK's own) and the time spent fetching
-     * credentials, and under `retryMode: 'adaptive'` the SDK's rate-limiter wait. A burst of concurrent reads larger than
-     * the socket pool can therefore time out with nothing slow on the wire: size the timeout above the worst queueing
-     * your concurrency implies, or raise `maxSockets` (the store's option, or your own client's). On a client built with
-     * `cacheMiddleware: true`, a timed read resolves its middleware each time.
-     */
-    readonly readTimeoutMs?: number;
-    /**
-     * Whether a delete removes a row for good, by a `DeleteObject` sent with `If-Match: <the ETag it read>`, rather than
-     * leaving a tombstone.
-     *
-     * Defaults to `true` when the host the client resolves is an AWS S3 host (`*.amazonaws.com`, `*.amazonaws.com.cn`: the
-     * FIPS, dual-stack, access-point and VPC interface forms included), where `If-Match` on `DeleteObject` is documented
-     * for general purpose and directory buckets, and to `false` for any other host, or when the host cannot be resolved.
-     * The host is the one the SDK resolves for a request, so an endpoint set through `AWS_ENDPOINT_URL_S3`,
-     * `AWS_ENDPOINT_URL` or an `endpoint_url` in the shared config file counts exactly as a constructor `endpoint` does.
-     * It is resolved once, lazily: until the registry's first read or listing the answer reads `false`, and a client that
-     * cannot be resolved then (no region) keeps tombstoning for the life of the registry, so set the
-     * option to override it.
-     *
-     * Set it explicitly to override the host. An S3-compatible store must apply the precondition before you set it there:
-     * MinIO, for one, ignores it and deletes anyway, and on such a store two sweepers and a re-create can delete a live
-     * row. A `true` never overrides the SDK: one that does not send `If-Match` on a `DeleteObject` leaves the row
-     * tombstoned whatever is set.
-     */
-    readonly conditionalDelete?: boolean;
-}
-/**
- * The calls {@link ObjectStoreRegistry} needs, in S3's dialect. Exported for the tests that drive one directly.
- *
- * `conditionalDelete` is the caller's explicit setting, or `undefined` to follow the client. What the client does is
- * found out once, before the first read, listing or write ({@link probeClient}), so by the time the registry decides
- * how to delete it has been.
- */
-export declare class S3RegistryStore implements ObjectRegistryStore {
-    private readonly client;
-    private readonly bucket;
-    private readonly readTimeoutMs;
-    private readonly explicitConditionalDelete?;
-    readonly label = "S3";
-    private probed;
-    private facts;
-    constructor(client: S3Client, bucket: string, readTimeoutMs: number, explicitConditionalDelete?: boolean | undefined);
-    /**
-     * Whether a delete may rely on `If-Match`: the caller's setting, else whether the client's host is AWS S3, and in
-     * neither case when the SDK is seen not to send the header. `false` until the client has been asked, unless the caller
-     * vouched for the store.
-     */
-    get conditionalDelete(): boolean;
-    /** Ask the client once what it does with the registry's requests; every caller waits for the same answer. */
-    private settle;
-    /** Refuse a write the SDK would send without its precondition: it would land as a plain overwrite. */
-    private refuseUnfencedWrites;
-    read(key: string): Promise<ObjectRow | null>;
-    write(key: string, body: Uint8Array, expect: 'absent' | {
-        version: string;
-    }): Promise<void>;
-    delete(key: string, expect: {
-        version: string;
-    }): Promise<void>;
-    listKeys(prefix: string): AsyncIterable<string>;
-}
-export declare class S3RegistryDriver extends ObjectStoreRegistry {
-    constructor(options: S3RegistryDriverOptions);
-}
-export {};

package/dist/s3-errors.d.ts

@@ -1,66 +0,0 @@
-/**
- * Pure helpers for classifying S3 SDK errors + parsing response headers (conflict and transient classification).
- *
- * Kept SDK-free and side-effect-free (they only read structural shapes — `err.name`,
- * `$metadata.httpStatusCode`, a `Content-Range` string) so the subtle S3-specific translation logic is
- * unit-testable without a live MinIO/S3 or even the AWS SDK. The AWS error shapes come from `./aws-errors`.
- */
-/** A conditional `If-None-Match: *` PUT lost the write-once race (the object already existed). */
-export declare function isPreconditionFailed(err: unknown): boolean;
-/**
- * A conditional write (`If-None-Match: *` / `If-Match: <etag>`) lost the race — **either** outcome S3 uses:
- * the precondition evaluated false (`412 PreconditionFailed`), **or** S3 rejected concurrent conditional
- * writes to the same key to prevent a lost update (`409 ConditionalRequestConflict`, which AWS documents and
- * asks you to retry). Both mean "you lost; re-read and retry" — so both must map to `WriteConflictError` and
- * route through the caller's OCC path, never a blind transient retry (which would just replay a doomed PUT).
- */
-export declare function isConditionalConflict(err: unknown): boolean;
-/**
- * S3 asked the client to slow down: `503 SlowDown`, or any other `503` (`ServiceUnavailable`). The SDK raises it with
- * `name` set to the code and `$metadata.httpStatusCode` to 503, and no `$retryable` marker. S3 does not document that a
- * throttled request was not applied, so a write sent again after one must still tell a landed first send apart.
- */
-export declare function isThrottle(err: unknown): boolean;
-/** A multipart upload id S3 no longer knows: completed, aborted or expired (`404 NoSuchUpload`). */
-export declare function isNoSuchUpload(err: unknown): boolean;
-/**
- * The bucket itself does not exist (`404 NoSuchBucket`): a wiring fault, never an absent object. Read as one, a
- * misnamed or deleted bucket would answer every read as an empty segment. A HEAD carries no code, so it cannot be told
- * apart there; every request that reaches a missing bucket with a body says so.
- */
-export declare function isMissingBucket(err: unknown): boolean;
-/**
- * `err`, or the {@link ValidationError} a missing bucket is: it names the bucket and what to check, and carries the
- * service's error as its `cause`. A wiring fault is not an absent object, so it is not a `NotFoundError`: a read
- * re-resolves on that, and would treat a misnamed bucket as a miss it can heal.
- */
-export declare function asMissingBucket(err: unknown, bucket: string): unknown;
-/**
- * The object / generation does not exist (GetObject → `NoSuchKey`, HeadObject → `NotFound`; both 404), in a bucket
- * that does: a 404 that says the bucket is missing is not one.
- */
-export declare function isNotFound(err: unknown): boolean;
-/** A range request started past EOF (HTTP 416). */
-export declare function isInvalidRange(err: unknown): boolean;
-/**
- * A transient S3 fault that is safe to retry: throttling (`SlowDown` / 503), any 5xx, a dropped/timed-out
- * connection, a clock-skew refusal the SDK has corrected for, or anything the SDK itself marks retryable. Excludes
- * the deterministic outcomes above (412/404/416) — those are caller-meaningful and must never be
- * retried/reclassified.
- */
-export declare function isTransient(err: unknown): boolean;
-/**
- * The message a transient S3 fault is handed on with: `transient S3 fault: <name>`, the SDK error's name, which names
- * S3's error code (`SlowDown`, `InternalError`) or the transport failure (`TimeoutError`).
- */
-export declare function transientFaultMessage(err: unknown): string;
-/** The first and last byte a `Content-Range: bytes <start>-<end>/<total>` header names, or `undefined` if unparseable. */
-export declare function spanFromContentRange(contentRange: string | undefined): {
-    start: number;
-    end: number;
-} | undefined;
-/**
- * Parse the total object size out of a `Content-Range: bytes <start>-<end>/<total>` header, or `undefined`
- * if absent/unparseable/unsafe. The total is the part after the final `/`.
- */
-export declare function totalFromContentRange(contentRange: string | undefined): number | undefined;

package/dist/scrub-error.d.ts

@@ -1,12 +0,0 @@
-/**
- * Remove credentials from an error the AWS SDK raised, before the driver throws it or keeps it as a `cause`.
- *
- * The SDK keeps the HTTP response it got on the error (`$response`), and through its socket the request it sent, with
- * the signed `Authorization` header and `x-amz-security-token`, on properties `util.inspect` shows only with
- * `showHidden`. Those objects are live (a socket still closing reads them), so they are never changed: the error is
- * replaced by a copy that has none of them (an error with none is returned as it is). The copy keeps its prototype, name, message, stack, status, code, request
- * id and every other plain field, so classification by name, code or status works on it as on the original. A
- * credential header or header line left anywhere in the copy's plain data is redacted.
- */
-/** `err` as it is safe to throw: a credential-free copy of an error object, any other value as it is. */
-export declare function scrubCredentials<T>(err: T): T;

package/dist/send-once.d.ts

@@ -1,23 +0,0 @@
-/**
- * `sendOnce` — send a conditional write exactly once, with the SDK's retry off for that one command.
- *
- * The SDK re-sends a request whose response it did not get: a timeout, a reset connection, a 5xx. For a conditional
- * write that is the wrong thing to do. When the write landed and only its response was lost, the second send meets
- * the first — `If-None-Match: *` finds the object it created, `If-Match` finds the ETag it replaced — and fails with
- * `412`, which the driver can only report as a lost race. The caller is told its write lost when it won. Only the
- * caller can find out which happened, by reading the pointer or listing the generations, so the write is sent once
- * and a transient failure reaches it as `TransientError`.
- *
- * **How.** The client runs its retry as one middleware, `retryMiddleware`, at high priority in the `finalizeRequest`
- * step, whatever retry strategy or `maxAttempts` it was built with. When a command is sent, its own middleware stack
- * is merged over the client's, and an entry with the same name, step and priority that sets `override` replaces the
- * client's. So this command runs with a pass-through where the retry was, and nothing about the client changes: a
- * caller's own client keeps its configuration, and every other command sent through it keeps its retry.
- *
- * The options object passed to `send` matters too. A client built with `cacheMiddleware: true` reuses the handler it
- * resolved for the first command of a class, and that handler holds the retry; `send` resolves afresh whenever it is
- * given options, so the replacement always takes effect.
- */
-import type { $Command, S3Client, S3ClientResolvedConfig, ServiceInputTypes, ServiceOutputTypes } from '@aws-sdk/client-s3';
-/** Send `command` once: its retry step is a pass-through, and the client's stays as it is for every other command. */
-export declare function sendOnce<Input extends ServiceInputTypes, Output extends ServiceOutputTypes>(client: S3Client, command: $Command<Input, Output, S3ClientResolvedConfig, ServiceInputTypes, ServiceOutputTypes>): Promise<Output>;

package/dist/socket-advisory.d.ts

@@ -1,57 +0,0 @@
-/**
- * The socket-pool advisory: once the first read has run, the SDK's own request handler has made its agents and its
- * public `httpHandlerConfigs()` reports their `maxSockets`. A pool smaller than twice the default window of a combine
- * (32 ranges held ahead per operand, two operands) makes reads queue for a socket, so one `advisory` event goes to the
- * store's metrics sink, once. Nothing is logged or printed.
- *
- * A handler this cannot read (a custom one, HTTP/2, Fetch, an agent class that hides `maxSockets`) gives no event and
- * no error. The window it compares against is the default, because a combine's `concurrency` is chosen per call.
- */
-import type { S3Client } from '@aws-sdk/client-s3';
-import type { IMetricsSink } from '@cloudbitmaps/core/driver-kit';
-/** The default window of a combine, which the engine owns; a test holds the two equal. */
-export declare const SOCKET_ADVISORY_CONCURRENCY = 32;
-/** What of the SDK's request handler the limit and the advisory need: its `handle` and the agents it exposes once it has run. */
-export interface PooledHandler {
-    handle(request: unknown, options?: unknown): Promise<unknown>;
-    httpHandlerConfigs?: () => {
-        httpAgent?: {
-            maxSockets: number;
-        };
-        httpsAgent?: {
-            maxSockets: number;
-        };
-    };
-}
-export declare class SocketAdvisory {
-    private readonly client;
-    private readonly bucket;
-    /** True from the first `attach` until the one check has started: the only thing a request pays for after the first. */
-    private pending;
-    /** Every sink ever attached, so a sink is never given the event twice. */
-    private readonly sinks;
-    /** The check's result, once it has started; a sink attached after that is given the result as it settles. */
-    private outcome;
-    constructor(client: S3Client, bucket: string);
-    /**
-     * Hand a sink to the advisory. Each sink gets the event at most once: a sink attached before the check runs gets it
-     * when the first read finishes, one attached later gets it as soon as the (single) check's result is known, and
-     * one attached again is ignored.
-     */
-    attach(sink: IMetricsSink): void;
-    /**
-     * Called as a request finishes. The first call after a sink is attached reads the pool, never throws and never
-     * rejects; every later one costs one boolean. Returns the pending check (for a test to await), or `undefined` once
-     * it has run.
-     */
-    afterRequest(): Promise<void> | undefined;
-    private read;
-    /**
-     * The pool the reads use, or `undefined` when it cannot be read. With an endpoint on the client, that is the
-     * `maxSockets` of the agent for its scheme. Without one (the SDK's own endpoints, or an endpoint set by the
-     * environment, which the client does not expose) the scheme is not known, so every agent the handler has made is
-     * read and the pool counts as small only if all of them are: the larger one is returned. That never warns on a pool
-     * the reads do not use, at the cost of a missed warning when only the unused agent is small.
-     */
-    private pool;
-}

package/dist/storage.d.ts

@@ -1,100 +0,0 @@
-import type { BlobSink, GenKey, IStorageDriver, SegmentRef, StorageCaps, StorageDeleteOptions, TailRead } from '@cloudbitmaps/core/driver-kit';
-import type { Clock, Rng } from '@cloudbitmaps/core';
-import { type S3Client } from '@aws-sdk/client-s3';
-import type { SocketAdvisory } from './socket-advisory.js';
-/** What the throttle backoff waits on. */
-type Sleeper = Pick<Clock, 'sleep'>;
-interface S3StorageDriverOptions {
-    /** A constructed S3 client (point its `endpoint` at MinIO for local/integration use). */
-    readonly client: S3Client;
-    /** Target bucket (must already exist). */
-    readonly bucket: string;
-    /** Optional key prefix under which all objects live (e.g. `cloudbitmaps/`). */
-    readonly prefix?: string;
-    /**
-     * Largest object this driver will write/advertise. Default = `partBytes × 10,000` (≈ 80 GiB at the default
-     * 8 MiB part) — the honest ceiling reachable within S3's 10,000-part limit. Set it higher and `partBytes`
-     * auto-grows so 10,000 parts still cover it (raising peak write memory to ~one part); up to the 5 TiB S3 max.
-     */
-    readonly maxObjectBytes?: number;
-    /** Multipart part size in bytes (default 8 MiB; a smaller value is raised to the S3 5 MiB minimum). Must be a
-     * positive safe integer. Tunes peak write memory. */
-    readonly partBytes?: number;
-    /**
-     * How long one read — a `GetObject` or `HeadObject`, its body included — may take before it is abandoned and throws
-     * `TransientError`, in ms. `0`, the default, sets no timeout. Must be a non-negative safe integer no larger than
-     * 2,147,483,647. Writes and listings are not timed.
-     *
-     * The clock starts when the read is handed to the SDK, so it also counts the time the read waits for one of the
-     * client's sockets (128 by default on the client the store builds, 50 on the SDK's own) and the time spent fetching
-     * credentials, and under `retryMode: 'adaptive'` the SDK's rate-limiter wait. A burst of concurrent reads larger than
-     * the socket pool can therefore time out with nothing slow on the wire: size the timeout above the worst queueing
-     * your concurrency implies, or raise `maxSockets` (the store's option, or your own client's). On a client built with
-     * `cacheMiddleware: true`, a timed read resolves its middleware each time.
-     */
-    readonly readTimeoutMs?: number;
-    /** The socket-pool check, run as each read finishes; absent for a driver built on its own. */
-    readonly sockets?: SocketAdvisory;
-    /** What the backoff before re-sending a throttled commit waits on; real time when absent. */
-    readonly clock?: Sleeper;
-    /** Where the jitter of that backoff is drawn from; `Math.random` when absent. */
-    readonly rng?: Rng;
-    /**
-     * Whether a delete given `ifVersion` is sent with `If-Match`, so it removes the object only while it is the one that
-     * ETag names. Defaults as the registry's option does: on when the host the client resolves is an AWS S3 host and the
-     * SDK sends the header, resolved on the first such delete (until then `capabilities()` reads `false`), and off for any
-     * other host, and for a client that cannot be resolved then (no region), whose deletes stay unconditional. Set it for
-     * an S3-compatible store only once you know the store applies `If-Match` on a delete. A `true` never overrides an SDK
-     * that does not send the header.
-     */
-    readonly conditionalDelete?: boolean;
-}
-export declare class S3StorageDriver implements IStorageDriver {
-    private readonly client;
-    private readonly bucket;
-    private readonly prefix;
-    private readonly maxObjectBytes;
-    private readonly partBytes;
-    private readonly readTimeoutMs;
-    private readonly clock;
-    private readonly rng;
-    private readonly sockets;
-    private readonly explicitConditionalDelete;
-    private probed;
-    private facts;
-    constructor(options: S3StorageDriverOptions);
-    capabilities(): StorageCaps;
-    /** Ask the client once where its requests go and whether it sends `If-Match` on a delete; it sends nothing. */
-    private settle;
-    putImmutable(key: GenKey, write: (sink: BlobSink) => Promise<void>): Promise<{
-        size: number;
-        sha256: string;
-    }>;
-    getRange(key: GenKey, offset: number, length: number): Promise<Uint8Array>;
-    getTail(key: GenKey, maxBytes: number): Promise<TailRead>;
-    private badRead;
-    /**
-     * The object's size and ETag from a `HeadObject`, each `undefined` when the response does not carry it. A missing
-     * object throws {@link NotFoundError}.
-     */
-    private head;
-    /**
-     * One read request under the read timeout, its failures mapped to the driver vocabulary. The timeout's own
-     * `TransientError` is raised outside the mapping, so it reaches the caller as it is.
-     */
-    private read;
-    delete(key: GenKey, options?: StorageDeleteOptions): Promise<void>;
-    /** Whether an object is under the key, from one `HeadObject`. A read that fails in any other way throws. */
-    private exists;
-    list(ref: SegmentRef): AsyncIterable<GenKey>;
-    /** Map S3 read errors to the driver vocabulary; pass everything else through {@link mapError}. */
-    private mapReadError;
-    /**
-     * Reclassify a transient S3 fault (throttle/5xx/dropped connection) as a retryable {@link TransientError}, so the
-     * store's read retry can ride it out and a write's caller can tell it from a deterministic failure, and a missing
-     * bucket as a `ValidationError` that names it; everything else propagates unchanged. The final fallback at every
-     * `client.send` site, so callers and the read retry only ever see typed errors.
-     */
-    private mapError;
-}
-export {};