Status: current Owns: the Redis persistent state a business service keeps — state: keys with no TTL and an atomic rebuild from the database

Uniform: library/connector

Duty sections that apply:

• all: L-MAIN, L-ENGINES, L-TESTS, L-TEST-SCRIPT, L-PACK-TESTS, L-PINS, L-NO-FILE-RANGE, L-CHANGELOG, L-README, L-README-REGION, L-CONSUMER
• connector: L-CONNECTOR-ENV

@onlineapps/conn-base-state

Redis persistent state connector for OA Drive microservices. Unlike conn-base-cache, state keys have no TTL — they persist until explicitly deleted or rebuilt from DB.

Key differences from conn-base-cache

| Feature | conn-base-cache | conn-base-state | |---------|----------------|-----------------| | Key prefix | cache:<service>: | state:<service>: | | TTL | Required (default 3600s) | Never — keys persist | | Purpose | Temporary caching | Operational state (entitlements, credits) | | Rebuild | No rebuild concept | rebuildFromDB() — atomic SCAN+DEL+repopulate | | Retry | Hard cutoff after N attempts | Exponential backoff, never gives up |

Quick Start

const StateConnector = require('@onlineapps/conn-base-state');

const state = new StateConnector({
  host: '127.0.0.1',
  port: 6379,
  serviceName: 'meta',
  logger                       // required: info/warn/error/debug
});

await state.connect();

// Set/get state (no TTL)
await state.set('entitlement:100:1', '1');
const val = await state.get('entitlement:100:1');

// Rebuild from DB — buildVersion is required, the connector cannot know it
const { flushed, written, epoch } = await state.rebuildFromDB(async (pipeline) => {
  pipeline.set('entitlement:100:1', '1');
  pipeline.sadd('entitlement:100:bundles', '1');
}, { buildVersion: process.env.BUILD_ID });

The projection epoch marker

rebuildFromDB() flushes the whole state:<service>: prefix before it repopulates it. Between those two halves — and after a crash that interrupts them — the prefix is empty, and an empty prefix is indistinguishable from a tenant that genuinely has no entitlements: the gateway answered 402 to everyone until meta was restarted by hand.

The marker makes the two states tellable apart.

| | | |---|---| | Key | state:<service>:__epoch (logical __epoch, exported as StateConnector.PROJECTION_EPOCH_KEY) | | Value | JSON { "at": "<ISO-8601 UTC instant>", "build": "<buildVersion the caller passed>" } | | Written | as the last command of the same pipeline the projection is written with, by rebuildFromDB() — never separately | | Exists | exactly when a rebuild completed | | Absent | before the first rebuild, during one (the flush removes the previous marker), and after one whose populate callback threw | | Writer | the connector, i.e. the service that owns the prefix. Readers (gateway, monitoring) read only — docs/standards/redis-key-contract.md rule 3 |

await state.hasProjection();       // → true | false   (EXISTS __epoch)
await state.getProjectionEpoch();  // → { at, build } | null

getProjectionEpoch() returns null only when the key is absent. Content that cannot be parsed, or that does not carry both fields, throws — null means "no projection", and answering that for damaged content would hide the damage behind the one value callers act on.

An ioredis pipeline is a batch, not a MULTI transaction. What the ordering buys is that the marker can never be visible before the records it vouches for, and that a populate callback which throws produces no marker at all; a marker command Redis rejects makes rebuildFromDB() throw rather than report a rebuild that did not complete.

Return value

{ flushed: 12, written: 340, epoch: { at: '2026-09-07T09:31:04.882Z', build: '1.4.2' } }

written counts the records the populate callback wrote. The marker is the connector's own bookkeeping, so it is reported as epoch and not counted in written.

API

See JSDoc in src/index.js for full documentation.

Testing

npm run test:unit                                                  # mocked ioredis, no stack
REDIS_HOST=127.0.0.1 REDIS_PORT=33030 npm run test:integration     # live Redis
npm test                                                           # both tiers

The integration tier isolates itself by prefix, not by database: every suite uses a service name carrying its own pid, so it can never see or delete another run's keys, and a raw prefix-less observer client makes the assertions on absolute key names.

Mock connector available for tests — it mirrors the epoch contract, including the required buildVersion:

const { MockStateConnector } = require('@onlineapps/conn-base-state');
const state = new MockStateConnector({ serviceName: 'test' });