Initial Commit
This commit is contained in:
134
openspec/changes/enterprise-server-cache-redis/proposal.md
Normal file
134
openspec/changes/enterprise-server-cache-redis/proposal.md
Normal file
@@ -0,0 +1,134 @@
|
||||
# OpenSpec Change: enterprise-server-cache-redis
|
||||
|
||||
- **Change ID**: enterprise-server-cache-redis
|
||||
- **Package**: `@suaveplan/cache-redis`
|
||||
- **Category**: server/data
|
||||
- **Target path**: `server/data/cache-redis`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/cache-redis.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/cache-redis` on the genesis branch from scratch at enterprise quality. The package provides a Redis-backed cache adapter implementing the `StorageLike` / `CacheLike` interface. It wraps `ioredis` with typed get/set/delete/has/list/clear/ttl operations, namespace prefixing, Zod-validated connection options, circuit-breaker via `@suaveplan/retry`, OTel instrumentation, and structured logging. Supports both single-node and cluster modes via a single `createRedisCacheAdapter` factory.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
The package does not exist on genesis yet — fresh build. No prior source, no test results, no coverage data.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | Typed error codes for `CACHE_REDIS.*` |
|
||||
| `@suaveplan/types` (`workspace:^`) | `StorageLike`, `LoggerLike` |
|
||||
| `@suaveplan/retry` (`workspace:^`) | Circuit breaker + backoff on connection loss |
|
||||
| `@suaveplan/logger` (`workspace:^`) | Structured logs |
|
||||
| `zod` (`catalog:forms`) | Options validation |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |
|
||||
| `ioredis` (`catalog:data`) | Redis client |
|
||||
| `tslib` (`catalog:build`) | Runtime helpers |
|
||||
|
||||
---
|
||||
|
||||
## Public API surface
|
||||
|
||||
### Adapter
|
||||
|
||||
```ts
|
||||
class RedisCacheAdapter {
|
||||
constructor(options: RedisCacheOptions)
|
||||
get(key: string): Promise<Uint8Array | undefined>
|
||||
set(key: string, value: Uint8Array, ttlMs?: number): Promise<void>
|
||||
delete(key: string): Promise<boolean>
|
||||
has(key: string): Promise<boolean>
|
||||
list(prefix?: string): Promise<string[]>
|
||||
clear(): Promise<void>
|
||||
ttl(key: string): Promise<number | undefined> // remaining TTL in ms
|
||||
connect(): Promise<void>
|
||||
disconnect(): Promise<void>
|
||||
ping(): Promise<boolean>
|
||||
}
|
||||
|
||||
function createRedisCacheAdapter(options: RedisCacheOptions): RedisCacheAdapter
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```ts
|
||||
interface RedisCacheOptions {
|
||||
host?: string // default: 'localhost'
|
||||
port?: number // default: 6379
|
||||
password?: string
|
||||
db?: number
|
||||
namespace?: string // key prefix, default: ''
|
||||
tls?: boolean
|
||||
clusterNodes?: Array<{ host: string; port: number }>
|
||||
maxRetries?: number // default: 3
|
||||
connectTimeout?: number // default: 5000 ms
|
||||
commandTimeout?: number // default: 2000 ms
|
||||
logger?: LoggerLike
|
||||
}
|
||||
|
||||
const RedisCacheOptionsSchema: z.ZodSchema<RedisCacheOptions>
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
type RedisCacheErrorCode =
|
||||
| 'CACHE_REDIS_CONNECT_FAILED'
|
||||
| 'CACHE_REDIS_COMMAND_FAILED'
|
||||
| 'CACHE_REDIS_TIMEOUT'
|
||||
| 'CACHE_REDIS_CLUSTER_ERROR'
|
||||
| 'CACHE_REDIS_INVALID_KEY'
|
||||
|
||||
function registerRedisCacheErrorCodes(): void
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
server/data/cache-redis/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/
|
||||
index.ts
|
||||
types/
|
||||
cache-redis.types.ts
|
||||
cache-redis.types.md
|
||||
adapter/
|
||||
redis-cache-adapter/
|
||||
redis-cache-adapter.ts
|
||||
redis-cache-adapter.md
|
||||
redis-cache-adapter.types.ts
|
||||
redis-cache-adapter.test.ts
|
||||
index.ts
|
||||
utils/
|
||||
key-builder.ts
|
||||
key-builder.md
|
||||
key-builder.test.ts
|
||||
tests/
|
||||
integration.test.ts # real Redis via docker
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
Downstream consumers: any server package needing distributed caching (api-gateway, rate-limiter, idempotency, sessions). No genesis package currently depends on it.
|
||||
|
||||
**Prerequisites on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/retry`, `@suaveplan/logger`.
|
||||
**Integration tests** require a live Redis instance — use `docker run redis:7-alpine` in CI.
|
||||
81
openspec/changes/enterprise-server-cache-redis/tasks.md
Normal file
81
openspec/changes/enterprise-server-cache-redis/tasks.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# Tasks: enterprise-server-cache-redis
|
||||
|
||||
**Change ID**: enterprise-server-cache-redis
|
||||
**Package**: `@suaveplan/cache-redis`
|
||||
**Target path**: `server/data/cache-redis`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/retry`, `@suaveplan/logger`
|
||||
|
||||
---
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [ ] Create `server/data/cache-redis/` with full directory tree per `proposal.md` layout.
|
||||
- [ ] Write `package.json` at version `0.1.0`, `"type": "module"`, `"sideEffects": false`, exports map with `"."` barrel plus subpaths for `adapter`, `utils/key-builder`.
|
||||
- [ ] Add dependencies: `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/retry workspace:^`, `@suaveplan/logger workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`, `ioredis catalog:data`, `tslib catalog:build`.
|
||||
- [ ] Add devDependencies: `vitest catalog:testing`, `@vitest/coverage-istanbul catalog:testing`, `@suaveplan/testing workspace:^`.
|
||||
- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library-node.json`.
|
||||
- [ ] Write `vitest.config.ts` using `createTestConfig()`.
|
||||
- [ ] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.
|
||||
|
||||
## 2. Types and errors
|
||||
|
||||
- [ ] Define `RedisCacheOptions`, `RedisCacheOptionsSchema` in `src/types/cache-redis.types.ts`.
|
||||
- [ ] Write `cache-redis.types.md` (≥200 words, both examples, API reference).
|
||||
- [ ] Implement `src/error-codes.ts`: `RedisCacheErrorCode` union, metadata, `registerRedisCacheErrorCodes()`, eager invocation.
|
||||
|
||||
## 3. Key builder utility
|
||||
|
||||
- [ ] Implement `src/utils/key-builder.ts`: `buildKey(namespace: string, key: string): string` — joins with `:` separator; rejects empty keys and `*`-glob injection; throws `CACHE_REDIS_INVALID_KEY`.
|
||||
- [ ] `extractKey(namespace: string, full: string): string` — strips namespace prefix for list results.
|
||||
- [ ] Write `key-builder.test.ts`: namespace join, empty key rejection, glob injection, extract round-trip.
|
||||
- [ ] Write `key-builder.md` (≥200 words).
|
||||
|
||||
## 4. Core adapter
|
||||
|
||||
- [ ] Implement `RedisCacheAdapter` in `src/adapter/redis-cache-adapter/redis-cache-adapter.ts`:
|
||||
- Constructor validates options via `RedisCacheOptionsSchema`; creates `ioredis.Redis` (single) or `ioredis.Cluster` (when `clusterNodes` present).
|
||||
- `connect()` / `disconnect()` / `ping()`: lifecycle methods; wrap with retry on first connect; OTel span `cache_redis.connect`.
|
||||
- `get(key)`: `redis.getBuffer(buildKey(...))` → `Uint8Array | undefined`; OTel span + counter.
|
||||
- `set(key, value, ttlMs?)`: `redis.set(k, v, 'PX', ttlMs)` or `redis.set(k, v)` when no TTL; OTel span.
|
||||
- `delete(key)`: `redis.del(k)` → boolean; OTel span.
|
||||
- `has(key)`: `redis.exists(k) > 0`; OTel span.
|
||||
- `list(prefix?)`: SCAN with `MATCH namespace:prefix*` using async cursor loop; OTel span.
|
||||
- `clear()`: SCAN all keys in namespace then DEL in batches of 100; OTel span.
|
||||
- `ttl(key)`: `redis.pttl(k)` → number in ms or `undefined` if no TTL.
|
||||
- All commands wrapped with `commandTimeout` via `redis.call` timeout or `AbortSignal`; retry on `CACHE_REDIS_CONNECT_FAILED` using `@suaveplan/retry`.
|
||||
- [ ] Export `createRedisCacheAdapter(options)`.
|
||||
- [ ] Write `redis-cache-adapter.types.ts` with internal-only types.
|
||||
- [ ] Write `redis-cache-adapter.test.ts` (≤500 lines): unit tests with a real Redis running locally — verify all CRUD, TTL expiry, namespace isolation, cluster option path (use single-node Redis). No vi.mock of ioredis.
|
||||
- [ ] Write `redis-cache-adapter.md` (≥200 words, simple + advanced, full API reference).
|
||||
|
||||
## 5. Integration tests
|
||||
|
||||
- [ ] Write `tests/integration.test.ts` (≤500 lines): full lifecycle — connect, set, get, has, list with prefix, delete, clear, disconnect; concurrent SET race condition; TTL expiry (use short TTL + real sleep).
|
||||
- [ ] Guard tests with `if (!process.env.REDIS_URL) test.skip(...)` to allow CI-skip when Redis is unavailable.
|
||||
|
||||
## 6. OTel instrumentation
|
||||
|
||||
- [ ] Counter `cache_redis.ops_total` with `operation` and `hit` (bool for get) attributes.
|
||||
- [ ] Histogram `cache_redis.duration_ms` per operation.
|
||||
- [ ] Span per public method; record exception; end in `finally`.
|
||||
|
||||
## 7. Docs
|
||||
|
||||
- [ ] All `.md` per layout; root `README.md` with quick-start, docker-compose snippet for Redis, API table, deps table.
|
||||
|
||||
## 8. Verify and publish
|
||||
|
||||
- [ ] `bunx turbo lint --filter=@suaveplan/cache-redis` — zero errors.
|
||||
- [ ] `bunx turbo typecheck --filter=@suaveplan/cache-redis` — zero errors.
|
||||
- [ ] `bunx turbo test --filter=@suaveplan/cache-redis` — all tests pass (start Redis before running).
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/cache-redis` — 100% on all touched modules.
|
||||
- [ ] Confirm no `TODO`, `FIXME`, `any`, `ts-ignore`, or `.skip` in `src/`.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/cache-redis`.
|
||||
- [ ] Update `CLAUDE.md` package listing.
|
||||
- [ ] Archive: move to `openspec/archive/2026-04-24-enterprise-server-cache-redis/`.
|
||||
Reference in New Issue
Block a user