Feature Flags

acton-service uses feature flags to keep compile times fast and binary sizes small. Enable only what you need.

Quick Decision Tree

┌─────────────────────────────────────────┐
│ What are you building?                  │
└─────────────────────────────────────────┘
                    │
        ┌───────────┴───────────┐
        │                       │
   REST API                gRPC Service
        │                       │
        ▼                       ▼
   ["http",              ["grpc",
    "observability"]      "observability"]
        │                       │
        ├───────────────────────┤
        │
        ▼
┌─────────────────────────────────────────┐
│ Do you need a database?                 │
└─────────────────────────────────────────┘
        │
        ├─── Yes ──▶ Add "database"
        └─── No  ──▶ Skip
        │
        ▼
┌─────────────────────────────────────────┐
│ Do you need caching?                    │
└─────────────────────────────────────────┘
        │
        ├─── Yes ──▶ Add "cache"
        └─── No  ──▶ Skip
        │
        ▼
┌─────────────────────────────────────────┐
│ Do you need events/messaging?           │
└─────────────────────────────────────────┘
        │
        ├─── Yes ──▶ Add "events"
        └─── No  ──▶ Skip
        │
        ▼
┌─────────────────────────────────────────┐
│ Do you need advanced features?          │
└─────────────────────────────────────────┘
        │
        ├─── Fine-grained authorization ──▶ Add "cedar-authz"
        ├─── Rate limiting ───────────────▶ Add "governor"
        ├─── Resilience ──────────────────▶ Add "resilience"
        ├─── Metrics ─────────────────────▶ Add "otel-metrics"
        └─── OpenAPI ─────────────────────▶ Add "openapi"

Core Features

http

Included in default features

Enables HTTP REST API support via Axum.

When to use: Building REST APIs (most common use case)

Dependencies: Axum, Tower

acton-service = { version = "0.6.0", features = ["http"] }

observability

Included in default features

Enables structured logging and OpenTelemetry tracing.

When to use: Always (highly recommended for production)

Dependencies: tracing, tracing-subscriber, OpenTelemetry

acton-service = { version = "0.6.0", features = ["observability"] }

Protocol Features

grpc

Enables gRPC support via Tonic. Can run on the same port as HTTP with automatic protocol detection.

When to use: Building gRPC services or dual HTTP+gRPC services

Dependencies: tonic, prost

acton-service = { version = "0.6.0", features = ["grpcOnly"] }

Data Layer Features

database

PostgreSQL connection pooling via SQLx with automatic health checks and retry logic.

When to use: Your service needs a SQL database

Dependencies: sqlx with postgres feature

Provides:

• Automatic connection pool management
• Health checks for database connections
• Retry logic on connection failures

acton-service = { version = "0.6.0", features = ["databaseOnly"] }

cache

Redis connection pooling with support for JWT token revocation and distributed rate limiting.

When to use: Need caching, session storage, or rate limiting

Dependencies: redis, deadpool-redis

Provides:

• Redis connection pool
• JWT token revocation support
• Distributed rate limiting

acton-service = { version = "0.6.0", features = ["cacheOnly"] }

events

NATS JetStream client for event-driven architecture and pub/sub messaging.

When to use: Building event-driven microservices

Dependencies: async-nats

Provides:

• NATS connection management
• JetStream support
• Pub/sub messaging

acton-service = { version = "0.6.0", features = ["eventsOnly"] }

Middleware & Resilience Features

cedar-authz

AWS Cedar policy-based authorization for fine-grained access control.

When to use: Need fine-grained access control with declarative policies

Dependencies: cedar-policy

Provides:

• Declarative Cedar policy files for resource-based permissions
• Role-based and attribute-based access control (RBAC/ABAC)
• Manual policy reload endpoint (automatic hot-reload in progress)
• Optional Redis caching for sub-5ms policy decisions
• HTTP and gRPC support with customizable path normalization
• Layered security with JWT authentication

acton-service = { version = "0.6.0", features = ["cedarAuthz"] }

Note: Works best with cache feature for policy decision caching.

resilience

Circuit breaker, retry, and bulkhead patterns for production services.

When to use: Production services calling external dependencies

Dependencies: tower-resilience

