Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

API Gateway

Description

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.

What it does

This service sits in front of a backend API and, for every incoming request:

  1. Authenticates the caller via an API key
  2. Rate limits them according to their key's configured tier (token bucket algorithm)
  3. Proxies the request to the real backend, transparently
  4. Caches responses to avoid redundant backend calls
  5. 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.

Architecture

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)]
Loading

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.

Tech stack

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

Project structure

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.

How each piece works

Authentication

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.

Rate limiting — token bucket

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.

Caching

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.

Async logging

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.

Database schema

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

Running it locally

Prerequisites

  • Rust toolchain (cargo)
  • Docker (for Postgres and Redis)
  • sqlx-cli:
cargo install sqlx-cli --no-default-features --features postgres

1. Start Postgres and Redis

docker 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:7

Note: If containers do not start just run them.

For Linux run ./start_containers.sh

2. Configure environment

Create a .env file at the project root:

DATABASE_URL=postgres://postgres:devpassword@localhost:5432/gateway

3. Run migrations

sqlx migrate run

4. Add a test API key

docker 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);"

5. Run the gateway

cargo run --bin api-gateway

Listens on http://0.0.0.0:3000.

6. Run the worker (separate terminal)

cargo run --bin worker

7. Test it

curl -H "x-api-key: test-key-123" http://localhost:3000

An 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.

Running the tests

cargo test

Tests 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. Requires DATABASE_URL to point at a reachable Postgres server.
  • Mocked-HTTP tests (proxy_request) — use wiremock to 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() (via tower::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.

Known limitations / possible extensions

  • 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.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages