brainos_httpadapter/lib.rs
1//! # Brain HTTP REST API Adapter
2//!
3//! Exposes Brain's signal processing pipeline over HTTP using axum.
4//!
5//! ## Routes
6//!
7//! Unauthenticated:
8//! - `GET /` — redirect to `/ui`
9//! - `GET /health` — liveness probe
10//! - `GET /metrics` — Prometheus-format counters
11//! - `GET /ui` — embedded memory explorer web UI
12//! - `GET /openapi.json` — OpenAPI 3.0 specification
13//! - `GET /api` — Swagger UI
14//!
15//! Authenticated (`Authorization: Bearer <api-key>`):
16//! - `POST /v1/signals` — submit a signal *(scope: write)*
17//! - `GET /v1/signals/:id` — retrieve cached signal response *(scope: read)*
18//! - `POST /v1/memory/search` — semantic search over stored facts *(scope: read)*
19//! - `GET /v1/memory/facts` — paginated fact list *(scope: read)*
20//! - `GET /v1/memory/namespaces` — list namespaces with counts *(scope: read)*
21//! - `GET /v1/memory/export` — full memory export *(scope: export)*
22//! - `POST /v1/memory/import` — import facts/episodes *(scope: write)*
23//! - `GET /v1/schedules` — list scheduled intents *(scope: read)*
24//! - `DELETE /v1/schedules/:id` — cancel a scheduled intent *(scope: write)*
25//! - `GET /v1/events` — SSE stream of signal/notification/brain events *(scope: read)*
26//! - `POST /v1/webhooks/:id` — inbound webhook delivery *(scope: write — or a configured signature verifier in lieu of Bearer auth)*
27//!
28//! ## Authentication
29//!
30//! A random API key is generated on `brain init` and printed to stdout.
31//! Configure additional keys (and their permission scopes) under
32//! `access.api_keys[]` in the config; `admin` is treated as an implicit
33//! superset of every other scope. Webhook endpoints accept a verifier
34//! (HMAC or Ed25519) as an alternative to Bearer auth — see
35//! `adapters.http.webhook_verifiers` in the config.
36
37pub mod auth;
38pub mod handlers;
39pub mod metrics;
40pub mod middleware;
41pub mod server;
42pub mod state;
43pub mod types;
44pub mod validate;
45
46// Re-export primary public types for convenience.
47pub use server::{create_router, serve};
48pub use state::AppState;
49pub use types::HttpAdapterError;
50
51#[cfg(test)]
52mod tests;