Files
knowledge-governance/internal/platform/postgres/store.go
T
姚章浩 146ac832a2
build / build (push) Successful in 2m9s
fix(library): 修复封存终态回写并增加精确核对
修复 varchar 状态参数在 AdvanceLibraryJob 的 42P08;worker 开始/终态写入失败
不再吞掉。新增管理员核对路由,仅在 completed capture queue、export succeeded、
精确 test_sealed 版本、来源身份和归档复核一致时,以条件更新修复仍为
pending/running 的同一作业;已有不同快照或并发失败/取消行拒绝覆盖。保留
第一因与历史记录,不重新封存、不产生快照、不写源或目标知识。

验证:真实 varchar DDL PG 路径、handler 负例/幂等、worker 注入、web 组件;
umask022 与真实隔离 kg_library_test_* 下 Go 全量与 make verify 17 项通过。
2026-11-06 10:04:19 +08:00

247 lines
7.2 KiB
Go

package postgres
import (
"context"
"errors"
"fmt"
"strings"
"time"
"github.com/jackc/pgx/v5"
"github.com/jackc/pgx/v5/pgconn"
"knowledge-governance/internal/jobs"
)
var ErrLeaseLost = errors.New("job lease lost")
type database interface {
QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
Exec(ctx context.Context, sql string, args ...any) (pgconn.CommandTag, error)
Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
Begin(ctx context.Context) (pgx.Tx, error)
}
type Store struct {
db database
libraryTargetID string
defaultInternalKBID string
defaultExternalKBID string
// restoreDispatchEvidenceRoot 是激活门唯一允许读取维护 journal 的根目录。
// 空值表示没有配置受信证据源:激活必须失败关闭,而不是退回"只看字符串"。
restoreDispatchEvidenceRoot string
}
// WithLibraryTarget isolates release facts without mutating a shared Store.
// The empty namespace retains legacy evidence; live API/workers bind a nonempty
// identity before exposing library operations. Source seals remain independent.
func (s *Store) WithLibraryTarget(id string) *Store {
copy := *s
copy.libraryTargetID = id
return &copy
}
func NewStore(db database) *Store {
return &Store{db: db}
}
// WithRoutingDefaults supplies the deployment's bootstrap bindings. The UI
// binding row still wins; defaults are only the unbound fallback, exactly like
// the route/readiness resolvers. Auto-continuation uses them only to prove the
// publication still targets the CURRENT effective knowledge base.
func (s *Store) WithRoutingDefaults(internal, external string) *Store {
copy := *s
copy.defaultInternalKBID = strings.TrimSpace(internal)
copy.defaultExternalKBID = strings.TrimSpace(external)
return &copy
}
// WithRestoreDispatchEvidence 绑定维护 journal 的受信根目录(部署配置
// LIBRARY_TARGET_JOURNAL_ROOT)。没有它时激活门一律失败关闭。
func (s *Store) WithRestoreDispatchEvidence(root string) *Store {
copy := *s
copy.restoreDispatchEvidenceRoot = root
return &copy
}
func (s *Store) Enqueue(ctx context.Context, request jobs.EnqueueRequest, now time.Time) (*jobs.Job, error) {
job, err := scanJob(s.db.QueryRow(
ctx,
enqueueJobSQL,
request.ID,
request.Type,
request.Payload,
request.Priority,
request.AvailableAt,
request.MaxAttempts,
request.IdempotencyKey,
now,
))
if err != nil {
return nil, fmt.Errorf("enqueue job: %w", err)
}
return job, nil
}
func (s *Store) Claim(ctx context.Context, workerID string, allowedTypes []string, now time.Time, leaseDuration time.Duration) (*jobs.Job, error) {
// Liveness heartbeat: refresh even on an empty claim so a healthy idle
// worker still looks alive to /readyz and the monitor matrix.
if _, err := s.db.Exec(ctx, workerHeartbeatSQL, workerID, strings.Join(allowedTypes, ","), now); err != nil {
return nil, fmt.Errorf("record worker heartbeat: %w", err)
}
job, err := scanJob(s.db.QueryRow(ctx, claimJobSQL, workerID, now, now.Add(leaseDuration), allowedTypes))
if errors.Is(err, pgx.ErrNoRows) {
return nil, nil
}
if err != nil {
return nil, fmt.Errorf("claim job: %w", err)
}
return job, nil
}
// ListByType lists only the requested job type, so a busy queue cannot hide the
// caller's own recent jobs behind unrelated traffic.
// QueueJob reads one queue row by exact id (no window / no type filter).
func (s *Store) QueueJob(ctx context.Context, id string) (jobs.Job, bool, error) {
if strings.TrimSpace(id) == "" {
return jobs.Job{}, false, errors.New("queue job id required")
}
job, err := scanJob(s.db.QueryRow(ctx, jobByIDSQL, id))
if errors.Is(err, pgx.ErrNoRows) {
return jobs.Job{}, false, nil
}
if err != nil {
return jobs.Job{}, false, fmt.Errorf("read queue job: %w", err)
}
return *job, true, nil
}
func (s *Store) ListByType(ctx context.Context, jobType string, limit int) ([]jobs.Job, error) {
if strings.TrimSpace(jobType) == "" || limit < 1 || limit > 200 {
return nil, errors.New("list jobs by type requires a type and a bounded limit")
}
rows, err := s.db.Query(ctx, listJobsByTypeSQL, jobType, limit)
if err != nil {
return nil, fmt.Errorf("list jobs by type: %w", err)
}
defer rows.Close()
result := make([]jobs.Job, 0, limit)
for rows.Next() {
job, err := scanJob(rows)
if err != nil {
return nil, fmt.Errorf("scan listed job: %w", err)
}
result = append(result, *job)
}
if err := rows.Err(); err != nil {
return nil, fmt.Errorf("iterate jobs: %w", err)
}
return result, nil
}
func (s *Store) List(ctx context.Context, limit int) ([]jobs.Job, error) {
rows, err := s.db.Query(ctx, listJobsSQL, limit)
if err != nil {
return nil, fmt.Errorf("list jobs: %w", err)
}
defer rows.Close()
result := make([]jobs.Job, 0)
for rows.Next() {
job, err := scanJob(rows)
if err != nil {
return nil, fmt.Errorf("scan listed job: %w", err)
}
result = append(result, *job)
}
if err := rows.Err(); err != nil {
return nil, fmt.Errorf("iterate jobs: %w", err)
}
return result, nil
}
func (s *Store) Complete(ctx context.Context, id, owner string, now time.Time) error {
// completeJobSQL is one statement: mark the job completed AND retire any
// open dead-letter rows for it. The EXISTS projection is the lease check.
var completed bool
if err := s.db.QueryRow(ctx, completeJobSQL, id, owner, now).Scan(&completed); err != nil {
return fmt.Errorf("complete job: %w", err)
}
if !completed {
return ErrLeaseLost
}
return nil
}
func (s *Store) Heartbeat(ctx context.Context, id, owner string, now time.Time, leaseDuration time.Duration) error {
tag, err := s.db.Exec(ctx, heartbeatJobSQL, id, owner, now, now.Add(leaseDuration))
if err != nil {
return fmt.Errorf("heartbeat job: %w", err)
}
if tag.RowsAffected() != 1 {
return ErrLeaseLost
}
return nil
}
func (s *Store) Fail(ctx context.Context, id, owner, message, code string, now, retryAt time.Time) error {
tag, err := s.db.Exec(ctx, failJobSQL, id, owner, message, now, code, retryAt)
if err != nil {
return fmt.Errorf("fail job: %w", err)
}
if tag.RowsAffected() != 1 {
return ErrLeaseLost
}
return nil
}
// FailTerminal implements jobs.TerminalFailer (P6): park the job in 'failed'
// immediately with a stable error code and project the dead-letter row.
func (s *Store) FailTerminal(ctx context.Context, id, owner, message, code string, now time.Time) error {
tag, err := s.db.Exec(ctx, failTerminalJobSQL, id, owner, message, code, now)
if err != nil {
return fmt.Errorf("fail terminal job: %w", err)
}
if tag.RowsAffected() != 1 {
return ErrLeaseLost
}
return nil
}
type rowScanner interface {
Scan(dest ...any) error
}
func scanJob(row rowScanner) (*jobs.Job, error) {
job := &jobs.Job{}
var state string
var leaseOwner *string
var lastError *string
if err := row.Scan(
&job.ID,
&job.Type,
&job.Payload,
&state,
&job.Priority,
&job.AvailableAt,
&leaseOwner,
&job.LeaseUntil,
&job.Attempt,
&job.MaxAttempts,
&lastError,
&job.IdempotencyKey,
&job.CreatedAt,
&job.UpdatedAt,
); err != nil {
return nil, err
}
job.State = jobs.State(state)
if leaseOwner != nil {
job.LeaseOwner = *leaseOwner
}
if lastError != nil {
job.LastError = *lastError
}
return job, nil
}