@ultimat3/storage 29.3.2 → 30.0.0

package/src/driver-s3-multipart.ts

@@ -0,0 +1,177 @@
+// Single responsibility: the S3 multipart calls (create, part, complete, abort, list parts, list uploads) over the disk's signed requests. Each answers
+// what its caller goes on with, or hands the provider's refusal to the disk's coded `refused`. The
+// order they run in, and what a failure aborts, is the caller's.
+
+import { escapeHtml } from '@ultimat3/core';
+import { type S3Refusal, type S3WireOptions, sendSigned, xmlField } from './driver-s3-signed';
+import type { MultipartSession, UploadedPart } from './multipart';
+
+export interface S3UploadTarget {
+  readonly wire: S3WireOptions;
+  readonly key: string;
+  /** The disk's coded write refusal. A refusal is never thrown bare. */
+  readonly refused: (refusal: S3Refusal) => never;
+}
+
+const unreadable = (what: string): S3Refusal => ({
+  name: 'S3Error',
+  code: 'UnreadableAnswer',
+  message: `the provider's answer to ${what} carried nothing to go on`,
+  statusCode: 200,
+});
+
+/** Every `<name>…</name>` block of an S3 listing, in order; the shapes read here are flat. */
+export const xmlBlocks = (xml: string, name: string): readonly string[] =>
+  [...xml.matchAll(new RegExp(`<${name}>([\\s\\S]*?)</${name}>`, 'g'))].map(
+    (match) => match[1] ?? '',
+  );
+
+/** XML's entities: S3 writes an etag as `&quot;…&quot;` and a key's `&` as `&amp;`. */
+export const xmlText = (text: string): string =>
+  text
+    // A numeric reference too: a gateway writes the etag's quotes as `&#34;`, S3 as `&quot;`.
+    .replace(/&#(x[0-9a-f]{1,6}|[0-9]{1,7});/gi, (_, code: string) =>
+      String.fromCodePoint(
+        Math.min(Number(code[0] === 'x' || code[0] === 'X' ? `0${code}` : code), 0x10ffff),
+      ),
+    )
+    .replaceAll('&quot;', '"')
+    .replaceAll('&apos;', "'")
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&amp;', '&');
+
+// Core's table: `&#39;`/`&quot;` are numeric/XML references too, so its output is valid XML text.
+const completeXml = (parts: readonly { partNumber: number; etag: string }[]): Uint8Array =>
+  new TextEncoder().encode(
+    `<CompleteMultipartUpload>${parts
+      .map(
+        ({ partNumber, etag }) =>
+          `<Part><PartNumber>${partNumber}</PartNumber><ETag>${escapeHtml(etag)}</ETag></Part>`,
+      )
+      .join('')}</CompleteMultipartUpload>`,
+  );
+
+/** CreateMultipartUpload. The object's own headers travel here: a part has none. */
+export async function createS3Upload(
+  { wire, key, refused }: S3UploadTarget,
+  headers: Readonly<Record<string, string>>,
+): Promise<string> {
+  const result = await sendSigned(wire, { method: 'POST', key, headers, query: { uploads: '' } });
+  if (!result.ok) return refused(result.refusal);
+  const id = xmlField(await result.response.text(), 'UploadId');
+  return id === undefined ? refused(unreadable('CreateMultipartUpload')) : id;
+}
+
+/** UploadPart, answering the etag the Complete must name. */
+export async function uploadS3Part(
+  { wire, key, refused }: S3UploadTarget,
+  uploadId: string,
+  partNumber: number,
+  body: Uint8Array,
+): Promise<string> {
+  const result = await sendSigned(wire, {
+    method: 'PUT',
+    key,
+    query: { partNumber: String(partNumber), uploadId },
+    body,
+  });
+  if (!result.ok) return refused(result.refusal);
+  await result.response.body?.cancel().catch(() => undefined);
+  const etag = result.response.headers.get('etag');
+  return etag === null ? refused(unreadable('UploadPart')) : etag;
+}
+
+/** CompleteMultipartUpload, `parts` ascending. The object exists only once this returns. */
+export async function completeS3Upload(
+  { wire, key, refused }: S3UploadTarget,
+  uploadId: string,
+  parts: readonly { readonly partNumber: number; readonly etag: string }[],
+): Promise<void> {
+  const result = await sendSigned(wire, {
+    method: 'POST',
+    key,
+    query: { uploadId },
+    body: completeXml(parts),
+  });
+  if (!result.ok) return refused(result.refusal);
+  // S3 answers a failed Complete with 200 and an `<Error>` body, once it has started working.
+  const answer = await result.response.text();
+  if (answer.includes('<Error>')) {
+    refused({
+      name: 'S3Error',
+      code: xmlField(answer, 'Code') ?? 'CompleteFailed',
+      message: xmlField(answer, 'Message') ?? 'the provider refused the Complete',
+      statusCode: 200,
+    });
+  }
+}
+
+/** AbortMultipartUpload. `undefined` on success; the refusal otherwise, for the caller to weigh. */
+export async function abortS3Upload(
+  { wire, key }: S3UploadTarget,
+  uploadId: string,
+): Promise<S3Refusal | undefined> {
+  const result = await sendSigned(wire, { method: 'DELETE', key, query: { uploadId } });
+  return result.ok ? undefined : result.refusal;
+}
+
+/** ListParts, every page: what landed, which is the resume and the Complete's etags. */
+export async function listS3Parts(
+  { wire, key, refused }: S3UploadTarget,
+  uploadId: string,
+): Promise<readonly UploadedPart[]> {
+  const parts: UploadedPart[] = [];
+  let marker: string | undefined;
+  for (;;) {
+    const query = { uploadId, ...(marker === undefined ? {} : { 'part-number-marker': marker }) };
+    const result = await sendSigned(wire, { method: 'GET', key, query });
+    if (!result.ok) return refused(result.refusal);
+    const answer = await result.response.text();
+    for (const block of xmlBlocks(answer, 'Part')) {
+      const partNumber = Number(xmlField(block, 'PartNumber'));
+      const size = Number(xmlField(block, 'Size'));
+      const etag = xmlText(xmlField(block, 'ETag') ?? '');
+      if (Number.isSafeInteger(partNumber) && Number.isSafeInteger(size) && etag !== '') {
+        parts.push({ partNumber, etag, size });
+      }
+    }
+    marker = xmlField(answer, 'NextPartNumberMarker');
+    if (xmlField(answer, 'IsTruncated') !== 'true' || marker === undefined) break;
+  }
+  return parts.sort((a, b) => a.partNumber - b.partNumber);
+}
+
+/** ListMultipartUploads under a prefix, every page: the sessions nobody completed or aborted. */
+export async function listS3Uploads(
+  { wire, refused }: Omit<S3UploadTarget, 'key'>,
+  prefix: string | undefined,
+): Promise<readonly MultipartSession[]> {
+  const sessions: MultipartSession[] = [];
+  let markers: Readonly<Record<string, string>> = {};
+  for (;;) {
+    const query = { uploads: '', ...(prefix === undefined ? {} : { prefix }), ...markers };
+    const result = await sendSigned(wire, { method: 'GET', key: '', query });
+    if (!result.ok) return refused(result.refusal);
+    const answer = await result.response.text();
+    for (const block of xmlBlocks(answer, 'Upload')) {
+      const key = xmlText(xmlField(block, 'Key') ?? '');
+      const uploadId = xmlText(xmlField(block, 'UploadId') ?? '');
+      const initiated = new Date(xmlField(block, 'Initiated') ?? '');
+      if (key === '' || uploadId === '') continue;
+      sessions.push({
+        key,
+        uploadId,
+        ...(Number.isNaN(initiated.getTime()) ? {} : { initiated }),
+      });
+    }
+    const nextKey = xmlField(answer, 'NextKeyMarker');
+    const nextId = xmlField(answer, 'NextUploadIdMarker');
+    if (xmlField(answer, 'IsTruncated') !== 'true' || nextKey === undefined) break;
+    markers = {
+      'key-marker': xmlText(nextKey),
+      ...(nextId === undefined ? {} : { 'upload-id-marker': xmlText(nextId) }),
+    };
+  }
+  return sessions;
+}

