@lobehub/lobehub 2.0.0-next.127 → 2.0.0-next.128

package/src/libs/redis/redis.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { IoRedisConfig } from './types';
+
+const buildRedisConfig = (): IoRedisConfig | null => {
+  const url = process.env.REDIS_URL;
+
+  if (!url) return null;
+
+  const database = Number.parseInt(process.env.REDIS_DATABASE ?? '', 10);
+
+  return {
+    database: Number.isNaN(database) ? undefined : database,
+    enabled: true,
+    password: process.env.REDIS_PASSWORD,
+    prefix: process.env.REDIS_PREFIX ?? 'lobe-chat-test',
+    provider: 'redis',
+    tls: process.env.REDIS_TLS === 'true',
+    url,
+    username: process.env.REDIS_USERNAME,
+  };
+};
+
+const loadRedisProvider = async () => (await import('./redis')).IoRedisRedisProvider;
+
+const createMockedProvider = async () => {
+  const mocks = {
+    connect: vi.fn().mockResolvedValue(undefined),
+    ping: vi.fn().mockResolvedValue('PONG'),
+    quit: vi.fn().mockResolvedValue(undefined),
+    get: vi.fn().mockResolvedValue('mock-value'),
+    set: vi.fn().mockResolvedValue('OK'),
+    setex: vi.fn().mockResolvedValue('OK'),
+    del: vi.fn().mockResolvedValue(1),
+    exists: vi.fn().mockResolvedValue(1),
+    expire: vi.fn().mockResolvedValue(1),
+    ttl: vi.fn().mockResolvedValue(50),
+    incr: vi.fn().mockResolvedValue(2),
+    decr: vi.fn().mockResolvedValue(0),
+    mget: vi.fn().mockResolvedValue(['a', 'b']),
+    mset: vi.fn().mockResolvedValue('OK'),
+    hget: vi.fn().mockResolvedValue('field'),
+    hset: vi.fn().mockResolvedValue(1),
+    hdel: vi.fn().mockResolvedValue(1),
+    hgetall: vi.fn().mockResolvedValue({ a: '1' }),
+  };
+
+  vi.resetModules();
+  vi.doMock('ioredis', () => {
+    class FakeRedis {
+      constructor(
+        public url: string,
+        public options: any,
+      ) {}
+      connect = mocks.connect;
+      ping = mocks.ping;
+      quit = mocks.quit;
+      get = mocks.get;
+      set = mocks.set;
+      setex = mocks.setex;
+      del = mocks.del;
+      exists = mocks.exists;
+      expire = mocks.expire;
+      ttl = mocks.ttl;
+      incr = mocks.incr;
+      decr = mocks.decr;
+      mget = mocks.mget;
+      mset = mocks.mset;
+      hget = mocks.hget;
+      hset = mocks.hset;
+      hdel = mocks.hdel;
+      hgetall = mocks.hgetall;
+    }
+
+    return { default: FakeRedis };
+  });
+
+  const IoRedisRedisProvider = await loadRedisProvider();
+  const provider = new IoRedisRedisProvider({
+    enabled: true,
+    prefix: 'mock',
+    provider: 'redis',
+    tls: false,
+    url: 'redis://localhost:6379',
+  });
+
+  await provider.initialize();
+
+  return { mocks, provider };
+};
+
+const shouldSkipIntegration = (error: unknown) =>
+  error instanceof Error &&
+  ['ENOTFOUND', 'ECONNREFUSED', 'EAI_AGAIN', 'Connection is closed'].some((msg) =>
+    error.message.includes(msg),
+  );
+
+afterEach(() => {
+  vi.clearAllMocks();
+  vi.resetModules();
+  vi.unmock('ioredis');
+});
+
+describe('integrated', (test) => {
+  const config = buildRedisConfig();
+  if (!config) {
+    test.skip('REDIS_URL not provided; skip integrated ioredis tests');
+    return;
+  }
+
+  it('set -> get -> del roundtrip', async () => {
+    vi.unmock('ioredis');
+    vi.resetModules();
+
+    const IoRedisRedisProvider = await loadRedisProvider();
+    const provider = new IoRedisRedisProvider(config);
+    try {
+      await provider.initialize();
+
+      const key = `redis:test:${Date.now()}`;
+      await provider.set(key, 'value', { ex: 60 });
+      expect(await provider.get(key)).toBe('value');
+      expect(await provider.del(key)).toBe(1);
+    } catch (error) {
+      if (shouldSkipIntegration(error)) {
+        // Remote Redis unavailable in current environment; treat as skipped.
+        return;
+      }
+
+      throw error;
+    } finally {
+      await provider.disconnect();
+    }
+  });
+});
+
+describe('mocked', () => {
+  it('normalizes set options into ioredis arguments', async () => {
+    const { mocks, provider } = await createMockedProvider();
+    await provider.set('key', 'value', { ex: 10, nx: true, get: true });
+
+    expect(mocks.set).toHaveBeenCalledWith('key', 'value', 'EX', 10, 'NX', 'GET');
+    await provider.disconnect();
+  });
+
+  it('supports buffer keys for hashes and strings', async () => {
+    const { mocks, provider } = await createMockedProvider();
+
+    const bufKey = Buffer.from('buffer-key');
+    await provider.hset(bufKey, 'field', 'value');
+    await provider.get(bufKey);
+
+    expect(mocks.hset).toHaveBeenCalledWith(bufKey, 'field', 'value');
+    expect(mocks.get).toHaveBeenCalledWith(bufKey);
+
+    await provider.disconnect();
+  });
+});

