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

package/dist/esm/checkpointer/internal/parse.js

@@ -0,0 +1,169 @@
+import { KEY_SEPARATOR, MAX_CHECKPOINT_NS_BYTES, MAX_KEY_SEGMENT_BYTES, MAX_PARTITION_ID_BYTES, MAX_SORT_KEY_BYTES, MAX_WRITE_CHANNEL_BYTES, } from '../../shared/dynamodb/table-schema.js';
+import { validationError } from '../../shared/errors/errors.js';
+import { assertSignalLike } from '../../shared/validation/collaborators.js';
+import { assertObjectShape } from '../../shared/validation/option-shape.js';
+import { parseIdentifier, parseKeySegment, parseLimit, parseStringArray, } from '../../shared/validation/primitives.js';
+import { writeSortKeyBytes } from './rows.js';
+export function parseThreadId(value) {
+    return parseIdentifier(value, KEY_SEPARATOR, 'thread_id', MAX_PARTITION_ID_BYTES);
+}
+export function parseCheckpointNs(value) {
+    return parseKeySegment(value, KEY_SEPARATOR, 'checkpoint_ns', MAX_CHECKPOINT_NS_BYTES);
+}
+export function parseCheckpointId(value, field = 'checkpoint_id') {
+    return parseIdentifier(value, KEY_SEPARATOR, field, MAX_KEY_SEGMENT_BYTES);
+}
+export function parseTaskId(value) {
+    return parseIdentifier(value, KEY_SEPARATOR, 'taskId', MAX_KEY_SEGMENT_BYTES);
+}
+export function parseWriteChannel(value) {
+    return parseIdentifier(value, KEY_SEPARATOR, 'channel', MAX_WRITE_CHANNEL_BYTES);
+}
+export function parseTaskPath(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw validationError('taskPath must be a string', 'taskPath');
+    return value;
+}
+export const ROOT_NAMESPACE = parseCheckpointNs('');
+function isAbsentId(value) {
+    return value === undefined || value === null || value === '';
+}
+function assertConfigShape(config) {
+    assertObjectShape(config, 'config');
+    if (config.configurable !== undefined)
+        assertObjectShape(config.configurable, 'configurable');
+    assertSignalLike(config.signal);
+}
+function configurableOf(config) {
+    assertConfigShape(config);
+    return (config.configurable ?? {});
+}
+function namespaceOf(configurable) {
+    if (configurable.checkpoint_ns === undefined)
+        return undefined;
+    return parseCheckpointNs(configurable.checkpoint_ns ?? '');
+}
+function resolveCheckpointId(configurable) {
+    if (!isAbsentId(configurable.checkpoint_id))
+        return parseCheckpointId(configurable.checkpoint_id);
+    if (!isAbsentId(configurable.thread_ts)) {
+        return parseCheckpointId(configurable.thread_ts, 'thread_ts');
+    }
+    return undefined;
+}
+export function parseConfig(config) {
+    const configurable = configurableOf(config);
+    const threadId = configurable.thread_id === undefined ? undefined : parseThreadId(configurable.thread_id);
+    return {
+        threadId,
+        checkpointNs: namespaceOf(configurable),
+        checkpointId: resolveCheckpointId(configurable),
+        signal: config.signal,
+    };
+}
+export function parseThreadConfig(config) {
+    const configurable = configurableOf(config);
+    const threadId = parseThreadId(configurable.thread_id);
+    return {
+        address: {
+            threadId,
+            checkpointNs: namespaceOf(configurable) ?? ROOT_NAMESPACE,
+            checkpointId: resolveCheckpointId(configurable),
+        },
+        signal: config.signal,
+    };
+}
+export function parsePutRequest(config, checkpoint, metadata) {
+    const { address, signal } = parseThreadConfig(config);
+    if (checkpoint === null || checkpoint === undefined) {
+        throw validationError('checkpoint must be an object', 'checkpoint');
+    }
+    const checkpointId = parseCheckpointId(checkpoint.id);
+    return {
+        address: { threadId: address.threadId, checkpointNs: address.checkpointNs, checkpointId },
+        parentCheckpointId: address.checkpointId,
+        checkpoint,
+        metadata,
+        signal,
+    };
+}
+function assertWriteEntries(writes) {
+    if (!Array.isArray(writes)) {
+        throw validationError('writes must be an array', 'writes');
+    }
+    for (let index = 0; index < writes.length; index += 1) {
+        if (!Array.isArray(writes[index])) {
+            throw validationError(`writes[${index}] must be a [channel, value] tuple`, 'writes');
+        }
+    }
+}
+function assertWriteKeyFits(address, taskId, channel) {
+    const bytes = writeSortKeyBytes({
+        checkpointNs: address.checkpointNs,
+        checkpointId: address.checkpointId,
+        taskId,
+        channel,
+    });
+    if (bytes > MAX_SORT_KEY_BYTES) {
+        throw validationError(`checkpoint_ns, checkpoint_id, taskId and channel compose a ${bytes}-byte sort key; ` +
+            `DynamoDB caps sort keys at ${MAX_SORT_KEY_BYTES} bytes`, 'sortKey');
+    }
+}
+export function parsePutWritesRequest(config, writes, taskId, taskPath) {
+    const parsedTaskId = parseTaskId(taskId);
+    const parsedTaskPath = parseTaskPath(taskPath);
+    const { address, signal } = parseThreadConfig(config);
+    if (address.checkpointId === undefined) {
+        throw validationError('checkpoint_id is required to store writes', 'checkpoint_id');
+    }
+    const target = {
+        threadId: address.threadId,
+        checkpointNs: address.checkpointNs,
+        checkpointId: address.checkpointId,
+    };
+    assertWriteEntries(writes);
+    const channels = writes.map(([channel]) => parseWriteChannel(channel));
+    for (const channel of channels)
+        assertWriteKeyFits(target, parsedTaskId, channel);
+    return {
+        address: target,
+        taskId: parsedTaskId,
+        taskPath: parsedTaskPath,
+        writes: writes.map(([, value], index) => [channels[index], value]),
+        signal,
+    };
+}
+function beforeCheckpointId(before) {
+    if (before === undefined)
+        return undefined;
+    assertObjectShape(before, 'before');
+    const checkpointId = before.configurable?.checkpoint_id;
+    if (isAbsentId(checkpointId))
+        return undefined;
+    return parseCheckpointId(checkpointId, 'before');
+}
+export function parseListScope(config, options) {
+    const { threadId, checkpointNs, checkpointId, signal } = parseConfig(config);
+    if (options !== undefined) {
+        assertObjectShape(options, 'options');
+        if (options.filter !== undefined)
+            assertObjectShape(options.filter, 'filter');
+    }
+    const limit = options?.limit === undefined ? undefined : parseLimit(options.limit, 0);
+    return {
+        threadId,
+        checkpointNs,
+        checkpointId,
+        before: beforeCheckpointId(options?.before),
+        filter: options?.filter,
+        limit,
+        signal,
+    };
+}
+export function parseDeltaHistoryRequest(options) {
+    assertObjectShape(options, 'options');
+    assertConfigShape(options.config);
+    return { config: options.config, channels: parseStringArray(options.channels, 'channels') };
+}

