feishu-user-plugin 1.3.7 → 1.3.9

package/src/events/cursor.js

@@ -0,0 +1,103 @@
+// src/events/cursor.js — events.cursor.json + drain protocol.
+//
+// cursor.json schema: { version: 1, file: "events.jsonl", offset: <int> }
+// Atomic write: tmp + rename.
+// Drain: take per-operation mutex, read cursor, read events.jsonl[offset:], advance.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { withMutex } = require('./lockfile');
+const { readFrom } = require('./event-log');
+
+const CURSOR_FILENAME = 'events.cursor.json';
+const CURSOR_LOCK_FILENAME = 'events.cursor.lock';
+
+function _cursorPath(dir) { return path.join(dir, CURSOR_FILENAME); }
+function _lockPath(dir) { return path.join(dir, CURSOR_LOCK_FILENAME); }
+
+function _readCursor(cursorPath, defaultFileSize) {
+  try {
+    const raw = fs.readFileSync(cursorPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || parsed.version !== 1) throw new Error('bad version');
+    if (typeof parsed.file !== 'string' || typeof parsed.offset !== 'number') throw new Error('bad shape');
+    return parsed;
+  } catch (e) {
+    // Conservative reset: skip history (offset = current size), don't replay.
+    if (e.code !== 'ENOENT') {
+      console.error(`[feishu-user-plugin] cursor.json read failed: ${e.message}; resetting to current EOF.`);
+    }
+    return { version: 1, file: 'events.jsonl', offset: defaultFileSize };
+  }
+}
+
+function _writeCursorAtomic(cursorPath, cursor) {
+  const tmpPath = cursorPath + '.tmp.' + process.pid;
+  fs.writeFileSync(tmpPath, JSON.stringify(cursor) + '\n', { mode: 0o600 });
+  fs.renameSync(tmpPath, cursorPath);
+}
+
+// Sanity check: offset in [0, fileSize]. Returns clamped cursor.
+function _sanitize(cursor, fileSize) {
+  if (cursor.offset < 0 || cursor.offset > fileSize) {
+    console.error(`[feishu-user-plugin] cursor offset ${cursor.offset} out of range [0, ${fileSize}]; resetting to EOF.`);
+    return { ...cursor, offset: fileSize };
+  }
+  return cursor;
+}
+
+// Drain: read events from current offset; advance cursor (unless peek).
+//
+// Returns { events, nextOffset, advanced }.
+// `events` is the raw event objects from events.jsonl (filter applied by caller).
+function drain(dir, { peek = false } = {}) {
+  const logPath = path.join(dir, 'events.jsonl');
+  const curPath = _cursorPath(dir);
+  const lockPath = _lockPath(dir);
+
+  return withMutex(lockPath, () => {
+    let stat;
+    try { stat = fs.statSync(logPath); } catch (e) {
+      if (e.code === 'ENOENT') return { events: [], nextOffset: 0, advanced: false };
+      throw e;
+    }
+    let cursor = _readCursor(curPath, stat.size);
+    cursor = _sanitize(cursor, stat.size);
+
+    const { events, nextOffset } = readFrom(logPath, cursor.offset);
+    if (!peek && nextOffset !== cursor.offset) {
+      _writeCursorAtomic(curPath, { version: 1, file: 'events.jsonl', offset: nextOffset });
+      return { events, nextOffset, advanced: true };
+    }
+    // Always persist cursor.json on first drain (ENOENT) so subsequent calls
+    // don't trigger the conservative-reset-to-EOF path.
+    if (!peek) {
+      const exists = (() => { try { fs.statSync(curPath); return true; } catch (_) { return false; } })();
+      if (!exists) _writeCursorAtomic(curPath, { version: 1, file: 'events.jsonl', offset: nextOffset });
+    }
+    return { events, nextOffset, advanced: false };
+  }, { staleMs: 30_000 });
+}
+
+// Read cursor without advancing or locking — for diagnostics.
+function readSnapshot(dir) {
+  const logPath = path.join(dir, 'events.jsonl');
+  const curPath = _cursorPath(dir);
+  let fileSize = 0;
+  try { fileSize = fs.statSync(logPath).size; } catch (_) {}
+  const cursor = _readCursor(curPath, fileSize);
+  return { cursor, fileSize, pending: Math.max(0, fileSize - cursor.offset) };
+}
+
+// Manual reset (used by force-rotate path).
+function resetCursorTo(dir, offset) {
+  const curPath = _cursorPath(dir);
+  const lockPath = _lockPath(dir);
+  withMutex(lockPath, () => {
+    _writeCursorAtomic(curPath, { version: 1, file: 'events.jsonl', offset });
+  }, { staleMs: 30_000 });
+}
+
+module.exports = { drain, readSnapshot, resetCursorTo, CURSOR_FILENAME };

