evento_remote/lib.rs
1//! Client/server remote executor for evento.
2//!
3//! Splits an evento application from its event store across a network boundary:
4//!
5//! - [`serve`] exposes **any** [`Executor`](evento_core::Executor) (Sql, Fjall,
6//! Accord, …) over length-delimited framed TCP.
7//! - [`Client`] implements [`Executor`](evento_core::Executor) by forwarding
8//! every call to a server, so `evento::create`, projections, and
9//! subscriptions work unchanged against a remote store.
10//!
11//! ```rust,no_run
12//! # async fn run() -> anyhow::Result<()> {
13//! // Server process: serve an existing executor.
14//! let executor = evento_fjall::Fjall::open("./data")?;
15//! let listener = tokio::net::TcpListener::bind("0.0.0.0:4321").await?;
16//! let handle = evento_remote::serve(listener, executor);
17//!
18//! // Client process: connect and use like any executor.
19//! let client = evento_remote::Client::connect("127.0.0.1:4321").await?;
20//! # let _ = (handle, client);
21//! # Ok(())
22//! # }
23//! ```
24//!
25//! A client-side subscription registers what it follows with the server and
26//! is pushed a notification for the writes that hold an event it would read,
27//! so it wakes with the same low latency as over a local `write_watch_for`,
28//! and a write wakes no subscription that does not follow it. The server's `stable_timestamp` watermark
29//! piggybacks on every frame, so fronting a replicated backend (Accord) keeps
30//! subscription safety intact.
31//!
32//! **Credentials, tenants.** A host authenticating its clients implements
33//! [`Resolver`]: each connection opens with a `Hello` carrying the token the
34//! client was built with ([`ClientBuilder::token`]), and the resolver answers
35//! with the [`Session`] to serve it — the executor, something to keep alive
36//! for the connection's lifetime, a signal to end it (a revoked credential) —
37//! or a [`Rejection`]. [`serve_with`] takes the resolver; [`serve`] is the open
38//! single-store case.
39//!
40//! Which tenant a client belongs to is the host application's decision — its
41//! resolver maps the token (an API key, say) to one. To confine the client to
42//! that tenant over a store shared by every tenant, serve the connection in it,
43//! `Session::new(store.clone()).tenant(tenant)?` ([`Session::tenant`]): every
44//! request then acts in that tenant whatever it names — what it reads and
45//! loads, the tenant its writes are stamped with — and `replicate` and the
46//! subscriber calls are refused, so the client never reaches another tenant's
47//! data. The client itself stays tenant-agnostic: the events it reads come
48//! back in the default tenant, as from a store of its own, and a tenant
49//! application following the store through a `Sidecar` (evento-core's `rw`
50//! feature) keeps its subscriptions' cursors and its snapshots in its own
51//! store. The write notifications follow the session too: a client serving a
52//! tenant is told of that tenant's writes, never of when or how often the
53//! rest of the store is written.
54//!
55//! **Addresses.** A client names its server by an [`Address`]: an IP and port,
56//! or a `host:port` looked up again on every connection attempt, so a
57//! reconnect follows a load balancer or a DNS (geo-)failover to whichever node
58//! now answers. Each server bounds a subscription's read by its own stability
59//! watermark, so a client reconnecting to a node that is further behind never
60//! skips events.
61//!
62//! **TLS.** [`serve_tls`] / [`serve_tls_with`] complete a rustls handshake
63//! on each connection (the operator supplies the `TlsAcceptor`), and
64//! [`ClientBuilder::tls`] the matching connector, mirroring `evento-cluster`'s
65//! `serve`/`serve_tls` split. Plain TCP stays for trusted networks: a token
66//! then travels in clear text.
67
68mod client;
69mod server;
70mod wire;
71
72pub use client::{Address, Client, ClientBuilder};
73pub use server::{
74 serve, serve_tls, serve_tls_with, serve_with, Hello, Resolver, ServerHandle, Session,
75};
76pub use wire::Rejection;