State Persistence Configuration¶

Doc Version: 1.0.0 Last Updated: 2026-06-09 Git Commit: ba6d6ddf Author: Lincoln

Document Version: 2.9.5 Applicable Version: v2.6.x Last Updated: 2026-06-09

Overview¶

JAiRouter supports state persistence functionality since v2.4.4, implementing a three-tier fallback strategy:

Redis (Tier 1) → H2 (Tier 2) → File (Tier 3)

Tier 1 (Redis): Highest priority, for distributed shared state
Tier 2 (H2): Default fallback layer, using existing StoreManager framework
Tier 3 (File): Ultimate fallback, for extreme scenarios

Configuration File¶

Basic Configuration¶

Configuration file location: src/main/resources/config/persistence/state-persistence-base.yml

jairouter:
  persistence:
    # Enable state persistence
    enabled: true

    # Redis configuration (Tier 1, optional: required only when replicas must share state)
    redis:
      enabled: false
      host: ${REDIS_HOST:localhost}
      port: ${REDIS_PORT:6379}
      password: ${REDIS_PASSWORD:}
      database: 0
      timeout: 3000        # Connect timeout (ms)
      ttl-days: 7          # State TTL (days)

    # H2 configuration (Tier 2) - default fallback layer
    h2:
      enabled: true
      data-dir: ./data
      database: jairouter_state

    # File configuration (Tier 3) - last-resort fallback layer
    file:
      enabled: true
      path: ./data/state
      compress: false

    # State recovery (on startup or via the recovery API)
    recovery:
      enabled: true
      auto-on-startup: true
      timeout: 10000       # Recovery timeout (ms)
      parallel: false

    # Tier fallback policy
    fallback:
      auto-detect: true
      health-check-interval: 30   # seconds
      retry-interval: 10          # seconds
      max-retries: 3
      sync-on-recovery: true

State Types¶

Supported state types for persistence:

State Type	Description	State Data
`CIRCUIT_BREAKER`	Circuit breaker state	State, failure count, success count, last failure time
`LOAD_BALANCER`	Load balancer state	Instance weights, active connections
`RATE_LIMITER`	Rate limiter state	Token count, algorithm type, config parameters
`MODEL_STATS`	Model statistics	Request count, success count, latency stats
`CUSTOM`	Custom state	User-defined arbitrary state

API Endpoints¶

State Persistence Management API¶

Endpoint	Method	Description
`/api/state-persistence/status`	GET	Get storage tier status
`/api/state-persistence/details`	GET	Get all state details
`/api/state-persistence/sync`	POST	Manual sync trigger
`/api/state-persistence/recovery/all`	POST	Recover all states
`/api/state-persistence/recovery/{type}/{id}`	POST	Recover single state
`/api/state-persistence/recovery/rate-limiter/{limiterId}`	POST	Recover rate limiter state

Example Requests¶

Get storage tier status:

curl -X GET http://localhost:8080/api/state-persistence/status \
  -H "Authorization: Bearer {token}"

Response example:

{
  "success": true,
  "data": {
    "activeTier": "h2",
    "tiers": {
      "redis": false,
      "h2": true,
      "file": true
    },
    "stats": {
      "circuitBreakerCount": 5,
      "loadBalancerCount": 6,
      "rateLimiterCount": 0
    }
  }
}

Performance Metrics¶

Metric	Target	Description
Single state save	< 100ms	H2 layer latency
Redis state save	< 50ms	Redis layer latency
Batch save throughput	> 100 ops/s	100 states
Recovery time	< 10s	Startup recovery
Fallback switch	< 1s	Tier switch latency

Best Practices¶

1. Production Environment Recommended Configuration¶

jairouter:
  persistence:
    enabled: true
    redis:
      enabled: true  # Recommended for production
    h2:
      enabled: true  # As fallback layer
    file:
      enabled: true  # As ultimate fallback

2. Development Environment Configuration¶

jairouter:
  persistence:
    enabled: true
    redis:
      enabled: false  # Optional for development
    h2:
      enabled: true
    file:
      enabled: false  # Optional for development

3. Monitoring Recommendations¶

Monitor activeTier changes to detect fallback switches
Monitor pendingSyncCount to ensure normal state sync
Regularly check health status to ensure storage tier availability

Failure Recovery¶

Automatic Fallback¶

When a tier is unavailable, the system automatically switches to the next tier:

Redis unavailable → Automatic switch to H2
H2 unavailable → Automatic switch to File
All tiers unavailable → Return error

Manual Recovery¶

# Recover all states
curl -X POST http://localhost:8080/api/state-persistence/recovery/all

# Recover single circuit breaker state
curl -X POST http://localhost:8080/api/state-persistence/recovery/circuit-breaker/ollama-1

# Recover rate limiter state
curl -X POST http://localhost:8080/api/state-persistence/recovery/rate-limiter/global

Change Log¶

Version	Date	Changes
1.0	2026-04-26	Initial state persistence configuration document