diff --git a/.scratch/query-serving-options/spec.md b/.scratch/query-serving-options/spec.md index 4af6c25b..d3e611e5 100644 --- a/.scratch/query-serving-options/spec.md +++ b/.scratch/query-serving-options/spec.md @@ -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;不是验收完成。 diff --git a/docs/operations/query-serving.md b/docs/operations/query-serving.md index b4c3aba2..57351b81 100644 --- a/docs/operations/query-serving.md +++ b/docs/operations/query-serving.md @@ -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派生键隔离旧协议;滚动混用或旧后台占有租约时只走原读取。 diff --git a/internal/store/query_read_builder.go b/internal/store/query_read_builder.go index 57432944..ff6098b1 100644 --- a/internal/store/query_read_builder.go +++ b/internal/store/query_read_builder.go @@ -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() +} diff --git a/internal/store/query_read_models.go b/internal/store/query_read_models.go index 4b953d48..18901b9f 100644 --- a/internal/store/query_read_models.go +++ b/internal/store/query_read_models.go @@ -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 diff --git a/internal/store/query_recovery_test.go b/internal/store/query_recovery_test.go index 6ba4213b..b5ce9321 100644 --- a/internal/store/query_recovery_test.go +++ b/internal/store/query_recovery_test.go @@ -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") + } +}