package/src/events/event-buffer.js

@@ -0,0 +1,103 @@
+// src/events/event-buffer.js — in-memory FIFO buffer.
+//
+// v1.3.9: This is now the **disk-full fallback** only. Normal flow writes
+// to events.jsonl via src/events/event-log.js. The owner falls back to this
+// buffer when fs.appendFileSync fails (ENOSPC etc); get_new_events does NOT
+// read from this buffer in the owner-arbitrated path. Pre-v1.3.8 behaviour
+// is preserved when no logPath is configured.
+//
+// (rest of file unchanged)
+//
+// What this owns:
+//   - _events: ordered list of events (oldest first)
+//   - cap: max retained; oldest dropped when full
+//   - push(event): append + trim
+//   - drain(filter?): remove and return matching events
+//   - peek(filter?): return matching events without removing
+//   - size, cap accessors
+
+const DEFAULT_CAP = 1000;
+
+class EventBuffer {
+  constructor({ cap = DEFAULT_CAP } = {}) {
+    this._events = [];
+    this._cap = Math.max(1, cap | 0);
+    this._totalSeen = 0;
+    this._totalDropped = 0;
+  }
+
+  push(event) {
+    if (!event || typeof event !== 'object') return;
+    if (!event._received_at) event._received_at = Math.floor(Date.now() / 1000);
+    this._events.push(event);
+    this._totalSeen++;
+    while (this._events.length > this._cap) {
+      this._events.shift();
+      this._totalDropped++;
+    }
+  }
+
+  drain(filter) {
+    if (!filter) {
+      const out = this._events;
+      this._events = [];
+      return out;
+    }
+    const fn = this._compileFilter(filter);
+    const kept = [];
+    const drained = [];
+    for (const e of this._events) {
+      if (fn(e)) drained.push(e);
+      else kept.push(e);
+    }
+    this._events = kept;
+    return drained;
+  }
+
+  peek(filter) {
+    if (!filter) return [...this._events];
+    const fn = this._compileFilter(filter);
+    return this._events.filter(fn);
+  }
+
+  size() { return this._events.length; }
+  cap() { return this._cap; }
+  stats() {
+    return {
+      size: this._events.length,
+      cap: this._cap,
+      totalSeen: this._totalSeen,
+      totalDropped: this._totalDropped,
+    };
+  }
+
+  // Filter language (intentionally narrow — extend on demand):
+  //   { event_type: "im.message.receive_v1" }       — exact match on type
+  //   { chat_id: "oc_zzz" }                         — extract from event payload
+  //   { since_seconds: 60 }                         — only events received in last N sec
+  //   { event_types: ["a", "b"] }                   — any of these types
+  // Multiple keys = AND.
+  _compileFilter(filter) {
+    return (e) => {
+      if (filter.event_type && e.event_type !== filter.event_type) return false;
+      if (filter.event_types && !filter.event_types.includes(e.event_type)) return false;
+      if (filter.chat_id) {
+        const chatId = this._extractChatId(e);
+        if (chatId !== filter.chat_id) return false;
+      }
+      if (filter.since_seconds) {
+        const cutoff = Math.floor(Date.now() / 1000) - filter.since_seconds;
+        if ((e._received_at || 0) < cutoff) return false;
+      }
+      return true;
+    };
+  }
+
+  _extractChatId(e) {
+    return e?.event?.message?.chat_id
+        || e?.event?.chat_id
+        || null;
+  }
+}
+
+module.exports = { EventBuffer, DEFAULT_CAP };

package/src/events/event-log.js

