fix(app): serve only setup until the owner setup transaction commits

The binary started connectors, module routes, the starter workflow and the
worker loops at boot whatever the database said, so an instance with no owner
answered operational requests, the bootstrap admin token among them. The
governance module now signals once the bootstrap registration has committed,
and the composition root holds every operational route, connector and loop back
until it does. Liveness stays up and readiness reports the missing owner.
This commit is contained in:
sam committed 2026-11-21 03:40:02 +11:00
1 parent 98c0c11cbb
commit ae3bbc6cfe
7 files changed
+761 -63

No files matched your search

+145
View File
@@ -0,0 +1,145 @@
package archie
import (
"context"
"errors"
"io/fs"
"log/slog"
"net/http"
"strings"
"sync"
"github.com/samcharles93/archie-core/internal/platform/health"
"github.com/samcharles93/archie-core/internal/platform/httpjson"
)
// The two account operations the setup page calls. Everything else under
// /api/ needs the instance it would be operating.
const (
authStatusPath = "/api/auth/status"
setUpAccountPath = "/api/auth/setup"
)
// gate is the surface the binary serves. Until the owner setup transaction has
// committed it answers only what the setup page needs, and refuses every
// operational route before its handler runs, whatever credential the request
// carries. Once operations are started and wired it hands every request to
// them.
type gate struct {
ops http.Handler
setup http.Handler
mu sync.RWMutex
open bool
}
// newGate returns a closed gate over the operational handler and the dashboard
// build its assets come from.
func newGate(ops http.Handler, dist fs.FS) *gate {
return &gate{ops: ops, setup: setupSurface(ops, dist)}
}
func (g *gate) ServeHTTP(w http.ResponseWriter, r *http.Request) {
next := g.setup
if g.opened() {
next = g.ops
}
next.ServeHTTP(w, r)
}
// publish opens the gate. It is called once, after everything operations need
// has started, so a half-wired API is never served.
func (g *gate) publish() {
g.mu.Lock()
defer g.mu.Unlock()
g.open = true
}
func (g *gate) opened() bool {
g.mu.RLock()
defer g.mu.RUnlock()
return g.open
}
// check is the readiness check for the gate. An instance still waiting for its
// owner is alive but has nothing ready to serve, and that is not a crash.
func (g *gate) check(context.Context) error {
if g.opened() {
return nil
}
return errors.New("owner setup is incomplete")
}
// serveSurface returns what the binary serves: the health probes throughout,
// and the gate for everything else.
func serveSurface(checks *health.Registry, g *gate) *http.ServeMux {
checks.Register("setup", g.check)
mux := http.NewServeMux()
checks.Routes(mux)
mux.Handle("/", g)
return mux
}
// setupSurface answers the routes the setup page needs and refuses the rest.
func setupSurface(ops http.Handler, dist fs.FS) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if !setupRequest(r, dist) {
httpjson.Error(w, http.StatusNotFound, "not found")
return
}
ops.ServeHTTP(w, r)
})
}
// setupRequest is the whole routing decision while the gate is closed: the
// setup page and the files it loads, and the two account operations it calls.
// Nothing else passes, so a route inside the SPA is not a way in and neither is
// the wrong method on a route that is.
func setupRequest(r *http.Request, dist fs.FS) bool {
switch r.URL.Path {
case setUpAccountPath:
return r.Method == http.MethodPost
case authStatusPath:
return r.Method == http.MethodGet || r.Method == http.MethodHead
}
if r.Method != http.MethodGet && r.Method != http.MethodHead {
return false
}
return r.URL.Path == "/" || builtFile(r.URL.Path, dist)
}
// builtFile reports whether path names a file in the dashboard build. The
// page's assets and icon are files; a route inside the SPA is not, so a deep
// link cannot borrow the setup entry's page.
func builtFile(path string, dist fs.FS) bool {
if dist == nil {
return false
}
info, err := fs.Stat(dist, strings.TrimPrefix(path, "/"))
return err == nil && !info.IsDir()
}
// starter is what activation brings up: the operations Run wired.
type starter interface {
Start(context.Context) error
}
// activate waits for the owner setup transaction to commit, starts the
// operations, and then opens the gate. It runs on the process context, never
// the setup request's: the request that triggers it is answered long before the
// work it starts is done.
func activate(ctx context.Context, log *slog.Logger, setup <-chan struct{}, setUp bool, ops starter, g *gate) error {
if !setUp {
select {
case <-setup:
case <-ctx.Done():
return ctx.Err()
}
}
if err := ops.Start(ctx); err != nil {
return err
}
g.publish()
log.InfoContext(ctx, "owner setup is complete; serving operations")
return nil
}
+391
View File
@@ -0,0 +1,391 @@
package archie
import (
"context"
json "encoding/json/v2"
"errors"
"log/slog"
"net/http"
"net/http/httptest"
"strings"
"sync"
"sync/atomic"
"testing"
"testing/fstest"
"github.com/samcharles93/archie-core/internal/platform/health"
"github.com/samcharles93/archie-core/modules/dashboard"
"github.com/samcharles93/archie-core/modules/governance"
)
//nolint:gosec // G101: a fake credential, sent to prove it opens nothing before an owner exists.
const testAdminToken = "Bearer a-bootstrap-admin-token"
// testLog discards what the gate and activation log.
func testLog() *slog.Logger { return slog.New(slog.DiscardHandler) }
// reached records the requests that get past the gate, so a test can tell a
// refusal from a handler that ran.
type reached struct {
mu sync.Mutex
seen []string
}
func (r *reached) handle(w http.ResponseWriter, req *http.Request) {
r.mu.Lock()
r.seen = append(r.seen, req.Method+" "+req.URL.Path)
r.mu.Unlock()
w.WriteHeader(http.StatusOK)
}
func (r *reached) count() int {
r.mu.Lock()
defer r.mu.Unlock()
return len(r.seen)
}
func (r *reached) paths() []string {
r.mu.Lock()
defer r.mu.Unlock()
return append([]string(nil), r.seen...)
}
// testServer builds the surface Run serves, with a stand-in for the API beside
// the real dashboard handler. The stand-in answers the routes the setup page
// calls and records every other route a request can reach.
func testServer(t *testing.T) (*http.ServeMux, *reached, *gate) {
t.Helper()
hit := &reached{}
dist := fstest.MapFS{
"index.html": {Data: []byte("<html>archie setup</html>")},
"favicon.svg": {Data: []byte("<svg>")},
"assets/app.js": {Data: []byte("console.log(1)")},
}
ops := http.NewServeMux()
dashboard.Routes(ops, dist)
ops.HandleFunc("GET "+authStatusPath, func(w http.ResponseWriter, _ *http.Request) {
_, _ = w.Write([]byte(`{"setup_required":true,"user":null}`))
})
ops.HandleFunc("POST "+setUpAccountPath, func(w http.ResponseWriter, _ *http.Request) {
w.WriteHeader(http.StatusCreated)
})
ops.HandleFunc("GET /api/system/bootstrap", hit.handle)
ops.HandleFunc("POST /hooks/{source}", hit.handle)
ops.HandleFunc("GET /api/docs", hit.handle)
ops.HandleFunc("GET /api/openapi", hit.handle)
ops.HandleFunc("POST /api/auth/login", hit.handle)
ops.HandleFunc("GET /oauth2/login", hit.handle)
ops.HandleFunc("GET /api/tasks", hit.handle)
checks := health.NewRegistry()
checks.Register("database", func(context.Context) error { return nil })
g := newGate(ops, dist)
return serveSurface(checks, g), hit, g
}
func do(t *testing.T, served http.Handler, method, path string, withAdmin bool) *httptest.ResponseRecorder {
t.Helper()
req := httptest.NewRequestWithContext(context.Background(), method, path, nil)
if withAdmin {
req.Header.Set("Authorization", testAdminToken)
}
rec := httptest.NewRecorder()
served.ServeHTTP(rec, req)
return rec
}
// TestClosedGateServesOnlySetup guards the regression this issue was filed for:
// with no owner in the database, the bootstrap admin token still reached
// GET /api/system/bootstrap, and every other operational route with it.
func TestClosedGateServesOnlySetup(t *testing.T) {
tests := []struct {
name string
method string
path string
admin bool
status int
body string
}{
{name: "auth status", method: http.MethodGet, path: authStatusPath, status: http.StatusOK, body: `"setup_required":true`},
{name: "auth status by head", method: http.MethodHead, path: authStatusPath, status: http.StatusOK},
{name: "set up the owner", method: http.MethodPost, path: setUpAccountPath, status: http.StatusCreated},
{name: "the setup page", method: http.MethodGet, path: "/", status: http.StatusOK, body: "archie setup"},
{name: "a script the page loads", method: http.MethodGet, path: "/assets/app.js", status: http.StatusOK, body: "console.log(1)"},
{name: "the page icon", method: http.MethodGet, path: "/favicon.svg", status: http.StatusOK, body: "<svg>"},
{name: "liveness", method: http.MethodGet, path: "/healthz", status: http.StatusOK, body: "ok\n"},
// From here down nothing reaches a handler, credential or not.
{name: "operational API", method: http.MethodGet, path: "/api/system/bootstrap", status: http.StatusNotFound},
{name: "operational API with the admin token", method: http.MethodGet, path: "/api/system/bootstrap", admin: true, status: http.StatusNotFound},
{name: "another operational read", method: http.MethodGet, path: "/api/tasks", status: http.StatusNotFound},
{name: "another operational read with the admin token", method: http.MethodGet, path: "/api/tasks", admin: true, status: http.StatusNotFound},
{name: "webhook intake", method: http.MethodPost, path: "/hooks/github", status: http.StatusNotFound},
{name: "API document", method: http.MethodGet, path: "/api/docs", status: http.StatusNotFound},
{name: "OpenAPI document", method: http.MethodGet, path: "/api/openapi", status: http.StatusNotFound},
{name: "sign in", method: http.MethodPost, path: "/api/auth/login", status: http.StatusNotFound},
{name: "OIDC sign in", method: http.MethodGet, path: "/oauth2/login", status: http.StatusNotFound},
{name: "a route inside the SPA", method: http.MethodGet, path: "/tasks", status: http.StatusNotFound},
{name: "a route inside the SPA with a trailing slash", method: http.MethodGet, path: "/settings/status/", status: http.StatusNotFound},
{name: "setup by GET", method: http.MethodGet, path: setUpAccountPath, status: http.StatusNotFound},
{name: "status by POST", method: http.MethodPost, path: authStatusPath, status: http.StatusNotFound},
{name: "status with a trailing slash", method: http.MethodGet, path: authStatusPath + "/", status: http.StatusNotFound},
{name: "the page by POST", method: http.MethodPost, path: "/", status: http.StatusNotFound},
{name: "a script by POST", method: http.MethodPost, path: "/assets/app.js", status: http.StatusNotFound},
{name: "a file the build has no name for", method: http.MethodGet, path: "/assets/missing.js", status: http.StatusNotFound},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
served, hit, _ := testServer(t)
rec := do(t, served, tc.method, tc.path, tc.admin)
if rec.Code != tc.status {
t.Fatalf("%s %s: status = %d, want %d", tc.method, tc.path, rec.Code, tc.status)
}
if tc.body != "" && !strings.Contains(rec.Body.String(), tc.body) {
t.Fatalf("%s %s: body = %q, want it to contain %q", tc.method, tc.path, rec.Body.String(), tc.body)
}
if got := hit.count(); got != 0 {
t.Fatalf("%s %s: %d operational handlers ran, want none (reached %v)", tc.method, tc.path, got, hit.paths())
}
})
}
}
// TestOpenGateServesOperations guards the other half: the routes the gate
// refuses before setup are the ones that answer after it, so a refusal above
// is the gate's decision and not a missing route.
func TestOpenGateServesOperations(t *testing.T) {
tests := []struct {
name string
method string
path string
admin bool
status int
handled int
body string
}{
{name: "operational API with the admin token", method: http.MethodGet, path: "/api/system/bootstrap", admin: true, status: http.StatusOK, handled: 1},
{name: "another operational read", method: http.MethodGet, path: "/api/tasks", status: http.StatusOK, handled: 1},
{name: "webhook intake", method: http.MethodPost, path: "/hooks/github", status: http.StatusOK, handled: 1},
{name: "API document", method: http.MethodGet, path: "/api/docs", status: http.StatusOK, handled: 1},
{name: "OpenAPI document", method: http.MethodGet, path: "/api/openapi", status: http.StatusOK, handled: 1},
{name: "sign in", method: http.MethodPost, path: "/api/auth/login", status: http.StatusOK, handled: 1},
{name: "OIDC sign in", method: http.MethodGet, path: "/oauth2/login", status: http.StatusOK, handled: 1},
{name: "a route inside the SPA", method: http.MethodGet, path: "/tasks", status: http.StatusOK, body: "archie setup"},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
served, hit, g := testServer(t)
g.publish()
rec := do(t, served, tc.method, tc.path, tc.admin)
if rec.Code != tc.status {
t.Fatalf("%s %s: status = %d, want %d", tc.method, tc.path, rec.Code, tc.status)
}
if tc.body != "" && !strings.Contains(rec.Body.String(), tc.body) {
t.Fatalf("%s %s: body = %q, want it to contain %q", tc.method, tc.path, rec.Body.String(), tc.body)
}
if got := hit.count(); got != tc.handled {
t.Fatalf("%s %s: %d operational handlers ran, want %d (reached %v)", tc.method, tc.path, got, tc.handled, hit.paths())
}
})
}
}
func TestGateIsNotBypassedByPathTricks(t *testing.T) {
// A path the mux cleans is redirected before the gate sees it, and the
// cleaned path is refused in turn, so no spelling reaches a handler.
for _, path := range []string{"//api/system/bootstrap", "/api/../api/system/bootstrap", "/api/./system/bootstrap", "/api/auth/../system/bootstrap"} {
t.Run(path, func(t *testing.T) {
served, hit, _ := testServer(t)
rec := do(t, served, http.MethodGet, path, true)
if rec.Code == http.StatusOK {
t.Fatalf("%s: status 200, want a refusal", path)
}
if location := rec.Header().Get("Location"); location != "" {
if followed := do(t, served, http.MethodGet, location, true); followed.Code != http.StatusNotFound {
t.Fatalf("%s redirected to %s, which answered %d, want 404", path, location, followed.Code)
}
}
if got := hit.count(); got != 0 {
t.Fatalf("%s: %d operational handlers ran, want none (reached %v)", path, got, hit.paths())
}
})
}
}
func TestReadinessReportsSetupUntilOperationsStart(t *testing.T) {
// A missing owner is not a crash: liveness answers, readiness says why the
// instance serves nothing operational, and the dependency checks take over
// once operations are up.
served, _, g := testServer(t)
if rec := do(t, served, http.MethodGet, "/healthz", false); rec.Code != http.StatusOK {
t.Fatalf("liveness while gated: status = %d, want %d", rec.Code, http.StatusOK)
}
rec := do(t, served, http.MethodGet, "/readyz", false)
if rec.Code != http.StatusServiceUnavailable {
t.Fatalf("readiness while gated: status = %d, want %d", rec.Code, http.StatusServiceUnavailable)
}
var body struct {
Ready bool `json:"ready"`
Failures map[string]string `json:"failures"`
}
if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
t.Fatalf("decode readiness: %v (%s)", err, rec.Body.String())
}
if body.Ready {
t.Fatalf("readiness while gated: ready = true, want false")
}
if !strings.Contains(body.Failures["setup"], "owner setup") {
t.Fatalf("readiness while gated: failures = %v, want the setup check", body.Failures)
}
g.publish()
if rec := do(t, served, http.MethodGet, "/readyz", false); rec.Code != http.StatusOK {
t.Fatalf("readiness once operations serve: status = %d, want %d (%s)", rec.Code, http.StatusOK, rec.Body.String())
}
}
// fakeOperations stands in for the connectors, the access chain, the shipped
// workflow and the worker loops, and counts how often they would start.
type fakeOperations struct {
starts atomic.Int32
err error
}
func (f *fakeOperations) Start(context.Context) error {
f.starts.Add(1)
return f.err
}
func TestActivateStartsOperationsWhenSetupCommits(t *testing.T) {
// Nothing starts while the owner is missing, the setup page keeps answering
// so the operator can finish, and the commit starts everything once.
signal := governance.NewSetupSignal()
ops := &fakeOperations{}
served, hit, g := testServer(t)
done := make(chan error, 1)
go func() { done <- activate(context.Background(), testLog(), signal.Done(), false, ops, g) }()
if got := ops.starts.Load(); got != 0 {
t.Fatalf("starts before the commit = %d, want 0", got)
}
if g.opened() {
t.Fatalf("the gate is open before the commit")
}
if rec := do(t, served, http.MethodGet, authStatusPath, false); rec.Code != http.StatusOK {
t.Fatalf("auth status while waiting: status = %d, want %d", rec.Code, http.StatusOK)
}
if rec := do(t, served, http.MethodGet, "/api/system/bootstrap", true); rec.Code != http.StatusNotFound {
t.Fatalf("operational API while waiting: status = %d, want %d", rec.Code, http.StatusNotFound)
}
signal.Complete()
if err := <-done; err != nil {
t.Fatalf("activate: %v", err)
}
if got := ops.starts.Load(); got != 1 {
t.Fatalf("starts after the commit = %d, want 1", got)
}
if rec := do(t, served, http.MethodGet, "/api/system/bootstrap", true); rec.Code != http.StatusOK {
t.Fatalf("operational API after the commit: status = %d, want %d", rec.Code, http.StatusOK)
}
if got := hit.count(); got != 1 {
t.Fatalf("operational handlers after the commit = %d, want 1", got)
}
}
func TestConcurrentSetupCommitsStartOperationsOnce(t *testing.T) {
// Two setup transactions can't both commit, but the signal has to hold even
// if callers race: one set of workers, one open gate.
signal := governance.NewSetupSignal()
ops := &fakeOperations{}
_, _, g := testServer(t)
done := make(chan error, 1)
go func() { done <- activate(context.Background(), testLog(), signal.Done(), false, ops, g) }()
var completing sync.WaitGroup
for range 8 {
completing.Go(signal.Complete)
}
completing.Wait()
signal.Complete()
if err := <-done; err != nil {
t.Fatalf("activate: %v", err)
}
if got := ops.starts.Load(); got != 1 {
t.Fatalf("starts = %d, want 1", got)
}
}
func TestFailedStartLeavesTheGateClosed(t *testing.T) {
// A connector or policy failure must not leave an instance answering
// operational requests with half its wiring up.
signal := governance.NewSetupSignal()
ops := &fakeOperations{err: errors.New("connectors refused")}
served, hit, g := testServer(t)
signal.Complete()
if err := activate(context.Background(), testLog(), signal.Done(), false, ops, g); err == nil {
t.Fatalf("activate returned no error, want the start failure")
}
if g.opened() {
t.Fatalf("the gate opened after a failed start")
}
if rec := do(t, served, http.MethodGet, "/api/system/bootstrap", true); rec.Code != http.StatusNotFound {
t.Fatalf("operational API after a failed start: status = %d, want %d", rec.Code, http.StatusNotFound)
}
if got := hit.count(); got != 0 {
t.Fatalf("operational handlers after a failed start = %d, want none", got)
}
}
func TestCancelledBeforeSetupStartsNothing(t *testing.T) {
signal := governance.NewSetupSignal()
ops := &fakeOperations{}
_, _, g := testServer(t)
ctx, cancel := context.WithCancel(context.Background())
done := make(chan error, 1)
go func() { done <- activate(ctx, testLog(), signal.Done(), false, ops, g) }()
cancel()
if err := <-done; !errors.Is(err, context.Canceled) {
t.Fatalf("activate = %v, want context.Canceled", err)
}
if got := ops.starts.Load(); got != 0 {
t.Fatalf("starts after cancellation = %d, want 0", got)
}
if g.opened() {
t.Fatalf("the gate opened on a cancelled activation")
}
}
func TestCompletedSetupStartsWithoutWaiting(t *testing.T) {
// The restart after a completed setup: durable state says no owner is
// missing, so the process must not wait for a signal this run can never
// send.
signal := governance.NewSetupSignal() // never completed, as on a restart
ops := &fakeOperations{}
served, hit, g := testServer(t)
if err := activate(context.Background(), testLog(), signal.Done(), true, ops, g); err != nil {
t.Fatalf("activate: %v", err)
}
if got := ops.starts.Load(); got != 1 {
t.Fatalf("starts = %d, want 1", got)
}
if !g.opened() {
t.Fatalf("the gate is shut with setup already complete")
}
if rec := do(t, served, http.MethodGet, "/api/system/bootstrap", true); rec.Code != http.StatusOK {
t.Fatalf("operational API after a restart: status = %d, want %d", rec.Code, http.StatusOK)
}
if got := hit.count(); got != 1 {
t.Fatalf("operational handlers = %d, want 1", got)
}
}
+100
View File
@@ -0,0 +1,100 @@
package archie
import (
"context"
"fmt"
"log/slog"
"sync"
"github.com/samcharles93/archie-core/internal/platform/health"
"github.com/samcharles93/archie-core/modules/approvals"
"github.com/samcharles93/archie-core/modules/chat"
"github.com/samcharles93/archie-core/modules/connectors"
"github.com/samcharles93/archie-core/modules/deliveries"
"github.com/samcharles93/archie-core/modules/events"
"github.com/samcharles93/archie-core/modules/governance"
"github.com/samcharles93/archie-core/modules/judgement"
"github.com/samcharles93/archie-core/modules/memory"
"github.com/samcharles93/archie-core/modules/runs"
)
// operations is everything the gate holds back: the connectors, the access
// chain administrative writes are checked against, the workflow that ships with
// the binary, and the loops that do work. Run wires it at boot and Start brings
// it up, once, after owner setup has committed.
type operations struct {
log *slog.Logger
checks *health.Registry
settings *governance.Module
conns *connectors.Module
engine *runs.Engine
hear *events.Module
tell *deliveries.Module
talk *chat.Module
judge *judgement.Module
allow *approvals.Module
remember *memory.Module
workers sync.WaitGroup
}
// Start brings up every part of the binary that does work, in the order the
// rest of it expects: connectors first, then the access chain they are checked
// against, then the shipped workflow, then the loops. A failure returns with
// what started still running for the caller to shut down; nothing is left to
// report ready.
func (o *operations) Start(ctx context.Context) error {
if err := o.conns.Start(ctx); err != nil {
return fmt.Errorf("start connectors: %w", err)
}
o.checks.Register("connectors", o.conns.Ready)
access, err := startAccess(ctx, o.log, o.settings)
if err != nil {
return err
}
// Administrative writes are checked against the same live policy chain as
// every other request.
o.settings.UseAuthorizer(access)
o.talk.Use(chat.Deps{
People: o.settings, Access: access, Settings: o.settings, Toolbox: o.conns, Judge: o.judge,
Approver: o.allow, Memory: o.remember, Runs: o.engine, Notifier: o.tell,
})
// A workflow takes its context from the run handle, as a handler takes it
// from the request.
o.engine.Use(runs.Deps{
Settings: o.settings, Toolbox: o.conns, Judge: o.judge, Approver: o.allow,
Notifier: o.tell, Memory: o.remember,
})
if err := installStarter(ctx, o.engine); err != nil {
return err
}
for _, loop := range []func(context.Context){o.engine.Work, o.hear.Work, o.tell.Work, o.talk.Work} {
o.workers.Go(func() { loop(ctx) })
}
return nil
}
// Wait blocks until every loop Start began has returned.
func (o *operations) Wait() {
o.workers.Wait()
}
// installStarter puts the workflow that ships with the binary in place. It
// belongs to the organisation, so it waits until setup has created one.
func installStarter(ctx context.Context, engine *runs.Engine) error {
if _, err := engine.Install(ctx, orgID, "investigate", runs.InvestigateDocument(), "starter"); err != nil {
return fmt.Errorf("install the investigate workflow: %w", err)
}
return nil
}
// startAccess seeds the operating org's shipped role policies and returns the
// access policy chain, kept current as policies change.
func startAccess(ctx context.Context, log *slog.Logger, settings *governance.Module) (*governance.Live, error) {
if err := settings.EnsureShippedOrgPolicies(ctx, governance.DefaultOrgID); err != nil {
return nil, fmt.Errorf("seed the role policies: %w", err)
}
return governance.StartLive(ctx, settings.ListPolicies, settings.PoliciesVersion, log.With("module", "governance")), nil
}
+78 -62
View File
@@ -13,7 +13,6 @@ import (
"net/http"
"os"
"strconv"
"sync"
"time"
"github.com/google/uuid"
@@ -44,6 +43,11 @@ const shutdownGrace = 10 * time.Second
// Run boots the binary from the config at configPath and blocks until ctx ends
// or the server fails.
//
// An instance whose owner setup has not committed serves the setup page and
// nothing else: connectors, module routes, the shipped workflow and the worker
// loops all wait for that transaction. Durable state says whether it already
// happened, so a restart needs no setup form and serves operations at once.
func Run(ctx context.Context, configPath string) error {
log := slog.New(slog.NewJSONHandler(os.Stdout, nil)).With("service", "archie", "version", buildinfo.Version)
@@ -58,28 +62,79 @@ func Run(ctx context.Context, configPath string) error {
if err != nil {
return err
}
defer func() { _ = db.Close() }()
b, err := wire(log, configPath, cfg, db) //nolint:contextcheck // the API's guard derives its context from each request
if err != nil {
_ = db.Close()
return err
}
defer b.close()
// Durable state decides the first gate. A read that fails cannot rule setup
// out, so the gate stays closed: nothing operational runs on an instance
// that may have no owner. The failure is logged and readiness reports it,
// and a restart reads the state again.
required, setupErr := b.settings.AccountSetupRequired(ctx)
if setupErr != nil {
log.ErrorContext(ctx, "read whether owner setup is required", "err", setupErr)
}
setUp := setupErr == nil && !required
work, stop := context.WithCancel(ctx)
defer stop()
started := make(chan error, 1)
go func() {
err := activate(work, log, b.settings.SetupDone(), setUp, b.ops, b.gate)
if err != nil {
// Whatever half of the operations came up is no use without the rest,
// so the binary stops rather than serving a partial instance.
stop()
}
started <- err
}()
serveErr := serve(work, log, cfg.Listen, b.served)
stop()
startErr := <-started
// Every loop activation began has returned before the caller closes the
// connectors and the database.
b.ops.Wait()
if startErr != nil && !errors.Is(startErr, context.Canceled) {
return startErr
}
return serveErr
}
// binary is a wired instance: the surface it serves, and what waits for owner
// setup before it does any work.
type binary struct {
db *sqlx.DB
conns *connectors.Module
gate *gate
served http.Handler
settings *governance.Module
ops *operations
}
// wire builds every module and registers its routes. Nothing operational
// starts here: the routes are wired on a mux the gate holds back, and Start
// brings them up once owner setup has committed.
func wire(log *slog.Logger, configPath string, cfg Config, db *sqlx.DB) (*binary, error) {
checks := health.NewRegistry()
checks.Register("database", db.PingContext)
mux := http.NewServeMux()
checks.Routes(mux)
runtime.RegisterBuiltinClasses()
settings := governance.NewModule(db, log.With("module", "governance"), orgID)
api := httpapi.New(mux, buildinfo.Version, settings.Authenticator(cfg.AdminTokenSHA256)) //nolint:contextcheck // the middleware derives from the request's context
mux := http.NewServeMux()
api := httpapi.New(mux, buildinfo.Version, settings.Authenticator(cfg.AdminTokenSHA256))
conns, err := connectors.NewModule(db, log.With("module", "connectors"), orgID, connectors.Sealing{
Identity: cfg.AgeIdentity, Backups: cfg.AgeBackupRecipients,
})
if err != nil {
return err
return nil, err
}
defer conns.Close()
if err := conns.Start(ctx); err != nil {
return err
}
checks.Register("connectors", conns.Ready)
// A model's key is a credential name resolved through the sealed store.
settings.UseCredentials(conns)
@@ -108,17 +163,6 @@ func Run(ctx context.Context, configPath string) error {
hear.Routes(mux)
judge := newJudgement(db, log, conns, classes, policies, settings, hear)
remember := memory.NewModule(db, orgID)
if err := useWorkflows(ctx, engine, runs.Deps{Settings: settings, Toolbox: conns, Judge: judge, Approver: allow, Notifier: tell, Memory: remember}); err != nil {
return err
}
access, err := startAccess(ctx, log, settings)
if err != nil {
return err
}
// Administrative writes are checked against the same live policy chain as
// every other request.
settings.UseAuthorizer(access)
talk.Use(chat.Deps{People: settings, Access: access, Settings: settings, Toolbox: conns, Judge: judge, Approver: allow, Memory: remember, Runs: engine, Notifier: tell})
apiModules{
settings: settings, conns: conns, system: sys, tell: tell, allow: allow, classes: classes, policies: policies,
hear: hear, judge: judge, engine: engine, chat: talk, drafts: drafts.NewModule(db, log.With("module", "drafts"), orgID, hear, engine, policies),
@@ -126,29 +170,20 @@ func Run(ctx context.Context, configPath string) error {
}.register(api)
dashboard.Routes(mux, ui.DistDirFS)
return serveWithWork(ctx, log, cfg.Listen, mux, engine.Work, hear.Work, tell.Work, talk.Work)
g := newGate(mux, ui.DistDirFS)
return &binary{
db: db, conns: conns, gate: g, served: serveSurface(checks, g), settings: settings,
ops: &operations{
log: log, checks: checks, settings: settings, conns: conns, engine: engine, hear: hear,
tell: tell, talk: talk, judge: judge, allow: allow, remember: remember,
},
}, nil
}
// serveWithWork serves mux while the loops run, and stops the loops once it
// returns.
func serveWithWork(ctx context.Context, log *slog.Logger, addr string, mux *http.ServeMux, loops ...func(context.Context)) error {
ctx, stop := context.WithCancel(ctx)
defer stop()
wait := work(ctx, loops...)
err := serve(ctx, log, addr, mux)
stop()
wait()
return err
}
// useWorkflows gives the engine what workflow steps use and installs the
// workflow that ships with the binary.
func useWorkflows(ctx context.Context, engine *runs.Engine, deps runs.Deps) error {
engine.Use(deps)
if _, err := engine.Install(ctx, orgID, "investigate", runs.InvestigateDocument(), "starter"); err != nil {
return fmt.Errorf("install the investigate workflow: %w", err)
}
return nil
// close stops the connectors and then the database.
func (b *binary) close() {
b.conns.Close()
_ = b.db.Close()
}
// answers wakes whatever asked for an approval: a chat turn, or else the run
@@ -165,16 +200,6 @@ func (a answers) Signal(ctx context.Context, id uuid.UUID, key string, payload j
return a.runs.Signal(ctx, id, key, payload)
}
// work runs each loop until ctx ends and returns a function that waits for
// them all.
func work(ctx context.Context, loops ...func(context.Context)) func() {
var workers sync.WaitGroup
for _, loop := range loops {
workers.Go(func() { loop(ctx) })
}
return workers.Wait
}
// newJudgement returns the judgement module with its hard rules, data guards
// and change-request rules. A failed action tightens its class.
func newJudgement(db *sqlx.DB, log *slog.Logger, conns *connectors.Module, classes *judgement.Classes, policies *judgement.Policies, settings *governance.Module, heard judgement.Events) *judgement.Module {
@@ -193,15 +218,6 @@ func newJudgement(db *sqlx.DB, log *slog.Logger, conns *connectors.Module, class
return judge
}
// startAccess seeds the operating org's shipped role policies and returns the
// access policy chain, kept current as policies change.
func startAccess(ctx context.Context, log *slog.Logger, settings *governance.Module) (*governance.Live, error) {
if err := settings.EnsureShippedOrgPolicies(ctx, governance.DefaultOrgID); err != nil {
return nil, fmt.Errorf("seed the role policies: %w", err)
}
return governance.StartLive(ctx, settings.ListPolicies, settings.PoliciesVersion, log.With("module", "governance")), nil
}
// orgID is the one organisation until hosting is multi-tenant.
const orgID = "default"
+2 -1
View File
@@ -257,12 +257,13 @@ type Module struct {
credentials Credentials
authorizer Authorizer
oidc *oidcLogin
setup *SetupSignal
}
// NewModule returns the governance module for orgID. The ai-sdk provider
// classes must already be registered.
func NewModule(db *sqlx.DB, log *slog.Logger, orgID string) *Module {
return &Module{orgID: orgID, store: store.New(db), log: log, oidc: &oidcLogin{}}
return &Module{orgID: orgID, store: store.New(db), log: log, oidc: &oidcLogin{}, setup: NewSetupSignal()}
}
// UseCredentials gives the module the sealed store a model's key reference
+34
View File
@@ -0,0 +1,34 @@
package governance
import "sync"
// SetupSignal reports that the owner setup transaction has committed. The
// composition root waits on it instead of polling the database for the change,
// and it fires once however many callers ask.
type SetupSignal struct {
once sync.Once
done chan struct{}
}
// NewSetupSignal returns a signal for a setup that has not committed yet.
func NewSetupSignal() *SetupSignal {
return &SetupSignal{done: make(chan struct{})}
}
// Complete records the commit. A second call, sequential or concurrent,
// changes nothing. A nil signal is a module built without durable state, as
// the API document is, and records nothing.
func (s *SetupSignal) Complete() {
if s == nil {
return
}
s.once.Do(func() { close(s.done) })
}
// Done is closed once the setup has committed.
func (s *SetupSignal) Done() <-chan struct{} {
if s == nil {
return nil
}
return s.done
}
+11
View File
@@ -344,6 +344,11 @@ func (m *Module) AccountSetupRequired(ctx context.Context) (bool, error) {
return m.store.AccountSetupRequired(ctx)
}
// SetupDone is closed once the owner setup transaction has committed.
func (m *Module) SetupDone() <-chan struct{} {
return m.setup.Done()
}
// RegisterAccount creates a user account, bootstrapping the operating org when bootstrap is true.
func (m *Module) RegisterAccount(ctx context.Context, r AccountRegistration, bootstrap bool) (Identity, error) {
role, orgID, err := registrationScope(ctx, &r, bootstrap)
@@ -375,6 +380,12 @@ func (m *Module) RegisterAccount(ctx context.Context, r AccountRegistration, boo
if err != nil {
return Identity{}, mapIdentityErr(err)
}
if bootstrap {
// The owner is in durable state now. Whatever waits on this signal starts
// operations, so it is sent only after the transaction committed: a failed
// attempt returns above and leaves it closed.
m.setup.Complete()
}
return identityFromRow(row), nil
}