mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-11-20 11:20:35 +00:00
* feat(sharing): add revocable read-only conversation snapshots * fix(sharing): preserve fork idempotency and allow snapshot cleanup
103 lines
6.0 KiB
Markdown
103 lines
6.0 KiB
Markdown
# Gateway API (`app/gateway/`)
|
|
|
|
The FastAPI application on port 8001. It serves the REST API, embeds the
|
|
LangGraph-compatible agent runtime, and owns auth, CSRF, run admission and thread
|
|
lifecycle. Route-level rules are in [routers/AGENTS.md](routers/AGENTS.md). The
|
|
endpoint list is the OpenAPI schema at `/docs`; [API.md](../../docs/API.md)
|
|
describes it for humans.
|
|
|
|
## Verify
|
|
|
|
```bash
|
|
cd backend
|
|
python -m pytest tests -q -k "gateway or router or auth or run_manager"
|
|
make test-blocking-io # request handlers share one event loop
|
|
```
|
|
|
|
Read these contracts before you change the matching area:
|
|
[thread lifecycle](../../docs/THREAD_LIFECYCLE.md) (branch, regenerate, edit
|
|
replay, archive), [run event stream](../../docs/RUN_EVENT_STREAM.md),
|
|
[run interaction policy](../../docs/RUN_INTERACTION_POLICY.md),
|
|
[auth design](../../docs/AUTH_DESIGN.md), [knowledge](../../docs/KNOWLEDGE.md).
|
|
|
|
## Trust boundary
|
|
|
|
- **Share tokens read only frozen snapshots.** See [sharing](../../../docs/guide/sharing.md).
|
|
- **Server-owned run context.** A client can send run context in `body.context`
|
|
and in `body.config`. Admit server-owned keys only from internally authenticated
|
|
callers and strip them from both places for everyone else. When you add a
|
|
server-owned key, add it to that strip list in the same change.
|
|
- **Server-owned state.** Reject thread state fields that only the server may write
|
|
(sandbox, thread data, viewed images, goal outcome) and reserved metadata keys
|
|
when they come from a client. External run input cannot carry system or developer
|
|
messages.
|
|
- **Owner scoping.** Run-history helpers default to the request user and fail
|
|
closed when there is no user context. Pass `user_id=None` only in migration or
|
|
admin code that needs an unscoped read, and say why at the call site.
|
|
- **Thread IDs become paths.** Validate every caller-provided thread ID with
|
|
`deerflow.utils.thread_id` before it reaches persistence or the filesystem.
|
|
Legacy IDs stay readable and deletable, but they are never interpolated into a
|
|
host path.
|
|
- **Shared decisions.** Route permissions, model use and skill visibility are each
|
|
decided in one helper in `authz.py`. HTTP routes, decorator-only auth and the
|
|
Live Browser WebSocket all call it. A new entry point calls the same helper so
|
|
that it cannot drift from the others.
|
|
- **Tokens and cookies.** A request with an invalid Bearer token gets 401 and never
|
|
falls back to the session cookie; the CSRF middleware skips Bearer requests and
|
|
relies on this. Personal access tokens work only on allowlisted routes.
|
|
- **Proxy headers.** "Is this localhost" decisions use the direct `Host` header.
|
|
Forwarded headers are client-controlled unless the outer proxy replaces them.
|
|
- **Untrusted remote text.** MCP notifications and other remote events reach the
|
|
model framed as untrusted data, outside the trusted instruction.
|
|
|
|
## Runs and threads
|
|
|
|
- **One writer per thread.** A run, a checkpoint write, an artifact write, a branch
|
|
and a delete are all thread operations that share one durable uniqueness
|
|
constraint. Reserve through `RunManager.reserve_thread_operation()` or
|
|
`services.reserve_checkpoint_write()`. A separate lock would let two workers
|
|
write the same thread. Outside run execution, checkpoint mutations — manual
|
|
compaction, `POST /threads/{id}/state`, both goal routes (`PUT` / `DELETE
|
|
/threads/{id}/goal`), and the `/goal from-chat` save (`POST
|
|
/threads/{id}/goal/from-chat`) — use `services.reserve_checkpoint_write()`.
|
|
`PUT /goal` creates a missing checkpoint; from-chat does not. From-chat
|
|
saves with `expected_checkpoint_id` pinned to the head its synthesis read:
|
|
a write that landed during the model call rejects the stale objective
|
|
instead of clobbering the newer state, and the model call itself passes the
|
|
same `authorize_model_use` admission as the suggestions route.
|
|
- **Several workers.** In-memory run records exist only on the worker that owns the
|
|
run. Cancel, takeover and orphan recovery are compare-and-set operations on the
|
|
run store; use the store's claim and cancel primitives so that a lease renewal
|
|
between your read and your write is not overwritten. Multi-worker deployments
|
|
need `run_events.backend: db`.
|
|
- **Idempotency keys.** Scope an external `Idempotency-Key` to its owner and thread
|
|
before it reaches `RunManager`; the manager's index is process-wide.
|
|
- **`/wait` on a reused run** returns the durable run status and error. The latest
|
|
thread checkpoint can belong to a different run.
|
|
- **Stream gaps.** Stream bridges keep a bounded buffer. A client that asks for
|
|
events older than the buffer receives a `gap` event and the run continues.
|
|
- **`Content-Location` must stay CORS-exposed.** Run-creating routes return the run
|
|
ID in that header and the LangGraph SDK reads it from there only.
|
|
- **Run event contract.** Producer code, `deerflow/constants.py`, the event
|
|
catalog, `contracts/run_event_stream_contract.json` and
|
|
`docs/RUN_EVENT_STREAM.md` change together.
|
|
- **Thread membership in a project** is written by thread creation, branching and
|
|
the explicit move route. Run admission reads it and never changes it.
|
|
|
|
## Lifecycle
|
|
|
|
- **Probe file-backed managed subagent storage once during startup, off the
|
|
event loop.** Probe failures warn operators before their first create request;
|
|
atomic create stays fail-closed rather than falling back to an overwrite.
|
|
- **Shutdown order matters.** `lifespan` drains runs and extensions first, then
|
|
closes MCP, then shuts the sandbox provider down off the event loop. Cleanup code
|
|
keeps running after cancellation, allocates nothing new, and logs failures
|
|
instead of raising.
|
|
- **Persistent writes in routers** go through
|
|
`app.gateway.persistent_writes.run_drained_write` so that a client disconnect
|
|
cannot leave a half-written file.
|
|
- **LangGraph Studio.** `langgraph_studio.py` is loaded by LangGraph's file loader
|
|
before the runtime starts and without a `sys.modules` entry. Keep its
|
|
annotations eager, and identify Studio callers by the upstream `StudioUser`
|
|
type, because the identity string can be reused by any client.
|