lark-relay 0.6.4 → 0.6.6

package/README.md

@@ -23,9 +23,9 @@ lark-relay take --app <app> --chats oc_xxx --render text
 lark-relay status
 ```
 
-采集在启动时读取 `lark-cli profile list`,每个未被 `--exclude` 排除的 profile 启动一个 bot consumer
+采集在启动时读取 `lark-cli profile list`,每个 profile 启动一个 bot consumer
 user 未登录或授权过期不影响 bot 采集,bot 凭据和权限由 `lark-cli event consume --as bot` 检查
-认证或连接失败会记录 CLI 错误并独立退避重试,无需采集的 profile 用 `--exclude` 排除
+认证或连接失败会记录 CLI 错误并独立退避重试
 新增或移除 profile 后需重启采集
 同一 app 的事件总线只允许一个实例,本地互斥锁按 `LARK_RELAY_HOME` 隔离
 
@@ -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,21 +76,23 @@ user 未登录或授权过期不影响 bot 采集,bot 凭据和权限由 `lark-c
 - 写入失败时清理本次临时文件,原断点保持不变
 - 按日期及数值文件名排序;stamp 在采集进程内严格递增
 - 按 message_id 去重,进程启动或跨天后的首条消息前从当天文件恢复集合
+- 损坏文件在恢复去重时跳过并告警,其 message_id 不在集合内,该条重投会重复落盘
 - 每 500ms 扫描保留的全部日期,不引入额外扫描窗口
 - 参数由 Node 内置解析器处理,不兼容已移除的命令或参数
 
 ## macOS 常驻部署
 
 - 使用 LaunchDaemon + UserName,开机即起,不依赖 GUI 登录
-- ProgramArguments 写可执行文件的绝对路径,显式设置 HOME/PATH/UTF-8 locale
+- ProgramArguments 写可执行文件的绝对路径,显式设置 HOME/PATH
 - KeepAlive 使用 SuccessfulExit=false;日志路径父目录须预先创建
 - 代码升级后用 `kickstart -k`,修改 plist 后用 `bootout`、等 label 释放、再 `bootstrap`
 
 日志直写 stderr,每行带 ISO 时间戳,不做轮转
 需要缩减日志时截断文件,不要删除或替换 launchd 持有的文件
 `status` 中 collect running 只说明主进程在跑,各 app 是否连接成功需查看采集日志
-`collect.profiles` 列出已配置 profile,不表示正在采集,也不反映 collect 的 `--exclude`
+`collect.profiles` 列出已配置 profile,不表示正在采集
 profile 查询失败时 `status` 保留本地状态并以 exit 1 返回,错误见 `collect.profileError` 或文本输出
+某个 app 有损坏事件时同样以 exit 1 返回,错误见该 app 的 `error` 字段或文本中的 ⚠ 标记
 
 ## 许可
 

package/bin/lark-relay-collect.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 'use strict'
 
-require('../lib/utf8').ensureUtf8()
 process.title = 'lark-relay-collect'
 
 const { parseArgs, numberArg } = require('../lib/args')
@@ -9,7 +8,7 @@ const { COLLECT_HELP } = require('../lib/help')
 const VERSION = require('../package.json').version
 
 async function main() {
-  const a = parseArgs(process.argv.slice(2), { keys: ['exclude', 'retain'], flags: ['version'] })
+  const a = parseArgs(process.argv.slice(2), { keys: ['retain'], flags: ['version'] })
   if (a.help || a.version) {
     process.stdout.write(`${a.version ? VERSION : COLLECT_HELP}\n`)
     return 0
@@ -20,10 +19,7 @@ async function main() {
     return 2
   }
   const { runCollect } = require('../lib/collect')
-  return runCollect({
-    exclude: a.exclude ? a.exclude.split(',').map((s) => s.trim()).filter(Boolean) : [],
-    retain,
-  })
+  return runCollect({ retain })
 }
 
 main()

package/bin/lark-relay.js

@@ -1,8 +1,6 @@
 #!/usr/bin/env node
 'use strict'
 
-require('../lib/utf8').ensureUtf8()
-
 const { parseArgs, numberArg } = require('../lib/args')
 const help = require('../lib/help')
 const VERSION = require('../package.json').version
@@ -104,6 +102,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 +128,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++)
@@ -128,7 +139,6 @@ async function runCollect(opts) {
     return 1
   }
 
