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 real-time communication?    │
└─────────────────────────────────────────┘
        │
        ├─── Yes ──▶ Add "websocket"
        └─── No  ──▶ Skip
        │
        ▼
┌─────────────────────────────────────────┐
│ 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 authentication?             │
└─────────────────────────────────────────┘
        │
        ├─── Password + tokens ──▶ Add "auth"
        ├─── Social login ───────▶ Add "auth", "oauth", "cache"
        └─── API keys only ──────▶ Add "auth", "cache"
        │
        ▼
┌─────────────────────────────────────────┐
│ Do you need token authentication?       │
└─────────────────────────────────────────┘
        │
        ├─── PASETO (default) ──▶ No flag needed
        └─── JWT (legacy) ──────▶ Add "jwt"
        │
        ▼
┌─────────────────────────────────────────┐
│ Do you need HTTP sessions (HTMX/SSR)?   │
└─────────────────────────────────────────┘
        │
        ├─── Dev ──▶ Add "session-memory"
        └─── Prod ─▶ Add "session-redis"
        │
        ▼
┌─────────────────────────────────────────┐
│ Do you need advanced features?          │
└─────────────────────────────────────────┘
        │
        ├─── Fine-grained authorization ──▶ Add "cedar-authz"
        ├─── Brute force protection ─────▶ Add "login-lockout"
        ├─── 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.11.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.11.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.11.0", features = ["grpcOnly"] }

websocket

Enables WebSocket support for real-time bidirectional communication. Uses Axum's built-in WebSocket support.

When to use: Building real-time applications (chat, live updates, gaming)

