@rowger_go/chatu 0.1.3

package/src/sdk/adapters/cache.test.ts

@@ -0,0 +1,205 @@
+/**
+ * T037b — MessageCache unit tests
+ *
+ * constitution §IV: New modules must have a test file.
+ *
+ * Tests cover:
+ *   - enqueue → FIFO order guarantee
+ *   - Capacity limit: evicts oldest + logger.warn (single STRING — §VII)
+ *   - flush → calls sendFn in FIFO order; marks submitted
+ *   - ack → removes item, prevents re-send
+ *   - File persistence: write then re-instantiate → queue restored
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { MessageCache, CachedMessage } from '../../sdk/adapters/cache';
+
+function makeMsg(id: string, channelId = 'ch-1'): CachedMessage {
+  return { id, channelId, content: { text: `msg-${id}` }, enqueuedAt: Date.now(), status: 'pending' };
+}
+
+describe('MessageCache', () => {
+  // ── enqueue / FIFO ──────────────────────────────────────────────────────────
+
+  describe('enqueue', () => {
+    it('maintains FIFO insertion order in snapshot', () => {
+      const cache = new MessageCache();
+      cache.enqueue(makeMsg('a'));
+      cache.enqueue(makeMsg('b'));
+      cache.enqueue(makeMsg('c'));
+
+      const ids = cache.snapshot().map((m) => m.id);
+      expect(ids).toEqual(['a', 'b', 'c']);
+    });
+
+    it('size reflects enqueued count', () => {
+      const cache = new MessageCache();
+      cache.enqueue(makeMsg('x'));
+      cache.enqueue(makeMsg('y'));
+      expect(cache.size).toBe(2);
+    });
+  });
+
+  // ── Capacity limit ──────────────────────────────────────────────────────────
+
+  describe('capacity enforcement', () => {
+    it('evicts the oldest item when limit is reached', () => {
+      const cache = new MessageCache({ maxCapacity: 3 });
+      cache.enqueue(makeMsg('first'));
+      cache.enqueue(makeMsg('second'));
+      cache.enqueue(makeMsg('third'));
+      cache.enqueue(makeMsg('fourth'));  // should evict 'first'
+
+      const ids = cache.snapshot().map((m) => m.id);
+      expect(ids).not.toContain('first');
+      expect(ids).toContain('fourth');
+      expect(cache.size).toBe(3);
+    });
+
+    it('calls logger.warn with a SINGLE STRING on eviction (§VII)', () => {
+      const warnMessages: string[] = [];
+      const logger = { warn: (msg: string) => { warnMessages.push(msg); } };
+
+      const cache = new MessageCache({ maxCapacity: 1, logger });
+      cache.enqueue(makeMsg('m1', 'ch-test'));
+      cache.enqueue(makeMsg('m2', 'ch-test'));  // evicts 'm1'
+
+      expect(warnMessages.length).toBe(1);
+      // Must be a string — not an object (§VII)
+      expect(typeof warnMessages[0]).toBe('string');
+      expect(warnMessages[0]).toContain('cache_capacity_exceeded');
+      expect(warnMessages[0]).toContain('ch-test');
+      expect(warnMessages[0]).toContain('m1');
+    });
+  });
+
+  // ── flush ───────────────────────────────────────────────────────────────────
+
+  describe('flush', () => {
+    it('calls sendFn for each pending message in FIFO order', async () => {
+      const cache = new MessageCache();
+      cache.enqueue(makeMsg('p1'));
+      cache.enqueue(makeMsg('p2'));
+      cache.enqueue(makeMsg('p3'));
+
+      const order: string[] = [];
+      const count = await cache.flush(async (msg) => {
+        order.push(msg.id);
+      });
+
+      expect(count).toBe(3);
+      expect(order).toEqual(['p1', 'p2', 'p3']);
+    });
+
+    it('marks flushed messages as submitted', async () => {
+      const cache = new MessageCache();
+      cache.enqueue(makeMsg('s1'));
+      await cache.flush(async () => { /* no-op */ });
+      const snap = cache.snapshot();
+      expect(snap[0].status).toBe('submitted');
+    });
+
+    it('stops flushing on first sendFn error, leaving remaining as pending', async () => {
+      const cache = new MessageCache();
+      cache.enqueue(makeMsg('ok1'));
+      cache.enqueue(makeMsg('fail'));
+      cache.enqueue(makeMsg('ok2'));
+
+      let calls = 0;
+      await cache.flush(async (msg) => {
+        calls++;
+        if (msg.id === 'fail') throw new Error('send failed');
+      });
+
+      // Stopped at 'fail' — only 'ok1' submitted
+      expect(calls).toBe(2);
+      const snaps = cache.snapshot();
+      expect(snaps.find((m) => m.id === 'ok1')?.status).toBe('submitted');
+      expect(snaps.find((m) => m.id === 'fail')?.status).toBe('pending');
+      expect(snaps.find((m) => m.id === 'ok2')?.status).toBe('pending');
+    });
+
+    it('does not re-send already-submitted messages on subsequent flush', async () => {
+      const cache = new MessageCache();
+      cache.enqueue(makeMsg('d1'));
+      await cache.flush(async () => { /* no-op */ });
+
+      const sentIds: string[] = [];
+      await cache.flush(async (msg) => { sentIds.push(msg.id); });
+      expect(sentIds).not.toContain('d1');
+    });
+  });
+
+  // ── ack ─────────────────────────────────────────────────────────────────────
+
+  describe('ack', () => {
+    it('removes the message from the queue by id', () => {
+      const cache = new MessageCache();
+      cache.enqueue(makeMsg('ack-1'));
+      cache.enqueue(makeMsg('ack-2'));
+
+      cache.ack('ack-1');
+
+      const ids = cache.snapshot().map((m) => m.id);
+      expect(ids).not.toContain('ack-1');
+      expect(ids).toContain('ack-2');
+    });
+
+    it('prevents the acked message from being re-sent on flush', async () => {
+      const cache = new MessageCache();
+      cache.enqueue(makeMsg('r1'));
+      cache.enqueue(makeMsg('r2'));
+      cache.ack('r1');
+
+      const sent: string[] = [];
+      await cache.flush(async (msg) => { sent.push(msg.id); });
+      expect(sent).not.toContain('r1');
+      expect(sent).toContain('r2');
+    });
+
+    it('is a no-op for unknown ids', () => {
+      const cache = new MessageCache();
+      cache.enqueue(makeMsg('x'));
+      expect(() => cache.ack('nonexistent')).not.toThrow();
+      expect(cache.size).toBe(1);
+    });
+  });
+
+  // ── File persistence ─────────────────────────────────────────────────────────
+
+  describe('file persistence', () => {
+    let tmpFile: string;
+
+    beforeEach(() => {
+      tmpFile = path.join(os.tmpdir(), `cache-test-${Date.now()}.json`);
+    });
+
+    afterEach(() => {
+      try { fs.unlinkSync(tmpFile); } catch { /* ignore */ }
+    });
+
+    it('persists queue to file and restores on re-instantiation', () => {
+      const cache1 = new MessageCache({ filePath: tmpFile });
+      cache1.enqueue(makeMsg('persist-1'));
+      cache1.enqueue(makeMsg('persist-2'));
+
+      // Re-instantiate from same file path
+      const cache2 = new MessageCache({ filePath: tmpFile });
+      const ids = cache2.snapshot().map((m) => m.id);
+      expect(ids).toEqual(['persist-1', 'persist-2']);
+    });
+
+    it('starts with empty queue if file does not exist', () => {
+      const cache = new MessageCache({ filePath: '/tmp/definitely-does-not-exist-xyz123.json' });
+      expect(cache.size).toBe(0);
+    });
+
+    it('starts with empty queue if file is corrupt JSON', () => {
+      fs.writeFileSync(tmpFile, 'not valid json');
+      const cache = new MessageCache({ filePath: tmpFile });
+      expect(cache.size).toBe(0);
+    });
+  });
+});

