Skip to content

feat(gateway): add stateless gateway proxy mode#123

Merged
slow2342 merged 1 commit into
mainfrom
feat/gateway-proxy
Jun 13, 2026
Merged

feat(gateway): add stateless gateway proxy mode#123
slow2342 merged 1 commit into
mainfrom
feat/gateway-proxy

Conversation

@slow2342

Copy link
Copy Markdown
Owner

Summary

Add a stateless gateway proxy that routes client gRPC requests to the correct backend cluster node without participating in Raft consensus. Clients connect to the gateway instead of directly to cluster nodes.

Changes

  • src/gateway/mod.rs — Core module: BackendPool with Vec-based O(1) round-robin, leader discovery, TLS channel creation, auth forwarding helper, health check HTTP server, redirect connection caching.
  • src/gateway/kv_proxy.rs — KV service proxy (Put/Get/Delete/Range/Txn). Serializable reads route to any node, writes and linearizable reads route to leader.
  • src/gateway/cluster_proxy.rs — Cluster service proxy (MemberList/Add/Remove/Promote).
  • src/gateway/maintenance_proxy.rs — Maintenance service proxy (Defrag/Alarm/Status).
  • src/gateway/watch_proxy.rs — Watch proxy with bidirectional streaming via channel forwarding.
  • src/gateway/lease_proxy.rs — Lease proxy (4 unary + bidirectional KeepAlive streaming).
  • src/gateway/lock_proxy.rs — Lock proxy (Lock/Unlock/Query).
  • src/gateway/election_proxy.rs — Election proxy (3 unary + server-streaming Observe).
  • src/gateway/barrier_proxy.rs — Barrier proxy (Create/Release/Query).
  • src/gateway/queue_proxy.rs — Queue proxy (Enqueue/Dequeue/Peek).
  • src/gateway/session_proxy.rs — Session proxy (3 unary + bidirectional KeepAlive streaming).
  • src/gateway/auth_proxy.rs — Auth proxy (17 methods, macro-simplified).
  • src/lib.rs — Add pub mod gateway.
  • src/main.rs — CLI args: --gateway, --backends, --request-timeout-ms, --tls-ca/cert/key, --health-addr. Gateway mode entry point.
  • Cargo.toml — Enable tonic tls-ring feature.

Key design

  • Stateless: No Raft, no storage, no state — purely request forwarding.
  • Auth forwarding: authorization metadata preserved from client to backend.
  • TLS: Optional mutual TLS to backends via --tls-ca/cert/key.
  • Health check: GET /health/live (always OK), GET /health/ready (at least one backend reachable).
  • Redirect handling: On x-aether-leader redirect header, update leader tracking, cache new connection, retry.
  • Streaming: Bidirectional streams (Watch, Lease/Session KeepAlive) use mpsc channel forwarding. Server streams (Election Observe) forward directly.

Testing

  • cargo build — 0 warnings
  • cargo clippy -- -D warnings — 0 errors
  • cargo fmt -- --check — clean
  • cargo test --lib — 170 passed, 0 failed

How to verify

# Start a 3-node cluster
aether --node-id 1 --addr 127.0.0.1:2379 --backends 127.0.0.1:2379,127.0.0.1:2381,127.0.0.1:2383
aether --node-id 2 --addr 127.0.0.1:2381 --backends 127.0.0.1:2379,127.0.0.1:2381,127.0.0.1:2383
aether --node-id 3 --addr 127.0.0.1:2383 --backends 127.0.0.1:2379,127.0.0.1:2381,127.0.0.1:2383

# Start gateway
aether --gateway --addr 127.0.0.1:2399 --backends 127.0.0.1:2379,127.0.0.1:2381,127.0.0.1:2383

# Health check
curl http://127.0.0.1:9091/health/live
curl http://127.0.0.1:9091/health/ready

# Use gateway address (2399) instead of direct cluster addresses

Related issues

Refs #94

…uting

Implement a stateless gateway proxy that routes client gRPC requests to the
correct backend cluster node without participating in Raft consensus.

- 11 service proxies: KV, Cluster, Maintenance, Watch, Lease, Lock,
  Election, Barrier, Queue, Session, Auth
- Auth token forwarding via metadata preservation
- TLS support for backend connections (--tls-ca, --tls-cert, --tls-key)
- Request timeout with configurable --request-timeout-ms
- Leader redirect detection with automatic retry and connection caching
- O(1) round-robin load balancing via Vec + AtomicUsize
- Leader discovery on startup via MemberList RPC
- Health check HTTP endpoint (/health/live, /health/ready)
- CLI: --gateway, --backends, --health-addr
- Streaming proxy support: Watch, Lease KeepAlive, Session KeepAlive
  (bidirectional), Election Observe (server streaming)
@slow2342
slow2342 merged commit 6cf8757 into main Jun 13, 2026
7 checks passed
@slow2342
slow2342 deleted the feat/gateway-proxy branch June 13, 2026 07:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant