@ultimat3/storage 23.0.0 → 24.0.0

package/src/driver-s3.ts

@@ -4,8 +4,17 @@
 // The client is built lazily on first use so importing this module never opens a socket, and
 // credentials arrive as env var NAMES: a literal key in app.config.ts is a key in git.
 
-import { ConfigInvalidError, EnvMissingError, finiteCount, stringField } from '@ultimat3/core';
 import {
+  ConfigInvalidError,
+  EnvMissingError,
+  finiteCount,
+  NotImplementedError,
+  renderFixShellArg,
+  stringField,
+} from '@ultimat3/core';
+import {
+  assertListOptions,
+  assertPutOptions,
   DEFAULT_CONTENT_TYPE,
   type ListOptions,
   type ListPage,
@@ -24,9 +33,12 @@ import { regionMismatch } from './driver-s3-region';
 import {
   checksumMismatch,
   deleteFailed,
+  getTooLarge,
+  isStorageError,
   listFailed,
   objectNotFound,
-  storageNotImplemented,
+  putFailed,
+  readFailed,
 } from './errors';
 import { assertSafeKey } from './path';
 import { DEFAULT_SIGNED_URL_TTL_MS } from './signed-url';
@@ -102,6 +114,12 @@ export interface S3DriverOptions {
    * and S3's single-PUT limit is 5GB regardless of what this says.
    */
   readonly maxPutBytes?: number | undefined;
+  /**
+   * Ceiling on ONE `get()`, because `get()` buffers the whole object — and on this disk nothing
+   * bounds what a presigned PUT stored (`SignedUrlOptions.maxBytes`). Defaults to `maxPutBytes`;
+   * an object past it is read with `stream()`.
+   */
+  readonly maxGetBytes?: number | undefined;
 }
 
 interface S3ClientConstructor {
@@ -157,8 +175,12 @@ function buildClient(options: S3DriverOptions): S3ClientLike {
   });
 }
 