@@ -0,0 +1,151 @@
+// src/events/event-log.js — events.jsonl management.
+//
+// Single-writer (owner) appends with `\n`-terminated lines.
+// Multi-reader (any process) seeks from cursor offset to EOF, parses lines,
+// tolerates a trailing partial line.
+//
+// On owner takeover, callers should run repairTail() once before appending
+// to ensure append-only invariant is intact.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function ensureLog(logPath) {
+  try { fs.mkdirSync(path.dirname(logPath), { recursive: true, mode: 0o700 }); } catch (_) {}
+  try { fs.openSync(logPath, 'a'); } catch (_) {}
+}
+
+function appendEvent(logPath, eventObj) {
+  const line = JSON.stringify(eventObj) + '\n';
+  fs.appendFileSync(logPath, line, { encoding: 'utf8' });
+}
+
+// Read from `offset` to EOF; return { events: [...], nextOffset }.
+// Tolerates a trailing partial line (no \n) — partial line not consumed,
+// nextOffset stops at the last full \n.
+function readFrom(logPath, offset) {
+  let stat;
+  try { stat = fs.statSync(logPath); } catch (e) {
+    if (e.code === 'ENOENT') return { events: [], nextOffset: 0, fileSize: 0 };
+    throw e;
+  }
+  const fileSize = stat.size;
+  if (offset >= fileSize) return { events: [], nextOffset: offset, fileSize };
+  if (offset < 0) offset = 0;
+
+  const fd = fs.openSync(logPath, 'r');
+  try {
+    const length = fileSize - offset;
+    const buf = Buffer.allocUnsafe(length);
+    fs.readSync(fd, buf, 0, length, offset);
+    const text = buf.toString('utf8');
+    // Find last \n; everything after it is partial.
+    const lastNl = text.lastIndexOf('\n');
+    if (lastNl < 0) {
+      // Entire chunk is partial; no events consumed.
+      return { events: [], nextOffset: offset, fileSize };
+    }
+    const fullText = text.slice(0, lastNl + 1);  // include the \n
+    const events = [];
+    for (const line of fullText.split('\n')) {
+      if (!line) continue;
+      try { events.push(JSON.parse(line)); } catch (_) { /* skip malformed */ }
+    }
+    return { events, nextOffset: offset + Buffer.byteLength(fullText, 'utf8'), fileSize };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// Repair: scan the tail for last \n; truncate file there if file ends with
+// non-\n bytes (partial line from a crash).
+function repairTail(logPath, scanBytes = 8192) {
+  let stat;
+  try { stat = fs.statSync(logPath); } catch (e) {
+    if (e.code === 'ENOENT') return { repaired: false, sizeBefore: 0, sizeAfter: 0 };
+    throw e;
+  }
+  if (stat.size === 0) return { repaired: false, sizeBefore: 0, sizeAfter: 0 };
+
+  const fd = fs.openSync(logPath, 'r+');
+  try {
+    const readLen = Math.min(scanBytes, stat.size);
+    const buf = Buffer.allocUnsafe(readLen);
+    fs.readSync(fd, buf, 0, readLen, stat.size - readLen);
+    // If the file already ends in \n, no repair needed.
+    if (buf[buf.length - 1] === 0x0A) return { repaired: false, sizeBefore: stat.size, sizeAfter: stat.size };
+    // Find last \n in the scanned tail.
+    let i = buf.length - 1;
+    while (i >= 0 && buf[i] !== 0x0A) i--;
+    if (i < 0) {
+      // No \n in last 8 KB — pathological. Don't truncate (might lose data); leave as is.
+      return { repaired: false, sizeBefore: stat.size, sizeAfter: stat.size, warning: 'no \\n in scan window' };
+    }
+    const truncateAt = stat.size - readLen + i + 1;  // +1 to keep the \n
+    fs.ftruncateSync(fd, truncateAt);
+    return { repaired: true, sizeBefore: stat.size, sizeAfter: truncateAt };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// Defer-rotate. Returns true if rotation happened.
+//
+// Conditions: size > sizeThresholdBytes AND (cursorOffset >= size - 4096) — i.e.,
+// consumer is within 4 KB of EOF.
+function maybeRotate(logPath, cursorOffset, sizeThresholdBytes) {
+  let stat;
+  try { stat = fs.statSync(logPath); } catch (e) {
+    if (e.code === 'ENOENT') return { rotated: false };
+    throw e;
+  }
+  if (stat.size <= sizeThresholdBytes) return { rotated: false, sizeBytes: stat.size };
+  if (cursorOffset < stat.size - 4096) {
+    return { rotated: false, deferred: true, sizeBytes: stat.size, cursorOffset };
+  }
+  const ts = Math.floor(Date.now() / 1000);
+  const droppedPath = logPath + '.dropped-' + ts;
+  fs.renameSync(logPath, droppedPath);
+  // Recreate empty events.jsonl.
+  fs.openSync(logPath, 'a');
+  return { rotated: true, droppedPath, sizeBytes: stat.size };
+}
+
+// Force rotate (called when log > hardCap and consumer is too far behind).
+// Drops the current log to .dropped-<ts>, writes a synthetic _rotated event
+// to the new log so consumers see the warning.
+function forceRotate(logPath, prevSize) {
+  const ts = Math.floor(Date.now() / 1000);
+  const droppedPath = logPath + '.dropped-' + ts;
+  try { fs.renameSync(logPath, droppedPath); } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  appendEvent(logPath, {
+    event_id: '_rotated',
+    ts: ts * 1000,
+    profile: '_system',
+    payload: { warning: 'force_rotated_log', prev_size: prevSize, dropped_file: path.basename(droppedPath) },
+  });
+  return { droppedPath };
+}
+
+// Cleanup of old .dropped-<ts> files. Keep last `keepDays` worth.
+function cleanupDropped(logPath, keepDays = 7) {
+  const dir = path.dirname(logPath);
+  const base = path.basename(logPath);
+  const cutoffMs = Date.now() - keepDays * 86400_000;
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch (_) { return; }
+  for (const name of entries) {
+    if (!name.startsWith(base + '.dropped-')) continue;
+    const fp = path.join(dir, name);
+    try {
+      const stat = fs.statSync(fp);
+      if (stat.mtimeMs < cutoffMs) fs.unlinkSync(fp);
+    } catch (_) {}
+  }
+}
+
+module.exports = { ensureLog, appendEvent, readFrom, repairTail, maybeRotate, forceRotate, cleanupDropped };

package/src/events/index.js

@@ -0,0 +1,12 @@
+// src/events/index.js — barrel import for the events subsystem.
+const { EventBuffer, DEFAULT_CAP } = require('./event-buffer');
+const { createWSServer } = require('./ws-server');
+const owner = require('./owner');
+const cursor = require('./cursor');
+const log = require('./event-log');
+const lockfile = require('./lockfile');
+
+module.exports = {
+  EventBuffer, DEFAULT_CAP, createWSServer,
+  owner, cursor, log, lockfile,
+};

package/src/events/lockfile.js

@@ -0,0 +1,126 @@
+// src/events/lockfile.js — generic O_CREAT|O_EXCL advisory lock.
+//
+// Two flavors:
+//   - acquireLongLived(path, info) → { release(), heartbeat() } for owner-style
+//     locks (one process holds for the duration of its lifetime, mtime = liveness).
+//     Steal: rename old → .stale-<pid>, then EXCL create. Returns null if active.
+//   - withMutex(path, fn, { staleMs }) → runs fn() while holding a per-operation
+//     mutex. Stale lock files (mtime older than staleMs) are reaped.
+//
+// Both reuse the same `fs.openSync(p, 'wx')` pattern v1.3.5 UAT lock established.
+// No new dep.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function _ensureDir(p) {
+  try { fs.mkdirSync(path.dirname(p), { recursive: true, mode: 0o700 }); } catch (_) {}
+}
+
+function _writeLockBody(fd, info) {
+  const body = JSON.stringify({ version: 1, pid: process.pid, start_time: Math.floor(Date.now() / 1000), ...info });
+  fs.writeSync(fd, body);
+}
+
+// Long-lived (owner) acquisition.
+//
+// Returns { release(), heartbeat() } on success.
+// Returns null if lock active (mtime within staleMs).
+function acquireLongLived(lockPath, { info = {}, staleMs = 60_000 } = {}) {
+  _ensureDir(lockPath);
+
+  // If lock exists, check staleness.
+  let stat;
+  try { stat = fs.statSync(lockPath); } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  if (stat) {
+    const ageMs = Date.now() - stat.mtimeMs;
+    if (ageMs < staleMs) return null;
+    // Stale — try to steal. Rename out of the way to make room for EXCL create.
+    const stolenPath = lockPath + '.stale-' + process.pid + '-' + Date.now();
+    try { fs.renameSync(lockPath, stolenPath); } catch (e) {
+      // Race: someone else got there first; try again from scratch.
+      if (e.code === 'ENOENT') return acquireLongLived(lockPath, { info, staleMs });
+      throw e;
+    }
+    // Schedule cleanup of the stolen file after a moment to avoid disk litter.
+    setTimeout(() => { try { fs.unlinkSync(stolenPath); } catch (_) {} }, 5000).unref();
+  }
+
+  // Atomic EXCL create — only one process wins this race.
+  let fd;
+  try {
+    fd = fs.openSync(lockPath, 'wx');
+  } catch (e) {
+    if (e.code === 'EEXIST') return null;  // someone else won
+    throw e;
+  }
+  try {
+    _writeLockBody(fd, info);
+  } finally {
+    fs.closeSync(fd);
+  }
+
+  return {
+    release() {
+      try { fs.unlinkSync(lockPath); } catch (_) {}
+    },
+    heartbeat() {
+      try {
+        const now = new Date();
+        fs.utimesSync(lockPath, now, now);
+      } catch (e) {
+        // If the lock file was stolen, our heartbeat will fail. Caller must
+        // detect this via separate check (e.g., re-stat + compare pid in body).
+        return false;
+      }
+      return true;
+    },
+  };
+}
+
+// Per-operation mutex. Synchronous wrapper for short critical sections.
+function withMutex(lockPath, fn, { staleMs = 30_000, retries = 30, retryDelayMs = 100 } = {}) {
+  _ensureDir(lockPath);
+
+  const start = Date.now();
+  while (true) {
+    // Stale reap.
+    try {
+      const stat = fs.statSync(lockPath);
+      if (Date.now() - stat.mtimeMs > staleMs) {
+        try { fs.unlinkSync(lockPath); } catch (_) {}
+      }
+    } catch (e) {
+      if (e.code !== 'ENOENT') throw e;
+    }
+
+    let fd;
+    try {
+      fd = fs.openSync(lockPath, 'wx');
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      // Wait + retry.
+      if (Date.now() - start > staleMs) {
+        throw new Error(`withMutex: lock ${lockPath} held longer than ${staleMs}ms`);
+      }
+      const sleepUntil = Date.now() + retryDelayMs;
+      while (Date.now() < sleepUntil) { /* busy wait — short delay */ }
+      continue;
+    }
+
+    try {
+      fs.writeSync(fd, JSON.stringify({ pid: process.pid, ts: Date.now() }));
+      fs.closeSync(fd);
+      const result = fn();
+      return result;
+    } finally {
+      try { fs.unlinkSync(lockPath); } catch (_) {}
+    }
+  }
+}
+
+module.exports = { acquireLongLived, withMutex };

package/src/events/owner.js

@@ -0,0 +1,73 @@
+// src/events/owner.js — ws-owner.lock acquire / heartbeat / takeover.
+//
+// Wraps lockfile.acquireLongLived for the WS-ownership use case.
+// Exposes an EventEmitter-style interface: 'become_owner', 'lose_owner', 'state_change'.
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { acquireLongLived } = require('./lockfile');
+
+const OWNER_LOCK_FILENAME = 'ws-owner.lock';
+const HEARTBEAT_INTERVAL_MS = 15_000;
+const STALE_MS = 60_000;
+const TAKEOVER_POLL_INTERVAL_MS = 30_000;
+
+function _ownerLockPath(dir) { return path.join(dir, OWNER_LOCK_FILENAME); }
+
+// Try to claim ownership (or steal if stale + force, or just steal if stale).
+// Returns:
+//   { isOwner: true, release(), heartbeat() } if successful
+//   { isOwner: false, ownerInfo } otherwise
+function tryClaim(dir, { info = {}, force = false } = {}) {
+  const lockPath = _ownerLockPath(dir);
+
+  if (force) {
+    // Force takeover: rename existing out of the way.
+    try { fs.renameSync(lockPath, lockPath + '.forced-' + Date.now()); } catch (e) {
+      if (e.code !== 'ENOENT') throw e;
+    }
+  }
+
+  const handle = acquireLongLived(lockPath, { info, staleMs: STALE_MS });
+  if (!handle) {
+    // Read existing lock body for diagnostics.
+    let body = null;
+    try { body = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch (_) {}
+    let mtimeMs = null;
+    try { mtimeMs = fs.statSync(lockPath).mtimeMs; } catch (_) {}
+    return { isOwner: false, ownerInfo: { ...body, mtimeMs, last_heartbeat_age_seconds: mtimeMs ? Math.floor((Date.now() - mtimeMs) / 1000) : null } };
+  }
+  return { isOwner: true, ...handle };
+}
+
+// Read current owner info without modifying anything.
+function readOwnerInfo(dir) {
+  const lockPath = _ownerLockPath(dir);
+  let body = null;
+  let mtimeMs = null;
+  try {
+    body = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+    mtimeMs = fs.statSync(lockPath).mtimeMs;
+  } catch (_) {}
+  if (!body) return { exists: false };
+  const ageSec = mtimeMs ? Math.floor((Date.now() - mtimeMs) / 1000) : null;
+  return {
+    exists: true,
+    pid: body.pid,
+    start_time: body.start_time,
+    mtimeMs,
+    last_heartbeat_age_seconds: ageSec,
+    alive: ageSec !== null && ageSec * 1000 < STALE_MS,
+  };
+}
+
+module.exports = {
+  tryClaim,
+  readOwnerInfo,
+  OWNER_LOCK_FILENAME,
+  HEARTBEAT_INTERVAL_MS,
+  STALE_MS,
+  TAKEOVER_POLL_INTERVAL_MS,
+};