mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-11-20 11:20:35 +00:00
* fix(threads): reject a state update as_node LangGraph cannot compile
POST /threads/{id}/state passes the client's as_node to the state
mutation graph as its only node. LangGraph refuses __start__, __end__,
its other reserved names and names containing ':' or '|', and that
compile runs before the route's error handling, so those values ended in
an unhandled 500.
Check the name in the request model with the same rules, so it is a 422
on the as_node field before any graph is built or state is written. A
parity test keeps the check aligned with LangGraph's own compile.
* docs(runtime): note the LangGraph floor the reserved-name check was verified on
* docs(checkpoints): re-anchor checkpoint_state rows and list validate_state_mutation_node
The new function shifts the cstate line ranges the reference page cites
for CheckpointStateAccessor.bind and build_state_mutation_graph.
384 lines
15 KiB
Python
384 lines
15 KiB
Python
from __future__ import annotations
|
|
|
|
from copy import deepcopy
|
|
from types import SimpleNamespace
|
|
from typing import Annotated, Any, TypedDict
|
|
|
|
import pytest
|
|
from langchain_core.messages import AnyMessage
|
|
from langgraph.checkpoint.memory import InMemorySaver
|
|
from langgraph.graph.message import add_messages
|
|
|
|
from deerflow.runtime import CheckpointStateAccessor
|
|
from deerflow.runtime.checkpoint_mode import CHECKPOINT_MODE_METADATA_KEY, INTERNAL_CHECKPOINT_MODE_KEY
|
|
|
|
|
|
class FakeCheckpointer:
|
|
def __init__(self) -> None:
|
|
self.sync_configs: list[dict[str, Any]] = []
|
|
self.async_configs: list[dict[str, Any]] = []
|
|
self.checkpoint_tuple: Any | None = None
|
|
|
|
def get_tuple(self, config: dict[str, Any]) -> None:
|
|
self.sync_configs.append(config)
|
|
return self.checkpoint_tuple
|
|
|
|
async def aget_tuple(self, config: dict[str, Any]) -> None:
|
|
self.async_configs.append(config)
|
|
return self.checkpoint_tuple
|
|
|
|
|
|
class FakeGraph:
|
|
def __init__(self) -> None:
|
|
self.checkpointer: Any = None
|
|
self.store: Any = None
|
|
self.calls: list[tuple[Any, ...]] = []
|
|
self.sync_history_yields = 0
|
|
self.async_history_yields = 0
|
|
|
|
def get_state(self, config: dict[str, Any]) -> SimpleNamespace:
|
|
self.calls.append(("get", config))
|
|
return SimpleNamespace(values={"messages": ["sync"]})
|
|
|
|
def get_state_history(self, config: dict[str, Any], *, limit: int | None = None):
|
|
self.calls.append(("history", config, limit))
|
|
for index in range(4):
|
|
if limit is not None and self.sync_history_yields >= limit:
|
|
return
|
|
self.sync_history_yields += 1
|
|
yield SimpleNamespace(values={"index": index})
|
|
|
|
def update_state(self, config: dict[str, Any], values: dict[str, Any], *, as_node: str | None = None) -> dict[str, Any]:
|
|
self.calls.append(("update", config, values, as_node))
|
|
return {"updated": values, "as_node": as_node}
|
|
|
|
async def aget_state(self, config: dict[str, Any]) -> SimpleNamespace:
|
|
self.calls.append(("aget", config))
|
|
return SimpleNamespace(values={"messages": ["async"]})
|
|
|
|
async def aget_state_history(self, config: dict[str, Any], *, limit: int | None = None):
|
|
self.calls.append(("ahistory", config, limit))
|
|
for index in range(4):
|
|
if limit is not None and self.async_history_yields >= limit:
|
|
return
|
|
self.async_history_yields += 1
|
|
yield SimpleNamespace(values={"index": index})
|
|
|
|
async def aupdate_state(
|
|
self,
|
|
config: dict[str, Any],
|
|
values: dict[str, Any],
|
|
*,
|
|
as_node: str | None = None,
|
|
) -> dict[str, Any]:
|
|
self.calls.append(("aupdate", config, values, as_node))
|
|
return {"updated": values, "as_node": as_node}
|
|
|
|
|
|
def _assert_delta_config_is_copied(original: dict[str, Any], forwarded: dict[str, Any]) -> None:
|
|
assert forwarded is not original
|
|
assert forwarded["configurable"] is not original["configurable"]
|
|
assert forwarded["metadata"] is not original["metadata"]
|
|
assert forwarded["configurable"][INTERNAL_CHECKPOINT_MODE_KEY] == "delta"
|
|
assert forwarded["metadata"][CHECKPOINT_MODE_METADATA_KEY] == "delta"
|
|
|
|
|
|
def test_mutation_graph_bakes_snapshot_frequency_into_fallback_schema() -> None:
|
|
from langgraph.channels import DeltaChannel
|
|
|
|
from deerflow.runtime.checkpoint_state import build_state_mutation_graph
|
|
|
|
default_graph = build_state_mutation_graph("compact", "delta")
|
|
assert isinstance(default_graph.channels["messages"], DeltaChannel)
|
|
assert default_graph.channels["messages"].snapshot_frequency == 10
|
|
|
|
low_cadence = build_state_mutation_graph("compact", "delta", snapshot_frequency=250)
|
|
assert low_cadence.channels["messages"].snapshot_frequency == 250
|
|
|
|
|
|
def _langgraph_refused_node_names() -> list[str]:
|
|
from langgraph._internal._constants import RESERVED
|
|
from langgraph.constants import END, START
|
|
|
|
return sorted({START, END, *RESERVED, "a|b", "a:b", "branch:x"})
|
|
|
|
|
|
@pytest.mark.parametrize("as_node", _langgraph_refused_node_names())
|
|
def test_validate_state_mutation_node_rejects_every_name_langgraph_refuses(as_node: str) -> None:
|
|
"""The client check and LangGraph's compile must refuse the same names."""
|
|
from deerflow.runtime.checkpoint_state import build_state_mutation_graph, validate_state_mutation_node
|
|
|
|
with pytest.raises(ValueError):
|
|
build_state_mutation_graph(as_node, "full")
|
|
with pytest.raises(ValueError):
|
|
validate_state_mutation_node(as_node)
|
|
|
|
|
|
@pytest.mark.parametrize("as_node", ["manual_state_update", "agent", "messages", "__start", "start", "a b", "é", "x" * 5000])
|
|
def test_validate_state_mutation_node_accepts_names_langgraph_compiles(as_node: str) -> None:
|
|
"""Names LangGraph compiles stay accepted, so the check never rejects a working update."""
|
|
from deerflow.runtime.checkpoint_state import build_state_mutation_graph, validate_state_mutation_node
|
|
|
|
assert as_node in build_state_mutation_graph(as_node, "full").nodes
|
|
assert validate_state_mutation_node(as_node) == as_node
|
|
|
|
|
|
def test_sync_accessor_binds_persistence_guards_operations_and_preserves_input() -> None:
|
|
graph = FakeGraph()
|
|
saver = FakeCheckpointer()
|
|
store = object()
|
|
accessor = CheckpointStateAccessor.bind(graph, saver, store=store, mode="delta")
|
|
config = {
|
|
"configurable": {"thread_id": "thread-sync", "checkpoint_ns": ""},
|
|
"metadata": {"caller": "test"},
|
|
"tags": ["preserved"],
|
|
}
|
|
original = deepcopy(config)
|
|
|
|
snapshot = accessor.get(config)
|
|
history = accessor.history(config, limit=2)
|
|
update = accessor.update(config, {"messages": ["changed"]}, as_node="tools")
|
|
|
|
assert snapshot.values == {"messages": ["sync"]}
|
|
assert [item.values for item in history] == [{"index": 0}, {"index": 1}]
|
|
assert graph.sync_history_yields == 2
|
|
assert update == {"updated": {"messages": ["changed"]}, "as_node": "tools"}
|
|
assert graph.checkpointer is saver
|
|
assert graph.store is store
|
|
assert config == original
|
|
for call in graph.calls:
|
|
_assert_delta_config_is_copied(config, call[1])
|
|
assert graph.calls[-1][2:] == ({"messages": ["changed"]}, "tools")
|
|
|
|
|
|
@pytest.mark.anyio
|
|
async def test_async_accessor_binds_persistence_guards_operations_and_preserves_input() -> None:
|
|
graph = FakeGraph()
|
|
saver = FakeCheckpointer()
|
|
store = object()
|
|
accessor = CheckpointStateAccessor.bind(graph, saver, store=store, mode="delta")
|
|
config = {
|
|
"configurable": {"thread_id": "thread-async", "checkpoint_ns": ""},
|
|
"metadata": {"caller": "test"},
|
|
"tags": ["preserved"],
|
|
}
|
|
original = deepcopy(config)
|
|
|
|
snapshot = await accessor.aget(config)
|
|
history = await accessor.ahistory(config, limit=2)
|
|
update = await accessor.aupdate(config, {"messages": ["changed"]}, as_node="agent")
|
|
|
|
assert snapshot.values == {"messages": ["async"]}
|
|
assert [item.values for item in history] == [{"index": 0}, {"index": 1}]
|
|
assert graph.async_history_yields == 2
|
|
assert update == {"updated": {"messages": ["changed"]}, "as_node": "agent"}
|
|
assert graph.checkpointer is saver
|
|
assert graph.store is store
|
|
assert config == original
|
|
for call in graph.calls:
|
|
_assert_delta_config_is_copied(config, call[1])
|
|
assert graph.calls[-1][2:] == ({"messages": ["changed"]}, "agent")
|
|
|
|
|
|
@pytest.mark.anyio
|
|
async def test_async_accessor_reads_checkpoint_metadata_without_materializing_state() -> None:
|
|
graph = FakeGraph()
|
|
saver = FakeCheckpointer()
|
|
saver.checkpoint_tuple = SimpleNamespace(metadata={"deerflow_agent_name": "stateless-agent"})
|
|
accessor = CheckpointStateAccessor.bind(graph, saver, mode="delta")
|
|
config = {
|
|
"configurable": {"thread_id": "thread-metadata", "checkpoint_ns": ""},
|
|
"metadata": {"caller": "test"},
|
|
}
|
|
original = deepcopy(config)
|
|
|
|
metadata = await accessor.aget_metadata(config)
|
|
|
|
assert metadata == {"deerflow_agent_name": "stateless-agent"}
|
|
assert graph.calls == []
|
|
assert len(saver.async_configs) == 1
|
|
_assert_delta_config_is_copied(config, saver.async_configs[0])
|
|
assert config == original
|
|
|
|
|
|
@pytest.mark.anyio
|
|
async def test_full_accessor_metadata_read_rejects_delta_checkpoint() -> None:
|
|
from deerflow.runtime.checkpoint_mode import CheckpointModeMismatchError
|
|
|
|
graph = FakeGraph()
|
|
saver = FakeCheckpointer()
|
|
saver.checkpoint_tuple = SimpleNamespace(metadata={CHECKPOINT_MODE_METADATA_KEY: "delta"})
|
|
accessor = CheckpointStateAccessor.bind(graph, saver, mode="full")
|
|
|
|
with pytest.raises(CheckpointModeMismatchError, match="requires delta mode"):
|
|
await accessor.aget_metadata({"configurable": {"thread_id": "thread-delta"}})
|
|
|
|
assert graph.calls == []
|
|
|
|
|
|
def test_sync_history_zero_limit_guards_without_consuming_a_snapshot() -> None:
|
|
graph = FakeGraph()
|
|
saver = FakeCheckpointer()
|
|
accessor = CheckpointStateAccessor.bind(graph, saver)
|
|
config = {"configurable": {"thread_id": "thread-sync-zero"}}
|
|
|
|
assert accessor.history(config, limit=0) == []
|
|
# The read-side gate folds onto the returned snapshot: no standalone tuple fetch.
|
|
assert len(saver.sync_configs) == 0
|
|
assert graph.sync_history_yields == 0
|
|
|
|
|
|
@pytest.mark.anyio
|
|
async def test_async_history_zero_limit_guards_without_consuming_a_snapshot() -> None:
|
|
graph = FakeGraph()
|
|
saver = FakeCheckpointer()
|
|
accessor = CheckpointStateAccessor.bind(graph, saver)
|
|
config = {"configurable": {"thread_id": "thread-async-zero"}}
|
|
|
|
assert await accessor.ahistory(config, limit=0) == []
|
|
assert len(saver.async_configs) == 0
|
|
assert graph.async_history_yields == 0
|
|
|
|
|
|
@pytest.mark.anyio
|
|
async def test_full_accessor_gates_writes_and_checks_reads_on_the_returned_snapshot() -> None:
|
|
"""Full mode: only writes pay the pre-write tuple fetch; reads check the
|
|
marker on the materialized snapshot's metadata instead."""
|
|
graph = FakeGraph()
|
|
saver = FakeCheckpointer()
|
|
accessor = CheckpointStateAccessor.bind(graph, saver)
|
|
config = {"configurable": {"thread_id": "thread-full"}}
|
|
|
|
accessor.get(config)
|
|
accessor.history(config, limit=1)
|
|
accessor.update(config, {}, as_node=None)
|
|
await accessor.aget(config)
|
|
await accessor.ahistory(config, limit=1)
|
|
await accessor.aupdate(config, {}, as_node=None)
|
|
|
|
assert len(saver.sync_configs) == 1
|
|
assert len(saver.async_configs) == 1
|
|
for prepared in [*saver.sync_configs, *saver.async_configs]:
|
|
assert prepared["configurable"][INTERNAL_CHECKPOINT_MODE_KEY] == "full"
|
|
assert CHECKPOINT_MODE_METADATA_KEY not in prepared["metadata"]
|
|
assert config == {"configurable": {"thread_id": "thread-full"}}
|
|
|
|
|
|
@pytest.mark.anyio
|
|
async def test_full_accessor_raises_when_the_returned_snapshot_is_delta_marked() -> None:
|
|
"""A full-mode accessor must fail closed on a delta checkpoint, detected
|
|
via the returned snapshot metadata (no pre-read tuple fetch)."""
|
|
from deerflow.runtime.checkpoint_mode import CheckpointModeMismatchError
|
|
|
|
graph = FakeGraph()
|
|
saver = FakeCheckpointer()
|
|
accessor = CheckpointStateAccessor.bind(graph, saver, mode="full")
|
|
config = {"configurable": {"thread_id": "thread-delta-marked"}}
|
|
graph.get_state = lambda _config: SimpleNamespace(values={}, metadata={CHECKPOINT_MODE_METADATA_KEY: "delta"})
|
|
|
|
with pytest.raises(CheckpointModeMismatchError, match="requires delta mode"):
|
|
accessor.get(config)
|
|
assert len(saver.sync_configs) == 0
|
|
|
|
async def _delta_history(_config, *, limit=None):
|
|
yield SimpleNamespace(values={"index": 0}, metadata={})
|
|
yield SimpleNamespace(values={"index": 1}, metadata={CHECKPOINT_MODE_METADATA_KEY: "delta"})
|
|
|
|
graph.aget_state_history = _delta_history
|
|
with pytest.raises(CheckpointModeMismatchError, match="requires delta mode"):
|
|
await accessor.ahistory(config)
|
|
assert len(saver.async_configs) == 0
|
|
|
|
|
|
@pytest.mark.anyio
|
|
async def test_full_accessor_writes_still_check_compatibility_before_writing() -> None:
|
|
"""Writes cannot be un-applied, so the pre-write tuple fetch stays."""
|
|
from deerflow.runtime.checkpoint_mode import CheckpointModeMismatchError
|
|
|
|
graph = FakeGraph()
|
|
|
|
class DeltaMarkedSaver(FakeCheckpointer):
|
|
async def aget_tuple(self, config):
|
|
self.async_configs.append(config)
|
|
return SimpleNamespace(metadata={CHECKPOINT_MODE_METADATA_KEY: "delta"})
|
|
|
|
saver = DeltaMarkedSaver()
|
|
accessor = CheckpointStateAccessor.bind(graph, saver, mode="full")
|
|
config = {"configurable": {"thread_id": "thread-delta-write"}}
|
|
|
|
with pytest.raises(CheckpointModeMismatchError, match="requires delta mode"):
|
|
await accessor.aupdate(config, {"messages": []}, as_node=None)
|
|
assert len(saver.async_configs) == 1
|
|
assert graph.calls == []
|
|
|
|
|
|
class _CountingSaver(InMemorySaver):
|
|
"""InMemorySaver that counts checkpoint round-trips."""
|
|
|
|
def __init__(self) -> None:
|
|
super().__init__()
|
|
self.aget_tuple_calls = 0
|
|
self.alist_limits: list[int | None] = []
|
|
|
|
async def aget_tuple(self, config):
|
|
self.aget_tuple_calls += 1
|
|
return await super().aget_tuple(config)
|
|
|
|
async def alist(self, config, *, filter=None, before=None, limit=None):
|
|
self.alist_limits.append(limit)
|
|
async for item in super().alist(config, filter=filter, before=before, limit=limit):
|
|
yield item
|
|
|
|
|
|
def _build_counting_graph(saver):
|
|
from langchain_core.messages import HumanMessage
|
|
from langgraph.graph import StateGraph
|
|
|
|
class _State(TypedDict):
|
|
messages: Annotated[list[AnyMessage], add_messages]
|
|
|
|
async def _append(state):
|
|
return {"messages": [HumanMessage(content=f"turn-{len(state.get('messages') or [])}")]}
|
|
|
|
builder = StateGraph(_State)
|
|
builder.add_node("append", _append)
|
|
builder.set_entry_point("append")
|
|
builder.set_finish_point("append")
|
|
return builder.compile(checkpointer=saver)
|
|
|
|
|
|
@pytest.mark.anyio
|
|
async def test_ahistory_pushes_limit_into_alist_and_reads_each_snapshot_once() -> None:
|
|
"""The history limit must reach ``checkpointer.alist`` (SQL LIMIT), and the
|
|
read-side compat gate must not add a standalone tuple fetch per call."""
|
|
saver = _CountingSaver()
|
|
graph = _build_counting_graph(saver)
|
|
accessor = CheckpointStateAccessor.bind(graph, saver, mode="full")
|
|
config = {"configurable": {"thread_id": "thread-counted"}}
|
|
for _ in range(4):
|
|
await graph.ainvoke({}, config)
|
|
|
|
saver.aget_tuple_calls = 0
|
|
history = await accessor.ahistory(config, limit=2)
|
|
|
|
assert len(history) == 2
|
|
assert saver.alist_limits[-1] == 2
|
|
# get_state_history walks via alist only; no aget_tuple in the read path.
|
|
assert saver.aget_tuple_calls == 0
|
|
|
|
|
|
@pytest.mark.anyio
|
|
async def test_aget_fetches_the_checkpoint_exactly_once_in_full_mode() -> None:
|
|
"""Full-mode reads: one fetch inside aget_state; the folded gate adds none."""
|
|
saver = _CountingSaver()
|
|
graph = _build_counting_graph(saver)
|
|
accessor = CheckpointStateAccessor.bind(graph, saver, mode="full")
|
|
config = {"configurable": {"thread_id": "thread-counted-get"}}
|
|
await graph.ainvoke({}, config)
|
|
|
|
saver.aget_tuple_calls = 0
|
|
snapshot = await accessor.aget(config)
|
|
|
|
assert [message.content for message in snapshot.values["messages"]] == ["turn-0"]
|
|
assert saver.aget_tuple_calls == 1
|