Files
knowledge-governance/internal/libraryhandoff/handoff_test.go
T
姚章浩 9300865d23 fix(library): 搬运复用前复验字节、回传游标分页与发布队列事务交接
父独立审查退回的四个 finding,逐项修在本包内,不改架构。

1 复用路径没复验字节:remoteEvidence 只读清单+摘要就宣布可用。现在新增
libraryctl snapshot-verify(整版逐部件重算)并在复用前调用;blob 缺失/篡改必须
在入发布队列之前失败。新增真实 local 跨进程用例:清单不动、删 blob / 改 blob 后
再 Push 必须拒绝。

2 回传枚举被固定 LIMIT 50 截断:LibraryJobSnapshots 只取成功作业且按摘要字典序。
改为 LibrarySnapshotCandidates:合并 library_versions、library_jobs.snapshot_id、
library_jobs.target_snapshot_id 三处引用,按 (created_at, snapshot_id) 游标分页;
回传循环翻页到不足一页为止。失败/待恢复作业留下的预备份、第 51 条以后、历史恢复
输入快照都能被枚举。另修"本地只有清单、blob 已损坏就永远跳过":改用整版 Load 判定,
并给 Unpack 增加显式 RepairCorruptBlobs(只在权威云端读回时开启)。

3 身份映射错误:搬运拿目标 tenant/KB 去核对封存快照,而封存清单写的是**源**身份
(云测试验收目标 a8e9c8ad/2e980686 与源 KB 必然不同)。现在 expectedSnapshotIdentity
按版本台账判定:test_sealed → 用部署注入的源绑定(LIBRARY_SOURCE_TENANT_ID /
LIBRARY_SOURCE_KB_*);预备份/生效/恢复版本 → 用目标绑定;没有登记或两类冲突一律拒绝。
身份永远来自独立绑定与台账,不接受包自证。

4 两步入队有竞态:Enqueue 成功后云执行器可能立刻领取并开始维护,Attach 失败却把作业
标失败并声称"未维护"。改为 EnqueueAndAttachLibraryJob 单事务(锁行 + 插入 + 关联 +
状态守卫),要么都成功要么都不发生;重复执行幂等,已关联别的队列作业则拒绝。
另修终态重放:AdvanceLibraryJob 无状态守卫,迟到的失败出口会把已成功作业改写;
新增 AdvanceLibraryJobIfActive(仅 pending/running 可推进),拿不到就明确记录"未覆盖"。

测试:libraryhandoff 用例覆盖跨租户/错误 scope/清单在而字节坏/本地损坏自愈;
隔离 fixture 库覆盖"校验通过才入队、失败不入队"、>50 条分页与失败作业预备份、
幂等重放不重复投递、迟到失败不改写终态。

未部署、未推送、未构建镜像;真实跨主机 SSH 链路仍未验证。
2026-10-30 19:10:02 +08:00

