1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
//! Senu: declare a function once and serve it as a web page, a JSON API and
//! an MCP tool.
//!
//! An [`operation::Operation`] is a read-only function over your state with
//! a name, a description, a permission and its string parameters. You list
//! it in an [`http::Endpoints`] table and in an MCP tool list; Senu's
//! adapters then do the same steps for every route and tool, in the same
//! order: size limits, the method, authentication, the permission, the
//! parameter envelope, your function, and the error mapping. Declaring an
//! operation exposes nothing: only what you list is reachable.
//!
//! ```
//! use senu::auth::{Bearer, Secret};
//! use senu::http::{AppState, Endpoints};
//! use senu::mcp::{self, McpServer};
//! use senu::operation::{
//! Args, OpError, Operation, Param, Permission, Principal, Run, TenantId, decode,
//! };
//!
//! // Your state, your permission and your function.
//! struct Stock(Vec<(&'static str, u32)>);
//!
//! const VIEW_STOCK: Permission = Permission::new("view_stock");
//!
//! #[derive(serde::Deserialize)]
//! #[serde(deny_unknown_fields)]
//! struct StockArgs {
//! sku: String,
//! }
//!
//! #[derive(serde::Serialize)]
//! struct Level {
//! sku: String,
//! units: u32,
//! }
//!
//! fn get_stock(stock: &Stock, _caller: &Principal, args: &Args) -> Result<Level, OpError> {
//! let StockArgs { sku } = decode(args)?;
//! let (sku, units) = stock.0.iter().find(|(known, _)| *known == sku).ok_or(OpError::NotFound)?;
//! Ok(Level { sku: (*sku).to_owned(), units: *units })
//! }
//!
//! // The declaration: nothing is exposed yet.
//! const GET_STOCK: Operation<Stock, Level> = Operation {
//! name: "get_stock",
//! description: "Units in stock for one SKU.",
//! permission: VIEW_STOCK,
//! params: &[Param::required("sku", "The SKU, such as SKU-1.")],
//! run: Run::Sync(get_stock),
//! };
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // A JSON route behind a Bearer token. `router` is an `axum::Router`.
//! let clerk = Principal::new("clerk", TenantId::from_static("main"), &[VIEW_STOCK]);
//! let state = AppState::builder(Stock(vec![("SKU-1", 12)]))
//! .api_auth(Bearer::new(Secret::new("a-long-random-token")?, clerk.clone()))
//! .build();
//! let router = Endpoints::new().api("/api/stock", &GET_STOCK).into_router(state)?;
//!
//! // The same operation as an MCP tool.
//! let server = McpServer::with_tools(Stock(vec![("SKU-1", 12)]), clerk, vec![mcp::tool(&GET_STOCK)])?;
//! # let _ = (router, server);
//! # Ok(())
//! # }
//! ```
//!
//! # Modules
//!
//! - [`operation`]: `Operation`, `Principal`, `Permission`, `OpError`.
//! - [`auth`]: the [`auth::Authenticate`] trait and the built-in Basic and
//! Bearer authenticators.
//! - [`http`]: the route table and the Axum router.
//! - [`mcp`]: the tool list and the stdio server.
//! - `contract` (feature `contract`): Senu's contract tests as a kit that
//! you run over your own routes and tools.
//!
//! # Features
//!
//! - `demo` (default): the catalogue demo, the `senu` binary and the article
//! site that holds the beginner course. A library user turns it off with
//! `default-features = false`.
//! - `contract`: the test kit. Enable it in `[dev-dependencies]`.
//!
//! # Limits
//!
//! Operations are read-only and served by `GET`; parameters are strings;
//! paths are exact. MCP runs over stdio. Writes, MCP over HTTP, sessions and
//! OAuth are not part of this version. Senu is not audited security
//! software; read `SECURITY.md` before you rely on it.
// The modules behind `demo` are the application and the course, not the
// library's API, so `missing_docs` is not required of them.