payload-reserve 2.3.0 → 3.0.0

package/dist/utilities/resolveReservationItems.js

@@ -1,15 +1,24 @@
 import { ValidationError } from 'payload';
+import { doRangesOverlap } from './slotUtils.js';
 /**
  * Normalize reservation data into a list of resource-level items.
  *
- * - If items[] is populated -> return items (filling defaults from parent).
+ * - If items[] is populated -> return items (filling defaults from parent), then
+ *   append a synthesised item for the top-level resource/startTime/endTime UNLESS
+ *   an items[] entry can already be shown to cover that same window (see B1 in
+ *   the synthesis step below) — this is what makes the top-level `resource`
+ *   conflict-checked even when items[] never names it.
  *   Items missing startTime or resource throw a ValidationError.
  *   Duplicate (resource, startTime) pairs throw a ValidationError.
+ *   An inverted top-level (parent) window throws a ValidationError too — UNLESS
+ *   `options.lenient` is set, in which case parent synthesis is silently
+ *   skipped instead (see the lenient-mode note below).
  * - If items[] is empty/absent -> return single item from top-level fields
  *
  * Every downstream function (conflict check, endTime calc, availability)
  * works with ResolvedItem[], never with raw reservation data.
- */ export function resolveReservationItems(data) {
+ */ export function resolveReservationItems(data, options) {
+    const lenient = options?.lenient ?? false;
     const items = data.items;
     if (items && items.length > 0) {
         const resolved = [];
@@ -58,6 +67,82 @@ import { ValidationError } from 'payload';
                 startTime
             });
         }
+        // The stored row occupies its top-level `resource` for every OTHER booking's
+        // conflict check (buildCoarseOverlapQuery matches top level OR items[]), so
+        // it must occupy it for its own check too. Sharing a resource id with an
+        // items[] entry is NOT sufficient to skip synthesis — an items[] entry for
+        // the same resource at an unrelated time is a genuinely separate occupancy,
+        // and treating "same resource anywhere" as "already covered" reopens the
+        // exact double-booking class this function exists to close (a caller can
+        // list resource A at one time in items[] while the top-level fields book A
+        // at a completely different, uncovered time). Synthesis is skipped only
+        // when an items[] entry for the SAME resource can be shown to cover the
+        // SAME window:
+        //  (a) an exact startTime match — needs no endTime, so it still works when
+        //      this function runs before endTime is computed (validateActive and
+        //      calculateEndTime both call it before calculateEndTime has run); or
+        //  (b) both endTimes are known and the windows overlap — covers
+        //      calculateEndTime's multi-resource branch, which can overwrite the
+        //      top-level startTime/endTime to SPAN every item, so by the time this
+        //      function runs again (e.g. from validateConflicts) the parent's
+        //      window no longer starts at the same instant as any one item even
+        //      though that item's own window is fully contained in it.
+        // When neither can be shown, synthesize: a redundant-but-harmless extra
+        // check is far cheaper than a silently missed one.
+        const parentResource = extractId(data.resource);
+        const parentStart = data.startTime;
+        const parentEnd = data.endTime;
+        // An inverted parent window can never overlap anything, so the coverage test
+        // below would always say "not covered" and synthesise a phantom item that
+        // conflicts with nothing. Reject it at the source instead — it is malformed
+        // input, not a case to paper over.
+        //
+        // Lenient mode (reservationOccupancies only — see AvailabilityService.ts)
+        // resolves ALREADY-STORED documents, which can carry an inverted window
+        // from a context.skipReservationHooks write or data predating this check.
+        // A read must never crash over one malformed row, and — critically — it
+        // must not lose the real items[] occupancies already resolved above by
+        // throwing out of this function entirely. So lenient mode just skips
+        // parent synthesis here instead of throwing: precisely the pre-check
+        // behavior minus the (harmless but pointless) phantom item. The write
+        // path never passes `lenient`, so it keeps the hard rejection.
+        if (parentStart && parentEnd && new Date(parentEnd) <= new Date(parentStart)) {
+            if (lenient) {
+                return resolved;
+            }
+            throw new ValidationError({
+                errors: [
+                    {
+                        message: 'endTime must be after startTime',
+                        path: 'endTime'
+                    }
+                ]
+            });
+        }
+        if (parentResource !== undefined && parentResource !== '' && parentStart) {
+            const parentAlreadyItemized = resolved.some((item)=>{
+                // String-compare ids: a raw id (string for Mongo, number for Postgres)
+                // and a populated relationship's extracted `.id` should match even if
+                // one side came through as a different primitive type than the other.
+                if (String(item.resource) !== String(parentResource)) {
+                    return false;
+                }
+                if (item.startTime === parentStart) {
+                    return true;
+                }
+                return Boolean(parentEnd && item.endTime && doRangesOverlap(new Date(parentStart), new Date(parentEnd), new Date(item.startTime), new Date(item.endTime)));
+            });
+            if (!parentAlreadyItemized) {
+                resolved.push({
+                    endTime: parentEnd,
+                    fromParent: true,
+                    guestCount: data.guestCount ?? 1,
+                    resource: parentResource,
+                    service: extractId(data.service),
+                    startTime: parentStart
+                });
+            }
+        }
         return resolved;
     }
     // Single-resource fallback (current behavior)