-const toDate = (value: string | Date | undefined): Date =>
-  value === undefined ? new Date(0) : value instanceof Date ? value : new Date(value);
+/**
+ * A missing `LastModified` is ABSENT, never `new Date(0)`: epoch 0 is older than every window, so
+ * `sweepOrphans` deleted an upload on the strength of a field the provider never sent.
+ */
+const dated = (value: string | Date | undefined): { readonly lastModified?: Date } =>
+  value === undefined ? {} : { lastModified: value instanceof Date ? value : new Date(value) };
 
 /** One numeric field off a value that may fight being read — `stringField`'s missing twin. */
 function numberField(value: unknown, key: string): number | undefined {
@@ -196,12 +218,12 @@ function isAbsentObject(error: unknown): boolean {
  */
 function refuseUnsupportedPut(bucket: string, key: string, putOptions?: PutOptions): void {
   if (putOptions?.metadata !== undefined || putOptions?.cacheControl !== undefined) {
-    const uri = `s3://${bucket}/${key}`;
-    throw storageNotImplemented(
-      'user metadata and cache-control on the s3 driver (Bun exposes no header hook yet)',
-      `drop metadata/cacheControl from put(), or set them out of band: ` +
-        `aws s3 cp ${uri} ${uri} --metadata-directive REPLACE`,
-    );
+    const uri = renderFixShellArg(`s3://${bucket}/${key}`, '<s3-uri>');
+    throw new NotImplementedError({
+      cause:
+        'user metadata and cache-control on the s3 driver (Bun exposes no header hook yet) is not implemented by this driver — drop metadata/cacheControl from put(), or set them out of band with the command in fix',
+      fix: `aws s3 cp ${uri} ${uri} --metadata-directive REPLACE`,
+    });
   }
   const sse = putOptions?.serverSideEncryption;
   if (sse === undefined) return;
@@ -209,10 +231,11 @@ function refuseUnsupportedPut(bucket: string, key: string, putOptions?: PutOptio
     sse.algorithm === 'aws:kms'
       ? `{"SSEAlgorithm":"aws:kms","KMSMasterKeyID":"${sse.kmsKeyId ?? '<key-arn>'}"}`
       : '{"SSEAlgorithm":"AES256"}';
-  throw storageNotImplemented(
-    'per-object server-side encryption on the s3 driver (Bun.S3Client exposes acl, storageClass and type, and nothing for x-amz-server-side-encryption)',
-    `set it bucket-wide, then drop serverSideEncryption from put(): aws s3api put-bucket-encryption --bucket ${bucket} --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":${rule},"BucketKeyEnabled":true}]}'`,
-  );
+  throw new NotImplementedError({
+    cause:
+      'per-object server-side encryption on the s3 driver (Bun.S3Client exposes acl, storageClass and type, and nothing for x-amz-server-side-encryption) is not implemented by this driver — set it bucket-wide with the command in fix, then drop serverSideEncryption from put()',
+    fix: `aws s3api put-bucket-encryption --bucket ${renderFixShellArg(bucket, '<bucket>')} --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":${rule},"BucketKeyEnabled":true}]}'`,
+  });
 }
 
 export function s3Driver(options: S3DriverOptions): StorageDriver {
@@ -224,6 +247,12 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
     options.maxPutBytes === undefined ? DEFAULT_MAX_UPLOAD_BYTES : options.maxPutBytes,
     1,
   );
+  const maxGetBytes = finiteCount(
+    'the s3 driver',
+    'maxGetBytes',
+    options.maxGetBytes === undefined ? maxPutBytes : options.maxGetBytes,
+    1,
+  );
   let client: S3ClientLike | undefined;
   const conn = (): S3ClientLike => {
     client ??= buildClient(options);
@@ -240,19 +269,51 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
     const mismatch = regionMismatch(options.bucket, error);
     if (mismatch !== undefined) throw mismatch;
   };
-  const misconfigured = (error: unknown): never => {
-    throwIfMisconfigured(error);
-    throw error;
-  };
+  /**
+   * A write the provider refused, coded: a denied `s3:PutObject`, a throttle, an expired
+   * credential. The bare `S3Error` used to escape `put()` and `copy()` exactly as it once escaped
+   * `list()` — no code, no fix, an anonymous 500.
+   */
+  const refusedWrite =
+    (key: string) =>
+    (error: unknown): never => {
+      throwIfMisconfigured(error);
+      throw putFailed(
+        DRIVER_NAME,
+        key,
+        error,
+        `aws s3api get-bucket-policy --bucket ${renderFixShellArg(options.bucket, '<bucket>')}`,
+      );
+    };
+
+  /**
+   * A read the provider refused, coded — `refusedWrite`'s twin. A 404 is "not found" wherever it
+   * arrives: an object deleted between `exists()` and the read is absent, not unreadable.
+   */
+  const refusedRead =
+    (key: string) =>
+    (error: unknown): never => {
+      if (isStorageError(error)) throw error;
+      if (isAbsentObject(error)) throw objectNotFound(DRIVER_NAME, key);
+      throwIfMisconfigured(error);
+      throw readFailed(
+        DRIVER_NAME,
+        key,
+        error,
+        `aws s3api head-object --bucket ${renderFixShellArg(options.bucket, '<bucket>')} --key ${renderFixShellArg(key, '<key>')}`,
+      );
+    };
+  const present = (key: string): Promise<boolean> =>
+    conn().file(key).exists().catch(refusedRead(key));
 
   const statObject = async (key: string): Promise<StorageObject> => {
-    const stat = await conn().file(key).stat();
+    const stat = await conn().file(key).stat().catch(refusedRead(key));
     return {
       key,
       size: stat.size,
       contentType: stat.type ?? DEFAULT_CONTENT_TYPE,
       etag: stat.etag ?? '',
-      lastModified: toDate(stat.lastModified),
+      ...dated(stat.lastModified),
     };
   };
 
@@ -262,6 +323,7 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
     async put(key: string, body: StorageBody, putOptions?: PutOptions): Promise<StorageObject> {
       const safe = assertSafeKey(key);
       refuseUnsupportedPut(options.bucket, safe, putOptions);
+      assertPutOptions(DRIVER_NAME, putOptions);
       // Buffered on purpose: size and checksum must be known before the object exists — so this
       // path is for objects that FIT IN MEMORY, and `maxPutBytes` is what makes that a contract
       // rather than a hope. User uploads never come through here: they go direct to the bucket
@@ -275,22 +337,32 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       await conn()
         .file(safe)
         .write(bytes, { type: putOptions?.contentType ?? DEFAULT_CONTENT_TYPE })
-        .catch(misconfigured);
+        .catch(refusedWrite(safe));
       return statObject(safe);
     },
 
+    async stat(key: string): Promise<StorageObject | undefined> {
+      const safe = assertSafeKey(key);
+      return (await present(safe)) ? statObject(safe) : undefined;
+    },
+
     async get(key: string): Promise<StorageRead> {
       const safe = assertSafeKey(key);
       const file = conn().file(safe);
-      if (!(await file.exists())) throw objectNotFound(DRIVER_NAME, safe);
-      const bytes = new Uint8Array(await file.arrayBuffer());
-      return { object: await statObject(safe), bytes };
+      if (!(await present(safe))) throw objectNotFound(DRIVER_NAME, safe);
+      // The HEAD comes FIRST, and it is the whole point: a client PUT straight into the bucket is
+      // bounded by nothing on this disk, so `arrayBuffer()` on whatever is there was heap growth
+      // the uploader chose. Refused on the provider's own size before a byte is read.
+      const object = await statObject(safe);
+      if (object.size > maxGetBytes) throw getTooLarge(DRIVER_NAME, safe, object.size, maxGetBytes);
+      const bytes = new Uint8Array(await file.arrayBuffer().catch(refusedRead(safe)));
+      return { object, bytes };
     },
 
     async stream(key: string): Promise<ReadableStream<Uint8Array>> {
       const safe = assertSafeKey(key);
       const file = conn().file(safe);
-      if (!(await file.exists())) throw objectNotFound(DRIVER_NAME, safe);
+      if (!(await present(safe))) throw objectNotFound(DRIVER_NAME, safe);
       return file.stream();
     },
 
@@ -305,12 +377,12 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       const source = assertSafeKey(from);
       const destination = assertSafeKey(to);
       const file = conn().file(source);
-      if (!(await file.exists())) throw objectNotFound(DRIVER_NAME, source);
-      const stat = await file.stat();
+      if (!(await present(source))) throw objectNotFound(DRIVER_NAME, source);
+      const stat = await file.stat().catch(refusedRead(source));
       await conn()
         .file(destination)
         .write(file, { type: stat.type ?? DEFAULT_CONTENT_TYPE })
-        .catch(misconfigured);
+        .catch(refusedWrite(destination));
       return statObject(destination);
     },
 
@@ -333,13 +405,14 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
     },
 
     async exists(key: string): Promise<boolean> {
-      return conn().file(assertSafeKey(key)).exists();
+      return present(assertSafeKey(key));
     },
 
     async list(listOptions?: ListOptions): Promise<ListPage> {
       const prefix = listOptions?.prefix ?? '';
       // Refused at the seam both drivers share, before the provider is asked: `maxKeys: 0` used to
       // go straight through, while the local disk answered a complete-looking empty page.
+      assertListOptions(listOptions);
       const maxKeys = resolveListLimit(listOptions?.limit);
       // `conn()` OUTSIDE the try: a missing credential or an absent `Bun.S3Client` is this disk
       // misconfigured, and it already answers with its own code and its own fix.
@@ -375,7 +448,7 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
           key: entry.key,
           size: entry.size ?? 0,
           etag: entry.eTag ?? '',
-          lastModified: toDate(entry.lastModified),
+          ...dated(entry.lastModified),
         });
       }
       const cursor = result.nextContinuationToken;

