@yunsoft/yuncms-core 0.1.3 → 0.1.6

package/src/query.js

@@ -1,24 +1,46 @@
 import { quoteIdentifier } from './identifier.js';
 
-const QUERY_KEYS = new Set(['fields', 'filter', 'sort', 'limit', 'offset']);
+const QUERY_KEYS = new Set(['fields', 'filter', 'sort', 'limit', 'offset', 'search', 'aggregate', 'groupBy']);
 const FILTER_OPERATORS = new Set([
   '_eq', '_neq', '_lt', '_lte', '_gt', '_gte',
   '_in', '_nin', '_null', '_nnull',
   '_contains', '_starts_with', '_ends_with',
 ]);
+const AGGREGATE_FUNCTIONS = new Set(['count', 'countDistinct', 'sum', 'avg', 'min', 'max']);
+const SEARCHABLE_TYPES = new Set(['string', 'text']);
 
-function queryError(message, path = null) {
+export const QUERY_LIMITS = Object.freeze({
+  defaultLimit: 100,
+  maxLimit: 500,
+  maxFields: 100,
+  maxRelationExpansions: 20,
+  maxRelationDepth: 4,
+  maxSortFields: 20,
+  maxOffset: 1_000_000,
+  maxFilterDepth: 8,
+  maxFilterNodes: 100,
+  maxInValues: 100,
+  maxSearchLength: 200,
+  maxAggregateFields: 20,
+  maxGroupByFields: 10,
+  maxCost: 2_000,
+});
+
+function queryError(message, path = null, code = 'INVALID_QUERY') {
   const error = new Error(message);
-  error.code = 'INVALID_QUERY';
+  error.code = code;
   if (path) error.path = path;
   return error;
 }
 
-function normalizeDelimited(value, label) {
+function normalizeDelimited(value, label, { maxItems }) {
   if (value == null || value === '') return null;
   const values = Array.isArray(value) ? value : String(value).split(',');
   const normalized = values.map((item) => String(item).trim()).filter(Boolean);
   if (normalized.length === 0) throw queryError(`${label} cannot be empty`, label);
+  if (normalized.length > maxItems) {
+    throw queryError(`${label} cannot contain more than ${maxItems} entries`, label);
+  }
   return normalized;
 }
 
@@ -36,36 +58,92 @@ function normalizeFilter(value) {
   if (typeof value === 'string') {
     try {
       const parsed = JSON.parse(value);
-      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw new Error('not an object');
-      }
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('not an object');
       return parsed;
     } catch {
       throw queryError('filter must be a valid JSON object', 'filter');
     }
   }
-  if (typeof value !== 'object' || Array.isArray(value)) {
-    throw queryError('filter must be an object', 'filter');
-  }
+  if (typeof value !== 'object' || Array.isArray(value)) throw queryError('filter must be an object', 'filter');
   return value;
 }
 
-export function parseItemsQuery(raw = {}, { defaultLimit = 100, maxLimit = 500 } = {}) {
-  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
-    throw queryError('Query must be an object');
+function normalizeSearch(value, limits) {
+  if (value == null || value === '') return null;
+  if (Array.isArray(value) || typeof value === 'object') throw queryError('search must be a string', 'search');
+  const search = String(value).trim();
+  if (!search) return null;
+  if (search.length > limits.maxSearchLength) {
+    throw queryError(`search cannot exceed ${limits.maxSearchLength} characters`, 'search');
   }
+  return search;
+}
+
+function normalizeAggregate(value, limits) {
+  if (value == null || value === '') return null;
+  let aggregate = value;
+  if (typeof aggregate === 'string') {
+    try { aggregate = JSON.parse(aggregate); } catch { throw queryError('aggregate must be a JSON object', 'aggregate'); }
+  }
+  if (!aggregate || typeof aggregate !== 'object' || Array.isArray(aggregate)) {
+    throw queryError('aggregate must be an object', 'aggregate');
+  }
+
+  const normalized = {};
+  let count = 0;
+  for (const [fn, rawFields] of Object.entries(aggregate)) {
+    if (!AGGREGATE_FUNCTIONS.has(fn)) throw queryError(`Unknown aggregate function: ${fn}`, `aggregate.${fn}`);
+    const fields = normalizeDelimited(rawFields, `aggregate.${fn}`, { maxItems: limits.maxAggregateFields });
+    if (!fields) throw queryError(`aggregate.${fn} cannot be empty`, `aggregate.${fn}`);
+    count += fields.length;
+    if (count > limits.maxAggregateFields) {
+      throw queryError(`aggregate cannot contain more than ${limits.maxAggregateFields} fields`, 'aggregate');
+    }
+    normalized[fn] = fields;
+  }
+  if (Object.keys(normalized).length === 0) throw queryError('aggregate cannot be empty', 'aggregate');
+  return normalized;
+}
+
+export function parseItemsQuery(raw = {}, options = {}) {
+  const limits = { ...QUERY_LIMITS, ...options };
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw queryError('Query must be an object');
 
   for (const key of Object.keys(raw)) {
     if (!QUERY_KEYS.has(key)) throw queryError(`Unknown query parameter: ${key}`, key);
   }
 
-  return {
-    fields: normalizeDelimited(raw.fields, 'fields'),
+  const query = {
+    fields: normalizeDelimited(raw.fields, 'fields', { maxItems: limits.maxFields }),
     filter: normalizeFilter(raw.filter),
-    sort: normalizeDelimited(raw.sort, 'sort'),
-    limit: normalizeInteger(raw.limit, defaultLimit, { label: 'limit', min: 1, max: maxLimit }),
-    offset: normalizeInteger(raw.offset, 0, { label: 'offset', min: 0, max: Number.MAX_SAFE_INTEGER }),
+    sort: normalizeDelimited(raw.sort, 'sort', { maxItems: limits.maxSortFields }),
+    limit: normalizeInteger(raw.limit, limits.defaultLimit, { label: 'limit', min: 1, max: limits.maxLimit }),
+    offset: normalizeInteger(raw.offset, 0, { label: 'offset', min: 0, max: limits.maxOffset }),
+    search: normalizeSearch(raw.search, limits),
+    aggregate: normalizeAggregate(raw.aggregate, limits),
+    groupBy: normalizeDelimited(raw.groupBy, 'groupBy', { maxItems: limits.maxGroupByFields }),
   };
+
+  if (query.groupBy && !query.aggregate) throw queryError('groupBy requires aggregate', 'groupBy');
+  return Object.freeze(query);
+}
+
+export function queryCost(query, { relationDepth = 0, relationCount = 0 } = {}) {
+  let cost = 1 + Number(query?.limit ?? QUERY_LIMITS.defaultLimit);
+  cost += (query?.fields?.length ?? 0) * 2;
+  cost += (query?.sort?.length ?? 0) * 5;
+  cost += relationCount * 50;
+  cost += relationDepth * 100;
+  if (query?.search) cost += 100;
+  if (query?.aggregate) cost += 250 + Object.values(query.aggregate).flat().length * 25;
+  return cost;
+}
+
+export function assertQueryCost(query, options = {}) {
+  const maxCost = options.maxCost ?? QUERY_LIMITS.maxCost;
+  const cost = queryCost(query, options);
+  if (cost > maxCost) throw queryError(`Query cost ${cost} exceeds limit ${maxCost}`, null, 'QUERY_COST_LIMIT');
+  return cost;
 }
 
 function resolveField(schema, field, path = field) {
@@ -76,7 +154,6 @@ function resolveField(schema, field, path = field) {
 export function compileSelectFields(fields, schema) {
   const selected = !fields || fields.includes('*') ? Object.keys(schema.fields) : fields;
   if (selected.length === 0) throw queryError('At least one field must be selected', 'fields');
-
   const unique = [...new Set(selected)];
   return {
     fields: unique,
@@ -89,7 +166,6 @@ export function compileSelectFields(fields, schema) {
 
 export function compileSort(sort, schema) {
   if (!sort) return '';
-
   const parts = sort.map((entry, index) => {
     const descending = entry.startsWith('-');
     const field = descending ? entry.slice(1) : entry;
@@ -97,7 +173,6 @@ export function compileSort(sort, schema) {
     resolveField(schema, field, `sort.${index}`);
     return `${quoteIdentifier(field, 'field name')} ${descending ? 'DESC' : 'ASC'}`;
   });
-
   return parts.length ? ` ORDER BY ${parts.join(', ')}` : '';
 }
 
@@ -105,9 +180,49 @@ function escapeLike(value) {
   return String(value).replace(/[\\%_]/g, '\\$&');
 }
 
-function compileOperator(fieldSql, operator, value, path) {
-  if (!FILTER_OPERATORS.has(operator)) throw queryError(`Unknown filter operator: ${operator}`, path);
+export function compileSearch(search, schema) {
+  if (!search) return { sql: '', params: [] };
+  const fields = Object.entries(schema?.fields ?? {})
+    .filter(([, field]) => SEARCHABLE_TYPES.has(field.type))
+    .map(([name]) => name);
+  if (fields.length === 0) return { sql: ' WHERE 0 = 1', params: [] };
+  const needle = `%${escapeLike(search)}%`;
+  return {
+    sql: ` WHERE (${fields.map((field) => `${quoteIdentifier(field, 'field name')} LIKE ? ESCAPE '\\\\'`).join(' OR ')})`,
+    params: fields.map(() => needle),
+  };
+}
+
+export function compileAggregate(aggregate, groupBy, schema) {
+  if (!aggregate) return null;
+  const groups = groupBy ?? [];
+  for (const field of groups) resolveField(schema, field, `groupBy.${field}`);
+  const selections = groups.map((field) => quoteIdentifier(field, 'field name'));
+  const aliases = new Set(groups);
 
+  for (const [fn, fields] of Object.entries(aggregate)) {
+    for (const field of fields) {
+      if (field === '*' && fn !== 'count') throw queryError(`${fn} does not support *`, `aggregate.${fn}`);
+      if (field !== '*') resolveField(schema, field, `aggregate.${fn}.${field}`);
+      const column = field === '*' ? '*' : quoteIdentifier(field, 'field name');
+      const sqlFn = fn === 'countDistinct' ? 'COUNT' : fn.toUpperCase();
+      const expression = fn === 'countDistinct' ? `${sqlFn}(DISTINCT ${column})` : `${sqlFn}(${column})`;
+      const rawAlias = field === '*' ? fn : `${fn}_${field}`;
+      let alias = rawAlias;
+      let suffix = 2;
+      while (aliases.has(alias)) alias = `${rawAlias}_${suffix++}`;
+      aliases.add(alias);
+      selections.push(`${expression} AS ${quoteIdentifier(alias, 'aggregate alias')}`);
+    }
+  }
+  return {
+    sql: selections.join(', '),
+    groupSql: groups.length ? ` GROUP BY ${groups.map((field) => quoteIdentifier(field, 'field name')).join(', ')}` : '',
+  };
+}
+
+function compileOperator(fieldSql, operator, value, path, limits) {
+  if (!FILTER_OPERATORS.has(operator)) throw queryError(`Unknown filter operator: ${operator}`, path);
   switch (operator) {
     case '_eq':
       if (value === null) throw queryError('Use _null for NULL comparisons', path);
@@ -122,12 +237,10 @@ function compileOperator(fieldSql, operator, value, path) {
     case '_in':
     case '_nin': {
       if (!Array.isArray(value)) throw queryError(`${operator} requires an array`, path);
+      if (value.length > limits.maxInValues) throw queryError(`${operator} accepts at most ${limits.maxInValues} values`, path);
       if (value.length === 0) return { sql: operator === '_in' ? '0 = 1' : '1 = 1', params: [] };
       const placeholders = value.map(() => '?').join(', ');
-      return {
-        sql: `${fieldSql} ${operator === '_in' ? 'IN' : 'NOT IN'} (${placeholders})`,
-        params: value,
-      };
+      return { sql: `${fieldSql} ${operator === '_in' ? 'IN' : 'NOT IN'} (${placeholders})`, params: value };
     }
     case '_null':
     case '_nnull': {
@@ -135,59 +248,48 @@ function compileOperator(fieldSql, operator, value, path) {
       const wantsNull = operator === '_null' ? value : !value;
       return { sql: `${fieldSql} IS ${wantsNull ? '' : 'NOT '}NULL`, params: [] };
     }
-    case '_contains':
-      return { sql: `${fieldSql} LIKE ? ESCAPE '\\\\'`, params: [`%${escapeLike(value)}%`] };
-    case '_starts_with':
-      return { sql: `${fieldSql} LIKE ? ESCAPE '\\\\'`, params: [`${escapeLike(value)}%`] };
-    case '_ends_with':
-      return { sql: `${fieldSql} LIKE ? ESCAPE '\\\\'`, params: [`%${escapeLike(value)}`] };
-    default:
-      throw queryError(`Unknown filter operator: ${operator}`, path);
+    case '_contains': return { sql: `${fieldSql} LIKE ? ESCAPE '\\\\'`, params: [`%${escapeLike(value)}%`] };
+    case '_starts_with': return { sql: `${fieldSql} LIKE ? ESCAPE '\\\\'`, params: [`${escapeLike(value)}%`] };
+    case '_ends_with': return { sql: `${fieldSql} LIKE ? ESCAPE '\\\\'`, params: [`%${escapeLike(value)}`] };
+    default: throw queryError(`Unknown filter operator: ${operator}`, path);
   }
 }
 
-function compileFilterObject(filter, schema, path = 'filter') {
-  if (!filter || typeof filter !== 'object' || Array.isArray(filter)) {
-    throw queryError('Filter node must be an object', path);
-  }
+function compileFilterObject(filter, schema, path, limits, state, depth) {
+  if (!filter || typeof filter !== 'object' || Array.isArray(filter)) throw queryError('Filter node must be an object', path);
+  if (depth > limits.maxFilterDepth) throw queryError(`Filter depth cannot exceed ${limits.maxFilterDepth}`, path);
+  state.nodes += 1;
+  if (state.nodes > limits.maxFilterNodes) throw queryError(`Filter cannot contain more than ${limits.maxFilterNodes} nodes`, path);
 
   const fragments = [];
   const params = [];
-
   for (const [key, value] of Object.entries(filter)) {
     if (key === '_and' || key === '_or') {
-      if (!Array.isArray(value) || value.length === 0) {
-        throw queryError(`${key} requires a non-empty array`, `${path}.${key}`);
-      }
-      const children = value.map((child, index) =>
-        compileFilterObject(child, schema, `${path}.${key}.${index}`));
+      if (!Array.isArray(value) || value.length === 0) throw queryError(`${key} requires a non-empty array`, `${path}.${key}`);
+      const children = value.map((child, index) => compileFilterObject(child, schema, `${path}.${key}.${index}`, limits, state, depth + 1));
       fragments.push(`(${children.map((child) => child.sql).join(key === '_and' ? ' AND ' : ' OR ')})`);
       for (const child of children) params.push(...child.params);
       continue;
     }
-
     resolveField(schema, key, `${path}.${key}`);
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
-      throw queryError('Field filters must be operator objects', `${path}.${key}`);
-    }
-
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw queryError('Field filters must be operator objects', `${path}.${key}`);
     const fieldSql = quoteIdentifier(key, 'field name');
     const fieldFragments = [];
     for (const [operator, operatorValue] of Object.entries(value)) {
-      const compiled = compileOperator(fieldSql, operator, operatorValue, `${path}.${key}.${operator}`);
+      const compiled = compileOperator(fieldSql, operator, operatorValue, `${path}.${key}.${operator}`, limits);
       fieldFragments.push(compiled.sql);
       params.push(...compiled.params);
     }
     if (fieldFragments.length === 0) throw queryError('Field filter cannot be empty', `${path}.${key}`);
     fragments.push(`(${fieldFragments.join(' AND ')})`);
   }
-
   if (fragments.length === 0) throw queryError('Filter cannot be empty', path);
   return { sql: fragments.join(' AND '), params };
 }
 
-export function compileFilter(filter, schema) {
+export function compileFilter(filter, schema, options = {}) {
   if (!filter) return { sql: '', params: [] };
-  const compiled = compileFilterObject(filter, schema);
+  const limits = { ...QUERY_LIMITS, ...options };
+  const compiled = compileFilterObject(filter, schema, 'filter', limits, { nodes: 0 }, 1);
   return { sql: ` WHERE ${compiled.sql}`, params: compiled.params };
 }

package/src/redis.js

@@ -0,0 +1,300 @@
+import { createHash } from 'node:crypto';
+import net from 'node:net';
+import tls from 'node:tls';
+
+function redisError(code, message, cause = null) {
+  const error = new Error(message, cause ? { cause } : undefined);
+  error.code = code;
+  return error;
+}
+
+export function redactRedisUrl(value) {
+  if (!value) return null;
+  try {
+    const url = new URL(value);
+    if (url.username) url.username = '***';
+    if (url.password) url.password = '***';
+    return url.toString();
+  } catch {
+    return '<invalid-redis-url>';
+  }
+}
+
+export function parseRedisUrl(value) {
+  if (!value) throw redisError('INVALID_REDIS_CONFIG', 'REDIS_URL is required for Redis shared state');
+  let url;
+  try { url = new URL(value); } catch { throw redisError('INVALID_REDIS_CONFIG', 'REDIS_URL must be a valid URL'); }
+  if (!['redis:', 'rediss:'].includes(url.protocol)) {
+    throw redisError('INVALID_REDIS_CONFIG', 'REDIS_URL must use redis:// or rediss://');
+  }
+  const database = url.pathname && url.pathname !== '/' ? Number(url.pathname.slice(1)) : 0;
+  if (!Number.isInteger(database) || database < 0 || database > 15) {
+    throw redisError('INVALID_REDIS_CONFIG', 'REDIS_URL database must be an integer between 0 and 15');
+  }
+  return Object.freeze({
+    tls: url.protocol === 'rediss:',
+    host: url.hostname,
+    port: Number(url.port || 6379),
+    username: decodeURIComponent(url.username || ''),
+    password: decodeURIComponent(url.password || ''),
+    database,
+  });
+}
+
+function encodeCommand(args) {
+  const parts = [`*${args.length}\r\n`];
+  for (const arg of args) {
+    const value = Buffer.from(String(arg));
+    parts.push(`$${value.length}\r\n`, value, '\r\n');
+  }
+  return Buffer.concat(parts.map((part) => Buffer.isBuffer(part) ? part : Buffer.from(part)));
+}
+
+function readLine(buffer, offset) {
+  const end = buffer.indexOf('\r\n', offset);
+  if (end === -1) return null;
+  return { value: buffer.toString('utf8', offset, end), next: end + 2 };
+}
+
+function parseReply(buffer, offset = 0) {
+  if (offset >= buffer.length) return null;
+  const type = String.fromCharCode(buffer[offset]);
+  const line = readLine(buffer, offset + 1);
+  if (!line) return null;
+
+  if (type === '+' || type === '-' || type === ':') {
+    const value = type === ':' ? Number(line.value) : line.value;
+    return { value, error: type === '-', next: line.next };
+  }
+  if (type === '$') {
+    const length = Number(line.value);
+    if (length === -1) return { value: null, next: line.next };
+    const end = line.next + length;
+    if (buffer.length < end + 2) return null;
+    return { value: buffer.toString('utf8', line.next, end), next: end + 2 };
+  }
+  if (type === '*') {
+    const count = Number(line.value);
+    if (count === -1) return { value: null, next: line.next };
+    let next = line.next;
+    const value = [];
+    for (let index = 0; index < count; index += 1) {
+      const child = parseReply(buffer, next);
+      if (!child) return null;
+      if (child.error) return child;
+      value.push(child.value);
+      next = child.next;
+    }
+    return { value, next };
+  }
+  throw redisError('REDIS_PROTOCOL_ERROR', `Unsupported Redis RESP type: ${type}`);
+}
+
+export class RedisClient {
+  constructor({ url, connectTimeoutMs = 5_000, commandTimeoutMs = 3_000, logger = console } = {}) {
+    this.config = parseRedisUrl(url);
+    this.connectTimeoutMs = connectTimeoutMs;
+    this.commandTimeoutMs = commandTimeoutMs;
+    this.logger = logger;
+    this.socket = null;
+    this.buffer = Buffer.alloc(0);
+    this.pending = [];
+    this.connecting = null;
+    this.closed = false;
+  }
+
+  async connect() {
+    if (this.socket && !this.socket.destroyed) return this;
+    if (this.connecting) return this.connecting;
+    if (this.closed) throw redisError('REDIS_CLOSED', 'Redis client is closed');
+
+    this.connecting = new Promise((resolve, reject) => {
+      const options = { host: this.config.host, port: this.config.port };
+      const socket = this.config.tls ? tls.connect(options) : net.createConnection(options);
+      const timer = setTimeout(() => {
+        socket.destroy(redisError('REDIS_CONNECT_TIMEOUT', 'Redis connection timed out'));
+      }, this.connectTimeoutMs);
+
+      const fail = (error) => {
+        clearTimeout(timer);
+        this.connecting = null;
+        reject(redisError('REDIS_CONNECT_FAILED', 'Redis connection failed', error));
+      };
+      socket.once('error', fail);
+      socket.once('connect', async () => {
+        clearTimeout(timer);
+        socket.off('error', fail);
+        this.socket = socket;
+        this.buffer = Buffer.alloc(0);
+        socket.on('data', (chunk) => this.#onData(chunk));
+        socket.on('error', (error) => this.#onSocketFailure(error));
+        socket.on('close', () => this.#onSocketFailure(redisError('REDIS_DISCONNECTED', 'Redis disconnected')));
+        try {
+          if (this.config.password) {
+            if (this.config.username) await this.command('AUTH', this.config.username, this.config.password);
+            else await this.command('AUTH', this.config.password);
+          }
+          if (this.config.database) await this.command('SELECT', this.config.database);
+          this.connecting = null;
+          resolve(this);
+        } catch (error) {
+          socket.destroy();
+          this.connecting = null;
+          reject(error);
+        }
+      });
+    });
+    return this.connecting;
+  }
+
+  #onData(chunk) {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+    while (this.pending.length) {
+      let parsed;
+      try { parsed = parseReply(this.buffer); } catch (error) {
+        this.#onSocketFailure(error);
+        return;
+      }
+      if (!parsed) return;
+      this.buffer = this.buffer.subarray(parsed.next);
+      const pending = this.pending.shift();
+      clearTimeout(pending.timer);
+      if (parsed.error) pending.reject(redisError('REDIS_COMMAND_FAILED', `Redis command failed: ${parsed.value}`));
+      else pending.resolve(parsed.value);
+    }
+  }
+
+  #onSocketFailure(error) {
+    const socket = this.socket;
+    this.socket = null;
+    if (socket && !socket.destroyed) socket.destroy();
+    const pending = this.pending.splice(0);
+    for (const request of pending) {
+      clearTimeout(request.timer);
+      request.reject(redisError('REDIS_UNAVAILABLE', 'Redis command interrupted', error));
+    }
+  }
+
+  async command(...args) {
+    if (!this.socket || this.socket.destroyed) await this.connect();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        const index = this.pending.findIndex((entry) => entry.resolve === resolve);
+        if (index >= 0) this.pending.splice(index, 1);
+        reject(redisError('REDIS_COMMAND_TIMEOUT', 'Redis command timed out'));
+      }, this.commandTimeoutMs);
+      this.pending.push({ resolve, reject, timer });
+      this.socket.write(encodeCommand(args));
+    });
+  }
+
+  async ping() {
+    return (await this.command('PING')) === 'PONG';
+  }
+
+  async close() {
+    this.closed = true;
+    const socket = this.socket;
+    this.socket = null;
+    if (!socket || socket.destroyed) return;
+    try { socket.end(encodeCommand(['QUIT'])); } catch {}
+    socket.destroy();
+  }
+}
+
+function assertPrefix(prefix) {
+  const value = String(prefix || 'yuncms:default:');
+  if (value.length < 3 || value.length > 128 || /[\r\n\0]/.test(value)) {
+    throw redisError('INVALID_REDIS_CONFIG', 'Redis prefix must be between 3 and 128 safe characters');
+  }
+  return value.endsWith(':') ? value : `${value}:`;
+}
+
+export class RedisCacheStore {
+  constructor({ client, prefix = 'yuncms:default:', namespace = 'permission', ttlMs = 30_000, logger = console } = {}) {
+    if (!client?.command) throw redisError('INVALID_REDIS_CONFIG', 'RedisCacheStore requires a Redis command client');
+    this.client = client;
+    this.prefix = assertPrefix(prefix);
+    this.namespace = String(namespace);
+    this.ttlMs = ttlMs;
+    this.logger = logger;
+  }
+
+  generationKey() { return `${this.prefix}${this.namespace}:generation`; }
+
+  async #generation() {
+    const value = await this.client.command('GET', this.generationKey());
+    return value == null ? '0' : String(value);
+  }
+
+  async #key(key) {
+    return `${this.prefix}${this.namespace}:${await this.#generation()}:${String(key)}`;
+  }
+
+  async get(key) {
+    try {
+      const raw = await this.client.command('GET', await this.#key(key));
+      if (raw == null) return undefined;
+      const parsed = JSON.parse(raw);
+      if (!parsed || parsed.v !== 1 || !Object.hasOwn(parsed, 'value')) return undefined;
+      return parsed.value;
+    } catch (error) {
+      this.logger?.warn?.('Redis cache read failed; falling back to source of truth', { code: error?.code });
+      return undefined;
+    }
+  }
+
+  async set(key, value, { ttlMs = this.ttlMs } = {}) {
+    try {
+      const payload = JSON.stringify({ v: 1, value });
+      await this.client.command('SET', await this.#key(key), payload, 'PX', ttlMs);
+    } catch (error) {
+      this.logger?.warn?.('Redis cache write failed; continuing without cache', { code: error?.code });
+    }
+    return value;
+  }
+
+  async delete(key) {
+    try { return Number(await this.client.command('DEL', await this.#key(key))) > 0; } catch { return false; }
+  }
+
+  async clear() {
+    try {
+      await this.client.command('INCR', this.generationKey());
+      return true;
+    } catch (error) {
+      this.logger?.warn?.('Redis cache generation invalidation failed', { code: error?.code });
+      return false;
+    }
+  }
+}
+
+const RATE_LIMIT_SCRIPT = `
+local count = redis.call('INCR', KEYS[1])
+if count == 1 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
+local ttl = redis.call('PTTL', KEYS[1])
+return {count, ttl}
+`.trim();
+
+export class RedisFixedWindowStore {
+  constructor({ client, prefix = 'yuncms:default:', logger = console } = {}) {
+    if (!client?.command) throw redisError('INVALID_REDIS_CONFIG', 'RedisFixedWindowStore requires a Redis command client');
+    this.client = client;
+    this.prefix = assertPrefix(prefix);
+    this.logger = logger;
+  }
+
+  async consume(identity, { windowMs, max, scope = 'api' } = {}) {
+    const digest = createHash('sha256').update(String(identity)).digest('hex');
+    const key = `${this.prefix}rate:${scope}:${digest}`;
+    const result = await this.client.command('EVAL', RATE_LIMIT_SCRIPT, 1, key, windowMs);
+    const count = Number(result?.[0] ?? 0);
+    const ttlMs = Math.max(1, Number(result?.[1] ?? windowMs));
+    return {
+      count,
+      remaining: Math.max(0, max - count),
+      retryAfterMs: ttlMs,
+      resetAt: Date.now() + ttlMs,
+    };
+  }
+}