Files
knowledge-governance/cmd/worker/library_writer.go
T
姚章浩 8d838d9cb4
build / build (push) Successful in 1m45s
feat(library): 整库发布身份、写集合与收尾边界
执行时真实时钟与持久授权回读(撤销/过期即停并保留预备份)、写集合写前落盘、
租约与 attempt 身份、恢复队列与原发送身份分离、成功收尾必须释放维护后再登记终态。
2026-11-01 11:35:10 +08:00

144 lines
6.6 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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, libraryAttemptLease, 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)
}