docs: publish Tend Compose continuity evidence
Export the reviewed allowlisted snapshot from private source commit 07c1655921f21ee5e4fc4d85639d199e8867b17d. This records the Docker Compose activation, schema-compatible rollback, and stateful migration resource findings from Observatory Preview 19 dogfooding. AI-Assisted: OpenAI Codex Signed-off-by: Cole Speelman <crspeelman@gmail.com>
This commit is contained in:
@@ -0,0 +1,156 @@
|
||||
// SPDX-License-Identifier: AGPL-3.0-only
|
||||
|
||||
package state
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"io"
|
||||
"net/netip"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"regexp"
|
||||
"time"
|
||||
)
|
||||
|
||||
const CandidateLeaseSchemaVersion = 1
|
||||
|
||||
var (
|
||||
leaseOperationPattern = regexp.MustCompile(`^[0-9a-f]{32}$`)
|
||||
leaseServicePattern = regexp.MustCompile(`^[a-z][a-z0-9-]{1,62}$`)
|
||||
)
|
||||
|
||||
type CandidateLease struct {
|
||||
SchemaVersion int `json:"schema_version"`
|
||||
Service string `json:"service"`
|
||||
OperationID string `json:"operation_id"`
|
||||
Release string `json:"release"`
|
||||
Unit string `json:"unit"`
|
||||
Address string `json:"address"`
|
||||
StartedAt string `json:"started_at"`
|
||||
}
|
||||
|
||||
func CandidateLeasePath(statePath string) string { return statePath + ".candidate-lease.json" }
|
||||
|
||||
func (l CandidateLease) Validate(root, service string) error {
|
||||
if l.SchemaVersion != CandidateLeaseSchemaVersion {
|
||||
return errors.New("candidate lease schema version is unsupported")
|
||||
}
|
||||
if !leaseServicePattern.MatchString(service) || l.Service != service {
|
||||
return errors.New("candidate lease service does not match configuration")
|
||||
}
|
||||
if !leaseOperationPattern.MatchString(l.OperationID) {
|
||||
return errors.New("candidate lease operation ID is invalid")
|
||||
}
|
||||
if err := releaseBelow(root, l.Release); err != nil {
|
||||
return fmt.Errorf("candidate lease release: %w", err)
|
||||
}
|
||||
expectedUnit := service + "-tend-candidate-" + l.OperationID[:12] + ".service"
|
||||
if l.Unit != expectedUnit {
|
||||
return errors.New("candidate lease unit does not match its operation")
|
||||
}
|
||||
address, err := netip.ParseAddrPort(l.Address)
|
||||
if err != nil || !address.Addr().IsLoopback() || address.Port() == 0 {
|
||||
return errors.New("candidate lease address is invalid")
|
||||
}
|
||||
if _, err := time.Parse(time.RFC3339, l.StartedAt); err != nil {
|
||||
return errors.New("candidate lease timestamp is invalid")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func LoadCandidateLease(path, root, service string) (CandidateLease, error) {
|
||||
info, err := os.Lstat(path)
|
||||
if err != nil {
|
||||
return CandidateLease{}, err
|
||||
}
|
||||
if !info.Mode().IsRegular() || info.Mode()&os.ModeSymlink != 0 || info.Size() > 64<<10 {
|
||||
return CandidateLease{}, errors.New("candidate lease must be a bounded regular file")
|
||||
}
|
||||
body, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return CandidateLease{}, err
|
||||
}
|
||||
decoder := json.NewDecoder(bytes.NewReader(body))
|
||||
decoder.DisallowUnknownFields()
|
||||
var lease CandidateLease
|
||||
if err := decoder.Decode(&lease); err != nil {
|
||||
return CandidateLease{}, fmt.Errorf("decode candidate lease: %w", err)
|
||||
}
|
||||
var extra any
|
||||
if err := decoder.Decode(&extra); !errors.Is(err, io.EOF) {
|
||||
return CandidateLease{}, errors.New("candidate lease contains trailing data")
|
||||
}
|
||||
if err := lease.Validate(root, service); err != nil {
|
||||
return CandidateLease{}, err
|
||||
}
|
||||
return lease, nil
|
||||
}
|
||||
|
||||
func StoreCandidateLease(path, root string, lease CandidateLease) error {
|
||||
if err := lease.Validate(root, lease.Service); err != nil {
|
||||
return err
|
||||
}
|
||||
if info, err := os.Lstat(path); err == nil && (!info.Mode().IsRegular() || info.Mode()&os.ModeSymlink != 0) {
|
||||
return errors.New("candidate lease path must be a regular file, not a symlink")
|
||||
} else if err != nil && !os.IsNotExist(err) {
|
||||
return err
|
||||
}
|
||||
body, err := json.MarshalIndent(lease, "", " ")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
body = append(body, '\n')
|
||||
dir := filepath.Dir(path)
|
||||
if err := os.MkdirAll(dir, 0o755); err != nil {
|
||||
return err
|
||||
}
|
||||
temporary, err := os.CreateTemp(dir, ".tend-candidate-lease-")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
name := temporary.Name()
|
||||
complete := false
|
||||
defer func() {
|
||||
_ = temporary.Close()
|
||||
if !complete {
|
||||
_ = os.Remove(name)
|
||||
}
|
||||
}()
|
||||
if err := temporary.Chmod(0o644); err != nil {
|
||||
return err
|
||||
}
|
||||
if _, err := temporary.Write(body); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := temporary.Sync(); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := temporary.Close(); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := os.Rename(name, path); err != nil {
|
||||
return err
|
||||
}
|
||||
complete = true
|
||||
return syncDir(dir)
|
||||
}
|
||||
|
||||
func RemoveCandidateLease(path string) error {
|
||||
info, err := os.Lstat(path)
|
||||
if os.IsNotExist(err) {
|
||||
return nil
|
||||
}
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if !info.Mode().IsRegular() || info.Mode()&os.ModeSymlink != 0 {
|
||||
return errors.New("candidate lease path must be a regular file, not a symlink")
|
||||
}
|
||||
if err := os.Remove(path); err != nil {
|
||||
return err
|
||||
}
|
||||
return syncDir(filepath.Dir(path))
|
||||
}
|
||||
@@ -0,0 +1,89 @@
|
||||
// SPDX-License-Identifier: AGPL-3.0-only
|
||||
|
||||
package state
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
func TestCandidateLeaseRoundTripAndRemoval(t *testing.T) {
|
||||
root := filepath.Join(t.TempDir(), "service")
|
||||
release := filepath.Join(root, "releases", "sha256-"+strings.Repeat("a", 64))
|
||||
if err := os.MkdirAll(release, 0o755); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
path := CandidateLeasePath(filepath.Join(root, "state.json"))
|
||||
operation := strings.Repeat("d", 32)
|
||||
lease := CandidateLease{SchemaVersion: CandidateLeaseSchemaVersion, Service: "example-site", OperationID: operation, Release: release, Unit: "example-site-tend-candidate-" + operation[:12] + ".service", Address: "127.0.0.1:18092", StartedAt: time.Unix(1, 0).UTC().Format(time.RFC3339)}
|
||||
if err := StoreCandidateLease(path, root, lease); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
loaded, err := LoadCandidateLease(path, root, "example-site")
|
||||
if err != nil || loaded != lease {
|
||||
t.Fatalf("loaded=%+v err=%v", loaded, err)
|
||||
}
|
||||
if err := RemoveCandidateLease(path); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if _, err := os.Lstat(path); !os.IsNotExist(err) {
|
||||
t.Fatalf("lease remains: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestCandidateLeaseRejectsCrossServiceAndSymlink(t *testing.T) {
|
||||
root := filepath.Join(t.TempDir(), "service")
|
||||
release := filepath.Join(root, "releases", "sha256-"+strings.Repeat("a", 64))
|
||||
if err := os.MkdirAll(release, 0o755); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
operation := strings.Repeat("d", 32)
|
||||
lease := CandidateLease{SchemaVersion: CandidateLeaseSchemaVersion, Service: "example-site", OperationID: operation, Release: release, Unit: "example-site-tend-candidate-" + operation[:12] + ".service", Address: "127.0.0.1:18092", StartedAt: time.Unix(1, 0).UTC().Format(time.RFC3339)}
|
||||
if err := lease.Validate(root, "other-site"); err == nil {
|
||||
t.Fatal("expected service mismatch")
|
||||
}
|
||||
path := CandidateLeasePath(filepath.Join(root, "state.json"))
|
||||
if err := os.Symlink(filepath.Join(root, "elsewhere"), path); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := StoreCandidateLease(path, root, lease); err == nil {
|
||||
t.Fatal("expected symlink refusal")
|
||||
}
|
||||
if err := RemoveCandidateLease(path); err == nil {
|
||||
t.Fatal("expected symlink removal refusal")
|
||||
}
|
||||
}
|
||||
|
||||
func TestCandidateLeasePreservesSchemaOneDeploymentState(t *testing.T) {
|
||||
root := filepath.Join(t.TempDir(), "service")
|
||||
release := filepath.Join(root, "releases", "sha256-"+strings.Repeat("a", 64))
|
||||
if err := os.MkdirAll(release, 0o755); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
at := time.Unix(1, 0).UTC().Format(time.RFC3339)
|
||||
statePath := filepath.Join(root, "state.json")
|
||||
record := Record{SchemaVersion: SchemaVersion, Strategy: "singleton_candidate", DesiredRelease: release, CandidateRelease: release, ActiveSlot: "singleton", ActiveRelease: release, LastAttemptRelease: release, LastAttemptOutcome: "running", LastAttemptAt: at, UpdatedAt: at}
|
||||
if err := Store(statePath, root, record); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
operation := strings.Repeat("d", 32)
|
||||
lease := CandidateLease{SchemaVersion: CandidateLeaseSchemaVersion, Service: "example-site", OperationID: operation, Release: release, Unit: "example-site-tend-candidate-" + operation[:12] + ".service", Address: "127.0.0.1:18092", StartedAt: at}
|
||||
if err := StoreCandidateLease(CandidateLeasePath(statePath), root, lease); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
body, err := os.ReadFile(statePath)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !bytes.Contains(body, []byte(`"schema_version": 1`)) || bytes.Contains(body, []byte("candidate_operation_id")) || bytes.Contains(body, []byte("candidate_unit")) {
|
||||
t.Fatalf("deployment state contract changed: %s", body)
|
||||
}
|
||||
loaded, err := Load(statePath, root, "singleton_candidate")
|
||||
if err != nil || loaded.SchemaVersion != 1 || loaded.CandidateRelease != release {
|
||||
t.Fatalf("loaded=%+v err=%v", loaded, err)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,172 @@
|
||||
// SPDX-License-Identifier: AGPL-3.0-only
|
||||
|
||||
package state
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"io"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
const SchemaVersion = 1
|
||||
|
||||
type Record struct {
|
||||
SchemaVersion int `json:"schema_version"`
|
||||
Strategy string `json:"strategy"`
|
||||
DesiredRelease string `json:"desired_release,omitempty"`
|
||||
CandidateRelease string `json:"candidate_release,omitempty"`
|
||||
ActiveSlot string `json:"active_slot"`
|
||||
ActiveRelease string `json:"active_release"`
|
||||
PreviousSlot string `json:"previous_slot,omitempty"`
|
||||
PreviousRelease string `json:"previous_release,omitempty"`
|
||||
LastAttemptRelease string `json:"last_attempt_release,omitempty"`
|
||||
LastAttemptOutcome string `json:"last_attempt_outcome,omitempty"`
|
||||
LastAttemptAt string `json:"last_attempt_at,omitempty"`
|
||||
UpdatedAt string `json:"updated_at"`
|
||||
}
|
||||
|
||||
func Load(path, root, strategy string) (Record, error) {
|
||||
b, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return Record{}, err
|
||||
}
|
||||
dec := json.NewDecoder(bytes.NewReader(b))
|
||||
dec.DisallowUnknownFields()
|
||||
var record Record
|
||||
if err := dec.Decode(&record); err != nil {
|
||||
return Record{}, fmt.Errorf("decode state: %w", err)
|
||||
}
|
||||
var extra any
|
||||
if err := dec.Decode(&extra); !errors.Is(err, io.EOF) {
|
||||
return Record{}, errors.New("state contains trailing data")
|
||||
}
|
||||
if err := record.Validate(root, strategy); err != nil {
|
||||
return Record{}, err
|
||||
}
|
||||
return record, nil
|
||||
}
|
||||
|
||||
func (r Record) Validate(root, strategy string) error {
|
||||
if r.SchemaVersion != SchemaVersion {
|
||||
return errors.New("state schema version is unsupported")
|
||||
}
|
||||
if r.Strategy != strategy {
|
||||
return errors.New("state strategy does not match configuration")
|
||||
}
|
||||
if strategy == "blue_green" && (r.ActiveSlot != "blue" && r.ActiveSlot != "green") {
|
||||
return errors.New("active slot is invalid")
|
||||
}
|
||||
if strategy == "singleton_candidate" && r.ActiveSlot != "singleton" {
|
||||
return errors.New("singleton state slot is invalid")
|
||||
}
|
||||
if err := releaseBelow(root, r.ActiveRelease); err != nil {
|
||||
return fmt.Errorf("active release: %w", err)
|
||||
}
|
||||
if r.PreviousRelease != "" {
|
||||
if err := releaseBelow(root, r.PreviousRelease); err != nil {
|
||||
return fmt.Errorf("previous release: %w", err)
|
||||
}
|
||||
}
|
||||
for label, release := range map[string]string{"desired release": r.DesiredRelease, "candidate release": r.CandidateRelease, "last attempt release": r.LastAttemptRelease} {
|
||||
if release != "" {
|
||||
if err := releaseBelow(root, release); err != nil {
|
||||
return fmt.Errorf("%s: %w", label, err)
|
||||
}
|
||||
}
|
||||
}
|
||||
if r.LastAttemptOutcome != "" {
|
||||
switch r.LastAttemptOutcome {
|
||||
case "running", "succeeded", "failed", "rolled_back":
|
||||
default:
|
||||
return errors.New("last attempt outcome is invalid")
|
||||
}
|
||||
if _, err := time.Parse(time.RFC3339, r.LastAttemptAt); err != nil {
|
||||
return errors.New("last attempt timestamp is invalid")
|
||||
}
|
||||
}
|
||||
if r.LastAttemptOutcome == "running" && r.CandidateRelease == "" {
|
||||
return errors.New("running attempt requires a candidate release")
|
||||
}
|
||||
if strategy == "blue_green" && r.PreviousRelease != "" && r.PreviousSlot == r.ActiveSlot {
|
||||
return errors.New("previous slot must differ from active slot")
|
||||
}
|
||||
if _, err := time.Parse(time.RFC3339, r.UpdatedAt); err != nil {
|
||||
return errors.New("state timestamp is invalid")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func Store(path, root string, record Record) error {
|
||||
if err := record.Validate(root, record.Strategy); err != nil {
|
||||
return err
|
||||
}
|
||||
if info, err := os.Lstat(path); err == nil && info.Mode()&os.ModeSymlink != 0 {
|
||||
return errors.New("state file must not be a symlink")
|
||||
} else if err != nil && !os.IsNotExist(err) {
|
||||
return err
|
||||
}
|
||||
b, err := json.MarshalIndent(record, "", " ")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
b = append(b, '\n')
|
||||
dir := filepath.Dir(path)
|
||||
if err := os.MkdirAll(dir, 0o755); err != nil {
|
||||
return err
|
||||
}
|
||||
tmp, err := os.CreateTemp(dir, ".tend-state-")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
name := tmp.Name()
|
||||
ok := false
|
||||
defer func() {
|
||||
_ = tmp.Close()
|
||||
if !ok {
|
||||
_ = os.Remove(name)
|
||||
}
|
||||
}()
|
||||
if err := tmp.Chmod(0o644); err != nil {
|
||||
return err
|
||||
}
|
||||
if _, err := tmp.Write(b); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := tmp.Sync(); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := tmp.Close(); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := os.Rename(name, path); err != nil {
|
||||
return err
|
||||
}
|
||||
ok = true
|
||||
return syncDir(dir)
|
||||
}
|
||||
|
||||
func releaseBelow(root, path string) error {
|
||||
if !filepath.IsAbs(path) || filepath.Clean(path) != path {
|
||||
return errors.New("must be a clean absolute path")
|
||||
}
|
||||
releases := filepath.Join(root, "releases")
|
||||
rel, err := filepath.Rel(releases, path)
|
||||
if err != nil || rel == "." || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) || strings.ContainsRune(rel, filepath.Separator) {
|
||||
return errors.New("must be one direct child of the release directory")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
func syncDir(path string) error {
|
||||
dir, err := os.Open(path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
defer dir.Close()
|
||||
return dir.Sync()
|
||||
}
|
||||
@@ -0,0 +1,55 @@
|
||||
// SPDX-License-Identifier: AGPL-3.0-only
|
||||
|
||||
package state
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
func TestStoreLoadRoundTripAndRejectSymlink(t *testing.T) {
|
||||
root := filepath.Join(t.TempDir(), "service")
|
||||
release := filepath.Join(root, "releases", "sha256-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
|
||||
if err := os.MkdirAll(release, 0o755); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
path := filepath.Join(root, "state.json")
|
||||
at := time.Unix(1, 0).UTC().Format(time.RFC3339)
|
||||
record := Record{SchemaVersion: SchemaVersion, Strategy: "singleton_candidate", DesiredRelease: release, ActiveSlot: "singleton", ActiveRelease: release, LastAttemptRelease: release, LastAttemptOutcome: "succeeded", LastAttemptAt: at, UpdatedAt: at}
|
||||
if err := Store(path, root, record); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
loaded, err := Load(path, root, "singleton_candidate")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if loaded.ActiveRelease != release || loaded.DesiredRelease != release || loaded.LastAttemptOutcome != "succeeded" {
|
||||
t.Fatalf("state=%+v", loaded)
|
||||
}
|
||||
if err := os.Remove(path); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := os.Symlink(filepath.Join(root, "elsewhere"), path); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := Store(path, root, record); err == nil {
|
||||
t.Fatal("expected symlink refusal")
|
||||
}
|
||||
}
|
||||
|
||||
func TestRecordRequiresCandidateForRunningAttempt(t *testing.T) {
|
||||
root := filepath.Join(t.TempDir(), "service")
|
||||
release := filepath.Join(root, "releases", "sha256-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
|
||||
record := Record{SchemaVersion: SchemaVersion, Strategy: "singleton_candidate", DesiredRelease: release, ActiveSlot: "singleton", ActiveRelease: release, LastAttemptRelease: release, LastAttemptOutcome: "running", LastAttemptAt: time.Unix(1, 0).UTC().Format(time.RFC3339), UpdatedAt: time.Unix(1, 0).UTC().Format(time.RFC3339)}
|
||||
if err := record.Validate(root, "singleton_candidate"); err == nil {
|
||||
t.Fatal("expected missing candidate rejection")
|
||||
}
|
||||
}
|
||||
func TestRecordRejectsReleaseOutsideRoot(t *testing.T) {
|
||||
record := Record{SchemaVersion: SchemaVersion, Strategy: "singleton_candidate", ActiveSlot: "singleton", ActiveRelease: "/tmp/other/release", UpdatedAt: time.Unix(1, 0).UTC().Format(time.RFC3339)}
|
||||
if err := record.Validate("/opt/example", "singleton_candidate"); err == nil {
|
||||
t.Fatal("expected path refusal")
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user