sunbeam-g2v 0.4.0

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

# 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** — multitenancy-aware auth (API key / Kratos session / tenant header), ReBAC permission enforcement, 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, integration tests backed by `testcontainers`
- **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 multitenancy-aware auth, ReBAC permissions, 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["auth_middleware"]
        I --> J["PermissionLayer"]
        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 |
| `auth` | Multitenancy-aware authn/authz (API keys, Kratos sessions, ReBAC permissions) |
| `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`, `auth`, `vault`, `election`.

### Minimal dependencies

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

## Integration tests

Integration tests live in `tests/` and use [`testcontainers`](https://crates.io/crates/testcontainers) to spin up real Postgres, NATS, and OpenBao instances on demand. No manual `docker compose` is required.

```bash
# Run all integration tests
cargo test -p sunbeam-g2v --test db_integration -- --nocapture --test-threads=1
cargo test -p sunbeam-g2v --test health_integration -- --nocapture --test-threads=1
cargo test -p sunbeam-g2v --test nats_integration -- --nocapture --test-threads=1
cargo test -p sunbeam-g2v --test election_nats_integration -- --nocapture --test-threads=1
cargo test -p sunbeam-g2v --test election_vault_integration -- --nocapture --test-threads=1
```

To run against existing services instead, set the standard environment variables:

```bash
DATABASE_URL=postgres://user:pass@host:5432/db \
NATS_URL=nats://host:4222 \
VAULT_ADDR=http://host:8200 \
VAULT_TOKEN=root \
cargo test -p sunbeam-g2v --test db_integration -- --nocapture --test-threads=1
```

Container images can be overridden via:

- `SUNBEAM_TEST_POSTGRES_IMAGE` (default `postgres:17-alpine`)
- `SUNBEAM_TEST_NATS_IMAGE` (default `nats:2.10-alpine`)
- `SUNBEAM_TEST_OPENBAO_IMAGE` (default `openbao/openbao:2.5.1`)

## API Reference

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

## License

MIT