《后端架构设计·演进与治理》9.1 制品、环境与不可变部署

// file: internal/platform/release/artifact.go
// tier: L1
// verify: go test ./internal/platform/release/ -count=1
package release

import (
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"fmt"
	"slices"
	"sort"
	"strings"
	"time"
)

// Clock lets deployment checks run against a fixed timeline in tests.
type Clock func() time.Time

// Digest is the content address of one artifact: "sha256:" plus 64 hex chars.
type Digest string

// DigestOf returns the content address of b.
func DigestOf(b []byte) Digest {
	sum := sha256.Sum256(b)
	return Digest("sha256:" + hex.EncodeToString(sum[:]))
}

// ParseDigest accepts only a lowercase sha256 content address, never a tag.
func ParseDigest(s string) (Digest, error) {
	body, ok := strings.CutPrefix(s, "sha256:")
	if !ok || len(body) != 64 {
		return "", fmt.Errorf("release: %q is not a 64-char digest", s)
	}
	for _, r := range body {
		if (r < '0' || r > '9') && (r < 'a' || r > 'f') {
			return "", errors.New("release: digest is not lowercase hex")
		}
	}
	return Digest(s), nil
}

// Artifact is an immutable build output.
type Artifact struct {
	Name, Version string
	Digest        Digest
	Size          int64
	BuiltAt       time.Time
}

// Registry stores artifacts by content address. A digest is never overwritten,
// so a rollback returns exactly the bytes that ran before.
type Registry struct{ artifacts map[Digest]Artifact }

// NewRegistry returns an empty registry.
func NewRegistry() *Registry { return &Registry{artifacts: map[Digest]Artifact{}} }

// Push verifies content and metadata before recording the artifact.
func (r *Registry) Push(a Artifact, content []byte) error {
	if a.Name == "" || a.Version == "" || a.Size <= 0 || a.BuiltAt.IsZero() {
		return errors.New("release: artifact metadata is incomplete")
	}
	if _, err := ParseDigest(string(a.Digest)); err != nil {
		return err
	}
	if got := DigestOf(content); got != a.Digest {
		return fmt.Errorf("release: content hashes to %s, declared %s", got, a.Digest)
	}
	if a.Size != int64(len(content)) {
		return fmt.Errorf("release: size %d, content %d", a.Size, len(content))
	}
	if _, exists := r.artifacts[a.Digest]; exists {
		return fmt.Errorf("release: digest %s already stored", a.Digest)
	}
	r.artifacts[a.Digest] = a
	return nil
}

// Resolve returns the stored artifact for a digest.
func (r *Registry) Resolve(d Digest) (Artifact, error) {
	a, ok := r.artifacts[d]
	if !ok {
		return Artifact{}, fmt.Errorf("release: digest %s not found", d)
	}
	return a, nil
}

// Deployment is one pinned release in one environment.
type Deployment struct {
	Environment, Version, Actor string
	Digest, Previous            Digest
	Config                      uint64
	At                          time.Time
}

// DeployRequest is what a pipeline may ask an environment to run.
type DeployRequest struct {
	Digest Digest
	Config uint64
	Actor  string
}

// Environment holds the current deployment.
type Environment struct {
	Name    string
	Accepts []string
	MinBake time.Duration
	Current *Deployment
}

// Deploy accepts a registry digest, never a tag such as "orders:latest".
func (e *Environment) Deploy(clock Clock, reg *Registry, req DeployRequest) (Deployment, error) {
	if e.Name == "" {
		return Deployment{}, errors.New("release: environment name is empty")
	}
	if _, err := ParseDigest(string(req.Digest)); err != nil {
		return Deployment{}, err
	}
	art, err := reg.Resolve(req.Digest)
	if err != nil {
		return Deployment{}, err
	}
	if req.Config == 0 || req.Actor == "" {
		return Deployment{}, errors.New("release: config and actor are required")
	}
	d := Deployment{Environment: e.Name, Digest: art.Digest, Version: art.Version,
		Config: req.Config, Actor: req.Actor, At: clock()}
	if e.Current != nil {
		d.Previous = e.Current.Digest
	}
	e.Current = &d
	return d, nil
}

// CanPromote checks the allowed path and the bake time.
func CanPromote(source, target Environment, clock Clock) error {
	if !slices.Contains(target.Accepts, source.Name) {
		return fmt.Errorf("release: %s does not accept promotion from %s", target.Name, source.Name)
	}
	if source.Current == nil {
		return fmt.Errorf("release: %s has no deployment", source.Name)
	}
	if elapsed := clock().Sub(source.Current.At); elapsed < target.MinBake {
		return fmt.Errorf("release: baked %s, want %s", elapsed, target.MinBake)
	}
	return nil
}

// Instance is one process reporting the digest it actually loaded.
type Instance struct {
	ID     string
	Digest Digest
}

// DriftItem is one instance running something other than the declared digest.
type DriftItem struct {
	Instance          string
	Running, Expected Digest
}

// Drift returns instances not running the declared digest, sorted by ID.
func Drift(expected Digest, instances []Instance) []DriftItem {
	var out []DriftItem
	for _, in := range instances {
		if in.Digest != expected {
			out = append(out, DriftItem{in.ID, in.Digest, expected})
		}
	}
	sort.Slice(out, func(i, j int) bool { return out[i].Instance < out[j].Instance })
	return out
}

// file: internal/platform/release/artifact_test.go
// tier: L1
// verify: go test ./internal/platform/release/ -count=1
package release

