feat: add a Redis-backed driver API load balancer

[CoreyLeath-code]

Summary

Implements issue #17 and retains the dated tracking entry in Dailylog.md.

• Adds an NGINX gateway at the existing public driver-location port (8000) and makes API replicas internal.
• Adds a Redis-backed driver-location store for the Compose topology, preventing replica-local state divergence while preserving the in-memory store for local single-process use.
• Adds liveness and Redis-aware readiness endpoints.
• Adds a CI integration job that proves the gateway sees shared Redis state, routes to multiple replicas, and stays ready after one backend stops.

Files changed

• nginx/driver-location-load-balancer.conf — least-connections upstream, forwarded-request headers, and safe retry policy for liveness/readiness.
• docker-compose.yml — adds Redis, removes direct API host exposure, and adds NGINX as the only public API endpoint.
• location_store.py — adds the Redis store and explicit store factory while preserving DriverLocationStore for local development.
• main.py — selects the shared store from DRIVER_LOCATION_REDIS_URL and provides a test-only opt-in replica header.
• api_router.py — adds /driver-location/ready without changing the existing liveness endpoint.
• test_redis_driver_location_store.py — behavioral round-trip and readiness coverage using an injected fake Redis client.
• .github/workflows/ci.yml — validates NGINX syntax and runs the three-replica gateway integration check.
• README.md — documents public gateway ownership, scaling, probes, and test scope.
• Dailylog.md — preserves the dated record and links enhancement: add a gateway load balancer for horizontally scaled APIs #17.

Validation performed

• Compared the branch against current main: 9 files changed, branch is 9 commits ahead and 0 behind.
• Reviewed the Compose topology to confirm only api-gateway publishes port 8000; API replicas use Redis state.
• Added behavioral unit coverage for Redis serialization, reads, deletion, and readiness.
• Added CI steps to validate NGINX, start three replicas, seed Redis, read the seeded record through the gateway, verify at least two replica identities, and recheck readiness after one backend stops.

The connected GitHub workspace cannot execute Docker or Python locally; the new CI job is the authoritative runtime validation and this PR remains draft until it reports.

Risks

• The Redis configuration is a local Compose single-node service, not a production HA Redis deployment.
• The NGINX upstream is intentionally Compose-specific; production needs its own ingress/load-balancer configuration.
• No throughput, availability, or load-test metric is claimed by this PR.

Follow-up recommendations

• Run a measured load and failover test in the intended deployment environment before setting operational SLOs.
• Add Redis authentication/TLS and a managed high-availability topology for production.
• Add API authentication, authorization, rate limiting, and PII controls before exposing the public gateway.

CI follow-up

The initial run failed only at mypy during the Type check step. The Redis-store constructor now narrows the optional URL before calling redis.Redis.from_url; the runtime behavior and gateway assertions are unchanged. CI run #160 completed successfully: format, lint, type check, tests, benchmark harness, broker integration, and driver API load-balancer integration all passed.

Summary by CodeRabbit

• New Features

  • Added load-balanced driver-location API access through a gateway on port 8000.
  • Added Redis-backed shared driver-location storage for multiple API instances.
  • Added service readiness checks and resilience when an API instance becomes unavailable.
  • Added optional instance identification in response headers for testing.

• Bug Fixes

  • Improved health monitoring by separating liveness and readiness checks.

• Documentation

  • Documented load balancing, shared state, readiness checks, and replica failure handling.

• Tests

  • Added automated validation for routing, Redis state sharing, readiness, and replica failover.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d2d44570-2534-487b-b5e1-f6e0a2a58f0d

📥 Commits

Reviewing files that changed from the base of the PR and between 15b3870 and 61c0b91.

📒 Files selected for processing (9)

• .github/workflows/ci.yml
• Dailylog.md
• README.md
• api_router.py
• docker-compose.yml
• location_store.py
• main.py
• nginx/driver-location-load-balancer.conf
• test_redis_driver_location_store.py

---

📝 Walkthrough

Walkthrough

The driver-location API now supports Redis-backed shared state, readiness checks, optional instance IDs, and NGINX load balancing. Docker Compose runs the gateway, Redis, and API services. CI validates replica routing, shared state, and resilience after one replica stops.

Changes

Load-balanced driver-location API

Layer / File(s)	Summary
Redis-backed driver location storage location_store.py, test_redis_driver_location_store.py	Adds Redis CRUD, counting, clearing, serialization, readiness checks, store selection, and tests using FakeRedis.
API readiness and instance identification api_router.py, main.py	Adds GET /ready, returns HTTP 503 when the store is unavailable, selects Redis from DRIVER_LOCATION_REDIS_URL, and optionally adds X-Instance-ID.
Compose gateway and service wiring docker-compose.yml, nginx/driver-location-load-balancer.conf	Adds persistent Redis, internal API replicas, NGINX least-connections routing, health and readiness proxy routes, and gateway status monitoring.
Integration validation and documentation .github/workflows/ci.yml, README.md, Dailylog.md	Adds CI checks for routing, shared state, readiness, replica failure, and cleanup. Documents the deployment and records the infrastructure audit.
Estimated code review effort: 4 (Complex)	~45 minutes

Possibly related issues

• enhancement: add a gateway load balancer for horizontally scaled APIs #17 — The PR implements the issue’s NGINX gateway, API replicas, readiness checks, shared Redis state, and resilience testing.

Possibly related PRs

• CoreyLeath-code/Scalable-Event-Driven-Ride-Sharing-Platform#10 — The PR extends the Docker Compose setup, CI validation, and driver-location documentation introduced there.

Sequence Diagram(s)

sequenceDiagram
  participant CI
  participant NGINX
  participant APIReplica
  participant Redis
  CI->>NGINX: Poll gateway readiness
  NGINX->>APIReplica: Proxy readiness request
  APIReplica->>Redis: Check Redis readiness
  Redis-->>APIReplica: Return ping status
  APIReplica-->>NGINX: Return readiness response
  NGINX-->>CI: Return gateway status
  CI->>NGINX: Send driver-location requests
  NGINX->>APIReplica: Route requests across replicas
  APIReplica->>Redis: Read shared driver state
  Redis-->>APIReplica: Return driver data
  APIReplica-->>NGINX: Return response with instance ID
  NGINX-->>CI: Return routed response

Loading

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/log-load-balancer-gap

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🎉 This PR is included in version 1.1.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