Add Valkey distributed cache for horizontal scaling

  Implement distributed caching using Valkey (Redis-compatible) to enable
  horizontal scaling of Trino Gateway across multiple instances. This allows
  query metadata to be shared between gateway instances, ensuring consistent
  routing regardless of which instance receives a request.

  Key features:
  - 3-tier caching architecture: L1 (Guava local) → L2 (Valkey distributed) → L3 (PostgreSQL)
  - Graceful degradation when Valkey unavailable (falls back to database)
  - Configurable health checks and connection pooling
  - Cache metrics (hits, misses, writes, errors, hit rate)
  - Write-through caching for backend and routing group lookups
  - Lazy-loading for external URL lookups
  - Convention over Configuration with sensible defaults

  Implementation:
  - Add ValkeyConfiguration with 11 configurable parameters (minimal 3 required)
  - Create DistributedCache interface and ValkeyDistributedCache implementation
  - Integrate distributed cache into BaseRoutingManager routing logic
  - Use modern Duration API (no deprecated methods)
  - Add comprehensive input validation and error handling
  - Include 31 unit tests (16 config + 15 cache tests)

  Configuration:
  valkeyConfiguration:
    enabled: true
    host: valkey.internal
    port: 6379
    password: ${VALKEY_PASSWORD}

  Documentation includes:
  - Quick start guide with minimal configuration
  - Full configuration reference with tuning guidelines
  - Deployment scenarios (single vs. multi-instance)
  - Performance tuning recommendations
  - Security best practices
  - Architecture documentation and troubleshooting

  Single-instance deployments don't need distributed caching - local Guava
  cache is sufficient. Multi-instance deployments benefit from shared cache
  for consistent query routing.

Author: hpopuri2

docs/config.yaml

@@ -18,3 +18,4 @@ valkeyConfiguration:
   host: localhost
   port: 6379
   # password: ${VALKEY_PASSWORD}  # Uncomment if Valkey requires AUTH
+  # cacheTtlSeconds: 1800  # Cache TTL in seconds (default: 1800 = 30 minutes)

docs/installation.md

@@ -176,8 +176,14 @@ valkeyConfiguration:
   host: valkey.internal.prod
   port: 6379
   password: ${ENV:VALKEY_PASSWORD}
+  cacheTtlSeconds: 1800  # Cache TTL (default: 1800 = 30 minutes)
 ```
 
+**Optional parameters**: You can customize `cacheTtlSeconds` based on your query duration:
+- Short queries (< 5 min): 600 seconds (10 minutes)
+- Default queries: 1800 seconds (30 minutes)
+- Long-running queries: 3600 seconds (1 hour)
+
 See [Valkey distributed cache configuration](valkey-configuration.md) for
 detailed configuration options, deployment scenarios, and performance tuning.
 

docs/valkey-configuration.md

@@ -187,7 +187,9 @@ valkeyConfiguration:
   host: ${VALKEY_INTERNAL_HOST}
   port: 6379
   password: ${VALKEY_PASSWORD}
+```
 
+```bash
 # Environment variables (set in deployment)
 export VALKEY_INTERNAL_HOST=valkey.vpc.internal
 export VALKEY_PASSWORD=$(vault read -field=password secret/valkey)

gateway-ha/config.yaml

@@ -30,3 +30,4 @@ valkeyConfiguration:
   host: localhost
   port: 6379
   # password: ${VALKEY_PASSWORD}  # Uncomment if Valkey requires AUTH
+  # cacheTtlSeconds: 1800  # Cache TTL in seconds (default: 1800 = 30 minutes)

gateway-ha/src/main/java/io/trino/gateway/ha/module/HaGatewayProviderModule.java

@@ -40,7 +40,6 @@
 import io.trino.gateway.ha.config.OAuth2GatewayCookieConfigurationPropertiesProvider;
 import io.trino.gateway.ha.config.RoutingRulesConfiguration;
 import io.trino.gateway.ha.config.RulesExternalConfiguration;
-import io.trino.gateway.ha.config.UserConfiguration;
 import io.trino.gateway.ha.config.ValkeyConfiguration;
 import io.trino.gateway.ha.persistence.JdbcConnectionManager;
 import io.trino.gateway.ha.persistence.RecordAndAnnotatedConstructorMapper;
@@ -55,9 +54,7 @@
 import io.trino.gateway.ha.router.QueryHistoryManager;
 import io.trino.gateway.ha.router.ResourceGroupsManager;
 import io.trino.gateway.ha.router.RoutingGroupSelector;
-import io.trino.gateway.ha.router.RoutingManager;
 import io.trino.gateway.ha.router.ValkeyDistributedCache;
-import io.trino.gateway.ha.security.ApiAuthenticator;
 import io.trino.gateway.ha.security.AuthorizationManager;
 import io.trino.gateway.ha.security.LbAuthorizer;
 import io.trino.gateway.ha.security.LbFormAuthManager;