🛡️ Require consumed change-stream markers for query freshness

This commit is contained in:
Codex 2026-11-12 03:58:29 -08:00
parent 352c405b11
commit 8b33f38e59
5 changed files with 145 additions and 26 deletions

View File

@ -15,13 +15,13 @@ Base: 9232bace
## 本地进展
后台读表、Valkey、Typesense 已实现,默认关闭。真实三组件22项(含竞态、范围、失联、重启、旧数据和缓存损坏)通过;既有五阶段作业/恢复、搜索与统计浏览器回归通过。官方 Go 基线为68项已有失败、无新增;前端基线与构建/生产启动检查通过。范围总报告保留了原生产诊断跳过、原测试债务和最初三组件瞬时回退断言失败,不将其写成全绿;修正的专项已重跑通过。
后台读表、Valkey、Typesense 已实现,默认关闭。真实三组件24项(含竞态、范围、失联、重启、旧数据和缓存损坏)通过;既有五阶段作业/恢复、搜索与统计浏览器回归通过。官方 Go 基线为68项已有失败、无新增;前端基线与构建/生产启动检查通过。范围总报告保留了原生产诊断跳过、原测试债务和最初三组件瞬时回退断言失败,不将其写成全绿;修正的专项已重跑通过。
81人、约2.6万任务/34万事件的首轮短测:候选零错误,347组账号/接口业务结果一致;管理员全部项目搜索p95 2592→799ms、生产总览3516→162ms;Mongo内部返回字节199215338→152507258,Go CPU +3.3%。这是短测,不是容量/生产验收。1GiB Mongo 对照OOM已作废,两版统一固定4GiB重新测得上述结果。
独立后台镜像构建和启动帮助检查已通过。待完成:冻结源码后的三轮持续对照和资源审查。未达标不准备发布;生产拓扑、新组件及派生索引/构建范围仍需具体计划与单独授权。现有两个受保护文件的哈希保持不变。
复查新增两项保护:Capture 候选按原 EqualFold 的 Unicode 简单折叠规范化,保留自由搜索原 ToLower/Contains 语义(含终形 sigma、长 s 和 Kelvin 符号回归);新候选与原历史条件组合超出 BSON 预算时退回旧路径,不截断。派生 schema 已升至v2,避免读旧候选。首次长测因发现此边界主动中止,不能作验收证据;22项真实三组件回归已通过,长测须重新冻结运行。
复查新增两项保护:Capture 候选按原 EqualFold 的 Unicode 简单折叠规范化,保留自由搜索原 ToLower/Contains 语义(含终形 sigma、长 s 和 Kelvin 符号回归);新候选与原历史条件组合超出 BSON 预算时退回旧路径,不截断。派生 schema 已升至v2,避免读旧候选。首次长测因发现此边界主动中止,不能作验收证据;24项真实三组件回归已通过,长测须重新冻结运行。
恢复边界补充:后台启动先递增观察代次使旧追平证明失效,只有变更流能推进 observedAt;单次预热复用完整观察路径,不能在重启或迟滞时重新信任旧索引。构建失败有界退避,搜索失联时普通孤儿载荷仍回收,远端意图恢复后清理。新增未重建失败窗口、发布不伪造追平、退避及断连清理回归。进程最大RSS(含预热)纳入规模报告。
@ -29,4 +29,10 @@ Base: 9232bace
原生Mongo 8.0.17(官方SHA256已核对)、同一约2.6万任务/34万事件、81账号的180秒短测:552组结果一致、零错误、零业务写入,全部搜索p95<2秒,生产总览1763→101ms,Go CPU约-11.9%、保留堆约-52.7%。但审核/验收/管理员面板各有一次约0.94秒尖峰,10秒预热短测不通过500ms门槛,不能作为最终验收。两版最大时钟变化62/28ms,旧Docker时钟失败单列保留。接下来必须按完整5分钟预热/30分钟稳态、三轮对照验证,不能丢弃尖峰或放宽门槛。
最新官方Go门禁仍为68项已知失败、0新增;22项真实三组件竞态/恢复回归、6项证据判定测试、格式和独立后台镜像构建/启动检查通过。尚未推送、部署、补写生产或变更生产索引。
最新官方Go门禁仍为68项已知失败、0新增;24项真实三组件竞态/恢复回归、6项证据判定测试、格式和独立后台镜像构建/启动检查通过。尚未推送、部署、补写生产或变更生产索引。
复查发现空变更批次不能直接证明追平,已在352c405b之后补改:仅消费私有控制标记的准确更新增量推进证明,标记每秒一次且受同一租约约束,派生schema升级v3;不会以空批次、发布或后续fullDocument刷新时间。新增准确标记与消费者暂停回退测试。第一轮长测因该正确性边界主动中止,不计验收;需冻结最终代码重新运行。
标记协议专项24项真实三组件竞态/恢复测试全部通过;快速检查中本任务用例通过,整体仍因受保护的生产只读诊断未启用而为incomplete,不执行生产诊断凑全绿。对照为同一候选关闭/启用加速的兼容路径比较,不能冒称两个生产二进制的直接A/B。原生环境与Docker环境资源差异单列。
标记修正后官方Go基线再次通过(68项原有失败、0新增),后台镜像构建/帮助启动通过。中止长测记录保存在 local-data/diagnostics/query-serving-20261112T114057Z/ABORTED.json;不是验收完成。