package/src/driver-s3-presign.ts

@@ -0,0 +1,52 @@
+// Single responsibility: the s3 disk's `signedUrl`, both presigners under one rule. Bun's presign
+// binds method and expiry and signs `host` alone: `type` becomes `response-content-type`, which
+// governs a GET, so a PUT's `Content-Type` is unsigned and `promoteAttachment` sniffs the object. A
+// `contentLength` leaves Bun for core's signer, the one way a presign can hold a size.
+
+import { assert, finiteCount, MAX_AWS_PRESIGN_SECONDS } from '@ultimat3/core';
+import { type SignedUrlOptions, signedByteBound } from './driver';
+import type { S3FileLike } from './driver-s3-client';
+import { presignBoundPut, type S3WireOptions } from './driver-s3-signed';
+import { uploadSizeUndeclared } from './errors-stream';
+import { assertSafeKey } from './path';
+import { DEFAULT_SIGNED_URL_TTL_MS } from './signed-url';
+
+export async function s3SignedUrl(
+  wire: S3WireOptions,
+  fileOf: (key: string) => S3FileLike,
+  key: string,
+  urlOptions: SignedUrlOptions | undefined,
+): Promise<string> {
+  // Screened with the SAME function `buildSignedUrl` applies on the local disk: `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.
+  const expiresInMs = finiteCount(
+    'the s3 driver',
+    'expiresInMs',
+    urlOptions?.expiresInMs === undefined ? DEFAULT_SIGNED_URL_TTL_MS : urlOptions.expiresInMs,
+    1,
+  );
+  const seconds = Math.ceil(expiresInMs / 1000);
+  // Before the branch, so Bun's presign cannot mint a URL past SigV4's limit the other refuses.
+  assert(
+    seconds <= MAX_AWS_PRESIGN_SECONDS,
+    `signedUrl() on the s3 disk was given expiresInMs ${expiresInMs}, past SigV4's seven days`,
+    `signedUrl(key, { expiresInMs: ${MAX_AWS_PRESIGN_SECONDS * 1000} })   # the longest a presign lives`,
+  );
+  const safe = assertSafeKey(key);
+  const contentLength = signedByteBound('s3', urlOptions);
+  if (urlOptions?.contentLength !== undefined && contentLength !== undefined) {
+    return presignBoundPut(wire, safe, contentLength, seconds, urlOptions?.part);
+  }
+  // A part names its exact size or nothing: Bun's presign below would drop it and sign a whole PUT.
+  if (urlOptions?.part !== undefined) throw uploadSizeUndeclared(safe, undefined);
+  // A ceiling bounds a PUT; a read has no body, and the local disks ignore it there too.
+  if (urlOptions?.method === 'PUT' && urlOptions.maxBytes !== undefined) {
+    throw uploadSizeUndeclared(safe, undefined);
+  }
+  return fileOf(safe).presign({
+    method: urlOptions?.method ?? 'GET',
+    expiresIn: seconds,
+    ...(urlOptions?.contentType === undefined ? {} : { type: urlOptions.contentType }),
+  });
+}

