@farukada/aws-langgraph-dynamodb-ts 0.9.0 → 1.0.0-rc.2

package/dist/store/internal/get-item.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Hides what a single read counts as absent, and how it outlives an overwrite.
+ *
+ * A get reads its row strongly consistently and answers `null` alike for a
+ * missing row, an expired one and a row this adapter does not own. When the
+ * object an offloaded row names is deleted between the row read and the
+ * download, one re-read settles whether the item was replaced, removed or
+ * truly lost. A caller gets an item or `null` and never sees the race.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getItem = getItem;
+const clock_1 = require("../../shared/clock");
+const codec_1 = require("../../shared/codec/codec");
+const retry_1 = require("../../shared/dynamodb/retry");
+const table_schema_1 = require("../../shared/dynamodb/table-schema");
+const rows_1 = require("./rows");
+/**
+ * Read the row strongly consistently and narrow it rather than cast. A
+ * foreign row sharing this key has no `namespace`, and one carrying a `value`
+ * PayloadDescriptor in the same shape a store item uses (a checkpointer WRITE
+ * row) would otherwise decode cleanly and be handed back as the caller's own
+ * value. The narrow is the whole-row one, so a row with no `createdAt` or
+ * `updatedAt` is refused here rather than decoded into an item whose
+ * timestamps are `Invalid Date`.
+ */
+async function readRow(context, namespace, key, signal) {
+    const result = await (0, retry_1.withDynamoDBRetry)((request) => context.client.get({
+        TableName: context.tableName,
+        Key: (0, rows_1.itemRowKey)({ namespace, key }),
+        ConsistentRead: true,
+    }, request), (0, retry_1.retryFor)(context, signal));
+    if (!result.Item)
+        return undefined;
+    const record = (0, rows_1.parseWholeStoreRow)(result.Item);
+    if (!record) {
+        context.logger.warn('store.get: ignored a row that is not a store item', {
+            partitionKey: (0, rows_1.partitionKey)(namespace),
+            sortKey: (0, rows_1.sortKey)(namespace, key),
+        });
+        return undefined;
+    }
+    // A row past its ttl is absent to every reader, however long DynamoDB's sweep lags.
+    return (0, table_schema_1.isExpiredRow)(record, (0, clock_1.nowSeconds)()) ? undefined : record;
+}
+/**
+ * True when both records point at the same offloaded object.
+ *
+ * Only `read` is known to hold a descriptor: it is the row whose download just
+ * failed. `reread` is whatever the overwrite this recovery exists for left
+ * behind, which can be a `null` where the descriptor belongs, so it is tested
+ * for presence first. A row pointing at nothing is not pointing at the object
+ * this read lost, so it is decoded like any other replacement and answered with
+ * the coded error that names the descriptor — not with a property read that
+ * would replace the download's own failure with a bare `TypeError`.
+ */
+function sameObject(read, reread) {
+    const fresh = reread.value;
+    if (!fresh)
+        return false;
+    return (read.value.location === codec_1.PayloadLocation.S3 &&
+        fresh.location === codec_1.PayloadLocation.S3 &&
+        read.value.s3Key === fresh.s3Key);
+}
+/**
+ * Retrieve a single item by namespace and key (strongly consistent), or null.
+ *
+ * An offloaded item can lose a race with a concurrent overwrite: between the
+ * row read and the S3 download the writer commits a new descriptor and deletes
+ * the object this read was about to fetch. That surfaces as `NoSuchKey`, and
+ * one strongly-consistent re-read settles it — the row now points at the new
+ * object (return that), is gone (null), or still points at the same missing
+ * object (a genuine loss, rethrown). A row the overwrite left with no
+ * descriptor at all is a replacement like any other: it is decoded, and refused
+ * by its own coded error. Any other download failure propagates.
+ *
+ * Accepts: `address` — parsed; no check is repeated here. `signal` — aborts
+ * the reads.
+ *
+ * Returns: the item, or `null` for one that does not exist, has expired, or
+ * whose key holds a row this adapter does not own — which includes a row whose
+ * `createdAt` or `updatedAt` is not the string this package writes there, since
+ * an item is reported with both. The answers are one on purpose: a caller
+ * cannot act on the difference, and reporting a foreign row would leak that a
+ * shared table holds one.
+ *
+ * Throws: `VALIDATION` naming — for a row whose descriptor is not one —
+ * `descriptor`; `FORMAT_UNSUPPORTED` for
+ * a row, or a payload, written by a newer version, which is *not* reported as
+ * absent — hiding an item that exists is worse than failing; `PAYLOAD_CORRUPT`
+ * or the download's own error for a payload that cannot be read; `ABORTED`
+ * when the signal fires.
+ *
+ * Guarantees: strongly consistent — an item just written is always seen, and
+ * the ttl is honoured here rather than waited for.
+ */
+async function getItem(context, address, signal) {
+    const { namespace, key } = address;
+    const record = await readRow(context, namespace, key, signal);
+    if (!record)
+        return null;
+    try {
+        return await (0, rows_1.readStoreItem)(context, record, signal);
+    }
+    catch (error) {
+        if (!(0, codec_1.isMissingObjectError)(error))
+            throw error;
+        const fresh = await readRow(context, namespace, key, signal);
+        if (!fresh)
+            return null;
+        if (sameObject(record, fresh))
+            throw error;
+        return (0, rows_1.readStoreItem)(context, fresh, signal);
+    }
+}

