# Armature Documentation
Welcome to the Armature framework documentation! Armature is a batteries-included web framework for Rust, inspired by NestJS and Angular.
## Framework Overview
Armature provides the building blocks for HTTP APIs:
- 🚀 **Actix-Competitive Performance** - 112 optimizations, SIMD JSON, zero-alloc responses
- 🔒 **Type-Safe** - Catch errors at compile time
- 💉 **Dependency Injection** - Automatic service injection
- 📦 **Modular Architecture** - Organize code into reusable modules
- 🔐 **Built-in Security** - JWT, OAuth2, SAML, 2FA, rate limiting
- 📊 **Observability** - OpenTelemetry, Prometheus, structured logging
- ☁️ **Cloud Native** - AWS, GCP, Azure SDKs with serverless support
## Getting Started
Start with the main [README](../README.md) in the project root for a quick introduction and setup guide.
```bash
# Install the CLI
cargo install armature-cli
# Create a new project
armature new my-api
cd my-api
# Start the dev server
armature dev
```
To add Armature to an existing project:
```toml
[dependencies]
armature = { package = "armature-framework", version = "0.8" }
```
Enable optional crates with features, for example
`armature = { package = "armature-framework", version = "0.8", features = ["auth", "security"] }`.
The library is imported as `armature` (`use armature::prelude::*;`).
### Secure defaults
Guards fail closed, request paths are canonicalized before routing, request bodies
and headers are read under deadlines, GraphQL developer tooling is off by default,
and client IPs come from the socket peer unless you trust a fixed number of proxies.
See the [Security Guide](security-guide.md), the [Authentication Guide](auth-guide.md)
and each crate's `CHANGELOG.md` for the details and migrations.
## Documentation Index
### Core Guides
| [Dependency Injection](di-guide.md) | Service injection, module system, best practices |
| [Configuration](config-guide.md) | Environment variables, type-safe config, validation |
| [Lifecycle Hooks](lifecycle-hooks.md) | OnInit, OnDestroy, module lifecycle |
| [Project Templates](project-templates.md) | Starter templates and scaffolding |
| [Macros Overview](macro-overview.md) | Decorator macros and code generation |
### Authentication & Security
| [Authentication](auth-guide.md) | Password hashing, JWT, guards, RBAC |
| [OAuth2 Providers](oauth2-providers-guide.md) | Google, Microsoft, GitHub, Discord, and more |
| [Security Best Practices](security-guide.md) | CORS, CSP, HSTS, request signing |
| [Advanced Security](security-advanced-guide.md) | 2FA, WebAuthn, API keys |
| [Session Management](session-guide.md) | Redis-backed sessions, cookies |
| [Rate Limiting](rate-limiting-guide.md) | Token bucket, sliding window algorithms |
### Routing & Controllers
| [Route Groups](route-groups-guide.md) | Organizing routes with shared middleware |
| [Route Constraints](route-constraints-guide.md) | Parameter validation at route level |
| [Guards](use-guard-guide.md) | Authorization and access control |
| [Middleware](use-middleware-guide.md) | Request/response middleware |
| [Guards & Interceptors](guards-interceptors.md) | Cross-cutting concerns |
| [Request Extractors](request-extractors.md) | Body, Query, Path, Header extractors |
### API Features
| [API Versioning](api-versioning-guide.md) | URL, header, and query-based versioning |
| [Content Negotiation](content-negotiation-guide.md) | Accept header handling |
| [Pagination & Filtering](pagination-filtering-guide.md) | Offset/cursor pagination, sorting |
| [Response Caching](response-caching-guide.md) | Cache-Control, ETags |
| [ETags & Conditional Requests](etag-conditional-requests-guide.md) | If-Match, If-None-Match |
| [Request Timeouts](request-timeouts-guide.md) | Configurable timeouts |
| [Streaming Responses](streaming-responses-guide.md) | Chunked transfer, large files |
### GraphQL & OpenAPI
| [GraphQL Guide](graphql-guide.md) | Schema-first and code-first GraphQL |
| [GraphQL Configuration](graphql-configuration.md) | Advanced GraphQL options |
| [OpenAPI/Swagger](openapi-guide.md) | Auto-generated API documentation |
### Real-Time Communication
| [WebSocket & SSE](websocket-sse-guide.md) | Real-time bidirectional communication |
| [Webhooks](webhooks.md) | Webhook sending and receiving |
### Background Processing
| [Job Queues](queue-guide.md) | Redis-backed background jobs |
| [Cron Jobs](cron-guide.md) | Scheduled tasks |
| [Graceful Shutdown](graceful-shutdown-guide.md) | Connection draining, cleanup hooks |
### Caching
| [Caching Strategies](cache-improvements-guide.md) | Multi-tier caching, tag invalidation |
| [Redis Integration](redis-guide.md) | Centralized Redis client |
### Observability
| [Structured Logging](logging-guide.md) | JSON logging, pretty printing, env config |
| [Debug Logging](debug-logging-guide.md) | Development logging |
| [OpenTelemetry](opentelemetry-guide.md) | Distributed tracing and metrics |
| [Prometheus Metrics](metrics-guide.md) | Custom metrics, /metrics endpoint |
| [Health Checks](health-check-guide.md) | Liveness, readiness, startup probes |
| [Error Correlation](error-correlation-guide.md) | Request ID tracking |
| [Audit Logging](audit-guide.md) | Who did what, when |
### Database
| [Diesel Integration](diesel-guide.md) | Async Diesel with connection pooling |
| [SeaORM Integration](seaorm-guide.md) | SeaORM with active record pattern |
### Data & Search
| [OpenSearch](opensearch-guide.md) | Full-text search, indexing, aggregations |
### Internationalization
| [i18n Guide](i18n-guide.md) | Translations, locale detection, pluralization, formatting |
### Serialization & AI
| [TOON Format](toon-guide.md) | Token-optimized serialization for LLM applications |
### Cloud Providers
| [Cloud Providers](cloud-providers-guide.md) | AWS, GCP, Azure SDK integration |
Armature provides first-class integrations with major cloud providers:
| **armature-aws** | Amazon Web Services | S3, DynamoDB, SQS, SNS, SES, Lambda, KMS, Cognito |
| **armature-gcp** | Google Cloud Platform | Storage, Pub/Sub, Firestore, Spanner, BigQuery |
| **armature-azure** | Microsoft Azure | Blob, Queue, Cosmos, Service Bus, Key Vault |
**Key Features:**
- 🔌 **Dynamic Loading** - Only compile services you need via feature flags
- 💉 **DI Integration** - Register once, inject everywhere
- ⚡ **Lazy Initialization** - Services created on first access
- 🔧 **Environment Config** - Reads from standard cloud environment variables
- 🧪 **Emulator Support** - LocalStack, GCP emulators, Azurite
### Networking & HTTP
| [HTTPS & TLS](https-guide.md) | TLS configuration |
| [ACME Certificates](acme-certificates.md) | Let's Encrypt auto-renewal |
| [Compression](compression.md) | Gzip, Brotli compression |
| [HTTP Status & Errors](http-status-errors.md) | Error handling |
| [Error Transformation](error-transformation-guide.md) | Custom error formatting |
### Testing
| [Testing Guide](testing-guide.md) | Unit, integration, e2e testing |
| [Test Coverage](testing-coverage.md) | Coverage reporting |
| [Testing Best Practices](testing-documentation.md) | Testing patterns |
| [Documentation Testing](documentation-testing.md) | Doc example testing |
| [Fuzzing Guide](fuzzing-guide.md) | Fuzz testing with cargo-fuzz |
### Architecture
| [Stateless Architecture](stateless-architecture.md) | Building scalable services |
| [Server Integration](server-integration.md) | Hyper, custom servers |
| [Macros Deep Dive](macros-guide.md) | Understanding Armature macros |
### Performance & Benchmarks
| [Performance Guide](performance-guide.md) | Optimization techniques, best practices, profiling |
| [vs Node.js](armature-vs-nodejs-benchmark.md) | Performance comparison with Express, NestJS |
| [vs Next.js](armature-vs-nextjs-benchmark.md) | Performance comparison with Next.js |
### Development & Contributing
| [Publishing to crates.io](publishing-guide.md) | Publishing workspace crates |
## Quick Example
```rust
use armature::prelude::*;
use serde::{Deserialize, Serialize};
#[derive(Serialize, Deserialize)]
struct User { id: u32, name: String }
// Injectable service
#[injectable]
#[derive(Default, Clone)]
struct UserService;
impl UserService {
fn find_by_id(&self, id: u32) -> Option<User> {
Some(User { id, name: "Alice".into() })
}
}
// Controller with routes
#[controller("/api/users")]
#[derive(Default, Clone)]
struct UserController;
impl UserController {
#[get("")]
async fn list() -> Result<Json<Vec<User>>, Error> {
Ok(Json(vec![User { id: 1, name: "Alice".into() }]))
}
#[get("/:id")]
async fn get_user(req: HttpRequest) -> Result<Json<User>, Error> {
let id: u32 = req.param("id").unwrap().parse().unwrap();
Ok(Json(User { id, name: "Alice".into() }))
}
}
// Module wires everything together
#[module(
providers: [UserService],
controllers: [UserController]
)]
#[derive(Default)]
struct AppModule;
#[tokio::main]
async fn main() {
let app = Application::create::<AppModule>().await;
app.listen(3000).await.unwrap();
}
```
## Examples
See the [examples directory](../examples/) for working code samples:
| `crud_api.rs` | Complete REST API with CRUD operations |
| `auth_api.rs` | JWT authentication flow |
| `realtime_api.rs` | WebSocket/SSE real-time communication |
| `dependency_injection.rs` | DI patterns and best practices |
| `websocket_chat.rs` | WebSocket chat room |
| `server_sent_events.rs` | SSE streaming |
## Key Concepts
### Dependency Injection
Armature provides automatic service injection based on field types:
```rust
#[injectable]
#[derive(Default, Clone)]
struct UserService { }
#[controller("/users")]
#[derive(Default, Clone)]
struct UserController {
user_service: UserService, // Auto-injected!
}
```
### Module System
Organize your application into modules:
```rust
#[module(
providers: [UserService, EmailService],
controllers: [UserController],
imports: [AuthModule, CacheModule]
)]
#[derive(Default)]
struct AppModule;
```
### Cloud Integration
Multi-cloud support with DI:
```rust
#[module_impl]
impl CloudModule {
#[provider(singleton)]
async fn aws() -> Arc<AwsServices> {
AwsServices::new(AwsConfig::from_env().enable_s3().build()).await.unwrap()
}
#[provider(singleton)]
async fn redis() -> Arc<RedisService> {
Arc::new(RedisService::new(RedisConfig::from_env().build()).await.unwrap())
}
}
```
## Documentation Conventions
- **Lowercase with hyphens**: `my-feature-guide.md`
- **Descriptive names**: `oauth2-providers-guide.md` not `oauth.md`
- **.md extension** for all Markdown files
## Version
This documentation is for Armature version 0.1.0.
---
For the latest updates, visit the [GitHub repository](https://github.com/quinnjr/armature).