@ultimat3/storage 29.4.0 → 30.0.0

package/src/driver-s3.ts

@@ -8,16 +8,15 @@ import {
   type Clock,
   finiteCount,
   isUltimateError,
-  NotImplementedError,
   type Page,
   pageOf,
-  renderFixLiteral,
   renderFixShellArg,
   systemClock,
 } from '@ultimat3/core';
 import {
   assertListOptions,
   assertPutOptions,
+  type CopyOptions,
   DEFAULT_CONTENT_TYPE,
   type ListOptions,
   type PutOptions,
@@ -32,11 +31,17 @@ import {
   toBytes,
 } from './driver';
 import { isAbsentObject } from './driver-s3-absent';
-import { buildClient, type S3ClientLike, type S3ListResultLike } from './driver-s3-client';
+import { buildClient, dated, type S3ClientLike, type S3ListResultLike } from './driver-s3-client';
+import { signedCopy } from './driver-s3-copy';
 import { needsSignedPut, readObjectLock, signedPut } from './driver-s3-lock';
+import { s3Multipart } from './driver-s3-multipart-session';
+import { s3SignedUrl } from './driver-s3-presign';
+import { putS3Stream } from './driver-s3-put-stream';
 import { readS3Range } from './driver-s3-range';
 import { regionMismatch } from './driver-s3-region';
+import { settleLostPut } from './driver-s3-settle';
 import type { S3FetchLike } from './driver-s3-signed';
+import { refuseUnsupportedPut } from './driver-s3-sse';
 import {
   checksumMismatch,
   deleteFailed,
@@ -47,10 +52,17 @@ import {
   putFailed,
   readFailed,
 } from './errors';
+import { objectChanged } from './errors-promote';
 import { assertObjectLockOptions, type ObjectLock } from './object-lock';
 import { assertSafeKey } from './path';
-import { assertGetOptions, type GetOptions } from './range';
-import { DEFAULT_SIGNED_URL_TTL_MS } from './signed-url';
+import { assertPutStream, type PutStreamOptions } from './put-stream';
+import {
+  assertGetOptions,
+  assertStreamRange,
+  type ByteRange,
+  type GetOptions,
+  streamedRange,
+} from './range';
 import { DEFAULT_MAX_UPLOAD_BYTES } from './upload';
 
 const DRIVER_NAME = 's3';
@@ -92,44 +104,13 @@ export interface S3DriverOptions {
    */
   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()`.
+   * Ceiling on ONE `get()`, because `get()` buffers the whole object — and a URL signed with no
+   * `contentLength` bounds nothing it stored. Defaults to `maxPutBytes`; an object past it is read
+   * with `stream()`.
    */
   readonly maxGetBytes?: number | undefined;
 }
 
-/**
- * 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) };
-
-/**
- * Everything `put()` may be handed that this driver cannot honour, refused before a byte moves.
- * A typed refusal at the call site is the whole point: `serverSideEncryption` exists on
- * `PutOptions` so that "this disk cannot prove per-object encryption" is something an engineer
- * meets while writing the call, not while answering a security review.
- */
-function refuseUnsupportedPut(bucket: string, putOptions?: PutOptions): void {
-  const sse = putOptions?.serverSideEncryption;
-  if (sse === undefined) return;
-  // The key id is the caller's own option, spliced into single-quoted JSON: `renderFixLiteral`
-  // escapes the `"` and `\` JSON needs, and a `'` — the one byte live inside single quotes — makes
-  // it the placeholder rather than ending the argument (plan 101 row S12).
-  const keyId = sse.kmsKeyId?.includes("'") === false ? sse.kmsKeyId : undefined;
-  const bucketArg = renderFixShellArg(bucket, "'<bucket>'");
-  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:
-      sse.algorithm === 'aws:kms'
-        ? `aws s3api put-bucket-encryption --bucket ${bucketArg} --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"aws:kms","KMSMasterKeyID":${renderFixLiteral(keyId, '"<key-arn>"')}},"BucketKeyEnabled":true}]}'`
-        : `aws s3api put-bucket-encryption --bucket ${bucketArg} --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"AES256"},"BucketKeyEnabled":true}]}'`,
-  });
-}
-
 export function s3Driver(options: S3DriverOptions): StorageDriver {
   // `=== undefined`, never `??`: `??` coalesces on `null` too, so an explicitly blanked key in a
   // decoded JSON config took the default instead of the refusal `finiteCount` is here to raise.
@@ -216,7 +197,12 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
     };
   };
 
