Redis Cache ExecModule

Overview

RedisCacheModule connects a ValkyrAI workflow to one TLS-enabled Redis database. Version 2.0 replaces the legacy process-local simulation with real bounded Redis commands, complete Workflow Studio metadata, IntegrationAccount-only credentials, normalized outputs, and credential-safe failures.

The module is registered as:

com.valkyrlabs.workflow.modules.cache.RedisCacheModule

It supports string keys, counters, TTL management, one-page cursor scans, and Pub/Sub publishing. It does not expose KEYS, Lua, arbitrary commands, list/hash/set command families, transactions, or pipelines.

Usage

1. Create a Redis IntegrationAccount whose accountId is a rediss:// endpoint.
2. Store the Redis password or token in an IntegrationAccount SecureField and mark the account READY.
3. Bind that account through the module's redisAccount configuration.
4. Select one supported operation and provide only its required inputs.
5. Execute the workflow and inspect status, the operation-specific result, attempts, and error.

Every execution opens a bounded TLS connection, sends at most one Redis command, closes the connection, and reports attempts: 1 if a command was attempted.

Inputs

Input	Required	Description
operation	Yes	get, set, delete, exists, increment, decrement, expire, ttl, scan, or publish.
key	By operation	Redis key, at most 1,024 UTF-8 bytes. Required except for scan and publish.
value	For set	String or JSON-serializable value. Serialized size is capped at 1 MiB.
ttlSeconds	By operation	Optional set TTL or required expire TTL. Range: 1–2,592,000 seconds. Use 0 to omit a set TTL.
onlyIfAbsent	No	Applies Redis NX semantics to set. Default: false.
delta	No	Positive counter delta from 1 through 1,000,000,000. Default: 1.
pattern	For scan	Redis glob pattern, at most 512 UTF-8 bytes. Default: *.
cursor	For scan	Decimal cursor returned by the previous nextCursor. Default: 0.
scanCount	For scan	Redis SCAN count hint from 1 through 500. Default: 100.
channel	For publish	Pub/Sub channel, at most 512 UTF-8 bytes.
message	For publish	Pub/Sub message, at most 1 MiB.

Raw password, apiKey, api_key, token, secret, auth, redisUrl, redis_url, mock, and test fields are rejected in workflow input and module configuration.

Outputs

Output	Description
status	success or error.
operation	Normalized Redis operation.
key	Validated key for a key-scoped operation.
value	String value for get, or integer value for counter operations.
exists	Whether the key exists for get or exists.
result	Normalized Redis reply for set, delete, expire, or publish.
ttlSeconds	Redis TTL: -2 for an absent key, -1 for a persistent key, or remaining seconds.
items	Keys returned by one SCAN page.
count	Number of keys returned by the SCAN page.
nextCursor	Opaque cursor for the next SCAN page.
hasMore	Whether Redis indicates that another SCAN page may exist.
attempts	Redis command attempts. Validation failures report 0; provider attempts report 1.
error	Safe object with code, message, and retryable.

Credentials, the full endpoint, raw provider exceptions, and command payloads are not returned.

IntegrationAccount Requirements

The bound IntegrationAccount must:

• have status exactly READY;
• put a TLS endpoint such as rediss://cache.example.com:6380/0 in accountId;
• put the optional Redis ACL username in username;
• put the Redis password or access token in the password SecureField, with apiKey accepted as a compatibility SecureField;
• contain no credentials in accountId, query parameters, workflow input, or module configuration;
• use a least-privilege Redis ACL limited to the documented keyspace and command allowlist.

Plaintext redis:// endpoints are rejected. The endpoint cannot contain user info, a query, or a fragment. Database indexes are limited to 0–255.

Configuration

Configuration	Default	Constraint
redisAccount	None	Required READY IntegrationAccount.
operation	None	Required allowlisted operation.
ttlSeconds	0	0–2,592,000; positive only for set or expire.
onlyIfAbsent	false	Redis NX behavior for set.
delta	1	1–1,000,000,000.
pattern	*	At most 512 UTF-8 bytes.
cursor	0	Decimal Redis cursor.
scanCount	100	1–500.
timeoutMs	5000	250–15,000 milliseconds.

The module does not accept a host, port, password, or provider URL as workflow configuration. Connection identity is owned by the IntegrationAccount.

Operations

get, exists, and ttl

Read one string key, test its existence, or read its remaining TTL. These operations send one command and do not retry automatically.

set

Writes one string value. Non-string input is serialized to bounded JSON. A positive ttlSeconds uses atomic Redis expiration semantics; onlyIfAbsent=true adds NX. NOT_STORED means the NX condition prevented the write.

delete and expire

Deletes one key or assigns a TTL. The integer/boolean provider result is normalized under result. These operations are writes even when Redis reports that no key changed.

increment and decrement

Uses atomic Redis integer commands with a positive bounded delta. Existing non-integer values fail as provider command errors.

scan

Reads one cursor page using SCAN, never blocking KEYS. Pass nextCursor back as cursor until hasMore is false. scanCount is a provider hint, not an exact page-size guarantee.

publish

Publishes one bounded message to one bounded channel and returns the subscriber count under result. Pub/Sub delivery is ephemeral and non-idempotent.

Errors and Failure Modes

Code	Meaning	Recovery
VALIDATION_ERROR	Missing or malformed input, unsafe endpoint, raw credential field, invalid size, or operation-specific constraint.	Correct the named field. No Redis command was sent.
UNSUPPORTED_OPERATION	The requested operation is outside the allowlist.	Select a documented operation; migrate legacy pipeline/list/hash/set/Lua workflows explicitly.
INTEGRATION_ACCOUNT_ERROR	No account is bound, status is not READY, or the SecureField credential is absent.	Repair and rebind the Redis IntegrationAccount.
REDIS_COMMAND_ERROR	TLS connection, authentication, timeout, provider command, or response handling failed.	Verify Redis availability and ACLs. Reconcile write state before retrying.

Provider exception text is deliberately not returned because Redis errors can echo keys, endpoints, usernames, or credential material. The module never silently switches to local memory.

Example

Store one JSON value for five minutes:

{
  "operation": "set",
  "key": "customer:42:summary",
  "value": {
    "tier": "pro",
    "risk": "low"
  },
  "ttlSeconds": 300,
  "onlyIfAbsent": false
}

Expected normalized result:

{
  "status": "success",
  "operation": "set",
  "key": "customer:42:summary",
  "result": "OK",
  "attempts": 1
}

Notes

• Pagination is explicit and bounded to one SCAN page per execution. Redis may return zero keys before the cursor reaches 0.
• The module sends at most one provider command and does not automatically retry reads or writes. This prevents silent duplicate increments and Pub/Sub sends.
• set with the same value is naturally repeatable, but the module is classified non-idempotent because increment, decrement, delete, expire, and publish have stateful side effects.
• No operation supports dry-run. Use NX or a caller-owned key convention when conditional writes are required.
• Redis Pub/Sub does not persist messages or guarantee that a subscriber consumed them. Reconcile business-critical delivery through a durable system instead.
• The repository suite does not use a live Redis credential. It deterministically verifies request normalization, account enforcement, endpoint validation, size limits, secret redaction, error behavior, annotation scanning, and catalog serialization. Live TLS connectivity and provider ACL behavior remain a deployment-time boundary.