package/src/driver-s3-put-stream.ts

@@ -0,0 +1,97 @@
+// Single responsibility: `putStream` on the s3 wire — the pump that cuts a body into parts. Not
+// `S3File.writer()`, measured on Bun 1.4.4: `end(error)` COMPLETES the upload, so an overrun would
+// replace the object at the key, and the writer cannot send `x-amz-meta-*`. Here the object does not
+// exist until the Complete, and every other exit aborts.
+
+import { pumpBounded } from './byte-pump';
+import type { PutOptions } from './driver';
+import { objectHeaders, signedPut } from './driver-s3-lock';
+import {
+  abortS3Upload,
+  completeS3Upload,
+  createS3Upload,
+  type S3UploadTarget,
+  uploadS3Part,
+} from './driver-s3-multipart';
+import {
+  isAnswered,
+  multipartEtagOf,
+  type S3Stat,
+  sentObject,
+  settleComplete,
+  settleLostPut,
+} from './driver-s3-settle';
+import type { S3WireOptions } from './driver-s3-signed';
+import { partBytesFor } from './multipart';
+import type { PutStreamOptions } from './put-stream';
+import { streamLimit } from './put-stream';
+
+export interface S3PutStreamInput extends Pick<S3UploadTarget, 'key' | 'refused'> {
+  readonly body: ReadableStream<Uint8Array>;
+  readonly options: PutStreamOptions;
+  readonly maxBytes: number;
+  readonly driver: string;
+  /** The disk's HEAD, asked only when a last request's answer was lost. */
+  readonly stat: S3Stat;
+}
+
+/** The whole body, stored — or nothing stored and the key as it was. */
+export async function putS3Stream(wire: S3WireOptions, input: S3PutStreamInput): Promise<void> {
+  const { key, body, options, maxBytes, driver, refused, stat } = input;
+  const target: S3UploadTarget = { wire, key, refused };
+  const putOptions: PutOptions = options;
+  // Screened before a byte is read: a header that cannot travel fails here, not on the Create.
+  const headers = objectHeaders(putOptions);
+  const partBytes = partBytesFor(maxBytes);
+  let chunks: Uint8Array[] = [];
+  let held = 0;
+  let total = 0;
+  let uploadId: string | undefined;
+  const etags: string[] = [];
+
+  const sendPart = async (): Promise<void> => {
+    uploadId ??= await createS3Upload(target, headers);
+    const part = new Uint8Array(Bun.concatArrayBuffers(chunks));
+    chunks = [];
+    held = 0;
+    etags.push(await uploadS3Part(target, uploadId, etags.length + 1, part));
+  };
+
+  try {
+    await pumpBounded(body, streamLimit(driver, key, maxBytes), async (chunk) => {
+      chunks.push(chunk);
+      held += chunk.byteLength;
+      total += chunk.byteLength;
+      if (held >= partBytes) await sendPart();
+    });
+    if (uploadId === undefined) {
+      const whole = new Uint8Array(Bun.concatArrayBuffers(chunks));
+      const rethrow = (error: unknown): never => {
+        throw error;
+      };
+      const refusal = await signedPut(wire, key, whole, putOptions).catch(
+        settleLostPut(stat, { driver, key, bytes: whole, attributes: options }, rethrow),
+      );
+      if (refusal !== undefined) refused(refusal);
+      return;
+    }
+    if (held > 0) await sendPart();
+    const open = uploadId;
+    await completeS3Upload(
+      target,
+      open,
+      etags.map((etag, at) => ({ partNumber: at + 1, etag })),
+    ).catch(async (lost: unknown) => {
+      if (isAnswered(lost)) throw lost;
+      // Settled here, abort included, so the catch below must not abort a second time.
+      uploadId = undefined;
+      const sent = sentObject(total, multipartEtagOf(etags), options);
+      await settleComplete(stat, { ...target, driver }, open, sent, lost);
+    });
+  } catch (error) {
+    // Parts bill until they are aborted. The refusal the caller reads is the first one, so an abort
+    // that fails too is left to the bucket's lifecycle rule rather than replacing it.
+    if (uploadId !== undefined) await abortS3Upload(target, uploadId).catch(() => undefined);
+    throw error;
+  }
+}