package/dist/utilities/resolveReservationItems.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utilities/resolveReservationItems.ts"],"sourcesContent":["import { ValidationError } from 'payload'\n\nexport type ResolvedItem = {\n  endTime: string\n  guestCount: number\n  resource: number | string\n  service?: number | string\n  startTime: string\n}\n\n/**\n * Normalize reservation data into a list of resource-level items.\n *\n * - If items[] is populated -> return items (filling defaults from parent).\n *   Items missing startTime or resource throw a ValidationError.\n *   Duplicate (resource, startTime) pairs throw a ValidationError.\n * - If items[] is empty/absent -> return single item from top-level fields\n *\n * Every downstream function (conflict check, endTime calc, availability)\n * works with ResolvedItem[], never with raw reservation data.\n */\nexport function resolveReservationItems(data: Record<string, unknown>): ResolvedItem[] {\n  const items = data.items as Array<Record<string, unknown>> | undefined\n\n  if (items && items.length > 0) {\n    const resolved: ResolvedItem[] = []\n    const seen = new Set<string>()\n\n    for (let i = 0; i < items.length; i++) {\n      const item = items[i]\n      const resource = extractId(item.resource) ?? extractId(data.resource)\n      const startTime = (item.startTime as string) ?? (data.startTime as string)\n\n      if (resource === undefined || resource === '') {\n        throw new ValidationError({\n          errors: [\n            {\n              message: `Item ${i} is missing a resource`,\n              path: `items.${i}.resource`,\n            },\n          ],\n        })\n      }\n\n      if (!startTime) {\n        throw new ValidationError({\n          errors: [\n            {\n              message: `Item ${i} is missing a startTime`,\n              path: `items.${i}.startTime`,\n            },\n          ],\n        })\n      }\n\n      const key = `${resource}::${startTime}`\n      if (seen.has(key)) {\n        throw new ValidationError({\n          errors: [\n            {\n              message: `Duplicate booking: item ${i} has the same resource and startTime as a previous item`,\n              path: `items.${i}.startTime`,\n            },\n          ],\n        })\n      }\n      seen.add(key)\n\n      resolved.push({\n        endTime: (item.endTime as string) ?? (data.endTime as string),\n        guestCount: (item.guestCount as number) ?? (data.guestCount as number) ?? 1,\n        resource,\n        service: extractId(item.service) ?? extractId(data.service),\n        startTime,\n      })\n    }\n\n    return resolved\n  }\n\n  // Single-resource fallback (current behavior)\n  if (!data.resource || !data.startTime) {\n    return []\n  }\n\n  const resource = extractId(data.resource)\n  if (resource === undefined || resource === '') {\n    return []\n  }\n\n  return [\n    {\n      endTime: data.endTime as string,\n      guestCount: (data.guestCount as number) ?? 1,\n      resource,\n      service: extractId(data.service),\n      startTime: data.startTime as string,\n    },\n  ]\n}\n\n// Exported for unit testing. Returns the underlying id value from a relationship\n// field which Payload represents as either the raw id (string for Mongo, number\n// for Postgres) or a populated document `{ id, ... }`.\n//\n// Note: `0` is a valid numeric Postgres id but rare; we still return it rather\n// than treat it as missing.\nexport function extractId(value: unknown): number | string | undefined {\n  if (typeof value === 'string' && value) {\n    return value\n  }\n  if (typeof value === 'number') {\n    return value\n  }\n  if (value && typeof value === 'object' && 'id' in value) {\n    return (value as { id: number | string }).id\n  }\n  return undefined\n}\n"],"names":["ValidationError","resolveReservationItems","data","items","length","resolved","seen","Set","i","item","resource","extractId","startTime","undefined","errors","message","path","key","has","add","push","endTime","guestCount","service","value","id"],"mappings":"AAAA,SAASA,eAAe,QAAQ,UAAS;AAUzC;;;;;;;;;;CAUC,GACD,OAAO,SAASC,wBAAwBC,IAA6B;IACnE,MAAMC,QAAQD,KAAKC,KAAK;IAExB,IAAIA,SAASA,MAAMC,MAAM,GAAG,GAAG;QAC7B,MAAMC,WAA2B,EAAE;QACnC,MAAMC,OAAO,IAAIC;QAEjB,IAAK,IAAIC,IAAI,GAAGA,IAAIL,MAAMC,MAAM,EAAEI,IAAK;YACrC,MAAMC,OAAON,KAAK,CAACK,EAAE;YACrB,MAAME,WAAWC,UAAUF,KAAKC,QAAQ,KAAKC,UAAUT,KAAKQ,QAAQ;YACpE,MAAME,YAAY,AAACH,KAAKG,SAAS,IAAgBV,KAAKU,SAAS;YAE/D,IAAIF,aAAaG,aAAaH,aAAa,IAAI;gBAC7C,MAAM,IAAIV,gBAAgB;oBACxBc,QAAQ;wBACN;4BACEC,SAAS,CAAC,KAAK,EAAEP,EAAE,sBAAsB,CAAC;4BAC1CQ,MAAM,CAAC,MAAM,EAAER,EAAE,SAAS,CAAC;wBAC7B;qBACD;gBACH;YACF;YAEA,IAAI,CAACI,WAAW;gBACd,MAAM,IAAIZ,gBAAgB;oBACxBc,QAAQ;wBACN;4BACEC,SAAS,CAAC,KAAK,EAAEP,EAAE,uBAAuB,CAAC;4BAC3CQ,MAAM,CAAC,MAAM,EAAER,EAAE,UAAU,CAAC;wBAC9B;qBACD;gBACH;YACF;YAEA,MAAMS,MAAM,GAAGP,SAAS,EAAE,EAAEE,WAAW;YACvC,IAAIN,KAAKY,GAAG,CAACD,MAAM;gBACjB,MAAM,IAAIjB,gBAAgB;oBACxBc,QAAQ;wBACN;4BACEC,SAAS,CAAC,wBAAwB,EAAEP,EAAE,uDAAuD,CAAC;4BAC9FQ,MAAM,CAAC,MAAM,EAAER,EAAE,UAAU,CAAC;wBAC9B;qBACD;gBACH;YACF;YACAF,KAAKa,GAAG,CAACF;YAETZ,SAASe,IAAI,CAAC;gBACZC,SAAS,AAACZ,KAAKY,OAAO,IAAgBnB,KAAKmB,OAAO;gBAClDC,YAAY,AAACb,KAAKa,UAAU,IAAgBpB,KAAKoB,UAAU,IAAe;gBAC1EZ;gBACAa,SAASZ,UAAUF,KAAKc,OAAO,KAAKZ,UAAUT,KAAKqB,OAAO;gBAC1DX;YACF;QACF;QAEA,OAAOP;IACT;IAEA,8CAA8C;IAC9C,IAAI,CAACH,KAAKQ,QAAQ,IAAI,CAACR,KAAKU,SAAS,EAAE;QACrC,OAAO,EAAE;IACX;IAEA,MAAMF,WAAWC,UAAUT,KAAKQ,QAAQ;IACxC,IAAIA,aAAaG,aAAaH,aAAa,IAAI;QAC7C,OAAO,EAAE;IACX;IAEA,OAAO;QACL;YACEW,SAASnB,KAAKmB,OAAO;YACrBC,YAAY,AAACpB,KAAKoB,UAAU,IAAe;YAC3CZ;YACAa,SAASZ,UAAUT,KAAKqB,OAAO;YAC/BX,WAAWV,KAAKU,SAAS;QAC3B;KACD;AACH;AAEA,iFAAiF;AACjF,gFAAgF;AAChF,uDAAuD;AACvD,EAAE;AACF,+EAA+E;AAC/E,4BAA4B;AAC5B,OAAO,SAASD,UAAUa,KAAc;IACtC,IAAI,OAAOA,UAAU,YAAYA,OAAO;QACtC,OAAOA;IACT;IACA,IAAI,OAAOA,UAAU,UAAU;QAC7B,OAAOA;IACT;IACA,IAAIA,SAAS,OAAOA,UAAU,YAAY,QAAQA,OAAO;QACvD,OAAO,AAACA,MAAkCC,EAAE;IAC9C;IACA,OAAOZ;AACT"}
+{"version":3,"sources":["../../src/utilities/resolveReservationItems.ts"],"sourcesContent":["import { ValidationError } from 'payload'\n\nimport { doRangesOverlap } from './slotUtils.js'\n\nexport type ResolvedItem = {\n  endTime: string\n  /** True when this item was synthesised from the top-level resource/startTime. */\n  fromParent?: boolean\n  guestCount: number\n  resource: number | string\n  service?: number | string\n  startTime: string\n}\n\n/**\n * Normalize reservation data into a list of resource-level items.\n *\n * - If items[] is populated -> return items (filling defaults from parent), then\n *   append a synthesised item for the top-level resource/startTime/endTime UNLESS\n *   an items[] entry can already be shown to cover that same window (see B1 in\n *   the synthesis step below) — this is what makes the top-level `resource`\n *   conflict-checked even when items[] never names it.\n *   Items missing startTime or resource throw a ValidationError.\n *   Duplicate (resource, startTime) pairs throw a ValidationError.\n *   An inverted top-level (parent) window throws a ValidationError too — UNLESS\n *   `options.lenient` is set, in which case parent synthesis is silently\n *   skipped instead (see the lenient-mode note below).\n * - If items[] is empty/absent -> return single item from top-level fields\n *\n * Every downstream function (conflict check, endTime calc, availability)\n * works with ResolvedItem[], never with raw reservation data.\n */\nexport function resolveReservationItems(\n  data: Record<string, unknown>,\n  options?: { lenient?: boolean },\n): ResolvedItem[] {\n  const lenient = options?.lenient ?? false\n  const items = data.items as Array<Record<string, unknown>> | undefined\n\n  if (items && items.length > 0) {\n    const resolved: ResolvedItem[] = []\n    const seen = new Set<string>()\n\n    for (let i = 0; i < items.length; i++) {\n      const item = items[i]\n      const resource = extractId(item.resource) ?? extractId(data.resource)\n      const startTime = (item.startTime as string) ?? (data.startTime as string)\n\n      if (resource === undefined || resource === '') {\n        throw new ValidationError({\n          errors: [\n            {\n              message: `Item ${i} is missing a resource`,\n              path: `items.${i}.resource`,\n            },\n          ],\n        })\n      }\n\n      if (!startTime) {\n        throw new ValidationError({\n          errors: [\n            {\n              message: `Item ${i} is missing a startTime`,\n              path: `items.${i}.startTime`,\n            },\n          ],\n        })\n      }\n\n      const key = `${resource}::${startTime}`\n      if (seen.has(key)) {\n        throw new ValidationError({\n          errors: [\n            {\n              message: `Duplicate booking: item ${i} has the same resource and startTime as a previous item`,\n              path: `items.${i}.startTime`,\n            },\n          ],\n        })\n      }\n      seen.add(key)\n\n      resolved.push({\n        endTime: (item.endTime as string) ?? (data.endTime as string),\n        guestCount: (item.guestCount as number) ?? (data.guestCount as number) ?? 1,\n        resource,\n        service: extractId(item.service) ?? extractId(data.service),\n        startTime,\n      })\n    }\n\n    // The stored row occupies its top-level `resource` for every OTHER booking's\n    // conflict check (buildCoarseOverlapQuery matches top level OR items[]), so\n    // it must occupy it for its own check too. Sharing a resource id with an\n    // items[] entry is NOT sufficient to skip synthesis — an items[] entry for\n    // the same resource at an unrelated time is a genuinely separate occupancy,\n    // and treating \"same resource anywhere\" as \"already covered\" reopens the\n    // exact double-booking class this function exists to close (a caller can\n    // list resource A at one time in items[] while the top-level fields book A\n    // at a completely different, uncovered time). Synthesis is skipped only\n    // when an items[] entry for the SAME resource can be shown to cover the\n    // SAME window:\n    //  (a) an exact startTime match — needs no endTime, so it still works when\n    //      this function runs before endTime is computed (validateActive and\n    //      calculateEndTime both call it before calculateEndTime has run); or\n    //  (b) both endTimes are known and the windows overlap — covers\n    //      calculateEndTime's multi-resource branch, which can overwrite the\n    //      top-level startTime/endTime to SPAN every item, so by the time this\n    //      function runs again (e.g. from validateConflicts) the parent's\n    //      window no longer starts at the same instant as any one item even\n    //      though that item's own window is fully contained in it.\n    // When neither can be shown, synthesize: a redundant-but-harmless extra\n    // check is far cheaper than a silently missed one.\n    const parentResource = extractId(data.resource)\n    const parentStart = data.startTime as string\n    const parentEnd = data.endTime as string | undefined\n\n    // An inverted parent window can never overlap anything, so the coverage test\n    // below would always say \"not covered\" and synthesise a phantom item that\n    // conflicts with nothing. Reject it at the source instead — it is malformed\n    // input, not a case to paper over.\n    //\n    // Lenient mode (reservationOccupancies only — see AvailabilityService.ts)\n    // resolves ALREADY-STORED documents, which can carry an inverted window\n    // from a context.skipReservationHooks write or data predating this check.\n    // A read must never crash over one malformed row, and — critically — it\n    // must not lose the real items[] occupancies already resolved above by\n    // throwing out of this function entirely. So lenient mode just skips\n    // parent synthesis here instead of throwing: precisely the pre-check\n    // behavior minus the (harmless but pointless) phantom item. The write\n    // path never passes `lenient`, so it keeps the hard rejection.\n    if (parentStart && parentEnd && new Date(parentEnd) <= new Date(parentStart)) {\n      if (lenient) {\n        return resolved\n      }\n      throw new ValidationError({\n        errors: [{ message: 'endTime must be after startTime', path: 'endTime' }],\n      })\n    }\n\n    if (parentResource !== undefined && parentResource !== '' && parentStart) {\n      const parentAlreadyItemized = resolved.some((item) => {\n        // String-compare ids: a raw id (string for Mongo, number for Postgres)\n        // and a populated relationship's extracted `.id` should match even if\n        // one side came through as a different primitive type than the other.\n        if (String(item.resource) !== String(parentResource)) {\n          return false\n        }\n        if (item.startTime === parentStart) {\n          return true\n        }\n        return Boolean(\n          parentEnd &&\n            item.endTime &&\n            doRangesOverlap(\n              new Date(parentStart),\n              new Date(parentEnd),\n              new Date(item.startTime),\n              new Date(item.endTime),\n            ),\n        )\n      })\n\n      if (!parentAlreadyItemized) {\n        resolved.push({\n          endTime: parentEnd as string,\n          fromParent: true,\n          guestCount: (data.guestCount as number) ?? 1,\n          resource: parentResource,\n          service: extractId(data.service),\n          startTime: parentStart,\n        })\n      }\n    }\n\n    return resolved\n  }\n\n  // Single-resource fallback (current behavior)\n  if (!data.resource || !data.startTime) {\n    return []\n  }\n\n  const resource = extractId(data.resource)\n  if (resource === undefined || resource === '') {\n    return []\n  }\n\n  return [\n    {\n      endTime: data.endTime as string,\n      guestCount: (data.guestCount as number) ?? 1,\n      resource,\n      service: extractId(data.service),\n      startTime: data.startTime as string,\n    },\n  ]\n}\n\n// Exported for unit testing. Returns the underlying id value from a relationship\n// field which Payload represents as either the raw id (string for Mongo, number\n// for Postgres) or a populated document `{ id, ... }`.\n//\n// Note: `0` is a valid numeric Postgres id but rare; we still return it rather\n// than treat it as missing.\nexport function extractId(value: unknown): number | string | undefined {\n  if (typeof value === 'string' && value) {\n    return value\n  }\n  if (typeof value === 'number') {\n    return value\n  }\n  if (value && typeof value === 'object' && 'id' in value) {\n    return (value as { id: number | string }).id\n  }\n  return undefined\n}\n"],"names":["ValidationError","doRangesOverlap","resolveReservationItems","data","options","lenient","items","length","resolved","seen","Set","i","item","resource","extractId","startTime","undefined","errors","message","path","key","has","add","push","endTime","guestCount","service","parentResource","parentStart","parentEnd","Date","parentAlreadyItemized","some","String","Boolean","fromParent","value","id"],"mappings":"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"}

package/dist/utilities/retryOnWriteConflict.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Retry a write that lost a transaction-level lock race.
+ *
+ * `acquireBookingLock` makes concurrent bookings for one resource contend on a
+ * single document so the database serializes them. On MongoDB the loser does
+ * not wait — it aborts immediately with a WriteConflict. That is correct for a
+ * `quantity: 1` resource (only one booking should win anyway) but wrong for a
+ * `quantity: 3` one, where two more bookings legitimately fit. Measured
+ * without retry: 8 simultaneous bookings against a `quantity: 3` resource
+ * persisted only 1.
+ *
+ * Retrying re-runs the whole operation on a fresh transaction. The retry takes
+ * the lock cleanly, re-reads availability — now seeing the winner's committed
+ * booking — and is admitted or rejected by `validateConflicts` on the merits.
+ */
+/**
+ * Whether an error means "the database refused this transaction because
+ * another one touched the same rows; running it again may succeed."
+ *
+ * Detection is by the driver's own structured signals, never by message text.
+ * MongoDB tags exactly this class with the `TransientTransactionError` label,
+ * which is the retry contract its drivers document; Postgres uses SQLSTATE;
+ * SQLite/libsql use a `code` string in the `SQLITE_BUSY`/`SQLITE_LOCKED*`
+ * family.
+ */
+export declare function isTransientWriteConflict(error: unknown): boolean;
+/**
+ * Run `operation`, retrying only transient write conflicts.
+ *
+ * Every other error — a genuine booking conflict, a validation failure, an
+ * access denial — propagates on the first attempt. Retrying those would turn a
+ * clean rejection into a slow one.
+ *
+ * Backoff is exponential with full jitter, so a burst of losers does not
+ * synchronise into a second stampede on the same document.
+ *
+ * Pass `req` whenever the operation writes through the Payload Local API. Every
+ * attempt re-invokes a closure over the SAME `req`, and Payload's
+ * `initTransaction` JOINS an existing `req.transactionID` rather than opening a
+ * fresh transaction — so a transaction id left behind by a failed attempt would
+ * make the next attempt re-enter a transaction the database already discarded.
+ * Payload's own operations normally clean up after themselves (`killTransaction`
+ * deletes the id from their catch), with one gap they cannot close: when
+ * `beginTransaction` ITSELF rejects, `initTransaction` has already stored the
+ * rejected promise on the req and `killTransaction`'s guard skips promises, so
+ * the req stays poisoned — every later `initTransaction` short-circuits on
+ * `instanceof Promise` and re-throws the first error without touching the
+ * database. Clearing a leftover here closes it. See dev/retryTransaction.spec.ts.
+ *
+ * Do NOT attribute SQLite's "raising the retry budget changes nothing"
+ * measurement to this. That has a different, independent cause: `@payloadcms/
+ * drizzle` rethrows the driver's error as a bare `Error`, so
+ * `isTransientWriteConflict` returns FALSE and this loop throws on attempt 1 —
+ * attempts 2..N never happen, and poisoning never gets a chance to matter. See
+ * README's "Concurrent booking: database adapter support". The shape this
+ * clearing actually protects is any caller that swallows a
+ * begin-transaction failure and then keeps using the same req (see the expiry
+ * sweep in HoldService.takeHold).
+ */
+export declare function retryOnWriteConflict<T>(operation: () => Promise<T>, { attempts, baseDelayMs, req, }?: {
+    attempts?: number;
+    baseDelayMs?: number;
+    req?: {
+        transactionID?: unknown;
+    };
+}): Promise<T>;

package/dist/utilities/retryOnWriteConflict.js

@@ -0,0 +1,135 @@
+/**
+ * Retry a write that lost a transaction-level lock race.
+ *
+ * `acquireBookingLock` makes concurrent bookings for one resource contend on a
+ * single document so the database serializes them. On MongoDB the loser does
+ * not wait — it aborts immediately with a WriteConflict. That is correct for a
+ * `quantity: 1` resource (only one booking should win anyway) but wrong for a
+ * `quantity: 3` one, where two more bookings legitimately fit. Measured
+ * without retry: 8 simultaneous bookings against a `quantity: 3` resource
+ * persisted only 1.
+ *
+ * Retrying re-runs the whole operation on a fresh transaction. The retry takes
+ * the lock cleanly, re-reads availability — now seeing the winner's committed
+ * booking — and is admitted or rejected by `validateConflicts` on the merits.
+ */ /** MongoDB WriteConflict. */ const MONGO_WRITE_CONFLICT = 112;
+/** Postgres serialization_failure and deadlock_detected. */ const POSTGRES_SERIALIZATION_FAILURES = new Set([
+    '40P01',
+    '40001'
+]);
+/**
+ * SQLite/libsql busy-or-locked family. Only reachable when the adapter is
+ * given a truthy `transactionOptions` — otherwise `beginTransaction` is a
+ * no-op and nothing ever contends. `SQLITE_BUSY` and plain `SQLITE_LOCKED`
+ * are the same family as the qualified variant measured below; prefix match
+ * (not an exact-set lookup like the Postgres codes above) because
+ * SQLite/libsql qualify the base code with a reason suffix (`_SHAREDCACHE`,
+ * `_SNAPSHOT`, ...) — the prefix is still the driver's own structured
+ * signal, never message text.
+ *
+ * KNOWN GAP, confirmed by direct inspection, not assumption: for a loser
+ * that aborts at `beginTransaction` itself (SQLite's actual failure mode —
+ * a second write transaction cannot even open while one is held, rather
+ * than queuing for it), this check can never fire in practice. The real
+ * driver error — a `LibsqlError` with `code: 'SQLITE_LOCKED_SHAREDCACHE'` —
+ * is caught *inside* `@payloadcms/drizzle`'s own `beginTransaction.js` (a
+ * Payload-core dependency, not this plugin) and re-thrown as a bare
+ * `new Error('Error: cannot begin transaction: ...')`: no `code`, no
+ * `cause`, generic `name`. By the time it reaches this function the
+ * structured signal is already gone, so retry never engages for that path
+ * — measured: burst of 8 against a `quantity: 3` resource with retry
+ * recovers only 1 of 3, identical to no retry at all, and raising the
+ * retry budget from 5 to 30 attempts makes no difference. This match is
+ * kept because it is still correct for any SQLite/libsql error shape that
+ * *does* preserve `code` (a mid-transaction conflict would be a different
+ * code path), and matching on the wrapped error's message text to plug this
+ * specific gap is exactly what this project's structured-signal-only
+ * constraint forbids.
+ */ const SQLITE_BUSY_OR_LOCKED_PREFIXES = [
+    'SQLITE_BUSY',
+    'SQLITE_LOCKED'
+];
+/**
+ * Whether an error means "the database refused this transaction because
+ * another one touched the same rows; running it again may succeed."
+ *
+ * Detection is by the driver's own structured signals, never by message text.
+ * MongoDB tags exactly this class with the `TransientTransactionError` label,
+ * which is the retry contract its drivers document; Postgres uses SQLSTATE;
+ * SQLite/libsql use a `code` string in the `SQLITE_BUSY`/`SQLITE_LOCKED*`
+ * family.
+ */ export function isTransientWriteConflict(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const { code, errorLabels } = error;
+    if (Array.isArray(errorLabels) && errorLabels.includes('TransientTransactionError')) {
+        return true;
+    }
+    if (code === MONGO_WRITE_CONFLICT) {
+        return true;
+    }
+    if (typeof code !== 'string') {
+        return false;
+    }
+    return POSTGRES_SERIALIZATION_FAILURES.has(code) || SQLITE_BUSY_OR_LOCKED_PREFIXES.some((prefix)=>code.startsWith(prefix));
+}
+/**
+ * Run `operation`, retrying only transient write conflicts.
+ *
+ * Every other error — a genuine booking conflict, a validation failure, an
+ * access denial — propagates on the first attempt. Retrying those would turn a
+ * clean rejection into a slow one.
+ *
+ * Backoff is exponential with full jitter, so a burst of losers does not
+ * synchronise into a second stampede on the same document.
+ *
+ * Pass `req` whenever the operation writes through the Payload Local API. Every
+ * attempt re-invokes a closure over the SAME `req`, and Payload's
+ * `initTransaction` JOINS an existing `req.transactionID` rather than opening a
+ * fresh transaction — so a transaction id left behind by a failed attempt would
+ * make the next attempt re-enter a transaction the database already discarded.
+ * Payload's own operations normally clean up after themselves (`killTransaction`
+ * deletes the id from their catch), with one gap they cannot close: when
+ * `beginTransaction` ITSELF rejects, `initTransaction` has already stored the
+ * rejected promise on the req and `killTransaction`'s guard skips promises, so
+ * the req stays poisoned — every later `initTransaction` short-circuits on
+ * `instanceof Promise` and re-throws the first error without touching the
+ * database. Clearing a leftover here closes it. See dev/retryTransaction.spec.ts.
+ *
+ * Do NOT attribute SQLite's "raising the retry budget changes nothing"
+ * measurement to this. That has a different, independent cause: `@payloadcms/
+ * drizzle` rethrows the driver's error as a bare `Error`, so
+ * `isTransientWriteConflict` returns FALSE and this loop throws on attempt 1 —
+ * attempts 2..N never happen, and poisoning never gets a chance to matter. See
+ * README's "Concurrent booking: database adapter support". The shape this
+ * clearing actually protects is any caller that swallows a
+ * begin-transaction failure and then keeps using the same req (see the expiry
+ * sweep in HoldService.takeHold).
+ */ export async function retryOnWriteConflict(operation, { attempts = 5, baseDelayMs = 10, req } = {}) {
+    let lastError;
+    // Only leftovers from a failed attempt are ours to clear. A req that arrives
+    // already inside a transaction belongs to an enclosing caller: dropping that
+    // id would silently detach the retried write from their unit of work.
+    const callerOwnsTransaction = req ? req.transactionID !== undefined : false;
+    for(let attempt = 0; attempt < attempts; attempt++){
+        if (attempt > 0 && req && !callerOwnsTransaction && req.transactionID !== undefined) {
+            delete req.transactionID;
+        }
+        try {
+            return await operation();
+        } catch (error) {
+            if (!isTransientWriteConflict(error)) {
+                throw error;
+            }
+            lastError = error;
+            if (attempt < attempts - 1) {
+                const ceiling = baseDelayMs * 2 ** attempt;
+                await new Promise((resolve)=>setTimeout(resolve, Math.random() * ceiling));
+            }
+        }
+    }
+    throw lastError;
+}
+
+//# sourceMappingURL=retryOnWriteConflict.js.map

package/dist/utilities/retryOnWriteConflict.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utilities/retryOnWriteConflict.ts"],"sourcesContent":["/**\n * Retry a write that lost a transaction-level lock race.\n *\n * `acquireBookingLock` makes concurrent bookings for one resource contend on a\n * single document so the database serializes them. On MongoDB the loser does\n * not wait — it aborts immediately with a WriteConflict. That is correct for a\n * `quantity: 1` resource (only one booking should win anyway) but wrong for a\n * `quantity: 3` one, where two more bookings legitimately fit. Measured\n * without retry: 8 simultaneous bookings against a `quantity: 3` resource\n * persisted only 1.\n *\n * Retrying re-runs the whole operation on a fresh transaction. The retry takes\n * the lock cleanly, re-reads availability — now seeing the winner's committed\n * booking — and is admitted or rejected by `validateConflicts` on the merits.\n */\n\n/** MongoDB WriteConflict. */\nconst MONGO_WRITE_CONFLICT = 112\n\n/** Postgres serialization_failure and deadlock_detected. */\nconst POSTGRES_SERIALIZATION_FAILURES = new Set(['40P01', '40001'])\n\n/**\n * SQLite/libsql busy-or-locked family. Only reachable when the adapter is\n * given a truthy `transactionOptions` — otherwise `beginTransaction` is a\n * no-op and nothing ever contends. `SQLITE_BUSY` and plain `SQLITE_LOCKED`\n * are the same family as the qualified variant measured below; prefix match\n * (not an exact-set lookup like the Postgres codes above) because\n * SQLite/libsql qualify the base code with a reason suffix (`_SHAREDCACHE`,\n * `_SNAPSHOT`, ...) — the prefix is still the driver's own structured\n * signal, never message text.\n *\n * KNOWN GAP, confirmed by direct inspection, not assumption: for a loser\n * that aborts at `beginTransaction` itself (SQLite's actual failure mode —\n * a second write transaction cannot even open while one is held, rather\n * than queuing for it), this check can never fire in practice. The real\n * driver error — a `LibsqlError` with `code: 'SQLITE_LOCKED_SHAREDCACHE'` —\n * is caught *inside* `@payloadcms/drizzle`'s own `beginTransaction.js` (a\n * Payload-core dependency, not this plugin) and re-thrown as a bare\n * `new Error('Error: cannot begin transaction: ...')`: no `code`, no\n * `cause`, generic `name`. By the time it reaches this function the\n * structured signal is already gone, so retry never engages for that path\n * — measured: burst of 8 against a `quantity: 3` resource with retry\n * recovers only 1 of 3, identical to no retry at all, and raising the\n * retry budget from 5 to 30 attempts makes no difference. This match is\n * kept because it is still correct for any SQLite/libsql error shape that\n * *does* preserve `code` (a mid-transaction conflict would be a different\n * code path), and matching on the wrapped error's message text to plug this\n * specific gap is exactly what this project's structured-signal-only\n * constraint forbids.\n */\nconst SQLITE_BUSY_OR_LOCKED_PREFIXES = ['SQLITE_BUSY', 'SQLITE_LOCKED']\n\n/**\n * Whether an error means \"the database refused this transaction because\n * another one touched the same rows; running it again may succeed.\"\n *\n * Detection is by the driver's own structured signals, never by message text.\n * MongoDB tags exactly this class with the `TransientTransactionError` label,\n * which is the retry contract its drivers document; Postgres uses SQLSTATE;\n * SQLite/libsql use a `code` string in the `SQLITE_BUSY`/`SQLITE_LOCKED*`\n * family.\n */\nexport function isTransientWriteConflict(error: unknown): boolean {\n  if (!error || typeof error !== 'object') {\n    return false\n  }\n\n  const { code, errorLabels } = error as { code?: unknown; errorLabels?: unknown }\n\n  if (Array.isArray(errorLabels) && errorLabels.includes('TransientTransactionError')) {\n    return true\n  }\n\n  if (code === MONGO_WRITE_CONFLICT) {\n    return true\n  }\n\n  if (typeof code !== 'string') {\n    return false\n  }\n\n  return (\n    POSTGRES_SERIALIZATION_FAILURES.has(code) ||\n    SQLITE_BUSY_OR_LOCKED_PREFIXES.some((prefix) => code.startsWith(prefix))\n  )\n}\n\n/**\n * Run `operation`, retrying only transient write conflicts.\n *\n * Every other error — a genuine booking conflict, a validation failure, an\n * access denial — propagates on the first attempt. Retrying those would turn a\n * clean rejection into a slow one.\n *\n * Backoff is exponential with full jitter, so a burst of losers does not\n * synchronise into a second stampede on the same document.\n *\n * Pass `req` whenever the operation writes through the Payload Local API. Every\n * attempt re-invokes a closure over the SAME `req`, and Payload's\n * `initTransaction` JOINS an existing `req.transactionID` rather than opening a\n * fresh transaction — so a transaction id left behind by a failed attempt would\n * make the next attempt re-enter a transaction the database already discarded.\n * Payload's own operations normally clean up after themselves (`killTransaction`\n * deletes the id from their catch), with one gap they cannot close: when\n * `beginTransaction` ITSELF rejects, `initTransaction` has already stored the\n * rejected promise on the req and `killTransaction`'s guard skips promises, so\n * the req stays poisoned — every later `initTransaction` short-circuits on\n * `instanceof Promise` and re-throws the first error without touching the\n * database. Clearing a leftover here closes it. See dev/retryTransaction.spec.ts.\n *\n * Do NOT attribute SQLite's \"raising the retry budget changes nothing\"\n * measurement to this. That has a different, independent cause: `@payloadcms/\n * drizzle` rethrows the driver's error as a bare `Error`, so\n * `isTransientWriteConflict` returns FALSE and this loop throws on attempt 1 —\n * attempts 2..N never happen, and poisoning never gets a chance to matter. See\n * README's \"Concurrent booking: database adapter support\". The shape this\n * clearing actually protects is any caller that swallows a\n * begin-transaction failure and then keeps using the same req (see the expiry\n * sweep in HoldService.takeHold).\n */\nexport async function retryOnWriteConflict<T>(\n  operation: () => Promise<T>,\n  {\n    attempts = 5,\n    baseDelayMs = 10,\n    req,\n  }: { attempts?: number; baseDelayMs?: number; req?: { transactionID?: unknown } } = {},\n): Promise<T> {\n  let lastError: unknown\n\n  // Only leftovers from a failed attempt are ours to clear. A req that arrives\n  // already inside a transaction belongs to an enclosing caller: dropping that\n  // id would silently detach the retried write from their unit of work.\n  const callerOwnsTransaction = req ? req.transactionID !== undefined : false\n\n  for (let attempt = 0; attempt < attempts; attempt++) {\n    if (attempt > 0 && req && !callerOwnsTransaction && req.transactionID !== undefined) {\n      delete req.transactionID\n    }\n\n    try {\n      return await operation()\n    } catch (error) {\n      if (!isTransientWriteConflict(error)) {\n        throw error\n      }\n\n      lastError = error\n\n      if (attempt < attempts - 1) {\n        const ceiling = baseDelayMs * 2 ** attempt\n        await new Promise((resolve) => setTimeout(resolve, Math.random() * ceiling))\n      }\n    }\n  }\n\n  throw lastError\n}\n"],"names":["MONGO_WRITE_CONFLICT","POSTGRES_SERIALIZATION_FAILURES","Set","SQLITE_BUSY_OR_LOCKED_PREFIXES","isTransientWriteConflict","error","code","errorLabels","Array","isArray","includes","has","some","prefix","startsWith","retryOnWriteConflict","operation","attempts","baseDelayMs","req","lastError","callerOwnsTransaction","transactionID","undefined","attempt","ceiling","Promise","resolve","setTimeout","Math","random"],"mappings":"AAAA;;;;;;;;;;;;;;CAcC,GAED,2BAA2B,GAC3B,MAAMA,uBAAuB;AAE7B,0DAA0D,GAC1D,MAAMC,kCAAkC,IAAIC,IAAI;IAAC;IAAS;CAAQ;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BC,GACD,MAAMC,iCAAiC;IAAC;IAAe;CAAgB;AAEvE;;;;;;;;;CASC,GACD,OAAO,SAASC,yBAAyBC,KAAc;IACrD,IAAI,CAACA,SAAS,OAAOA,UAAU,UAAU;QACvC,OAAO;IACT;IAEA,MAAM,EAAEC,IAAI,EAAEC,WAAW,EAAE,GAAGF;IAE9B,IAAIG,MAAMC,OAAO,CAACF,gBAAgBA,YAAYG,QAAQ,CAAC,8BAA8B;QACnF,OAAO;IACT;IAEA,IAAIJ,SAASN,sBAAsB;QACjC,OAAO;IACT;IAEA,IAAI,OAAOM,SAAS,UAAU;QAC5B,OAAO;IACT;IAEA,OACEL,gCAAgCU,GAAG,CAACL,SACpCH,+BAA+BS,IAAI,CAAC,CAACC,SAAWP,KAAKQ,UAAU,CAACD;AAEpE;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCC,GACD,OAAO,eAAeE,qBACpBC,SAA2B,EAC3B,EACEC,WAAW,CAAC,EACZC,cAAc,EAAE,EAChBC,GAAG,EAC4E,GAAG,CAAC,CAAC;IAEtF,IAAIC;IAEJ,6EAA6E;IAC7E,6EAA6E;IAC7E,sEAAsE;IACtE,MAAMC,wBAAwBF,MAAMA,IAAIG,aAAa,KAAKC,YAAY;IAEtE,IAAK,IAAIC,UAAU,GAAGA,UAAUP,UAAUO,UAAW;QACnD,IAAIA,UAAU,KAAKL,OAAO,CAACE,yBAAyBF,IAAIG,aAAa,KAAKC,WAAW;YACnF,OAAOJ,IAAIG,aAAa;QAC1B;QAEA,IAAI;YACF,OAAO,MAAMN;QACf,EAAE,OAAOX,OAAO;YACd,IAAI,CAACD,yBAAyBC,QAAQ;gBACpC,MAAMA;YACR;YAEAe,YAAYf;YAEZ,IAAImB,UAAUP,WAAW,GAAG;gBAC1B,MAAMQ,UAAUP,cAAc,KAAKM;gBACnC,MAAM,IAAIE,QAAQ,CAACC,UAAYC,WAAWD,SAASE,KAAKC,MAAM,KAAKL;YACrE;QACF;IACF;IAEA,MAAML;AACR"}

package/dist/utilities/tenantTimezone.d.ts

@@ -1,4 +1,5 @@
-import type { Payload } from 'payload';
+import type { Payload, PayloadRequest } from 'payload';
+import type { ResolvedReservationPluginConfig } from '../types.js';
 type CollectionLike = {
     fields?: unknown[];
 } | null | undefined;
@@ -33,9 +34,84 @@ export declare function tenantCollectionSlug(collection: CollectionLike, tenantF
 export declare function getEffectiveTenantTimezone(args: {
     globalTimezone: string;
     payload: Payload;
+    req?: PayloadRequest;
     scopedCollection: CollectionLike;
     tenantField: string;
     tenantId: null | string;
     timezoneField: string;
 }): Promise<string>;
+/**
+ * Normalizes a relationship-shaped value down to its id: a raw string/number
+ * id, or an object carrying one — `{ id }`, the shape both a populated
+ * relationship and a client sending `{ "tenant": { "id": "..." } }` produce.
+ * Returns null for anything else (including an object with no usable `id`),
+ * so callers can fail closed on a shape they don't recognize instead of
+ * silently skipping whatever check they were about to run.
+ */
+export declare function normalizeRelationshipId(value: unknown): null | number | string;
+/**
+ * Every tenant id a tenant-field value names, as a list.
+ *
+ * Exists because multi-tenant supports a `hasMany` tenant field, so the value
+ * can legitimately be an ARRAY of relationship-shaped entries.
+ * {@link normalizeRelationshipId} returns null for an array, and the caller
+ * fails closed on null — which turned a supported multi-tenant configuration
+ * into a blanket 403 on every authenticated booking that carried an explicit
+ * tenant (a total booking outage for that install, with no diagnostic).
+ *
+ * - `[]` -> `[]`: an empty array writes no tenant, so there is nothing to
+ *   authorize; the caller permits it, exactly as it does for an absent value.
+ * - a one-or-many array -> one id per entry, all of which the caller must be
+ *   authorized for (any single unrecognized entry poisons the whole value).
+ * - a scalar / `{ id }` -> a single-element list.
+ * - anything else -> null, so the caller can still fail closed, loudly.
+ */
+export declare function normalizeRelationshipIds(value: unknown): Array<number | string> | null;
+/**
+ * Whether an authenticated caller may write the tenant value present in
+ * `data[config.multiTenant.tenantField]` onto a new document in
+ * `config.slugs.reservations`.
+ *
+ * Exists because delegating `overrideAccess` is NOT sufficient on its own:
+ * multi-tenant's tenant-field `validate` only checks presence, and Payload's
+ * `create` operation (`executeAccess`) only checks the TRUTHINESS of a
+ * collection access result — unlike read/update/delete, which apply a
+ * returned `Where` via `combineQueries` against a real document. So MT's own
+ * tenant-scoped `create` access can't reject an explicit foreign tenant
+ * either; an authenticated caller can write one straight through regardless
+ * of `overrideAccess`. This closes that gap the same way
+ * {@link getEffectiveTenantTimezone} closes it for a client-supplied tenant
+ * *cookie*: an access-checked (`overrideAccess: false`) probe read against
+ * the tenants collection for the *submitted* tenant id — a lookup that finds
+ * nothing means the caller isn't a member (or a multi-tenant super-admin).
+ *
+ * PRECONDITION — this is a real membership check only when the caller
+ * authenticates against the SAME collection multi-tenant wraps as its
+ * admin/tenant-owning collection. `withTenantAccess` only applies its
+ * membership constraint when `req.user.collection === adminUsersSlug`;
+ * otherwise it falls back to the tenants collection's own (here: default,
+ * unrestricted) access function, which only requires `Boolean(req.user)`. In
+ * this plugin's STANDALONE mode (`userCollection` unset), a customer
+ * authenticates against `slugs.customers` — a collection multi-tenant never
+ * wraps — so this probe passes for ANY tenant id for a logged-in customer.
+ * `src/plugin.ts`'s boot diagnostic warns about that configuration. It is
+ * also a no-op if the host set multi-tenant's own
+ * `useTenantsCollectionAccess: false`, which is not detectable from here.
+ *
+ * Returns true — nothing to check — when the reservations collection isn't
+ * tenant-scoped at all, or `data` doesn't carry an explicit tenant value (MT's
+ * own access-checked `defaultValue` applies in that case; see
+ * `getEffectiveTenantTimezone`'s doc comment for why that path is already
+ * safe). Returns false — fail closed — for an unrecognized value shape (logged,
+ * since a shape this plugin cannot read refuses every such booking), a probe
+ * that finds no matching tenant, or any error while probing.
+ *
+ * A `hasMany` tenant field is supported: the value may be an array, and EVERY
+ * id in it is probed.
+ */
+export declare function callerMayUseTenant(args: {
+    config: Pick<ResolvedReservationPluginConfig, 'multiTenant' | 'slugs'>;
+    data: Record<string, unknown>;
+    req: PayloadRequest;
+}): Promise<boolean>;
 export {};