package/src/driver.ts

@@ -23,7 +23,12 @@ export interface StorageListEntry {
   /** Absent means the driver's listing does not carry it. Never a fabricated default. */
   readonly contentType?: string | undefined;
   readonly etag: string;
-  readonly lastModified: Date;
+  /**
+   * ABSENT when the provider did not say — never epoch 0, which every age test reads as "older
+   * than any window", and never an invalid `Date`, which is a value a reader has to remember to
+   * test. A reader that needs an age handles `undefined`; `sweepOrphans` spares it.
+   */
+  readonly lastModified?: Date | undefined;
   /** Present only when the driver actually stored what `put()` was handed — never invented. */
   readonly cacheControl?: string | undefined;
   readonly metadata?: Readonly<Record<string, string>> | undefined;
@@ -115,6 +120,17 @@ export interface StorageDriver {
    */
   registerAs?(diskName: string): void;
   put(key: string, body: StorageBody, options?: PutOptions): Promise<StorageObject>;
+  /**
+   * What a read would say about the object, WITHOUT its bytes — `undefined` when nothing is there.
+   * `promoteAttachment` decides on `stat().size`, because a presigned PUT lands on the disk
+   * unmeasured and `get()` is the one call that must not be how its size is learned. Required: a
+   * driver that cannot measure cannot be promoted from, and that is a compile error, not a refusal.
+   */
+  stat(key: string): Promise<StorageObject | undefined>;
+  /**
+   * The whole object, BUFFERED — so bounded: an object over the driver's `maxGetBytes` is
+   * `X_STORAGE_TOO_LARGE`, exactly as `put()` refuses a body over `maxPutBytes`. Past it, `stream()`.
+   */
   get(key: string): Promise<StorageRead>;
   /** Bytes without buffering — the only safe path for anything over a few MB. */
   stream(key: string): Promise<ReadableStream<Uint8Array>>;
@@ -181,6 +197,45 @@ export function resolveListLimit(limit: number | undefined): number {
   return limit;
 }
 
+const isStringRecord = (value: unknown): boolean =>
+  typeof value === 'object' &&
+  value !== null &&
+  !Array.isArray(value) &&
+  Object.values(value).every((entry) => typeof entry === 'string');
+
+/**
+ * What `put()` was told ABOUT the bytes, held to its type before a byte moves. An untyped caller's
+ * `metadata: { n: 1n }` reached `JSON.stringify` on the local disk as a bare `TypeError`, and the
+ * memory disk stored it — against the `Record<string, string>` every reader is typed on.
+ */
+export function assertPutOptions(driver: string, options: PutOptions | undefined): void {
+  if (options === undefined) return;
+  for (const name of ['contentType', 'cacheControl'] as const) {
+    assert(
+      options[name] === undefined || typeof options[name] === 'string',
+      `put() on the ${driver} disk was given a ${name} that is not a string`,
+      `put(key, body, { ${name}: 'a string' }) — or omit ${name}`,
+    );
+  }
+  assert(
+    options.metadata === undefined || isStringRecord(options.metadata),
+    `put() on the ${driver} disk was given metadata that is not a plain object of string values`,
+    "put(key, body, { metadata: { name: 'value' } }) — every value a string: String(n) a number, JSON.stringify anything nested",
+  );
+}
+
+/** A `prefix` or a `cursor` that is not a string reached `startsWith` and `<=` as whatever it was. */
+export function assertListOptions(options: ListOptions | undefined): void {
+  for (const name of ['prefix', 'cursor'] as const) {
+    const value = options?.[name];
+    assert(
+      value === undefined || typeof value === 'string',
+      `list() was given a ${name} that is not a string`,
+      `disk.list({ ${name}: 'a string' }) — or omit ${name}`,
+    );
+  }
+}
+
 /** What `toBytes` needs to refuse a body: the ceiling, and the key to name in the refusal. */
 export interface ByteLimit {
   readonly driver: string;
@@ -212,6 +267,13 @@ export async function toBytes(body: StorageBody, limit: ByteLimit): Promise<Uint
     }
     return new Uint8Array(await body.arrayBuffer());
   }
+  // The type says so; an untyped caller's `put(key, 'a string')` reached `getReader` as a
+  // bare `TypeError`.
+  assert(
+    body instanceof ReadableStream,
+    `put() on the ${limit.driver} disk was given a body that is not a Uint8Array, a Blob or a ReadableStream`,
+    "put(key, new TextEncoder().encode(text)) — bytes, never a string: encode it, or pass the request's own body stream",
+  );
   return readBounded(body, limit);
 }
 

