m4
1.2 KiB
1.2 KiB
Usage Spool v1
spool 只允许位于本地文件系统，目录为 tmp/、pending/、inflight/、quarantine/。
文件名是 lowercase_hex(sha256(event_id)) + ".json"，正文只允许 UsageEvent v1。
写入顺序：在 tmp 创建唯一文件，写完整 JSON，fsync 文件，以 O_EXCL 获取相同 event key
的短锁，原子 rename 到 pending，fsync pending 目录，再释放锁。相同 ID/相同 payload
丢弃临时副本；相同 ID/不同 payload 移入 quarantine。任何错误必须 fail-open，并记录
first_loss_at，不能改变模型结果。
sender 通过同文件系统原子 rename 从 pending claim 到 inflight。200 accepted/duplicate 后删除并 fsync inflight；409、400、413、422 移入 quarantine；网络、429 和 5xx 回 pending；401、403、 404、426 保留 inflight/pending 并暂停或重新协商。超过 120 秒的 inflight 在启动和扫描时回收。
崩溃恢复：tmp 只可删除过期孤儿；pending 重发；inflight 超过 lease 后回 pending；HTTP ACK 后、 本地删除前崩溃会重发，由 Collector event ID 幂等；本地删除后不再依赖 spool。pending/inflight 不能按时间淘汰，达到软上限时拒绝新事件并将完整性状态标为 degraded。