diff --git a/cmd/archie-state-store/main.go b/cmd/archie-state-store/main.go index c664fa746..f9da1e4e8 100644 --- a/cmd/archie-state-store/main.go +++ b/cmd/archie-state-store/main.go @@ -39,6 +39,7 @@ 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/internal/app/archied/state_store.go b/internal/app/archied/state_store.go index 6c3779b97..1fe82d3ef 100644 --- a/internal/app/archied/state_store.go +++ b/internal/app/archied/state_store.go @@ -30,6 +30,7 @@ import ( "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/infrastructure/cronstore" "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" ) @@ -65,6 +66,10 @@ 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 @@ -131,10 +136,8 @@ func RunStateStore(ctx context.Context, options StateStoreOptions) error { defer listener.Close() b.log.Info("archie-state-store running", "addr", listener.Addr().String(), "token_required", !loopback) - if options.ReadyAddr != "" { - if err := b.startStateStoreReadiness(ctx, options.ReadyAddr); err != nil { - return err - } + if err := b.startOptionalSurfaces(ctx, options); err != nil { + return err } deps := b.stateStoreDeps(grants) @@ -421,6 +424,55 @@ func (b *boot) startStateStoreReadiness(ctx context.Context, readyAddr string) e return b.serveHealth(ctx, readyAddr, mux, "state store readiness") } +// startOptionalSurfaces starts the HTTP surfaces this process serves beside +// the gRPC contract, each enabled only by its own flag. +// +// They are gathered here rather than branched inline because RunStateStore is +// at its complexity budget: a surface that is off by default belongs to its +// own decision, not to the boot sequence that triggers it -- the same reason +// reportUnseededResources is a method. +func (b *boot) startOptionalSurfaces(ctx context.Context, options StateStoreOptions) error { + if options.ReadyAddr != "" { + if err := b.startStateStoreReadiness(ctx, options.ReadyAddr); err != nil { + 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/stateadmin/stateadmin.go b/internal/infrastructure/stateadmin/stateadmin.go new file mode 100644 index 000000000..8ae03a45a --- /dev/null +++ b/internal/infrastructure/stateadmin/stateadmin.go @@ -0,0 +1,181 @@ +// 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 ( + "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. +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_bindings", `SELECT id, name, source, mapping_id, workflow, owner, repo, version, status FROM bindings`}, + {"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 := 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) + if err != nil { + collection = core.NewViewCollection(v.name) + } else if !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 +} + +// 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 new file mode 100644 index 000000000..03a6b3fbf --- /dev/null +++ b/internal/infrastructure/stateadmin/stateadmin_test.go @@ -0,0 +1,168 @@ +package stateadmin_test + +import ( + "errors" + "net/http" + "net/http/httptest" + "path/filepath" + "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) + } +}