package/src/errors.ts

@@ -2,7 +2,12 @@
 // rejected upload must tell the caller which constraint fired and where that constraint is
 // configured, or the caller retries the same bytes forever.
 
-import { registerErrorCodes, renderThrowable, UltimateError } from '@ultimat3/core';
+import {
+  registerErrorCodes,
+  renderFixLiteral,
+  renderThrowable,
+  UltimateError,
+} from '@ultimat3/core';
 
 /** Codes this package declares and owns. */
 export const STORAGE_OWNED_ERROR_CODES = [
@@ -21,11 +26,14 @@ export const STORAGE_OWNED_ERROR_CODES = [
   'X_STORAGE_LIST_FAILED',
   'X_STORAGE_QUARANTINED',
   'X_STORAGE_NOT_PENDING',
+  'X_STORAGE_KEY_CONFLICT',
+  'X_STORAGE_PUT_FAILED',
+  'X_STORAGE_READ_FAILED',
 ] as const;
 
 /**
- * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. `storageNotImplemented()` throws it and this package
- * keeps no title for it — one code, one owner, one title, or the two copies drift apart in silence.
+ * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. The drivers throw core's own `NotImplementedError`
+ * and this package keeps no title for it — one code, one owner, one title, or the two copies drift apart in silence.
  * `X_IMAGE_UNSUPPORTED` / `X_IMAGE_DECODE_FAILED` are core's too and surface unwrapped (`image.ts`).
  * `X_ENV_MISSING` is core's for the same reason: an unset `STORAGE_SIGNING_SECRET` outside
  * development is a missing environment variable, not a storage concept needing its own code.
@@ -57,6 +65,9 @@ export const STORAGE_ERROR_TITLES: Readonly<Record<StorageOwnedErrorCode, string
   X_STORAGE_LIST_FAILED: 'the objects could not be listed',
   X_STORAGE_QUARANTINED: 'the object is still in quarantine',
   X_STORAGE_NOT_PENDING: 'the key is not a pending upload',
+  X_STORAGE_KEY_CONFLICT: 'the key collides with another key on the local disk',
+  X_STORAGE_PUT_FAILED: 'the object could not be written',
+  X_STORAGE_READ_FAILED: 'the object could not be read',
 };
 
 // One unconditional call, so a second package claiming one of storage's codes throws
@@ -161,6 +172,49 @@ export const putTooLarge = (
     meta: { disk, key, bytes, maxBytes },
   });
 
+/**
+ * The SERVER-side `get()` ceiling — `putTooLarge`'s twin. `get()` buffers the whole object, and an
+ * object's size is not this process's to choose: a presigned PUT lands in the bucket unmeasured,
+ * so a later `get()` of it was heap growth the uploader picked.
+ */
+export const getTooLarge = (
+  disk: string,
+  key: string,
+  bytes: number,
+  maxBytes: number,
+): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_TOO_LARGE',
+    cause: `"${key}" is ${bytes}B against the ${disk} disk's get ceiling of ${maxBytes}B, and get() buffers the whole object`,
+    fix:
+      `read it with disk.stream(key) instead of get(), or raise the ceiling: ` +
+      (disk === 's3'
+        ? `s3Driver({ bucket, maxGetBytes: ${bytes} })`
+        : disk === 'memory'
+          ? `memoryDriver({ maxGetBytes: ${bytes} })`
+          : `localDriver({ root, maxGetBytes: ${bytes} })`),
+    meta: { disk, key, bytes, maxBytes },
+  });
+
+/**
+ * The local disk stores an object as a FILE at its key, so a key cannot also be the directory of
+ * another: `put('a')` then `put('a/b')`, or the reverse, or the same pair one tree over in the
+ * sidecars (`a` and `a.json/b`). It surfaced as a bare `ENOTDIR` / `EISDIR`. S3 and the memory
+ * disk hold both — this is the local disk's own limit, refused by name rather than hidden.
+ *
+ * The `fix` lists what is in the way: the remedy is storing one of the two under another key, and
+ * which one is only decidable by a reader who can see both.
+ */
+export const keyConflict = (disk: string, key: string, blocking: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_KEY_CONFLICT',
+    cause: `the "${disk}" disk is a local one and cannot store "${key}": "${blocking}" is already on it, and a POSIX path is a file or a directory, never both — so one key cannot be a path prefix of another here. Store one of the two under a different key; an s3 disk holds both`,
+    // The REGISTERED name, never the driver kind: `disk('local')` on a disk registered as
+    // `uploads` lists another disk, or answers X_STORAGE_DISK_UNKNOWN.
+    fix: `disk(${renderFixLiteral(disk, "'local'")}).list({ prefix: ${renderFixLiteral(blocking, "'a/'")} })`,
+    meta: { disk, key, blocking },
+  });
+
 /** The declared type is not on the allowlist at all. */
 export const contentTypeNotAllowed = (
   key: string,
@@ -258,6 +312,43 @@ export const deleteFailed = (
   });
 };
 