Provides:

• Circuit breaker (prevent cascading failures)
• Exponential backoff retry
• Bulkhead (concurrency limiting)

acton-service = { version = "0.6.0", features = ["resilience"] }

governor

Advanced rate limiting with per-user limits via JWT claims.

When to use: Need sophisticated rate limiting beyond basic throttling

Dependencies: tower_governor

Provides:

• Per-second/minute/hour rate limits
• Per-user rate limiting via JWT claims
• In-memory rate limiting

acton-service = { version = "0.6.0", features = ["governor"] }

otel-metrics

HTTP metrics collection via OpenTelemetry for detailed monitoring.

When to use: Need detailed request metrics for monitoring

Dependencies: tower-otel-http-metrics

Provides:

• Request count, duration, size metrics
• Active request tracking
• HTTP status code distribution

acton-service = { version = "0.6.0", features = ["otelMetrics"] }

Documentation Features

openapi

OpenAPI/Swagger documentation generation with multiple UI options.

When to use: Need API documentation UI

Dependencies: utoipa, utoipa-swagger-ui

Provides:

• Swagger UI
• ReDoc UI
• RapiDoc UI
• Auto-generated OpenAPI specs

acton-service = { version = "0.6.0", features = ["openapiOnly"] }

Common Configurations

Minimal REST API

Use case: Simple REST API, no database

[dependencies]

Binary size: ~10MB (stripped) Compile time: ~30s (clean build)

REST API with Database

Use case: Standard CRUD API with PostgreSQL

[dependencies]

Binary size: ~12MB (stripped) Compile time: ~45s (clean build)

Full-Featured REST API

Use case: Production API with all bells and whistles

[dependencies]
acton-service = { version = "

Binary size: ~18MB (stripped) Compile time: ~90s (clean build)

REST API with Cedar Authorization

Use case: Secure API with fine-grained policy-based access control

[dependencies]
acton-service = { version = "

Binary size: ~16MB (stripped) Compile time: ~75s (clean build)

Dual HTTP + gRPC Service

Use case: Service exposing both REST and gRPC APIs

[dependencies]
acton-service = { version = "

Binary size: ~15MB (stripped) Compile time: ~60s (clean build)

Event-Driven Microservice

Use case: Background worker processing NATS events

[dependencies]
acton-service = { version = "

Binary size: ~14MB (stripped) Compile time: ~55s (clean build)

Everything (Development/Prototyping)

Use case: Exploring all features, quick prototyping

[dependencies]

Binary size: ~20MB (stripped) Compile time: ~120s (clean build)

⚠️ Warning: full includes everything. For production, only enable what you need.

Feature Dependencies

Some features work better together:

Troubleshooting

"cannot find type AppState"

Solution: You're probably missing required features. Add http and observability.

"method database not found"

Solution: Add database feature flag.

"could not find tonic in the list"

Solution: Add grpc feature flag.

Very slow compile times

Solution: You might have full enabled. Only enable features you actually use.

Large binary size

Solution:

1. Remove unused features
2. Build with --release
3. Strip symbols: strip target/release/my-service

Best Practices

Start Small

Begin with minimal features and add as needed:

# Start here
features = ["http", "observability"]

# Add as you grow
features = ["http", "observability", "database"]

# Production-ready
features = ["http", "observability", "database", "cache", "resilience"]

Production Recommendations

Minimum for production:

features = ["http", "observability", "resilience"]

Recommended for production:

features = [
    "http",
    "observability",
    "database",        # If you need it
    "cache",          # For sessions/rate limiting/Cedar caching
    "cedar-authz",    # Fine-grained authorization (optional)
    "resilience",     # Circuit breaker, retry
    "otel-metrics"    # Monitoring
]

CI/CD Optimization

Use different feature sets for different build stages:

# Fast CI check
cargo check --features "http,observability"

# Full integration tests
cargo test --features "http,observability,database,cache"

# Production build
cargo build --release --features "http,observability,database,cache,resilience,otel-metrics"

Need More Help?

• Quickstart - Get started in 5 minutes
• Tutorial - Step-by-step service guide
• Examples - Working examples for each feature
• Cargo.toml - Feature definitions