import (
	"strings"
	"testing"
	"time"
)

func fixedClock(t time.Time) Clock { return func() time.Time { return t } }

func registryWith(t *testing.T, content []byte, version string) (*Registry, Digest) {
	t.Helper()
	d := DigestOf(content)
	reg := NewRegistry()
	err := reg.Push(Artifact{Name: "orders", Version: version, Digest: d,
		Size: int64(len(content)), BuiltAt: time.Unix(0, 0).UTC()}, content)
	if err != nil {
		t.Fatalf("push: %v", err)
	}
	return reg, d
}

func TestDigestAndRegistry(t *testing.T) {
	content := []byte("orders image v1")
	reg, d := registryWith(t, content, "1.4.2")
	if _, err := ParseDigest(string(d)); err != nil {
		t.Fatalf("DigestOf produced invalid digest: %v", err)
	}
	for _, bad := range []string{"orders:latest", "sha256:abc", "sha256:" + strings.Repeat("A", 64)} {
		if _, err := ParseDigest(bad); err == nil {
			t.Fatalf("accepted %q", bad)
		}
	}
	art, _ := reg.Resolve(d)
	if err := reg.Push(art, []byte("orders image v2")); err == nil {
		t.Fatal("content/digest mismatch accepted")
	}
	if err := reg.Push(art, content); err == nil {
		t.Fatal("duplicate digest overwrote an immutable artifact")
	}
	t.Logf("digest=%s version=%s", d, art.Version)
}

func TestDeployRequiresDigest(t *testing.T) {
	content := []byte("orders image v1")
	reg, d := registryWith(t, content, "1.4.2")
	now := time.Date(2026, 10, 31, 0, 0, 0, 0, time.UTC)
	env := Environment{Name: "prod"}
	if _, err := env.Deploy(fixedClock(now), reg, DeployRequest{Digest: "orders:latest", Config: 7, Actor: "pipeline"}); err == nil {
		t.Fatal("tag accepted as a deployable reference")
	}
	if _, err := env.Deploy(fixedClock(now), reg, DeployRequest{Digest: d, Config: 0, Actor: "pipeline"}); err == nil {
		t.Fatal("zero config version accepted")
	}
	dep, err := env.Deploy(fixedClock(now), reg, DeployRequest{Digest: d, Config: 7, Actor: "pipeline"})
	if err != nil || dep.Version != "1.4.2" || dep.Config != 7 {
		t.Fatalf("Deploy = %+v, %v", dep, err)
	}
	t.Logf("deployed digest=%s config=%d", dep.Digest, dep.Config)
}

func TestPromotionBakeTime(t *testing.T) {
	content := []byte("orders image v1")
	reg, d := registryWith(t, content, "1.4.2")
	base := time.Date(2026, 10, 31, 0, 0, 0, 0, time.UTC)
	staging := Environment{Name: "staging"}
	if _, err := staging.Deploy(fixedClock(base), reg, DeployRequest{Digest: d, Config: 7, Actor: "pipeline"}); err != nil {
		t.Fatal(err)
	}
	prod := Environment{Name: "prod", Accepts: []string{"staging"}, MinBake: 30 * time.Minute}
	if err := CanPromote(staging, prod, fixedClock(base.Add(10*time.Minute))); err == nil {
		t.Fatal("promoted before the bake window")
	}
	if err := CanPromote(staging, prod, fixedClock(base.Add(31*time.Minute))); err != nil {
		t.Fatalf("promotion after bake window: %v", err)
	}
	if err := CanPromote(Environment{Name: "dev"}, prod, fixedClock(base.Add(time.Hour))); err == nil {
		t.Fatal("dev promoted directly to prod")
	}
	t.Logf("staging baked=%s prod_min=%s", 31*time.Minute, prod.MinBake)
}

func TestDriftDetection(t *testing.T) {
	declared := DigestOf([]byte("orders image v2"))
	old := DigestOf([]byte("orders image v1"))
	instances := []Instance{{"orders-2", declared}, {"orders-1", old}, {"orders-3", old}, {"orders-0", declared}}
	drift := Drift(declared, instances)
	if len(drift) != 2 || drift[0].Instance != "orders-1" || drift[1].Instance != "orders-3" {
		t.Fatalf("drift = %+v", drift)
	}
	t.Logf("instances=%d drifting=%d first=%s", len(instances), len(drift), drift[0].Instance)
}

$ go test ./internal/platform/release/ -run 'TestDigestAndRegistry|TestDeployRequiresDigest|TestPromotionBakeTime|TestDriftDetection' -v -count=1
=== RUN   TestDigestAndRegistry
    artifact_test.go:44: digest=sha256:69aaeb8913379f079adbb3a18357fb546ca3e878c6410ffec8497af42d11f20c version=1.4.2
--- PASS: TestDigestAndRegistry (0.00s)
=== RUN   TestDeployRequiresDigest
    artifact_test.go:62: deployed digest=sha256:69aaeb8913379f079adbb3a18357fb546ca3e878c6410ffec8497af42d11f20c config=7
--- PASS: TestDeployRequiresDigest (0.00s)
=== RUN   TestPromotionBakeTime
    artifact_test.go:83: staging baked=31m0s prod_min=30m0s
--- PASS: TestPromotionBakeTime (0.00s)
=== RUN   TestDriftDetection
    artifact_test.go:94: instances=4 drifting=2 first=orders-1
--- PASS: TestDriftDetection (0.00s)
PASS
ok  	archlab/internal/platform/release	0.252s