+/**
+ * A write the disk REFUSED — `deleteFailed`'s twin for `put()` and `copy()`. The local disk's
+ * `EACCES` / `ENOSPC` / `EROFS` left as a bare filesystem `Error`, and a provider's refused PUT as
+ * a bare `S3Error`: no code, no fix, nothing for the http error map to render but an anonymous 500.
+ * The `fix` is the driver's, for `deleteFailed`'s reason.
+ */
+export const putFailed = (disk: string, key: string, error: unknown, fix: string): StorageError => {
+  const reason = renderThrowable(error);
+  return new StorageError({
+    code: 'X_STORAGE_PUT_FAILED',
+    cause: `disk "${disk}" refused to write "${key}": ${reason}`,
+    fix,
+    meta: { disk, key, reason },
+  });
+};
+
+/**
+ * A read the disk REFUSED — `putFailed`'s read-side twin, for `get`, `stat`, `exists`, `stream` and
+ * the read half of `copy`. A denied `s3:GetObject`, a throttle, `EACCES`, `EIO`. An object that is
+ * simply absent is `objectNotFound`, never this: "not there" and "could not look" need opposite
+ * answers from a caller. The `fix` is the driver's, for `deleteFailed`'s reason.
+ */
+export const readFailed = (
+  disk: string,
+  key: string,
+  error: unknown,
+  fix: string,
+): StorageError => {
+  const reason = renderThrowable(error);
+  return new StorageError({
+    code: 'X_STORAGE_READ_FAILED',
+    cause: `disk "${disk}" refused to read "${key}": ${reason}`,
+    fix,
+    meta: { disk, key, reason },
+  });
+};
+
 /**
  * A listing the disk REFUSED — a denied `s3:ListBucket`, a throttle, an expired credential, a root
  * this process cannot read. Exactly `deleteFailed`'s shape and for exactly its reason: an empty
@@ -363,12 +454,3 @@ export const signingSecretMissing = (environment: string, disk = 'local'): Stora
     fix: 'export STORAGE_SIGNING_SECRET="$(openssl rand -hex 32)"',
     meta: { key: 'STORAGE_SIGNING_SECRET', environment },
   });
-
-/** An interface-complete driver whose remote half is not bound yet. Always carries a fix. */
-export const storageNotImplemented = (feature: string, fix: string): StorageError =>
-  new StorageError({
-    code: 'X_NOT_IMPLEMENTED',
-    cause: `${feature} is declared but not implemented in @ultimat3/storage`,
-    fix,
-    meta: { feature },
-  });