package/src/sdk/adapters/cache.ts

@@ -0,0 +1,193 @@
+/******************************************************************
+ * Plugin Local Message Cache (cache.ts)
+ *
+ * In-memory FIFO queue for outbound messages that couldn't be sent
+ * while the WebSocket was disconnected.
+ *
+ * Key behaviour (spec FR-007/US2):
+ *   - Capacity limited to CHATU_CACHE_MAX (default 1000)
+ *   - On overflow: oldest item is evicted; PluginLogger.warn is called
+ *     with a SINGLE STRING (constitution §VII — NON-NEGOTIABLE)
+ *   - Optional JSON file persistence via CHATU_CACHE_FILE env var
+ *   - flush(sendFn) sends items in FIFO order; ack(id) marks delivered
+ *
+ * @see specs/001-plugin-channel-realtime/tasks.md T013
+ ******************************************************************/
+
+import fs from 'fs';
+import path from 'path';
+
+/** Minimal subset of PluginLogger used here (§VII: warn accepts single string). */
+export interface PluginLoggerSubset {
+  warn: (msg: string) => void;
+  info?: (msg: string) => void;
+}
+
+/** A cached outbound message entry. */
+export interface CachedMessage {
+  id: string;
+  channelId: string;
+  content: unknown;
+  enqueuedAt: number;
+  /** 'pending' until ACKed by the server. */
+  status: 'pending' | 'submitted';
+}
+
+export interface CacheOptions {
+  /** Max items before evicting the oldest. Defaults to CHATU_CACHE_MAX env or 1000. */
+  maxCapacity?: number;
+  /** Path for JSON file persistence. Defaults to CHATU_CACHE_FILE env or undefined. */
+  filePath?: string;
+  /** Logger used for capacity warnings (§VII). */
+  logger?: PluginLoggerSubset;
+}
+
+const DEFAULT_CAPACITY = 1000;
+
+/**
+ * MessageCache — FIFO queue for offline-buffered outbound messages.
+ *
+ * @example
+ * ```typescript
+ * const cache = new MessageCache({ logger: api.logger });
+ * cache.enqueue({ id: uuid(), channelId: 'wh_ch_xxx', content: { text: 'hello' }, enqueuedAt: Date.now(), status: 'pending' });
+ * await cache.flush(async (msg) => adapter.send(msg));
+ * ```
+ */
+export class MessageCache {
+  private queue: CachedMessage[] = [];
+  private maxCapacity: number;
+  private filePath: string | undefined;
+  private logger: PluginLoggerSubset | undefined;
+
+  constructor(options: CacheOptions = {}) {
+    this.maxCapacity =
+      options.maxCapacity ??
+      (process.env.CHATU_CACHE_MAX ? parseInt(process.env.CHATU_CACHE_MAX, 10) : DEFAULT_CAPACITY);
+
+    this.filePath =
+      options.filePath ??
+      (process.env.CHATU_CACHE_FILE ? path.resolve(process.env.CHATU_CACHE_FILE) : undefined);
+
+    this.logger = options.logger;
+
+    // Restore from file if configured
+    if (this.filePath) {
+      this.loadFromFile();
+    }
+  }
+
+  // ─── Public API ──────────────────────────────────────────────────────────────
+
+  /**
+   * Enqueue a message for later delivery.
+   * If at capacity, evicts the oldest pending item and logs a warning.
+   */
+  enqueue(msg: CachedMessage): void {
+    if (this.queue.length >= this.maxCapacity) {
+      const dropped = this.queue.shift();
+      if (dropped && this.logger) {
+        // §VII: PluginLogger.warn must receive a SINGLE STRING — no object argument
+        this.logger.warn(
+          'cache_capacity_exceeded: channelId=' + msg.channelId + ' dropped=' + dropped.id,
+        );
+      }
+    }
+
+    this.queue.push(msg);
+    this.persist();
+  }
+
+  /**
+   * Flush all 'pending' items in FIFO order by calling sendFn for each.
+   * Items that sendFn resolves successfully are marked 'submitted'.
+   * Items where sendFn throws remain 'pending' for the next flush.
+   *
+   * Returns the number of successfully flushed items.
+   */
+  async flush(sendFn: (msg: CachedMessage) => Promise<void>): Promise<number> {
+    let flushed = 0;
+    const pending = this.queue.filter((m) => m.status === 'pending');
+
+    for (const msg of pending) {
+      try {
+        await sendFn(msg);
+        msg.status = 'submitted';
+        flushed++;
+      } catch {
+        // Leave as pending — will retry on next flush
+        break;
+      }
+    }
+
+    this.persist();
+    return flushed;
+  }
+
+  /**
+   * Acknowledge delivery of a message by its id.
+   * Removes it from the queue to prevent duplicate re-sends.
+   */
+  ack(id: string): void {
+    const idx = this.queue.findIndex((m) => m.id === id);
+    if (idx !== -1) {
+      this.queue.splice(idx, 1);
+      this.persist();
+    }
+  }
+
+  /**
+   * Returns a snapshot of the current queue (read-only copy).
+   */
+  snapshot(): ReadonlyArray<Readonly<CachedMessage>> {
+    return [...this.queue];
+  }
+
+  /**
+   * Number of items currently in the queue.
+   */
+  get size(): number {
+    return this.queue.length;
+  }
+
+  /**
+   * Number of pending (not yet ACKed) items.
+   */
+  get pendingCount(): number {
+    return this.queue.filter((m) => m.status === 'pending').length;
+  }
+
+  // ─── Persistence ─────────────────────────────────────────────────────────────
+
+  /**
+   * Persist the current queue to the JSON file (if configured).
+   * Errors are silently swallowed to avoid disrupting the main flow.
+   */
+  private persist(): void {
+    if (!this.filePath) return;
+    try {
+      const dir = path.dirname(this.filePath);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(this.filePath, JSON.stringify(this.queue, null, 2), 'utf-8');
+    } catch {
+      // best-effort: silently ignore fs errors
+    }
+  }
+
+  /**
+   * Load queue from the JSON file on startup (if the file exists).
+   */
+  private loadFromFile(): void {
+    if (!this.filePath) return;
+    try {
+      if (!fs.existsSync(this.filePath)) return;
+      const raw = fs.readFileSync(this.filePath, 'utf-8');
+      const parsed = JSON.parse(raw) as unknown;
+      if (Array.isArray(parsed)) {
+        this.queue = parsed as CachedMessage[];
+      }
+    } catch {
+      // best-effort: ignore corrupt/missing files
+    }
+  }
+}

