Refactor architecture into eight components and consolidate reliability work
Build and publish container images / images (push) Successful in 9m34s
Release container images / release (push) Successful in 36s

Extract Grammaratur, Dregarnuhr, Geduldh, Mestionora, Ordoschnellic, Schutzaria, Kunstzeal and Seheweit behind compatible application contracts.

Include accumulated editor resilience, navigation and theme UX, remote CLI, storage/schema and DR groundwork, tests and design/operations documentation.

Verified: uncached full Go suite; go vet ./...; race tests for all eight components; 11 targeted Chromium tests; Node suites; 19 Python CLI tests; reproducible editor build. No push, release tag or deployment in this checkpoint.
This commit is contained in:
Anya Tokugawa committed 2026-11-01 15:23:31 +09:00
1 parent 9dd425f765
commit d5d21b7841
302 files changed
+20037 -3492

No files matched your search

+294
View File
@@ -0,0 +1,294 @@
package dr
import (
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"os"
"path/filepath"
"testing"
"time"
"pageswiki/internal/db"
)
func fixture(t *testing.T) string {
t.Helper()
root := t.TempDir()
database, err := db.Open(filepath.Join(root, "pages.db"))
if err != nil {
t.Fatal(err)
}
if _, err = database.Exec("CREATE TABLE revisions(document_hash TEXT); INSERT INTO revisions(rowid,document_hash) VALUES(42,'')"); err != nil {
t.Fatal(err)
}
if err = database.Close(); err != nil {
t.Fatal(err)
}
if _, err = Init(root); err != nil {
t.Fatal(err)
}
if err = os.WriteFile(filepath.Join(root, "auth.key"), make([]byte, 32), 0600); err != nil {
t.Fatal(err)
}
return root
}
func TestSnapshotRestorePromote(t *testing.T) {
root := fixture(t)
ctx := context.Background()
dest := filepath.Join(t.TempDir(), "snapshot")
body := []byte("synthetic DR test document")
sum := sha256.Sum256(body)
hash := hex.EncodeToString(sum[:])
path := filepath.Join(root, "documents", "sha256", hash[:2], hash)
if err := os.MkdirAll(filepath.Dir(path), 0700); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(path, body, 0600); err != nil {
t.Fatal(err)
}
database, err := db.Open(filepath.Join(root, "pages.db"))
if err != nil {
t.Fatal(err)
}
// Hold a connection open to keep committed WAL pages present. No writer is
// active during snapshot; this covers recovery after an uncheckpointed stop.
if _, err = database.Exec("PRAGMA wal_autocheckpoint=0; UPDATE revisions SET document_hash=? WHERE rowid=42", hash); err != nil {
t.Fatal(err)
}
defer database.Close()
if err = os.MkdirAll(filepath.Join(root, "previews"), 0700); err != nil {
t.Fatal(err)
}
os.WriteFile(filepath.Join(root, "previews", "ignored"), []byte("cache"), 0600)
m, digest, err := Snapshot(ctx, root, dest)
if err != nil {
t.Fatal(err)
}
if _, err = Verify(ctx, dest, digest); err != nil {
t.Fatal(err)
}
if _, err = Verify(ctx, dest, digest); err != nil {
t.Fatalf("verification must not mutate snapshot: %v", err)
}
restored := filepath.Join(t.TempDir(), "standby")
node, err := Restore(ctx, dest, digest, restored)
if err != nil {
t.Fatal(err)
}
if node.Role != "standby" || node.NodeID == node.PrimaryNodeID || node.SnapshotID != m.ID || !node.Readable(time.Now()) {
t.Fatalf("bad standby: %+v", node)
}
if _, err = os.Stat(filepath.Join(restored, "previews")); !os.IsNotExist(err) {
t.Fatal("copied cache")
}
ro, err := db.OpenReadOnly(filepath.Join(restored, "pages.db"))
if err != nil {
t.Fatal(err)
}
defer ro.Close()
var got string
if err = ro.QueryRow("SELECT document_hash FROM revisions WHERE rowid=42").Scan(&got); err != nil || got != hash {
t.Fatalf("WAL or rowid lost: %s %v", got, err)
}
if _, err = ro.Exec("DELETE FROM revisions"); err == nil {
t.Fatal("standby accepted write")
}
shared, err := Lock(restored, false)
if err != nil {
t.Fatal(err)
}
if _, err = Promote(restored, node.PrimaryNodeID, "test fence", true); err == nil {
t.Fatal("promoted running standby")
}
shared.Close()
if _, err = Promote(restored, "wrong", "test fence", true); err == nil {
t.Fatal("accepted wrong primary")
}
if _, err = Promote(restored, node.PrimaryNodeID, "test fence", false); err == nil {
t.Fatal("accepted implicit data loss")
}
promoted, err := Promote(restored, node.PrimaryNodeID, "test fence", true)
if err != nil {
t.Fatal(err)
}
if promoted.Role != "primary" || promoted.Epoch != node.Epoch+1 || len(promoted.History) != 1 {
t.Fatalf("bad promotion: %+v", promoted)
}
if promoted.WorkersEnabled {
t.Fatal("promotion replayed jobs without review")
}
if _, err = ResumeWorkers(restored, false); err == nil {
t.Fatal("resumed jobs without review")
}
resumed, err := ResumeWorkers(restored, true)
if err != nil {
t.Fatal(err)
}
if !resumed.WorkersEnabled || resumed.WorkersResumedAt.IsZero() {
t.Fatal("worker resumption not audited")
}
if _, err = Restore(ctx, dest, digest, restored); err == nil {
t.Fatal("overwrote existing restore")
}
}
func TestSnapshotCalendarReferencesAndRestoreSafety(t *testing.T) {
root := fixture(t)
dir := filepath.Join(root, "documents", "calendars", "synthetic-domain", "synthetic-calendar")
if err := os.MkdirAll(dir, 0700); err != nil {
t.Fatal(err)
}
body := []byte("synthetic opaque monthly generation; no external calendar data")
sum := sha256.Sum256(body)
hash := hex.EncodeToString(sum[:])
metadata, _ := json.Marshal(map[string]any{"months": map[string]string{"2026-09": hash}})
if err := os.WriteFile(filepath.Join(dir, "calendar.json"), metadata, 0600); err != nil {
t.Fatal(err)
}
dest := filepath.Join(t.TempDir(), "snapshot")
if _, _, err := Snapshot(context.Background(), root, dest); err == nil {
t.Fatal("accepted missing calendar month")
}
if err := os.WriteFile(filepath.Join(dir, "2026-09."+hash+".ics"), body, 0600); err != nil {
t.Fatal(err)
}
_, digest, err := Snapshot(context.Background(), root, dest)
if err != nil {
t.Fatal(err)
}
if _, err = Verify(context.Background(), dest, digest); err != nil {
t.Fatal(err)
}
if _, _, err = Snapshot(context.Background(), root, filepath.Join(root, "inside")); err == nil {
t.Fatal("snapshot inside source accepted")
}
if _, err = Restore(context.Background(), dest, digest, root); err == nil {
t.Fatal("restore overwrote existing data")
}
if _, err = Restore(context.Background(), dest, digest, filepath.Join(dest, "nested")); err == nil {
t.Fatal("restore corrupted source snapshot")
}
ctx, cancel := context.WithCancel(context.Background())
cancel()
if _, err = Verify(ctx, dest, digest); err == nil {
t.Fatal("verification ignored cancellation")
}
}
func TestSnapshotRefusesActiveMissingAndSymlink(t *testing.T) {
root := fixture(t)
dest := filepath.Join(t.TempDir(), "snapshot")
ctx := context.Background()
shared, err := Lock(root, false)
if err != nil {
t.Fatal(err)
}
if _, _, err = Snapshot(ctx, root, dest); err == nil {
t.Fatal("snapshotted running instance")
}
shared.Close()
database, err := db.Open(filepath.Join(root, "pages.db"))
if err != nil {
t.Fatal(err)
}
_, err = database.Exec("UPDATE revisions SET document_hash=?", string(make([]byte, 64)))
if err != nil {
t.Fatal(err)
}
database.Close()
if _, _, err = Snapshot(ctx, root, dest); err == nil {
t.Fatal("accepted missing canonical document")
}
if _, err = os.Stat(dest); !os.IsNotExist(err) {
t.Fatal("published failed snapshot")
}
if err = os.Symlink(t.TempDir(), filepath.Join(root, "themes")); err != nil {
t.Fatal(err)
}
if _, _, err = Snapshot(ctx, root, dest); err == nil {
t.Fatal("followed source symlink")
}
}
func TestSnapshotTamperAndPathValidation(t *testing.T) {
root := fixture(t)
dest := filepath.Join(t.TempDir(), "snapshot")
ctx := context.Background()
_, digest, err := Snapshot(ctx, root, dest)
if err != nil {
t.Fatal(err)
}
if _, err = Verify(ctx, dest, ""); err == nil {
t.Fatal("accepted unauthenticated manifest")
}
manifestPath := filepath.Join(dest, "manifest.json")
encoded, err := os.ReadFile(manifestPath)
if err != nil {
t.Fatal(err)
}
var m Manifest
if err = json.Unmarshal(encoded, &m); err != nil {
t.Fatal(err)
}
m.Files[0].Path = "../outside"
altered, _ := json.Marshal(m)
sum := sha256.Sum256(altered)
os.WriteFile(manifestPath, altered, 0600)
if _, err = Verify(ctx, dest, digest); err == nil {
t.Fatal("accepted changed manifest")
}
if _, err = Verify(ctx, dest, hex.EncodeToString(sum[:])); err == nil {
t.Fatal("accepted traversal even with matching manifest digest")
}
os.WriteFile(manifestPath, encoded, 0600)
os.WriteFile(filepath.Join(dest, "data", "auth.key"), []byte("tampered"), 0600)
if _, err = Verify(ctx, dest, digest); err == nil {
t.Fatal("accepted payload tamper")
}
for _, path := range []string{"/etc/passwd", "documents/../auth.key", "documents\\foo", "dr-node.json", "pages.db-wal", "cache/foo"} {
if canonical(path) {
t.Errorf("accepted %q", path)
}
}
}
func TestConfigFailsClosedAndExpiry(t *testing.T) {
root := fixture(t)
c, err := Load(root)
if err != nil {
t.Fatal(err)
}
c.Role = "standby"
if err = Save(root, *c); err == nil {
t.Fatal("accepted inconsistent role")
}
os.WriteFile(filepath.Join(root, ConfigFile), []byte(`{"role":"broken"}`), 0600)
if _, err = Load(root); err == nil {
t.Fatal("invalid config accepted")
}
c.Role = "standby"
c.CapturedAt = time.Now().Add(-2 * time.Hour)
c.MaxReadAgeSeconds = 3600
if c.Readable(time.Now()) {
t.Fatal("stale snapshot is readable")
}
c.CapturedAt = time.Now().Add(time.Hour)
if c.Readable(time.Now()) {
t.Fatal("future snapshot is readable")
}
if err = RequireRole(nil, "standby"); err == nil {
t.Fatal("empty standby volume would start writable")
}
if err = RequireRole(c, "primary"); err == nil {
t.Fatal("mismatched deployment role accepted")
}
if err = RequireRole(c, "standby"); err != nil {
t.Fatal(err)
}
if err = RequireRole(nil, ""); err != nil {
t.Fatal("legacy startup broken")
}
}
+70
View File
@@ -0,0 +1,70 @@
package dr
import (
"bytes"
"context"
"crypto/sha256"
"encoding/hex"
"io"
"os"
"path/filepath"
"testing"
"pageswiki/internal/db"
"pageswiki/internal/geduldh"
)
func TestGeduldhSnapshotRestoreCompatibility(t *testing.T) {
root := fixture(t)
documents := filepath.Join(root, "documents")
if err := os.MkdirAll(documents, 0755); err != nil {
t.Fatal(err)
}
backend, err := geduldh.NewLocal(documents)
if err != nil {
t.Fatal(err)
}
ctx := context.Background()
body := []byte("Geduldh DR compatibility 日本語\x00\xff")
sum := sha256.Sum256(body)
hash := hex.EncodeToString(sum[:])
if err := backend.PutIfAbsent(ctx, hash, int64(len(body)), bytes.NewReader(body)); err != nil {
t.Fatal(err)
}
database, err := db.Open(filepath.Join(root, "pages.db"))
if err != nil {
t.Fatal(err)
}
defer database.Close()
if _, err := database.Exec(`UPDATE revisions SET document_hash=? WHERE rowid=42`, hash); err != nil {
t.Fatal(err)
}
snapshot := filepath.Join(t.TempDir(), "snapshot")
_, digest, err := Snapshot(ctx, root, snapshot)
if err != nil {
t.Fatal(err)
}
if _, err := Verify(ctx, snapshot, digest); err != nil {
t.Fatal(err)
}
restored := filepath.Join(t.TempDir(), "standby")
if _, err := Restore(ctx, snapshot, digest, restored); err != nil {
t.Fatal(err)
}
recovered, err := geduldh.NewLocal(filepath.Join(restored, "documents"))
if err != nil {
t.Fatal(err)
}
if err := recovered.Verify(ctx, hash); err != nil {
t.Fatal(err)
}
reader, err := recovered.Open(ctx, hash)
if err != nil {
t.Fatal(err)
}
defer reader.Close()
data, err := io.ReadAll(reader)
if err != nil || !bytes.Equal(data, body) {
t.Fatalf("restored payload changed: %v", err)
}
}
+273
View File
@@ -0,0 +1,273 @@
// Package dr implements offline, operator-fenced recovery, not leader election.
package dr
import (
"encoding/json"
"errors"
"fmt"
"io"
"os"
"path/filepath"
"strings"
"syscall"
"time"
"github.com/google/uuid"
)
const ConfigFile = "dr-node.json"
const LockFile = ".pageswiki-instance.lock"
// RequireRole is an optional deployment guard against mounting an empty/wrong
// data volume on a DR host and accidentally starting a new writable instance.
func RequireRole(c *Config, expected string) error {
if expected == "" {
return nil
}
if expected != "primary" && expected != "standby" {
return errors.New("PAGESWIKI_DR_EXPECT_ROLE must be primary or standby")
}
if c == nil || c.Role != expected {
return errors.New("DR role does not match PAGESWIKI_DR_EXPECT_ROLE; refusing startup")
}
return nil
}
type Promotion struct {
At time.Time `json:"at"`
PreviousNode string `json:"previous_node"`
FenceReference string `json:"fence_reference"`
SnapshotID string `json:"snapshot_id"`
Epoch uint64 `json:"epoch"`
}
// Config is node-local and MUST NOT be overwritten by a primary's snapshot.
// Epoch is an audit generation only; it is NOT a distributed fencing token.
type Config struct {
Version int `json:"version"`
ClusterID string `json:"cluster_id"`
NodeID string `json:"node_id"`
PrimaryNodeID string `json:"primary_node_id"`
Role string `json:"role"`
Epoch uint64 `json:"epoch"`
SnapshotID string `json:"snapshot_id,omitempty"`
CapturedAt time.Time `json:"captured_at,omitempty"`
MaxReadAgeSeconds int64 `json:"max_read_age_seconds"`
WorkersEnabled bool `json:"workers_enabled"`
WorkersResumedAt time.Time `json:"workers_resumed_at,omitempty"`
History []Promotion `json:"promotion_history,omitempty"`
}
func (c Config) Validate() error {
for _, id := range []string{c.ClusterID, c.NodeID, c.PrimaryNodeID} {
u, err := uuid.Parse(id)
if err != nil || u == uuid.Nil || u.String() != id {
return errors.New("DR identity must be a canonical nonzero UUID")
}
}
if c.Version != 1 || c.Epoch == 0 || c.MaxReadAgeSeconds < 1 || c.MaxReadAgeSeconds > 86400 {
return errors.New("invalid DR version, epoch or max_read_age_seconds (1..86400)")
}
if c.Role != "primary" && c.Role != "standby" {
return errors.New("DR role must be primary or standby")
}
if (c.Role == "primary") != (c.PrimaryNodeID == c.NodeID) {
return errors.New("DR role and primary identity disagree")
}
if c.Role == "standby" && (c.SnapshotID == "" || c.CapturedAt.IsZero()) {
return errors.New("standby requires a verified snapshot")
}
if c.Role == "standby" && c.WorkersEnabled {
return errors.New("standby cannot enable background workers")
}
if c.SnapshotID != "" {
u, err := uuid.Parse(c.SnapshotID)
if err != nil || u == uuid.Nil || u.String() != c.SnapshotID {
return errors.New("invalid snapshot identity")
}
}
return nil
}
func (c Config) Readable(now time.Time) bool {
return c.Role == "standby" && !c.CapturedAt.After(now.Add(time.Minute)) && now.Sub(c.CapturedAt) <= time.Duration(c.MaxReadAgeSeconds)*time.Second
}
func (c Config) ReadUntil() time.Time {
if c.CapturedAt.After(time.Now().Add(time.Minute)) {
return time.Time{}
}
return c.CapturedAt.Add(time.Duration(c.MaxReadAgeSeconds) * time.Second)
}
func Load(dataDir string) (*Config, error) {
f, err := os.Open(filepath.Join(dataDir, ConfigFile))
if errors.Is(err, os.ErrNotExist) {
return nil, nil
}
if err != nil {
return nil, err
}
defer f.Close()
info, err := f.Stat()
if err != nil {
return nil, err
}
if !info.Mode().IsRegular() || info.Size() > 1<<20 {
return nil, errors.New("invalid or oversized DR configuration")
}
var c Config
d := json.NewDecoder(io.LimitReader(f, 1<<20))
d.DisallowUnknownFields()
if err = d.Decode(&c); err != nil {
return nil, err
}
if err = d.Decode(new(any)); err != io.EOF {
return nil, errors.New("trailing DR configuration data")
}
return &c, c.Validate()
}
func Save(dataDir string, c Config) error {
if err := c.Validate(); err != nil {
return err
}
b, err := json.MarshalIndent(c, "", " ")
if err != nil {
return err
}
f, err := os.CreateTemp(dataDir, ".dr-node-")
if err != nil {
return err
}
defer os.Remove(f.Name())
if _, err = f.Write(append(b, '\n')); err != nil {
f.Close()
return err
}
if err = f.Sync(); err != nil {
f.Close()
return err
}
if err = f.Close(); err != nil {
return err
}
if err = os.Rename(f.Name(), filepath.Join(dataDir, ConfigFile)); err != nil {
return err
}
return syncDir(dataDir)
}
// Lock is shared for a running server/CLI, exclusive for offline maintenance.
// Advisory locking cannot fence older binaries or an independent SQLite client.
func Lock(dataDir string, exclusive bool) (*os.File, error) {
// Shared locks also work with a read-only standby mount.
path := filepath.Join(dataDir, LockFile)
f, err := os.Open(path)
if exclusive || errors.Is(err, os.ErrNotExist) {
if f != nil {
f.Close()
}
f, err = os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0600)
}
if err != nil {
return nil, err
}
mode := syscall.LOCK_SH
if exclusive {
mode = syscall.LOCK_EX
}
if err = syscall.Flock(int(f.Fd()), mode|syscall.LOCK_NB); err != nil {
f.Close()
return nil, fmt.Errorf("DR data directory is in use; stop all writers/readers before maintenance: %w", err)
}
return f, nil
}
func Init(dataDir string) (*Config, error) {
l, err := Lock(dataDir, true)
if err != nil {
return nil, err
}
defer l.Close()
if c, err := Load(dataDir); err != nil || c != nil {
return nil, errors.New("DR configuration exists or cannot be read; refusing initialization")
}
id := uuid.NewString()
c := Config{Version: 1, ClusterID: uuid.NewString(), NodeID: id, PrimaryNodeID: id, Role: "primary", Epoch: 1, MaxReadAgeSeconds: 3600, WorkersEnabled: true}
return &c, Save(dataDir, c)
}
// Promote records an operator's fencing attestation. It does not contact,
// power off, or independently verify the former primary. No automatic promotion.
func Promote(dataDir, fencedNode, reference string, acceptLoss bool) (*Config, error) {
l, err := Lock(dataDir, true)
if err != nil {
return nil, err
}
defer l.Close()
c, err := Load(dataDir)
if err != nil {
return nil, err
}
if c == nil || c.Role != "standby" {
return nil, errors.New("only an offline standby can be promoted")
}
if err = checkAuthKey(dataDir); err != nil {
return nil, err
}
if fencedNode != c.PrimaryNodeID || !acceptLoss || len(strings.TrimSpace(reference)) < 4 || len(reference) > 1024 {
return nil, errors.New("promotion requires exact former primary ID, fencing reference and explicit acceptance of snapshot data loss")
}
if c.Epoch == ^uint64(0) {
return nil, errors.New("DR epoch exhausted")
}
c.Epoch++
c.History = append(c.History, Promotion{At: time.Now().UTC(), PreviousNode: fencedNode, FenceReference: strings.TrimSpace(reference), SnapshotID: c.SnapshotID, Epoch: c.Epoch})
c.Role, c.PrimaryNodeID = "primary", c.NodeID
// Replaying pre-snapshot jobs can duplicate notifications or external writes.
// Resume them only after an operator reviews the restored queue.
c.WorkersEnabled = false
return c, Save(dataDir, *c)
}
func checkAuthKey(dataDir string) error {
if strings.TrimSpace(os.Getenv("PAGESWIKI_AUTH_KEY")) != "" {
return nil
}
key, err := os.ReadFile(filepath.Join(dataDir, "auth.key"))
if err != nil || len(key) != 32 {
return errors.New("original auth.key or PAGESWIKI_AUTH_KEY is required; refusing implicit key regeneration")
}
return nil
}
func ResumeWorkers(dataDir string, reviewed bool) (*Config, error) {
if !reviewed {
return nil, errors.New("review restored jobs and federation state before resuming workers")
}
l, err := Lock(dataDir, true)
if err != nil {
return nil, err
}
defer l.Close()
c, err := Load(dataDir)
if err != nil {
return nil, err
}
if c == nil || c.Role != "primary" {
return nil, errors.New("only an offline primary can resume workers")
}
c.WorkersEnabled = true
c.WorkersResumedAt = time.Now().UTC()
return c, Save(dataDir, *c)
}
func syncDir(path string) error {
f, err := os.Open(path)
if err != nil {
return err
}
defer f.Close()
return f.Sync()
}
+579
View File
@@ -0,0 +1,579 @@
package dr
import (
"context"
"crypto/sha256"
"database/sql"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"io"
"io/fs"
"net/url"
"os"
"path/filepath"
"strings"
"time"
"github.com/google/uuid"
"golang.org/x/sys/unix"
"modernc.org/sqlite"
"pageswiki/internal/db"
)
type File struct {
Path string `json:"path"`
Size int64 `json:"size"`
SHA256 string `json:"sha256"`
}
type Manifest struct {
Version int `json:"version"`
ID string `json:"id"`
ClusterID string `json:"cluster_id"`
PrimaryNodeID string `json:"primary_node_id"`
Epoch uint64 `json:"epoch"`
CapturedAt time.Time `json:"captured_at"`
CompletedAt time.Time `json:"completed_at"`
Scope string `json:"scope"`
Files []File `json:"files"`
}
// Include canonical stores, auth/signing keys and managed-campus enrollment.
// Caches, temporary uploads, editor workspaces and node-local DR state are NOT
// recovery authorities. Extra mounted storage/environment secrets are external.
func canonical(path string) bool {
if !filepath.IsLocal(path) || filepath.ToSlash(path) != path || strings.Contains(path, "\\") || path != filepath.Clean(path) {
return false
}
root := strings.Split(path, "/")[0]
switch root {
case "documents", "themes", "federation":
return true
case "pages.db", "auth.key", "instance-ed25519.key":
return path == root
}
return false
}
func fileHash(path string) (File, error) {
f, err := os.Open(path)
if err != nil {
return File{}, err
}
defer f.Close()
i, err := f.Stat()
if err != nil || !i.Mode().IsRegular() {
return File{}, errors.New("snapshot entry is not a regular file")
}
h := sha256.New()
n, err := io.CopyBuffer(h, f, make([]byte, 256<<10))
return File{Size: n, SHA256: hex.EncodeToString(h.Sum(nil))}, err
}
func copyFile(source, target string) error {
i, err := os.Lstat(source)
if err != nil {
return err
}
if !i.Mode().IsRegular() {
return fmt.Errorf("refusing nonregular source: %s", source)
}
in, err := os.Open(source)
if err != nil {
return err
}
defer in.Close()
opened, err := in.Stat()
if err != nil || !os.SameFile(i, opened) {
return errors.New("source changed during snapshot")
}
if err = os.MkdirAll(filepath.Dir(target), 0700); err != nil {
return err
}
out, err := os.OpenFile(target, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0600)
if err != nil {
return err
}
_, err = io.CopyBuffer(out, in, make([]byte, 256<<10))
if err == nil {
err = out.Sync()
}
closeErr := out.Close()
if err == nil {
err = closeErr
}
return err
}
// Backup API preserves rowids (unlike VACUUM INTO) and includes committed WAL.
func backupDB(ctx context.Context, source, target string) error {
database, err := db.OpenReadOnly(source)
if err != nil {
return err
}
defer database.Close()
conn, err := database.Conn(ctx)
if err != nil {
return err
}
defer conn.Close()
err = conn.Raw(func(raw any) error {
b, err := raw.(interface {
NewBackup(string) (*sqlite.Backup, error)
}).NewBackup((&url.URL{Scheme: "file", Path: target}).String())
if err != nil {
return err
}
for {
if err = ctx.Err(); err != nil {
b.Finish()
return err
}
more, e := b.Step(256)
if e != nil {
b.Finish()
return e
}
if !more {
return b.Finish()
}
}
})
if err != nil {
return err
}
// Do not leave a WAL-mode snapshot that creates sidecars during verification.
dst, err := sql.Open("sqlite", (&url.URL{Scheme: "file", Path: target, RawQuery: "mode=rw"}).String())
if err != nil {
return err
}
_, err = dst.ExecContext(ctx, "PRAGMA journal_mode=DELETE")
closeErr := dst.Close()
if err != nil {
return err
}
if closeErr != nil {
return closeErr
}
// Finish leaves a standalone DB; fsync before publishing the generation.
f, err := os.OpenFile(target, os.O_RDWR, 0600)
if err != nil {
return err
}
defer f.Close()
if err = f.Chmod(0600); err != nil {
return err
}
return f.Sync()
}
// Snapshot requires every writer stopped, including older binaries and CLIs.
// The lock enforces this for upgraded PagesWiki processes, not arbitrary tools.
func Snapshot(ctx context.Context, dataDir, target string) (*Manifest, string, error) {
source, err := filepath.EvalSymlinks(dataDir)
if err != nil {
return nil, "", err
}
source, err = filepath.Abs(source)
if err != nil {
return nil, "", err
}
target, err = filepath.Abs(target)
if err != nil {
return nil, "", err
}
parent, err := filepath.EvalSymlinks(filepath.Dir(target))
if err != nil {
return nil, "", err
}
target = filepath.Join(parent, filepath.Base(target))
if target == source || strings.HasPrefix(target, source+string(filepath.Separator)) {
return nil, "", errors.New("snapshot destination must be outside the data directory")
}
l, err := Lock(source, true)
if err != nil {
return nil, "", err
}
defer l.Close()
c, err := Load(source)
if err != nil {
return nil, "", err
}
if c == nil || c.Role != "primary" {
return nil, "", errors.New("initialize primary DR configuration before snapshot")
}
if _, err = os.Lstat(target); !errors.Is(err, os.ErrNotExist) {
return nil, "", errors.New("snapshot destination must not exist")
}
stage, err := os.MkdirTemp(parent, ".dr-snapshot-")
if err != nil {
return nil, "", err
}
defer os.RemoveAll(stage)
m := &Manifest{Version: 1, ID: uuid.NewString(), ClusterID: c.ClusterID, PrimaryNodeID: c.NodeID, Epoch: c.Epoch, CapturedAt: time.Now().UTC(), Scope: "instance-offline-v1"}
root := filepath.Join(stage, "data")
if err = os.Mkdir(root, 0700); err != nil {
return nil, "", err
}
info, err := os.Lstat(filepath.Join(source, "pages.db"))
if err != nil {
return nil, "", err
}
if !info.Mode().IsRegular() {
return nil, "", errors.New("snapshot database must be a regular file, not a symlink")
}
if err = checkAuthKey(source); err != nil {
return nil, "", err
}
if err = backupDB(ctx, filepath.Join(source, "pages.db"), filepath.Join(root, "pages.db")); err != nil {
return nil, "", err
}
for _, name := range []string{"documents", "themes", "federation", "auth.key", "instance-ed25519.key"} {
base := filepath.Join(source, name)
if _, e := os.Lstat(base); errors.Is(e, os.ErrNotExist) {
continue
} else if e != nil {
return nil, "", e
}
err = filepath.WalkDir(base, func(path string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
if err := ctx.Err(); err != nil {
return err
}
if entry.Type()&os.ModeSymlink != 0 {
return fmt.Errorf("snapshot refuses symlink: %s", path)
}
rel, _ := filepath.Rel(source, path)
if entry.IsDir() {
return os.MkdirAll(filepath.Join(root, rel), 0700)
}
return copyFile(path, filepath.Join(root, rel))
})
if err != nil {
return nil, "", err
}
}
err = filepath.WalkDir(root, func(path string, entry fs.DirEntry, e error) error {
if e != nil {
return e
}
if entry.IsDir() {
return syncDir(path)
}
if len(m.Files) >= 100000 {
return errors.New("snapshot exceeds 100000 files; partitioned snapshots require a later format")
}
f, e := fileHash(path)
if e != nil {
return e
}
f.Path, _ = filepath.Rel(root, path)
m.Files = append(m.Files, f)
return nil
})
if err != nil {
return nil, "", err
}
m.CompletedAt = time.Now().UTC()
encoded, err := json.MarshalIndent(m, "", " ")
if err != nil {
return nil, "", err
}
if err = os.WriteFile(filepath.Join(stage, "manifest.json"), encoded, 0600); err != nil {
return nil, "", err
}
manifestFile, err := os.OpenFile(filepath.Join(stage, "manifest.json"), os.O_RDWR, 0600)
if err != nil {
return nil, "", err
}
err = manifestFile.Sync()
manifestFile.Close()
if err != nil {
return nil, "", err
}
hash := sha256.Sum256(encoded)
if _, err = Verify(ctx, stage, hex.EncodeToString(hash[:])); err != nil {
return nil, "", err
}
if err = syncDir(stage); err != nil {
return nil, "", err
}
if err = publish(stage, target); err != nil {
return nil, "", err
}
return m, hex.EncodeToString(hash[:]), syncDir(parent)
}
func Verify(ctx context.Context, root, expectedHash string) (*Manifest, error) {
if len(expectedHash) != 64 {
return nil, errors.New("expected manifest SHA-256 is required from a trusted channel")
}
root, err := filepath.Abs(root)
if err != nil {
return nil, err
}
info, err := os.Lstat(filepath.Join(root, "manifest.json"))
if err != nil {
return nil, err
}
if !info.Mode().IsRegular() || info.Size() > 64<<20 {
return nil, errors.New("invalid or oversized snapshot manifest")
}
encoded, err := os.ReadFile(filepath.Join(root, "manifest.json"))
if err != nil {
return nil, err
}
sum := sha256.Sum256(encoded)
if hex.EncodeToString(sum[:]) != expectedHash {
return nil, errors.New("manifest SHA-256 mismatch")
}
var m Manifest
if err = json.Unmarshal(encoded, &m); err != nil {
return nil, err
}
if m.Version != 1 || m.Scope != "instance-offline-v1" || m.Epoch == 0 || len(m.Files) == 0 || len(m.Files) > 100000 || m.CapturedAt.IsZero() || m.CompletedAt.Before(m.CapturedAt) || m.CompletedAt.After(time.Now().Add(time.Minute)) {
return nil, errors.New("invalid snapshot manifest")
}
for _, id := range []string{m.ID, m.ClusterID, m.PrimaryNodeID} {
u, e := uuid.Parse(id)
if e != nil || u == uuid.Nil || u.String() != id {
return nil, errors.New("invalid snapshot identity")
}
}
seen := map[string]bool{}
hashes := map[string]string{}
for _, item := range m.Files {
if err = ctx.Err(); err != nil {
return nil, err
}
if !canonical(item.Path) || seen[item.Path] {
return nil, errors.New("invalid/duplicate snapshot path")
}
seen[item.Path] = true
hashes[item.Path] = item.SHA256
path := filepath.Join(root, "data", item.Path)
// Refuse symlinks in every component, including parent directories.
for p := path; p != filepath.Dir(root) && p != "."; p = filepath.Dir(p) {
info, e := os.Lstat(p)
if e != nil {
return nil, e
}
if info.Mode()&os.ModeSymlink != 0 {
return nil, errors.New("snapshot contains symlink")
}
if p == root || filepath.Dir(p) == p {
break
}
}
actual, e := fileHash(path)
if e != nil {
return nil, e
}
if actual.Size != item.Size || actual.SHA256 != item.SHA256 {
return nil, fmt.Errorf("snapshot payload mismatch: %s", item.Path)
}
if strings.HasPrefix(item.Path, "documents/sha256/") && filepath.Base(item.Path) != actual.SHA256 {
return nil, errors.New("CAS filename does not match payload hash")
}
}
if !seen["pages.db"] {
return nil, errors.New("snapshot database missing")
}
if err = verifyCalendarFiles(root, hashes); err != nil {
return nil, err
}
err = filepath.WalkDir(filepath.Join(root, "data"), func(path string, entry fs.DirEntry, e error) error {
if e != nil {
return e
}
if entry.IsDir() {
return nil
}
rel, _ := filepath.Rel(filepath.Join(root, "data"), path)
if !seen[rel] {
return errors.New("unlisted snapshot payload")
}
return nil
})
if err != nil {
return nil, err
}
database, err := db.OpenReadOnly(filepath.Join(root, "data", "pages.db"))
if err != nil {
return nil, err
}
defer database.Close()
var integrity string
if err = database.QueryRowContext(ctx, "PRAGMA quick_check").Scan(&integrity); err != nil {
return nil, err
}
if integrity != "ok" {
return nil, errors.New("snapshot database integrity check failed")
}
if err = verifyReferences(ctx, database, seen); err != nil {
return nil, err
}
return &m, nil
}
// Restore never merges into or overwrites a running/existing data directory.
// It publishes a new generation with a fresh physical node ID, always standby.
func Restore(ctx context.Context, snapshot, expectedHash, target string) (*Config, error) {
m, err := Verify(ctx, snapshot, expectedHash)
if err != nil {
return nil, err
}
target, err = filepath.Abs(target)
if err != nil {
return nil, err
}
parent, err := filepath.EvalSymlinks(filepath.Dir(target))
if err != nil {
return nil, err
}
target = filepath.Join(parent, filepath.Base(target))
source, err := filepath.EvalSymlinks(snapshot)
if err != nil {
return nil, err
}
source, err = filepath.Abs(source)
if err != nil {
return nil, err
}
if target == source || strings.HasPrefix(target, source+string(filepath.Separator)) {
return nil, errors.New("restore destination must be outside the snapshot")
}
if _, err = os.Lstat(target); !errors.Is(err, os.ErrNotExist) {
return nil, errors.New("restore target must not exist; use a new generation")
}
stage, err := os.MkdirTemp(filepath.Dir(target), ".dr-restore-")
if err != nil {
return nil, err
}
defer os.RemoveAll(stage)
for _, item := range m.Files {
if err = ctx.Err(); err != nil {
return nil, err
}
if err = copyFile(filepath.Join(snapshot, "data", item.Path), filepath.Join(stage, item.Path)); err != nil {
return nil, err
}
actual, e := fileHash(filepath.Join(stage, item.Path))
if e != nil {
return nil, e
}
if actual.Size != item.Size || actual.SHA256 != item.SHA256 {
return nil, errors.New("snapshot changed during restore")
}
}
c := &Config{Version: 1, ClusterID: m.ClusterID, NodeID: uuid.NewString(), PrimaryNodeID: m.PrimaryNodeID, Role: "standby", Epoch: m.Epoch, SnapshotID: m.ID, CapturedAt: m.CapturedAt, MaxReadAgeSeconds: 3600}
if err = Save(stage, *c); err != nil {
return nil, err
}
if err = os.MkdirAll(filepath.Join(stage, "documents", "sha256"), 0700); err != nil {
return nil, err
}
// Create the lock before a read-only data mount is applied.
l, err := Lock(stage, true)
if err != nil {
return nil, err
}
l.Close()
err = filepath.WalkDir(stage, func(path string, entry fs.DirEntry, e error) error {
if e != nil {
return e
}
if entry.IsDir() {
return syncDir(path)
}
return nil
})
if err != nil {
return nil, err
}
if err = publish(stage, target); err != nil {
return nil, err
}
return c, syncDir(filepath.Dir(target))
}
// Linux deployment: atomically publish without replacing even an empty directory.
func publish(stage, target string) error {
return unix.Renameat2(unix.AT_FDCWD, stage, unix.AT_FDCWD, target, unix.RENAME_NOREPLACE)
}
func verifyReferences(ctx context.Context, database *sql.DB, seen map[string]bool) error {
// Only authoritative references, not derived projection/preview caches. Some
// installations predate optional modules, hence the explicit table check.
for _, ref := range [][2]string{{"revisions", "document_hash"}, {"assets", "head_document_hash"}, {"asset_head_history", "document_hash"}, {"organizer_items", "document_hash"}, {"organizer_revisions", "document_hash"}} {
var exists bool
if err := database.QueryRowContext(ctx, "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type='table' AND name=?)", ref[0]).Scan(&exists); err != nil {
return err
}
if !exists {
continue
}
rows, err := database.QueryContext(ctx, "SELECT DISTINCT "+ref[1]+" FROM "+ref[0]+" WHERE "+ref[1]+" IS NOT NULL AND "+ref[1]+"<>''")
if err != nil {
return err
}
for rows.Next() {
var hash string
if err = rows.Scan(&hash); err != nil {
rows.Close()
return err
}
if len(hash) != 64 || !seen["documents/sha256/"+hash[:2]+"/"+hash] {
rows.Close()
return fmt.Errorf("snapshot lacks canonical payload referenced by %s", ref[0])
}
}
err = rows.Err()
rows.Close()
if err != nil {
return err
}
}
return nil
}
// Verify file-based calendar authority without parsing event bodies or making
// external calendar requests. Derived calendar indexes may be repaired only
// after promotion, never by a standby read request.
func verifyCalendarFiles(root string, hashes map[string]string) error {
for path := range hashes {
if !strings.HasPrefix(path, "documents/calendars/") || filepath.Base(path) != "calendar.json" {
continue
}
filename := filepath.Join(root, "data", path)
info, err := os.Stat(filename)
if err != nil {
return err
}
if info.Size() > 16<<20 {
return errors.New("calendar metadata exceeds snapshot verification limit")
}
encoded, err := os.ReadFile(filename)
if err != nil {
return err
}
var metadata struct {
Months map[string]string `json:"months"`
}
if err = json.Unmarshal(encoded, &metadata); err != nil {
return errors.New("invalid calendar metadata in snapshot")
}
for month, hash := range metadata.Months {
if _, err = time.Parse("2006-01", month); err != nil {
return errors.New("invalid calendar month in snapshot")
}
if len(hash) != 64 || hashes[filepath.ToSlash(filepath.Join(filepath.Dir(path), month+"."+hash+".ics"))] != hash {
return errors.New("snapshot lacks a valid calendar monthly generation")
}
}
}
return nil
}