package/src/grant.ts

@@ -83,12 +83,12 @@ export async function grantUpload(input: GrantUploadInput): Promise<UploadGrant>
   }
 
   // Refused here as well as in the presigner one call down: `expiresAt: now + NaN` is `NaN` in the
-  // grant this function RETURNS, and the message a caller can act on names `createUploadGrant`'s
+  // grant this function RETURNS, and the message a caller can act on names `grantUpload`'s
   // own option rather than `buildSignedUrl`'s.
   // `=== undefined`, never `??`, for the reason `buildSignedUrl` states: `??` coalesces on `null`
   // too, so an explicit one took the default instead of this refusal.
   const expiresInMs = finiteCount(
-    'createUploadGrant',
+    'grantUpload',
     'expiresInMs',
     input.expiresInMs === undefined ? DEFAULT_SIGNED_URL_TTL_MS : input.expiresInMs,
     1,

package/src/image.ts

@@ -6,12 +6,13 @@
 import {
   assertFiniteImageQuality,
   blurDataUrl,
+  finiteCount,
   type ImageFormat,
   imageUnsupported,
   probeImage,
   transformImageBytes,
 } from '@ultimat3/core';
-import { assertSafeKey, keyExtname } from './path';
+import { assertSafeKey } from './path';
 
 /**
  * The formats a stored VARIANT can be minted in — a strict subset of the ones `@ultimat3/core`
@@ -67,13 +68,28 @@ const FORMAT_EXTENSIONS: Readonly<Record<VariantFormat, string>> = {
   png: 'png',
 };
 
+/**
+ * One edge of a variant box: a whole number of pixels, at least one. Core's `finiteCount`, for the
+ * reason `quality` goes through core's screen below — `{ width: NaN }` minted `a@wNaN.webp`, a
+ * writable key for bytes no encoder can produce, and `w1.5` / `w-3` are an unbounded number of
+ * keys in a bucket. `!== undefined`, never a truthiness test: an explicit `null` is refused.
+ */
+function edge(subject: string, option: 'width' | 'height', value: number | undefined): void {
+  if (value !== undefined) finiteCount(subject, option, value, 1);
+}
+
 /**
  * Derived, not stored: the same source + transform always yields the same key, so a variant
  * is a cache lookup rather than a database row.
+ *
+ * The WHOLE source key is the stem, extension included. It used to be cut, so `p/hero.png` and
+ * `p/hero.jpg` minted one `p/hero@w100.webp` and whichever was requested first was served for
+ * both — two sources, one cache identity.
  */
 export function variantKey(sourceKey: string, transform: ImageTransform): string {
   const safe = assertSafeKey(sourceKey);
-  const stem = safe.slice(0, safe.length - keyExtname(safe).length);
+  edge('variantKey', 'width', transform.width);
+  edge('variantKey', 'height', transform.height);
   // `string`, not `VariantFormat`: a format off a query string or through an `as` reaches here as
   // any string core can probe, and indexing FORMAT_EXTENSIONS with `gif` minted
   // `photos/hero@full.undefined` — a well-formed, writable key naming a file nothing can serve.
@@ -101,7 +117,7 @@ export function variantKey(sourceKey: string, transform: ImageTransform): string
   );
   if (quality !== DEFAULT_QUALITY) parts.push(`q${quality}`);
   if (parts.length === 0) parts.push('full');
-  return assertSafeKey(`${stem}@${parts.join('-')}.${FORMAT_EXTENSIONS[format]}`);
+  return assertSafeKey(`${safe}@${parts.join('-')}.${FORMAT_EXTENSIONS[format]}`);
 }
 
 export interface SrcsetDescriptor {
@@ -139,23 +155,33 @@ export function srcsetDescriptors(
     }));
 }
 
