@ultimat3/storage 27.11.0 → 27.13.0

package/CLAUDE.md

@@ -83,7 +83,9 @@ Gotchas:
   in which the sidecar may not describe the bytes: `get`/`stat`/`copy` re-check against the bytes,
   `list` reports no type and `etag: ''`. A fresh key is absent until its bytes land.
   `driver-local-crash.test.ts` dies at every step through `WriteSteps`. Writers and `get()` of one
-  key also queue in-process (`keyedQueue`) — unqueued, two puts interleaved 3/3.
+  key also queue in-process (`keyedQueue`) — unqueued, two puts interleaved 3/3. `copy()` holds BOTH
+  keys' turns (`inTurnOfBoth`, key order): measured in one and read in the other, an overwritten
+  source committed new bytes under the old etag.
 - **A refused write is `X_STORAGE_PUT_FAILED` and a refused read `X_STORAGE_READ_FAILED`**, on
   local and s3 (both were bare throws); a 404 mid-read stays `X_STORAGE_NOT_FOUND`; `assertPutOptions` holds `metadata`/`cacheControl`/`contentType` to their types on
   all three drivers before a byte moves.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/storage",
-  "version": "27.11.0",
+  "version": "27.13.0",
   "description": "Named disks over Bun.file and Bun.s3: safe keys, signed URLs, sniffed uploads",
   "license": "MIT",
   "type": "module",
@@ -32,6 +32,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "27.11.0"
+    "@ultimat3/core": "27.13.0"
   }
 }

package/src/driver-local-write.ts

@@ -164,6 +164,23 @@ export async function commitObject(
 /** Runs `task` after every earlier task queued under the same key has settled. */
 export type KeyedQueue = <T>(key: string, task: () => Promise<T>) => Promise<T>;
 
+/**
+ * `task` holding BOTH keys' turns — what a copy needs: the measured source must be the source it
+ * then reads, and the destination must be its alone. Taken in key order, so two crossing copies
+ * (`a → b`, `b → a`) never each hold the turn the other waits on; one key is taken once, since a
+ * queue's second turn on a key it already holds would wait on itself.
+ */
+export const inTurnOfBoth = <T>(
+  queue: KeyedQueue,
+  one: string,
+  other: string,
+  task: () => Promise<T>,
+): Promise<T> => {
+  if (one === other) return queue(one, task);
+  const [first, second] = one < other ? [one, other] : [other, one];
+  return queue(first, () => queue(second, task));
+};
+
 /**
  * One writer — or one reader — per key at a time, inside this process. An object is two files, so
  * two unserialised `put()`s of one key interleaved their four writes and left one's bytes under the

package/src/driver-local.ts

@@ -35,6 +35,7 @@ import { etagOfFile, headObject, readObjectBytes, readSidecar } from './driver-l
 import { lockOfSidecar, type Sidecar, sidecarLock } from './driver-local-sidecar';
 import {
   commitObject,
+  inTurnOfBoth,
   type KeyedQueue,
   keyedQueue,
   pendingPathOf,
@@ -286,20 +287,22 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
     async copy(from: string, to: string): Promise<StorageObject> {
       const source = assertSafeKey(from);
       const destination = assertSafeKey(to);
-      // Measured, not merely read: the destination gets a sidecar, and one carrying `etag: ''` or
-      // a torn source's borrowed type is a durable lie every later `get()` of the copy would
-      // trust. The hash is streamed, and only for a sidecar-less source or a pair in doubt.
-      const entry = await measured(source);
-      if (entry === undefined) throw objectNotFound(registered, source);
-      const lastModified = clock.now();
-      const sidecar: Sidecar = {
-        contentType: entry.contentType ?? DEFAULT_CONTENT_TYPE,
-        etag: entry.etag,
-        cacheControl: entry.cacheControl,
-        metadata: entry.metadata,
-        lastModified: lastModified.toISOString(),
-      };
-      await oneAtATime(destination, async () => {
+      // Measured AND read in one turn on both keys. Measured in the source's turn and read in the
+      // destination's, a put() of the source in between committed its NEW bytes under the OLD
+      // etag and type — a pair no marker flags, so every later `get()` of the copy trusted it.
+      return inTurnOfBoth(oneAtATime, source, destination, async () => {
+        // Measured, not merely read: a sidecar carrying `etag: ''` or a torn source's borrowed
+        // type is the same durable lie. The hash is streamed, and only for a pair in doubt.
+        const entry = await headObject(root, source, () => etagOfFile(root, source, registered));
+        if (entry === undefined) throw objectNotFound(registered, source);
+        const lastModified = clock.now();
+        const sidecar: Sidecar = {
+          contentType: entry.contentType ?? DEFAULT_CONTENT_TYPE,
+          etag: entry.etag,
+          cacheControl: entry.cacheControl,
+          metadata: entry.metadata,
+          lastModified: lastModified.toISOString(),
+        };
         await refuseOverwrite(destination, 'copy onto');
         await commitObject({
           root,
@@ -307,18 +310,14 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
           disk: registered,
           body: Bun.file(filePath(source)),
           sidecar,
+        }).catch(async (error: unknown) => {
+          // The queue is this process's: another process can still take the source mid-copy.
+          if (!(await Bun.file(filePath(source)).exists()))
+            throw objectNotFound(registered, source);
+          throw error;
         });
-      }).catch(async (error: unknown) => {
-        // The source was deleted while this copy waited its turn on the destination.
-        if (!(await Bun.file(filePath(source)).exists())) throw objectNotFound(registered, source);
-        throw error;
+        return { ...entry, key: destination, contentType: sidecar.contentType, lastModified };
       });
-      return {
-        ...entry,
-        key: destination,
-        contentType: sidecar.contentType,
-        lastModified,
-      };
     },
 
     async delete(key: string): Promise<void> {