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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
//! # tonin
//!
//! **The one-person framework for Kubernetes microservices.**
//!
//! `tonin` is an opinionated framework designed to handle the entire lifecycle of a Kubernetes
//! microservice — from protocol buffers and gRPC routing to containerization, Helm chart rendering,
//! OpenTelemetry telemetry, and LLM-callable MCP tool exposure — all controlled from a single
//! declarative `tonin.toml`.
//!
//! ---
//!
//! ## Crate Architecture
//!
//! The `tonin` ecosystem is split across specialized crates:
//!
//! * **`tonin`** (this crate) — The umbrella CLI binary. Installs the `tonin` command to scaffold
//! services (`tonin service new`), compile protocols, and deploy using Helm (`tonin helm`). It has
//! no runtime API.
//! * **[`tonin-sdk`](https://docs.rs/tonin-sdk)** — The runtime framework. Provides the `Service`
//! builder, capability interfaces (database, cache, events), JWT auth, and OTel telemetry.
//! * **[`tonin-client`](https://docs.rs/tonin-client)** — Peer-service client transport, retry policies,
//! circuit breaking, and trace propagation without full server dependencies.
//! * **[`tonin-build`](https://docs.rs/tonin-build)** — `build.rs` compile helper wrapping `tonic-build`.
//!
//! ---
//!
//! ## The CLI Workflow (`tonin` binary)
//!
//! To get a running, instrumented, mesh-secured gRPC service deployed to Kubernetes:
//!
//! ```bash
//! # 1. Scaffold a new service from built-in templates
//! tonin service new greeter --lang rust
//! cd greeter
//!
//! # 2. Run locally (boots gRPC server on :50051 + MCP tool sidecar on :50052)
//! cargo run
//!
//! # 3. Generate Helm chart templates based on tonin.toml
//! tonin helm generate
//!
//! # 4. Deploy to Kubernetes (performs 'helm upgrade --install')
//! tonin helm upgrade --env prod
//! ```
//!
//! ---
//!
//! ## Declarative Configuration (`tonin.toml`)
//!
//! Every infrastructure decision (replicas, security context, databases, caches, mesh ingress policies)
//! is declared in a single file at the root of your service:
//!
//! ```toml
//! [service]
//! name = "greeter"
//! version = "0.7.8"
//!
//! [deploy]
//! replicas = 2
//! mesh = "cilium" # auto-generates CiliumNetworkPolicies
//! namespace = "default"
//! mcp_sidecar = true # auto-exposes gRPC routes as LLM tools
//!
//! [database]
//! engine = "postgres" # auto-provisions and injects Postgres
//! size = "10Gi"
//!
//! [cache]
//! engine = "redis" # auto-provisions Redis StatefulSet
//! ```
//!
//! ---
//!
//! ## Writing a Service (`tonin-sdk`)
//!
//! Services use the **`tonin-sdk`** crate to implement their handlers. Below is a complete
//! guide showing how to implement a gRPC trait, access database pools, extract user authentication,
//! and call other services.
//!
//! ### 1. Implementing a gRPC Handler (with Auth & DB State)
//!
//! Handlers are standard Rust structs that implement gRPC traits generated by `tonic` (`prost`).
//! You can access database connections and client pools directly from the `State` bundle, and read
//! the request's JWT authentication context using task-locals.
//!
//! ```rust,ignore
//! use tonin_sdk::prelude::*;
//! use greeter_server::gen::greeter_v1_server::{Greeter, GreeterServer};
//! use greeter_server::gen::{HelloRequest, HelloReply};
//!
//! #[derive(Clone)]
//! struct GreeterImpl {
//! // Store the pre-wired database pool
//! db: sqlx::PgPool,
//! }
//!
//! #[async_trait]
//! impl Greeter for GreeterImpl {
//! async fn say_hello(
//! &self,
//! req: Request<HelloRequest>
//! ) -> Result<Response<HelloReply>, Status> {
//! // 1. Retrieve the task-local JWT authentication context
//! let auth = tonin_sdk::auth::current();
//! if !auth.is_authenticated() {
//! return Err(Status::unauthenticated("missing or invalid token"));
//! }
//!
//! // Access user identification principal
//! let user_id = auth.principal_id();
//! tracing::info!(?user_id, "serving authenticated gRPC request");
//!
//! // 2. Perform raw database queries using sqlx (connection managed by state)
//! let username: String = sqlx::query_scalar("SELECT name FROM users WHERE id = $1")
//! .bind(user_id)
//! .fetch_one(&self.db)
//! .await
//! .map_err(|e| Status::internal(e.to_string()))?;
//!
//! Ok(Response::new(HelloReply {
//! message: format!("Hello, {}!", username),
//! }))
//! }
//! }
//! ```
//!
//! ### 2. Bootstrapping and Starting the Service
//!
//! In your `main.rs`, initialize the connection state from the environment, register your gRPC
//! handlers, and spin up the runtime listener:
//!
//! ```rust,ignore
//! #[tokio::main]
//! async fn main() -> Result<(), tonin_sdk::Error> {
//! // Construct DB/Cache pools automatically from environment variables
//! let state = State::from_env().await?;
//!
//! let handler = GreeterImpl {
//! db: state.pg()?.clone(),
//! };
//!
//! // Service handles OTel tracing, logging, and graceful shutdown automatically
//! Service::new("greeter")
//! .with_auth(tonin_sdk::auth::default_verifier())
//! .handler(GreeterServer::new(handler))
//! .run()
//! .await
//! }
//! ```
//!
//! ### 3. Outbound Calls to Peer Services (Service Discovery)
//!
//! To call another service in the cluster, use `tonin_sdk::discovery::service_url` to resolve the
//! Kubernetes DNS route. The service mesh automatically handles mTLS encryption, load-balancing, and retries.
//!
//! ```rust,ignore
//! use greeter_client::gen::greeter_v1_client::GreeterClient;
//!
//! async fn call_greeter() -> Result<(), tonin_sdk::Error> {
//! // Resolves to http://greeter.default.svc.cluster.local:50051
//! let url = tonin_sdk::discovery::service_url("greeter", "default");
//!
//! let mut client = GreeterClient::connect(url).await?;
//! let response = client.say_hello(HelloRequest { name: "Alice".into() }).await?;
//!
//! println!("Received: {:?}", response.into_inner().message);
//! Ok(())
//! }
//! ```
//!
//! ---
//!
//! ## Core Features
//!
//! `tonin` simplifies distributed application development by providing built-in implementations of key microservice patterns:
//!
//! * **gRPC Server & Routing**: Built on top of `tonic`, providing standard server scaffolding,
//! graceful shutdown, and automated client stub generation. Services can also expose a parallel HTTP
//! port for metrics, health checks, or REST endpoints.
//! * **Model Context Protocol (MCP)**: Every service can act as an MCP tool host. By adding the `#[mcp_expose]`
//! attribute to your gRPC implementation, methods are automatically parsed into JSON schemas and served
//! by a sidecar on port `50052`, allowing LLMs to invoke them natively.
//! * **Telemetry & Observability**: Integrated OpenTelemetry (OTel) tracing and structured logging.
//! W3C trace context is automatically extracted from incoming gRPC metadata and injected into outbound
//! calls to maintain distributed request chains.
//! * **Authentication & Zero-Trust**: Structured token verifiers handle header extraction, JWT signature validation,
//! and JWKS keyset loading. The resulting user context is stored as a thread/task-local `AuthCtx`, allowing any
//! inner library code to query user claims safely.
//! * **Pre-Wired Connection State**: Boot-time env variables (`DATABASE_URL`, `REDIS_URL`, etc.) are parsed,
//! validated, and connected to eagerly. The resulting `PgPool` or `redis::Client` is stored inside the reference-counted
//! `State` struct.
//! * **Service Discovery**: The framework provides simple helper functions to compile cluster-native DNS routes
//! (e.g., `<service>.<namespace>.svc.cluster.local`) for peer-to-peer communication.
//! * **Outbound Proxy Sidecar (`tonin-proxy`)**: For services not written in Rust, the `tonin-proxy` sidecar
//! implements request coalescing (singleflight), response caching, circuit breaking, and backoff retries.
//!
//! For more details, read the [conceptual guides](https://github.com/Rushit/tonin/tree/main/docs)
//! or view the end-to-end example at [`examples/greeter`](https://github.com/Rushit/tonin/tree/main/examples/greeter).