lark-relay 0.6.4 → 0.6.5

package/README.md

@@ -37,6 +37,7 @@ user 未登录或授权过期不影响 bot 采集,bot 凭据和权限由 `lark-c
 - app 和消费名称不能含路径分隔符、控制字符、首尾空白或以点开头
 - `--filter` 是唯一业务过滤入口,使用 jq 表达式;语法错误在启动前拒绝
 - jq 求值失败或输出不完整时中止取批,不输出消息、不提交待交付批次的断点;修正后可重取
+- 损坏的事件文件跳过并告警,不中止取批 —— 硬失败会把断点永久停在它前面
 - 默认防抖 5 秒,从第一条消息起最多攒 25 秒,本次取用总超时 12 小时
 - `--render` 支持 `ndjson`(默认)和按群/话题分组的 `text`
 - 参数校验完成后 stderr 输出「监听中」;未知参数、位置参数、缺值和空值均报错
@@ -57,7 +58,9 @@ user 未登录或授权过期不影响 bot 采集,bot 凭据和权限由 `lark-c
 已有断点始终续接,不按空闲时长过期;首次取用由 `--since now|all` 决定起点,默认 `now`
 需要从新的起点消费时使用新的 `--name`
 两种首次起点都会创建断点,没有事件时也可通过 `status` 查看等待中的消费者
-断点和事件文件读取失败或内容损坏时明确报错,不会当成首次消费或空数据继续推进
+断点和事件文件读取失败时明确报错,不会当成首次消费或空数据继续推进
+损坏的事件文件不中止 `take`、采集或 `status`:三者都跳过它并告警,断点越过它继续。
+那几条消息永久丢失 —— `status` 标记该 app 并返回非零,复核后删除坏文件
 
 采集端 `--retain` 指定事件保留天数(默认 3 个自然日,含今天),启动时及每小时回收超期目录
 回收失败写入采集日志,排除文件系统错误后在下一轮重试
@@ -73,6 +76,7 @@ user 未登录或授权过期不影响 bot 采集,bot 凭据和权限由 `lark-c
 - 写入失败时清理本次临时文件,原断点保持不变
 - 按日期及数值文件名排序;stamp 在采集进程内严格递增
 - 按 message_id 去重,进程启动或跨天后的首条消息前从当天文件恢复集合
+- 损坏文件在恢复去重时跳过并告警,其 message_id 不在集合内,该条重投会重复落盘
 - 每 500ms 扫描保留的全部日期,不引入额外扫描窗口
 - 参数由 Node 内置解析器处理,不兼容已移除的命令或参数
 
@@ -88,6 +92,7 @@ user 未登录或授权过期不影响 bot 采集,bot 凭据和权限由 `lark-c
 `status` 中 collect running 只说明主进程在跑,各 app 是否连接成功需查看采集日志
 `collect.profiles` 列出已配置 profile,不表示正在采集,也不反映 collect 的 `--exclude`
 profile 查询失败时 `status` 保留本地状态并以 exit 1 返回,错误见 `collect.profileError` 或文本输出
+某个 app 有损坏事件时同样以 exit 1 返回,错误见该 app 的 `error` 字段或文本中的 ⚠ 标记
 
 ## 许可
 

package/bin/lark-relay.js

@@ -104,6 +104,14 @@ async function cmdTake(argv) {
     timeoutMs,
     signal: ac.signal,
   })
