rust-api-starter

A production-ready Rust REST API workspace with built-in internationalization (English + Arabic).

قالب API جاهز للإنتاج مبني بلغة Rust مع دعم متكامل للعربية والإنجليزية. — README بالعربية

Live demo: coming at v2.0.0 release — https://rust-api-starter-demo.<your-domain>/docs

Features

• Cargo workspace, 7 focused crates — strict acyclic dependency graph enforced at compile time.
• First-class i18n with Mozilla Fluent. English and Arabic ship by default; adding a language is one folder.
• Authentication — registration, login, JWT access tokens, rotating refresh tokens with reuse detection, argon2id password hashing.
• Role-based access — user and admin roles with a first-class AdminOnly extractor.
• PostgreSQL + SQLx — pool with exponential-backoff retry, compile-time query checking, transactions.
• OpenAPI 3.0 — generated from Rust types via utoipa, served through Swagger UI at /docs.
• Production hardening — structured tracing with request IDs, security headers, configurable CORS, per-route rate limiting that respects X-Forwarded-For from trusted proxies, graceful shutdown.
• Container-first — multi-stage Dockerfile with HEALTHCHECK, docker-compose for dev and prod, opt-in hot-reload profile.
• Integration tests — real HTTP, real Postgres, covering auth, users CRUD, i18n, rate limits, and plural forms.

Quick start

git clone https://github.com/monzeromer-lab/rust-api-starter.git my-api
cd my-api
cp .env.example .env                  # set JWT_SECRET (>= 32 chars)
docker compose up --build

Then open http://localhost:8080/docs for Swagger UI.

Locale switching in action

Register a user, log in, and try the same failing request with both locales:

# English (default)
curl -s -X POST http://localhost:8080/auth/register \
    -H 'content-type: application/json' \
    -d '{"email":"ada@example.com","password":"short"}'
# → { "error": { "code": "validation_failed", "message": "Validation failed", "locale": "en", ... } }

# Arabic — same shape, localized message
curl -s -X POST http://localhost:8080/auth/register \
    -H 'content-type: application/json' \
    -H 'accept-language: ar' \
    -d '{"email":"ada@example.com","password":"short"}'
# → { "error": { "code": "validation_failed", "message": "فشل التحقق من صحة البيانات", "locale": "ar", ... } }

Benchmarks

Reference numbers on a 4-core laptop (DB on localhost):

Metric	Value
/health throughput	run benches/run.sh to populate
/users/me (authed) p99	run benches/run.sh to populate
Cold start	measured on clean release binary
i18n lookup per request	< 100 μs (Fluent bundles cached at startup)

Run your own:

docker compose up -d
./benches/run.sh

Documentation

Topic	English	العربية
Getting started	GETTING_STARTED.md	GETTING_STARTED.ar.md
Configuration reference	CONFIGURATION.md	CONFIGURATION.ar.md
Deployment recipes	DEPLOYMENT.md	DEPLOYMENT.ar.md
Database operations	DATABASE.md	—
i18n: adding a language	I18N_GUIDE.md	I18N_GUIDE.ar.md
Frequently asked questions	FAQ.md	FAQ.ar.md
Architecture (developer)	ARCHITECTURE.md	—
Adding a new domain (developer)	ADDING_A_DOMAIN.md	—
Testing philosophy (developer)	TESTING.md	—
Security model (developer)	SECURITY.md	—
Contributing (developer)	CONTRIBUTING.md	—

Project layout

rust-api-starter/
├── crates/
│   ├── common/       # AppError, ErrorResponse, i18n infra, validation helpers
│   ├── config/       # env loading, type-safe Config (incl. rate limits, CORS, proxies)
│   ├── db/           # SQLx pool with backoff, migrations, transaction helpers
│   ├── auth/         # JWT, argon2id, refresh rotation, middleware, handlers
│   ├── users/        # reference CRUD domain
│   ├── api/          # route assembly, OpenAPI, Swagger UI, middleware, bootstrap
│   └── app/          # binary: main.rs (~25 lines)
├── tests/integration/ # workspace-level integration tests
├── migrations/       # SQL migrations (embedded in the binary at compile time)
├── locales/          # Fluent translation files (en, ar)
├── docs/             # user-facing and developer documentation
├── deploy/           # systemd + nginx reference assets
├── benches/          # performance benchmark script
├── .github/workflows # CI, Docker build + publish, GitHub Pages rustdoc
├── Dockerfile, docker-compose.yml, docker-compose.prod.yml
└── .env.example

Contributing

See docs/CONTRIBUTING.md. Translations (especially non-English) are gladly welcomed — see docs/I18N_GUIDE.md.

License

Dual-licensed under MIT or Apache-2.0 at your option.