-  const exclude = new Set(opts.exclude || [])
   let profiles
   try {
     profiles = await larkcli.listProfiles()
@@ -143,24 +153,18 @@ async function runCollect(opts) {
     return 1
   }
 
-  const chosen = profiles.filter((name) => !exclude.has(name))
-  const skipped = profiles.filter((name) => exclude.has(name))
-
-  if (skipped.length) {
-    logLine(`跳过 --exclude: ${skipped.join(' ')}`)
-  }
-  if (!chosen.length) {
-    logLine('error: 没有待采集的 profile,检查 `lark-cli profile list` 和 --exclude')
+  if (!profiles.length) {
+    logLine('error: 没有待采集的 profile,检查 `lark-cli profile list`')
     return 1
   }
 
   logLine(
-    `lark-relay-collect: ${chosen.length}/${profiles.length} profiles → ${paths.store}\n` +
-      `  ${chosen.join(' ')}\n` +
+    `lark-relay-collect: ${profiles.length} profiles → ${paths.store}\n` +
+      `  ${profiles.join(' ')}\n` +
       `  event_key=${EVENT_KEY} store 保留 ${opts.retain}天`,
   )
 
-  const collectors = chosen.map((name) => new AppCollector(name))
+  const collectors = profiles.map((name) => new AppCollector(name))
   for (const c of collectors) c.start()
 
   // 只回收超期事件,保留消费者的断点

package/lib/help.js

@@ -30,7 +30,8 @@ const TAKE_HELP = `需要 --app 和 --chats,监听要求 bot 已在群内
 断点持续保留,不随空闲时间过期;store 只保留采集端设定天数的消息
 使用新的 --name 可从新的起点消费
 app 和消费名称不能含路径分隔符、控制字符、首尾空白或以点开头
-读取或过滤失败时中止取批并保留待交付批次的断点,修正后可重取
+过滤失败时中止取批并保留待交付批次的断点,修正后可重取
+损坏的事件文件跳过并在 stderr 告警,断点越过它继续 —— 那几条消息永久丢失
 
 退出码:0=有一批/帮助/信号退出,1=运行错误,2=参数错,3=身份被占用,4=超时无消息`
 
@@ -39,21 +40,20 @@ const COLLECT_HELP = `lark-relay-collect -- 常驻收集 im.message.receive_v1
   lark-relay-collect
   lark-relay status
 
-启动时读取 lark-cli profile list,每个未被 --exclude 排除的 profile 启动一个 bot consumer
+启动时读取 lark-cli profile list,每个 profile 启动一个 bot consumer
 不依赖 user 登录态,bot 凭据和权限由 lark-cli 检查;失败会记录并退避重试
 新增或移除 profile 后需重启采集
 每 app 独立退避重连,断线期间的消息无法回放
 同一 app 只允许一个事件总线实例,接管前先停止现有采集
 
 参数
-  --exclude <apps>  排除指定 profile,逗号分隔
   --retain N        事件保留的整数天数,默认 3;每小时回收,启动时也执行
   -h, --help       用法
   -v, --version    版本
 
 macOS 常驻部署
   使用 LaunchDaemon + UserName,开机启动且不依赖 GUI 登录
-  ProgramArguments 写绝对路径,显式设置 HOME/PATH/UTF-8 locale
+  ProgramArguments 写绝对路径,显式设置 HOME/PATH
   KeepAlive 使用 SuccessfulExit=false,日志路径的父目录须已存在
   sudo launchctl bootstrap system /Library/LaunchDaemons/<label>.plist
   修改 plist 后需 bootout + bootstrap,代码升级后用 kickstart -k
@@ -70,6 +70,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/paths.js

@@ -48,12 +48,13 @@ function readDir(dir, options) {
   }
 }
 
-// stamp 在进程内严格单调,文件名按 stamp/pid/seq 数值排序
-let lastStamp = 0n
+// stamp(毫秒)在进程内严格单调,文件名按 stamp/pid/seq 数值排序:
+// 同毫秒内 seq 保序,跨进程由 pid 防撞名
+let lastStamp = 0
 
 function eventFilename(seq) {
-  const wall = BigInt(Date.now()) * 1000000n
-  lastStamp = wall > lastStamp ? wall : lastStamp + 1n
+  const wall = Date.now()
+  lastStamp = wall > lastStamp ? wall : lastStamp + 1
   return `${lastStamp}_${process.pid}_${seq}.json`
 }
 

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

@@ -36,7 +36,7 @@ const NAME_RE = /^(\d+)_(\d+)_(\d+)\.json$/
 function parseKey(name) {
   const m = NAME_RE.exec(name)
   if (!m) throw new Error(`事件文件名无效:${name}`)
-  return { stamp: BigInt(m[1]), pid: Number(m[2]), seq: Number(m[3]) }
+  return { stamp: Number(m[1]), pid: Number(m[2]), seq: Number(m[3]) }
 }
 
 function isEventName(name) {
@@ -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.6",
   "description": "Lark event relay: collect events to disk, take a batch when you need it.",
   "keywords": [
     "lark",

package/lib/utf8.js

@@ -1,15 +0,0 @@
-'use strict'
-
-// UTF-8 兜底:launchd 环境无 LANG -> C locale。虽然 Node 的字符串处理
-// 不像 bash 那样按字节切片,但子进程(lark-cli)会继承 locale,中文仍会被切坏。
-//
-// 两个 bin(lark-relay / lark-relay-collect)都要,故抽成模块 —— 复制两份会漂移。
-// 必须在任何 spawn 之前执行,所以两个入口都在最顶上 require 它。
-function ensureUtf8(env = process.env) {
-  if (!/utf-?8/i.test(env.LC_ALL || env.LC_CTYPE || env.LANG || '')) {
-    env.LANG = 'C.UTF-8'
-    env.LC_ALL = 'C.UTF-8'
-  }
-}
-
-module.exports = { ensureUtf8 }