+  // 跳过的坏文件必须显式说出来:它们是永久丢掉的消息,不是延迟送达。
+  // 退出码保持批次语义,否则调用方会把已交付的一批当成失败丢弃
+  if (res.skipped.length) {
+    process.stderr.write(
+      `warn: 跳过 ${res.skipped.length} 个损坏的事件文件,这些消息永久丢失:` +
+        `${res.skipped.join(' ')}\n  用 lark-relay status 复核,确认后删除坏文件\n`,
+    )
+  }
   if (!res.events.length) {
     process.stderr.write(`没等到消息(${res.reason}),再起一个继续\n`)
     return res.reason === 'timeout' ? 4 : 0
@@ -122,7 +130,8 @@ async function cmdStatus(argv) {
   const { buildStatus, formatStatus } = require('../lib/status')
   const s = await buildStatus()
   process.stdout.write(`${a.json ? JSON.stringify(s, null, 2) : formatStatus(s)}\n`)
-  return s.collect.profileError ? 1 : 0
+  // 输出完整,但异常仍以退出码透出,便于脚本发现
+  return s.collect.profileError || s.apps.some((r) => r.error) ? 1 : 0
 }
 
 // 自然排空 stdout,避免大批次经管道输出时被截断

package/lib/collect.js

@@ -31,8 +31,19 @@ class AppCollector {
       this.day = today
       this.seen = null
     }
-    // 首条消息前恢复当天去重;读取失败可在下次重试,不阻断其他 app 启动
-    if (this.seen === null) this.seen = store.seedIds(this.app, this.day)
+    // 首条消息前恢复当天去重;读不出的文件跳过,不阻断落盘
+    if (this.seen === null) {
+      const { ids, skipped } = store.seedIds(this.app, this.day)
+      this.seen = ids
+      // 跳过的文件其 message_id 不在集合内,那几条重投会重复落盘;
+      // 换来的是这个 app 继续采集,而不是每条消息都在 seed 上再失败一次
+      if (skipped.length) {
+        logLine(
+          `[${this.app}] warn: 恢复去重不完整,跳过 ${skipped.join(' ')};` +
+            `这些消息的 message_id 不在去重集合内,重投会重复落盘`,
+        )
+      }
+    }
     const id = obj?.message_id
     if (id && this.seen.has(id)) return false
     store.writeEvent(this.app, obj, this.seq++)

package/lib/help.js

@@ -30,7 +30,8 @@ const TAKE_HELP = `需要 --app 和 --chats,监听要求 bot 已在群内
 断点持续保留,不随空闲时间过期;store 只保留采集端设定天数的消息
 使用新的 --name 可从新的起点消费
 app 和消费名称不能含路径分隔符、控制字符、首尾空白或以点开头
-读取或过滤失败时中止取批并保留待交付批次的断点,修正后可重取
+过滤失败时中止取批并保留待交付批次的断点,修正后可重取
+损坏的事件文件跳过并在 stderr 告警,断点越过它继续 —— 那几条消息永久丢失
 
 退出码:0=有一批/帮助/信号退出,1=运行错误,2=参数错,3=身份被占用,4=超时无消息`
 
@@ -70,6 +71,7 @@ const STATUS_HELP = `lark-relay status -- 采集状态、事件数量和消费
 首次 --since all 等待中也会保留起始断点
 profiles 列出已配置项,不表示正在采集,也不反映 collect 的 --exclude
 profile 查询失败时保留本地状态并以 exit 1 返回,错误见 collect.profileError
+扫描全部保留日期,任意位置的损坏事件都标记 ⚠ 并以 exit 1 返回,其余 app 照常显示
 collect running 只表示主进程在跑,各 app 的连接状态需查看采集日志`
 
 module.exports = { TAKE_HELP, COLLECT_HELP, STATUS_HELP }

package/lib/lock.js

@@ -87,4 +87,4 @@ function holderPid(key) {
   return alive(pid) ? pid : null
 }
 
-module.exports = { acquireExclusive, lockPathFor, holderPid }
+module.exports = { acquireExclusive, holderPid }

package/lib/render.js

@@ -8,9 +8,9 @@ function fmtTime(ts) {
   return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`
 }
 
+// 事件体里没有发送者姓名:mentions 只装被 @ 的人,实测 861 条真实事件
+// 无一条把 sender_id 收进 mentions。要姓名需另查通讯录,不在渲染层做
 function senderLabel(e) {
-  const mention = (e.mentions || []).find((m) => m && m.id === e.sender_id)
-  if (mention && mention.name) return mention.name
   return e.sender_id || 'unknown'
 }
 
@@ -61,4 +61,4 @@ function render(events, mode) {
   return renderNdjson(events)
 }
 
-module.exports = { render, renderText }
+module.exports = { render }

package/lib/status.js

@@ -73,12 +73,27 @@ async function buildStatus() {
 
   const apps = [...new Set([...store.listApps(), ...profiles, ...byApp.keys()])].sort()
   const rows = apps.map((app) => {
-    const latest = store.latestEntry(app)
-    const ev = latest ? store.readEvent(latest) : null
+    // 扫全量:坏文件不在最新位置时同样要报出来 —— take 会跳过它,
+    // 而 status 是唯一的排障入口。实测本机 905 个事件全读约 23ms
+    const corrupt = []
+    let latestMs = null
+    for (const entry of store.scanAll(app)) {
+      let ev
+      try {
+        ev = store.readEvent(entry)
+      } catch (err) {
+        if (!err.corrupt) throw err
+        corrupt.push(`${entry.day}/${entry.name}`)
+        continue
+      }
+      // 最新时间取最后一条读得出的事件,坏文件不该让它变成「—」
+      if (ev) latestMs = Number(ev.timestamp) || latestMs
+    }
     return {
       app,
       today: store.countToday(app),
-      latestMs: Number(ev?.timestamp) || null,
+      latestMs,
+      error: corrupt.length ? `${corrupt.length} 个事件文件损坏:${corrupt.join(' ')}` : null,
       consumers: byApp.get(app) || [],
     }
   })
@@ -127,14 +142,16 @@ function formatStatus(s) {
   for (const r of s.apps) {
     if (!r.consumers.length) {
       out.push(`${w(r.app, 8)}${w(r.today, 10)}${w(ago(r.latestMs), 13)}—(无消费者)`)
-      continue
-    }
-    // 消费者各占一行:「谁在跑」是排障第一问,挤在一行里 ●/○ 会被淹掉
-    out.push(`${w(r.app, 8)}${w(r.today, 10)}${w(ago(r.latestMs), 13)}`.trimEnd())
-    for (const c of r.consumers) {
-      const note = c.pid ? `在跑 (pid ${c.pid})` : '未运行 (断点保留)'
-      out.push(`  ${w(c.name, 24)}${c.pid ? '●' : '○'} ${note}`)
+    } else {
+      // 消费者各占一行:「谁在跑」是排障第一问,挤在一行里 ●/○ 会被淹掉
+      out.push(`${w(r.app, 8)}${w(r.today, 10)}${w(ago(r.latestMs), 13)}`.trimEnd())
+      for (const c of r.consumers) {
+        const note = c.pid ? `在跑 (pid ${c.pid})` : '未运行 (断点保留)'
+        out.push(`  ${w(c.name, 24)}${c.pid ? '●' : '○'} ${note}`)
+      }
     }
+    // 坏文件会让该 app 的采集跳过去重、take 直接失败,必须显式暴露
+    if (r.error) out.push(`  ⚠ ${r.error}`)
   }
   out.push('')
   out.push(

package/lib/store.js

@@ -95,20 +95,37 @@ function readEvent(entry) {
     if (!event || typeof event !== 'object' || Array.isArray(event)) throw new Error('需要 JSON 对象')
     return event
   } catch (err) {
-    throw Object.assign(new Error(`事件文件损坏:${entry.file}: ${err.message}`), { userFacing: true })
+    // corrupt:盘上数据坏了,重试不会好转。与 EACCES 等瞬时错误区分开,
+    // 让只读概览和采集能跳过单个坏文件继续跑;take 仍然硬失败
+    throw Object.assign(new Error(`事件文件损坏:${entry.file}: ${err.message}`), {
+      userFacing: true, corrupt: true,
+    })
   }
 }
 
-// 重启后从当天事件恢复 message_id 去重集合
+// 重启后从当天事件恢复 message_id 去重集合。
+// 去重是尽力而为的优化,不是落盘的前置条件:任何读不出的文件都跳过并回报,
+// 最坏结果是那几条重投时重复落盘,比为它们丢掉后续所有消息轻得多
 function seedIds(app, day = dayKey()) {
   const ids = new Set()
-  for (const name of readDir(paths.appDay(app, day))) {
+  const skipped = []
+  const dir = paths.appDay(app, day)
+  let names
+  try {
+    names = readDir(dir) // ENOENT 已按空目录处理,这里兜的是 EACCES 等
+  } catch (err) {
+    return { ids, skipped: [`整个目录读不出(${err.code || err.message})`] }
+  }
+  for (const name of names) {
     if (!isEventName(name)) continue
-    const ev = readEvent({ file: path.join(paths.appDay(app, day), name) })
-    const id = ev?.message_id
-    if (id) ids.add(id)
+    try {
+      const ev = readEvent({ file: path.join(dir, name) })
+      if (ev?.message_id) ids.add(ev.message_id)
+    } catch {
+      skipped.push(name)
+    }
   }
-  return ids
+  return { ids, skipped }
 }
 
 function readCursor(name, app) {
@@ -186,10 +203,8 @@ module.exports = {
   seedCursor,
   afterCursor,
   entryKey,
-  cmpEntry,
   cmpName,
   countToday,
-  latestEntry,
   listApps,
   gcStore,
 }

package/lib/take.js

@@ -46,8 +46,9 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
 
 /**
  * 阻塞等一批事件。
- * @returns {Promise<{events:array, reason:string, cursor:string|null}>}
+ * @returns {Promise<{events:array, reason:string, cursor:string|null, skipped:string[]}>}
  *   reason: batch | timeout | signal
+ *   skipped: 跳过的损坏事件文件名,调用方负责告警
  */
 async function takeBatch(opts) {
   const {
@@ -65,6 +66,7 @@ async function takeBatch(opts) {
   const chatSet = new Set(chats)
   const startedAt = Date.now()
   const batch = []
+  const skipped = []
   let firstAt = null
   let lastNewAt = null
   let cursor = store.readCursor(name, app)
@@ -73,14 +75,23 @@ async function takeBatch(opts) {
     // 信号退出也交付已攒的批次,提交时机与正常退出一致
     if (signal && signal.aborted) {
       if (batch.length && cursor) store.writeCursor(name, app, cursor)
-      return { events: batch, reason: batch.length ? 'batch' : 'signal', cursor }
+      return { events: batch, reason: batch.length ? 'batch' : 'signal', cursor, skipped }
     }
 
     const entries = store.scanAll(app).filter((e) => store.afterCursor(e, cursor))
     const fresh = []
     for (const entry of entries) {
       cursor = store.entryKey(entry)
-      const ev = store.readEvent(entry)
+      let ev
+      try {
+        ev = store.readEvent(entry)
+      } catch (err) {
+        // 损坏是永久错误:硬失败会让断点停在它前面,把它之后的好消息也永久取不到。
+        // 跳过并推进,损失是这一条;由调用方告警,status 也会标记它
+        if (!err.corrupt) throw err
+        skipped.push(`${entry.day}/${entry.name}`)
+        continue
+      }
       if (!ev) continue // 扫描后已被 GC 回收
       if (ev.type !== 'im.message.receive_v1') continue
       if (chatSet.size && !chatSet.has(ev.chat_id)) continue
@@ -108,13 +119,13 @@ async function takeBatch(opts) {
       if (quiet || capped) {
         // at-most-once:交付前提交,不等待业务处理确认
         if (cursor) store.writeCursor(name, app, cursor)
-        return { events: batch, reason: 'batch', cursor }
+        return { events: batch, reason: 'batch', cursor, skipped }
       }
     }
 
     if (Date.now() - startedAt >= timeoutMs) {
       if (batch.length && cursor) store.writeCursor(name, app, cursor)
-      return { events: batch, reason: batch.length ? 'batch' : 'timeout', cursor }
+      return { events: batch, reason: batch.length ? 'batch' : 'timeout', cursor, skipped }
     }
 
     await sleep(pollMs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lark-relay",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "Lark event relay: collect events to disk, take a batch when you need it.",
   "keywords": [
     "lark",