diff --git a/Taskfile.yml b/Taskfile.yml index 6ab86a670..ab1018911 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -353,10 +353,6 @@ tasks: archie-gateway and archie-ui dial it -- none owns the DB in-process (docs/prds/state-store-contract.md §12 step 7) - * state admin read-only PocketBase surface over archie.db on - 127.0.0.1:8686 (view collections only; the gRPC - contract stays the only writer). Served by the - archie-state-store process, not a sixth one. * archie-ui serves the dashboard on 127.0.0.1:8484 from the embedded dist (deployments/dev.toml). After the UI cutover (archie-core-8cda.5.4) archied runs no @@ -387,12 +383,8 @@ tasks: dev:state-store: desc: archie-state-store only, no live-reload (prefer `task dev`) - # -admin-addr serves the read-only operator dashboard over the same - # archie.db this process already owns. It is a flag rather than a config - # key for the same reason -ready-addr is: the address is a property of - # how this process was launched, not of the deployment's config document. cmds: - - go run ./cmd/archie-state-store -config-overlay deployments/dev.toml -admin-addr 127.0.0.1:8686 + - go run ./cmd/archie-state-store -config-overlay deployments/dev.toml dev:gateway: desc: archie-gateway only, no live-reload (prefer `task dev`) diff --git a/cmd/archie-state-store/main.go b/cmd/archie-state-store/main.go index f9da1e4e8..c664fa746 100644 --- a/cmd/archie-state-store/main.go +++ b/cmd/archie-state-store/main.go @@ -39,7 +39,6 @@ func run() int { flag.StringVar(&options.Listen, "listen", "", "state store gRPC listen address (defaults to [services.state].listen, else 127.0.0.1:9090)") flag.StringVar(&options.Token, "token", "", "bearer token required for a non-loopback listener (defaults to [services.state].target_token)") flag.StringVar(&options.ReadyAddr, "ready-addr", "", "optional readiness HTTP listen address (e.g. 127.0.0.1:9091)") - flag.StringVar(&options.AdminAddr, "admin-addr", "", "optional read-only operator dashboard listen address (e.g. 127.0.0.1:8090)") flag.Usage = func() { fmt.Fprintf(flag.CommandLine.Output(), "usage: archie-state-store [flags] # serve the State Store gRPC contract\n\noffline recovery: archie-state-store -h\n\n") flag.PrintDefaults() diff --git a/deployments/README.md b/deployments/README.md index 34afd05c1..24c9c4d20 100644 --- a/deployments/README.md +++ b/deployments/README.md @@ -124,21 +124,3 @@ indicates dual-store ownership (`docs/prds/state-store-contract.md` §12 step 7/ The readiness probe is the single-writer check the runbook has against a degraded store: a `503` from `/health/detailed` means `archied` should be started only after the store is healthy. - -### Inspecting the store - -`-admin-addr` starts a read-only operator dashboard on the same process, over -the file it already owns: - -```bash -archie-state-store -admin-addr 127.0.0.1:8686 # dashboard on http://127.0.0.1:8686/_/ -``` - -It co-tenants on `-tasks.sqlite` rather than opening a second -database, so it does not disturb the single-writer rule above: it runs inside -the process that holds the ownership claim, and every archie table is exposed -as a read-only view collection. The routes that could write past those views -(`POST /api/sql`, `/api/backups`) are refused, so the gRPC contract stays the -only writer and `archie-state-store backup` stays the only snapshot path. - -Leave the flag off and no dashboard listener is started. diff --git a/internal/app/archied/state_store.go b/internal/app/archied/state_store.go index 4918ee7b5..60a5af36f 100644 --- a/internal/app/archied/state_store.go +++ b/internal/app/archied/state_store.go @@ -27,7 +27,6 @@ import ( "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/infrastructure/edastore" "github.com/samcharles93/archie-core/internal/infrastructure/readiness" - "github.com/samcharles93/archie-core/internal/infrastructure/stateadmin" "github.com/samcharles93/archie-core/internal/infrastructure/staterpc" "github.com/samcharles93/archie-core/internal/store" ) @@ -68,10 +67,6 @@ type StateStoreOptions struct { // address: GET /healthz (liveness) and GET /health/detailed (the // state_db probe). Empty disables it. ReadyAddr string - // AdminAddr, when non-empty, starts the read-only operator dashboard on - // the address. It co-tenants on the same SQLite file this process already - // owns, so it needs no lock and no database of its own. Empty disables it. - AdminAddr string } // RunStateStore owns the single archie.db SQLite file, registers every @@ -383,42 +378,9 @@ func (b *boot) startOptionalSurfaces(ctx context.Context, options StateStoreOpti return err } } - if options.AdminAddr != "" { - if err := b.startStateAdmin(ctx, options.AdminAddr); err != nil { - return err - } - } return nil } -// startStateAdmin starts the read-only operator dashboard on adminAddr. -// -// It is started here, inside the process that already holds the database's -// ownership claim (openStateStore above), because that claim is what makes a -// second reader safe to co-tenant: a separate admin process would be a second -// opener of a single-owner file. The surface exposes view collections only and -// refuses the routes that could write, so the StateStoreService contract this -// process serves stays the only writer of task state. -func (b *boot) startStateAdmin(ctx context.Context, adminAddr string) error { - admin, err := stateadmin.New(stateadmin.Config{ - DBPath: taskDBPath(b.cfg.DBPath), - DataDir: filepath.Join(filepath.Dir(taskDBPath(b.cfg.DBPath)), "admin"), - }) - if err != nil { - return err - } - b.addCleanup(func() { - if err := admin.Close(); err != nil { - b.log.Error("close state admin", "err", err) - } - }) - handler, err := admin.Handler() - if err != nil { - return fmt.Errorf("build state admin handler: %w", err) - } - return b.serveHealth(ctx, adminAddr, handler, "state store admin") -} - // stateStoreServerOpts applies the transport security boundary (§9): a // loopback listener is served insecure with no token; any non-loopback // address requires a bearer token, else the process fails closed. It cannot diff --git a/internal/infrastructure/edastore/edastore.go b/internal/infrastructure/edastore/edastore.go index 9c4c6c86e..7c336b39d 100644 --- a/internal/infrastructure/edastore/edastore.go +++ b/internal/infrastructure/edastore/edastore.go @@ -7,8 +7,7 @@ // to a workflow. That loop wants a runtime-editable store with a live view of // arriving payloads, which is what PocketBase collections give directly. // -// Unlike the read-only surface in internal/infrastructure/stateadmin, these -// collections are authoritative and writable: the admin UI editing a binding +// These collections are authoritative and writable: the admin UI editing a binding // IS the feature, not a hazard. The task lifecycle tables stay on SQLite -- // they carry ordering, cursor and task-grant semantics that gain nothing from // being hand-editable. binding_dispatches.task reaches them by plain id, which diff --git a/internal/infrastructure/stateadmin/stateadmin.go b/internal/infrastructure/stateadmin/stateadmin.go deleted file mode 100644 index 62c31e221..000000000 --- a/internal/infrastructure/stateadmin/stateadmin.go +++ /dev/null @@ -1,219 +0,0 @@ -// Package stateadmin serves a read-only operator surface over the State -// Store's SQLite file: a dashboard for inspecting task state, backed by -// PocketBase. -// -// It co-tenants on archie.db rather than owning a database of its own. -// PocketBase's data.db is redirected onto the State Store's file, so its -// system tables sit beside the State Store's in one file, and PRAGMA -// user_version -- archie's migration version -- is left untouched. Running -// inside the State Store process puts the surface under the same -// store.AcquireOwnership claim, so the single-owner invariant covers it -// without a second lock. -// -// Every archie table is exposed as a PocketBase *view* collection, which is -// read-only by construction. That is the point: the StateStoreService gRPC -// contract stays the only writer of task state, and this surface cannot -// become a second one. -// -// View collections alone are not enough to hold that line. PocketBase also -// ships two superuser routes that reach past them, so both are refused here: -// POST /api/sql executes write statements as well as reads (apis.executeQuery -// detects a write and runs it anyway), and /api/backups would give the file a -// second snapshot and restore semantics next to store.Backup's VACUUM INTO. -// Refusing the routes removes them rather than leaving them behind an auth -// check, because "only a superuser can corrupt task state" is still a second -// writer. -package stateadmin - -import ( - "database/sql" - "errors" - "fmt" - "net/http" - "path/filepath" - "strings" - - "github.com/pocketbase/dbx" - "github.com/pocketbase/pocketbase" - "github.com/pocketbase/pocketbase/apis" - "github.com/pocketbase/pocketbase/core" - "github.com/pocketbase/pocketbase/tools/router" - "github.com/pocketbase/pocketbase/ui" - _ "modernc.org/sqlite" -) - -// refusedPrefixes are the PocketBase routes that would make this surface a -// second writer of State Store data. See the package comment. -var refusedPrefixes = []string{"/api/backups", "/api/sql"} - -// views maps each exposed collection to the query that populates it. The -// collection name is prefixed so it cannot collide with a PocketBase system -// collection, and every query must select an "id": PocketBase keys view -// records on it, and resources is keyed by kind rather than a row id. -// -// Only the task-lifecycle tables appear here. The event-capture tables moved -// to internal/infrastructure/edastore, which owns them as real, editable -// collections; mirroring them as read-only views would be a second, weaker -// surface over data that already has a better one. -var views = []struct { - name string - query string -}{ - {"archie_tasks", `SELECT id, owner, repo, issue_number, title, status, workflow, stage, branch, pr_number, tokens_used, iterations, attempt, park_reason, identity, created_at, updated_at FROM tasks`}, - {"archie_transitions", `SELECT id, task_id, at, from_status, to_status, detail FROM transitions`}, - {"archie_events", `SELECT id, at, kind, task_id, repo, issue, workflow, stage, attempt FROM events`}, - {"archie_identities", `SELECT id, kind, display_name, lifecycle, version, created_at, updated_at FROM identities`}, - {"archie_resources", `SELECT kind AS id, kind, version, updated_at FROM resources`}, -} - -// ViewCollections returns the collection names this surface exposes. -func ViewCollections() []string { - names := make([]string, 0, len(views)) - for _, v := range views { - names = append(names, v.name) - } - return names -} - -// Config describes one admin surface. -type Config struct { - // DBPath is the State Store's SQLite file. The surface co-tenants on it. - DBPath string - // DataDir holds PocketBase's own auxiliary.db, settings and uploads. - // Nothing archie owns lives here. - DataDir string -} - -// Server is a bootstrapped admin surface. -type Server struct { - app *pocketbase.PocketBase -} - -// New bootstraps the surface against cfg.DBPath and registers its view -// collections. It binds no listener: the caller serves Handler on its own, -// so this package has no lifecycle of its own to get wrong. -func New(cfg Config) (*Server, error) { - if cfg.DBPath == "" { - return nil, errors.New("stateadmin: DBPath is required") - } - if cfg.DataDir == "" { - return nil, errors.New("stateadmin: DataDir is required") - } - app := pocketbase.NewWithConfig(pocketbase.Config{ - DefaultDataDir: cfg.DataDir, - HideStartBanner: true, - DBConnect: connectTo(cfg.DBPath), - }) - if err := app.Bootstrap(); err != nil { - return nil, fmt.Errorf("stateadmin: bootstrap: %w", err) - } - // apis.Serve would run these on listen; this surface is served through the - // caller's listener instead, so it applies them itself. - if err := app.RunAllMigrations(); err != nil { - return nil, fmt.Errorf("stateadmin: run migrations: %w", err) - } - if err := removeDefaultAuthCollection(app); err != nil { - return nil, err - } - if err := registerViews(app); err != nil { - return nil, err - } - return &Server{app: app}, nil -} - -// connectTo redirects PocketBase's data.db onto the State Store's file while -// leaving auxiliary.db where PocketBase wants it. The DSN matches the one the -// store opens with, so both connections agree on journal mode and busy -// timeout instead of racing on conflicting pragmas. -func connectTo(dbPath string) core.DBConnectFunc { - return func(requested string) (*dbx.DB, error) { - if filepath.Base(requested) == "data.db" { - requested = dbPath - } - return dbx.Open("sqlite", requested+"?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)") - } -} - -// registerViews creates or updates each view collection. It runs on every -// process start, so an existing collection is updated rather than refused. -func registerViews(app core.App) error { - for _, v := range views { - collection, err := app.FindCollectionByNameOrId(v.name) - switch { - case errors.Is(err, sql.ErrNoRows): - collection = core.NewViewCollection(v.name) - case err != nil: - // A lookup that failed for any other reason must not be read as - // "absent": creating a second collection over a live one would - // be a schema change made on the strength of a transient error. - return fmt.Errorf("stateadmin: look up view %q: %w", v.name, err) - case !collection.IsView(): - return fmt.Errorf("stateadmin: collection %q exists and is not a view", v.name) - } - collection.ViewQuery = v.query - if err := app.Save(collection); err != nil { - return fmt.Errorf("stateadmin: register view %q: %w", v.name, err) - } - } - return nil -} - -// removeDefaultAuthCollection deletes the "users" collection PocketBase -// creates on first bootstrap. -// -// Its createRule is open, so leaving it in place lets an unauthenticated -// caller POST a record and write a row into the State Store's database file. -// This surface authenticates superusers only and has no notion of end users, -// so the collection is deleted rather than given a tighter rule: a collection -// that is not there cannot be loosened again by a later PocketBase default. -func removeDefaultAuthCollection(app core.App) error { - collection, err := app.FindCollectionByNameOrId("users") - switch { - case errors.Is(err, sql.ErrNoRows): - // Already absent: every restart after the first, and any deployment - // whose PocketBase version stops shipping the default. - return nil - case err != nil: - return fmt.Errorf("stateadmin: look up default users collection: %w", err) - } - if err := app.Delete(collection); err != nil { - return fmt.Errorf("stateadmin: remove default users collection: %w", err) - } - return nil -} - -// refuseWritePaths answers every refusedPrefixes route with 404. -func refuseWritePaths(r *router.Router[*core.RequestEvent]) { - r.BindFunc(func(e *core.RequestEvent) error { - for _, prefix := range refusedPrefixes { - if strings.HasPrefix(e.Request.URL.Path, prefix) { - return router.NewNotFoundError("", nil) - } - } - return e.Next() - }) -} - -// Handler builds the surface's HTTP handler without binding a listener. -// -// apis.NewRouter binds the JSON API but not the dashboard: apis.Serve mounts -// the embedded UI on /_/ itself, along with autocert and www-redirect -// machinery this surface has no use for. So the dashboard route is mounted -// here, and the caller keeps ownership of the listener. -func (s *Server) Handler() (http.Handler, error) { - r, err := apis.NewRouter(s.app) - if err != nil { - return nil, err - } - refuseWritePaths(r) - if ui.DistDirFS != nil { - r.GET("/_/{path...}", apis.Static(ui.DistDirFS, false)).Bind(apis.Gzip()) - } - return r.BuildMux() -} - -// App exposes the underlying PocketBase application. -func (s *Server) App() core.App { return s.app } - -// Close releases the surface's database connections. -func (s *Server) Close() error { return s.app.ClearBootstrap() } diff --git a/internal/infrastructure/stateadmin/stateadmin_test.go b/internal/infrastructure/stateadmin/stateadmin_test.go deleted file mode 100644 index b867bae7f..000000000 --- a/internal/infrastructure/stateadmin/stateadmin_test.go +++ /dev/null @@ -1,196 +0,0 @@ -package stateadmin_test - -import ( - "errors" - "net/http" - "net/http/httptest" - "path/filepath" - "strings" - "testing" - - "github.com/samcharles93/archie-core/internal/domain/workflow" - "github.com/samcharles93/archie-core/internal/infrastructure/stateadmin" - "github.com/samcharles93/archie-core/internal/store" -) - -// openArchieDB creates a real, migrated State Store database and returns its -// path. The admin surface co-tenants on this exact file, so the tests exercise -// the production schema rather than a stand-in. -func openArchieDB(t *testing.T) string { - t.Helper() - path := filepath.Join(t.TempDir(), "archie.db-tasks.sqlite") - st, err := store.Open(t.Context(), path) - if err != nil { - t.Fatalf("store.Open() error = %v", err) - } - t.Cleanup(func() { _ = st.Close() }) - return path -} - -func newAdmin(t *testing.T, dbPath string) *stateadmin.Server { - t.Helper() - srv, err := stateadmin.New(stateadmin.Config{ - DBPath: dbPath, - DataDir: filepath.Join(t.TempDir(), "pb_data"), - }) - if err != nil { - t.Fatalf("stateadmin.New() error = %v", err) - } - t.Cleanup(func() { _ = srv.Close() }) - return srv -} - -// TestViewCollectionsExposeStateTables pins that every table the admin surface -// claims to expose is registered as a *view* collection. View collections are -// read-only by construction, which is what keeps the gRPC contract the only -// writer of task state. -func TestViewCollectionsExposeStateTables(t *testing.T) { - srv := newAdmin(t, openArchieDB(t)) - - for _, name := range stateadmin.ViewCollections() { - collection, err := srv.App().FindCollectionByNameOrId(name) - if err != nil { - t.Fatalf("FindCollectionByNameOrId(%q) error = %v, want the collection to exist", name, err) - } - if !collection.IsView() { - t.Errorf("collection %q type = %q, want a view: a base collection would let the admin UI write task state behind the gRPC contract", name, collection.Type) - } - } -} - -// TestBootstrapPreservesSchemaVersion pins that PocketBase's own bootstrap does -// not disturb archie's migration versioning. Both systems share one file; -// PRAGMA user_version is archie's and must survive co-tenancy untouched. -func TestBootstrapPreservesSchemaVersion(t *testing.T) { - path := openArchieDB(t) - - before, err := store.ValidateFile(t.Context(), path) - if err != nil { - t.Fatalf("ValidateFile() before admin bootstrap error = %v", err) - } - - newAdmin(t, path) - - after, err := store.ValidateFile(t.Context(), path) - if err != nil { - t.Fatalf("ValidateFile() after admin bootstrap error = %v, want the store to still validate", err) - } - if before != after { - t.Errorf("schema version moved across admin bootstrap: before = %d, after = %d", before, after) - } -} - -// TestStoreWritesSurviveCoTenancy is the regression that matters: archie's -// conditional-UPDATE optimistic concurrency must keep working, and keep -// reporting ErrStaleTransition for a losing writer, while the admin surface -// holds its own connections to the same file. -func TestStoreWritesSurviveCoTenancy(t *testing.T) { - path := openArchieDB(t) - newAdmin(t, path) - - st, err := store.Open(t.Context(), path) - if err != nil { - t.Fatalf("store.Open() alongside admin error = %v", err) - } - defer st.Close() - - if _, err := st.EnqueueIssue(t.Context(), "o", "r", 1, "co-tenancy", "", "", ""); err != nil { - t.Fatalf("EnqueueIssue() while admin holds the file error = %v", err) - } - queued, err := st.TaskByIssue(t.Context(), "o", "r", 1) - if err != nil { - t.Fatalf("TaskByIssue() error = %v", err) - } - id := queued.ID - - if err := st.Transition(t.Context(), id, workflow.StatusQueued, workflow.StatusRunning, ""); err != nil { - t.Fatalf("Transition(queued->running) error = %v, want the write to commit under co-tenancy", err) - } - // The same transition again must lose: the row is no longer queued. - if err := st.Transition(t.Context(), id, workflow.StatusQueued, workflow.StatusRunning, ""); !errors.Is(err, store.ErrStaleTransition) { - t.Fatalf("second Transition() error = %v, want ErrStaleTransition: optimistic concurrency must not degrade under co-tenancy", err) - } -} - -// TestWriteReachingRoutesAreRefused pins that the routes which reach past the -// read-only view collections are gone, not merely authenticated. POST /api/sql -// executes write statements (apis.executeQuery runs a detected write anyway), -// and /api/backups would add a second snapshot and restore path beside -// store.Backup. Both are superuser-gated upstream, which is not the same as -// absent: a superuser writing task state is still a second writer. -func TestWriteReachingRoutesAreRefused(t *testing.T) { - srv := newAdmin(t, openArchieDB(t)) - - mux, err := srv.Handler() - if err != nil { - t.Fatalf("Handler() error = %v", err) - } - // The method must match the route PocketBase actually binds: a GET against - // the POST-only /api/sql would 404 on method alone and assert nothing. - for _, route := range []struct{ method, path string }{ - {http.MethodGet, "/api/backups"}, - {http.MethodGet, "/api/backups/some-snapshot"}, - {http.MethodPost, "/api/sql"}, - } { - rec := httptest.NewRecorder() - mux.ServeHTTP(rec, httptest.NewRequestWithContext(t.Context(), route.method, route.path, nil)) - if rec.Code != http.StatusNotFound { - t.Errorf("%s %s status = %d, want 404: the gRPC contract is the only writer and store.Backup the only snapshot path", route.method, route.path, rec.Code) - } - } -} - -// TestViewCollectionsAreIdempotent pins that a restart re-registers cleanly. -// The admin surface bootstraps on every process start, so a second pass over an -// already-populated database must update rather than fail. -func TestViewCollectionsAreIdempotent(t *testing.T) { - path := openArchieDB(t) - newAdmin(t, path) - newAdmin(t, path) -} - -// TestDashboardIsServed pins that the operator dashboard is actually reachable. -// apis.NewRouter binds the JSON API only; the embedded UI is mounted by -// apis.Serve, which this surface does not use. Without an explicit mount /_/ -// answers 404 and the surface has an API but no dashboard, which is the whole -// reason it exists. -func TestDashboardIsServed(t *testing.T) { - srv := newAdmin(t, openArchieDB(t)) - - mux, err := srv.Handler() - if err != nil { - t.Fatalf("Handler() error = %v", err) - } - rec := httptest.NewRecorder() - mux.ServeHTTP(rec, httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/_/", nil)) - if rec.Code != http.StatusOK { - t.Errorf("GET /_/ status = %d, want 200: the dashboard is the surface's reason to exist", rec.Code) - } -} - -// TestNoOpenRegistration pins that the surface has no self-service signup. -// PocketBase creates a "users" auth collection on first bootstrap whose -// createRule is open, so an unauthenticated caller could POST a record and -// write a row into the State Store's own database file. The surface is -// superuser-only by design, so the collection is removed rather than left -// with a tightened rule: a collection that does not exist cannot regress. -func TestNoOpenRegistration(t *testing.T) { - srv := newAdmin(t, openArchieDB(t)) - - if _, err := srv.App().FindCollectionByNameOrId("users"); err == nil { - t.Error("the default users collection still exists; it accepts unauthenticated record creation into archie's database file") - } - - mux, err := srv.Handler() - if err != nil { - t.Fatalf("Handler() error = %v", err) - } - body := strings.NewReader(`{"email":"nobody@example.com","password":"hunter2hunter2","passwordConfirm":"hunter2hunter2"}`) - req := httptest.NewRequestWithContext(t.Context(), http.MethodPost, "/api/collections/users/records", body) - req.Header.Set("Content-Type", "application/json") - rec := httptest.NewRecorder() - mux.ServeHTTP(rec, req) - if rec.Code < 400 { - t.Errorf("POST /api/collections/users/records status = %d, want a refusal: unauthenticated writes must not reach the State Store's file", rec.Code) - } -}