@rx-ted/packages-honest-plugins 1.0.1

package/cache/src/local/driver.ts

@@ -0,0 +1,117 @@
+import type { CacheDriver } from '../types';
+
+interface CacheEntry {
+  value: unknown;
+  expiresAt: number | null;
+}
+
+export function createLocalCacheDriver(): CacheDriver {
+  const store = new Map<string, CacheEntry>();
+
+  function isExpired(entry: CacheEntry): boolean {
+    return entry.expiresAt !== null && Date.now() > entry.expiresAt;
+  }
+
+  function prune(): void {
+    for (const [key, entry] of store) {
+      if (isExpired(entry)) store.delete(key);
+    }
+  }
+
+  return {
+    async get<T>(key: string): Promise<T | null> {
+      const entry = store.get(key);
+      if (!entry || isExpired(entry)) {
+        store.delete(key);
+        return null;
+      }
+      return entry.value as T;
+    },
+
+    async set(key: string, value: unknown, ttl?: number): Promise<boolean> {
+      store.set(key, {
+        value,
+        expiresAt: ttl ? Date.now() + ttl * 1000 : null,
+      });
+      return true;
+    },
+
+    async delete(key: string): Promise<boolean> {
+      return store.delete(key);
+    },
+
+    async exists(key: string): Promise<boolean> {
+      const entry = store.get(key);
+      if (!entry || isExpired(entry)) {
+        store.delete(key);
+        return false;
+      }
+      return true;
+    },
+
+    async mget<T>(keys: string[]): Promise<(T | null)[]> {
+      return keys.map((key) => {
+        const entry = store.get(key);
+        if (!entry || isExpired(entry)) {
+          store.delete(key);
+          return null;
+        }
+        return entry.value as T;
+      });
+    },
+
+    async mset(items: Array<{ key: string; value: unknown; ttl?: number }>): Promise<boolean> {
+      for (const item of items) {
+        store.set(item.key, {
+          value: item.value,
+          expiresAt: item.ttl ? Date.now() + item.ttl * 1000 : null,
+        });
+      }
+      return true;
+    },
+
+    async deleteByPattern(pattern: string): Promise<number> {
+      const regex = new RegExp(pattern.replace(/\*/g, '.*'));
+      let count = 0;
+      for (const key of store.keys()) {
+        if (regex.test(key)) {
+          store.delete(key);
+          count++;
+        }
+      }
+      return count;
+    },
+
+    async incr(key: string): Promise<number> {
+      const entry = store.get(key);
+      const current = entry && !isExpired(entry) ? (entry.value as number) : 0;
+      const next = current + 1;
+      store.set(key, { value: next, expiresAt: null });
+      return next;
+    },
+
+    async decr(key: string): Promise<number> {
+      const entry = store.get(key);
+      const current = entry && !isExpired(entry) ? (entry.value as number) : 0;
+      const next = current - 1;
+      store.set(key, { value: next, expiresAt: null });
+      return next;
+    },
+
+    async expire(key: string, ttl: number): Promise<boolean> {
+      const entry = store.get(key);
+      if (!entry) return false;
+      entry.expiresAt = Date.now() + ttl * 1000;
+      return true;
+    },
+
+    async close(): Promise<void> {
+      store.clear();
+    },
+
+    async healthCheck(): Promise<boolean> {
+      prune();
+      return true;
+    },
+  };
+}

package/cache/src/local/index.ts

@@ -0,0 +1,2 @@
+export { LocalCachePlugin, LOCAL_CACHE_CONTEXT_KEY } from './plugin';
+export { createLocalCacheDriver } from './driver';

package/cache/src/local/plugin.ts

