@dokebi/cache-redis

The Redis driver of @dokebi/cache. It is not a plugin. Its package.json has no dokebi manifest, so dokebi add refuses it. Add it with npm install @dokebi/cache-redis. core ^0.4.0, Node 24.0.0 or later, version 0.4.1 (unpublished). AI agents start with AI.md.

Configuration

Write driver: redis on a dokebi-cache backend. The option schema and validation live in @dokebi/cache.

options:
  dokebi-redis:
    connections:
      main:
        url: redis://127.0.0.1:6379/0
  dokebi-cache:
    backends:
      shared:
        driver: redis
        connection: main
        namespace: my-service
        ttlMs: 60000
        maxEntryBytes: 65536

connection is a name that exists in options.dokebi-redis.connections. Addresses and namespaces never get invented defaults. dokebi-cache prepares the dokebi-redis dependency automatically and imports this package. Without it, dokebi-cache fails to start with DRIVER_NOT_INSTALLED and dokebi doctor reports DRIVER_PACKAGE_MISSING. The backend option maxPending was called maxPendingOperations before 0.4.0 (still accepted with a warning).

Public API

• createRedisCacheDriver(connection, options, logger?): CacheDriver — dokebi-cache calls it. connection is a dokebi-redis RedisConnection; options is validated again with parseRedisCacheBackend (from @dokebi/cache); logger is optional.
• peerDependencies: @dokebi/core, @dokebi/cache, @dokebi/redis.

Behavior

backend.get(key) returns unknown, or undefined when missing. null is a normal value. set(key, value, { ttlMs? }) resolves when stored, and delete(key) returns whether an existing value was removed. TTL is 1–2147483647 ms; there is no 0 or unlimited.

A JSON snapshot is made before storing and independent data is returned on every read. It reuses the J1: UTF-8 format of @dokebi/cache/codec, and maxEntryBytes includes the prefix. Finite numbers, safe integers and ordinary JSON data are supported. Functions, classes, cycles, getters, proxies, sparse arrays and similar are rejected. A corrupt value is reported as CORRUPT_VALUE, never hidden as a miss.

By default at most 4096 operations are in flight (maxPending), and writes in flight hold at most 64 MiB of encoded values (maxPendingBytes, at least maxEntryBytes); both are backend options in dokebi.yaml (D-0106). A get reserves nothing. Past a limit an operation fails with QUEUE_FULL without being sent, which dokebi-web answers as a retryable 503 CACHE_BUSY. When outside code writes a huge invalid value into Redis, this driver does not limit the SDK's receive allocation in advance.

At shutdown it blocks new commands and waits a bounded time for submitted ones. The shared connection is never closed (dokebi-redis owns it). Deleting a whole namespace, KEYS, FLUSH and changing server eviction are not offered.

A key is a non-empty, well-formed UTF-16 string, by default at most 1024 UTF-8 bytes. Stored keys are separated by namespace, feature kind and SHA-256. Tokens, original values and addresses never appear in error messages; a failure's cause is the RedisError, which names none of them.

Error classification

• Redis errors are classified by structure, not instanceof: error.plugin === 'dokebi-redis' && error.outcome === 'not-submitted' means the command was never sent, and code === 'COMMAND_REJECTED' means the server rejected it with an error reply such as OOM (both PROVIDER_FAILED, D-0049). Other failures of a changing command (timeout, lost connection) are OUTCOME_UNKNOWN, and a failed read is PROVIDER_FAILED. A duplicated install of @dokebi/redis does not change the classification.
• OUTCOME_UNKNOWN may mean the change already happened, so it is never retried automatically.
• PROVIDER_FAILED and OUTCOME_UNKNOWN keep the Redis error as their cause; through dokebi-web a transient one answers @dokebi/redis's retryable 503 (D-0102).

The runnable example is example 15. Operations checks such as Redis HA and the fault matrix are tracked in OPS-002.