package/src/libs/redis/redis.ts

@@ -0,0 +1,117 @@
+import debug from 'debug';
+import type { Redis } from 'ioredis';
+
+import {
+  BaseRedisProvider,
+  IoRedisConfig,
+  RedisKey,
+  RedisMSetArgument,
+  RedisProviderName,
+  RedisSetResult,
+  RedisValue,
+  SetOptions,
+} from './types';
+import { buildIORedisSetArgs, normalizeMsetValues } from './utils';
+
+const log = debug('lobe:redis');
+
+export class IoRedisRedisProvider implements BaseRedisProvider {
+  provider: RedisProviderName = 'redis';
+  private client: Redis | null = null;
+
+  constructor(private config: IoRedisConfig) {}
+
+  async initialize() {
+    const IORedis = await import('ioredis');
+
+    this.client = new IORedis.default(this.config.url, {
+      db: this.config.database,
+      keyPrefix: this.config.prefix ? `${this.config.prefix}:` : undefined,
+      lazyConnect: true,
+      maxRetriesPerRequest: 2,
+      password: this.config.password,
+      tls: this.config.tls ? {} : undefined,
+      username: this.config.username,
+    });
+
+    await this.client.connect();
+    await this.client.ping();
+
+    log('Connected to Redis provider with prefix "%s"', this.config.prefix);
+  }
+
+  async disconnect() {
+    await this.client?.quit();
+  }
+
+  private ensureClient(): Redis {
+    if (!this.client) {
+      throw new Error('Redis client is not initialized');
+    }
+
+    return this.client;
+  }
+
+  async get(key: RedisKey): Promise<string | null> {
+    return this.ensureClient().get(key);
+  }
+
+  async set(key: RedisKey, value: RedisValue, options?: SetOptions): Promise<RedisSetResult> {
+    const args = buildIORedisSetArgs(options);
+
+    // ioredis has many overloads for SET; use a cast to keep async-only usage ergonomic
+    return (this.ensureClient().set as any)(key, value, ...args);
+  }
+
+  async setex(key: RedisKey, seconds: number, value: RedisValue): Promise<'OK'> {
+    return this.ensureClient().setex(key, seconds, value);
+  }
+
+  async del(...keys: RedisKey[]): Promise<number> {
+    return this.ensureClient().del(...keys);
+  }
+
+  async exists(...keys: RedisKey[]): Promise<number> {
+    return this.ensureClient().exists(...keys);
+  }
+
+  async expire(key: RedisKey, seconds: number): Promise<number> {
+    return this.ensureClient().expire(key, seconds);
+  }
+
+  async ttl(key: RedisKey): Promise<number> {
+    return this.ensureClient().ttl(key);
+  }
+
+  async incr(key: RedisKey): Promise<number> {
+    return this.ensureClient().incr(key);
+  }
+
+  async decr(key: RedisKey): Promise<number> {
+    return this.ensureClient().decr(key);
+  }
+
+  async mget(...keys: RedisKey[]): Promise<(string | null)[]> {
+    return this.ensureClient().mget(...keys);
+  }
+
+  async mset(values: RedisMSetArgument): Promise<'OK'> {
+    return this.ensureClient().mset(normalizeMsetValues(values));
+  }
+
+  async hget(key: RedisKey, field: RedisKey): Promise<string | null> {
+    return this.ensureClient().hget(key, field);
+  }
+
+  async hset(key: RedisKey, field: RedisKey, value: RedisValue): Promise<number> {
+    return this.ensureClient().hset(key, field, value);
+  }
+
+  async hdel(key: RedisKey, ...fields: RedisKey[]): Promise<number> {
+    return this.ensureClient().hdel(key, ...fields);
+  }
+
+  async hgetall(key: RedisKey): Promise<Record<string, string>> {
+    return this.ensureClient().hgetall(key);
+  }
+}

