A self-built API gateway written in Rust, demonstrating core backend engineering concepts: authentication, rate limiting, caching, asynchronous logging, and horizontal-scaling-friendly design. Built as a learning project to gain hands-on experience with the technologies that underpin real backend systems.
This service sits in front of a backend API and, for every incoming request:
- Authenticates the caller via an API key
- Rate limits them according to their key's configured tier (token bucket algorithm)
- Proxies the request to the real backend, transparently
- Caches responses to avoid redundant backend calls
- Logs the outcome of every request asynchronously, without adding latency to the response path
It's the same architectural pattern used by production API gateways (Kong, AWS API Gateway, etc.), built from scratch to understand what's actually happening underneath.
flowchart TD
client[Client request] --> gateway[Gateway<br/>axum]
gateway --> backend[Real backend<br/>proxied]
gateway --> postgres[(Postgres<br/>API keys / logs)]
gateway --> rediscache[(Redis<br/>cache)]
gateway --> redisqueue[(Redis<br/>log queue)]
redisqueue --> worker[Worker<br/>drains log queue]
worker --> postgres2[(Postgres<br/>batch insert)]
The gateway and the worker are separate processes. The gateway handles requests and pushes lightweight log entries onto a Redis queue; the worker independently drains that queue and writes to Postgres in batches. This means logging never blocks or slows down the response path — if the worker is momentarily busy or the database is slow, callers of the gateway are completely unaffected.
| Component | Choice | Why |
|---|---|---|
| Language | Rust | Performance and safety guarantees suited to a network-facing service |
| Web framework | axum | Idiomatic async Rust, built on tokio and tower |
| Async runtime | tokio | Industry-standard async runtime for Rust |
| Database | PostgreSQL | Stores API keys, owners, rate-limit tiers, and request logs |
| DB access | sqlx | Compile-time checked SQL — a typo'd column name fails to compile, not just to run |
| Cache / Queue | Redis | Doubles as the response cache (GET/SET with TTL) and the async log queue (LPUSH/BRPOP) |
| HTTP client (outbound) | reqwest | Used by the gateway to proxy requests to the real backend |
src/
bin/
worker.rs — separate binary: polls the Redis queue, batches, writes to Postgres
auth.rs — API key extraction and lookup (ApiKeyInfo)
config.rs — configuration constants / env-var loading
handlers.rs — root: the axum handler that composes auth → rate limit → proxy
lib.rs — declares the library's public modules
logging.rs — provide logging function to REDIS which is handled by handler
main.rs — binary entry point: builds state, router, starts the server (wiring only)
proxy.rs — proxy_request (plain proxy) and proxy_with_cache (cache-aware proxy)
rate_limit.rs — check_rate_limit (operates on the shared bucket map)
state.rs — AppState, TokenBucket (the rate-limit primitive)
worker_logic.rs — parse_batch / insert_batch: testable logic used by the worker
migrations/
<timestamp>_create_api_keys.sql
<timestamp>_create_request_logs.sql
The project is structured as a library + two binaries: shared logic lives in the library (src/lib.rs and its modules) so both the gateway (main.rs) and the worker (bin/worker.rs) can use it, and so the logic is unit-testable independently of either binary.
Callers identify themselves via an x-api-key header. The gateway looks this key up in the api_keys Postgres table; a missing or invalid key results in 401 Unauthorized before any other work happens.
Each API key gets its own token bucket, held in an in-memory HashMap shared across requests (Arc<Mutex<HashMap<String, TokenBucket>>>). Each key's bucket capacity and refill rate come from its row in the database, so different customers can have different tiers.
The token bucket algorithm: a bucket starts full, holds up to capacity tokens, refills continuously at refill_rate tokens/second (calculated lazily on each check, not via a background timer), and each request consumes one token. If no tokens remain, the request is rejected with 429 Too Many Requests. This allows natural bursts (an idle client's bucket is full) while still capping sustained request rates.
Successful proxy responses are cached in Redis with a TTL (currently 30 seconds). A cache hit skips the backend call entirely, returning the stored response directly — this is what makes repeated identical requests near-instant. Cache entries expire automatically, so the gateway never serves indefinitely stale data.
Known limitation: the cache key currently doesn't vary per-request-path or per-API-key. This is fine for a single fixed target URL, but before multi-path proxying is added, the cache key needs to incorporate the actual request path (and possibly the caller) so different requests don't collide into the same cached entry.
Every request — success or failure — gets a RequestLog entry (api_key, status, timestamp) pushed onto a Redis list (LPUSH request_logs). The gateway never waits on this write completing meaningfully slowing the response; it fires the push and moves on.
The worker process independently runs BRPOP request_logs 5 in a loop (blocking up to 5 seconds for the first entry, then draining anything else already queued via non-blocking RPOP up to a cap of 100), batches everything it collected into a single multi-row INSERT via sqlx::QueryBuilder, and writes it to Postgres in one round-trip. This batching means a burst of 50 simultaneous requests results in roughly one database write, not fifty.
api_keys
| column | type | notes |
|---|---|---|
| id | SERIAL PRIMARY KEY | |
| key | TEXT UNIQUE NOT NULL | the actual API key string |
| owner_name | TEXT NOT NULL | who the key belongs to |
| rate_limit_capacity | DOUBLE PRECISION | token bucket capacity for this key |
| rate_limit_refill_rate | DOUBLE PRECISION | tokens/second refill rate |
| created_at | TIMESTAMPTZ | defaults to now() |
request_logs
| column | type | notes |
|---|---|---|
| id | SERIAL PRIMARY KEY | |
| api_key | TEXT NOT NULL | |
| status | INTEGER NOT NULL | HTTP status code of the request |
| timestamp | TIMESTAMPTZ NOT NULL | when the request was logged |
- Rust toolchain (
cargo) - Docker (for Postgres and Redis)
sqlx-cli:
cargo install sqlx-cli --no-default-features --features postgresdocker run --name gateway-db -e POSTGRES_PASSWORD=devpassword -e POSTGRES_DB=gateway -p 5432:5432 -d postgres:16
docker run --name gateway-redis -p 6379:6379 -d redis:7For Linux run ./start_containers.sh
Create a .env file at the project root:
DATABASE_URL=postgres://postgres:devpassword@localhost:5432/gateway
sqlx migrate rundocker exec -it gateway-db psql -U postgres -d gateway -c \
"INSERT INTO api_keys (key, owner_name, rate_limit_capacity, rate_limit_refill_rate) VALUES ('test-key-123', 'nimes', 5.0, 1.0);"cargo run --bin api-gatewayListens on http://0.0.0.0:3000.
cargo run --bin workercurl -H "x-api-key: test-key-123" http://localhost:3000An invalid key returns 401; exceeding the bucket's capacity returns 429.
A test script covering all three cases (valid key, invalid key, rate-limit burst) is included as test_gateway.sh.
cargo testTests are organized in tiers:
- Pure unit tests (
TokenBucket,extract_api_key,check_rate_limit,parse_batch) — no external dependencies, run instantly. - Database integration tests (
ApiKeyInfo::try_get,insert_batch) — use#[sqlx::test], which spins up a fresh, isolated test database per test (migrations applied automatically) and tears it down afterward. RequiresDATABASE_URLto point at a reachable Postgres server. - Mocked-HTTP tests (
proxy_request) — usewiremockto run a local mock server instead of calling a real external backend, so tests don't depend on the internet or on the real target being up. - Full pipeline integration test (
root) — uses axum's.oneshot()(viatower::ServiceExt) to send a real request through the actual router in-process, without binding a port. Currently connects to a real local Redis instance rather than a mocked one.
- Cache key doesn't yet vary by request path or caller — fine for a single fixed target, would need addressing before proxying arbitrary paths.
- Failed requests are logged, but the log queue itself has no dead-letter handling if the worker is down for an extended period (Redis's list would simply grow).
- Only one fixed backend target is currently supported; routing to multiple backends based on path/key would be a natural next step.
- No TLS termination yet — assumed to sit behind a reverse proxy (nginx/Caddy) in a real deployment.