@@ -0,0 +1,34 @@
+import type { Hono } from 'hono';
+import type { ILogger } from '@rx-ted/packages-core';
+import type { IPlugin, Application } from '@rx-ted/packages-honest';
+import { ComponentManager, resolvePluginLogger } from '@rx-ted/packages-honest';
+import { createLocalCacheDriver } from './driver';
+import type { CacheDriver } from '../types';
+import { CACHE_GLOBAL_KEY } from '../cache-service';
+
+export const LOCAL_CACHE_CONTEXT_KEY = 'honest:local-cache';
+
+export class LocalCachePlugin implements IPlugin {
+  static readonly globalKey = 'local-cache';
+  readonly name = 'local-cache-plugin';
+  readonly version = '1.0.0';
+
+  logger?: ILogger;
+  private driver: CacheDriver;
+
+  constructor() {
+    this.driver = createLocalCacheDriver();
+  }
+
+  async beforeModulesRegistered(app: Application, _hono: Hono): Promise<void> {
+    this.logger ??= resolvePluginLogger(this.name);
+    this.logger.info('Local cache: initializing in-memory cache...');
+    app.getContext().set(LOCAL_CACHE_CONTEXT_KEY, this.driver);
+    ComponentManager.registerPlugin(CACHE_GLOBAL_KEY, this.driver);
+    this.logger.info('Local cache: ready');
+  }
+
+  async close(): Promise<void> {
+    await this.driver.close();
+  }
+}