package/src/libs/redis/types.ts

@@ -0,0 +1,71 @@
+export type RedisKey = string | Buffer;
+export type RedisValue = string | Buffer | number;
+export type RedisProvider = false | 'redis' | 'upstash';
+export type RedisProviderName = Exclude<RedisProvider, false>;
+
+export type IoRedisConfig = {
+  database?: number;
+  enabled: boolean;
+  password?: string;
+  prefix: string;
+  provider: 'redis';
+  tls: boolean;
+  url: string;
+  username?: string;
+};
+
+export type UpstashConfig = {
+  enabled: boolean;
+  prefix: string;
+  provider: 'upstash';
+  token: string;
+  url: string;
+};
+
+export type DisabledRedisConfig = {
+  enabled: false;
+  prefix: string;
+  provider: false;
+};
+
+export type RedisConfig = IoRedisConfig | UpstashConfig | DisabledRedisConfig;
+
+export interface SetOptions {
+  ex?: number;
+  exat?: number;
+  get?: boolean;
+  keepTtl?: boolean;
+  nx?: boolean;
+  px?: number;
+  pxat?: number;
+  xx?: boolean;
+}
+
+// NOTICE: number comes from upstash
+export type RedisSetResult = 'OK' | null | string | number;
+export type RedisMSetArgument = Record<string, RedisValue> | Map<RedisKey, RedisValue>;
+
+export interface RedisClient {
+  decr(key: RedisKey): Promise<number>;
+  del(...keys: RedisKey[]): Promise<number>;
+  exists(...keys: RedisKey[]): Promise<number>;
+  expire(key: RedisKey, seconds: number): Promise<number>;
+  get(key: RedisKey): Promise<string | null>;
+  hdel(key: RedisKey, ...fields: RedisKey[]): Promise<number>;
+  hget(key: RedisKey, field: RedisKey): Promise<string | null>;
+  hgetall(key: RedisKey): Promise<Record<string, string>>;
+  hset(key: RedisKey, field: RedisKey, value: RedisValue): Promise<number>;
+  incr(key: RedisKey): Promise<number>;
+  mget(...keys: RedisKey[]): Promise<(string | null)[]>;
+  mset(values: RedisMSetArgument): Promise<'OK'>;
+  set(key: RedisKey, value: RedisValue, options?: SetOptions): Promise<RedisSetResult>;
+  setex(key: RedisKey, seconds: number, value: RedisValue): Promise<'OK'>;
+  ttl(key: RedisKey): Promise<number>;
+}
+
+export interface BaseRedisProvider extends RedisClient {
+  disconnect(): Promise<void>;
+
+  initialize(): Promise<void>;
+  provider: RedisProviderName;
+}

