Struct ServiceBootstrap 

pub struct ServiceBootstrap { /* private fields */ }

Builder for a microservice runtime.

use socle::{ServiceBootstrap, BootstrapCtx, Result};
use axum::{Router, routing::get};

ServiceBootstrap::new("my-service")
    .with_telemetry()
    .with_router(|_ctx: &BootstrapCtx| Router::new().route("/health", get(|| async { "ok" })))
    .serve("0.0.0.0:8080")
    .await

Implementations

impl ServiceBootstrap

pub fn new(service_name: impl Into<Arc<str>>) -> Self

Start a new bootstrap for a service.

pub fn with_dotenv(self) -> Self

Load .env file if present. Call this before any with_* methods that read from environment variables.

pub fn from_config( service_name: impl Into<Arc<str>>, cfg: BootstrapConfig, ) -> Result<Self>

Build from a BootstrapConfig.

pub async fn run(self) -> Result<()>

Run using the bind address loaded from BootstrapConfig.

pub fn with_body_limit(self, bytes: usize) -> Self

Override the maximum request body size in bytes. Defaults to 2 MiB.

pub fn with_shutdown_timeout(self, timeout: Duration) -> Self

Hard deadline on graceful shutdown drain. Defaults to 30 seconds.

pub fn with_shutdown_hook<F, Fut>( self, name: impl Into<String>, timeout: Duration, hook: F, ) -> Self

where F: Fn() -> Fut + Send + Sync + 'static, Fut: Future<Output = ()> + Send + 'static,

Register an async drain callback that runs after the HTTP server stops.

pub fn with_readiness_check<F, Fut>( self, name: impl Into<String>, check: F, ) -> Self

where F: Fn() -> Fut + Send + Sync + 'static, Fut: Future<Output = HealthCheck> + Send + 'static,

Register a readiness check.