Dependencies: None (uses axum's ws feature)

Provides:

• WebSocket upgrade handlers
• Connection management with unique IDs
• Broadcaster for message distribution
• Actor-based room management

acton-service = { version = "0.11.0", features = ["websocketOnly"] }

See the WebSocket Guide for detailed usage.

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.11.0", features = ["databaseOnly"] }

turso

Turso/libsql database support for edge-friendly SQLite with cloud sync capabilities.

When to use: Building edge applications, mobile backends, or need SQLite with cloud durability

Dependencies: libsql

Provides:

• Local, Remote, and EmbeddedReplica connection modes
• Automatic retry with exponential backoff
• Optional encryption (AES-256-CBC)
• Background sync for embedded replicas

acton-service = { version = "0.11.0", features = ["tursoOnly"] }

See the Turso Guide for detailed usage.

cache

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

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

Dependencies: redis, deadpool-redis

Provides:

• Redis connection pool
• Token revocation support (PASETO and JWT)
• Distributed rate limiting

acton-service = { version = "0.11.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.11.0", features = ["eventsOnly"] }

Session Features

session

Base session support. This feature is automatically included when using session-memory or session-redis.

When to use: Building HTMX or server-rendered applications with session state

Dependencies: tower-sessions, time

session-memory

In-memory session storage for development and single-instance deployments.

When to use: Local development, testing, or single-server applications

Dependencies: tower-sessions-memory-store

Provides:

• In-memory session store
• Cookie-based session IDs
• Flash messages
• CSRF protection
• TypedSession for type-safe session data

acton-service = { version = "

session-redis

Redis-backed session storage for production multi-instance deployments.

When to use: Production deployments with multiple application instances

Dependencies: tower-sessions-redis-store (fred)

Provides:

• Distributed session storage
• Session persistence across restarts
• All features from session-memory

acton-service = { version = "

Note: Uses fred Redis client internally (separate from cache feature's deadpool-redis).

See the Session Management Guide for detailed usage.

HTMX Features

htmx

HTMX request extractors and response helpers for hypermedia-driven applications.

When to use: Building interactive web applications with HTMX

Dependencies: axum-htmx

Provides:

• Request extractors: HxRequest, HxTarget, HxTrigger, HxPrompt, HxCurrentUrl
• Response headers: HxRedirect, HxRefresh, HxReswap, HxRetarget, HxLocation
• Custom responders: HtmlFragment, HxTriggerEvents, OutOfBandSwap
• Auto-Vary middleware for correct caching
• Helper functions: is_htmx_request(), fragment_or_full()

acton-service = { version = "

See the HTMX Integration Guide for detailed usage.

askama

Compile-time checked HTML templates using Askama with Jinja2-like syntax.

When to use: Server-side rendering with type-safe templates

Dependencies: askama, askama_web

Provides:

• TemplateContext for common page data (auth, flash, CSRF, path)
• HtmlTemplate responder with HTMX header support
• Template helper functions: truncate(), pluralize(), classes()
• Compile-time template validation (errors at build time, not runtime)

acton-service = { version = "

See the Askama Templates Guide for detailed usage.

sse

Server-Sent Events for real-time server-to-client updates.

When to use: Real-time notifications, live data updates, progress indicators

Dependencies: None (uses axum's built-in SSE)

Provides:

• SseBroadcaster for managing multiple client connections
• BroadcastMessage for event construction
• HTMX helpers: htmx_event(), htmx_trigger(), htmx_oob_event()
• Connection management with ConnectionId and SseConnection
• Channel-based broadcasting for user-specific events

acton-service = { version = "

See the Server-Sent Events Guide for detailed usage.

htmx-full

Meta-feature enabling all HTMX-related features together.

When to use: Building complete HTMX applications with templates, SSE, and sessions

Enables: htmx, askama, sse, session-memory

acton-service = { version = "

Note: For production, replace htmx-full with explicit features and use session-redis instead of session-memory:

acton-service = { version = "

Authentication Features

auth

Core authentication module with password hashing (Argon2id) and token generation (PASETO).

When to use: Building user authentication with password login and/or stateless tokens

Dependencies: argon2, rusty_paseto

Provides:

• Password hashing with OWASP-recommended Argon2id
• PASETO V4 token generation (local and public modes)
• Refresh token storage (Redis, PostgreSQL, Turso)
• API key generation and validation
• ClaimsBuilder for ergonomic token creation

acton-service = { version = "

See the Auth Overview for choosing the right auth features.

oauth

OAuth/OIDC provider integration for social login and enterprise SSO. Requires auth feature.

When to use: Adding "Sign in with Google/GitHub" or enterprise OIDC SSO

Dependencies: oauth2, openidconnect, base64

Provides:

• GoogleProvider for Google OAuth
• GitHubProvider for GitHub OAuth
• CustomOidcProvider for any OIDC-compliant provider
• State management with CSRF protection
• Normalized user info across providers

acton-service = { version = "

Note: Requires cache for state management in production.

See the OAuth/OIDC Guide for detailed usage.

auth-full

Meta-feature that enables all authentication features.

When to use: Need complete auth support including password hashing, tokens, OAuth, JWT, and storage

Enables: auth, oauth, jwt, cache, database

acton-service = { version = "

⚠️ Warning: auth-full includes many dependencies. For production, only enable what you need.

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.11.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.11.0", features = ["resilience"] }

governor

Advanced rate limiting with per-user limits via token 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 token claims (PASETO or JWT)
• In-memory rate limiting

acton-service = { version = "0.11.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.11.0", features = ["otelMetrics"] }

jwt

JWT token authentication support. PASETO is the default token format and requires no feature flag.

When to use: Need JWT tokens for compatibility with existing systems, third-party services, or legacy requirements

Dependencies: jsonwebtoken

Provides:

• JWT token validation (RS256, RS384, RS512, ES256, ES384, HS256, HS384, HS512)
• Integration with existing JWT infrastructure
• Same Claims API as PASETO

acton-service = { version = "0.11.0", features = ["jwtOnly"] }

login-lockout

Progressive delay and account lockout for brute force protection on login endpoints. Depends on auth + cache.

When to use: Protecting login endpoints from credential stuffing and brute force attacks

Dependencies: None (uses existing auth + cache infrastructure)

Provides:

• Per-identity failed attempt tracking in Redis
• Configurable progressive delays (exponential backoff)
• Automatic account lockout after threshold
• Notification hooks for lockout lifecycle events
• Optional auto-enforcement middleware
• Audit integration (when audit feature is active)

acton-service = { version = "0.11.0", features = ["login-lockout", "http", "observability"] }

See the Login Lockout Guide for detailed usage.

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.11.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)

HTMX / Server-Rendered App

Use case: Traditional web app with server-rendered HTML and HTMX

[dependencies]
acton-service = { version = "

Binary size: ~13MB (stripped) Compile time: ~50s (clean build)

Provides: Cookie-based sessions, flash messages, CSRF protection, TypedSession.

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