package/src/driver-s3-range.ts

@@ -0,0 +1,99 @@
+// Single responsibility: the s3 disk's ranged read — ONE signed GET whose `Range:` answer carries
+// the bytes AND what they are (`Content-Range`'s window and total size, `ETag`, type, date), so the
+// slice and its description come from one response about one version. A HEAD beside it could not
+// promise that: a write between the two, or an A → B → A overwrite of one length, slips past both.
+
+import type { StorageObject, StorageRead } from './driver';
+import { DEFAULT_CONTENT_TYPE } from './driver';
+import { type S3Refusal, type S3WireOptions, sendSigned } from './driver-s3-signed';
+import { rangeTooLarge, rangeUnsatisfiable } from './errors-range';
+import type { ByteRange } from './range';
+
+/** What the driver lends this read: its coded refusals and its own HEAD for a 416's size. */
+export interface S3RangeDeps {
+  readonly driver: string;
+  readonly maxGetBytes: number;
+  /** A refusal the provider gave (403, 503, a wrong region, a 404) as the disk's coded error. */
+  readonly refused: (key: string, refusal: S3Refusal) => never;
+  /** The disk's HEAD — asked only after a 416, for the size the refusal names. */
+  readonly sizeOf: (key: string) => Promise<number>;
+  /** A response the read cannot use: no `Content-Range`, or one that is not the window asked. */
+  readonly unreadable: (key: string, why: string) => never;
+}
+
+const CONTENT_RANGE = /^bytes (\d+)-(\d+)\/(\d+)$/;
+
+/**
+ * The window asked, CAPPED at `maxGetBytes` before it is sent: the ceiling bounds the range, and the
+ * object's size is not known until the answer — so at most the ceiling crosses the wire, and an
+ * answer that shows the object went on past the cap is refused before its body is read.
+ */
+const errorMessage = (thrown: unknown): string =>
+  thrown instanceof Error ? thrown.message : String(thrown);
+
+export async function readS3Range(
+  wire: S3WireOptions,
+  key: string,
+  range: ByteRange,
+  deps: S3RangeDeps,
+): Promise<StorageRead> {
+  const [first, last] = range;
+  const capped = Math.min(last, first + deps.maxGetBytes - 1);
+  const result = await sendSigned(wire, {
+    method: 'GET',
+    key,
+    headers: { range: `bytes=${first}-${capped}` },
+  });
+  if (!result.ok) {
+    if (result.refusal.statusCode !== 416) return deps.refused(key, result.refusal);
+    // A first byte at or past the end — of the object as it is NOW, which the HEAD names.
+    throw rangeUnsatisfiable(deps.driver, key, range, await deps.sizeOf(key));
+  }
+  const { response } = result;
+  const window = CONTENT_RANGE.exec(response.headers.get('content-range') ?? '');
+  if (response.status !== 206 || window === null) {
+    await response.body?.cancel().catch(() => undefined);
+    return deps.unreadable(key, `the ranged GET answered ${response.status} with no byte range`);
+  }
+  const served: ByteRange = [Number(window[1]), Number(window[2])];
+  const size = Number(window[3]);
+  if (served[0] !== first || served[1] > capped) {
+    await response.body?.cancel().catch(() => undefined);
+    return deps.unreadable(
+      key,
+      `asked bytes ${first}-${capped}, answered ${served[0]}-${served[1]}`,
+    );
+  }
+  // Cut by the CAP, not by the end of the object: the range asked is over the ceiling.
+  if (last > capped && size - 1 > capped) {
+    await response.body?.cancel().catch(() => undefined);
+    throw rangeTooLarge(deps.driver, key, [first, Math.min(last, size - 1)], deps.maxGetBytes);
+  }
+  let bytes: Uint8Array;
+  try {
+    bytes = new Uint8Array(await response.arrayBuffer());
+  } catch (thrown) {
+    // The headers came, the body broke (a reset connection): the disk's coded read failure.
+    return deps.unreadable(key, `the ranged body broke mid-read: ${errorMessage(thrown)}`);
+  }
+  if (bytes.byteLength !== served[1] - served[0] + 1) {
+    return deps.unreadable(
+      key,
+      `Content-Range promised ${served[1] - served[0] + 1}B, the body held ${bytes.byteLength}B`,
+    );
+  }
+  return { object: objectOf(key, size, response.headers), bytes, range: served };
+}
+
+/** The WHOLE object, as the same response describes it — never a second request's view. */
+function objectOf(key: string, size: number, headers: Headers): StorageObject {
+  const modified = new Date(headers.get('last-modified') ?? '');
+  return {
+    key,
+    size,
+    contentType: headers.get('content-type') ?? DEFAULT_CONTENT_TYPE,
+    etag: headers.get('etag') ?? '',
+    // Omitted when the provider sent none, never epoch 0 — `StorageListEntry.lastModified`.
+    ...(Number.isFinite(modified.getTime()) ? { lastModified: modified } : {}),
+  };
+}

