Caching Implementation Guidelines

Standard

Distributed cache: Azure Cache for Redis
Provisioning: Terraform libraries repo: az-modules-tf
Landing zone implementation: az-adc-lz-tf
Integration: framework-nodejs-caching
Pattern: Cache-aside
TTL: Mandatory for all keys

1. Infrastructure Requirements

Fluxx should use Azure Cache for Redis provisioned via Terraform modules from:

• az-modules-tf
• Implemented within the Fluxx landing zone in az-adc-lz-tf

Required characteristics:

• SKU/tier must support:
  • Microsoft Entra ID authentication
  • Disabling access keys
• Access key authentication disabled
• Entra ID authentication enabled
• Private endpoint enforced
• Private DNS configured
• Deployed within Fluxx ALZ networking boundaries

Fluxx services must assume:

• No key-based authentication
• No public endpoint access
• Redis reachable only via private networking
• Identity-based authentication only

2. Authentication Model

Azure environments

• Services authenticate using Managed Identity
• Entra ID token is acquired by the framework
• Redis access is authorized via Entra ID

Local development

• May use username/password only if explicitly configured
• Must not rely on access keys in non-local environments

3. Framework Integration

Required package

import 'framework-nodejs-caching';

Redis client creation

In src/index.ts, after AppConfig initialization:

await frameworkApp.initAppConfig({
  useEnvironmentVariables: true,
});
await frameworkApp.createRedisClient('RedisClient');

Configuration source:

• AppConfig key: FRAMEWORK_REDIS_CONFIG
• Client selected by matching "name": "RedisClient"

Redis configuration must not be hardcoded

4. AppConfig Structure

Example structure for FRAMEWORK_REDIS_CONFIG:

[
  {
    "name": "RedisClient",
    "config": {
      "host": "<redis-host>",
      "port": 6380,
      "usetls": true,
      "resiliencePolicy": {
        "retryOptions": {
          "enabled": true,
          "interval": 200,
          "maxAttempts": 2,
          "intervalType": "regular"
        },
        "circuitBreakerOptions": {
          "enabled": true,
          "errorThresholdTimespan": 5000,
          "errorThresholdPercentage": 25,
          "resetTime": 5000,
          "requestTimeout": 1500
        }
      }
    }
  }
]

5. Application ID Standard

Each Fluxx service must define an appId.

Rules:

• Must be lowercase
• Must be prefixed with fluxx-
• Must represent the service boundary

Examples:

fluxx-file-intake
fluxx-registration
fluxx-extractor
fluxx-statuscheck

Recommended implementation:

export const APP_ID = 'fluxx-file-intake';

appId must not be derived from Entra client IDs or GUIDs

6. Key Format Standard

{appId}:v1:{resource}:{identifier}

Examples:

fluxx-file-intake:v1:client:fd394f62-da0e-46f0-977c-65ad2c0c2aee
fluxx-file-intake:v1:status:job-edc26186-a780-46e6-98d3-015da9b656a3

Rules:

• appId must be first segment
• Version segment required and must follow appId
• Resource segment required and singular
• Identifier must uniquely represent the cached object
• TTL required on every key
• No PII stored
• No document payloads stored

Versioning

If key schema changes:

• Increment version segment (v2, v3) for schema changes
• Allow coexistence during migration
• Remove legacy keys after migration window

7. Cache Pattern

Required: Cache-aside

Read flow:

1. Attempt GET from Redis
2. On miss, retrieve from authoritative data store
3. Write to Redis with TTL
4. Return value

Write flow:

1. Persist to authoritative data store
2. Invalidate or update cache key

No write-through. No background refresh unless explicitly designed

8. TTL Standards

TTL is mandatory. Redis does not enforce TTL automatically

Defined ranges:

• Auth metadata: 5 to 15 minutes
• Config/reference: 5 to 60 minutes
• Status responses: 10 to 60 seconds
• Idempotency keys: 1 to 24 hours aligned to retry window

TTL Jitter

Apply ±10 percent jitter to avoid synchronized expiration.

9. Eviction Policy

Preferred policy: volatile-lru

Reason:

• Only keys with TTL are eligible for eviction.
• Fluxx requires TTL on all keys.

Keys without TTL will not be evicted under this policy.

10. Stampede Protection

For hot keys:

• Implement in-process single-flight locking around cache-miss path
• Apply TTL jitter
• Avoid synchronized expirations

11. Size and Payload Constraints

• Recommended max value size: 256 KB
• Do not cache large JSON payloads
• Do not cache document contents
• Prefer caching identifiers over full objects
• Avoid high-cardinality keys without TTL

12. Kubernetes Client Best Practices

• Stagger pod startup to avoid simultaneous connection spikes
• Avoid reconnection storms during rolling deployments
• Ensure sufficient CPU and memory for pods
• Reuse Redis connections via the framework client
• Avoid excessive connection churn

13. Connection and Resilience

• Use framework resiliencePolicy configuration
• Limit retry attempts
• Fail fast on sustained outages
• Services must degrade safely on Redis failure
• Redis outages must not corrupt workflow state

14. Memory Constraints (In-Pod)

Redis is the shared cache layer

In-pod memory caching:

• Only request-scoped memoization
• Strict size bounds required
• Micro-TTL only
• Must not affect correctness

Each service must:

• Define container memory limits
• Avoid unbounded maps
• Monitor heap usage
• Handle OOM restarts safely

Definition of Done for Redis Adoption

• Azure Cache for Redis provisioned via az-modules-tf
• Implemented within Fluxx landing zone in az-adc-lz-tf
• SKU supports Entra ID and disabled access keys
• Private endpoint connectivity validated
• RedisClient created via framework
• AppConfig entry defined
• All cache writes include TTL
• Keys follow naming convention
• No PII stored in Redis
• Services operate correctly with cold cache