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) } }