-  return {
+  /** The HEAD a lost write's answer is settled against, and the `.catch` of a single PUT. */
+  const statOf = async (key: string) => ((await present(key)) ? statObject(key) : undefined);
+  const lostPut = (key: string, bytes: Uint8Array, attributes: PutOptions | undefined) =>
+    settleLostPut(statOf, { driver: DRIVER_NAME, key, bytes, attributes }, refusedWrite(key));
+
+  const disk: StorageDriver = {
     name: DRIVER_NAME,
     registerAs(name: string): void {
       diskName = name;
@@ -240,7 +226,9 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       if (putOptions !== undefined && needsSignedPut(putOptions)) {
         // Off the Bun client only for what it cannot send: `S3File.write` takes a type, an ACL and
         // a storage class and no header. One request either way — never a PUT then a second call.
-        const refusal = await signedPut(options, safe, bytes, putOptions).catch(refusedWrite(safe));
+        const refusal = await signedPut(options, safe, bytes, putOptions).catch(
+          lostPut(safe, bytes, putOptions),
+        );
         if (refusal !== undefined) refusedWrite(safe)(refusal);
         // Stored — the PUT succeeded with them — so reported, as the local disk reports its own.
         return {
@@ -254,10 +242,37 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       await conn()
         .file(safe)
         .write(bytes, { type: putOptions?.contentType ?? DEFAULT_CONTENT_TYPE })
-        .catch(refusedWrite(safe));
+        .catch(lostPut(safe, bytes, putOptions));
       return statObject(safe);
     },
 
+    async putStream(
+      key: string,
+      body: ReadableStream<Uint8Array>,
+      streamOptions: PutStreamOptions,
+    ): Promise<StorageObject> {
+      const safe = assertSafeKey(key);
+      const maxBytes = assertPutStream(DRIVER_NAME, body, streamOptions);
+      await putS3Stream(options, {
+        key: safe,
+        body,
+        options: streamOptions,
+        maxBytes,
+        driver: DRIVER_NAME,
+        refused: refusedWrite(safe),
+        stat: statOf,
+      }).catch(refusedWrite(safe));
+      return {
+        ...(await statObject(safe)),
+        ...(streamOptions.cacheControl === undefined
+          ? {}
+          : { cacheControl: streamOptions.cacheControl }),
+        ...(streamOptions.metadata === undefined
+          ? {}
+          : { metadata: { ...streamOptions.metadata } }),
+      };
+    },
+
     async stat(key: string): Promise<StorageObject | undefined> {
       const safe = assertSafeKey(key);
       return (await present(safe)) ? statObject(safe) : undefined;
@@ -305,6 +320,20 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       return file.stream();
     },
 
+    async streamRange(key: string, range: ByteRange): Promise<ReadableStream<Uint8Array>> {
+      const safe = assertSafeKey(key);
+      assertStreamRange(DRIVER_NAME, range);
+      if (!(await present(safe))) throw objectNotFound(diskName, safe);
+      // The HEAD first: past the end, Bun's slice raises from inside the stream, after a caller has
+      // already answered 206. Refused here it is still a status.
+      const { size } = await statObject(safe);
+      const [first, last] = streamedRange(DRIVER_NAME, safe, range, size);
+      return conn()
+        .file(safe)
+        .slice(first, last + 1)
+        .stream();
+    },
+
     /**
      * Bytes from one key to another without a round trip through this process. Bun exposes no
      * `CopyObject`, so the source `S3File` is handed to `write()` — Bun's own union accepts one —
@@ -312,9 +341,20 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
      * win available today: promoting a 500MB attachment used to be `get()` + `put()`, a full GB
      * resident in the pod. A true server-side copy needs a Bun API that does not exist in 1.3.
      */
-    async copy(from: string, to: string): Promise<StorageObject> {
+    async copy(from: string, to: string, copyOptions?: CopyOptions): Promise<StorageObject> {
       const source = assertSafeKey(from);
       const destination = assertSafeKey(to);
+      // Bun's `write` takes no condition, so a revision-bound copy is the signed CopyObject.
+      if (copyOptions?.ifMatch !== undefined) {
+        const refusal = await signedCopy(options, source, destination, copyOptions.ifMatch).catch(
+          refusedWrite(destination),
+        );
+        if (refusal?.statusCode === 404) throw objectNotFound(diskName, source);
+        if (refusal?.statusCode === 412)
+          throw objectChanged(source, copyOptions.ifMatch, 'another');
+        if (refusal !== undefined) refusedWrite(destination)(refusal);
+        return statObject(destination);
+      }
       const file = conn().file(source);
       if (!(await present(source))) throw objectNotFound(diskName, source);
       const stat = await file.stat().catch(refusedRead(source));
@@ -421,29 +461,13 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       );
     },
 
-    /**
-     * Provider presigning. The signature covers method, expiry and content type but NOT
-     * `maxBytes` — S3 has no header for it, so size stays a server-side policy check.
-     */
+    /** Both presigners, one rule: `driver-s3-presign.ts`. */
     async signedUrl(key: string, urlOptions?: SignedUrlOptions): Promise<string> {
-      // Screened with the SAME function `buildSignedUrl` applies on the local disk — one
-      // finite-bound path for both presigners, never a private copy per package: `Math.ceil(NaN /
-      // 1000)` is `NaN`, so `X-Amz-Expires=NaN` went to AWS and the app got a 403 on a link it
-      // believed it had just minted. `=== undefined` rather than `??`, so an explicit `null` is
-      // refused instead of silently taking the default.
-      const expiresInMs = finiteCount(
-        'the s3 driver',
-        'expiresInMs',
-        urlOptions?.expiresInMs === undefined ? DEFAULT_SIGNED_URL_TTL_MS : urlOptions.expiresInMs,
-        1,
-      );
-      return conn()
-        .file(assertSafeKey(key))
-        .presign({
-          method: urlOptions?.method ?? 'GET',
-          expiresIn: Math.ceil(expiresInMs / 1000),
-          ...(urlOptions?.contentType === undefined ? {} : { type: urlOptions.contentType }),
-        });
+      return s3SignedUrl(options, (safe) => conn().file(safe), key, urlOptions);
     },
   };
+  // Attached in place: the capability presigns and stats through the disk it belongs to.
+  return Object.assign(disk, {
+    multipart: s3Multipart({ wire: options, driver: disk, refusedWrite }),
+  });
 }

package/src/driver.ts

@@ -5,10 +5,13 @@
 
 import type { Clock, Page } from '@ultimat3/core';
 import { assert } from '@ultimat3/core';
+import { pumpBounded } from './byte-pump';
 import { putTooLarge } from './errors';
+import type { MultipartCapability } from './multipart';
 import type { ObjectLock, ObjectLockOptions } from './object-lock';
+import type { PutStreamOptions } from './put-stream';
 import type { ByteRange, GetOptions } from './range';
-import type { SignedUrlVerification } from './signed-url';
+import type { SignedPart, SignedUrlVerification } from './signed-url';
 
 export type StorageBody = Uint8Array | ReadableStream<Uint8Array> | Blob;
 
@@ -99,18 +102,30 @@ export interface SignedUrlOptions {
   readonly method?: SignedUrlMethod | undefined;
   readonly expiresInMs?: number | undefined;
   /**
-   * Ceiling on a `PUT`, and **the one option whose enforcement is the driver's, not the caller's**.
-   *
-   * `localDriver` signs it into the URL, so `acceptSignedUpload` refuses a client that widens it.
-   * `s3Driver` CANNOT: S3 has no request header for a size and Bun's `presign` covers method,
-   * expiry and content type only — so the client PUTs straight into the bucket and nothing between
-   * the grant and the object enforces this number. It is not refused there, because `grantUpload`
-   * supplies it on every grant and refusing would break every s3 upload an app mints; the ceiling
-   * a bucket-backed disk actually gets is a bucket rule or a post-upload check on `object.size`.
-   * `driver-parity.test.ts` pins both halves so neither moves alone.
+   * Ceiling on a `PUT`. `localDriver` signs it into the URL, so `acceptSignedUpload` refuses a client
+   * that widens it. A provider's URL has no ceiling to sign, so `s3Driver` refuses it without
+   * `contentLength` (`X_STORAGE_UPLOAD_SIZE_UNDECLARED`) rather than mint a URL that ignores it.
    */
   readonly maxBytes?: number | undefined;
+  /**
+   * The exact size of a `PUT`, inside the signature. On `s3Driver` the URL then signs
+   * `content-length`, so the provider refuses any other length, a chunked body with none included
+   * (403 `SignatureDoesNotMatch`). The local disks hold it as a ceiling (`x-max`): they count what
+   * arrives, so a shorter body passes there and not on s3. `driver-parity.test.ts` pins both.
+   */
+  readonly contentLength?: number | undefined;
   readonly contentType?: string | undefined;
+  /**
+   * A part of an open upload, inside the signature: the URL then writes that part and nothing else.
+   * Only a disk whose `multipart.receivePart` stores parts signs one; `s3Driver` refuses it, since
+   * its parts are signed by `multipart.signPart` against the provider.
+   */
+  readonly part?: SignedPart | undefined;
+}
+
+export interface CopyOptions {
+  /** The source's `etag` as this disk reported it. */
+  readonly ifMatch?: string | undefined;
 }
 
 export interface StorageDriver {
@@ -133,6 +148,16 @@ export interface StorageDriver {
    */
   registerAs?(diskName: string): void;
   put(key: string, body: StorageBody, options?: PutOptions): Promise<StorageObject>;
+  /**
+   * A body of any length, without buffering it: counted against the call's required `maxBytes`, and
+   * past it the write is abandoned with the key as it was (`X_STORAGE_TOO_LARGE`). Takes no
+   * `checksum`, retention or legal hold, which need the bytes before the object exists.
+   */
+  putStream(
+    key: string,
+    stream: ReadableStream<Uint8Array>,
+    options: PutStreamOptions,
+  ): 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
@@ -149,12 +174,19 @@ export interface StorageDriver {
   get(key: string, options?: GetOptions): Promise<StorageRead>;
   /** Bytes without buffering — the only safe path for anything over a few MB. */
   stream(key: string): Promise<ReadableStream<Uint8Array>>;
+  /**
+   * The bytes `[first, last]` (inclusive, clamped, as `get`'s range) with none before them read, so
+   * a seek late in a film costs its window. `X_STORAGE_RANGE_UNSATISFIABLE` past the end. A method and
+   * not an option on `stream`, which a third-party driver would ignore and serve the wrong bytes.
+   */
+  streamRange(key: string, range: ByteRange): Promise<ReadableStream<Uint8Array>>;
   /**
    * Bytes from one key to another without them passing through this process. Idempotent in the
    * destination and non-destructive in the source: the caller deletes the source afterwards if
-   * it wanted a move. `X_STORAGE_NOT_FOUND` when `from` is absent.
+   * it wanted a move. `X_STORAGE_NOT_FOUND` when `from` is absent. `ifMatch` copies only that
+   * revision: any other is `X_STORAGE_OBJECT_CHANGED` and writes nothing.
    */
-  copy(from: string, to: string): Promise<StorageObject>;
+  copy(from: string, to: string, options?: CopyOptions): Promise<StorageObject>;
   /**
    * Deleting an ABSENT key is not an error. Anything else is: a denied `s3:DeleteObject`, a
    * throttle, an expired credential and a read-only mount all raise `X_STORAGE_DELETE_FAILED`,
@@ -193,6 +225,12 @@ export interface StorageDriver {
    * provider and never reaches this path, and a third-party driver that implements neither is
    * refused by name (`X_STORAGE_URL_UNVERIFIABLE`) rather than reported as a bad signature.
    */
+  /**
+   * An upload in parts: resumable, and past S3's 5 GiB single-PUT ceiling. Optional, so a
+   * third-party driver still compiles; `grantMultipart` refuses a disk without it
+   * (`X_STORAGE_MULTIPART_UNSUPPORTED`). Every shipped disk has one.
+   */
+  readonly multipart?: MultipartCapability | undefined;
   verifySigned?(input: {
     readonly url: string;
     /** Overrides the driver's own, so a test's frozen clock still governs expiry. */
@@ -251,6 +289,36 @@ export function assertPutOptions(driver: string, options: PutOptions | undefined
   );
 }
 
+/**
+ * The number a signed URL holds, screened on every disk: `contentLength` when there is one, since it
+ * is the tighter fact, and a `contentLength` past `maxBytes` or on anything but a `PUT` is a call
+ * that contradicts itself.
+ */
+export function signedByteBound(
+  driver: string,
+  options: SignedUrlOptions | undefined,
+): number | undefined {
+  const length = options?.contentLength;
+  if (length === undefined) return options?.maxBytes;
+  const maxBytes = options?.maxBytes;
+  assert(
+    Number.isSafeInteger(length) && length >= 0,
+    `signedUrl() on the ${driver} disk was given a contentLength that is not a whole byte count`,
+    "signedUrl(key, { method: 'PUT', contentLength: file.size })",
+  );
+  assert(
+    options?.method === 'PUT',
+    `signedUrl() on the ${driver} disk was given a contentLength on a read, which has no body to bind`,
+    "signedUrl(key, { method: 'PUT', contentLength: file.size })",
+  );
+  assert(
+    maxBytes === undefined || length <= maxBytes,
+    `signedUrl() on the ${driver} disk was given a contentLength of ${length}B past its maxBytes of ${String(maxBytes)}B`,
+    "signedUrl(key, { method: 'PUT', contentLength: file.size })   # at or under maxBytes",
+  );
+  return length;
+}
+
 /** 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) {
@@ -309,31 +377,13 @@ async function readBounded(
   body: ReadableStream<Uint8Array>,
   limit: ByteLimit,
 ): Promise<Uint8Array> {
-  const reader = body.getReader();
   const chunks: Uint8Array[] = [];
-  let total = 0;
-  try {
-    for (;;) {
-      const next = await reader.read();
-      if (next.done) break;
-      total += next.value.byteLength;
-      if (total > limit.maxBytes) {
-        throw putTooLarge(limit.driver, limit.key, total, limit.maxBytes);
-      }
-      chunks.push(next.value);
-    }
-  } finally {
-    // Cancel rather than merely release: a refused body must stop arriving, not keep filling a
-    // socket buffer nobody will read. Already-closed streams answer this with a no-op.
-    await reader.cancel().catch(() => undefined);
-  }
-  const bytes = new Uint8Array(total);
-  let offset = 0;
-  for (const chunk of chunks) {
-    bytes.set(chunk, offset);
-    offset += chunk.byteLength;
-  }
-  return bytes;
+  const { driver, key, maxBytes } = limit;
+  const refuse = (total: number): Error => putTooLarge(driver, key, total, maxBytes);
+  await pumpBounded(body, { driver, maxBytes, refuse }, (chunk) => {
+    chunks.push(chunk);
+  });
+  return new Uint8Array(Bun.concatArrayBuffers(chunks));
 }
 
 /** base64 SHA-256 — the wire form for `PutOptions.checksum` and `ValidatedUpload.checksum`. */

package/src/errors-multipart.ts

@@ -0,0 +1,35 @@
+// The refusals of an upload in parts. Registered with the rest of the package's codes in
+// `errors.ts`; each `fix:` names the call that goes next, with the key and upload id screened.
+
+import { renderFixLiteral } from '@ultimat3/core';
+import { StorageError } from './errors';
+
+const keyArg = (key: string): string => renderFixLiteral(key, "'<key>'");
+const idArg = (uploadId: string): string => renderFixLiteral(uploadId, "'<uploadId>'");
+
+/** A disk whose driver declares no `multipart`: a third-party driver, most likely. */
+export const multipartUnsupported = (disk: string, key: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_MULTIPART_UNSUPPORTED',
+    cause: `the ${disk} disk's driver declares no multipart capability, so "${key}" cannot be uploaded in parts`,
+    fix: 'grantUpload({ disk, orgId, request })   # one PUT; or implement StorageDriver.multipart on the driver',
+    meta: { disk, key },
+  });
+
+/** No open session by that id for that key: never opened, completed, or aborted. */
+export const uploadUnknown = (disk: string, key: string, uploadId: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_UPLOAD_UNKNOWN',
+    cause: `no upload ${idArg(uploadId)} is open for "${key}" on the ${disk} disk: it was never opened there, or it was already completed or aborted`,
+    fix: 'grantMultipart({ disk, orgId, request })   # a new session, then send every part under its uploadId',
+    meta: { disk, key, uploadId },
+  });
+
+/** The parts a Complete named do not match what the disk holds. */
+export const partsInvalid = (key: string, uploadId: string, problem: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_PARTS_INVALID',
+    cause: `the parts named to complete "${key}" do not match the parts stored: ${problem}`,
+    fix: `await listParts({ disk, orgId, key: ${keyArg(key)}, uploadId: ${idArg(uploadId)} })   # what landed; resend the missing part, then completeUpload again`,
+    meta: { key, uploadId, problem },
+  });

package/src/errors-promote.ts

@@ -2,6 +2,7 @@
 // still in quarantine, a key that is not a pending upload, and one an earlier call already moved.
 // Their codes are registered with the rest of the package's in `errors.ts`.
 
+import { renderFixLiteral } from '@ultimat3/core';
 import { StorageError } from './errors';
 
 /**
@@ -42,3 +43,16 @@ export const alreadyPromoted = (key: string, attachedKey: string, orgId: string)
     fix: `await disk.stat('${attachedKey}') answers the moved object: answer the row that references that key if one exists, write it with that key if none does, and never delete the key on a failure of your own`,
     meta: { key, attachedKey, orgId },
   });
+
+/**
+ * The object is no longer the revision that was judged. A presigned PUT stays valid until it
+ * expires, so an uploader can overwrite between the sniff and the copy, and what would land on the
+ * row's key is bytes nothing looked at.
+ */
+export const objectChanged = (key: string, expected: string, actual: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_OBJECT_CHANGED',
+    cause: `"${key}" changed while it was being promoted: it was judged at ${expected} and is now ${actual}`,
+    fix: `promoteAttachment({ disk, key: ${renderFixLiteral(key, "'<pending key>'")}, orgId, target, policy }) once the upload has finished: it reads the object again`,
+    meta: { key, expected, actual },
+  });

package/src/errors-sniff.ts

@@ -0,0 +1,35 @@
+// The two refusals only a bounded sniff can reach: markup that could sit past what was read. Their
+// code is `X_STORAGE_TYPE_REJECTED`, registered with the rest of the package's in `errors.ts`; they
+// are their own constructors because the sniff saw nothing to name, so `contentTypeMismatch`'s
+// "re-upload with the sniffed type" would be advice about a type nobody found.
+
+import { renderFixLiteral } from '@ultimat3/core';
+import { StorageError } from './errors';
+
+/**
+ * A body opening with more whitespace than `limit` bytes. Past a window nothing is seen, so padding
+ * is how markup would hide from a head read, and no real file opens this way.
+ */
+export const leadingWhitespacePastLimit = (
+  key: string,
+  declared: string,
+  limit: number,
+): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_TYPE_REJECTED',
+    cause: `"${key}" declares ${declared} and opens with more than ${limit} bytes of whitespace, so its type cannot be read`,
+    fix: `validateUpload({ key: ${renderFixLiteral(key, "'a/file.txt'")}, declaredContentType: ${renderFixLiteral(declared, "'text/plain'")}, bytes: new TextEncoder().encode(text.trimStart()) }, policy) — where text is the file with its leading whitespace removed`,
+    meta: { key, declared, limit },
+  });
+
+/**
+ * An XML document too long for a head window to screen: XML runs a script anywhere in the tree, so
+ * no prefix can clear it. The server-side path reads all of it, which is the way through.
+ */
+export const xmlBodyPastWindow = (key: string, declared: string, window: number): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_TYPE_REJECTED',
+    cause: `"${key}" declares ${declared} and is over the ${window} bytes promotion reads, and an XML document can run a script anywhere in it`,
+    fix: `validateUpload({ key: ${renderFixLiteral(key, "'a/data.xml'")}, declaredContentType: ${renderFixLiteral(declared, "'application/xml'")}, bytes }, policy) — upload it through the server, which reads the whole body, then disk.put(key, bytes, { contentType })`,
+    meta: { key, declared, window },
+  });