package/src/libs/redis/upstash.test.ts

@@ -0,0 +1,154 @@
+// @vitest-environment node
+// NOTICE: here due to the reason we are using [`happy-dom`](https://github.com/lobehub/lobe-chat/blob/13753145557a9dede98b1f5489f93ac570ef2956/vitest.config.mts#L45)
+// for Vitest environment, and in fact that this is a known bug for happy-dom not including
+// Authorization header in fetch requests.
+//
+// Read more here: https://github.com/capricorn86/happy-dom/issues/1042#issuecomment-3585851354
+import { Buffer } from 'node:buffer';
+import { describe, expect, it, vi } from 'vitest';
+
+import { UpstashConfig } from './types';
+
+const buildUpstashConfig = (): UpstashConfig | null => {
+  const url = process.env.UPSTASH_REDIS_REST_URL;
+  const token = process.env.UPSTASH_REDIS_REST_TOKEN;
+
+  if (!url || !token) return null;
+
+  return {
+    enabled: true,
+    prefix: process.env.REDIS_PREFIX ?? 'lobe-chat-test',
+    provider: 'upstash',
+    token,
+    url,
+  };
+};
+
+const loadUpstashProvider = async () => (await import('./upstash')).UpstashRedisProvider;
+
+const createMockedProvider = async () => {
+  const mocks = {
+    mockSet: vi.fn().mockResolvedValue('OK'),
+    mockGet: vi.fn().mockResolvedValue('mock-value'),
+    mockDel: vi.fn().mockResolvedValue(1),
+    mockSetex: vi.fn().mockResolvedValue('OK'),
+    mockMset: vi.fn().mockResolvedValue('OK'),
+    mockHset: vi.fn().mockResolvedValue(1),
+    mockHdel: vi.fn().mockResolvedValue(1),
+    mockHgetall: vi.fn().mockResolvedValue({ a: '1' }),
+    mockPing: vi.fn().mockResolvedValue('PONG'),
+    mockExists: vi.fn().mockResolvedValue(1),
+    mockExpire: vi.fn().mockResolvedValue(1),
+    mockTtl: vi.fn().mockResolvedValue(50),
+    mockIncr: vi.fn().mockResolvedValue(2),
+    mockDecr: vi.fn().mockResolvedValue(0),
+    mockMget: vi.fn().mockResolvedValue(['a', 'b']),
+    mockHget: vi.fn().mockResolvedValue('field'),
+  };
+
+  vi.resetModules();
+  vi.doMock('@upstash/redis', () => {
+    class FakeRedis {
+      constructor(public config: any) {}
+      ping = mocks.mockPing;
+      set = mocks.mockSet;
+      get = mocks.mockGet;
+      del = mocks.mockDel;
+      setex = mocks.mockSetex;
+      exists = mocks.mockExists;
+      expire = mocks.mockExpire;
+      ttl = mocks.mockTtl;
+      incr = mocks.mockIncr;
+      decr = mocks.mockDecr;
+      mget = mocks.mockMget;
+      mset = mocks.mockMset;
+      hget = mocks.mockHget;
+      hset = mocks.mockHset;
+      hdel = mocks.mockHdel;
+      hgetall = mocks.mockHgetall;
+    }
+
+    return { Redis: FakeRedis };
+  });
+
+  const UpstashRedisProvider = await loadUpstashProvider();
+  const provider = new UpstashRedisProvider({
+    enabled: true,
+    prefix: 'mock',
+    provider: 'upstash',
+    token: 'token',
+    url: 'https://example.upstash.io',
+  });
+
+  await provider.initialize();
+
+  return { mocks, provider };
+};
+
+const shouldSkipIntegration = (error: unknown) =>
+  error instanceof Error &&
+  ['ENOTFOUND', 'ECONNREFUSED', 'EAI_AGAIN', 'Connection is closed'].some((msg) =>
+    error.message.includes(msg),
+  );
+
+afterEach(() => {
+  vi.clearAllMocks();
+  vi.resetModules();
+  vi.unmock('@upstash/redis');
+});
+
+describe('integrated', (test) => {
+  const config = buildUpstashConfig();
+  if (!config) {
+    test.skip('UPSTASH_REDIS_REST_URL/TOKEN not provided; skip integrated upstash tests');
+    return;
+  }
+
+  it('set -> get -> del roundtrip', async () => {
+    vi.unmock('@upstash/redis');
+    vi.resetModules();
+
+    const UpstashRedisProvider = await loadUpstashProvider();
+    const provider = new UpstashRedisProvider(config);
+    try {
+      await provider.initialize();
+
+      const key = `upstash:test:${Date.now()}`;
+      await provider.set(key, 'value', { ex: 60 });
+      expect(await provider.get(key)).toBe('value');
+      expect(await provider.del(key)).toBe(1);
+    } catch (error) {
+      if (shouldSkipIntegration(error)) {
+        // Remote Upstash Redis unavailable in current environment; treat as skipped.
+        return;
+      }
+
+      throw error;
+    } finally {
+      await provider.disconnect();
+    }
+  });
+});
+
+describe('mocked', () => {
+  it('normalizes buffer keys to strings', async () => {
+    const { mocks, provider } = await createMockedProvider();
+
+    const bufKey = Buffer.from('buffer-key');
+    await provider.set(bufKey, 'value');
+    await provider.hset(bufKey, 'field', 'value');
+    await provider.del(bufKey);
+
+    expect(mocks.mockSet).toHaveBeenCalledWith('buffer-key', 'value', undefined);
+    expect(mocks.mockHset).toHaveBeenCalledWith('buffer-key', { field: 'value' });
+    expect(mocks.mockDel).toHaveBeenCalledWith('buffer-key');
+  });
+
+  it('passes set options through to upstash client', async () => {
+    const { mocks, provider } = await createMockedProvider();
+
+    await provider.set('key', 'value', { ex: 10, nx: true, get: true });
+
+    expect(mocks.mockSet).toHaveBeenCalledWith('key', 'value', { ex: 10, nx: true, get: true });
+  });
+});