package/dist/esm/checkpointer/internal/pending-writes.d.ts

@@ -0,0 +1,314 @@
+/**
+ * Hides how one `putWrites` call's rows commit, and which uploads each outcome
+ * releases.
+ *
+ * A positional write is first-write-wins: a retried task must not overwrite
+ * what its first run committed, and a rejection is the expected outcome of a
+ * retry, not a failure. A special channel's write overwrites, as every reference
+ * checkpointer does, under a compare-and-swap on the row's `writeGroup` so two
+ * concurrent calls cannot both release the same superseded payload. Around both,
+ * an upload is released only when a read, or the row a rejection returned,
+ * proves no live row names it — never on an outcome nothing confirmed.
+ */
+import { type PayloadDescriptor } from '../../shared/codec/codec.js';
+import { type RowProbe } from '../../shared/dynamodb/idempotent-write.js';
+import type { ThreadId } from './parse.js';
+import { type CheckpointWriteRow } from './rows.js';
+import type { CheckpointerContext } from './setup.js';
+/** One call's rows, ready to commit. */
+export interface PendingWriteBatch {
+    /** The caller's thread, which scopes every superseded object this commit may release. */
+    readonly threadId: ThreadId;
+    readonly items: CheckpointWriteRow[];
+    readonly signal: AbortSignal | undefined;
+}
+/**
+ * Commit one call's pending-write rows, then release the uploads the outcome
+ * proves dead.
+ *
+ * Accepts: `batch` — the call's thread, its encoded rows (positional and
+ * special together, in any order), and its signal.
+ *
+ * Returns: nothing, once every write has settled and the cleanup has run.
+ *
+ * Throws: the first genuine write failure, after every write has settled and
+ * the cleanup has run. A first-write-wins rejection is not a failure.
+ */
+export declare function commitPendingWrites(context: CheckpointerContext, batch: PendingWriteBatch): Promise<void>;
+/**
+ * Overwrite one special row, pinned to the `writeGroup` this call observed, and
+ * report the descriptor it superseded.
+ *
+ * Overwriting is correct for special channels — every reference implementation
+ * does it — but two concurrent calls to the same channel both read the same
+ * previous descriptor and both delete it, orphaning the loser's upload. Pinning
+ * the observed `writeGroup` and re-reading on rejection makes each call
+ * supersede exactly one payload.
+ *
+ * `BatchWriteItem` cannot carry conditions, which is why this path issues
+ * individual puts; a call holds at most one row per special channel, so that is
+ * four writes at worst.
+ *
+ * The compare-and-swap runs only when an offloader is configured — matching
+ * `store/internal/item-write.ts` — because without one there is no S3 object to
+ * orphan, so a plain unconditional put stays correct and costs no extra
+ * ConsistentRead or write capacity (see {@link writeWithoutOffloader}).
+ *
+ * A failure of the first read, before any put, is no verdict read from the row,
+ * and this call releases its own upload only on one. It is therefore reported
+ * the way every unverified outcome is: `committed: true` with the error, so the
+ * caller keeps the upload and leaves it to the lifecycle rule.
+ *
+ * Accepts: `item` — one special-channel row, carrying this call's `writeGroup`.
+ * `signal` — aborts the attempts.
+ *
+ * Returns: whether this item's upload must be kept (see
+ * {@link SpecialWriteOutcome}), the descriptor it superseded when the write
+ * committed, and the failure when there was one.
+ *
+ * Throws: nothing. The caller runs this concurrently with the regular writes
+ * under `Promise.all`, whose own cleanup depends on every branch resolving
+ * rather than short-circuiting.
+ *
+ * Guarantees: each call supersedes exactly one payload, so two concurrent calls
+ * to the same channel cannot both delete the same object and orphan the loser's
+ * upload.
+ */
+export declare function writeSpecialRow(context: CheckpointerContext, item: CheckpointWriteRow, signal?: AbortSignal): Promise<SpecialWriteOutcome>;
+/** What a special item's row held before this call tried to overwrite it. */
+export interface SpecialRowState {
+    exists: boolean;
+    value?: PayloadDescriptor;
+    revision?: string;
+}
+/**
+ * Outcome of one special item's conditional write. Never thrown, always returned.
+ *
+ * `committed` is true whenever this call's own upload must be kept: a confirmed
+ * commit, or an outcome nothing confirmed, which then also carries `error`. It
+ * is false only when the write is confirmed not to have committed, or when no
+ * offloader is configured and there is no upload to keep.
+ */
+export interface SpecialWriteOutcome {
+    committed: boolean;
+    superseded?: PayloadDescriptor;
+    error?: Error;
+}
+/** What a post-failure verification read established about the attempt. */
+export interface VerifiedFailure {
+    outcome: SpecialWriteOutcome;
+    /**
+     * Present only when the attempt is confirmed not to have landed: the row's
+     * state, for a compare-and-swap to re-pin to.
+     */
+    observed?: SpecialRowState;
+}
+/**
+ * The probe that recognises a write row's own write on its row — a special
+ * channel's row or a regular one, both of which carry a `writeGroup`.
+ *
+ * Accepts: `item` — the row this call tried to write, carrying its own
+ * `writeGroup`.
+ *
+ * Returns: the probe, which projects the guard attribute and the descriptor —
+ * the descriptor because a caller that has to re-pin a compare-and-swap needs
+ * the value it lost to, not just the fact that it lost.
+ *
+ * Throws: nothing.
+ */
+export declare function writeRowProbe(item: CheckpointWriteRow): RowProbe;
+/**
+ * Read a special row's current descriptor and the writeGroup guarding it.
+ *
+ * Accepts: `item` — the row to read, by its key.
+ *
+ * Returns: the row's state, with `exists: false` when there is none — which is
+ * what a first writer pins its compare-and-swap to.
+ *
+ * Throws: whatever the read throws. Deliberately not swallowed: the caller
+ * reports that failure with its own cause rather than guessing at the row's
+ * state, which is why this is separate from {@link verifyAfterFailure}.
+ */
+export declare function readSpecialRow(context: CheckpointerContext, item: CheckpointWriteRow): Promise<SpecialRowState>;
+/**
+ * Read the row back after a put failed, and report what that failure actually
+ * did — never assuming it did nothing.
+ *
+ * A guard rejection already carries the row that turned it away (see
+ * `rejectedRow`), so the strongly-consistent read is spent only for a failure
+ * that does not: a lost response, or a rejection whose row vanished since.
+ *
+ * Five answers are possible:
+ * - the row holds this item's own `writeGroup`: the write landed, and the
+ *   descriptor this attempt pinned is the dead one.
+ * - the row no longer satisfies this attempt's condition — it holds some other
+ *   group than the one the attempt was pinned to, or it is absent while the
+ *   attempt was pinned to a revision (`#rev = :rev`): the write is confirmed
+ *   not to be what is live and can no longer apply, so this item's own upload
+ *   is dead — its key ends in this call's own group, which no row names.
+ *   `observed` is returned so a rejected compare-and-swap can re-pin and try
+ *   again.
+ * - the row does not hold this item's group but still satisfies this attempt's
+ *   condition — it holds exactly the state the attempt was pinned to; or the
+ *   attempt was pinned to "no revision" and the row is absent, which that
+ *   `attribute_not_exists` guard admits too; or this attempt was never pinned
+ *   at all (the unconditional overwrite, which fits any row, a third writer's
+ *   included) — and the failure may
+ *   still land: any attempt of its budget got no answer (a cancel, a timeout,
+ *   a dropped connection), or DynamoDB answered that an earlier attempt under
+ *   this same token is still being processed, or with a server error (5xx).
+ *   Nothing is confirmed either way, so this is `'unverified'` rather than
+ *   `'not-landed'`, and the outcome reports a commit and keeps the upload.
+ * - the row still fits this attempt, but the failure was an answer that leaves
+ *   nothing in flight (a refusal, a throttle, a spent budget of such answers):
+ *   the write did not land, so this is `'not-landed'` and the upload is dead.
+ * - the read itself fails: nothing is confirmed, so the outcome still reports a
+ *   commit and keeps the originating error. That leaks one S3 object at worst
+ *   (reclaimed by `ensureS3LifecycleRule`) where the alternative strands a live
+ *   row — the same trade `store/internal/item-write.ts` makes.
+ *
+ * Accepts: `attempted` — the state this attempt pinned, whose descriptor is the
+ * one superseded if the write did land. `error` — the failure being explained.
+ * `pinned` — false for the unconditional overwrite, whose attempt can land
+ * over any row.
+ *
+ * Returns: the outcome, and the row's observed state whenever the attempt is
+ * confirmed not to have landed, so a rejected compare-and-swap can re-pin and
+ * try again.
+ *
+ * Throws: nothing. It exists to turn a failure into a decision.
+ *
+ * Guarantees: a guard rejection already carries the row that turned it away, so
+ * the strongly-consistent read is spent only for a failure that does not — a
+ * lost response, or a rejection whose row vanished since.
+ */
+export declare function verifyAfterFailure(context: CheckpointerContext, item: CheckpointWriteRow, attempted: SpecialRowState, error: Error, pinned?: boolean): Promise<VerifiedFailure>;
+/**
+ * Write special (negative-index) rows, then clean up the correct side of each.
+ *
+ * Overwrite is correct here, matching every reference checkpointer. Each item
+ * is written with a compare-and-swap on its row's `writeGroup` (see
+ * {@link writeSpecialRow}) so a concurrent call to the same special channel
+ * cannot make both callers delete the same superseded object and orphan one
+ * upload. A committed item cleans up the payload it actually superseded, and an
+ * item confirmed never to have committed cleans up its own new upload. Neither
+ * reads the row again first: every call uploads under its own `writeGroup`, so
+ * a row another call writes never names this item's upload, and this item's
+ * row names only that upload, never the payload it superseded.
+ *
+ * "Confirmed" is load-bearing, and {@link writeSpecialRow} is what earns it:
+ * an ambiguous failure, or a first read of the row that failed, is reported as
+ * committed unless a read proves otherwise. Deleting on *unknown* would strand
+ * a live row pointing at a deleted object; leaking one object instead is
+ * recoverable.
+ *
+ * Accepts: `items` — this call's special-channel rows; empty writes nothing.
+ * `threadId` — the caller's, which scopes every object this cleanup may delete.
+ *
+ * Returns: the first failure, or undefined when every item committed.
+ *
+ * Throws: nothing — a failure is reported via the return value, because the
+ * caller runs this concurrently with `writeRegularRows` under `Promise.all`,
+ * whose own cleanup depends on every branch resolving rather than
+ * short-circuiting.
+ *
+ * Guarantees: a superseded payload is released only once the item that
+ * superseded it committed, and an item's own upload only once a read, or the
+ * row returned with its rejected write, shows that the item's write is not what
+ * the row holds and can no longer land there: the row no longer satisfies the
+ * attempt's condition, or the failure left no attempt in flight (see
+ * {@link verifyAfterFailure}).
+ */
+export declare function writeSpecialRowsWithCleanup(context: CheckpointerContext, threadId: ThreadId, items: CheckpointWriteRow[], signal?: AbortSignal): Promise<Error | undefined>;
+/**
+ * Outcome of {@link writeRegularRows}: never rejects. `deadUploads` holds
+ * exactly the items whose own S3 upload is confirmed unreferenced by this
+ * call's row — a verified non-commit, a guard rejection whose returned row
+ * provably belongs to another call, or a write the caller's signal came
+ * before, which was never sent at all. Everything else either committed, was
+ * turned away by a row this call may have written itself, or could not be
+ * verified; none of those may be cleaned up.
+ *
+ * No other row is consulted before an upload in `deadUploads` is released: its
+ * key ends in this call's own `writeGroup`, which no row of another call names.
+ */
+export interface RegularWriteOutcome {
+    deadUploads: CheckpointWriteRow[];
+    error?: Error;
+}
+/**
+ * Regular pending writes one `putWrites` call keeps in flight. A `Send`
+ * fan-out can name a thousand of them, and the SDK's HTTP agent holds 50
+ * sockets by default: past that, a request waits for a socket, and the
+ * request timeout counts the wait, so a wide enough fan-out, larger values,
+ * or an injected client with a shorter request timeout can time out healthy
+ * writes that the retry layer then re-sends. Thirty-two in flight stays
+ * under the socket pool and still overlaps the round trips.
+ */
+export declare const REGULAR_WRITE_CONCURRENCY = 32;
+/**
+ * Write regular rows with a first-write-wins guard. Every write fully settles,
+ * at most {@link REGULAR_WRITE_CONCURRENCY} at a time, before this resolves,
+ * and it never rejects; a genuine failure is reported via `error`, not thrown.
+ * The fan-out is one call per item whichever shape {@link commitWriteRow}
+ * gives that item's write.
+ *
+ * A failure is not proof of a non-commit: `withDynamoDBRetry` re-issues a put
+ * whose response was lost, and the re-issues can time out at the transport, so
+ * the budget is spent on a `RETRY_EXHAUSTED` error while the row is live.
+ * Treating that as "never reached DynamoDB" deleted the object the live row
+ * pointed at, making the checkpoint's pending writes unreadable forever. Each
+ * such failure is therefore verified against the row before it is classified,
+ * and a committed one is not an error at all.
+ *
+ * Accepts: `items` — this call's regular write rows; empty writes nothing.
+ * `signal` — aborts the puts.
+ *
+ * Returns: which items are known not to have committed — whose own uploads are
+ * therefore dead — and the first genuine failure, if any; a write the caller's
+ * signal came before is not sent, and its upload is dead.
+ *
+ * Throws: nothing. Every put settles before this resolves, because the caller
+ * runs it beside the special writes under `Promise.all` and its cleanup depends
+ * on every branch resolving rather than short-circuiting.
+ *
+ * Guarantees: first-write-wins. A rejection means the row is already held, which
+ * is the expected outcome of a retry, not a failure.
+ */
+export declare function writeRegularRows(context: CheckpointerContext, items: CheckpointWriteRow[], signal?: AbortSignal): Promise<RegularWriteOutcome>;
+/**
+ * Report a guard rejection. Sort keys carry their channel, so a rejection
+ * normally means this exact (task, channel, occurrence) row is already
+ * committed — a genuine duplicate, and the expected outcome of a retry. A row
+ * held by a *different* channel is not something this adapter can produce, so
+ * it is reported at `warn`: the write was not persisted and something else
+ * wrote to this key space.
+ *
+ * Accepts: `error` — the rejection, which carries the row that caused it when
+ * the service returned attributes. No attributes means the two cases cannot be
+ * told apart, and the ordinary duplicate is the one assumed: warning on every
+ * unattributed rejection would cry wolf on the expected outcome of a retry.
+ *
+ * Returns: nothing. A rejection is not a failure here — first-write-wins means
+ * losing is a normal outcome — so it is reported, not thrown.
+ *
+ * Throws: nothing.
+ */
+export declare function reportGuardRejection(context: CheckpointerContext, item: CheckpointWriteRow, error: Error): void;
+/**
+ * Whether the rejection's returned row provably belongs to another `putWrites`
+ * call.
+ *
+ * Accepts: `error` — the rejection. `item` — the row this call tried to write,
+ * carrying its own `writeGroup`.
+ *
+ * Returns: whether the row that won carries a *different* group, which is the
+ * only evidence that this call's own upload is dead and safe to delete. A
+ * retried put whose response was lost can be rejected by the row it wrote
+ * itself, so an equal group — or no attributes at all — proves nothing and is
+ * answered `false`: the object is then left to the lifecycle rule rather than
+ * deleted out from under a live row.
+ *
+ * Throws: nothing.
+ */
+export declare function rejectionProvesForeignRow(item: CheckpointWriteRow, error: Error): boolean;