feat(library): 目标维护窗口(持久所有权/独占/release-on-verify)+ known-broken 记录
build / build (push) Failing after 16s

为什么:用户确认维护窗口方案,需要真实占有目标而不是 503 页面。

- 迁移 000070 library_maintenance:scope 唯一持有者、作业/目标身份、服务原状态、阶段。
- worker 在写目标前 acquire,验证+登记成功才 release;回滚失败/未验证保持 needs_restore。
- API GET /library/maintenance + 同步入口在他人持有时 409。
- 已知缺陷如实记录:候选实例该路由 404;kill 取证脚本竞态导致三项断言为 false。
This commit is contained in:
姚章浩
2026-10-28 20:45:02 +08:00
parent b76a433574
commit 288e01a01a
10 changed files with 250 additions and 6 deletions
@@ -0,0 +1,99 @@
package postgres
import (
"context"
"errors"
"fmt"
"time"
"github.com/jackc/pgx/v5"
)
// LibraryMaintenance 是目标维护窗口的持有记录:一个 scope 只能有一个持有者。
type LibraryMaintenance struct {
Scope string `json:"scope"`
OwnerJobID string `json:"owner_job_id"`
TargetIdentity string `json:"target_identity"`
State string `json:"state"`
OriginalServiceState string `json:"original_service_state"`
Note string `json:"note"`
AcquiredAt time.Time `json:"acquired_at"`
UpdatedAt time.Time `json:"updated_at"`
ReleasedAt *time.Time `json:"released_at,omitempty"`
}
// ErrMaintenanceHeld 表示目标维护窗口被别的作业占着:任何新的写入都必须拒绝。
var ErrMaintenanceHeld = errors.New("目标正在维护中,被其他作业占用")
// AcquireLibraryMaintenance 原子地拿到维护权:
// 同一作业可以重入(接管后继续),别的作业一律拒绝——这不是"尽力而为"的锁。
func (s *Store) AcquireLibraryMaintenance(ctx context.Context, item LibraryMaintenance, now time.Time) (LibraryMaintenance, error) {
row := s.db.QueryRow(ctx, `
INSERT INTO library_maintenance (scope, owner_job_id, target_identity, state, original_service_state, note, acquired_at, updated_at)
VALUES ($1,$2,$3,$4,$5,$6,$7,$7)
ON CONFLICT (scope) DO UPDATE SET
owner_job_id = EXCLUDED.owner_job_id,
target_identity = EXCLUDED.target_identity,
state = EXCLUDED.state,
note = EXCLUDED.note,
updated_at = EXCLUDED.updated_at,
released_at = NULL
WHERE library_maintenance.owner_job_id = EXCLUDED.owner_job_id
RETURNING scope, owner_job_id, target_identity, state, original_service_state, note, acquired_at, updated_at, released_at`,
item.Scope, item.OwnerJobID, item.TargetIdentity, item.State, item.OriginalServiceState, item.Note, now.UTC())
acquired, err := scanMaintenance(row)
if errors.Is(err, pgx.ErrNoRows) {
return LibraryMaintenance{}, ErrMaintenanceHeld
}
if err != nil {
return LibraryMaintenance{}, fmt.Errorf("acquire library maintenance: %w", err)
}
return acquired, nil
}
// UpdateLibraryMaintenanceState 只允许持有者改自己的窗口状态。
func (s *Store) UpdateLibraryMaintenanceState(ctx context.Context, scope, ownerJobID, state, note string, now time.Time) error {
tag, err := s.db.Exec(ctx, `UPDATE library_maintenance SET state=$3, note=$4, updated_at=$5
WHERE scope=$1 AND owner_job_id=$2 AND released_at IS NULL`, scope, ownerJobID, state, note, now.UTC())
if err != nil {
return fmt.Errorf("update library maintenance: %w", err)
}
if tag.RowsAffected() == 0 {
return errors.New("library maintenance not held by this job")
}
return nil
}
// ReleaseLibraryMaintenance 只在完整验证通过后调用;失败路径必须保持窗口。
func (s *Store) ReleaseLibraryMaintenance(ctx context.Context, scope, ownerJobID string, now time.Time) error {
tag, err := s.db.Exec(ctx, `UPDATE library_maintenance SET state='released', released_at=$3, updated_at=$3
WHERE scope=$1 AND owner_job_id=$2 AND released_at IS NULL`, scope, ownerJobID, now.UTC())
if err != nil {
return fmt.Errorf("release library maintenance: %w", err)
}
if tag.RowsAffected() == 0 {
return errors.New("library maintenance not held by this job")
}
return nil
}
// LibraryMaintenanceOf 读当前窗口状态(页面与诊断用)。
func (s *Store) LibraryMaintenanceOf(ctx context.Context, scope string) (*LibraryMaintenance, error) {
row := s.db.QueryRow(ctx, `SELECT scope, owner_job_id, target_identity, state, original_service_state, note,
acquired_at, updated_at, released_at FROM library_maintenance WHERE scope=$1`, scope)
item, err := scanMaintenance(row)
if errors.Is(err, pgx.ErrNoRows) {
return nil, nil
}
if err != nil {
return nil, err
}
return &item, nil
}
func scanMaintenance(row pgx.Row) (LibraryMaintenance, error) {
var item LibraryMaintenance
err := row.Scan(&item.Scope, &item.OwnerJobID, &item.TargetIdentity, &item.State,
&item.OriginalServiceState, &item.Note, &item.AcquiredAt, &item.UpdatedAt, &item.ReleasedAt)
return item, err
}
@@ -0,0 +1 @@
DROP TABLE IF EXISTS library_maintenance;
@@ -0,0 +1,14 @@
-- 目标维护窗口:同步/恢复期间独占目标,只有完整验证通过才开放。
-- 一个 scope 同时只能有一个维护持有者;持有者进程死掉后由下一个接管的 worker 继承,
-- 不会被"finally"无条件释放。
CREATE TABLE library_maintenance (
scope VARCHAR(16) PRIMARY KEY CHECK (scope IN ('internal','external')),
owner_job_id VARCHAR(128) NOT NULL,
target_identity TEXT NOT NULL,
state VARCHAR(24) NOT NULL CHECK (state IN ('acquired','applying','verified','released','needs_restore')),
original_service_state TEXT NOT NULL DEFAULT '',
note TEXT NOT NULL DEFAULT '',
acquired_at TIMESTAMPTZ NOT NULL,
updated_at TIMESTAMPTZ NOT NULL,
released_at TIMESTAMPTZ
);
@@ -11,22 +11,25 @@ func TestEmbeddedMigrationsAreVersionSorted(t *testing.T) {
if err != nil {
t.Fatalf("loadMigrations() error = %v", err)
}
if len(migrations) != 69 {
t.Fatalf("migration count = %d, want 69", len(migrations))
if len(migrations) != 70 {
t.Fatalf("migration count = %d, want 70", len(migrations))
}
if tail := migrations[len(migrations)-1]; tail.Version != 69 ||
if tail := migrations[len(migrations)-2]; tail.Version != 69 ||
!strings.Contains(tail.UpSQL, "library_jobs_write_target") {
t.Fatalf("migration 69 = %#v", tail)
}
if restore := migrations[len(migrations)-2]; restore.Version != 68 || !strings.Contains(restore.UpSQL, "restore") {
if maint := migrations[len(migrations)-1]; maint.Version != 70 || !strings.Contains(maint.UpSQL, "library_maintenance") {
t.Fatalf("migration 70 = %#v", maint)
}
if restore := migrations[len(migrations)-3]; restore.Version != 68 || !strings.Contains(restore.UpSQL, "restore") {
t.Fatalf("migration 68 = %#v", restore)
}
if last := migrations[len(migrations)-3]; last.Version != 67 ||
if last := migrations[len(migrations)-4]; last.Version != 67 ||
!strings.Contains(last.UpSQL, "library_release_authorizations") ||
!strings.Contains(last.UpSQL, "params_digest") {
t.Fatalf("migration 67 = %#v", last)
}
if flow := migrations[len(migrations)-4]; flow.Version != 66 ||
if flow := migrations[len(migrations)-5]; flow.Version != 66 ||
!strings.Contains(flow.UpSQL, "CREATE TABLE library_versions") ||
!strings.Contains(flow.UpSQL, "library_jobs_active") {
t.Fatalf("migration 66 = %#v", flow)