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

package/dist/checkpointer/internal/read.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Hides which rows a checkpoint read issues, with what consistency, and how a
+ * checkpoint an older release wrote is read back.
+ *
+ * A tuple is a META row, a PAYLOAD row and a checkpoint's WRITE rows, read
+ * strongly for `getTuple` and eventually for `list`, with expired rows absent
+ * however long DynamoDB's sweep lags, and with a pre-v4 checkpoint's `Send`s
+ * migrated from its parent's pending writes. The caller asks for a tuple; which
+ * reads that takes, and in what order, is decided here.
+ */
+import { type Checkpoint, type CheckpointMetadata, type CheckpointPendingWrite, type CheckpointTuple } from '@langchain/langgraph-checkpoint';
+import type { ThreadAddress } from './parse';
+import { type CheckpointLocation, type CheckpointMetaRow, type CheckpointPayloadRow } from './rows';
+import type { CheckpointerContext } from './setup';
+/** The thread and namespace a read was asked for. */
+export interface ThreadLocation {
+    readonly threadId: string;
+    readonly checkpointNs: string;
+}
+/** A checkpoint's parent, whose pending writes a pre-v4 checkpoint's migration reads. */
+export interface PendingSendsSource extends ThreadLocation {
+    readonly parentCheckpointId: string | undefined;
+}
+/** Per-read options for the payload and writes reads. */
+export interface ReadOptions {
+    signal?: AbortSignal;
+    /** `false` for bulk reads (`list`) that trade read-your-writes for half the read cost. */
+    consistent?: boolean;
+}
+/**
+ * The META row a read is about: the one `checkpointId` names, else the newest
+ * in the namespace.
+ *
+ * Accepts: `address` — parsed; its `checkpointId` names the row, and its
+ * absence asks for the newest in the namespace. `signal` — aborts the read.
+ *
+ * Returns: the row, or undefined when there is none — including when every row
+ * in the namespace has expired, or when the only rows there belong to another
+ * writer.
+ *
+ * Throws: `FORMAT_UNSUPPORTED` for a row of ours written by a newer version;
+ * whatever the read throws.
+ *
+ * Guarantees: strongly consistent, and expiry is judged here rather than waited
+ * for, so a checkpoint past its ttl is absent to every reader however long
+ * DynamoDB's sweep lags. The newest-first read returns the first live row of
+ * ours and stops there, stepping over expired and foreign rows
+ * {@link LATEST_META_PAGE_SIZE} at a time rather than one per round trip.
+ */
+export declare function fetchTargetMeta(context: CheckpointerContext, address: ThreadAddress, signal?: AbortSignal): Promise<CheckpointMetaRow | undefined>;
+/**
+ * The PAYLOAD row of one checkpoint.
+ *
+ * Accepts: `at` — the checkpoint's location. `read.consistent` — defaults to
+ * true; `list` passes false and accepts replica lag, since a listing tolerates
+ * what a read-your-writes `getTuple` does not.
+ *
+ * Returns: the row, or undefined when it is not there — the window the ordered
+ * PAYLOAD→META write leaves open, which the caller answers as "no checkpoint".
+ *
+ * Throws: `FORMAT_UNSUPPORTED` for a row a newer release wrote; whatever the
+ * read throws.
+ */
+export declare function fetchPayload(context: CheckpointerContext, at: CheckpointLocation, read?: ReadOptions): Promise<CheckpointPayloadRow | undefined>;
+/**
+ * Every pending write stored for one checkpoint, decoded, in write order.
+ *
+ * Accepts: `at` — the checkpoint's location. `read.consistent` — omitted reads
+ * strongly consistently; `list` passes `false` explicitly and accepts replica
+ * lag, `getTuple` passes `true`.
+ *
+ * Returns: the writes after `dropSupersededWrites` has resolved
+ * first-write-wins; a checkpoint with none returns an empty array.
+ *
+ * Throws: `FORMAT_UNSUPPORTED` for a row a newer release wrote; whatever the
+ * query or the payload decode throws.
+ *
+ * Guarantees: the read is deliberately uncapped. It must be complete to be
+ * correct — a `Send` fan-out retried with a changed write order leaves
+ * superseded rows behind that would count toward any cap — so past
+ * {@link LIST_SCAN_WARN_THRESHOLD} rows the read still succeeds and an operator
+ * is told the checkpoint is unusually heavy.
+ */
+export declare function fetchPendingWrites(context: CheckpointerContext, at: CheckpointLocation, read?: ReadOptions): Promise<CheckpointPendingWrite[]>;
+/** How a tuple is assembled: cancellation, read consistency, and metadata already decoded by the caller. */
+export interface AssembleOptions {
+    signal?: AbortSignal;
+    /** `true` for `getTuple` (read-your-writes), `false` for the eventually-consistent `list` path. */
+    consistent: boolean;
+    /** Metadata the caller decoded to apply a filter, so it is not decoded (or downloaded) twice. */
+    metadata?: CheckpointMetadata;
+}
+/**
+ * A full {@link CheckpointTuple} built from a META row.
+ *
+ * Accepts: `thread` — the **caller's** location, never the row's: `thread.threadId`
+ * scopes which S3 object the row may point at, so it must come from the
+ * partition the caller asked for; `thread.checkpointNs` is its namespace.
+ * `options.metadata` — already decoded by a filtered `list`, so a filtered
+ * listing decodes and downloads each metadata blob once, not twice.
+ * `options.consistent` — true for `getTuple`, false for `list`.
+ *
+ * Returns: the tuple, with `parentConfig` set only when the row names a parent;
+ * `undefined` when the PAYLOAD row is absent — the window the ordered
+ * PAYLOAD→META write leaves open, and the same answer a caller gets for a
+ * checkpoint that does not exist.
+ *
+ * Throws: whatever the reads and decodes throw.
+ */
+export declare function assembleTuple(context: CheckpointerContext, thread: ThreadLocation, meta: CheckpointMetaRow, options: AssembleOptions): Promise<CheckpointTuple | undefined>;
+/**
+ * Pre-v4 checkpoints kept a task's `Send`s as `__pregel_tasks` pending writes
+ * on the parent rather than in the checkpoint itself. Reading such a
+ * checkpoint rebuilds `channel_values[TASKS]` from those writes and stamps
+ * the channel with the highest version the checkpoint already carries (or
+ * the first version when it carries none), exactly as the reference savers
+ * do, so a thread written before LangGraph 0.2 still resumes.
+ *
+ * Accepts: `checkpoint` — any version. `parent` — the checkpoint's own thread
+ * and namespace, plus `parent.parentCheckpointId`, the parent whose pending
+ * writes hold the sends; absent means there is nowhere to migrate from.
+ * `read` — cancellation and consistency for the pending-writes read.
+ *
+ * Returns: the checkpoint untouched when it is v4 or has no parent, and
+ * otherwise a copy with `channel_values[TASKS]` rebuilt. The input is never
+ * mutated.
+ *
+ * Throws: whatever reading the parent's pending writes throws.
+ */
+export declare function migratePendingSends(context: CheckpointerContext, checkpoint: Checkpoint, parent: PendingSendsSource, read: ReadOptions): Promise<Checkpoint>;

