turul_a2a/lib.rs
1//! A2A Protocol v1.0 server framework.
2//!
3//! `turul-a2a` provides the server side of the [A2A
4//! Protocol](https://github.com/a2aproject/A2A): a typed
5//! [`executor::AgentExecutor`] trait, HTTP + JSON-RPC transports, Server-Sent
6//! Events streaming, and a storage abstraction with four backends
7//! (in-memory, SQLite, PostgreSQL, DynamoDB) — all proto-normative per
8//! `proto/a2a.proto`.
9//!
10//! # Quick start
11//!
12//! See the `examples/echo-agent` crate for a runnable end-to-end example.
13//! A minimal executor implements [`executor::AgentExecutor`] and is passed to
14//! [`A2aServer::builder()`]:
15//!
16//! ```text
17//! let server = A2aServer::builder()
18//! .executor(MyExecutor)
19//! .bind(([0, 0, 0, 0], 3000))
20//! .build()?;
21//! server.run().await?;
22//! ```
23//!
24//! # Feature flags
25//!
26//! - `in-memory` (default) — volatile in-process storage
27//! - `sqlite` — SQLx SQLite backend (atomic task+event writes)
28//! - `postgres` — SQLx PostgreSQL backend
29//! - `dynamodb` — AWS DynamoDB backend with TTL
30//! - `compat-v03` — opt-in compatibility shim for a2a-sdk 0.3.x clients
31//! (method name normalization, root POST route, optional `A2A-Version`
32//! header). Canonical builds are v1.0 strict.
33//!
34//! # Durable event coordination
35//!
36//! Task state and streaming events are written atomically via
37//! [`storage::A2aAtomicStore`]. The in-process event broker is a local
38//! wake-up signal; the storage backend is the source of truth. Subscribers
39//! attached while a task is non-terminal receive replay of prior events and
40//! then live delivery, supporting `Last-Event-ID` reconnection across
41//! instances when the same backend is used (e.g., shared DynamoDB or
42//! PostgreSQL). Subscribing to an already-terminal task returns
43//! `UnsupportedOperationError` per A2A v1.0 §3.1.6 — use [`storage`] or
44//! `GetTask` to retrieve the final state.
45//!
46//! # Multi-instance streaming
47//!
48//! The in-process [`streaming`] broker fans out to clients on the same
49//! process only. Cross-instance streaming relies on the shared durable event
50//! store for replay. For horizontally scaled deployments, configure all
51//! instances against the same backend.
52
53pub mod card_builder;
54#[cfg(feature = "compat-v03")]
55pub mod compat_v03;
56pub mod durable_executor;
57pub mod error;
58pub mod event_sink;
59pub mod executor;
60#[cfg(feature = "grpc")]
61pub mod grpc;
62pub mod jsonrpc;
63pub mod middleware;
64pub mod prelude;
65pub mod push;
66pub mod router;
67pub mod server;
68pub mod storage;
69pub mod streaming;
70
71pub use server::A2aServer;