package/src/errors-stream.ts

@@ -0,0 +1,62 @@
+// The refusals of the streaming calls and of a size a grant was not told. Registered with the rest
+// of the package's codes in `errors.ts`; each `fix:` names the call that goes next, because these
+// calls have their own option where `put()`'s refusal names the disk's ceiling.
+
+import { describeValue, renderFixLiteral, renderThrowable } from '@ultimat3/core';
+import { StorageError } from './errors';
+
+const keyArg = (key: string): string => renderFixLiteral(key, "'<key>'");
+
+/** A `putStream` body past the call's own `maxBytes`. Counted, so `bytes` is how far it had got. */
+export const streamTooLarge = (
+  disk: string,
+  key: string,
+  bytes: number,
+  maxBytes: number,
+): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_TOO_LARGE',
+    cause: `the stream for "${key}" passed its maxBytes of ${maxBytes}B at ${bytes}B on the ${disk} disk, so the write was abandoned and nothing was stored`,
+    fix: `await disk.putStream(${keyArg(key)}, stream, { maxBytes: ${bytes * 2} })   # a higher maxBytes on the call, if a body this large is meant`,
+    meta: { disk, key, bytes, maxBytes },
+  });
+
+/** `rangeUnsatisfiable` for a call that holds no size: the next step is learning it. */
+export const streamRangeUnsatisfiable = (
+  disk: string,
+  key: string,
+  range: readonly [number, number],
+  size: number,
+): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_RANGE_UNSATISFIABLE',
+    cause: `streamRange() asked "${key}" for bytes ${range[0]}-${range[1]}, and the object on the ${disk} disk is ${size}B, so its first byte is past the end`,
+    fix: `const { size } = await disk.stat(${keyArg(key)})   # the object's size now; any first byte below it is a window`,
+    meta: { disk, key, first: range[0], last: range[1], size },
+  });
+
+/**
+ * A grant with nothing to bind. A presign has one way to hold a size, the exact `Content-Length`
+ * inside the signature, so "any size up to the policy" is a URL that bounds nothing.
+ */
+export const uploadSizeUndeclared = (key: string, size: unknown): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_UPLOAD_SIZE_UNDECLARED',
+    cause: `the upload for "${key}" declared its size as ${describeValue(size)}, not a whole byte count of at least 1, so the URL could not bind one`,
+    fix: 'grantUpload({ disk, orgId, request: { filename, contentType, size: file.size } })',
+    meta: { key },
+  });
+
+/**
+ * A write sent whose answer was lost, and nothing could settle what it did. Never `putFailed`: that
+ * says the key is as it was, and the object may be the one sent. `X_DB_COMMIT_UNKNOWN`'s idea.
+ */
+export const writeOutcomeUnknown = (disk: string, key: string, lost: unknown): StorageError => {
+  const reason = renderThrowable(lost);
+  return new StorageError({
+    code: 'X_STORAGE_WRITE_OUTCOME_UNKNOWN',
+    cause: `the write of "${key}" on the ${disk} disk was sent and its answer lost (${reason}), and neither a stat nor an abort could say whether it landed`,
+    fix: `await disk.stat(${keyArg(key)})   # the size and etag now at the key; the same as what was sent means it landed`,
+    meta: { disk, key, reason },
+  });
+};

