@cloudbitmaps/s3 0.20.0 → 0.21.0

package/dist/read-timeout.d.ts

@@ -1,9 +1,5 @@
-/** No timeout unless one is set: the value a read takes stays the caller's until in-region measurements justify one. */
-export declare const DEFAULT_READ_TIMEOUT_MS = 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;
-/** A value as an error message can show it: a string quoted, so `'200'` is not mistaken for `200`, and never a throw. */
-export declare function describe(value: unknown): string;
 /** 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;

package/dist/registry.d.ts

@@ -35,7 +35,7 @@
 import { ObjectStoreRegistry } from '@cloudbitmaps/core/driver-kit';
 import type { ObjectRegistryStore, ObjectRow } from '@cloudbitmaps/core/driver-kit';
 import { type S3Client } from '@aws-sdk/client-s3';
-export interface S3RegistryDriverOptions {
+interface S3RegistryDriverOptions {
     /** A constructed S3 client (point its `endpoint` at MinIO for local/integration use). */
     readonly client: S3Client;
     /** Target bucket (must already exist). */
@@ -115,3 +115,4 @@ export declare class S3RegistryStore implements ObjectRegistryStore {
 export declare class S3RegistryDriver extends ObjectStoreRegistry {
     constructor(options: S3RegistryDriverOptions);
 }
+export {};

package/dist/s3-errors.d.ts

@@ -29,6 +29,12 @@ export declare function isNoSuchUpload(err: unknown): boolean;
  * 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.
@@ -43,6 +49,11 @@ export declare function isInvalidRange(err: unknown): boolean;
  * 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;

package/dist/storage.d.ts

@@ -1,11 +1,10 @@
 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. */
-interface Sleeper {
-    sleep(ms: number): Promise<void>;
-}
-export interface S3StorageDriverOptions {
+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). */
@@ -38,6 +37,8 @@ export interface S3StorageDriverOptions {
     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
@@ -56,6 +57,7 @@ export declare class S3StorageDriver implements IStorageDriver {
     private readonly partBytes;
     private readonly readTimeoutMs;
     private readonly clock;
+    private readonly rng;
     private readonly sockets;
     private readonly explicitConditionalDelete;
     private probed;
@@ -88,10 +90,10 @@ export declare class S3StorageDriver implements IStorageDriver {
     /** 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;
-     * everything else propagates unchanged. The final fallback at every `client.send` site, so callers and the
-     * read retry only ever see typed errors.
+     * 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;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbitmaps/s3",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "S3 and S3-compatible storage (R2, MinIO, Ceph, Wasabi, B2) for CloudBitmaps",
   "keywords": [
     "cloudbitmaps",
@@ -53,7 +53,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": ">=3.700.0 <4",
-    "@cloudbitmaps/core": "^0.20.0"
+    "@cloudbitmaps/core": "^0.21.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/dist/keys.d.ts

@@ -1,17 +0,0 @@
-import type { GenKey, SegmentRef } from '@cloudbitmaps/core/driver-kit';
-/** Validate a caller-supplied key prefix. The rule is shared with every other object store. */
-export { normalizeObjectPrefix as normalizeS3Prefix } from '@cloudbitmaps/core/driver-kit';
-/**
- * The S3 key prefix shared by all of a segment's generations: `<prefix><ns>/segments/<segment>.`. Used
- * both as the `ListObjectsV2` prefix and as the string stripped by {@link parseGenerationFromKey}.
- */
-export declare function segmentObjectPrefix(prefix: string | undefined, ref: SegmentRef): string;
-/** The full S3 key of one `.crbm` generation: `<segmentPrefix><gen>.crbm`. */
-export declare function storageObjectKey(prefix: string | undefined, key: GenKey): string;
-/**
- * Parse a generation number out of a full object key, given its segment prefix, or `null` if it doesn't
- * match. Canonical decimal only — no leading zeros (so `…s.07.crbm` can't alias `…s.7.crbm`) and within
- * safe-integer range. This also rejects a *different* segment whose name merely shares the prefix (e.g. a
- * key for segment `s.x` won't parse under segment `s`'s prefix, since its middle isn't all digits).
- */
-export declare function parseGenerationFromKey(segmentPrefix: string, objectKey: string): number | null;