package/cache/src/redis/driver.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createRedisDriver } from './driver';
+import type { RedisClientOptions } from './driver';
+
+vi.mock('redis', () => {
+  const mockClient = {
+    on: vi.fn(),
+    connect: vi.fn().mockResolvedValue(undefined),
+    get: vi.fn(),
+    set: vi.fn(),
+    setEx: vi.fn(),
+    del: vi.fn(),
+    exists: vi.fn(),
+    mGet: vi.fn(),
+    multi: vi.fn(() => mockMulti),
+    incr: vi.fn(),
+    decr: vi.fn(),
+    expire: vi.fn(),
+    scan: vi.fn(),
+    ping: vi.fn(),
+    quit: vi.fn().mockResolvedValue(undefined),
+  };
+
+  const mockMulti = {
+    set: vi.fn(() => mockMulti),
+    setEx: vi.fn(() => mockMulti),
+    exec: vi.fn(),
+  };
+
+  return {
+    createClient: vi.fn(() => mockClient),
+  };
+});
+
+describe('RedisDriver', () => {
+  const options: RedisClientOptions = {
+    host: '127.0.0.1',
+    port: 6379,
+    db: 0,
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('creates driver with url option', async () => {
+    const { createClient } = await import('redis');
+    await createRedisDriver({ url: 'redis://localhost:6379' });
+    expect(createClient).toHaveBeenCalledWith({ url: 'redis://localhost:6379' });
+  });
+
+  it('creates driver with host/port options', async () => {
+    const { createClient } = await import('redis');
+    await createRedisDriver(options);
+    expect(createClient).toHaveBeenCalledWith({
+      socket: { host: '127.0.0.1', port: 6379 },
+      username: undefined,
+      password: undefined,
+      database: 0,
+    });
+  });
+
+  it('connects to redis', async () => {
+    const redis = await import('redis');
+    const createClient = redis.createClient as any;
+
+    await createRedisDriver(options);
+    expect(createClient).toHaveBeenCalledOnce();
+    expect(createClient().connect).toHaveBeenCalled();
+  });
+});

package/cache/src/redis/driver.ts

@@ -0,0 +1,124 @@
+import { createClient } from 'redis';
+import type { CacheDriver } from '../types';
+
+type RedisClientInstance = ReturnType<typeof createClient>;
+
+export interface RedisClientOptions {
+  url?: string;
+  host?: string;
+  port?: number;
+  username?: string;
+  password?: string;
+  db?: number;
+}
+
+export async function createRedisDriver(options: RedisClientOptions): Promise<CacheDriver> {
+  const client = createClient(
+    options.url
+      ? { url: options.url }
+      : {
+          socket: {
+            host: options.host ?? '127.0.0.1',
+            port: options.port ?? 6379,
+          },
+          username: options.username,
+          password: options.password,
+          database: options.db ?? 0,
+        },
+  );
+
+  await client.connect();
+
+  return new RedisDriver(client);
+}
+
+class RedisDriver implements CacheDriver {
+  constructor(private client: RedisClientInstance) {}
+
+  async get<T = unknown>(key: string): Promise<T | null> {
+    const value = await this.client.get(key);
+    if (value === null) return null;
+    return JSON.parse(value) as T;
+  }
+
+  async set(key: string, value: unknown, ttl?: number): Promise<boolean> {
+    const serialized = JSON.stringify(value);
+    let result: string;
+    if (ttl) {
+      result = await this.client.setEx(key, ttl, serialized);
+    } else {
+      result = (await this.client.set(key, serialized)) ?? '';
+    }
+    return result === 'OK';
+  }
+
+  async delete(key: string): Promise<boolean> {
+    const result = await this.client.del(key);
+    return result > 0;
+  }
+
+  async deleteByPattern(pattern: string): Promise<number> {
+    let cursor = 0;
+    let total = 0;
+    do {
+      const result = await this.client.scan(cursor, { MATCH: pattern, COUNT: 100 });
+      cursor = result.cursor;
+      if (result.keys.length > 0) {
+        const count = await this.client.del(result.keys);
+        total += count;
+      }
+    } while (cursor !== 0);
+    return total;
+  }
+
+  async exists(key: string): Promise<boolean> {
+    const result = await this.client.exists(key);
+    return result > 0;
+  }
+
+  async mget<T = unknown>(keys: string[]): Promise<(T | null)[]> {
+    const values = await this.client.mGet(keys);
+    return values.map((v: string | null) => (v ? (JSON.parse(v) as T) : null));
+  }
+
+  async mset(items: Array<{ key: string; value: unknown; ttl?: number }>): Promise<boolean> {
+    const pipeline = this.client.multi();
+    for (const item of items) {
+      const serialized = JSON.stringify(item.value);
+      if (item.ttl) {
+        pipeline.setEx(item.key, item.ttl, serialized);
+      } else {
+        pipeline.set(item.key, serialized);
+      }
+    }
+    const results = await pipeline.exec();
+    if (!results) return false;
+    return results.every((r: unknown) => r === 'OK');
+  }
+
+  async incr(key: string): Promise<number> {
+    return this.client.incr(key);
+  }
+
+  async decr(key: string): Promise<number> {
+    return this.client.decr(key);
+  }
+
+  async expire(key: string, ttl: number): Promise<boolean> {
+    const result = (await this.client.expire(key, ttl)) as unknown as number;
+    return result === 1;
+  }
+
+  async close(): Promise<void> {
+    await this.client.quit();
+  }
+
+  async healthCheck(): Promise<boolean> {
+    try {
+      await this.client.ping();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/cache/src/redis/index.ts

@@ -0,0 +1,4 @@
+export { RedisPlugin, REDIS_CONTEXT_KEY, REDIS_GLOBAL_KEY } from './plugin';
+export type { RedisPluginOptions } from './plugin';
+export { createRedisDriver } from './driver';
+export type { RedisClientOptions } from './driver';

package/cache/src/redis/plugin.ts

@@ -0,0 +1,84 @@
+import type { Hono } from 'hono';
+import type { ILogger } from '@rx-ted/packages-core';
+import { ComponentManager, maskSensitive, resolvePluginLogger } from '@rx-ted/packages-honest';
+import type { Application, IPlugin } from '@rx-ted/packages-honest';
+import { createRedisDriver } from './driver';
+import type { RedisClientOptions } from './driver';
+import type { CacheDriver } from '../types';
+import { CACHE_GLOBAL_KEY } from '../cache-service';
+
+export const REDIS_CONTEXT_KEY = 'honest:redis';
+export const REDIS_GLOBAL_KEY = 'redis';
+
+export interface RedisPluginOptions {
+  connection: RedisClientOptions;
+  contextKey?: string;
+}
+
+export class RedisPlugin implements IPlugin {
+  static readonly globalKey = REDIS_GLOBAL_KEY;
+  readonly name = 'redis-plugin';
+  readonly version = '1.0.0';
+
+  logger?: ILogger;
+
+  private driver: CacheDriver | null = null;
+  private readonly connection: RedisClientOptions;
+  private readonly contextKey: string;
+
+  constructor(options: RedisPluginOptions) {
+    this.connection = options.connection;
+    this.contextKey = options.contextKey ?? REDIS_CONTEXT_KEY;
+  }
+
+  getClient(): CacheDriver {
+    if (!this.driver) {
+      throw new Error('Redis not connected. Ensure beforeModulesRegistered has run.');
+    }
+    return this.driver;
+  }
+
+  async beforeModulesRegistered(app: Application, _hono: Hono): Promise<void> {
+    this.logger ??= resolvePluginLogger(this.name);
+    this.logger.info('Redis: connecting...');
+
+    const connInfo: Record<string, unknown> = {
+      category: 'plugins',
+      host: this.connection.host,
+      port: this.connection.port,
+      db: this.connection.db,
+      username: this.connection.username,
+      password: maskSensitive(this.connection.password),
+    };
+
+    try {
+      this.driver = await createRedisDriver(this.connection);
+      app.getContext().set(this.contextKey, this.driver);
+      ComponentManager.registerPlugin(CACHE_GLOBAL_KEY, this.driver);
+
+      const ok = await this.driver.healthCheck();
+      if (!ok) throw new Error('Redis: health check failed');
+      this.logger.info(connInfo, 'success to redis');
+    } catch (error) {
+      this.logger.error(
+        { ...connInfo, error: error instanceof Error ? error.message : String(error) },
+        'fail to connect redis',
+      );
+      throw error;
+    }
+  }
+
+  async afterModulesRegistered(_app: Application, _hono: Hono): Promise<void> {
+    if (this.driver) {
+      const ok = await this.driver.healthCheck();
+      if (ok) {
+        this.logger?.info('Redis: health check passed');
+      }
+    }
+  }
+
+  async close(): Promise<void> {
+    await this.driver?.close();
+    this.driver = null;
+  }
+}

package/cache/src/resolve.test.ts

@@ -0,0 +1,257 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const mockKvNs = vi.hoisted(() => ({ get: vi.fn(), put: vi.fn(), delete: vi.fn() }));
+
+const mockHasPlugin = vi.hoisted(() => vi.fn());
+const mockGetPlugin = vi.hoisted(() => vi.fn());
+const mockRegisterPlugin = vi.hoisted(() => vi.fn());
+const mockRuntimeEnv = vi.hoisted(() => vi.fn().mockReturnValue({}));
+
+const mockKvDriver = vi.hoisted(() => ({
+  name: 'cloudflare-kv',
+  close: vi.fn().mockResolvedValue(undefined),
+  healthCheck: vi.fn().mockResolvedValue(true),
+}));
+const mockRedisDriver = vi.hoisted(() => ({
+  name: 'redis',
+  close: vi.fn().mockResolvedValue(undefined),
+  healthCheck: vi.fn().mockResolvedValue(true),
+}));
+const mockLocalDriver = vi.hoisted(() => ({
+  name: 'local-cache',
+  close: vi.fn().mockResolvedValue(undefined),
+  healthCheck: vi.fn().mockResolvedValue(true),
+}));
+
+const mockCreateCloudflareKvDriver = vi.hoisted(() => vi.fn().mockReturnValue(mockKvDriver));
+const mockCreateRedisDriver = vi.hoisted(() => vi.fn().mockResolvedValue(mockRedisDriver));
+const mockCreateLocalCacheDriver = vi.hoisted(() => vi.fn().mockReturnValue(mockLocalDriver));
+
+vi.mock('@rx-ted/packages-core', () => {
+  function resolveBinding(name: string) {
+    return (
+      (globalThis as any)[name] ??
+      (globalThis as any).env?.[name] ??
+      (typeof process !== 'undefined' ? (process.env as any)?.[name] : undefined) ??
+      mockRuntimeEnv()?.[name]
+    );
+  }
+  return {
+    ENV_SYMBOL: Symbol('app:env'),
+    Platform: { env: mockRuntimeEnv },
+    resolveBinding,
+  };
+});
+
+vi.mock('@rx-ted/packages-honest', () => ({
+  ComponentManager: {
+    hasPlugin: mockHasPlugin,
+    getPlugin: mockGetPlugin,
+    registerPlugin: mockRegisterPlugin,
+  },
+  resolvePluginLogger: vi.fn().mockReturnValue({
+    child: vi.fn().mockReturnThis(),
+    info: vi.fn(),
+    error: vi.fn(),
+    warn: vi.fn(),
+    debug: vi.fn(),
+  }),
+}));
+
+vi.mock('./cloudflare/driver', () => ({ createCloudflareKvDriver: mockCreateCloudflareKvDriver }));
+vi.mock('./redis/driver', () => ({ createRedisDriver: mockCreateRedisDriver }));
+vi.mock('./local/driver', () => ({ createLocalCacheDriver: mockCreateLocalCacheDriver }));
+vi.mock('./cache-service', () => ({ CACHE_GLOBAL_KEY: 'app:cache' }));
+
+import { CachePlugin, findKvBinding, resolveBinding } from './resolve';
+
+function makeEnv(platform: string, vars: Record<string, string> = {}) {
+  return {
+    platform,
+    has: (key: string) => key in vars,
+    get: (key: string, _type?: string) => vars[key],
+    toObject: () => ({ ...vars }),
+  };
+}
+
+function mockApp() {
+  return { getContext: () => ({ set: vi.fn() }) };
+}
+
+describe('CachePlugin', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockHasPlugin.mockReturnValue(true);
+    mockGetPlugin.mockReturnValue(makeEnv('node'));
+    mockRuntimeEnv.mockReturnValue({});
+    mockCreateRedisDriver.mockResolvedValue(mockRedisDriver);
+  });
+
+  describe('auto-detect on cloudflare', () => {
+    beforeEach(() => {
+      mockGetPlugin.mockReturnValue(makeEnv('cloudflare'));
+      for (const key of Object.keys(globalThis as any)) {
+        if ((globalThis as any)[key] === mockKvNs) {
+          delete (globalThis as any)[key];
+        }
+      }
+    });
+
+    it('uses Cloudflare KV when binding on globalThis', async () => {
+      (globalThis as any).MY_KV = mockKvNs;
+      const plugin = new CachePlugin();
+      await plugin.beforeModulesRegistered(mockApp() as any);
+
+      expect(mockCreateCloudflareKvDriver).toHaveBeenCalledWith(mockKvNs);
+      expect(mockCreateLocalCacheDriver).not.toHaveBeenCalled();
+      expect(mockRegisterPlugin).toHaveBeenCalledWith('app:cache', mockKvDriver);
+      delete (globalThis as any).MY_KV;
+    });
+
+    it('throws when no KV binding on cloudflare', async () => {
+      const plugin = new CachePlugin();
+      await expect(plugin.beforeModulesRegistered(mockApp() as any)).rejects.toThrow(
+        'Cloudflare KV binding not found',
+      );
+      expect(mockCreateLocalCacheDriver).not.toHaveBeenCalled();
+      expect(mockCreateCloudflareKvDriver).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('auto-detect on node', () => {
+    it('uses Redis when env has REDIS_HOST', async () => {
+      mockGetPlugin.mockReturnValue(
+        makeEnv('node', { REDIS_HOST: 'localhost', REDIS_PORT: '6379' }),
+      );
+      const plugin = new CachePlugin();
+      await plugin.beforeModulesRegistered(mockApp() as any);
+
+      expect(mockCreateRedisDriver).toHaveBeenCalled();
+      expect(mockCreateLocalCacheDriver).not.toHaveBeenCalled();
+    });
+
+    it('falls back to local when no Redis config', async () => {
+      const plugin = new CachePlugin();
+      await plugin.beforeModulesRegistered(mockApp() as any);
+
+      expect(mockCreateLocalCacheDriver).toHaveBeenCalled();
+      expect(mockCreateRedisDriver).not.toHaveBeenCalled();
+    });
+
+    it('falls back to local when Redis connection fails', async () => {
+      mockGetPlugin.mockReturnValue(makeEnv('node', { REDIS_HOST: 'bad-host' }));
+      mockCreateRedisDriver.mockRejectedValue(new Error('connection refused'));
+      const plugin = new CachePlugin();
+      await plugin.beforeModulesRegistered(mockApp() as any);
+
+      expect(mockCreateRedisDriver).toHaveBeenCalled();
+      expect(mockCreateLocalCacheDriver).toHaveBeenCalled();
+    });
+  });
+
+  describe('explicit driver option', () => {
+    it('uses KV when driver: "kv" with binding on globalThis', async () => {
+      (globalThis as any).MY_KV = mockKvNs;
+      const plugin = new CachePlugin({ driver: 'kv' });
+      await plugin.beforeModulesRegistered(mockApp() as any);
+
+      expect(mockCreateCloudflareKvDriver).toHaveBeenCalled();
+      expect(mockCreateLocalCacheDriver).not.toHaveBeenCalled();
+      delete (globalThis as any).MY_KV;
+    });
+
+    it('throws when driver: "kv" without binding', async () => {
+      const plugin = new CachePlugin({ driver: 'kv' });
+      await expect(plugin.beforeModulesRegistered(mockApp() as any)).rejects.toThrow(
+        'Cloudflare KV binding not found',
+      );
+    });
+
+    it('uses Redis when driver: "redis"', async () => {
+      const plugin = new CachePlugin({ driver: 'redis', redis: { host: 'explicit-host' } });
+      await plugin.beforeModulesRegistered(mockApp() as any);
+
+      expect(mockCreateRedisDriver).toHaveBeenCalled();
+      expect(mockCreateLocalCacheDriver).not.toHaveBeenCalled();
+    });
+
+    it('uses local when driver: "local"', async () => {
+      const plugin = new CachePlugin({ driver: 'local' });
+      await plugin.beforeModulesRegistered(mockApp() as any);
+
+      expect(mockCreateLocalCacheDriver).toHaveBeenCalled();
+      expect(mockCreateCloudflareKvDriver).not.toHaveBeenCalled();
+      expect(mockCreateRedisDriver).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('explicit redis options', () => {
+    it('uses explicit redis config over env vars', async () => {
+      const env = makeEnv('node', { REDIS_HOST: 'ignored' });
+      mockGetPlugin.mockReturnValue(env);
+      const plugin = new CachePlugin({ redis: { host: 'explicit-host', port: 9999 } });
+      await plugin.beforeModulesRegistered(mockApp() as any);
+
+      expect(mockCreateRedisDriver).toHaveBeenCalledWith({ host: 'explicit-host', port: 9999 });
+    });
+  });
+
+  describe('API', () => {
+    it('getClient returns driver after init', async () => {
+      const plugin = new CachePlugin();
+      await plugin.beforeModulesRegistered(mockApp() as any);
+      expect(plugin.getClient()).toBe(mockLocalDriver);
+    });
+
+    it('getClient throws before init', () => {
+      const plugin = new CachePlugin();
+      expect(() => plugin.getClient()).toThrow('not initialized');
+    });
+
+    it('close calls driver.close and clears driver', async () => {
+      const plugin = new CachePlugin();
+      await plugin.beforeModulesRegistered(mockApp() as any);
+      await plugin.close();
+
+      expect(mockLocalDriver.close).toHaveBeenCalled();
+      expect(() => plugin.getClient()).toThrow('not initialized');
+    });
+  });
+});
+
+describe('findKvBinding', () => {
+  beforeEach(() => {
+    // Clean up any test bindings on globalThis
+    for (const key of Object.keys(globalThis as any)) {
+      if ((globalThis as any)[key] === mockKvNs) {
+        delete (globalThis as any)[key];
+      }
+    }
+  });
+
+  it('finds binding on globalThis by duck-type (get+put+delete)', () => {
+    (globalThis as any).MY_KV = mockKvNs;
+    expect(findKvBinding()).toBe('MY_KV');
+  });
+
+  it('finds binding on globalThis.env by duck-type', () => {
+    (globalThis as any).env = { MY_KV: mockKvNs };
+    expect(findKvBinding()).toBe('MY_KV');
+    delete (globalThis as any).env;
+  });
+
+  it('returns empty string when no binding found', () => {
+    expect(findKvBinding()).toBe('');
+  });
+
+  it('accepts optional Env parameter (for consistency)', () => {
+    const fakeEnv = { toObject: () => ({}) };
+    expect(findKvBinding(fakeEnv as any)).toBe('');
+  });
+});
+
+describe('resolveBinding', () => {
+  it('finds binding from env.get fallback', () => {
+    expect(resolveBinding('NONEXISTENT')).toBeUndefined();
+  });
+});