package main import ( "context" "errors" "fmt" "log" "time" "knowledge-governance/internal/governance" "knowledge-governance/internal/jobs" postgresstore "knowledge-governance/internal/platform/postgres" ) // libraryAttemptWriter 是"这一次执行代次"的写入口。 // // 它嵌入完整 Store,只把**可变**入口换成带 epoch 守卫的实现(方法名相同,所以调用点 // 一行都不用改)。这样"谁能写业务状态/维护锁"只由这一个类型回答:handler 里拿到的 // 是 writer 而不是裸 Store,就不可能顺手绕过守卫去写。 // // 为什么必须这样:失租的旧执行器和接管它的新代次用的是**同一个 job_id**。只加一个 // epoch 列而不让写路径读它,等于什么都没做(这正是 F13 的原始形态)。 type libraryAttemptWriter struct { *postgresstore.Store attempt governance.LibraryAttempt } // beginLibraryWriter 取得这个作业的执行权,返回带守卫的写入口。 // owner 用队列作业 ID:每一次投递是一个确定的执行者身份,重复投递是同一个身份(幂等), // 不同投递互不覆盖(这正是"第二个 resumer 不能释放第一个的锁"需要的区分)。 func beginLibraryWriter(ctx context.Context, store *postgresstore.Store, jobID, owner string) (*libraryAttemptWriter, error) { job, err := store.LibraryJob(ctx, jobID) if err != nil { return nil, fmt.Errorf("读不到业务作业 %s:%w", jobID, err) } if job.OperationID == "" { // 迁移前的历史作业没有 operation:仍然取租约(防止双执行),但没有代次可守卫。 log.Printf("library job %s has no operation id (pre-identity row): guarded writes fall back to lease only", jobID) } attempt, err := store.BeginLibraryAttempt(ctx, jobID, owner, 10*time.Minute, time.Now().UTC()) if err != nil { return nil, err } return &libraryAttemptWriter{Store: store, attempt: attempt}, nil } func (w *libraryAttemptWriter) AdvanceLibraryJob(ctx context.Context, jobID string, state governance.LibraryJobState, stage, message, recovery, snapshotID, targetSnapshotID string, now time.Time) error { if err := w.checkJob(jobID); err != nil { return err } return w.Store.AdvanceLibraryJobGuarded(ctx, w.attempt, state, stage, message, recovery, snapshotID, targetSnapshotID, now) } func (w *libraryAttemptWriter) UpdateLibraryStage(ctx context.Context, jobID, stage, state string, total, completed, bytesTotal, bytesDone *int64, detail string, now time.Time) error { if err := w.checkJob(jobID); err != nil { return err } return w.Store.UpdateLibraryStageGuarded(ctx, w.attempt, stage, state, total, completed, bytesTotal, bytesDone, detail, now) } // RecordLibraryVersion 注入本次代次身份:事件登记因此也受 epoch 守卫。 func (w *libraryAttemptWriter) RecordLibraryVersion(ctx context.Context, version governance.LibraryVersion) error { if version.OperationID == "" { version.OperationID = w.attempt.OperationID } if version.AttemptEpoch == 0 { version.AttemptEpoch = w.attempt.Epoch } version.AttemptOwner = w.attempt.Owner return w.Store.RecordLibraryVersion(ctx, version) } func (w *libraryAttemptWriter) SetLibraryMaintenanceIngress(ctx context.Context, scope, ownerJobID, state, note string, now time.Time) error { return w.Store.SetLibraryMaintenanceIngressGuarded(ctx, scope, ownerJobID, state, note, w.attempt, now) } func (w *libraryAttemptWriter) SetInstanceMaintenanceIngress(ctx context.Context, instance, ownerJobID, state, note string, now time.Time) error { return w.Store.SetInstanceMaintenanceIngressGuarded(ctx, instance, ownerJobID, state, note, w.attempt, now) } func (w *libraryAttemptWriter) UpdateLibraryMaintenanceState(ctx context.Context, scope, ownerJobID, state, note string, now time.Time) error { return w.Store.UpdateLibraryMaintenanceStateGuarded(ctx, scope, ownerJobID, state, note, w.attempt, now) } func (w *libraryAttemptWriter) UpdateInstanceMaintenanceState(ctx context.Context, instance, ownerJobID, state, note string, now time.Time) error { return w.Store.UpdateInstanceMaintenanceStateGuarded(ctx, instance, ownerJobID, state, note, w.attempt, now) } func (w *libraryAttemptWriter) ReleaseLibraryMaintenance(ctx context.Context, scope, ownerJobID string, now time.Time) error { return w.Store.ReleaseLibraryMaintenanceGuarded(ctx, scope, ownerJobID, w.attempt, now) } func (w *libraryAttemptWriter) ReleaseInstanceMaintenance(ctx context.Context, instance, ownerJobID string, now time.Time) error { return w.Store.ReleaseInstanceMaintenanceGuarded(ctx, instance, ownerJobID, w.attempt, now) } // finish 结束本次代次。失败只记日志:代次结束写不进去不该反过来把已经完成的数据收尾 // 判成失败(下一次接管会重新开始一个新代次,旧代次的残留状态由 active 唯一索引兜住)。 func (w *libraryAttemptWriter) finish(ctx context.Context, state governance.LibraryAttemptState, outcome string) { if w.attempt.OperationID == "" { return } if err := w.Store.FinishLibraryAttempt(ctx, w.attempt, state, outcome, time.Now().UTC()); err != nil && !errors.Is(err, governance.ErrLibraryEpochStale) { log.Printf("library attempt %s#%d finish failed: %v", w.attempt.OperationID, w.attempt.Epoch, err) } } func (w *libraryAttemptWriter) checkJob(jobID string) error { if jobID != w.attempt.JobID { return fmt.Errorf("尝试用代次 %s#%d 写另一个作业 %s:拒绝(跨作业写入不是续作)", w.attempt.OperationID, w.attempt.Epoch, jobID) } return nil } // 编译期断言:writer 必须同时满足"成功收尾"与"阶段记录"两个存储面。 var ( _ libraryMaintenanceStore = (*libraryAttemptWriter)(nil) _ libraryStageStore = (*libraryAttemptWriter)(nil) ) // libraryQueueOwner 构造**每一次投递**的执行者身份:worker + 队列作业 + 队列尝试序号。 // // 不能用稳定的 queueJobID 单独当身份(父的复核项 R2):同一个队列作业被重投时 // ID 不变,而执行者是新的——那样第二次投递会被误判成"同一次执行重复调用", // 直接复用上一代租约而不开新代次。加上 worker 与 attempt 之后: // // · 同一次投递重复调用 ⇒ 身份相同 ⇒ 幂等复用; // · 换 worker 或换队列尝试 ⇒ 身份不同 ⇒ 必须开新代次(旧代次被结束,守卫立即失效)。 func libraryQueueOwner(workerID string, job jobs.Job, libraryJobID string) string { queueID := job.ID if queueID == "" { queueID = libraryJobID } worker := workerID if worker == "" { worker = "worker" } return fmt.Sprintf("%s#%s#%d", worker, queueID, job.Attempt) }