package/src/libs/redis/upstash.ts

@@ -0,0 +1,109 @@
+import { Redis, RedisConfigNodejs } from '@upstash/redis';
+import { Buffer } from 'node:buffer';
+
+import {
+  BaseRedisProvider,
+  RedisKey,
+  RedisMSetArgument,
+  RedisSetResult,
+  RedisValue,
+  SetOptions,
+  UpstashConfig,
+} from './types';
+import {
+  buildUpstashSetOptions,
+  normalizeMsetValues,
+  normalizeRedisKey,
+  normalizeRedisKeys,
+} from './utils';
+
+export class UpstashRedisProvider implements BaseRedisProvider {
+  provider: 'upstash' = 'upstash';
+  private client: Redis;
+
+  constructor(options: UpstashConfig | RedisConfigNodejs) {
+    this.client = new Redis(options as RedisConfigNodejs);
+  }
+
+  async initialize(): Promise<void> {
+    await this.client.ping();
+  }
+
+  async disconnect() {
+    // upstash client is stateless http, nothing to disconnect
+  }
+
+  async get(key: RedisKey): Promise<string | null> {
+    return this.client.get(normalizeRedisKey(key));
+  }
+
+  async set(key: RedisKey, value: RedisValue, options?: SetOptions): Promise<RedisSetResult> {
+    const res = await this.client.set(
+      normalizeRedisKey(key),
+      value,
+      buildUpstashSetOptions(options),
+    );
+    if (Buffer.isBuffer(res)) {
+      return res.toString();
+    }
+
+    return res;
+  }
+
+  async setex(key: RedisKey, seconds: number, value: RedisValue): Promise<'OK'> {
+    return this.client.setex(normalizeRedisKey(key), seconds, value);
+  }
+
+  async del(...keys: RedisKey[]): Promise<number> {
+    return this.client.del(...normalizeRedisKeys(keys));
+  }
+
+  async exists(...keys: RedisKey[]): Promise<number> {
+    return this.client.exists(...normalizeRedisKeys(keys));
+  }
+
+  async expire(key: RedisKey, seconds: number): Promise<number> {
+    return this.client.expire(normalizeRedisKey(key), seconds);
+  }
+
+  async ttl(key: RedisKey): Promise<number> {
+    return this.client.ttl(normalizeRedisKey(key));
+  }
+
+  async incr(key: RedisKey): Promise<number> {
+    return this.client.incr(normalizeRedisKey(key));
+  }
+
+  async decr(key: RedisKey): Promise<number> {
+    return this.client.decr(normalizeRedisKey(key));
+  }
+
+  async mget(...keys: RedisKey[]): Promise<(string | null)[]> {
+    return this.client.mget(...normalizeRedisKeys(keys));
+  }
+
+  async mset(values: RedisMSetArgument): Promise<'OK'> {
+    return this.client.mset(normalizeMsetValues(values));
+  }
+
+  async hget(key: RedisKey, field: RedisKey): Promise<string | null> {
+    return this.client.hget(normalizeRedisKey(key), normalizeRedisKey(field));
+  }
+
+  async hset(key: RedisKey, field: RedisKey, value: RedisValue): Promise<number> {
+    return this.client.hset(normalizeRedisKey(key), { [normalizeRedisKey(field)]: value });
+  }
+
+  async hdel(key: RedisKey, ...fields: RedisKey[]): Promise<number> {
+    return this.client.hdel(normalizeRedisKey(key), ...normalizeRedisKeys(fields));
+  }
+
+  async hgetall(key: RedisKey): Promise<Record<string, string>> {
+    const res = await this.client.hgetall(normalizeRedisKey(key));
+    if (!res) {
+      return {};
+    }
+
+    return res as Record<string, string>;
+  }
+}

