Examples

Browse complete, runnable examples showing how to build different types of services with acton-service. All examples are organized by category in the examples/ directory.

Example Categories

Examples are organized by feature and complexity. New to acton-service? Start with Basic Examples.

📚 Basic Examples {#basic-examples}

Directory:

Simple getting-started examples demonstrating core functionality:

simple-api.rs - Zero-Configuration Versioned API

The simplest possible service with automatic health checks.

use acton_service::prelude::*;

async fn hello() -> &'static str {
    "Hello, world!"
}

#[tokio::main]
async fn main() -> Result<()> {
    let routes = VersionedApiBuilder::new()
        .with_base_path("/api")
        .add_version(ApiVersion::V1, |router| {
            router.route("/hello", get(hello))
        })
        .build_routes();

    ServiceBuilder::new()
        .with_routes(routes)
        .build()
        .serve()
        .await
}

Demonstrates:

• Automatic configuration loading
• Type-safe API versioning
• Auto-generated health endpoints (/health, /ready)
• Built-in tracing and logging

cargo run --manifest-path=acton-service/Cargo.toml --example simple-api

users-api.rs - Multi-Version API Evolution

Shows how to manage multiple API versions with deprecation headers.

Demonstrates:

• Multiple API versions (V1, V2, V3)
• Automatic deprecation warnings
• API evolution patterns
• Breaking change management

cargo run --manifest-path=acton-service/Cargo.toml --example users-api

ping-pong.rs - Simple Request/Response

Minimal service template for basic HTTP endpoints.

cargo run --manifest-path=acton-service/Cargo.toml --example ping-pong --features grpc

Best for: First-time users, understanding basic patterns

🔐 Authorization {#authorization}

Directory:

Fine-grained access control using AWS Cedar policies.

cedar-authz.rs - Policy-Based Authorization

Complete example with JWT authentication + Cedar authorization.

Demonstrates:

• Role-based access control (admin vs user)
• Resource ownership patterns
• JWT + Cedar integration
• Optional Redis caching for policy decisions

cargo run --manifest-path=acton-service/Cargo.toml --example cedar-authz --features cedar-authz,cache

Features auto-setup with:

• policies.cedar - Policy definitions
• jwt-public.pem - JWT validation key
• config.toml - Service configuration

Best for: Implementing RBAC or attribute-based access control

for detailed setup, testing instructions, and policy explanations.

🔌 gRPC Examples {#grpc}

Directory:

gRPC service integration patterns.

single-port.rs - HTTP + gRPC on One Port

Run both REST and gRPC on a single port with automatic protocol detection.

Demonstrates:

• Dual-protocol support on port 8080
• Automatic routing based on content-type
• gRPC (application/grpc) → tonic services
• All other requests → axum HTTP handlers

cargo run --manifest-path=acton-service/Cargo.toml --example single-port --features grpc

Test HTTP:

curl http://localhost:8080/api/v1/hello

Test gRPC:

grpcurl -plaintext -d '{"name": "world"}' localhost:8080 hello.HelloService/SayHello

Best for: Services needing both REST and gRPC interfaces

📨 Event-Driven Architecture {#events}

Directory:

Event bus patterns and asynchronous communication.

event-driven.rs - HTTP API + gRPC with Event Bus

Recommended architecture: HTTP publishes events, gRPC consumes them.

Demonstrates:

• HTTP REST API (port 8080) publishing events
• gRPC service (port 9090) consuming events
• Decoupled microservice communication
• Async event processing

cargo run --manifest-path=acton-service/Cargo.toml --example event-driven --features grpc

Architecture:

HTTP Client → REST API → Event Bus → gRPC Service → Business Logic

Best for: Decoupled microservices, async message processing

📊 Observability {#observability}

Directory:

Metrics, tracing, and monitoring integration.

test-metrics.rs - Prometheus Metrics

Prometheus metrics collection and custom metric definitions.

cargo run --manifest-path=acton-service/Cargo.toml --example test-metrics --features otel-metrics
curl http://localhost:8080/metrics

test-observability.rs - OpenTelemetry Tracing

Distributed tracing setup with OpenTelemetry.

cargo run --manifest-path=acton-service/Cargo.toml --example test-observability --features observability

Demonstrates:

• OpenTelemetry initialization
• Span creation and propagation
• Integration with Jaeger/Zipkin
• Structured logging correlation

Best for: Production monitoring, debugging, performance analysis

📋 Templates {#templates}

Directory:

Configuration and build templates for new projects.

• config.toml.example - Complete service configuration template
• build.rs.example - Build script for proto compilation

Use these as starting points for your own services:

cp examples/templates/config.toml.example config.toml
cp examples/templates/build.rs.example build.rs

Best for: Starting a new project, understanding all configuration options

Running Examples

All examples run from the repository root with updated paths:

# Basic examples
cargo run --manifest-path=acton-service/Cargo.toml --example simple-api
cargo run --manifest-path=acton-service/Cargo.toml --example users-api
cargo run --manifest-path=acton-service/Cargo.toml --example ping-pong --features grpc

# Authorization (requires features)
cargo run --manifest-path=acton-service/Cargo.toml --example cedar-authz --features cedar-authz,cache

# gRPC (requires features)
cargo run --manifest-path=acton-service/Cargo.toml --example single-port --features grpc

# Events (requires features)
cargo run --manifest-path=acton-service/Cargo.toml --example event-driven --features grpc

# Observability (requires features)
cargo run --manifest-path=acton-service/Cargo.toml --example test-metrics --features otel-metrics
cargo run --manifest-path=acton-service/Cargo.toml --example test-observability --features observability

Feature Flags for Examples

Some examples require specific feature flags:

Learning Path

Recommended order for exploring acton-service:

1. Start: simple-api.rs - Understand basic service setup
2. Versioning: users-api.rs - Learn API version management
3. Authorization: cedar-authz.rs - Add access control
4. Advanced: Explore gRPC, events, and observability as needed

Example Structure

Each category includes:

• README.md - Detailed category documentation
• Complete source code - Runnable examples
• Inline documentation - Code comments explaining key concepts
• Test commands - Copy/paste curl/grpcurl commands

Next Steps

• Review Feature Flags to understand which features to enable
• Check Troubleshooting if you encounter issues
• Explore API Reference for detailed documentation