docs: reorder & testing

gateway/internal/config/config.go

@@ -166,6 +166,14 @@ const (
 	// rate-limit burst.
 	authenticatedGRPCMessageClassRateLimitBurstEnvVar = "GATEWAY_AUTHENTICATED_GRPC_ANTI_ABUSE_MESSAGE_CLASS_RATE_LIMIT_BURST"
 
+	// sessionCacheMaxEntriesEnvVar names the environment variable that configures
+	// the in-memory session cache LRU bound (entries).
+	sessionCacheMaxEntriesEnvVar = "GATEWAY_SESSION_CACHE_MAX_ENTRIES"
+
+	// sessionCacheTTLEnvVar names the environment variable that configures the
+	// in-memory session cache safety-net TTL applied to every cached entry.
+	sessionCacheTTLEnvVar = "GATEWAY_SESSION_CACHE_TTL"
+
 	// replayRedisKeyPrefixEnvVar names the environment variable that configures
 	// the Redis key prefix used for authenticated replay reservations.
 	replayRedisKeyPrefixEnvVar = "GATEWAY_REPLAY_REDIS_KEY_PREFIX"
@@ -309,6 +317,9 @@ const (
 	defaultAuthenticatedGRPCMessageClassRateLimitRequests = 60
 	defaultAuthenticatedGRPCMessageClassRateLimitBurst = 20
 
+	defaultSessionCacheMaxEntries = 50_000
+	defaultSessionCacheTTL = 10 * time.Minute
+
 	defaultReplayRedisKeyPrefix = "gateway:replay:"
 	defaultReplayRedisReserveTimeout = 250 * time.Millisecond
 
@@ -521,6 +532,21 @@ type AuthenticatedGRPCConfig struct {
 	AntiAbuse AuthenticatedGRPCAntiAbuseConfig
 }
 
+// SessionCacheConfig describes the bounds of the gateway's in-memory
+// session cache. The cache fronts every authenticated request and
+// falls back to a synchronous backend lookup on miss; push-event
+// driven invalidations flip cached records to revoked status without
+// a backend roundtrip.
+type SessionCacheConfig struct {
+	// MaxEntries bounds the LRU. Zero or negative values fall back to
+	// the package default at construction time.
+	MaxEntries int
+
+	// TTL is the safety-net freshness window applied to every cached
+	// entry. Zero or negative values fall back to the package default.
+	TTL time.Duration
+}
+
 // ReplayRedisConfig describes the Redis namespace and timeout used for
 // authenticated replay reservations.
 type ReplayRedisConfig struct {
@@ -577,6 +603,10 @@ type Config struct {
 	// Streams; Redis is now used only for replay reservations.
 	Redis redisconn.Config
 
+	// SessionCache configures the in-memory session cache fronting
+	// every authenticated request.
+	SessionCache SessionCacheConfig
+
 	// ReplayRedis configures the Redis-backed authenticated ReplayStore.
 	ReplayRedis ReplayRedisConfig
 
@@ -699,6 +729,15 @@ func DefaultReplayRedisConfig() ReplayRedisConfig {
 	}
 }
 
+// DefaultSessionCacheConfig returns the default LRU bound and safety-net TTL
+// used by the in-memory session cache.
+func DefaultSessionCacheConfig() SessionCacheConfig {
+	return SessionCacheConfig{
+		MaxEntries: defaultSessionCacheMaxEntries,
+		TTL: defaultSessionCacheTTL,
+	}
+}
+
 // DefaultBackendConfig returns the default backend settings used for the
 // gateway → backend HTTP and gRPC conversation. URL fields stay empty and
 // must be supplied explicitly via env vars.
@@ -727,6 +766,7 @@ func LoadFromEnv() (Config, error) {
 		AdminHTTP: DefaultAdminHTTPConfig(),
 		AuthenticatedGRPC: DefaultAuthenticatedGRPCConfig(),
 		Redis: redisconn.DefaultConfig(),
+		SessionCache: DefaultSessionCacheConfig(),
 		ReplayRedis: DefaultReplayRedisConfig(),
 		ResponseSigner: DefaultResponseSignerConfig(),
 	}
@@ -895,6 +935,18 @@ func LoadFromEnv() (Config, error) {
 	}
 	cfg.Redis = redisConn
 
+	sessionCacheMaxEntries, err := loadIntEnvWithDefault(sessionCacheMaxEntriesEnvVar, cfg.SessionCache.MaxEntries)
+	if err != nil {
+		return Config{}, err
+	}
+	cfg.SessionCache.MaxEntries = sessionCacheMaxEntries
+
+	sessionCacheTTL, err := loadDurationEnvWithDefault(sessionCacheTTLEnvVar, cfg.SessionCache.TTL)
+	if err != nil {
+		return Config{}, err
+	}
+	cfg.SessionCache.TTL = sessionCacheTTL
+
 	rawReplayRedisKeyPrefix, ok := os.LookupEnv(replayRedisKeyPrefixEnvVar)
 	if ok {
 		cfg.ReplayRedis.KeyPrefix = rawReplayRedisKeyPrefix