package/src/errors.ts

@@ -33,6 +33,12 @@ export const STORAGE_OWNED_ERROR_CODES = [
   'X_STORAGE_KEY_UNSHARED',
   'X_STORAGE_ALREADY_PROMOTED',
   'X_STORAGE_RANGE_UNSATISFIABLE',
+  'X_STORAGE_OBJECT_CHANGED',
+  'X_STORAGE_UPLOAD_SIZE_UNDECLARED',
+  'X_STORAGE_WRITE_OUTCOME_UNKNOWN',
+  'X_STORAGE_MULTIPART_UNSUPPORTED',
+  'X_STORAGE_UPLOAD_UNKNOWN',
+  'X_STORAGE_PARTS_INVALID',
 ] as const;
 
 /**
@@ -76,6 +82,13 @@ export const STORAGE_ERROR_TITLES: Readonly<Record<StorageOwnedErrorCode, string
   X_STORAGE_KEY_UNSHARED: 'object key is outside every tenant and every shared prefix',
   X_STORAGE_ALREADY_PROMOTED: 'the upload was already promoted onto its row',
   X_STORAGE_RANGE_UNSATISFIABLE: 'the requested byte range starts past the end of the object',
+  X_STORAGE_OBJECT_CHANGED: 'the object changed while it was being promoted',
+  X_STORAGE_UPLOAD_SIZE_UNDECLARED: 'an upload grant was asked for without the size of the file',
+  X_STORAGE_WRITE_OUTCOME_UNKNOWN:
+    'a write was sent and its answer lost, and the disk could not say whether it landed',
+  X_STORAGE_MULTIPART_UNSUPPORTED: 'this disk cannot take an upload in parts',
+  X_STORAGE_UPLOAD_UNKNOWN: 'no open multipart upload has that id',
+  X_STORAGE_PARTS_INVALID: 'the parts named do not match the parts stored',
 };
 
 // One unconditional call, so a second package claiming one of storage's codes throws