package/src/driver-s3-settle.ts

@@ -0,0 +1,150 @@
+// Single responsibility: what a write whose answer was lost actually did. The last request went out
+// and the socket died, so the provider may have stored the object. Settled by a stat against what
+// was sent, and for a multipart upload by an abort, whose answer says whether it was still open.
+// What neither can settle is `X_STORAGE_WRITE_OUTCOME_UNKNOWN`, never a refusal the disk did not make.
+
+import { isUltimateError, stringField } from '@ultimat3/core';
+import { DEFAULT_CONTENT_TYPE, type PutOptions } from './driver';
+import { abortS3Upload, type S3UploadTarget } from './driver-s3-multipart';
+import { writeOutcomeUnknown } from './errors-stream';
+
+/** The disk's own HEAD: `undefined` for nothing there. A throw is a stat that could not answer. */
+export type S3Stat = (
+  key: string,
+) => Promise<
+  { readonly size: number; readonly etag: string; readonly contentType: string } | undefined
+>;
+
+export interface SentObject {
+  readonly size: number;
+  /** The etag the provider gives exactly these bytes, unquoted; `undefined` when it cannot be known. */
+  readonly etag: string | undefined;
+  readonly contentType: string;
+  /**
+   * The write set something a HEAD does not read back (metadata, cache-control, a lock). Then a
+   * match proves only the bytes, which an overwrite of the same bytes matches already: unknown.
+   */
+  readonly unverifiable: boolean;
+}
+
+/** What a write said about the object, beyond its bytes. */
+export interface SentAttributes
+  extends Pick<PutOptions, 'contentType' | 'cacheControl' | 'metadata'> {
+  readonly retention?: unknown;
+  readonly legalHold?: unknown;
+}
+
+/** `SentObject` for `size` bytes of `etag` under `attributes`. */
+export const sentObject = (
+  size: number,
+  etag: string | undefined,
+  attributes: SentAttributes | undefined,
+): SentObject => ({
+  size,
+  etag,
+  contentType: attributes?.contentType ?? DEFAULT_CONTENT_TYPE,
+  unverifiable:
+    attributes?.metadata !== undefined ||
+    attributes?.cacheControl !== undefined ||
+    attributes?.retention !== undefined ||
+    attributes?.legalHold !== undefined,
+});
+
+const unquoted = (etag: string): string => etag.replace(/^W\//, '').replaceAll('"', '');
+
+const md5Hex = (bytes: Uint8Array): string =>
+  new Bun.CryptoHasher('md5').update(bytes).digest('hex');
+
+/** A single PUT's etag: the body's MD5. A provider encrypting with KMS mints another, so no match. */
+export const putEtagOf = (bytes: Uint8Array): string => md5Hex(bytes);
+
+/**
+ * S3's multipart etag: the MD5 of the parts' binary MD5s, then `-<count>`. Measured equal on the test
+ * stack's gateway. A part etag that is not an MD5 (KMS) makes it unknowable, never a guess.
+ */
+export function multipartEtagOf(partEtags: readonly string[]): string | undefined {
+  const digests: Uint8Array[] = [];
+  for (const etag of partEtags) {
+    const hex = unquoted(etag);
+    if (!/^[0-9a-f]{32}$/i.test(hex)) return undefined;
+    digests.push(Uint8Array.fromHex(hex));
+  }
+  return `${md5Hex(new Uint8Array(Bun.concatArrayBuffers(digests)))}-${partEtags.length}`;
+}
+
+/** `true` when the key holds what was sent, `false` when it holds something else, `undefined` unknown. */
+async function holds(stat: S3Stat, key: string, sent: SentObject): Promise<boolean | undefined> {
+  let found: Awaited<ReturnType<S3Stat>>;
+  try {
+    found = await stat(key);
+  } catch {
+    return undefined;
+  }
+  if (found === undefined) return false;
+  if (sent.etag === undefined || sent.unverifiable) return undefined;
+  return (
+    found.size === sent.size &&
+    unquoted(found.etag) === sent.etag &&
+    found.contentType === sent.contentType
+  );
+}
+
+/**
+ * Whether a failed write is the provider ANSWERING (a refusal, already coded or Bun's `S3Error`) or
+ * the answer lost on the wire, after which the object may be stored.
+ */
+export const isAnswered = (error: unknown): boolean =>
+  isUltimateError(error) || stringField(error, 'name') === 'S3Error';
+
+/**
+ * The `.catch` for a single PUT: a provider answer goes to `refused`, a lost one is settled, so
+ * `put()` resolves when the object landed and is `X_STORAGE_WRITE_OUTCOME_UNKNOWN` when unproven.
+ */
+export const settleLostPut =
+  (
+    stat: S3Stat,
+    input: {
+      readonly driver: string;
+      readonly key: string;
+      readonly bytes: Uint8Array;
+      readonly attributes: SentAttributes | undefined;
+    },
+    refused: (error: unknown) => never,
+  ) =>
+  async (error: unknown): Promise<undefined> => {
+    if (isAnswered(error)) return refused(error);
+    const sent = sentObject(input.bytes.byteLength, putEtagOf(input.bytes), input.attributes);
+    await settlePut(stat, { driver: input.driver, key: input.key, lost: error }, sent);
+    return undefined;
+  };
+
+/** A lost single PUT. It cannot be aborted, so only a match settles it. */
+export async function settlePut(
+  stat: S3Stat,
+  input: { readonly driver: string; readonly key: string; readonly lost: unknown },
+  sent: SentObject,
+): Promise<void> {
+  if ((await holds(stat, input.key, sent)) === true) return;
+  throw writeOutcomeUnknown(input.driver, input.key, input.lost);
+}
+
+/**
+ * A lost Complete. Resolves when the object landed; rethrows `lost` when the abort proves the upload
+ * was still open, so nothing was stored and the caller's refusal is the truth.
+ */
+export async function settleComplete(
+  stat: S3Stat,
+  target: S3UploadTarget & { readonly driver: string },
+  uploadId: string,
+  sent: SentObject,
+  lost: unknown,
+): Promise<void> {
+  if ((await holds(stat, target.key, sent)) === true) return;
+  const refusal = await abortS3Upload(target, uploadId).catch(() => 'unanswered' as const);
+  if (refusal === undefined) throw lost;
+  // NoSuchUpload: nothing is open, so the Complete finished. Whether with these bytes, the key says.
+  if (refusal !== 'unanswered' && refusal.statusCode === 404) {
+    if ((await holds(stat, target.key, sent)) === true) return;
+  }
+  throw writeOutcomeUnknown(target.driver, target.key, lost);
+}