460 lines
15 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 libraryhandoff
import (
"bytes"
"context"
"crypto/sha256"
"encoding/hex"
"errors"
"io"
"os"
"os/exec"
"path/filepath"
"sync"
"testing"
"time"
"knowledge-governance/internal/librarysnapshot"
)
var libraryctlBinary string
// TestMain 构建真正的 libraryctl 二进制:local 通道的"云端"动作必须跨进程执行,
// 否则"跨进程证据"只是同一次调用里的函数调用。
func TestMain(m *testing.M) {
dir, err := os.MkdirTemp("", "handoff-bin-")
if err != nil {
panic(err)
}
binary := filepath.Join(dir, "libraryctl")
build := exec.Command("go", "build", "-o", binary, "knowledge-governance/cmd/libraryctl")
build.Stderr = os.Stderr
if err := build.Run(); err != nil {
panic("build libraryctl: " + err.Error())
}
libraryctlBinary = binary
code := m.Run()
os.RemoveAll(dir)
os.Exit(code)
}
const (
fixtureTenant = 10000
fixtureKB = "kb-handoff-fixture"
)
func newArchive(t *testing.T) (string, *librarysnapshot.Archive) {
t.Helper()
root := t.TempDir()
if err := os.Chmod(root, 0700); err != nil {
t.Fatal(err)
}
archive, err := librarysnapshot.Open(root, 1024*1024)
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { archive.Close() })
return root, archive
}
func seal(t *testing.T, archive *librarysnapshot.Archive) string {
t.Helper()
part, err := archive.Put(bytes.NewBufferString("[]"))
if err != nil {
t.Fatal(err)
}
mapping := sha256.Sum256([]byte("fixture-mapping"))
manifest := librarysnapshot.Manifest{
Format: librarysnapshot.Format, Scope: "internal", TenantID: fixtureTenant,
KnowledgeBaseID: fixtureKB, CreatedAt: time.Date(2026, 10, 30, 0, 0, 0, 0, time.UTC),
Compatibility: librarysnapshot.Compatibility{
WeKnoraVersion: "v0.7.1", SchemaVersion: 74, RetrieverEngine: "elasticsearch_v8",
EmbeddingModel: "fixture-model", EmbeddingDimension: 1024,
IndexMappingSHA256: hex.EncodeToString(mapping[:]),
},
}
for _, name := range []string{"knowledges", "chunks", "resources", "resource_bindings", "knowledge_tags", "knowledge_tag_relations"} {
current := part
current.Kind, current.Name = "database", name
manifest.Parts = append(manifest.Parts, current)
}
for _, name := range []string{"wiki_pages", "wiki_folders", "wiki_page_issues", "wiki_log_entries"} {
current := part
current.Kind, current.Name = "wiki", name
manifest.Parts = append(manifest.Parts, current)
}
index := part
index.Kind, index.Name = "index", "chunks"
manifest.Parts = append(manifest.Parts, index)
id, err := archive.Seal(manifest)
if err != nil {
t.Fatal(err)
}
return id
}
// fixture 在同一个临时根下模拟"云端主机":bundles/ 是暂存,archive/ 是执行器归档根。
type fixture struct {
root string
cfg Config
remoteA string
}
func newFixture(t *testing.T, localArchive string) fixture {
t.Helper()
root := t.TempDir()
remoteArchive := filepath.Join(root, "archive")
staging := filepath.Join(root, "staging")
for _, dir := range []string{remoteArchive, staging, filepath.Join(root, "bundles")} {
if err := os.MkdirAll(dir, 0700); err != nil {
t.Fatal(err)
}
}
t.Setenv("LIBRARY_HANDOFF_LIBRARYCTL", libraryctlBinary)
return fixture{root: root, remoteA: remoteArchive, cfg: Config{
Transport: TransportLocal, LocalRoot: root,
ExecutorContainer: "fixture-executor",
BundleDir: filepath.Join(root, "bundles"),
RemoteArchive: remoteArchive,
LocalArchive: localArchive,
StagingDir: staging,
MaxBundleBytes: 8 << 20,
OpTimeout: 60 * time.Second,
}}
}
// withLocalArchive 复用**同一台云端 fixture**(同一 root),只换本机归档根:
// 读回必须打到"发布执行器所在的那台机器"的归档,而不是另起一份空目录。
func withLocalArchive(t *testing.T, up fixture, localArchive string) Config {
t.Helper()
staging := filepath.Join(t.TempDir(), "staging")
if err := os.MkdirAll(staging, 0700); err != nil {
t.Fatal(err)
}
config := up.cfg
config.LocalArchive = localArchive
config.StagingDir = staging
return config
}
func TestPushThenFetchKeepsIdentityAndBytesAcrossProcesses(t *testing.T) {
sourceRoot, source := newArchive(t)
id := seal(t, source)
up := newFixture(t, sourceRoot)
pusher, err := New(up.cfg, nil)
if err != nil {
t.Fatal(err)
}
want := Identity{SnapshotID: id, Scope: "internal", TenantID: fixtureTenant, KnowledgeBaseID: fixtureKB}
pushed, err := pusher.Push(context.Background(), want)
if err != nil {
t.Fatalf("Push() error = %v", err)
}
if pushed.Reused || pushed.Parts != 11 || pushed.Snapshot != id {
t.Fatalf("push evidence = %#v", pushed)
}
// 云端确实落了版本清单,且摘要自证。
raw, err := os.ReadFile(filepath.Join(up.remoteA, "versions", id+".json"))
if err != nil {
t.Fatalf("remote manifest missing: %v", err)
}
sum := sha256.Sum256(raw)
if hex.EncodeToString(sum[:]) != id {
t.Fatal("remote manifest digest mismatch")
}
// 暂存目录不残留传输 bundle。
if entries, _ := os.ReadDir(up.cfg.BundleDir); len(entries) != 0 {
t.Fatalf("bundle staging not cleaned: %v", entries)
}
// 另一台"本机"取回:跨目录 + 跨进程(local 通道执行真正的 libraryctl)。
destinationRoot, _ := newArchive(t)
fetcher, err := New(withLocalArchive(t, up, destinationRoot), nil)
if err != nil {
t.Fatal(err)
}
fetched, err := fetcher.Fetch(context.Background(), id)
if err != nil {
t.Fatalf("Fetch() error = %v", err)
}
if fetched.Snapshot != id || fetched.Parts != 11 || fetched.KnowledgeBase != fixtureKB {
t.Fatalf("fetch evidence = %#v", fetched)
}
verify, err := librarysnapshot.Open(destinationRoot, 1024*1024)
if err != nil {
t.Fatal(err)
}
defer verify.Close()
if _, err := verify.Load(id); err != nil {
t.Fatalf("fetched snapshot does not verify: %v", err)
}
}
func TestPushRejectsIdentityThatDoesNotMatchTheSnapshot(t *testing.T) {
sourceRoot, source := newArchive(t)
id := seal(t, source)
up := newFixture(t, sourceRoot)
pusher, err := New(up.cfg, nil)
if err != nil {
t.Fatal(err)
}
wrong := Identity{SnapshotID: id, Scope: "internal", TenantID: fixtureTenant, KnowledgeBaseID: "kb-other"}
if _, err := pusher.Push(context.Background(), wrong); err == nil {
t.Fatal("Push() accepted a snapshot whose KB does not match the request")
}
if _, err := os.Stat(filepath.Join(up.remoteA, "versions", id+".json")); !errors.Is(err, os.ErrNotExist) {
t.Fatal("a rejected push left a version on the executor")
}
}
func TestPushIsIdempotentAndRejectsMissingLocalSnapshot(t *testing.T) {
sourceRoot, source := newArchive(t)
id := seal(t, source)
up := newFixture(t, sourceRoot)
pusher, err := New(up.cfg, nil)
if err != nil {
t.Fatal(err)
}
want := Identity{SnapshotID: id, Scope: "internal", TenantID: fixtureTenant, KnowledgeBaseID: fixtureKB}
if _, err := pusher.Push(context.Background(), want); err != nil {
t.Fatal(err)
}
again, err := pusher.Push(context.Background(), want)
if err != nil || !again.Reused {
t.Fatalf("second push = %#v, %v (want reused)", again, err)
}
missing := Identity{SnapshotID: hex.EncodeToString(bytes.Repeat([]byte{7}, 32)), Scope: "internal",
TenantID: fixtureTenant, KnowledgeBaseID: fixtureKB}
if _, err := pusher.Push(context.Background(), missing); err == nil {
t.Fatal("Push() accepted a snapshot that does not exist locally")
}
}
func TestConcurrentPushOfSameSnapshotSerialises(t *testing.T) {
sourceRoot, source := newArchive(t)
id := seal(t, source)
up := newFixture(t, sourceRoot)
pusher, err := New(up.cfg, nil)
if err != nil {
t.Fatal(err)
}
want := Identity{SnapshotID: id, Scope: "internal", TenantID: fixtureTenant, KnowledgeBaseID: fixtureKB}
var wg sync.WaitGroup
errs := make([]error, 3)
for i := 0; i < 3; i++ {
wg.Add(1)
go func(index int) {
defer wg.Done()
_, errs[index] = pusher.Push(context.Background(), want)
}(i)
}
wg.Wait()
for index, err := range errs {
if err != nil {
t.Fatalf("concurrent push %d failed: %v", index, err)
}
}
}
func TestFetchRefusesTamperedRemoteArchive(t *testing.T) {
sourceRoot, source := newArchive(t)
id := seal(t, source)
up := newFixture(t, sourceRoot)
pusher, err := New(up.cfg, nil)
if err != nil {
t.Fatal(err)
}
if _, err := pusher.Push(context.Background(), Identity{SnapshotID: id, Scope: "internal",
TenantID: fixtureTenant, KnowledgeBaseID: fixtureKB}); err != nil {
t.Fatal(err)
}
// 篡改云端一个 blob:云端 libraryctl snapshot-pack 会在 Load 时逐 blob 重算并失败。
blobs, err := os.ReadDir(filepath.Join(up.remoteA, "blobs"))
if err != nil || len(blobs) == 0 {
t.Fatalf("remote blobs = %v, %v", blobs, err)
}
target := filepath.Join(up.remoteA, "blobs", blobs[0].Name())
if err := os.Chmod(target, 0600); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(target, []byte("tampered"), 0600); err != nil {
t.Fatal(err)
}
destinationRoot, _ := newArchive(t)
fetcher, err := New(withLocalArchive(t, up, destinationRoot), nil)
if err != nil {
t.Fatal(err)
}
if _, err := fetcher.Fetch(context.Background(), id); err == nil {
t.Fatal("Fetch() imported a tampered snapshot")
}
if _, err := os.Stat(filepath.Join(destinationRoot, "versions", id+".json")); !errors.Is(err, os.ErrNotExist) {
t.Fatal("a failed fetch left a version locally")
}
}
func TestFetchRefusesUnknownRemoteSnapshotWithoutClaimingRecoverable(t *testing.T) {
destinationRoot, _ := newArchive(t)
empty := newFixture(t, destinationRoot)
fetcher, err := New(empty.cfg, nil)
if err != nil {
t.Fatal(err)
}
unknown := hex.EncodeToString(bytes.Repeat([]byte{9}, 32))
if _, err := fetcher.Fetch(context.Background(), unknown); err == nil {
t.Fatal("Fetch() reported success for a snapshot that exists nowhere")
}
if _, err := os.Stat(filepath.Join(destinationRoot, "versions", unknown+".json")); !errors.Is(err, os.ErrNotExist) {
t.Fatal("unknown snapshot produced a local version")
}
}
func TestHandoffRejectsCallerControlledNamesAndPaths(t *testing.T) {
if _, err := bundleName("../../etc/passwd"); err == nil {
t.Fatal("bundleName accepted a traversal name")
}
if _, err := bundleName("ABCDEF"); err == nil {
t.Fatal("bundleName accepted a non-digest name")
}
if _, err := New(Config{Transport: TransportSSH, SSHTarget: "x", SSHConfig: "/tmp/x"}, nil); err == nil {
t.Fatal("New() accepted an incomplete SSH configuration")
}
if _, err := New(Config{Transport: TransportLocal}, nil); err == nil {
t.Fatal("New() accepted local transport without an isolation root")
}
}
// 断线/超时:远端读版本清单一直失败必须报错,不能当成"没有版本"然后继续搬。
func TestPushSurfacesRemoteErrorsInsteadOfAssumingAbsent(t *testing.T) {
sourceRoot, source := newArchive(t)
id := seal(t, source)
up := newFixture(t, sourceRoot)
handoff := &Handoff{config: Config{LocalArchive: sourceRoot, MaxBundleBytes: 1 << 20, OpTimeout: time.Second},
remote: errorRemote{}, now: time.Now}
_, err := handoff.Push(context.Background(), Identity{SnapshotID: id, Scope: "internal",
TenantID: fixtureTenant, KnowledgeBaseID: fixtureKB})
if err == nil {
t.Fatal("Push() ignored a remote transport error")
}
_ = up
}
type errorRemote struct{}
func (errorRemote) PutBundle(context.Context, string, io.Reader) error {
return errors.New("network down")
}
func (errorRemote) OpenBundle(context.Context, string) (io.ReadCloser, error) {
return nil, errors.New("network down")
}
func (errorRemote) RemoveBundle(context.Context, string) error { return errors.New("network down") }
func (errorRemote) RunLibraryctl(context.Context, ...string) ([]byte, error) {
return nil, errors.New("network down")
}
func (errorRemote) VerifySnapshot(context.Context, string) error { return errors.New("network down") }
func (errorRemote) ReadVersionManifest(context.Context, string) ([]byte, error) {
return nil, errors.New("network down")
}
// 已有清单但字节坏了:Push 的复用路径必须整版校验,不能只看清单摘要就宣布可用。
func TestPushRefusesToReuseWhenRemoteBytesAreGoneOrTampered(t *testing.T) {
sourceRoot, source := newArchive(t)
id := seal(t, source)
up := newFixture(t, sourceRoot)
pusher, err := New(up.cfg, nil)
if err != nil {
t.Fatal(err)
}
want := Identity{SnapshotID: id, Scope: "internal", TenantID: fixtureTenant, KnowledgeBaseID: fixtureKB}
if _, err := pusher.Push(context.Background(), want); err != nil {
t.Fatal(err)
}
blobs, err := os.ReadDir(filepath.Join(up.remoteA, "blobs"))
if err != nil || len(blobs) == 0 {
t.Fatalf("remote blobs = %v %v", blobs, err)
}
// 清单不动、只把 blob 偷走:清单摘要仍然自证,但字节已经不在。
remoteBlob := filepath.Join(up.remoteA, "blobs", blobs[0].Name())
original, err := os.ReadFile(remoteBlob)
if err != nil {
t.Fatal(err)
}
if err := os.Remove(remoteBlob); err != nil {
t.Fatal(err)
}
if _, err := pusher.Push(context.Background(), want); err == nil {
t.Fatal("Push() reused a remote copy whose blobs are missing")
}
// 同名不同内容同样必须被拒绝。
if err := os.WriteFile(remoteBlob, append(original, 'x'), 0600); err != nil {
t.Fatal(err)
}
if _, err := pusher.Push(context.Background(), want); err == nil {
t.Fatal("Push() reused a remote copy with tampered bytes")
}
}
// 跨租户 / 错误 scope:期望身份与清单不一致一律拒绝(身份只能来自可信绑定)。
func TestPushRejectsCrossTenantAndWrongScope(t *testing.T) {
sourceRoot, source := newArchive(t)
id := seal(t, source)
up := newFixture(t, sourceRoot)
pusher, err := New(up.cfg, nil)
if err != nil {
t.Fatal(err)
}
crossTenant := Identity{SnapshotID: id, Scope: "internal", TenantID: fixtureTenant + 1, KnowledgeBaseID: fixtureKB}
if _, err := pusher.Push(context.Background(), crossTenant); err == nil {
t.Fatal("Push() accepted a snapshot from another tenant")
}
wrongScope := Identity{SnapshotID: id, Scope: "external", TenantID: fixtureTenant, KnowledgeBaseID: fixtureKB}
if _, err := pusher.Push(context.Background(), wrongScope); err == nil {
t.Fatal("Push() accepted a snapshot sealed for another scope")
}
if _, err := os.Stat(filepath.Join(up.remoteA, "versions", id+".json")); !errors.Is(err, os.ErrNotExist) {
t.Fatal("rejected pushes left a version on the executor")
}
}
// 本地副本损坏(清单在、blob 坏):Fetch 必须能修复,而不是永远报"已存在不同字节"。
func TestFetchRepairsCorruptLocalCopy(t *testing.T) {
sourceRoot, source := newArchive(t)
id := seal(t, source)
up := newFixture(t, sourceRoot)
pusher, err := New(up.cfg, nil)
if err != nil {
t.Fatal(err)
}
if _, err := pusher.Push(context.Background(), Identity{SnapshotID: id, Scope: "internal",
TenantID: fixtureTenant, KnowledgeBaseID: fixtureKB}); err != nil {
t.Fatal(err)
}
localRoot, _ := newArchive(t)
fetcher, err := New(withLocalArchive(t, up, localRoot), nil)
if err != nil {
t.Fatal(err)
}
if _, err := fetcher.Fetch(context.Background(), id); err != nil {
t.Fatalf("first fetch: %v", err)
}
blobs, err := os.ReadDir(filepath.Join(localRoot, "blobs"))
if err != nil || len(blobs) == 0 {
t.Fatalf("local blobs = %v %v", blobs, err)
}
victim := filepath.Join(localRoot, "blobs", blobs[0].Name())
if err := os.WriteFile(victim, []byte("corrupt"), 0600); err != nil {
t.Fatal(err)
}
if _, err := fetcher.Fetch(context.Background(), id); err != nil {
t.Fatalf("Fetch() could not repair a corrupt local copy: %v", err)
}
archive, err := librarysnapshot.Open(localRoot, 1024*1024)
if err != nil {
t.Fatal(err)
}
defer archive.Close()
if _, err := archive.Load(id); err != nil {
t.Fatalf("repaired snapshot still does not verify: %v", err)
}
}