docs.rs failed to build sunbeam-g2v-0.4.0
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

Visit the last successful build: sunbeam-g2v-0.3.3

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

cargo add sunbeam-g2v

#[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/ directory for a complete working service with multitenancy-aware auth, ReBAC permissions, and health checks.

Architecture

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"]

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

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

Integration tests

Integration tests live in tests/ and use testcontainers to spin up real Postgres, NATS, and OpenBao instances on demand. No manual docker compose is required.

# 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:

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.

License

MIT

sunbeam-g2v 0.4.0