sunbeam-g2v 0.3.0

Sunbeam Service Framework - A ConnectRPC-based framework for building microservices
Documentation 
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

# sunbeam-g2v

A ConnectRPC-based framework for building microservices in Rust.

## Features

- **Service trait** — `SunbeamService` with `on_start`/`on_stop` hooks and graceful shutdown
- **Configuration** — Figment-based config with env-var support via `ServiceConfig`
- **Server builders** — `ServerBuilder` → `AxumServer` (or `StandaloneServer`) with one-shot `serve()`
- **Middleware stack** — JWT validation, Keto authorization, Prometheus metrics, request IDs, logging, tracing, panic recovery
- **Database** — SQLx Postgres integration with `connect`/`connect_eager` and automatic migrations
- **Message queue** — NATS / JetStream wrapper (`NatsClient`) with stream and consumer helpers
- **Leader election** — Pluggable `LeaderElection` trait with Vault and NATS implementations
- **Client resiliency** — `ClientFactory`, `RetryLayer`/`RetryPolicy`, and a full `CircuitBreaker`
- **Health checks** — `HealthRouter` exposing `/health/live` and `/health/ready`
- **Testing** — `TestHarness` (boots a real server on a random port), `MockService`, data fixtures
- **Proc-macros** — `#[derive(Instrumented)]` and `#[derive(Metrics)]`

## Quick start

```bash
cargo add sunbeam-g2v
```

```rust,no_run
#[cfg(feature = "axum")]
{
    use sunbeam_g2v::prelude::*;

    #[tokio::main]
    async fn main() -> ServiceResult<()> {
        let router = ServiceRouter::new();
        ServerBuilder::new()
            .with_router(router)
            .serve()
            .await
    }
}
```

See the [`examples/`](examples/) directory for a complete working service with JWT, Keto, and health checks.

## Architecture

```mermaid
flowchart LR
    A["ServerBuilder"] --> B["with_router"]
    B --> C["with_health"]
    C --> D["with_config"]
    D --> E["build_axum"]
    E --> F["AxumServer"]
    F --> G["serve"]
```

```mermaid
graph TB
    subgraph Middleware
        direction LR
        H["RequestIdLayer"] --> I["JwtLayer"]
        I --> J["KetoLayer"]
        J --> K["InstrumentationLayer"]
        K --> L["LoggingLayer"]
        L --> M["TracingLayer"]
        M --> N["CatchPanicLayer"]
    end
```

## Feature flags

| Feature | Description |
|---------|-------------|
| `axum` | Axum server integration (default) |
| `standalone` | Hyper standalone server |
| `sqlx` / `sqlx-postgres` | Database connectivity |
| `nats` | NATS / JetStream messaging |
| `redis` | Redis client |
| `jwt` | JWT validation middleware |
| `keto` | Ory Keto authorization |
| `vault` | HashiCorp Vault integration |
| `election` | Leader election (requires `vault` + `nats`) |
| `metrics` | Prometheus metrics |
| `tracing` | OpenTelemetry tracing |
| `logging` | tracing-subscriber logging |
| `tls` | TLS support |
| `all` | Every feature listed above |

Default features enable: `axum`, `metrics`, `tracing`, `logging`, `sqlx`, `sqlx-postgres`, `nats`, `jwt`, `keto`, `vault`, `election`.

### Minimal dependencies

```toml
[dependencies]
sunbeam-g2v = { version = "0.2", default-features = false, features = ["axum", "metrics", "jwt"] }
```

## API Reference

Full API docs are published to [docs.rs/sunbeam-g2v](https://docs.rs/sunbeam-g2v).

## License

MIT