pub fn with_health_probe(self, probe: impl HealthProbe + 'static) -> Self

Register a typed HealthProbe as a readiness check.

pub fn with_version(self, version: impl Into<String>) -> Self

Override the version reported by the liveness endpoint.

pub fn with_health_path(self, path: impl Into<String>) -> Self

Override the base path for health endpoints. Defaults to /health.

pub fn with_telemetry(self) -> Self

Enable basic tracing via tracing_subscriber.

pub fn with_telemetry_init<F>(self, f: F) -> Self

where F: FnOnce(&str) -> Result<()> + Send + 'static,

Override the telemetry initialisation function.

When set, called instead of the built-in tracing_subscriber setup. Use this to wire in a full OTel SDK (e.g. otel-bootstrap) from a wrapper crate without forking serve().

The callback receives the service name and must return Ok(()) on success or an Error that aborts startup.

Implies ServiceBootstrap::with_telemetry — no need to call both.

Prefer with_telemetry_provider for new code; it also handles shutdown (span/metric flush) automatically.

pub fn with_telemetry_provider<P: TelemetryProvider>(self, provider: P) -> Self

Plug in a TelemetryProvider implementation.

The provider’s TelemetryProvider::init is called at startup and its TelemetryProvider::on_shutdown is registered as a drain hook that runs after the HTTP server stops (with a 30-second timeout).

Takes priority over with_telemetry_init and ServiceBootstrap::with_telemetry when all are called. Implies ServiceBootstrap::with_telemetry.

Use this to wire in otel-bootstrap or any other OTel SDK from a wrapper crate:

use socle::{ServiceBootstrap, ports::telemetry::TelemetryProvider, Result};

struct MyOtelProvider;
impl TelemetryProvider for MyOtelProvider {
    fn init(&self, _: &str) -> Result<()> { Ok(()) }
}

ServiceBootstrap::new("svc").with_telemetry_provider(MyOtelProvider);

pub fn with_database(self, url: impl Into<String>) -> Self

Connect to a Postgres database and build a sqlx::PgPool.

pub fn with_db_pool(self, pool: PgPool) -> Self

Provide a pre-built sqlx::PgPool instead of a connection URL.

Use this when the pool is constructed externally — for example by sqlx-switchboard’s PoolConfig — so that serve() skips its own pool construction. Takes precedence over ServiceBootstrap::with_database if both are called.

pub fn with_migrations(self, migrator: Migrator) -> Self

Run sqlx migrations at startup.

pub fn with_rate_limit(self, config: RateLimitBackend) -> Self

Enable the in-process GCRA rate limiter.

The limiter is applied as a tower layer inside serve(). By default it keys on the remote IP address — see with_rate_limit_extractor to change the extraction strategy.

Reverse-proxy note: the default RateLimitExtractor::Ip reads the L4 peer address, which is the proxy IP in production. All clients will share one rate-limit bucket. Use with_rate_limit_extractor(RateLimitExtractor::Header("x-forwarded-for")) when the service runs behind a trusted reverse proxy.

Memory note: the keyed limiter stores one entry per unique key with no TTL or size cap. Avoid RateLimitExtractor::Header with attacker-controlled headers in production; prefer Ip or a header with bounded cardinality.

pub fn with_rate_limit_extractor(self, extractor: RateLimitExtractor) -> Self

Override the key extractor used by the rate limiter.

pub fn with_rate_limit_provider<P: RateLimitProvider>(self, provider: P) -> Self

Plug in a RateLimitProvider implementation.

Takes priority over with_rate_limit when both are called. The provider receives the assembled router and returns it with the rate-limit tower layer applied.

Use this to inject distributed backends (Postgres, Redis, gossip) from a wrapper crate without calling with_layer directly:

use axum::Router;
use socle::{ServiceBootstrap, ports::rate_limit::RateLimitProvider};

struct MyDistributedRl;
impl RateLimitProvider for MyDistributedRl {
    fn apply(&self, router: Router) -> Router {
        router // .layer(my_distributed_rl_layer)
    }
}

ServiceBootstrap::new("svc").with_rate_limit_provider(MyDistributedRl);

pub fn with_auth_provider<P: AuthProvider>(self, provider: P) -> Self

Plug in an AuthProvider implementation.

Groundwork ships no built-in auth backend — the provider is supplied by the caller (typically a wrapper crate such as service-kit) and owns its configuration, JWKS cache, API-key validator, etc.

The provider receives the assembled router (already wrapped by the rate-limit layer when one is configured) and returns it with the auth tower layer applied. Auth is applied after rate-limit so unauthenticated requests are still rate-counted, and before any extra layers registered via with_layer.

use axum::Router;
use socle::{ServiceBootstrap, ports::auth::AuthProvider};

struct MyJwtAuth;
impl AuthProvider for MyJwtAuth {
    fn apply(&self, router: Router) -> Router {
        router // .layer(my_auth_layer)
    }
}

ServiceBootstrap::new("svc").with_auth_provider(MyJwtAuth);

pub fn with_audit_sink(self, sink: Arc<dyn AuditSink>) -> Self

Attach a pluggable audit sink.

When set, AuditLayer is applied after auth and before any with_layer extensions. Pass any type that implements AuditSink.

pub fn with_audit_filter(self, filter: AuditFilter) -> Self

Override the default AuditFilter.

Has no effect unless with_audit_sink is also called.

pub fn with_cors(self, cors: CorsLayer) -> Self

Override the default permissive CORS layer.

pub fn with_cors_config(self, cfg: CorsConfig) -> Result<Self>

Configure CORS from a structured CorsConfig.

pub fn with_router<F>(self, f: F) -> Self

where F: FnOnce(&BootstrapCtx) -> Router + Send + 'static,

Provide the router builder closure.

pub fn with_layer<F>(self, f: F) -> Self

where F: FnOnce(Router) -> Router + Send + 'static,

Inject an arbitrary tower layer into the middleware stack.

Layers are applied in registration order, innermost first (i.e. the first call to with_layer wraps closest to the user router).

This is the primary extension point for wrapper crates. Example — adding the distributed-ratelimit layer from service-kit:

bootstrap.with_layer(|router| router.layer(my_distributed_rl_layer))

impl ServiceBootstrap

pub async fn serve(self, addr: impl Into<String>) -> Result<()>

Run the service. Initialises every enabled integration in dependency order, binds the listener, serves until SIGINT/SIGTERM, then drains.

pub async fn serve_with_shutdown( self, listener: TcpListener, shutdown: impl Future<Output = ()> + Send + 'static, ) -> Result<()>

Run the service using a pre-bound listener and a caller-supplied shutdown future. Useful for integration tests where you need to bind on port 0 and control when the server stops.

use axum::{Router, routing::get};
use socle::{BootstrapCtx, ServiceBootstrap};
use tokio::net::TcpListener;

ServiceBootstrap::new("my-service")
    .with_router(|_: &BootstrapCtx| Router::new().route("/", get(|| async { "ok" })))
    .serve_with_shutdown(listener, std::future::pending())
    .await
    .unwrap()