-/** Aspect-ratio fitting. `cover` rounds up so the box is always fully covered. */
+/** A derived edge is never zero: 1000x1 at width 100 rounded to a height no encoder can fill. */
+const atLeastOne = (pixels: number): number => Math.max(1, Math.round(pixels));
+
+/**
+ * Aspect-ratio fitting. `cover` is the exact box asked for; everything else fits INSIDE the box
+ * and never above the source — upscaling is never useful, whichever edges were named.
+ */
 export function fitDimensions(source: ImageSize, transform: ImageTransform): ImageSize {
   const ratio = source.height / source.width;
   const { width, height } = transform;
+  edge('fitDimensions', 'width', width);
+  edge('fitDimensions', 'height', height);
   if (width === undefined && height === undefined) return source;
   if (height === undefined) {
     const target = Math.min(width ?? source.width, source.width);
-    return { width: target, height: Math.round(target * ratio) };
+    return { width: target, height: atLeastOne(target * ratio) };
   }
   if (width === undefined) {
     const target = Math.min(height, source.height);
-    return { width: Math.round(target / ratio), height: target };
+    return { width: atLeastOne(target / ratio), height: target };
   }
   // `cover` crops to the exact box; `contain` scales down until both sides fit.
   if (transform.fit === 'cover') return { width, height };
-  const scale = Math.min(width / source.width, height / source.height);
-  return { width: Math.round(source.width * scale), height: Math.round(source.height * scale) };
+  // Clamped at 1: a single named edge already stopped at the source, and two of them did not —
+  // a 40x20 source asked for 400x400 came back 400x200.
+  const scale = Math.min(1, width / source.width, height / source.height);
+  return { width: atLeastOne(source.width * scale), height: atLeastOne(source.height * scale) };
 }
 
 /**

package/src/index.ts

@@ -43,22 +43,18 @@ export type {
   StorageRead,
 } from './driver';
 export {
+  // Exported for the same reason `toBytes` is: a driver written outside this package has to
+  // refuse a `limit` the same way both shipped ones do, or it is a third answer to one question.
+  assertPutOptions,
   DEFAULT_CONTENT_TYPE,
   DEFAULT_LIST_LIMIT,
   etagOf,
-  // Exported for the same reason `toBytes` is: a driver written outside this package has to
-  // refuse a `limit` the same way both shipped ones do, or it is a third answer to one question.
   resolveListLimit,
   sha256Base64,
   toBytes,
 } from './driver';
 export type { LocalDriverOptions } from './driver-local';
-export {
-  DEV_SIGNING_SECRET,
-  localDriver,
-  STORAGE_SIGNING_SECRET_KEY,
-  usesDevStorageSecret,
-} from './driver-local';
+export { localDriver } from './driver-local';
 export type { MemoryDriverOptions, MemoryStorageDriver } from './driver-memory';
 export { memoryDriver } from './driver-memory';
 export type {
@@ -78,13 +74,17 @@ export {
   contentTypeUnrecognised,
   deleteFailed,
   diskUnknown,
+  getTooLarge,
   isStorageError,
+  keyConflict,
   listFailed,
   objectNotFound,
   orgMismatch,
   pathUnsafe,
+  putFailed,
   putTooLarge,
   quarantined,
+  readFailed,
   STORAGE_ERROR_CODES,
   STORAGE_ERROR_TITLES,
   StorageError,
@@ -92,7 +92,6 @@ export {
   signedUrlRejected,
   signedUrlUnverifiable,
   signingSecretMissing,
-  storageNotImplemented,
   tooLarge,
   uploadFailed,
 } from './errors';
@@ -152,9 +151,15 @@ export {
   SIGNED_URL_VERSION,
   signConstraints,
   signedUrlBaseFor,
+  signedUrlBasePath,
   timingSafeEqual,
   verifySignedUrl,
 } from './signed-url';
+export {
+  DEV_SIGNING_SECRET,
+  STORAGE_SIGNING_SECRET_KEY,
+  usesDevStorageSecret,
+} from './signing-secret';
 export type { Storage, StorageConfig } from './storage';
 export { definedStorage, defineStorage, disk, resetStorage, storage } from './storage';
 export type { UploadCandidate, UploadPolicy, UploadPolicyInit, ValidatedUpload } from './upload';