package/dist/checkpointer/internal/read.js

@@ -0,0 +1,264 @@
+"use strict";
+/**
+ * Hides which rows a checkpoint read issues, with what consistency, and how a
+ * checkpoint an older release wrote is read back.
+ *
+ * A tuple is a META row, a PAYLOAD row and a checkpoint's WRITE rows, read
+ * strongly for `getTuple` and eventually for `list`, with expired rows absent
+ * however long DynamoDB's sweep lags, and with a pre-v4 checkpoint's `Send`s
+ * migrated from its parent's pending writes. The caller asks for a tuple; which
+ * reads that takes, and in what order, is decided here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchTargetMeta = fetchTargetMeta;
+exports.fetchPayload = fetchPayload;
+exports.fetchPendingWrites = fetchPendingWrites;
+exports.assembleTuple = assembleTuple;
+exports.migratePendingSends = migratePendingSends;
+const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
+const clock_1 = require("../../shared/clock");
+const paginate_1 = require("../../shared/dynamodb/paginate");
+const retry_1 = require("../../shared/dynamodb/retry");
+const table_schema_1 = require("../../shared/dynamodb/table-schema");
+const rows_1 = require("./rows");
+/**
+ * Rows one page of the newest-first META read evaluates. The read stops at the
+ * first live row of ours, so this decides only how many *dead* rows one round
+ * trip can step over: at one row per page, a thread whose head has aged out
+ * under a `ttl` costs one `Query` per expired row, and DynamoDB's own sweep may
+ * lag that `ttl` by up to 48 hours, so the run of dead rows can be as long as
+ * the thread is busy. This is the hottest read the package performs — every
+ * graph step begins with it — so a round trip per aged-out row is the wrong
+ * side of the trade to pay on every step.
+ *
+ * The trade runs the other way when nothing at the head has expired, which is
+ * every thread that sets no `ttl` at all. DynamoDB applies `Limit` before the
+ * filter and bills for what it evaluated, so such a read pays for up to this
+ * many META rows and keeps exactly one. A META row measures roughly 500
+ * bytes for a typical checkpoint, which puts a page at ~26 KB: about seven
+ * strongly consistent read units where a single row costs one, and a fortieth
+ * of the 1 MB a `Query` may return, so the page size rather than the response
+ * cap is always what ends a page.
+ */
+const LATEST_META_PAGE_SIZE = 50;
+/**
+ * The META row a read is about: the one `checkpointId` names, else the newest
+ * in the namespace.
+ *
+ * Accepts: `address` — parsed; its `checkpointId` names the row, and its
+ * absence asks for the newest in the namespace. `signal` — aborts the read.
+ *
+ * Returns: the row, or undefined when there is none — including when every row
+ * in the namespace has expired, or when the only rows there belong to another
+ * writer.
+ *
+ * Throws: `FORMAT_UNSUPPORTED` for a row of ours written by a newer version;
+ * whatever the read throws.
+ *
+ * Guarantees: strongly consistent, and expiry is judged here rather than waited
+ * for, so a checkpoint past its ttl is absent to every reader however long
+ * DynamoDB's sweep lags. The newest-first read returns the first live row of
+ * ours and stops there, stepping over expired and foreign rows
+ * {@link LATEST_META_PAGE_SIZE} at a time rather than one per round trip.
+ */
+async function fetchTargetMeta(context, address, signal) {
+    const { threadId, checkpointNs, checkpointId } = address;
+    // Expired rows are absent to every reader, however long DynamoDB's sweep lags.
+    const now = (0, clock_1.nowSeconds)();
+    if (checkpointId !== undefined) {
+        const result = await (0, retry_1.withDynamoDBRetry)((request) => context.client.get({
+            TableName: context.tableName,
+            Key: (0, rows_1.metaRowKey)({ threadId, checkpointNs, checkpointId }),
+            ConsistentRead: true,
+        }, request), (0, retry_1.retryFor)(context, signal));
+        const meta = (0, rows_1.parseHeadRow)(context, result.Item);
+        return meta && !(0, table_schema_1.isExpiredRow)(meta, now) ? meta : undefined;
+    }
+    const params = (0, rows_1.beginsWithQuery)(context.tableName, (0, rows_1.partitionKey)(threadId), (0, rows_1.metaSortKeyPrefix)(checkpointNs), {
+        limit: LATEST_META_PAGE_SIZE,
+        consistent: true,
+    });
+    // Both caps stay off, each for its own reason. `maxItems` counts the rows
+    // yielded past the server-side filter, and a finite value there would add
+    // the probe `paginateQuery` runs to tell a reached cap apart from an
+    // exhausted read — more requests, on the read the page size above exists to
+    // make cheaper. `maxIterations` is the runaway guard, but a finite value
+    // would turn a namespace whose rows have all aged out into a thrown
+    // `RESULT_TRUNCATED` where this function documents `undefined`, failing
+    // every graph step on exactly the thread shape the page size is here to
+    // serve. The page size is what bounds the walk instead: it divides the
+    // requests a dead head costs by `LATEST_META_PAGE_SIZE`.
+    const rows = (0, paginate_1.paginateQuery)({
+        retry: (0, retry_1.retryFor)(context, signal),
+        signal,
+        client: context.client,
+        params: (0, table_schema_1.withoutExpired)(params, now),
+        maxItems: Number.POSITIVE_INFINITY,
+        maxIterations: Number.POSITIVE_INFINITY,
+    });
+    for await (const raw of rows) {
+        const meta = (0, rows_1.parseHeadRow)(context, raw);
+        if (meta && !(0, table_schema_1.isExpiredRow)(meta, now))
+            return meta;
+    }
+    return undefined;
+}
+/**
+ * The PAYLOAD row of one checkpoint.
+ *
+ * Accepts: `at` — the checkpoint's location. `read.consistent` — defaults to
+ * true; `list` passes false and accepts replica lag, since a listing tolerates
+ * what a read-your-writes `getTuple` does not.
+ *
+ * Returns: the row, or undefined when it is not there — the window the ordered
+ * PAYLOAD→META write leaves open, which the caller answers as "no checkpoint".
+ *
+ * Throws: `FORMAT_UNSUPPORTED` for a row a newer release wrote; whatever the
+ * read throws.
+ */
+async function fetchPayload(context, at, read = {}) {
+    const result = await (0, retry_1.withDynamoDBRetry)((request) => context.client.get({
+        TableName: context.tableName,
+        Key: (0, rows_1.payloadRowKey)(at),
+        ConsistentRead: read.consistent ?? true,
+    }, request), (0, retry_1.retryFor)(context, read.signal));
+    const item = result.Item;
+    // A payload of ours written by a newer release fails loudly, as its META row
+    // would: decoding it under today's rules is how a checkpoint comes back with
+    // state silently missing.
+    if (item !== undefined)
+        (0, table_schema_1.assertReadableRow)(item, 'checkpoint payload');
+    return item;
+}
+/**
+ * Every pending write stored for one checkpoint, decoded, in write order.
+ *
+ * Accepts: `at` — the checkpoint's location. `read.consistent` — omitted reads
+ * strongly consistently; `list` passes `false` explicitly and accepts replica
+ * lag, `getTuple` passes `true`.
+ *
+ * Returns: the writes after `dropSupersededWrites` has resolved
+ * first-write-wins; a checkpoint with none returns an empty array.
+ *
+ * Throws: `FORMAT_UNSUPPORTED` for a row a newer release wrote; whatever the
+ * query or the payload decode throws.
+ *
+ * Guarantees: the read is deliberately uncapped. It must be complete to be
+ * correct — a `Send` fan-out retried with a changed write order leaves
+ * superseded rows behind that would count toward any cap — so past
+ * {@link LIST_SCAN_WARN_THRESHOLD} rows the read still succeeds and an operator
+ * is told the checkpoint is unusually heavy.
+ */
+async function fetchPendingWrites(context, at, read = {}) {
+    const params = (0, rows_1.beginsWithQuery)(context.tableName, (0, rows_1.partitionKey)(at.threadId), (0, rows_1.writeSortKeyPrefix)(at.checkpointNs, at.checkpointId), { ascending: true, consistent: read.consistent ?? true });
+    // Unbounded: the read must be complete to be correct, and a Send fan-out
+    // retried with a changed write order leaves superseded rows behind that
+    // count toward any cap. Past the warning threshold the read still succeeds,
+    // but an operator is told the checkpoint is unusually heavy.
+    const items = [];
+    for await (const item of (0, paginate_1.paginateQuery)({
+        retry: (0, retry_1.retryFor)(context, read.signal),
+        signal: read.signal,
+        client: context.client,
+        params,
+        maxItems: Number.POSITIVE_INFINITY,
+        maxIterations: Number.POSITIVE_INFINITY,
+    })) {
+        // Checked before `dropSupersededWrites` reads `writeGroup`: that dedup runs
+        // on every row regardless of format, and a newer format may give the
+        // attribute a different meaning.
+        (0, table_schema_1.assertReadableRow)(item, 'pending write');
+        items.push(item);
+    }
+    if (items.length >= paginate_1.LIST_SCAN_WARN_THRESHOLD) {
+        context.logger.warn('getTuple: a checkpoint carries very many pending-write rows; the read is complete but slow', {
+            threadId: at.threadId,
+            checkpointId: at.checkpointId,
+            rows: items.length,
+        });
+    }
+    return (0, rows_1.toPendingWrites)(context, items, at.threadId, read.signal);
+}
+/** Build a config that addresses a specific checkpoint. */
+function configFor(threadId, checkpointNs, checkpointId) {
+    return {
+        configurable: { thread_id: threadId, checkpoint_ns: checkpointNs, checkpoint_id: checkpointId },
+    };
+}
+/**
+ * A full {@link CheckpointTuple} built from a META row.
+ *
+ * Accepts: `thread` — the **caller's** location, never the row's: `thread.threadId`
+ * scopes which S3 object the row may point at, so it must come from the
+ * partition the caller asked for; `thread.checkpointNs` is its namespace.
+ * `options.metadata` — already decoded by a filtered `list`, so a filtered
+ * listing decodes and downloads each metadata blob once, not twice.
+ * `options.consistent` — true for `getTuple`, false for `list`.
+ *
+ * Returns: the tuple, with `parentConfig` set only when the row names a parent;
+ * `undefined` when the PAYLOAD row is absent — the window the ordered
+ * PAYLOAD→META write leaves open, and the same answer a caller gets for a
+ * checkpoint that does not exist.
+ *
+ * Throws: whatever the reads and decodes throw.
+ */
+async function assembleTuple(context, thread, meta, options) {
+    const read = { signal: options.signal, consistent: options.consistent };
+    const at = { ...thread, checkpointId: meta.checkpointId };
+    const payload = await fetchPayload(context, at, read);
+    if (!payload)
+        return undefined;
+    const [checkpoint, metadata, pendingWrites] = await Promise.all([
+        (0, rows_1.readCheckpoint)(context, payload, thread.threadId, options.signal).then((stored) => migratePendingSends(context, stored, { ...thread, parentCheckpointId: meta.parentCheckpointId }, read)),
+        options.metadata ?? (0, rows_1.readMetadata)(context, meta, thread.threadId, options.signal),
+        fetchPendingWrites(context, at, read),
+    ]);
+    const tuple = {
+        config: configFor(thread.threadId, thread.checkpointNs, meta.checkpointId),
+        checkpoint,
+        metadata,
+        pendingWrites,
+    };
+    if (meta.parentCheckpointId !== undefined) {
+        tuple.parentConfig = configFor(thread.threadId, thread.checkpointNs, meta.parentCheckpointId);
+    }
+    return tuple;
+}
+/**
+ * Pre-v4 checkpoints kept a task's `Send`s as `__pregel_tasks` pending writes
+ * on the parent rather than in the checkpoint itself. Reading such a
+ * checkpoint rebuilds `channel_values[TASKS]` from those writes and stamps
+ * the channel with the highest version the checkpoint already carries (or
+ * the first version when it carries none), exactly as the reference savers
+ * do, so a thread written before LangGraph 0.2 still resumes.
+ *
+ * Accepts: `checkpoint` — any version. `parent` — the checkpoint's own thread
+ * and namespace, plus `parent.parentCheckpointId`, the parent whose pending
+ * writes hold the sends; absent means there is nowhere to migrate from.
+ * `read` — cancellation and consistency for the pending-writes read.
+ *
+ * Returns: the checkpoint untouched when it is v4 or has no parent, and
+ * otherwise a copy with `channel_values[TASKS]` rebuilt. The input is never
+ * mutated.
+ *
+ * Throws: whatever reading the parent's pending writes throws.
+ */
+async function migratePendingSends(context, checkpoint, parent, read) {
+    if (checkpoint.v >= 4 || parent.parentCheckpointId === undefined)
+        return checkpoint;
+    const writes = await fetchPendingWrites(context, {
+        threadId: parent.threadId,
+        checkpointNs: parent.checkpointNs,
+        checkpointId: parent.parentCheckpointId,
+    }, read);
+    const sends = writes.filter(([, channel]) => channel === langgraph_checkpoint_1.TASKS).map(([, , value]) => value);
+    const versions = Object.values(checkpoint.channel_versions);
+    return {
+        ...checkpoint,
+        channel_values: { ...checkpoint.channel_values, [langgraph_checkpoint_1.TASKS]: sends },
+        channel_versions: {
+            ...checkpoint.channel_versions,
+            [langgraph_checkpoint_1.TASKS]: versions.length > 0 ? (0, langgraph_checkpoint_1.maxChannelVersion)(...versions) : 1,
+        },
+    };
+}