Refactor architecture into eight components and consolidate reliability work
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:
1 parent
9dd425f765
commit
d5d21b7841
302 files changed
+20037
-3492
No files matched your search
@@ -0,0 +1,127 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"flag"
|
||||
"fmt"
|
||||
"io"
|
||||
"os"
|
||||
"time"
|
||||
|
||||
"pageswiki/internal/dr"
|
||||
)
|
||||
|
||||
// All role changes are operator-only and offline. Never expose this as a
|
||||
// domain-admin API: a data directory contains multiple campuses and domains.
|
||||
func runDR(args []string, out io.Writer) error {
|
||||
const usage = "pageswiki dr {init|status|snapshot|verify|restore|promote|resume-workers} [flags]\nUse COMMAND --help. Snapshot requires all writers stopped; promotion requires external fencing."
|
||||
if len(args) == 0 || args[0] == "--help" {
|
||||
_, err := fmt.Fprintln(out, usage)
|
||||
return err
|
||||
}
|
||||
cmd := args[0]
|
||||
switch cmd {
|
||||
case "init", "status", "snapshot", "verify", "restore", "promote", "resume-workers":
|
||||
default:
|
||||
return errors.New(usage)
|
||||
}
|
||||
f := flag.NewFlagSet("dr "+cmd, flag.ContinueOnError)
|
||||
f.SetOutput(out)
|
||||
defaultDir := os.Getenv("PAGESWIKI_DATA_DIR")
|
||||
if defaultDir == "" {
|
||||
defaultDir = "./data"
|
||||
}
|
||||
dir := f.String("data-dir", defaultDir, "instance data directory")
|
||||
var output, snapshot, hash, target, fenced, reference *string
|
||||
var stopped, loss, reviewed *bool
|
||||
switch cmd {
|
||||
case "resume-workers":
|
||||
reviewed = f.Bool("reviewed-restored-jobs", false, "attest restored queues and federation state have been reviewed for replay/duplicate effects")
|
||||
case "snapshot":
|
||||
output = f.String("output", "", "new snapshot directory outside data directory")
|
||||
stopped = f.Bool("writers-stopped", false, "attest ALL servers, CLIs and external writers are stopped")
|
||||
case "verify", "restore":
|
||||
snapshot = f.String("snapshot", "", "snapshot directory")
|
||||
hash = f.String("manifest-sha256", "", "manifest SHA-256 received over an authenticated channel")
|
||||
if cmd == "restore" {
|
||||
target = f.String("target", "", "new, nonexistent data directory (always standby)")
|
||||
}
|
||||
case "promote":
|
||||
fenced = f.String("fenced-node", "", "exact former primary node UUID")
|
||||
reference = f.String("fence-reference", "", "operator evidence/ticket for verified power/storage/network fencing")
|
||||
loss = f.Bool("accept-data-loss", false, "accept loss of writes since the snapshot cutoff")
|
||||
}
|
||||
if err := f.Parse(args[1:]); err != nil {
|
||||
if errors.Is(err, flag.ErrHelp) {
|
||||
return nil
|
||||
}
|
||||
return err
|
||||
}
|
||||
if f.NArg() != 0 {
|
||||
return errors.New("unexpected positional arguments")
|
||||
}
|
||||
encode := func(v any) error { e := json.NewEncoder(out); e.SetIndent("", " "); return e.Encode(v) }
|
||||
ctx := context.Background()
|
||||
switch cmd {
|
||||
case "resume-workers":
|
||||
c, err := dr.ResumeWorkers(*dir, *reviewed)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return encode(c)
|
||||
case "init":
|
||||
c, err := dr.Init(*dir)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return encode(c)
|
||||
case "status":
|
||||
c, err := dr.Load(*dir)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return encode(struct {
|
||||
Node *dr.Config `json:"node"`
|
||||
StandbyReadable bool `json:"standby_readable"`
|
||||
}{c, c != nil && c.Readable(time.Now())})
|
||||
case "snapshot":
|
||||
if *output == "" || !*stopped {
|
||||
return errors.New("snapshot requires --output and --writers-stopped; stop every writer first")
|
||||
}
|
||||
m, sum, err := dr.Snapshot(ctx, *dir, *output)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return encode(struct {
|
||||
Manifest *dr.Manifest `json:"manifest"`
|
||||
SHA256 string `json:"manifest_sha256"`
|
||||
}{m, sum})
|
||||
case "verify":
|
||||
if *snapshot == "" {
|
||||
return errors.New("--snapshot is required")
|
||||
}
|
||||
m, err := dr.Verify(ctx, *snapshot, *hash)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return encode(m)
|
||||
case "restore":
|
||||
if *snapshot == "" || *target == "" {
|
||||
return errors.New("--snapshot and --target are required")
|
||||
}
|
||||
c, err := dr.Restore(ctx, *snapshot, *hash, *target)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return encode(c)
|
||||
case "promote":
|
||||
c, err := dr.Promote(*dir, *fenced, *reference, *loss)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return encode(c)
|
||||
}
|
||||
return errors.New("unknown DR command")
|
||||
}
|
||||
@@ -0,0 +1,21 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestDRCLIRequiresExplicitOfflineAttestation(t *testing.T) {
|
||||
var out bytes.Buffer
|
||||
err := runDR([]string{"snapshot", "--data-dir", t.TempDir(), "--output", "/not-used"}, &out)
|
||||
if err == nil || !strings.Contains(err.Error(), "writers-stopped") {
|
||||
t.Fatalf("unsafe invocation: %v", err)
|
||||
}
|
||||
if err = runDR([]string{"restore"}, &out); err == nil {
|
||||
t.Fatal("missing restore target accepted")
|
||||
}
|
||||
if err = runDR([]string{"snapshot", "--help"}, &out); err != nil || !strings.Contains(out.String(), "writers-stopped") {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
+55
-1
@@ -1,16 +1,34 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"log"
|
||||
"os"
|
||||
"path/filepath"
|
||||
|
||||
"pageswiki/internal/db"
|
||||
"pageswiki/internal/dr"
|
||||
"pageswiki/internal/server"
|
||||
"pageswiki/internal/store"
|
||||
)
|
||||
|
||||
func main() {
|
||||
if len(os.Args) > 1 && os.Args[1] == "schema" {
|
||||
if err := runSchema(os.Args[2:], os.Stdout); err != nil {
|
||||
log.Print(err)
|
||||
if errors.Is(err, errSchemaPending) {
|
||||
os.Exit(2)
|
||||
}
|
||||
os.Exit(1)
|
||||
}
|
||||
return
|
||||
}
|
||||
if len(os.Args) > 1 && os.Args[1] == "dr" {
|
||||
if err := runDR(os.Args[2:], os.Stdout); err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
return
|
||||
}
|
||||
enrollment, err := parseExternalCampusEnrollment(os.Args[1:])
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
@@ -34,6 +52,39 @@ func main() {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
instanceLock, err := dr.Lock(dataDir, false)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
defer instanceLock.Close()
|
||||
node, err := dr.Load(dataDir)
|
||||
if err != nil {
|
||||
log.Fatalf("invalid DR configuration (startup refused): %v", err)
|
||||
}
|
||||
if err = dr.RequireRole(node, os.Getenv("PAGESWIKI_DR_EXPECT_ROLE")); err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
if node != nil && node.Role == "standby" {
|
||||
if len(os.Args) > 1 {
|
||||
log.Fatal("standby does not accept enrollment/startup mutation flags")
|
||||
}
|
||||
database, err := db.OpenReadOnly(filepath.Join(dataDir, "pages.db"))
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
defer database.Close()
|
||||
st, err := store.NewReadOnlyWithDocumentRoot(database, filepath.Join(dataDir, "documents"))
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
st.StandbyReadUntil = node.ReadUntil()
|
||||
log.Printf("DR standby: migrations, federation reconciliation and background workers disabled; snapshot=%s", node.SnapshotID)
|
||||
if err := server.New(st).Run(":3000"); err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
return
|
||||
}
|
||||
|
||||
dbPath :=
|
||||
filepath.Join(
|
||||
dataDir,
|
||||
@@ -87,7 +138,10 @@ func main() {
|
||||
if err := enrollExternalCampus(dataDir, st, enrollment); err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
startManagedCampusReconciler(dataDir, st)
|
||||
st.BackgroundJobsDisabled = node != nil && !node.WorkersEnabled
|
||||
if !st.BackgroundJobsDisabled {
|
||||
startManagedCampusReconciler(dataDir, st)
|
||||
}
|
||||
|
||||
srv := server.New(st)
|
||||
|
||||
|
||||
@@ -0,0 +1,114 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"flag"
|
||||
"fmt"
|
||||
"io"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"time"
|
||||
|
||||
"pageswiki/internal/db"
|
||||
"pageswiki/internal/store"
|
||||
)
|
||||
|
||||
var errSchemaPending = errors.New("schema migrations are pending; no changes were applied")
|
||||
var errSchemaBlocked = errors.New("schema history or contract is incompatible; no changes were applied")
|
||||
|
||||
func runSchema(args []string, out io.Writer) error {
|
||||
const usage = "pageswiki schema {status|check} [--db FILE | --data-dir DIR] [--json] [--timeout 30s]\nRead-only inspection of managed components; legacy migrations and pending DDL are not rehearsed.\ncheck exits 2 for pending migrations, 1 for incompatible state, 0 when managed components are current."
|
||||
if len(args) == 0 || args[0] == "--help" {
|
||||
_, err := fmt.Fprintln(out, usage)
|
||||
return err
|
||||
}
|
||||
if args[0] != "status" && args[0] != "check" {
|
||||
return errors.New(usage)
|
||||
}
|
||||
f := flag.NewFlagSet("schema "+args[0], flag.ContinueOnError)
|
||||
f.SetOutput(out)
|
||||
defaultDir := os.Getenv("PAGESWIKI_DATA_DIR")
|
||||
if defaultDir == "" {
|
||||
defaultDir = "./data"
|
||||
}
|
||||
dir := f.String("data-dir", defaultDir, "instance data directory (not created)")
|
||||
path := f.String("db", "", "explicit existing SQLite database path")
|
||||
jsonOutput := f.Bool("json", false, "JSON report")
|
||||
timeout := f.Duration("timeout", 30*time.Second, "inspection timeout")
|
||||
if err := f.Parse(args[1:]); err != nil {
|
||||
if errors.Is(err, flag.ErrHelp) {
|
||||
return nil
|
||||
}
|
||||
return err
|
||||
}
|
||||
if f.NArg() != 0 || *timeout <= 0 {
|
||||
return errors.New("unexpected arguments or invalid timeout")
|
||||
}
|
||||
explicitDir := false
|
||||
f.Visit(func(flag *flag.Flag) {
|
||||
if flag.Name == "data-dir" {
|
||||
explicitDir = true
|
||||
}
|
||||
})
|
||||
if *path != "" && explicitDir {
|
||||
return errors.New("choose --db or --data-dir, not both")
|
||||
}
|
||||
if *path == "" {
|
||||
*path = filepath.Join(*dir, "pages.db")
|
||||
}
|
||||
database, err := db.OpenReadOnly(*path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
defer database.Close()
|
||||
ctx, cancel := context.WithTimeout(context.Background(), *timeout)
|
||||
defer cancel()
|
||||
report, err := store.InspectSchema(ctx, database)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if *jsonOutput {
|
||||
encoder := json.NewEncoder(out)
|
||||
encoder.SetIndent("", " ")
|
||||
err = encoder.Encode(report)
|
||||
} else {
|
||||
_, err = fmt.Fprintf(out, "Coverage: %s (not a full startup or data migration rehearsal)\n", report.Coverage)
|
||||
for _, component := range report.Components {
|
||||
if err != nil {
|
||||
break
|
||||
}
|
||||
_, err = fmt.Fprintf(out, "%-24s %-8s %d -> %d\n", component.Component, component.State, component.AppliedVersion, component.LatestVersion)
|
||||
for _, step := range component.Pending {
|
||||
if err != nil {
|
||||
break
|
||||
}
|
||||
_, err = fmt.Fprintf(out, " pending v%d %s (%d SQL statements, %d conditional columns)\n", step.Version, step.Name, step.Statements, len(step.AddColumns))
|
||||
}
|
||||
for _, issue := range component.Issues {
|
||||
if err != nil {
|
||||
break
|
||||
}
|
||||
_, err = fmt.Fprintf(out, " %s\n", issue)
|
||||
}
|
||||
}
|
||||
if err == nil {
|
||||
_, err = fmt.Fprintf(out, "Legacy areas not covered: %v\n", report.LegacyAreas)
|
||||
}
|
||||
}
|
||||
if err != nil || args[0] == "status" {
|
||||
return err
|
||||
}
|
||||
pending := false
|
||||
for _, component := range report.Components {
|
||||
if component.State == "blocked" || component.State == "unknown" {
|
||||
return errSchemaBlocked
|
||||
}
|
||||
pending = pending || component.State == "pending"
|
||||
}
|
||||
if pending {
|
||||
return errSchemaPending
|
||||
}
|
||||
return nil
|
||||
}
|
||||
@@ -0,0 +1,106 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
|
||||
"pageswiki/internal/db"
|
||||
"pageswiki/internal/store"
|
||||
)
|
||||
|
||||
func TestSchemaCommandMissingDatabaseDoesNotInitialize(t *testing.T) {
|
||||
dir := filepath.Join(t.TempDir(), "missing")
|
||||
var out bytes.Buffer
|
||||
if err := runSchema([]string{"status", "--data-dir", dir}, &out); err == nil {
|
||||
t.Fatal("missing DB accepted")
|
||||
}
|
||||
if _, err := os.Stat(dir); !errors.Is(err, os.ErrNotExist) {
|
||||
t.Fatalf("directory created: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestSchemaCommandPendingAndBlocked(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
database, err := db.Open(filepath.Join(dir, "pages.db"))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
defer database.Close()
|
||||
if err := database.Ping(); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var out bytes.Buffer
|
||||
if err := runSchema([]string{"status", "--data-dir", dir, "--json"}, &out); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var report store.SchemaInspection
|
||||
if err := json.Unmarshal(out.Bytes(), &report); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if report.Coverage != "managed-components-only" || len(report.Components) == 0 || len(report.LegacyAreas) == 0 {
|
||||
t.Fatalf("report=%+v", report)
|
||||
}
|
||||
out.Reset()
|
||||
if err := runSchema([]string{"check", "--db", filepath.Join(dir, "pages.db")}, &out); !errors.Is(err, errSchemaPending) {
|
||||
t.Fatalf("pending: %v", err)
|
||||
}
|
||||
if _, err := database.Exec(`CREATE TABLE schema_migration_steps(component TEXT,version INTEGER,name TEXT,checksum TEXT,applied_at_ms INTEGER); INSERT INTO schema_migration_steps VALUES('future-component',1,'future','unknown',0)`); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
out.Reset()
|
||||
if err := runSchema([]string{"check", "--data-dir", dir}, &out); !errors.Is(err, errSchemaBlocked) {
|
||||
t.Fatalf("unknown component: %v", err)
|
||||
}
|
||||
var count int
|
||||
if err := database.QueryRow(`SELECT count(*) FROM sqlite_master WHERE type='table'`).Scan(&count); err != nil || count != 1 {
|
||||
t.Fatalf("command initialized DB: %d %v", count, err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestSchemaCommandArguments(t *testing.T) {
|
||||
for _, args := range [][]string{{"apply"}, {"check", "--timeout", "0s"}, {"check", "extra"}, {"check", "--db", "a", "--data-dir", "b"}} {
|
||||
if err := runSchema(args, &bytes.Buffer{}); err == nil {
|
||||
t.Fatalf("accepted %v", args)
|
||||
}
|
||||
}
|
||||
for _, args := range [][]string{nil, {"--help"}, {"check", "--help"}} {
|
||||
if err := runSchema(args, &bytes.Buffer{}); err != nil {
|
||||
t.Fatalf("help %v: %v", args, err)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestSchemaCommandCurrentApplicationDatabase(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
database, err := db.Open(filepath.Join(dir, "pages.db"))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
defer database.Close()
|
||||
if err := db.Init(database); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := db.Migrate(database); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
// Initialize only this synthetic fixture. runSchema must not run the
|
||||
// constructor itself, even for an already initialized application DB.
|
||||
store.NewWithDocumentRoot(database, filepath.Join(dir, "documents"))
|
||||
var out bytes.Buffer
|
||||
if err := runSchema([]string{"check", "--data-dir", dir, "--json"}, &out); err != nil {
|
||||
t.Fatalf("current database: %v\n%s", err, out.String())
|
||||
}
|
||||
var report store.SchemaInspection
|
||||
if err := json.Unmarshal(out.Bytes(), &report); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
for _, component := range report.Components {
|
||||
if component.State != "current" {
|
||||
t.Fatalf("component=%+v", component)
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user