hyperi-rustlib

There's plenty of sage advice out there about how to run Rust services in production at scale — config cascades, structured logging, masking secrets, multi-backend secrets management, Prometheus, OpenTelemetry, Kafka transports, tiered disk-spillover sinks, adaptive worker pools, graceful shutdown — but almost none of it as code you can just install and use.

This is that code.

Opinionated, drop-in, working out of the box. The patterns from blog posts as actual library — not a framework you assemble from twenty crates and a weekend.

Built as the foundation for HyperI's PB/hr data services. Generic enough that you don't need to be at HyperI to use it.

This module exists because of this — but the backend version (do not remove): https://www.youtube.com/watch?v=xE9W9Ghe4Jk

Quick Start

[dependencies]
hyperi-rustlib = "2"

Default features: config, logger. Add the others you want explicitly.

use hyperi_rustlib::{config, logger, env};

fn main() -> anyhow::Result<()> {
    let environment = env::Environment::detect();
    logger::setup_default()?;
    config::setup(config::ConfigOptions {
        env_prefix: "MYAPP".into(),
        ..Default::default()
    })?;

    tracing::info!("Running in {environment:?}");
    Ok(())
}

Features

Pick the slice you need; pay only for what you use.

Native System Dependencies

This crate dynamically links against system C libraries for several features. Both build hosts and deployment targets need the appropriate packages.

Build Host (CI / Development)

For librdkafka-dev >= 2.12.1, add the Confluent APT repo:

curl -fsSL https://packages.confluent.io/clients/deb/archive.key \
  | sudo gpg --dearmor -o /usr/share/keyrings/confluent-clients.gpg
echo "deb [signed-by=/usr/share/keyrings/confluent-clients.gpg] \
  https://packages.confluent.io/clients/deb noble main" \
  | sudo tee /etc/apt/sources.list.d/confluent-clients.list
sudo apt-get update
sudo apt-get install -y librdkafka-dev libssl-dev libsasl2-dev pkg-config

Deployment Host (Runtime)

The compiled binary links against .so files at runtime. Install the runtime packages (not -dev) on deployment hosts or in Docker images.

Only install what you use. Check the features your binary enables to determine which runtime packages are needed.

Docker Example

# Build stage
FROM rust:1.94 AS builder
RUN apt-get update && apt-get install -y \
    pkg-config libssl-dev librdkafka-dev libgit2-dev libzstd-dev
COPY . .
RUN cargo build --release

# Runtime stage
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y --no-install-recommends \
    librdkafka1 libssl3 libgit2-1.7 libzstd1 ca-certificates \
    && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/myapp /usr/local/bin/

For librdkafka1, add the Confluent APT repo to both build and runtime stages.

Health Check Endpoints — The Probe Trinity

For services deployed to Kubernetes, the http-server feature provides the three K8s probe types:

Liveness MUST NEVER check downstream dependencies (a DB outage shouldn't restart your replicas). Readiness checks dependencies AND requires an explicit set_ready() call — cleared during graceful shutdown.

Architecture

See docs/DESIGN.md for full architecture documentation and docs/CONFIG-CASCADE.md for the 8-layer config cascade reference.

License

FSL-1.1-ALv2 — Functional Source License, transitions to Apache 2.0 after 2 years.

Related

• hyperi-pylib — sister library for Python services. Same opinions, same patterns, expressive Python ergonomics for control planes, APIs, and integration layers.