pikku-redis

name

pikku-redis

description

Use when setting up Redis-backed services in a Pikku app. Covers channel stores, workflow services, secret services, event hubs, agent runs, and deployment services backed by Redis. TRIGGER when: code uses RedisChannelStore, RedisWorkflowService, RedisSecretService, or user asks about Redis setup with Pikku. DO NOT TRIGGER when: user asks about BullMQ queues (use pikku-queue) or SQL databases (use pikku-kysely).

Pikku Redis

Agent Operating Procedure

Use this skill as an execution checklist, not reference material.

1. Discover before editing. Prefer OpenCode tools such as pikku-meta when available; otherwise run the relevant pikku meta ... --json command and inspect only the focused output you need.
2. Identify the source files that own the behavior. Do not start by reading generated output, .pikku, node_modules, vendored packages, or broad build artifacts.
3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
4. Validate with the narrowest relevant command first, then run pikku-verify or pikku all when functions, wirings, schemas, or generated clients may have changed.
5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.

@pikku/redis provides Redis-backed implementations of Pikku's core service interfaces using ioredis.

Installation

yarn add @pikku/redis

API Reference

Available Services

All services accept a Redis connection (ioredis Redis instance, RedisOptions, or connection string) in their constructor.

Service	Interface	Purpose
RedisChannelStore	ChannelStore	WebSocket channel state persistence
RedisEventHubStore	EventHubStore	Event hub state persistence
RedisWorkflowService	PikkuWorkflowService	Workflow definition storage
RedisWorkflowRunService	WorkflowRunService	Workflow execution tracking
RedisDeploymentService	DeploymentService	Deployment state management
RedisAgentRunService	AgentRunService	Agent execution tracking
RedisSecretService	SecretService	Encrypted secret storage (envelope encryption)

Secret Service

import { RedisSecretService } from '@pikku/redis'

const secrets = new RedisSecretService(
  connectionOrConfig: Redis | RedisOptions | string,
  config: { kekSecret: string; salt: string }
)

await secrets.getSecret<T = string>(key: string): Promise<T>
await secrets.getSecrets<T>(keys: (keyof T & string)[]): Promise<Partial<T>>
await secrets.hasSecret(key: string): Promise<boolean>
await secrets.setSecret(key: string, value: unknown): Promise<void>
await secrets.deleteSecret(key: string): Promise<void>
await secrets.rotateKEK(): Promise<number>
await secrets.close(): Promise<void>

Usage Patterns

Full Setup

import {
  RedisChannelStore,
  RedisWorkflowService,
  RedisSecretService,
} from '@pikku/redis'

const createSingletonServices = pikkuServices(async (config) => {
  const logger = new PinoLogger()

  const channelStore = new RedisChannelStore(config.redisUrl)
  const workflowService = new RedisWorkflowService(config.redisUrl)

  const secrets = new RedisSecretService(config.redisUrl, {
    kekSecret: config.kekSecret,
    salt: config.salt,
  })

  return { config, logger, channelStore, workflowService, secrets }
})