Getting started

Rust microservice framework with type-enforced patterns

Build microservices with dual HTTP+gRPC support, automatic health checks, and built-in observability.

What is this?

Building microservices often involves implementing the same patterns: API versioning, health checks, observability, resilience patterns, connection pooling, and configuration management. Many frameworks leave these as optional concerns or implementation details.

acton-service provides a type-enforced framework with built-in implementations of these patterns:

• Type-enforced API versioning - Impossible to bypass, compiler-enforced versioning
• Dual HTTP + gRPC - Run both protocols on the same port with automatic detection
• Cedar policy-based authorization - AWS Cedar integration for fine-grained access control
• Observability - OpenTelemetry tracing, metrics, and structured logging built-in
• Resilience patterns - Circuit breaker, retry logic, and bulkhead patterns included
• Zero-config defaults - XDG-compliant configuration with sensible production defaults
• Kubernetes-ready - Automatic health/readiness probes for orchestration

It's opinionated and designed for teams that want consistent patterns across services.

Quick Start

use acton_service::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    // Build versioned API routes - versioning enforced by type system
    let routes = VersionedApiBuilder::new()
        .with_base_path("/api")
        .add_version(ApiVersion::V1, |router| {
            router.route("/hello", get(|| async { "Hello, V1!" }))
        })
        .add_version(ApiVersion::V2, |router| {
            router.route("/hello", get(|| async { "Hello, V2!" }))
        })
        .build_routes();

    // Zero-config service startup with automatic features:
    // - Health/readiness endpoints (/health, /ready)
    // - OpenTelemetry tracing and metrics
    // - Structured JSON logging
    // - Request tracking and correlation IDs
    // - Configuration from environment or files
    ServiceBuilder::new()
        .with_routes(routes)
        .build()
        .serve()
        .await
}

cargo run

# Versioned API endpoints
curl http://localhost:8080/api/v1/hello
curl http://localhost:8080/api/v2/hello

# Automatic health checks (Kubernetes-ready)
curl http://localhost:8080/health
curl http://localhost:8080/ready

# OpenTelemetry metrics automatically collected
# Structured logs in JSON format automatically emitted
# Request IDs automatically generated and tracked

The type system enforces best practices:

// ❌ This won't compile - unversioned routes rejected at compile time
let app = Router::new().route("/unversioned", get(handler));
ServiceBuilder::new().with_routes(app).build();
//                                   ^^^ expected VersionedRoutes, found Router

Why acton-service?

Common Challenges

Building microservices often involves solving recurring problems:

• Dual Protocols: Supporting both HTTP REST APIs and gRPC typically requires choosing one or running two separate servers
• Observability: Distributed tracing, metrics collection, and structured logging need integration across multiple libraries
• Resilience Patterns: Circuit breakers, retries, and bulkheads require careful implementation
• Health Checks: Orchestrators need health endpoints, but implementation approaches vary
• API Evolution: Breaking changes can occur when versioning is optional
• Configuration: Environment-based config often requires boilerplate for each service

acton-service Approach

acton-service provides opinionated solutions to these challenges:

1. Dual HTTP + gRPC - Run both protocols on the same port with automatic protocol detection, or use separate ports
2. Observability stack - OpenTelemetry tracing, HTTP metrics, and structured JSON logging configured by default
3. Resilience patterns - Circuit breaker, exponential backoff retry, and bulkhead middleware included
4. Automatic health endpoints - Kubernetes liveness and readiness probes with dependency monitoring
5. Type-enforced API versioning - Compiler prevents unversioned APIs through opaque types
6. Configuration system - XDG-compliant configuration with defaults and environment variable overrides
7. Middleware library - JWT auth, Cedar policy-based authorization, rate limiting, request tracking, compression, CORS, timeouts
8. Connection pool management - PostgreSQL, Redis, and NATS support with automatic retry and health checks

The type system enforces these patterns at compile time.

Core Features

acton-service provides these capabilities:

• Type-Safe API Versioning - Compile-time enforcement with RFC 8594 deprecation headers
• Automatic Health Checks - Kubernetes liveness/readiness probes with dependency monitoring
• Middleware Library - Authentication (JWT, Cedar policies), resilience (circuit breaker, retry, bulkhead), rate limiting, observability
• HTTP + gRPC Support - Single-port multiplexing with automatic protocol detection
• Configuration System - XDG-compliant config with environment overrides

For detailed documentation on each feature, see the API Versioning, Health Checks, Resilience Patterns, and Observability guides.

Installation

Add to your Cargo.toml:

[dependencies]
acton-service = { version = "

Or use the CLI to scaffold a complete service:

cargo install acton-cli
acton service new my-api --yes
cd my-api && cargo run

See the Installation Guide for detailed setup instructions and feature combinations.

Next Steps

• Quickstart Guide - Get a service running in 5 minutes
• Installation - Detailed installation and setup instructions
• Framework Comparison - How acton-service compares to Axum, Actix-Web, Rocket, and others
• [Examples](https://github.com/govcraft/acton-service/tree/main/acton-service/examples) - Complete working examples for common patterns