feat: 知识治理平台(含已验证发布/回滚契约)

全栈知识治理平台首次入库(P1-P10 + 发布链路模拟验证闭环):

- 治理核心:源目录/变更集/人工审核/发布批次/发布执行(fail-closed 闸口)
- 测试通道:WeKnora 测试 KB 上传/轮询/验收;poll 完成时写入
  parser_generation/index_generation,修复 manual/seed 路径发布闸口永久拦截
- 发布适配器 v071(本地 source=测试角色 / 云端 target=生产角色 模拟验证通过):
  * ES 导出/导入 mapping 自适应(.keyword 子字段、可选 tenant_id)
  * OSS locator 支持嵌套 scheme;chunks.seq_id 由目标序列分配
  * bundle 归档同身份重试原子替换;verifier 按 bundle chunk_type 计数
  * 回滚 job payload 支持 prior_execution_id(strict 解码)
- 三通道发布+回滚演练实测:publish 4/4 verified,检索命中,
  rollback 4/4 rolled_back,目标端 PG is_enabled=false、ES is_enabled=false
- 前端 A·Data-console 风格全站统一,120 用例通过
- 门禁:go vet / go test 全包通过,gofmt 干净
This commit is contained in:
2026-09-13 12:02:58 +08:00
committed by 姚章浩
parent ed48c4ceda
commit dcdc8d1ddd
410 changed files with 56661 additions and 1 deletions
+299
View File
@@ -0,0 +1,299 @@
package release
import (
"context"
"encoding/json"
"errors"
"io"
"log"
"os"
"strings"
"time"
"knowledge-governance/internal/governance"
"knowledge-governance/internal/jobs"
)
// debugReleaseItemErrors enables fail-closed-safe diagnostics: only the
// generic step-level cause text is logged, never payload or credentials.
var debugReleaseItemErrors = os.Getenv("RELEASE_DEBUG_ITEM_ERRORS") == "true"
const (
ErrorCodeContractMismatch = "release_contract_mismatch"
ErrorCodeBundleInvalid = "release_bundle_invalid"
ErrorCodeTargetUnavailable = "release_target_unavailable"
ErrorCodeTargetWriteFailed = "release_target_write_failed"
ErrorCodeVerificationFailed = "release_verification_failed"
ErrorCodeRollbackArtifactMissing = "release_rollback_artifact_missing"
ErrorCodeRollbackFailed = "release_rollback_failed"
ErrorCodeStoppedAfterFailure = "release_stopped_after_failure"
ErrorCodeInternal = "release_internal_error"
)
var (
ErrInvalidReleaseJob = errors.New("invalid_release_job")
ErrReleaseRetryable = errors.New("release_retryable")
ErrReleaseState = errors.New("release_state_failed")
)
type PlanItem struct {
ReleaseExecutionID string `json:"release_execution_id"`
PublicationID string `json:"publication_id"`
Action string `json:"action"`
SourceItemVersionID string `json:"source_item_version_id"`
SourceRevision string `json:"source_revision"`
ParseRevision string `json:"parse_revision"`
ReleaseRevision string `json:"release_revision"`
TestKnowledgeBaseID string `json:"test_knowledge_base_id"`
KnowledgeID string `json:"knowledge_id"`
DecidedVisibility governance.Visibility `json:"decided_visibility"`
PreviousProductionRevision string `json:"previous_production_revision"`
}
type ItemResult struct {
BundleSHA256 string
PreviousProductionRevision string
ProductionRevision string
}
type StartExecutionRequest struct {
ExecutionID string
JobID string
Operation governance.ReleaseOperation
Now time.Time
}
type CompleteItemRequest struct {
ExecutionID string
PublicationID string
BundleSHA256 string
PreviousProductionRevision string
ProductionRevision string
Now time.Time
}
type FailItemRequest struct {
ExecutionID string
PublicationID string
ErrorCode string
Now time.Time
}
type Store interface {
StartExecution(context.Context, StartExecutionRequest) ([]PlanItem, error)
BeginBatch(context.Context, string, int, int, time.Time) error
CompleteItem(context.Context, CompleteItemRequest) error
FailItem(context.Context, FailItemRequest) error
FinishExecution(context.Context, string, time.Time) error
ScheduleAutomaticRollback(context.Context, string, time.Time) error
}
type Publisher interface {
Publish(context.Context, PlanItem) (ItemResult, error)
Delete(context.Context, PlanItem) (ItemResult, error)
Rollback(context.Context, PlanItem) (ItemResult, error)
}
type ItemError struct {
Code string
Retryable bool
Cause error
}
func (err *ItemError) Error() string {
if err == nil || !ValidErrorCode(err.Code) {
return ErrorCodeInternal
}
return err.Code
}
func (err *ItemError) Unwrap() error {
if err == nil {
return nil
}
return err.Cause
}
type jobPayload struct {
ExecutionID string `json:"execution_id"`
ReleaseBatchID string `json:"release_batch_id"`
Operation string `json:"operation"`
PriorExecutionID string `json:"prior_execution_id"`
}
func NewHandler(store Store, publisher Publisher, now func() time.Time) (jobs.Handler, error) {
if store == nil || publisher == nil || now == nil {
return nil, errors.New("release handler dependencies are required")
}
return func(ctx context.Context, job jobs.Job) error {
payload, operation, err := parseJob(job)
if err != nil {
return err
}
items, err := store.StartExecution(ctx, StartExecutionRequest{
ExecutionID: payload.ExecutionID, JobID: job.ID, Operation: operation, Now: now().UTC(),
})
if err != nil {
return ErrReleaseState
}
retryableFailure := false
permanentFailure := false
failureIndex := -1
const batchSize = 50
totalBatches := (len(items) + batchSize - 1) / batchSize
for start := 0; start < len(items); start += batchSize {
batchNumber := start/batchSize + 1
if err := store.BeginBatch(ctx, payload.ExecutionID, batchNumber, totalBatches, now().UTC()); err != nil {
return ErrReleaseState
}
end := start + batchSize
if end > len(items) {
end = len(items)
}
for index := start; index < end; index++ {
item := items[index]
result, itemErr := publishItem(ctx, publisher, operation, item)
if itemErr != nil {
code, retryable := classifyItemError(itemErr)
if debugReleaseItemErrors {
var itemErrDetail *ItemError
causeText := ""
if errors.As(itemErr, &itemErrDetail) && itemErrDetail != nil && itemErrDetail.Cause != nil {
causeText = itemErrDetail.Cause.Error()
}
log.Printf("release item %s (%s/%s) failed code=%s cause=%s", item.PublicationID, item.Action, item.KnowledgeID, code, causeText)
}
if retryable && job.Attempt < job.MaxAttempts {
retryableFailure = true
continue
}
if err := store.FailItem(ctx, FailItemRequest{ExecutionID: payload.ExecutionID, PublicationID: item.PublicationID, ErrorCode: code, Now: now().UTC()}); err != nil {
return ErrReleaseState
}
permanentFailure = true
failureIndex = index
break
}
if !validResult(operation, result) {
if err := store.FailItem(ctx, FailItemRequest{ExecutionID: payload.ExecutionID, PublicationID: item.PublicationID, ErrorCode: ErrorCodeBundleInvalid, Now: now().UTC()}); err != nil {
return ErrReleaseState
}
permanentFailure = true
failureIndex = index
break
}
if err := store.CompleteItem(ctx, CompleteItemRequest{
ExecutionID: payload.ExecutionID, PublicationID: item.PublicationID,
BundleSHA256: result.BundleSHA256, PreviousProductionRevision: result.PreviousProductionRevision,
ProductionRevision: result.ProductionRevision, Now: now().UTC(),
}); err != nil {
return ErrReleaseState
}
}
if permanentFailure {
break
}
}
if permanentFailure {
for _, item := range items[failureIndex+1:] {
if err := store.FailItem(ctx, FailItemRequest{ExecutionID: payload.ExecutionID, PublicationID: item.PublicationID, ErrorCode: ErrorCodeStoppedAfterFailure, Now: now().UTC()}); err != nil {
return ErrReleaseState
}
}
}
if retryableFailure {
return ErrReleaseRetryable
}
if err := store.FinishExecution(ctx, payload.ExecutionID, now().UTC()); err != nil {
return ErrReleaseState
}
if permanentFailure && operation == governance.ReleaseOperationPublish {
if err := store.ScheduleAutomaticRollback(ctx, payload.ExecutionID, now().UTC()); err != nil {
return ErrReleaseState
}
}
return nil
}, nil
}
func parseJob(job jobs.Job) (jobPayload, governance.ReleaseOperation, error) {
var payload jobPayload
decoder := json.NewDecoder(strings.NewReader(string(job.Payload)))
decoder.DisallowUnknownFields()
if err := decoder.Decode(&payload); err != nil {
return jobPayload{}, "", ErrInvalidReleaseJob
}
var trailing any
if err := decoder.Decode(&trailing); !errors.Is(err, io.EOF) {
return jobPayload{}, "", ErrInvalidReleaseJob
}
operation := governance.ReleaseOperation(payload.Operation)
expectedType := "release." + payload.Operation
if !validID(payload.ExecutionID, "rx-") || !validID(payload.ReleaseBatchID, "rb-") || !operation.Valid() || job.Type != expectedType || job.Attempt < 1 || job.MaxAttempts < job.Attempt {
return jobPayload{}, "", ErrInvalidReleaseJob
}
return payload, operation, nil
}
func publishItem(ctx context.Context, publisher Publisher, operation governance.ReleaseOperation, item PlanItem) (ItemResult, error) {
if operation == governance.ReleaseOperationRollback {
return publisher.Rollback(ctx, item)
}
if item.Action == "delete" {
return publisher.Delete(ctx, item)
}
return publisher.Publish(ctx, item)
}
func classifyItemError(err error) (string, bool) {
var itemErr *ItemError
if errors.As(err, &itemErr) && ValidErrorCode(itemErr.Code) {
return itemErr.Code, itemErr.Retryable
}
return ErrorCodeInternal, true
}
func validResult(operation governance.ReleaseOperation, result ItemResult) bool {
if strings.TrimSpace(result.ProductionRevision) == "" || len(result.ProductionRevision) > 128 {
return false
}
if operation == governance.ReleaseOperationPublish {
return validSHA256(result.BundleSHA256)
}
return true
}
func validSHA256(value string) bool {
if len(value) != 64 {
return false
}
for _, char := range value {
if (char < '0' || char > '9') && (char < 'a' || char > 'f') {
return false
}
}
return true
}
func validID(value, prefix string) bool {
if !strings.HasPrefix(value, prefix) || len(value) > 36 || len(value) <= len(prefix) {
return false
}
for _, char := range value {
if (char < 'a' || char > 'z') && (char < '0' || char > '9') && char != '-' {
return false
}
}
return true
}
func ValidErrorCode(code string) bool {
switch code {
case ErrorCodeContractMismatch, ErrorCodeBundleInvalid, ErrorCodeTargetUnavailable,
ErrorCodeTargetWriteFailed, ErrorCodeVerificationFailed, ErrorCodeRollbackArtifactMissing,
ErrorCodeRollbackFailed, ErrorCodeStoppedAfterFailure, ErrorCodeInternal:
return true
default:
return false
}
}
+209
View File
@@ -0,0 +1,209 @@
package release
import (
"context"
"errors"
"fmt"
"reflect"
"testing"
"time"
"knowledge-governance/internal/governance"
"knowledge-governance/internal/jobs"
)
func TestHandlerStopsAfterPermanentItemFailureAndSchedulesAutomaticRollback(t *testing.T) {
store := &fakeStore{items: []PlanItem{{PublicationID: "tp-1"}, {PublicationID: "tp-2"}, {PublicationID: "tp-3"}}}
publisher := &fakePublisher{publish: map[string]publishResult{
"tp-1": {result: ItemResult{BundleSHA256: repeatHex('a'), ProductionRevision: "prod-1"}},
"tp-2": {err: &ItemError{Code: ErrorCodeContractMismatch, Retryable: false}},
"tp-3": {result: ItemResult{BundleSHA256: repeatHex('b'), ProductionRevision: "prod-3"}},
}}
handler, err := NewHandler(store, publisher, func() time.Time { return time.Date(2026, 9, 6, 7, 0, 0, 0, time.UTC) })
if err != nil {
t.Fatal(err)
}
job := releaseJob("release.publish", 1, 3)
if err := handler(context.Background(), job); err != nil {
t.Fatal(err)
}
if len(store.completed) != 1 || store.completed[0].PublicationID != "tp-1" {
t.Fatalf("completed=%#v", store.completed)
}
if len(store.failed) != 2 || store.failed[0].ErrorCode != ErrorCodeContractMismatch || store.failed[1].PublicationID != "tp-3" || store.failed[1].ErrorCode != ErrorCodeStoppedAfterFailure {
t.Fatalf("failed=%#v", store.failed)
}
if store.finishedExecutionID != "rx-safe" || store.automaticRollbackExecutionID != "rx-safe" || publisher.publishCalls != 2 {
t.Fatalf("finished=%q rollback=%q publishCalls=%d", store.finishedExecutionID, store.automaticRollbackExecutionID, publisher.publishCalls)
}
}
func TestHandlerPersistsProgressAtFiftyItemBatchBoundaries(t *testing.T) {
items := make([]PlanItem, 0, 105)
results := make(map[string]publishResult, 105)
for index := 0; index < 105; index++ {
id := fmt.Sprintf("tp-%03d", index)
items = append(items, PlanItem{PublicationID: id})
results[id] = publishResult{result: ItemResult{BundleSHA256: repeatHex('a'), ProductionRevision: "prod-1"}}
}
store := &fakeStore{items: items}
handler, err := NewHandler(store, &fakePublisher{publish: results}, time.Now)
if err != nil {
t.Fatal(err)
}
if err := handler(context.Background(), releaseJob("release.publish", 1, 3)); err != nil {
t.Fatal(err)
}
if !reflect.DeepEqual(store.startedBatches, [][2]int{{1, 3}, {2, 3}, {3, 3}}) {
t.Fatalf("started batches=%v", store.startedBatches)
}
}
func TestHandlerPublishesDeleteActionAsVerifiedAbsentRevision(t *testing.T) {
store := &fakeStore{items: []PlanItem{{PublicationID: "tp-delete", Action: "delete", PreviousProductionRevision: "prod-current"}}}
publisher := &fakePublisher{delete: map[string]publishResult{
"tp-delete": {result: ItemResult{BundleSHA256: repeatHex('d'), PreviousProductionRevision: "prod-current", ProductionRevision: "absent"}},
}}
handler, err := NewHandler(store, publisher, func() time.Time { return time.Date(2026, 9, 10, 4, 0, 0, 0, time.UTC) })
if err != nil {
t.Fatal(err)
}
if err := handler(context.Background(), jobs.Job{ID: "job-delete", Type: "release.publish", Payload: []byte(`{"execution_id":"rx-delete","release_batch_id":"rb-delete","operation":"publish"}`), Attempt: 1, MaxAttempts: 3}); err != nil {
t.Fatal(err)
}
if publisher.deleteCalls != 1 || publisher.publishCalls != 0 || len(store.completed) != 1 || store.completed[0].ProductionRevision != "absent" {
t.Fatalf("deleteCalls=%d publishCalls=%d completed=%#v", publisher.deleteCalls, publisher.publishCalls, store.completed)
}
}
func TestHandlerReturnsOnlySanitizedRetryErrorBeforeLastAttempt(t *testing.T) {
store := &fakeStore{items: []PlanItem{{PublicationID: "tp-1"}}}
publisher := &fakePublisher{publish: map[string]publishResult{
"tp-1": {err: &ItemError{Code: ErrorCodeTargetUnavailable, Retryable: true, Cause: errors.New("raw endpoint and credential text")}},
}}
handler, _ := NewHandler(store, publisher, time.Now)
err := handler(context.Background(), releaseJob("release.publish", 1, 3))
if !errors.Is(err, ErrReleaseRetryable) || err.Error() != ErrReleaseRetryable.Error() {
t.Fatalf("error=%v", err)
}
if len(store.failed) != 0 || store.finishedExecutionID != "" {
t.Fatalf("failed=%#v finished=%q", store.failed, store.finishedExecutionID)
}
}
func TestHandlerFailsRetryableItemsWithFixedCodeOnLastAttempt(t *testing.T) {
store := &fakeStore{items: []PlanItem{{PublicationID: "tp-1"}}}
publisher := &fakePublisher{publish: map[string]publishResult{
"tp-1": {err: &ItemError{Code: ErrorCodeTargetUnavailable, Retryable: true}},
}}
handler, _ := NewHandler(store, publisher, time.Now)
if err := handler(context.Background(), releaseJob("release.publish", 3, 3)); err != nil {
t.Fatal(err)
}
if len(store.failed) != 1 || store.failed[0].ErrorCode != ErrorCodeTargetUnavailable || store.finishedExecutionID != "rx-safe" {
t.Fatalf("failed=%#v finished=%q", store.failed, store.finishedExecutionID)
}
}
func TestHandlerDispatchesRollbackAndRejectsInvalidPayload(t *testing.T) {
store := &fakeStore{items: []PlanItem{{PublicationID: "tp-1"}}}
publisher := &fakePublisher{rollback: map[string]publishResult{"tp-1": {result: ItemResult{ProductionRevision: "prod-old"}}}}
handler, _ := NewHandler(store, publisher, time.Now)
if err := handler(context.Background(), releaseJob("release.rollback", 1, 3)); err != nil {
t.Fatal(err)
}
if publisher.rollbackCalls != 1 || publisher.publishCalls != 0 {
t.Fatalf("publish=%d rollback=%d", publisher.publishCalls, publisher.rollbackCalls)
}
bad := releaseJob("release.publish", 1, 3)
bad.Payload = []byte(`{"execution_id":"../bad"}`)
if err := handler(context.Background(), bad); !errors.Is(err, ErrInvalidReleaseJob) {
t.Fatalf("error=%v", err)
}
// Production rollback payloads carry prior_execution_id; the strict
// decoder must accept it (regression: release jobs failed permanently as
// invalid_release_job the moment rollback executions included the field).
withPrior := releaseJob("release.rollback", 1, 3)
withPrior.Payload = []byte(`{"execution_id":"rx-safe","release_batch_id":"rb-safe","operation":"rollback","prior_execution_id":"rx-prior"}`)
if err := handler(context.Background(), withPrior); err != nil {
t.Fatalf("rollback payload with prior_execution_id rejected: %v", err)
}
}
func releaseJob(jobType string, attempt, maxAttempts int) jobs.Job {
payload := []byte(`{"execution_id":"rx-safe","release_batch_id":"rb-safe","operation":"publish"}`)
if jobType == "release.rollback" {
payload = []byte(`{"execution_id":"rx-safe","release_batch_id":"rb-safe","operation":"rollback"}`)
}
return jobs.Job{ID: "job-safe", Type: jobType, Payload: payload, Attempt: attempt, MaxAttempts: maxAttempts}
}
type fakeStore struct {
items []PlanItem
completed []CompleteItemRequest
failed []FailItemRequest
finishedExecutionID string
automaticRollbackExecutionID string
startedBatches [][2]int
}
func (s *fakeStore) StartExecution(context.Context, StartExecutionRequest) ([]PlanItem, error) {
return s.items, nil
}
func (s *fakeStore) CompleteItem(_ context.Context, request CompleteItemRequest) error {
s.completed = append(s.completed, request)
return nil
}
func (s *fakeStore) FailItem(_ context.Context, request FailItemRequest) error {
s.failed = append(s.failed, request)
return nil
}
func (s *fakeStore) FinishExecution(_ context.Context, executionID string, _ time.Time) error {
s.finishedExecutionID = executionID
return nil
}
func (s *fakeStore) ScheduleAutomaticRollback(_ context.Context, executionID string, _ time.Time) error {
s.automaticRollbackExecutionID = executionID
return nil
}
func (s *fakeStore) BeginBatch(_ context.Context, _ string, batch, total int, _ time.Time) error {
s.startedBatches = append(s.startedBatches, [2]int{batch, total})
return nil
}
type publishResult struct {
result ItemResult
err error
}
type fakePublisher struct {
publish, rollback, delete map[string]publishResult
publishCalls, rollbackCalls, deleteCalls int
}
func (p *fakePublisher) Publish(_ context.Context, item PlanItem) (ItemResult, error) {
p.publishCalls++
value := p.publish[item.PublicationID]
return value.result, value.err
}
func (p *fakePublisher) Rollback(_ context.Context, item PlanItem) (ItemResult, error) {
p.rollbackCalls++
value := p.rollback[item.PublicationID]
return value.result, value.err
}
func (p *fakePublisher) Delete(_ context.Context, item PlanItem) (ItemResult, error) {
p.deleteCalls++
value := p.delete[item.PublicationID]
return value.result, value.err
}
func repeatHex(value byte) string {
result := make([]byte, 64)
for index := range result {
result[index] = value
}
return string(result)
}
var _ = governance.ReleaseOperationPublish
@@ -0,0 +1,65 @@
package release
import (
"context"
"errors"
"strings"
)
type RoutingPublisher struct {
publishers map[string]Publisher
}
func NewRoutingPublisher(publishers map[string]Publisher) (*RoutingPublisher, error) {
if len(publishers) == 0 {
return nil, errors.New("release publisher routes are required")
}
copied := make(map[string]Publisher, len(publishers))
for knowledgeBaseID, publisher := range publishers {
if !validRoutingID(knowledgeBaseID) || publisher == nil {
return nil, errors.New("invalid release publisher route")
}
copied[knowledgeBaseID] = publisher
}
return &RoutingPublisher{publishers: copied}, nil
}
func (router *RoutingPublisher) Publish(ctx context.Context, item PlanItem) (ItemResult, error) {
publisher, ok := router.publishers[item.TestKnowledgeBaseID]
if !ok {
return ItemResult{}, &ItemError{Code: ErrorCodeContractMismatch, Retryable: false}
}
return publisher.Publish(ctx, item)
}
func (router *RoutingPublisher) Rollback(ctx context.Context, item PlanItem) (ItemResult, error) {
publisher, ok := router.publishers[item.TestKnowledgeBaseID]
if !ok {
return ItemResult{}, &ItemError{Code: ErrorCodeContractMismatch, Retryable: false}
}
return publisher.Rollback(ctx, item)
}
func (router *RoutingPublisher) Delete(ctx context.Context, item PlanItem) (ItemResult, error) {
publisher, ok := router.publishers[item.TestKnowledgeBaseID]
if !ok {
return ItemResult{}, &ItemError{Code: ErrorCodeContractMismatch, Retryable: false}
}
return publisher.Delete(ctx, item)
}
func validRoutingID(value string) bool {
value = strings.TrimSpace(value)
if value == "" || len(value) > 128 {
return false
}
for _, char := range value {
if (char >= 'a' && char <= 'z') || (char >= 'A' && char <= 'Z') || (char >= '0' && char <= '9') || char == '-' || char == '_' || char == '.' {
continue
}
return false
}
return true
}
var _ Publisher = (*RoutingPublisher)(nil)
@@ -0,0 +1,52 @@
package release
import (
"context"
"testing"
)
func TestRoutingPublisherSelectsExactKnowledgeBase(t *testing.T) {
first := &routingPublisherStub{result: ItemResult{ProductionRevision: "prod-a"}}
second := &routingPublisherStub{result: ItemResult{ProductionRevision: "prod-b"}}
router, err := NewRoutingPublisher(map[string]Publisher{"kb-a": first, "kb-b": second})
if err != nil {
t.Fatal(err)
}
item := testPlanItem()
item.TestKnowledgeBaseID = "kb-b"
result, err := router.Publish(context.Background(), item)
if err != nil {
t.Fatal(err)
}
if result.ProductionRevision != "prod-b" || first.calls != 0 || second.calls != 1 {
t.Fatalf("result=%#v calls=%d/%d", result, first.calls, second.calls)
}
if _, err := router.Delete(context.Background(), item); err != nil || first.deleteCalls != 0 || second.deleteCalls != 1 {
t.Fatalf("delete error=%v deleteCalls=%d/%d", err, first.deleteCalls, second.deleteCalls)
}
item.TestKnowledgeBaseID = "unknown"
if _, err := router.Publish(context.Background(), item); err == nil || err.Error() != ErrorCodeContractMismatch {
t.Fatalf("error=%v", err)
}
}
type routingPublisherStub struct {
result ItemResult
err error
calls int
deleteCalls int
}
func (s *routingPublisherStub) Publish(context.Context, PlanItem) (ItemResult, error) {
s.calls++
return s.result, s.err
}
func (s *routingPublisherStub) Rollback(context.Context, PlanItem) (ItemResult, error) {
s.calls++
return s.result, s.err
}
func (s *routingPublisherStub) Delete(context.Context, PlanItem) (ItemResult, error) {
s.deleteCalls++
return s.result, s.err
}
@@ -0,0 +1,162 @@
package release
import (
"context"
"errors"
"strings"
"knowledge-governance/internal/releasebundle"
)
type BundleExporter interface {
Export(ctx context.Context, item PlanItem) (ExportedBundle, error)
}
type ExportedBundle interface {
ReleaseManifest() releasebundle.Manifest
}
type PreparedChange struct {
PreviousRevision string
ProductionRevision string
}
type SidecarTarget interface {
Contract(ctx context.Context, item PlanItem) (releasebundle.TargetContract, error)
Prepare(ctx context.Context, item PlanItem, bundle ExportedBundle) (PreparedChange, error)
Activate(ctx context.Context, item PlanItem, change PreparedChange) error
Verify(ctx context.Context, item PlanItem, change PreparedChange) error
Compensate(ctx context.Context, item PlanItem, change PreparedChange) error
Restore(ctx context.Context, item PlanItem, revision string) (string, error)
VerifyRestored(ctx context.Context, item PlanItem, revision string) error
}
type SidecarPublisher struct {
exporter BundleExporter
target SidecarTarget
}
func NewSidecarPublisher(exporter BundleExporter, target SidecarTarget) (*SidecarPublisher, error) {
if exporter == nil || target == nil {
return nil, errors.New("release sidecar dependencies are required")
}
return &SidecarPublisher{exporter: exporter, target: target}, nil
}
func (publisher *SidecarPublisher) Publish(ctx context.Context, item PlanItem) (ItemResult, error) {
bundle, err := publisher.exporter.Export(ctx, item)
if err != nil {
return ItemResult{}, newSidecarError(ErrorCodeTargetUnavailable, true, err)
}
if bundle == nil {
return ItemResult{}, newSidecarError(ErrorCodeBundleInvalid, false, errors.New("empty release bundle"))
}
manifest := bundle.ReleaseManifest()
if manifest.ExecutionID != item.ReleaseExecutionID || manifest.PublicationID != item.PublicationID ||
manifest.SourceItemVersionID != item.SourceItemVersionID || manifest.SourceRevision != item.SourceRevision ||
manifest.ParseRevision != item.ParseRevision || manifest.ReleaseRevision != item.ReleaseRevision ||
manifest.Contract.KnowledgeBaseID != item.TestKnowledgeBaseID || manifest.Contract.KnowledgeID != item.KnowledgeID {
return ItemResult{}, newSidecarError(ErrorCodeContractMismatch, false, errors.New("bundle identity mismatch"))
}
targetContract, err := publisher.target.Contract(ctx, item)
if err != nil {
return ItemResult{}, newSidecarError(ErrorCodeTargetUnavailable, true, err)
}
if err := releasebundle.Validate(manifest, targetContract); err != nil {
return ItemResult{}, newSidecarError(ErrorCodeContractMismatch, false, err)
}
change, err := publisher.target.Prepare(ctx, item, bundle)
if err != nil {
return ItemResult{}, newSidecarError(ErrorCodeTargetWriteFailed, true, err)
}
if !validRevision(change.ProductionRevision) || (change.PreviousRevision != "" && !validRevision(change.PreviousRevision)) {
return ItemResult{}, publisher.compensateError(ctx, item, change, ErrorCodeBundleInvalid, errors.New("invalid prepared revision"))
}
if err := publisher.target.Activate(ctx, item, change); err != nil {
return ItemResult{}, publisher.compensateError(ctx, item, change, ErrorCodeTargetWriteFailed, err)
}
if err := publisher.target.Verify(ctx, item, change); err != nil {
return ItemResult{}, publisher.compensateError(ctx, item, change, ErrorCodeVerificationFailed, err)
}
return ItemResult{
BundleSHA256: manifest.BundleSHA256,
PreviousProductionRevision: change.PreviousRevision,
ProductionRevision: change.ProductionRevision,
}, nil
}
func (publisher *SidecarPublisher) Rollback(ctx context.Context, item PlanItem) (ItemResult, error) {
if !validRevision(item.PreviousProductionRevision) {
return ItemResult{}, newSidecarError(ErrorCodeRollbackArtifactMissing, false, errors.New("missing rollback revision"))
}
restoredRevision, err := publisher.target.Restore(ctx, item, item.PreviousProductionRevision)
if err != nil {
return ItemResult{}, newSidecarError(ErrorCodeTargetWriteFailed, true, err)
}
if restoredRevision != item.PreviousProductionRevision {
return ItemResult{}, newSidecarError(ErrorCodeContractMismatch, false, errors.New("restored revision mismatch"))
}
if err := publisher.target.VerifyRestored(ctx, item, restoredRevision); err != nil {
return ItemResult{}, newSidecarError(ErrorCodeVerificationFailed, false, err)
}
return ItemResult{ProductionRevision: restoredRevision}, nil
}
func (publisher *SidecarPublisher) Delete(ctx context.Context, item PlanItem) (ItemResult, error) {
bundle, err := publisher.exporter.Export(ctx, item)
if err != nil {
return ItemResult{}, newSidecarError(ErrorCodeTargetUnavailable, true, err)
}
if bundle == nil {
return ItemResult{}, newSidecarError(ErrorCodeBundleInvalid, false, errors.New("empty release bundle"))
}
manifest := bundle.ReleaseManifest()
if manifest.ExecutionID != item.ReleaseExecutionID || manifest.PublicationID != item.PublicationID ||
manifest.SourceItemVersionID != item.SourceItemVersionID || manifest.SourceRevision != item.SourceRevision ||
manifest.ParseRevision != item.ParseRevision || manifest.ReleaseRevision != item.ReleaseRevision ||
manifest.Contract.KnowledgeBaseID != item.TestKnowledgeBaseID || manifest.Contract.KnowledgeID != item.KnowledgeID {
return ItemResult{}, newSidecarError(ErrorCodeContractMismatch, false, errors.New("bundle identity mismatch"))
}
targetContract, err := publisher.target.Contract(ctx, item)
if err != nil {
return ItemResult{}, newSidecarError(ErrorCodeTargetUnavailable, true, err)
}
if err := releasebundle.Validate(manifest, targetContract); err != nil {
return ItemResult{}, newSidecarError(ErrorCodeContractMismatch, false, err)
}
change, err := publisher.target.Prepare(ctx, item, bundle)
if err != nil {
return ItemResult{}, newSidecarError(ErrorCodeTargetWriteFailed, true, err)
}
if !validRevision(change.PreviousRevision) || change.ProductionRevision != item.ReleaseRevision {
return ItemResult{}, publisher.compensateError(ctx, item, change, ErrorCodeBundleInvalid, errors.New("invalid delete snapshot revision"))
}
restoredRevision, err := publisher.target.Restore(ctx, item, "absent")
if err != nil {
return ItemResult{}, publisher.compensateError(ctx, item, change, ErrorCodeTargetWriteFailed, err)
}
if restoredRevision != "absent" {
return ItemResult{}, publisher.compensateError(ctx, item, change, ErrorCodeContractMismatch, errors.New("deleted revision mismatch"))
}
if err := publisher.target.VerifyRestored(ctx, item, "absent"); err != nil {
return ItemResult{}, publisher.compensateError(ctx, item, change, ErrorCodeVerificationFailed, err)
}
return ItemResult{BundleSHA256: manifest.BundleSHA256, PreviousProductionRevision: change.PreviousRevision, ProductionRevision: "absent"}, nil
}
func (publisher *SidecarPublisher) compensateError(ctx context.Context, item PlanItem, change PreparedChange, code string, cause error) error {
if err := publisher.target.Compensate(ctx, item, change); err != nil {
return newSidecarError(ErrorCodeRollbackFailed, false, err)
}
return newSidecarError(code, false, cause)
}
func newSidecarError(code string, retryable bool, cause error) error {
return &ItemError{Code: code, Retryable: retryable, Cause: cause}
}
func validRevision(value string) bool {
return value == strings.TrimSpace(value) && value != "" && len(value) <= 128 && !strings.ContainsAny(value, "\x00\r\n\t/?#\\")
}
var _ Publisher = (*SidecarPublisher)(nil)
@@ -0,0 +1,217 @@
package release
import (
"context"
"errors"
"reflect"
"strings"
"testing"
"time"
"knowledge-governance/internal/releasebundle"
)
func TestSidecarPublisherPublishesWithContractAndVerification(t *testing.T) {
calls := []string{}
manifest, err := releasebundle.Seal(testManifest())
if err != nil {
t.Fatal(err)
}
exporter := &fakeExporter{manifest: manifest, calls: &calls}
target := &fakeSidecarTarget{contract: testTargetContract(), calls: &calls, prepared: PreparedChange{PreviousRevision: "prod-v0", ProductionRevision: "prod-v1"}}
publisher, err := NewSidecarPublisher(exporter, target)
if err != nil {
t.Fatal(err)
}
result, err := publisher.Publish(context.Background(), testPlanItem())
if err != nil {
t.Fatal(err)
}
if result.BundleSHA256 != manifest.BundleSHA256 || result.PreviousProductionRevision != "prod-v0" || result.ProductionRevision != "prod-v1" {
t.Fatalf("result=%#v", result)
}
want := []string{"export", "contract", "prepare", "activate", "verify"}
if !reflect.DeepEqual(calls, want) {
t.Fatalf("calls=%v want=%v", calls, want)
}
}
func TestSidecarPublisherRollsBackFailedVerificationWithoutLeakingCause(t *testing.T) {
calls := []string{}
manifest, err := releasebundle.Seal(testManifest())
if err != nil {
t.Fatal(err)
}
target := &fakeSidecarTarget{contract: testTargetContract(), calls: &calls, prepared: PreparedChange{PreviousRevision: "prod-v0", ProductionRevision: "prod-v1"}, verifyErr: errors.New("signed-url-secret-should-not-leak")}
publisher, err := NewSidecarPublisher(&fakeExporter{manifest: manifest, calls: &calls}, target)
if err != nil {
t.Fatal(err)
}
_, err = publisher.Publish(context.Background(), testPlanItem())
var itemErr *ItemError
if !errors.As(err, &itemErr) || itemErr.Code != ErrorCodeVerificationFailed || itemErr.Retryable {
t.Fatalf("error=%#v", err)
}
if strings.Contains(err.Error(), "signed-url") {
t.Fatalf("error leaked cause: %v", err)
}
want := []string{"export", "contract", "prepare", "activate", "verify", "compensate"}
if !reflect.DeepEqual(calls, want) {
t.Fatalf("calls=%v want=%v", calls, want)
}
}
func TestSidecarPublisherRejectsContractDriftBeforeTargetMutation(t *testing.T) {
calls := []string{}
manifest, err := releasebundle.Seal(testManifest())
if err != nil {
t.Fatal(err)
}
contract := testTargetContract()
contract.EmbeddingDimension = 768
publisher, err := NewSidecarPublisher(&fakeExporter{manifest: manifest, calls: &calls}, &fakeSidecarTarget{contract: contract, calls: &calls})
if err != nil {
t.Fatal(err)
}
_, err = publisher.Publish(context.Background(), testPlanItem())
var itemErr *ItemError
if !errors.As(err, &itemErr) || itemErr.Code != ErrorCodeContractMismatch {
t.Fatalf("error=%#v", err)
}
if !reflect.DeepEqual(calls, []string{"export", "contract"}) {
t.Fatalf("calls=%v", calls)
}
}
func TestSidecarPublisherRejectsRevisionMismatchBeforeTargetMutation(t *testing.T) {
calls := []string{}
manifest, err := releasebundle.Seal(testManifest())
if err != nil {
t.Fatal(err)
}
item := testPlanItem()
item.ParseRevision = "other-parser/index"
publisher, err := NewSidecarPublisher(&fakeExporter{manifest: manifest, calls: &calls}, &fakeSidecarTarget{contract: testTargetContract(), calls: &calls})
if err != nil {
t.Fatal(err)
}
_, err = publisher.Publish(context.Background(), item)
var itemErr *ItemError
if !errors.As(err, &itemErr) || itemErr.Code != ErrorCodeContractMismatch {
t.Fatalf("error=%#v", err)
}
if !reflect.DeepEqual(calls, []string{"export"}) {
t.Fatalf("calls=%v", calls)
}
}
func TestSidecarPublisherDeletesOnlyAfterArchivingAndVerifiesAbsent(t *testing.T) {
calls := []string{}
manifest, err := releasebundle.Seal(testManifest())
if err != nil {
t.Fatal(err)
}
target := &fakeSidecarTarget{contract: testTargetContract(), calls: &calls, prepared: PreparedChange{PreviousRevision: "prod-v0", ProductionRevision: "release-v1"}, expectedRestoreRevision: "absent", restoredRevision: "absent"}
publisher, err := NewSidecarPublisher(&fakeExporter{manifest: manifest, calls: &calls}, target)
if err != nil {
t.Fatal(err)
}
result, err := publisher.Delete(context.Background(), testPlanItem())
if err != nil {
t.Fatal(err)
}
if result.BundleSHA256 != manifest.BundleSHA256 || result.PreviousProductionRevision != "prod-v0" || result.ProductionRevision != "absent" {
t.Fatalf("result=%#v", result)
}
if want := []string{"export", "contract", "prepare", "restore", "verify-restored"}; !reflect.DeepEqual(calls, want) {
t.Fatalf("calls=%v want=%v", calls, want)
}
}
func TestSidecarPublisherRestoresArchivedRevision(t *testing.T) {
calls := []string{}
target := &fakeSidecarTarget{calls: &calls, restoredRevision: "prod-v0"}
publisher, err := NewSidecarPublisher(&fakeExporter{}, target)
if err != nil {
t.Fatal(err)
}
result, err := publisher.Rollback(context.Background(), testPlanItem())
if err != nil {
t.Fatal(err)
}
if result.ProductionRevision != "prod-v0" || !reflect.DeepEqual(calls, []string{"restore", "verify-restored"}) {
t.Fatalf("result=%#v calls=%v", result, calls)
}
}
type fakeExporter struct {
manifest releasebundle.Manifest
calls *[]string
err error
}
func (f *fakeExporter) Export(context.Context, PlanItem) (ExportedBundle, error) {
if f.calls != nil {
*f.calls = append(*f.calls, "export")
}
return fakeExportedBundle{manifest: f.manifest}, f.err
}
type fakeExportedBundle struct{ manifest releasebundle.Manifest }
func (bundle fakeExportedBundle) ReleaseManifest() releasebundle.Manifest { return bundle.manifest }
type fakeSidecarTarget struct {
contract releasebundle.TargetContract
calls *[]string
prepared PreparedChange
prepareErr, activateErr, verifyErr, compensateErr, restoreErr, verifyRestoredErr error
restoredRevision string
expectedRestoreRevision string
}
func (f *fakeSidecarTarget) Contract(context.Context, PlanItem) (releasebundle.TargetContract, error) {
*f.calls = append(*f.calls, "contract")
return f.contract, nil
}
func (f *fakeSidecarTarget) Prepare(context.Context, PlanItem, ExportedBundle) (PreparedChange, error) {
*f.calls = append(*f.calls, "prepare")
return f.prepared, f.prepareErr
}
func (f *fakeSidecarTarget) Activate(context.Context, PlanItem, PreparedChange) error {
*f.calls = append(*f.calls, "activate")
return f.activateErr
}
func (f *fakeSidecarTarget) Verify(context.Context, PlanItem, PreparedChange) error {
*f.calls = append(*f.calls, "verify")
return f.verifyErr
}
func (f *fakeSidecarTarget) Compensate(context.Context, PlanItem, PreparedChange) error {
*f.calls = append(*f.calls, "compensate")
return f.compensateErr
}
func (f *fakeSidecarTarget) Restore(_ context.Context, _ PlanItem, revision string) (string, error) {
*f.calls = append(*f.calls, "restore")
expected := f.expectedRestoreRevision
if expected == "" {
expected = "prod-v0"
}
if revision != expected {
return "", errors.New("wrong revision")
}
return f.restoredRevision, f.restoreErr
}
func (f *fakeSidecarTarget) VerifyRestored(context.Context, PlanItem, string) error {
*f.calls = append(*f.calls, "verify-restored")
return f.verifyRestoredErr
}
func testPlanItem() PlanItem {
return PlanItem{ReleaseExecutionID: "rx-safe", PublicationID: "tp-safe", SourceItemVersionID: "sv-safe", SourceRevision: "source-v1", ParseRevision: "parser-v1@index-v1", ReleaseRevision: "release-v1", TestKnowledgeBaseID: "kb-safe", KnowledgeID: "knowledge-safe", DecidedVisibility: "internal", PreviousProductionRevision: "prod-v0"}
}
func testManifest() releasebundle.Manifest {
return releasebundle.Manifest{FormatVersion: releasebundle.FormatVersionV1, ExecutionID: "rx-safe", PublicationID: "tp-safe", SourceItemVersionID: "sv-safe", SourceRevision: "source-v1", ParseRevision: "parser-v1@index-v1", ReleaseRevision: "release-v1", CreatedAt: time.Date(2026, 9, 6, 8, 0, 0, 0, time.UTC), Contract: releasebundle.Contract{WeKnoraVersion: releasebundle.WeKnoraVersionV071, MigrationVersion: releasebundle.WeKnoraMigrationV071, TenantID: 10000, KnowledgeBaseID: "kb-safe", KnowledgeID: "knowledge-safe", RetrieverEngine: "elasticsearch_v8", EmbeddingModel: "bge-m3", EmbeddingDimension: releasebundle.EmbeddingDimensionV071, ElasticsearchMappingSHA256: strings.Repeat("a", 64)}, Tables: []releasebundle.TableDigest{{Name: "knowledges", RowCount: 1, SHA256: strings.Repeat("b", 64)}, {Name: "chunks", RowCount: 1, SHA256: strings.Repeat("c", 64)}}, Search: releasebundle.SearchDigest{DocumentCount: 1, SHA256: strings.Repeat("d", 64)}, Assets: releasebundle.AssetDigest{SHA256: strings.Repeat("e", 64)}}
}
func testTargetContract() releasebundle.TargetContract {
return releasebundle.TargetContract{WeKnoraVersion: releasebundle.WeKnoraVersionV071, MigrationVersion: releasebundle.WeKnoraMigrationV071, TenantID: 10000, KnowledgeBaseID: "kb-safe", RetrieverEngine: "elasticsearch_v8", EmbeddingModel: "bge-m3", EmbeddingDimension: releasebundle.EmbeddingDimensionV071, ElasticsearchMappingSHA256: strings.Repeat("a", 64)}
}