package/src/sdk/adapters/default.ts

@@ -0,0 +1,196 @@
+/******************************************************************
+ * Channel SDK - Default Adapter Factory
+ * 
+ * OpenClaw Channel SDK 的默认适配器工厂
+ * 
+ * @see https://github.com/chatu-ai/openclaw-web-hub-channel
+ ******************************************************************/
+
+import {
+  ConnectionConfig,
+  ChannelStats,
+  ConnectionStatus,
+  ChannelCapabilities,
+  MessageType,
+  TargetType,
+} from '../types/channel';
+import type {
+  ConnectionAdapter,
+  MessageAdapter,
+  HeartbeatAdapter,
+  AuthAdapter,
+  CapabilitiesAdapter,
+  LoggerAdapter,
+  MessageCallback,
+  StatusCallback,
+  AdapterFactory,
+} from '../types/adapters';
+import { WebSocketAdapter } from './websocket';
+import { v4 as uuidv4 } from 'uuid';
+
+/**
+ * 消息适配器实现 [Channel SDK 标准]
+ */
+class DefaultMessageAdapter implements MessageAdapter {
+  parseInbound(raw: unknown): any {
+    return raw;
+  }
+  
+  formatOutbound(message: any): any {
+    return message;
+  }
+  
+  validate(message: any): boolean {
+    return message && typeof message === 'object';
+  }
+  
+  sanitize(text: string): string {
+    return text
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;');
+  }
+}
+
+/**
+ * 心跳适配器实现 [Channel SDK 标准]
+ */
+class DefaultHeartbeatAdapter implements HeartbeatAdapter {
+  private lastResponse: number = Date.now();
+  private timeout: number;
+  
+  constructor(timeout: number = 10000) {
+    this.timeout = timeout;
+  }
+  
+  async send(): Promise<boolean> {
+    return true;
+  }
+  
+  handleResponse(): void {
+    this.lastResponse = Date.now();
+  }
+  
+  isTimeout(): boolean {
+    return Date.now() - this.lastResponse > this.timeout;
+  }
+  
+  getNextHeartbeatTime(): number {
+    return Date.now() + 30000;
+  }
+}
+
+/**
+ * 认证适配器实现 [Channel SDK 标准]
+ */
+class DefaultAuthAdapter implements AuthAdapter {
+  private token: string;
+  
+  constructor(token: string) {
+    this.token = token;
+  }
+  
+  getAuthHeaders(): Record<string, string> {
+    return {
+      'Authorization': `Bearer ${this.token}`,
+      'Content-Type': 'application/json',
+    };
+  }
+  
+  validateResponse(response: unknown): boolean {
+    return response !== null && response !== undefined;
+  }
+  
+  async refreshToken(): Promise<boolean> {
+    return true;
+  }
+}
+
+/**
+ * 能力适配器实现 [Channel SDK 标准]
+ */
+class DefaultCapabilitiesAdapter implements CapabilitiesAdapter {
+  async getCapabilities(): Promise<ChannelCapabilities> {
+    return {
+      messageTypes: [
+        MessageType.TEXT,
+        MessageType.IMAGE,
+        MessageType.VIDEO,
+        MessageType.AUDIO,
+        MessageType.FILE,
+      ],
+      targetTypes: [TargetType.USER, TargetType.GROUP],
+      richFormats: ['markdown'],
+      attachments: true,
+      reply: true,
+    };
+  }
+  
+  hasCapability(capability: keyof ChannelCapabilities): boolean {
+    return true;
+  }
+}
+
+/**
+ * 日志适配器实现 [Channel SDK 标准]
+ */
+class DefaultLoggerAdapter implements LoggerAdapter {
+  debug(message: string, data?: unknown): void {
+    console.debug(`[DEBUG] ${message}`, data || '');
+  }
+  
+  info(message: string, data?: unknown): void {
+    console.info(`[INFO] ${message}`, data || '');
+  }
+  
+  warn(message: string, data?: unknown): void {
+    console.warn(`[WARN] ${message}`, data || '');
+  }
+  
+  error(message: string, error?: Error): void {
+    console.error(`[ERROR] ${message}`, error || '');
+  }
+}
+
+/**
+ * 默认适配器工厂 [Channel SDK 标准]
+ * 
+ * 提供所有适配器的默认实现
+ */
+export class DefaultAdapterFactory implements AdapterFactory {
+  createConnectionAdapter(config: ConnectionConfig): ConnectionAdapter {
+    return new WebSocketAdapter(config);
+  }
+  
+  createMessageAdapter(): MessageAdapter {
+    return new DefaultMessageAdapter();
+  }
+  
+  createHeartbeatAdapter(): HeartbeatAdapter {
+    return new DefaultHeartbeatAdapter();
+  }
+  
+  createAuthAdapter(token?: string): AuthAdapter {
+    return new DefaultAuthAdapter(token || '');
+  }
+  
+  createCapabilitiesAdapter(): CapabilitiesAdapter {
+    return new DefaultCapabilitiesAdapter();
+  }
+  
+  createLoggerAdapter(): LoggerAdapter {
+    return new DefaultLoggerAdapter();
+  }
+}
+
+/**
+ * 创建默认工厂单例 [Channel SDK 标准]
+ */
+let factory: DefaultAdapterFactory | null = null;
+
+export function createDefaultFactory(): DefaultAdapterFactory {
+  if (!factory) {
+    factory = new DefaultAdapterFactory();
+  }
+  return factory;
+}