Sunbeam Service Framework (g2v)

A ConnectRPC-based framework for building microservices in Rust. The name is the Sun's spectral classification (G2V — main-sequence yellow dwarf), not a backronym.

The TypeScript client (@sunbeam/g2v) moved out of this repository and now lives in the sdk repo at sdk/typescript/. This repository is the Rust framework.

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 (bearer token / session cookie / session token), ReBAC permission enforcement, Prometheus metrics, panic recovery
• Request tracing — x-request-id honored/generated/echoed on every request and OpenTelemetry server spans with W3C trace-context propagation, both applied by default
• Observability bootstrap — telemetry::init wires tracing spans into OpenTelemetry and exports OTLP/HTTP to a collector
• 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 — unified HTTP client with retry (incl. opt-in 401 refresh), circuit breaker, cache, and automatic x-request-id / trace-context propagation
• 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 the sdk's testcontainer builders
• Proc-macros — #[derive(Instrumented)] and #[derive(Metrics)]

Quick Start

cargo add sunbeam-g2v

use sunbeam_g2v::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Optional: export traces when OTEL_EXPORTER_OTLP_ENDPOINT is set.
    let _telemetry = sunbeam_g2v::telemetry::init(Default::default())?;

    let router = ServiceRouter::new();
    ServerBuilder::new()
        .with_router(router)
        .serve()
        .await?;
    Ok(())
}

Example

cargo run --example simple

The example exposes public, authenticated, and permission-authorized routes plus a ConnectRPC Eliza service; see examples/simple/main.rs.

Repository Layout

.
├── src/                  # sunbeam-g2v crate source
├── sunbeam-g2v-derive/   # proc-macro crate (Instrumented, Metrics derives)
├── tests/                # integration tests (sdk testcontainer builders)
├── examples/             # runnable examples
├── proto/                # protobuf definitions
└── docs/                 # guides and architecture docs

Documentation

• Getting Started
• Architecture
• Contributing
• Security

License

MIT — see LICENSE.md.