Spring Cloud Gateway

Overview

This service exposes WebSocket and HTTP endpoints for all clients. It routes requests to backend services and integrates with the TCP Proxy Service for Telnet clients.

Responsibilities

• Terminate TLS and enforce authentication for admin routes
• Upgrade WebSocket connections and route to the correct tenant
• Apply rate limits and basic abuse protections
• Relay traffic to the Game Session Service and other backends

Architecture / Design Notes

• Maintains persistent WebSocket sessions and supports raw TCP through a proxy.
• Event-driven updates synchronize game state across connected players.
• Includes a fallback mechanism so players with unstable connections can rejoin seamlessly.
• Gateway restarts are transparent thanks to the layered reconnection model outlined in Reconnection Strategy.
• Applies rate limiting and authentication filters for admin endpoints.
• Relies on the Game Session Service for gameplay login and session management.
• Terminates external TLS and forwards traffic to backend services using mutual TLS, as described in the Security Architecture.
• Hostnames or path prefixes map incoming connections to a tenantId so the gateway can route players to the correct game instance. See Multi-Tenancy.
• Utilizes the Shared Libraries for DTO definitions, logging interceptors, and Micrometer metrics.

Key Features

• Central API gateway and authentication point.
• Real-time state synchronization for multiplayer actions.
• Reconnection support for dropped clients.
• Routes REST and gRPC traffic to appropriate backend services.
• Supports dynamic route management via the GatewayManagementService gRPC API.

Data Model

The gateway is stateless and sits in the DMZ alongside the TCP Proxy Service. Route configurations are stored in application-*.yml and reloaded on startup. No persistent database is required. The default configuration defines routes for the core services so Docker Compose environments work out of the box.

Filter Chain

• Authentication, rate limiting, and logging filters run before routing.
• WebSocket upgrades are handled with heartbeat and idle timeout logic.

Key Routes

• /api/session/** → Game Session Service (WebSocket and REST endpoints).
• /api/admin/** → Logging & Admin Service with JWT authentication.
• /api/design/** → Game Design Service for content management.

Dependencies

• Internal:
  • Game Session Service and other microservices over gRPC.
  • TCP Proxy Service forwards Telnet traffic into the gateway.
• External: Spring Cloud Gateway infrastructure.

See Gateway Architecture, Deployment Environments, and Protocol Bridging for details on shared infrastructure components.

Operational Notes

• Runs as a stateless gateway Deployment in Kubernetes, typically exposed via a load balancer service.
• /actuator/health endpoints are used for readiness and liveness probes.
• Prometheus scrapes metrics such as connection counts while Fluent Bit forwards structured logs to Elasticsearch; tracing integrates with OpenTelemetry.
• Deployment Environments explains how routes and certificates differ between Docker Compose and production clusters.

Proto Files

Gateway-related proto definitions are stored in ../../../../protos/spring-cloud-gateway/v1. After edits, run ./gradlew generateProto to regenerate gateway stubs. The gateway_management_service.proto file defines gRPC endpoints for remotely adding or removing routes at runtime.

📚 Related Documentation

• System Architecture Overview

• Reconnection Strategy

• Security Architecture

• Multi-Tenancy

• Service Responsibility Matrix

• User Journeys – Player Login and Gameplay

• gRPC API Style & Versioning Guidelines

• Shared Libraries Overview

• Testing Strategy

• CI/CD Pipeline

• Logging & Monitoring

• Backup & Disaster Recovery

• System Architecture Diagram

• System Context Diagram

Future Enhancements

• Connection metrics and throttling.
• Horizontal scaling for high concurrency.
• Remote route configuration over gRPC.