View File

@ -6,7 +6,7 @@
Mongo 仍是任务、权限、归属、版本与正式审查记录的权威存储。独立 `query-read-builder` 只写 `queryReadModelControl`、`queryReadModelData` 及既有 `annotationOutputSnapshot*` 派生集合,不领取、退回、重置、补验或改写客户任务。读取新集合不触发构建。
后台使用租约代次隔离写者,先完整构建再发布清单。单个失败不会发布半份结果。进程重启先使旧追平证明失效,再打开变更流、核对源身份和重建;发布代次不能推进观察器追平时间。`--once` 也执行这条路径并有5分钟上限,退出后搜索新鲜度随心跳过期,不把遗留索引视为最新。副本集/分片集群变更流是持续搜索加速的前提,普通独立 Mongo 不支持时后台暂停,API 继续旧路径。
后台使用租约代次隔离写者,先完整构建再发布清单。单个失败不会发布半份结果。进程重启先使旧追平证明失效,再打开变更流、核对源身份和重建;发布代次不能推进观察器追平时间。空批次不代表追平:后台每秒在私有控制记录写入一次标记,只使用对应变更事件的原始 updateDescription,不读取可能已更新的 fullDocument;滞后时证明自然过期,查询走兼容路径。此路径额外约每秒一次私有写入,计入资源对照。`--once` 也执行这条路径并有5分钟上限,退出后搜索新鲜度随心跳过期,不把遗留索引视为最新。副本集/分片集群变更流是持续搜索加速的前提,普通独立 Mongo 不支持时后台暂停,API 继续旧路径。
- 生产总览复用原事实读取与 `productionstats.Build`,保留原日期、供应商、人员和首次送检批次口径。当前配置项目集合生成一份报告;其他未预建项目组合走原路径。来源无变化且观察器新鲜时复用同一代次;有变化按原事实缓存时限停止使用旧结果。
- 人员与供应商看板复用既有分片快照和聚合器,后台无人访问也预热。Valkey 共享不可变分片及按完整范围、用户、供应商、日期、时区、代次隔离的结果;本进程已算出的结果优先,避免每次重复访问缓存服务器。已访问的个人/供应商查询登记保留4分钟,每范围最多256条,单个身份最多预热2条;新代次发布前复用原聚合器、每分片只解码一次,最多预热128条/5秒。预热不完整不缓存半份结果,失败也不阻断完整快照发布。时区规则必须与当前服务端标准规则一致,自定义时区保留原计算。
@ -35,10 +35,12 @@ Docker 本机规模夹具统一使用 Mongo 2 CPU/4GiB(WiredTiger 0.5GiB)、
显式 `query-read-builder --ensure-indexes` 只为派生行创建 `query_model_rows_v1`;API 启动不建索引。生产新增组件、该索引及派生数据构建会产生数据库读取和索引维护开销,需另列具体部署、资源和授权计划。不上线时不向公司集群安装或写入这些数据。
修改生产统计或名称匹配的语义时必须递增 `queryModelSchema`,防止新代码复用旧口径的派生代次。API 与后台应发布同一已核验源码版本。
修改生产统计或名称匹配的语义时必须递增 `queryModelSchema`(当前v3),防止新代码复用旧口径的派生代次。API 与后台应发布同一已核验源码版本。
## 发布与回退条件
先核对 Mongo 拓扑与权限、私网连接及组件资源,再在隔离环境验收完整任务链和查询结果。比较搜索 p95、冷/暖看板延迟、错误、结果/权限等价、后台业务写入为零、Mongo 读取字节与命令、Go/三组件 CPU 和内存。未达到搜索p95≤2秒、暖面板p95≤500ms、预热首访≤2秒,或三轮持续资源恶化未解释时保持待验收。
上线采用独立开关,先预热后逐步启用读取。回退关闭 API 的 `QUERY_SERVING_READS` 并停后台,恢复原读取;不改写客户记录,不要求删除新派生集合。组件失联仅是性能降级,不改变标注、切片、送检、质检和验收准入,也不恢复严格源校验。
追平语义依据:[MongoDB变更流规范](https://github.com/mongodb/specifications/blob/master/source/change-streams/change-streams.md)中的 postBatchResumeToken 表示已扫描的位置,不等于客户端当前时间;[update事件说明](https://www.mongodb.com/docs/manual/reference/change-events/update/)明确 updateLookup 可能读到后续版本。因此不解码内部token、不以空批次当前时间或后续全文伪造追平。v3派生键隔离旧协议;滚动混用或旧后台占有租约时只走原读取。

View File

@ -12,7 +12,6 @@ import (
"droboticflow/internal/outputsnapshot"
"droboticflow/internal/productionstats"
"go.mongodb.org/mongo-driver/bson"
"go.mongodb.org/mongo-driver/bson/primitive"
"go.mongodb.org/mongo-driver/mongo"
"go.mongodb.org/mongo-driver/mongo/options"
)
@ -235,7 +234,13 @@ func (b *QueryReadBuilder) run(ctx context.Context, started chan<- struct{}) err
}
// No fullDocument lookup: projecting only event identity avoids copying
// annotation bodies, credentials or full video payloads on each save.
pipeline := mongo.Pipeline{{{Key: "$match", Value: bson.M{"ns.coll": bson.M{"$in": querySourceCollections}}}}, {{Key: "$project", Value: bson.M{"_id": 1, "ns": 1, "documentKey": 1, "operationType": 1, "clusterTime": 1}}}}
pipeline := mongo.Pipeline{
{{Key: "$match", Value: bson.M{"$or": bson.A{
bson.M{"ns.coll": bson.M{"$in": querySourceCollections}},
bson.M{"ns.coll": "queryReadModelControl", "documentKey._id": "global", "operationType": "update", "updateDescription.updatedFields.watchBarrier": bson.M{"$exists": true}},
}}}},
{{Key: "$project", Value: bson.M{"_id": 1, "ns": 1, "documentKey": 1, "operationType": 1, "updateDescription.updatedFields.watchBarrier": 1}}},
}
stream, err := b.store.db.Watch(ctx, pipeline, options.ChangeStream().SetMaxAwaitTime(time.Second))
if err != nil {
return fmt.Errorf("query builder needs available Mongo change streams: %w", err)
@ -267,36 +272,47 @@ func (b *QueryReadBuilder) run(ctx context.Context, started chan<- struct{}) err
}
go func() {
defer close(watchExited)
lastHeartbeat := time.Time{}
lastHeartbeat, lastBarrier, observed := time.Time{}, time.Time{}, time.Time{}
pendingChange := false
for watchCtx.Err() == nil {
observed := time.Now().UTC()
if stream.TryNext(watchCtx) {
var event struct {
NS struct {
Collection string `bson:"coll"`
} `bson:"ns"`
Operation string `bson:"operationType"`
Key bson.M `bson:"documentKey"`
ClusterTime primitive.Timestamp `bson:"clusterTime"`
// An empty filtered batch is not proof that the stream reached
// the oplog end. Publish a private marker, then advance proof
// only when that exact immutable update delta is observed.
if time.Since(lastBarrier) >= time.Second {
now := time.Now().UTC()
result, e := b.store.queryControl().UpdateOne(watchCtx, queryLeaseFilter(l), bson.M{"$set": bson.M{"watchBarrier": now}})
if e != nil {
failWatch(e)
return
}
if result.MatchedCount != 1 {
failWatch(errors.New("query barrier fenced"))
return
}
lastBarrier = now
}
if stream.TryNext(watchCtx) {
var event queryWatchEvent
if e := stream.Decode(&event); e != nil {
failWatch(e)
return
}
pendingChange = true
if event.ClusterTime.T > 0 {
observed = time.Unix(int64(event.ClusterTime.T), 0).UTC()
}
if e := b.observeQuerySourceEvent(watchCtx, l, event.NS.Collection, event.Operation, event.Key); e != nil {
failWatch(e)
return
if marker, ok := event.barrierTime(); ok {
if marker.After(observed) {
observed = marker
}
} else if event.NS.Collection != "queryReadModelControl" {
pendingChange = true
if e := b.observeQuerySourceEvent(watchCtx, l, event.NS.Collection, event.Operation, event.Key); e != nil {
failWatch(e)
return
}
}
} else if e := stream.Err(); e != nil {
failWatch(e)
return
}
if time.Since(lastHeartbeat) < time.Second {
if observed.IsZero() || time.Since(lastHeartbeat) < time.Second {
continue
}
if e := b.recordObserved(watchCtx, l, observed, pendingChange); e != nil {
@ -459,3 +475,22 @@ func (r *queryBuildRetry) fail(initial, maximum time.Duration) {
}
r.Next = time.Now().Add(r.Delay)
}
// The change-stream delta is the value written by that operation, unlike
// fullDocument updateLookup which can already contain a later marker.
type queryWatchEvent struct {
NS struct {
Collection string `bson:"coll"`
} `bson:"ns"`
Operation string `bson:"operationType"`
Key bson.M `bson:"documentKey"`
Update struct {
Fields struct {
Barrier time.Time `bson:"watchBarrier"`
} `bson:"updatedFields"`
} `bson:"updateDescription"`
}
func (e queryWatchEvent) barrierTime() (time.Time, bool) {
return e.Update.Fields.Barrier, e.NS.Collection == "queryReadModelControl" && e.Operation == "update" && e.Key["_id"] == "global" && !e.Update.Fields.Barrier.IsZero()
}

View File

@ -22,7 +22,7 @@ import (
"go.mongodb.org/mongo-driver/mongo/options"
)
const queryModelSchema = "query-model/v2"
const queryModelSchema = "query-model/v3"
const queryModelChunkBytes = 2 << 20
const queryModelMaxBytes = 64 << 20

View File

@ -443,3 +443,79 @@ func TestQuerySearchCredentialsInLegacyNamesKeepOriginalPathLocal(t *testing.T)
t.Fatal("legacy search lost", len(rows), e)
}
}
func TestQueryReadModelObservationRequiresExactPrivateBarrier(t *testing.T) {
now := time.Now().UTC().Truncate(time.Millisecond)
for _, raw := range []bson.M{
{},
{"ns": bson.M{"coll": "humanItems"}, "operationType": "update", "documentKey": bson.M{"_id": "global"}, "updateDescription": bson.M{"updatedFields": bson.M{"watchBarrier": now}}},
{"ns": bson.M{"coll": "queryReadModelControl"}, "operationType": "update", "documentKey": bson.M{"_id": "other"}, "updateDescription": bson.M{"updatedFields": bson.M{"watchBarrier": now}}},
{"ns": bson.M{"coll": "queryReadModelControl"}, "operationType": "update", "documentKey": bson.M{"_id": "global"}, "fullDocument": bson.M{"watchBarrier": now}},
} {
data, e := bson.Marshal(raw)
if e != nil {
t.Fatal(e)
}
var event queryWatchEvent
if e = bson.Unmarshal(data, &event); e != nil {
t.Fatal(e)
}
if _, ok := event.barrierTime(); ok {
t.Fatal("non-marker or later lookup used as proof", raw)
}
}
var event queryWatchEvent
data, _ := bson.Marshal(bson.M{"ns": bson.M{"coll": "queryReadModelControl"}, "operationType": "update", "documentKey": bson.M{"_id": "global"}, "updateDescription": bson.M{"updatedFields": bson.M{"watchBarrier": now}}, "fullDocument": bson.M{"watchBarrier": now.Add(time.Hour)}})
if e := bson.Unmarshal(data, &event); e != nil {
t.Fatal(e)
}
if got, ok := event.barrierTime(); !ok || !got.Equal(now) {
t.Fatal("marker was replaced by a later document", got, ok)
}
}
func TestQueryReadModelObservedBarrierAndPausedConsumerFallbackLocal(t *testing.T) {
f := newQueryModelFixture(t, 3)
s := f.s
b := NewQueryReadBuilder(s)
defer b.Close()
ctx, cancel := context.WithCancel(t.Context())
defer cancel()
done := make(chan error, 1)
go func() { done <- b.Run(ctx) }()
defer func() { cancel(); <-done }()
ready, finish := context.WithTimeout(ctx, 10*time.Second)
defer finish()
if e := b.WaitReady(ready, f.org, []string{"p"}); e != nil {
t.Fatal(e)
}
var control struct {
Observed time.Time `bson:"observedAt"`
Barrier time.Time `bson:"watchBarrier"`
}
if e := s.queryControl().FindOne(ctx, bson.M{"_id": "global"}).Decode(&control); e != nil {
t.Fatal(e)
}
if control.Observed.IsZero() || control.Barrier.IsZero() || control.Observed.After(control.Barrier) {
t.Fatal("freshness advanced without consumed barrier", control)
}
// Block source-event handling, not Mongo or the request path. Proof must age
// out instead of being refreshed by empty batches or a publication pass.
b.mu.Lock()
_, e := s.captureRecords.UpdateOne(ctx, bson.M{"id": "capture-item-000000"}, bson.M{"$set": bson.M{"captureId": "paused-consumer-new-name"}})
if e != nil {
b.mu.Unlock()
t.Fatal(e)
}
select {
case <-time.After(6 * time.Second):
case <-ctx.Done():
b.mu.Unlock()
t.Fatal(ctx.Err())
}
_, hit := s.querySearchCandidates(ctx, f.org, "FYLX", "")
b.mu.Unlock()
if hit {
t.Fatal("paused observer advertised a current catalog")
}
}