package/src/libs/redis/utils.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildIORedisSetArgs,
+  buildUpstashSetOptions,
+  normalizeMsetValues,
+  normalizeRedisKey,
+  normalizeRedisKeys,
+} from './utils';
+
+describe('redis utils', () => {
+  it('normalizes single redis key to string', () => {
+    expect(normalizeRedisKey('foo')).toBe('foo');
+    expect(normalizeRedisKey(Buffer.from('bar'))).toBe('bar');
+  });
+
+  it('normalizes an array of redis keys', () => {
+    expect(normalizeRedisKeys(['foo', Buffer.from('bar')])).toEqual(['foo', 'bar']);
+  });
+
+  it('normalizes mset values from Map', () => {
+    const payload = normalizeMsetValues(
+      new Map<Buffer | string, number>([
+        [Buffer.from('a'), 1],
+        ['b', 2],
+      ]),
+    );
+
+    expect(payload).toEqual({ a: 1, b: 2 });
+  });
+
+  it('builds ioredis set arguments', () => {
+    const args = buildIORedisSetArgs({ ex: 1, nx: true, get: true });
+
+    expect(args).toEqual(['EX', 1, 'NX', 'GET']);
+  });
+
+  it('builds upstash set options', () => {
+    expect(buildUpstashSetOptions()).toBeUndefined();
+    expect(buildUpstashSetOptions({ ex: 10, nx: true, get: true })).toEqual({
+      ex: 10,
+      nx: true,
+      get: true,
+    });
+  });
+});