package/dist/store/internal/item-write.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Hides how an item's row is replaced or removed without stranding its S3
+ * object or deleting one a live row still names.
+ *
+ * A put with an offloader pins its write to the revision it observed and
+ * re-reads when a concurrent writer wins; once the budget is spent it
+ * overwrites and may leak one object to the lifecycle rule. A delete pins
+ * itself the same way. Either releases the payload it superseded only once its
+ * own write committed, and a write whose outcome was lost is read back before
+ * anything is released. Without an offloader there is no object to protect,
+ * and a put is a plain write.
+ */
+import { type WriteVerdict } from '../../shared/dynamodb/idempotent-write';
+import type { StoreAddress } from './parse';
+import { type ExistingRowMeta, type StoreItemRow } from './rows';
+import type { StoreContext } from './setup';
+/**
+ * Delete the item and, when a vector backend is configured, drop its vector.
+ *
+ * The row is read first, then removed inside a one-item `TransactWriteItems`
+ * conditioned on the revision that read observed. An unconditional delete
+ * erases a put that commits between the caller's call and the write — no lost
+ * acknowledgement needed, no S3 involved — and releases the object that put
+ * uploaded. The condition refuses that, and the request token makes a lost
+ * acknowledgement harmless: the replay is answered from DynamoDB's idempotency
+ * cache instead of removing whatever has arrived since.
+ *
+ * **A key with no row costs one read and sends no write at all**, which is the
+ * same race closed from the other side: there is nothing to pin, so a put that
+ * lands mid-call survives. The S3 release and the vector sync still run, since
+ * a key with no row can still have a stranded vector and clearing it is a
+ * repair path callers have today — and the vector sync goes through the same
+ * confirmation as every other path rather than letting the pre-read stand in
+ * for it, so the put that lands mid-call keeps its vector too.
+ *
+ * What a caller can and cannot tell apart:
+ *
+ * - **Compare-and-swap exhaustion resolves rather than throwing.** Three
+ *   consecutive writers between a re-pin and its attempt leave the item in
+ *   place, release nothing — correctly, a live row names the object — and emit
+ *   one `warn`. Throwing instead would add a failure mode to an interleaving
+ *   that succeeds today, which every caller deleting in a `finally` would have
+ *   to handle.
+ * - **The vector is dropped only on a confirmation, and that window is
+ *   narrowed rather than closed.** Immediately before the backend call — and
+ *   above the S3 cleanup, so no round trip with its own retries sits inside the
+ *   window — one strongly-consistent projected read asks whether the key holds
+ *   a row now, and a row that is there keeps its vector and logs one `info`.
+ *   That covers both interleavings that would otherwise erase a live item's vector: a
+ *   put recreating the row this call removed, and the compare-and-swap above
+ *   resolving with the row untouched. What is left is a put committing between
+ *   that read and the backend call, two adjacent statements apart. Closing it
+ *   needs a compare-and-swap **on the vector backend** — delete this vector
+ *   only if it is still the one written at time T — which the `VectorBackend`
+ *   contract cannot express and no implementation would be obliged to honour,
+ *   so `reconcileVectorIndex` stays the named repair for it.
+ * - **A deadline cut and a spent budget are one error.** The transaction's
+ *   budget is additionally bounded by `MAX_WRITE_LIFETIME_MS`, so a caller who
+ *   configures a long retry policy can see the budget end there rather than at
+ *   its own last attempt; both arrive as `RETRY_EXHAUSTED` and neither says
+ *   which bound stopped it.
+ * - **The pre-read is a new way for this call to fail.** It issues no read
+ *   today, so a delete of a key with *no row* can now fail where it always
+ *   succeeded. Nothing has been written when it does: no row removed, no object
+ *   released, no vector touched. The error types a caller sees are unchanged —
+ *   `store.delete` already documents `RETRY_EXHAUSTED` — but "deleting an
+ *   item that is not there is not an error" now describes the outcome rather
+ *   than the round trip.
+ *
+ * Accepts: `address` — parsed; the namespace and key the cleanup is scoped and
+ * logged by, and the row's key is derived from it.
+ *
+ * Returns: nothing. The item is gone, was already gone, or — on
+ * compare-and-swap exhaustion — is still there and was left alone.
+ *
+ * Throws: whatever the pre-read throws; whatever the transaction throws other
+ * than a guard rejection, which is this call's own business; and
+ * `RETRY_EXHAUSTED` when the budget is spent and a read cannot confirm the
+ * row is gone. Three things about that list are worth saying rather than
+ * leaving to be inferred. The **pre-read** is why a delete of a key with no row
+ * can now fail at all, and nothing has been written when it does. A **guard
+ * rejection** is refused rather than raised: the row it names was replaced
+ * after this call observed it, so removing it would erase that put and release
+ * the object the put uploaded, and re-pinning on the row the rejection carried
+ * is strictly safer than either raising or proceeding. And **exhausting** those
+ * re-pins throws nothing either — it resolves with the item still there and one
+ * `warn`, so a caller that needs the item gone re-runs once the key is
+ * quiescent rather than catching anything.
+ *
+ * Guarantees: the object released is the **last observation's**, on every path
+ * that releases at all — the pre-read's when nothing re-pinned, the rejected
+ * row's when something did. It is never read back from the response, so by
+ * construction the object of a delete whose acknowledgement was lost is not
+ * leaked. Nothing is released while the outcome is unknown: only a
+ * confirmed absence or a confirmed delete licenses it. And the backend's
+ * `delete` is never reached without a confirmation immediately before it, on
+ * every path including the one whose key never had a row: one rule with no
+ * exception, because an exception on a repair-shaped path is where the erasure
+ * comes back unnoticed.
+ */
+export declare function deleteStoreItem(context: StoreContext, address: StoreAddress): Promise<void>;
+/**
+ * Put the record and clean up whichever side is now dead.
+ *
+ * The compare-and-swap path runs **only when an offloader is configured**:
+ * without one there is no S3 object to orphan, so a plain last-write-wins put
+ * stays correct and costs no extra write capacity (DynamoDB charges for a
+ * failed conditional write too). With one, the swap is what lets this call
+ * delete exactly the payload it superseded rather than a descriptor a racer may
+ * already have replaced.
+ *
+ * Every failure reaching the catch arrives after at least one put was issued —
+ * `putWithRevisionSwap` only re-reads from inside its own catch — so none of
+ * them proves a non-commit on its own: a put can commit server-side and lose
+ * its response, and a `ConditionalCheckFailedException` is as consistent with
+ * hitting the row this call just wrote as with a competitor's win. The row is
+ * therefore read back (`verifyWriteLanded`) before anything is deleted. Only a
+ * confirmed `'not-landed'` deletes this record's own object; a confirmed
+ * `'landed'` cleans up the previous object like the success path and swallows
+ * the error, and an `'unverified'` read deletes nothing and rethrows — leaking
+ * one object at worst rather than stranding a live row pointing at a deleted
+ * one. The verification compares the per-call `rev`, so an inline record is
+ * verified too: otherwise a lost acknowledgement of an inline overwrite would be
+ * reported as a failure while the previous offloaded object was never cleaned.
+ *
+ * Neither release reads the row again first. The record's object is uploaded
+ * under the record's own `rev`, which no other put uses, so no row another put
+ * commits names it; and the record names only that object, never the one it
+ * superseded.
+ *
+ * Accepts: `record` — the fully encoded row, its payload already uploaded if it
+ * was offloaded. `existing` — what the caller read before encoding.
+ *
+ * Returns: nothing. The row is committed and exactly one side's object, at
+ * most, has been released.
+ *
+ * Throws: whatever the write throws, unless the verification proves the write
+ * landed after all — in which case the error is swallowed and the cleanup runs
+ * as on the success path.
+ *
+ * Guarantees: this record's own object is released only after a read proves
+ * the write did not land, and a superseded object only after this record is
+ * committed. The failure modes are ordered by which is worse: a leaked object
+ * costs storage until the lifecycle rule reclaims it, while a row pointing at a
+ * deleted object is unreadable data, so every ambiguous case leaks instead of
+ * deletes.
+ */
+export declare function persistRow(context: StoreContext, record: StoreItemRow, existing: ExistingRowMeta): Promise<void>;
+/**
+ * Commit `record`, re-reading and retrying while another writer holds the row,
+ * and return the state this write actually superseded — the only descriptor
+ * safe to delete afterwards.
+ *
+ * Without the swap both racers read the same previous descriptor, both commit,
+ * and both delete it, orphaning the loser's own upload. Retrying against the
+ * *re-read* state is what makes each writer supersede exactly one payload.
+ *
+ * A rejection is not proof a competitor won: `withDynamoDBRetry` retries
+ * transient errors, so an attempt can commit server-side, its response can be
+ * lost, and the retried put can hit the row it just wrote and fail the same
+ * guard — indistinguishable from a competitor's win by the rejection alone.
+ * Each attempt's pinned observation is captured in `attempted` before the
+ * put, so that when a re-read finds the row already holding *this call's
+ * own* `rev`, the swap returns whatever `attempted` held — never this
+ * record's own just-committed value, which would strand the live row
+ * pointing at a deleted object. That comparison is guarded on `rev` being
+ * set: `rev` is optional on the record type, and an unnonced record against a
+ * pre-0.9.0 revision-less row would otherwise match `undefined === undefined`
+ * and claim a race it never entered.
+ *
+ * On exhaustion the write proceeds unconditionally and warns. That is
+ * deliberate: the fallback is precisely the pre-0.9.0 behaviour — one possible
+ * orphan, reclaimed by a lifecycle rule — so pathological contention degrades
+ * instead of turning a working put into an error. `createdAt` is refreshed from
+ * each re-read so a row created by whoever won keeps its true creation time.
+ *
+ * Accepts: `record` — the row to commit, carrying this call's own `rev`.
+ * `existing` — what the caller read before encoding, used as the first pin; an
+ * `exists: false` observation pins "no row", so a creation races correctly too.
+ *
+ * Returns: the state this write actually superseded — the descriptor safe to
+ * delete — which is the last observation the winning put was pinned to, never
+ * this record's own value.
+ *
+ * Throws: whatever the put throws other than a conditional-check failure; those
+ * are the swap's own business.
+ *
+ * Guarantees: at most {@link OVERWRITE_CAS_MAX_ATTEMPTS} conditional puts, and
+ * a re-read only when the rejection did not already carry the row that caused
+ * it.
+ */
+export declare function putWithRevisionSwap(context: StoreContext, record: StoreItemRow, existing: ExistingRowMeta): Promise<ExistingRowMeta>;
+/**
+ * Whether `error` is a spent retry budget.
+ *
+ * Accepts: any error, and equally anything else a `throw` can produce.
+ * Recognised by brand and code: the code is the one thing an error crossing a
+ * module or realm boundary can be relied on to keep.
+ *
+ * Returns: whether the write is ambiguous for the reason retries were spent,
+ * which is the only failure a verification read is allowed to resolve.
+ *
+ * Throws: **nothing**, for any value. A value carrying no such code is not a
+ * spent budget, so the caller rethrows it rather than spending a read on it.
+ */
+export declare function isRetryExhausted(error: Error): boolean;
+/**
+ * Read `record`'s row back to establish what an ambiguous write actually did,
+ * comparing the row's revision with the one this write carried. Every put
+ * stamps a fresh per-call `rev`, so the comparison works for inline and
+ * offloaded records alike.
+ *
+ * Accepts: `record` — the row this call wrote, carrying the `rev` it stamped.
+ * A record with no `rev` has nothing to compare and is reported `'not-landed'`
+ * without spending a read.
+ *
+ * Returns: `'landed'`, `'not-landed'` or `'unverified'`; see
+ * {@link WriteVerdict} for what each answer licenses the caller to do. Only the
+ * `rev` is read: an offloaded record's key ends in that same `rev`, so the row
+ * holding a different one never names this write's object, and a cleanup
+ * needs nothing more from it.
+ *
+ * Throws: nothing — a failed verification is `'unverified'`, which is an
+ * answer, not an error.
+ */
+export declare function verifyWriteLanded(context: StoreContext, record: {
+    PK: string;
+    SK: string;
+    rev?: string;
+}): Promise<WriteVerdict>;