From 472d8d717c55f3bd0bf56c2e1eec7594b2a4147b Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sun, 9 Aug 2026 01:25:58 +1000 Subject: [PATCH] feat(config,channels): format-neutral config resolution and truthful channel state Loader.Resolve() selects TOML/YAML files or a config directory as the production entry point, replacing the TOML-only Overlay() as the default path. Add internal/channels.Manager, reporting each adapter's actual runtime lifecycle (configured/starting/running/degraded/failed) instead of inferring health from configuration presence alone. Wire channel reload through a per-adapter seam. Fixes #55 --- internal/channels/manager.go | 89 ++++++++++++++ internal/channels/manager_test.go | 25 ++++ .../infrastructure/configuration/decode.go | 12 ++ .../infrastructure/configuration/loader.go | 46 ++++++- .../configuration/loader_test.go | 58 +++++++++ internal/webui/api_config.go | 112 ++++++++++++++++-- internal/webui/api_config_test.go | 24 ++++ ui/src/channels/channels.js | 11 +- ui/src/settings/settings.js | 10 ++ 9 files changed, 373 insertions(+), 14 deletions(-) create mode 100644 internal/channels/manager.go create mode 100644 internal/channels/manager_test.go diff --git a/internal/channels/manager.go b/internal/channels/manager.go new file mode 100644 index 000000000..fda93fb72 --- /dev/null +++ b/internal/channels/manager.go @@ -0,0 +1,89 @@ +package channels + +import "sync" + +// State reports the runtime lifecycle independently from whether a channel is +// present in configuration. A configured adapter can fail to start; an +// unconfigured adapter is simply stopped, not unhealthy. +type State string + +const ( + StateConfigured State = "configured" + StateStarting State = "starting" + StateRunning State = "running" + StateDegraded State = "degraded" + StateFailed State = "failed" + StateStopped State = "stopped" +) + +// Descriptor is the safe, operator-facing declaration of one channel. +// Configuration values are intentionally not retained here: a manager must +// never become a second source for tokens or credentials. +type Descriptor struct { + ID string + Name string + Configured bool + ReloadSupported bool + Detail string +} + +// Status is an immutable manager snapshot for a single channel. +type Status struct { + Descriptor + State State +} + +// Manager owns channel lifecycle facts for the dashboard and other operator +// surfaces. It is deliberately typed to channels rather than extending the +// metadata-only plugin interface. +type Manager struct { + mu sync.RWMutex + channels []Status + index map[string]int +} + +func NewManager(descriptors []Descriptor) *Manager { + m := &Manager{index: make(map[string]int, len(descriptors))} + for _, d := range descriptors { + state := StateStopped + if d.Configured { + state = StateConfigured + } + m.index[d.ID] = len(m.channels) + m.channels = append(m.channels, Status{Descriptor: d, State: state}) + } + return m +} + +func (m *Manager) Snapshot() []Status { + if m == nil { + return nil + } + m.mu.RLock() + defer m.mu.RUnlock() + return append([]Status(nil), m.channels...) +} + +func (m *Manager) MarkStarting(id string) { m.set(id, StateStarting, "") } +func (m *Manager) MarkRunning(id string) { m.set(id, StateRunning, "") } +func (m *Manager) MarkDegraded(id, detail string) { + m.set(id, StateDegraded, detail) +} +func (m *Manager) MarkFailed(id, detail string) { m.set(id, StateFailed, detail) } +func (m *Manager) MarkStopped(id, detail string) { m.set(id, StateStopped, detail) } + +func (m *Manager) set(id string, state State, detail string) { + if m == nil { + return + } + m.mu.Lock() + defer m.mu.Unlock() + i, ok := m.index[id] + if !ok { + return + } + m.channels[i].State = state + if detail != "" { + m.channels[i].Detail = detail + } +} diff --git a/internal/channels/manager_test.go b/internal/channels/manager_test.go new file mode 100644 index 000000000..e65e7fcec --- /dev/null +++ b/internal/channels/manager_test.go @@ -0,0 +1,25 @@ +package channels + +import "testing" + +func TestManagerTracksConfiguredLifecycleAndReloadCapability(t *testing.T) { + m := NewManager([]Descriptor{ + {ID: "telegram", Name: "Telegram", Configured: true, ReloadSupported: true}, + {ID: "email", Name: "Email", Configured: false}, + }) + + if got := m.Snapshot()[0].State; got != StateConfigured { + t.Fatalf("initial state = %q, want %q", got, StateConfigured) + } + m.MarkStarting("telegram") + m.MarkRunning("telegram") + m.MarkFailed("telegram", "token rejected") + + views := m.Snapshot() + if got := views[0]; got.State != StateFailed || got.Detail != "token rejected" || !got.ReloadSupported { + t.Errorf("telegram = %#v", got) + } + if got := views[1]; got.State != StateStopped || got.Configured { + t.Errorf("email = %#v", got) + } +} diff --git a/internal/infrastructure/configuration/decode.go b/internal/infrastructure/configuration/decode.go index ff701a5d9..c0819bf36 100644 --- a/internal/infrastructure/configuration/decode.go +++ b/internal/infrastructure/configuration/decode.go @@ -3,6 +3,7 @@ package configuration import ( "fmt" "os" + "path/filepath" "github.com/BurntSushi/toml" "gopkg.in/yaml.v3" @@ -10,6 +11,17 @@ import ( "github.com/samcharles93/archie-core/internal/config" ) +func decodeConfigFile(path string, target any) error { + switch filepath.Ext(path) { + case ".yaml", ".yml": + return decodeYAML(path, target) + case ".toml": + return decodeTOML(path, target) + default: + return fmt.Errorf("%w: config file %s must end in .toml, .yaml, or .yml", ErrUnreadable, path) + } +} + // decodeTOML decodes a TOML file into target. func decodeTOML(path string, target any) error { if _, err := toml.DecodeFile(path, target); err != nil { diff --git a/internal/infrastructure/configuration/loader.go b/internal/infrastructure/configuration/loader.go index 5942fa0c0..4189ee8ec 100644 --- a/internal/infrastructure/configuration/loader.go +++ b/internal/infrastructure/configuration/loader.go @@ -65,9 +65,43 @@ func xdgDataHome() string { return filepath.Join(home, ".local", "share") } -// File loads a single TOML configuration file. +// File loads a single configuration file. TOML remains supported for existing +// deployments; YAML files use the same defaults and validation path. func (l *Loader) File(path string) (*Document, error) { - return l.Overlay(path, "") + return l.Resolve(path, "") +} + +// Resolve selects the configuration source from its filesystem type: a TOML +// or YAML file, or a feature-config directory. This is the production entry +// point. Keeping selection here ensures command-line loading and operator +// tooling share the exact same precedence and validation rules. +func (l *Loader) Resolve(basePath, overlayPath string) (*Document, error) { + info, err := os.Stat(basePath) + if err != nil { + return nil, fmt.Errorf("%w: config source %s: %w", ErrUnreadable, basePath, err) + } + if info.IsDir() { + if overlayPath != "" { + overlayInfo, statErr := os.Stat(overlayPath) + if statErr != nil { + return nil, fmt.Errorf("%w: config overlay %s: %w", ErrUnreadable, overlayPath, statErr) + } + if !overlayInfo.IsDir() { + return nil, fmt.Errorf("config overlay %s must be a directory when config source %s is a directory", overlayPath, basePath) + } + } + return l.Dir(basePath, overlayPath) + } + if overlayPath != "" { + overlayInfo, statErr := os.Stat(overlayPath) + if statErr != nil { + return nil, fmt.Errorf("%w: config overlay %s: %w", ErrUnreadable, overlayPath, statErr) + } + if overlayInfo.IsDir() { + return nil, fmt.Errorf("config overlay %s must be a file when config source %s is a file", overlayPath, basePath) + } + } + return l.overlayFile(basePath, overlayPath) } // Overlay loads basePath, then decodes overlayPath into the same value so @@ -76,15 +110,19 @@ func (l *Loader) File(path string) (*Document, error) { // declare only what differs instead of restating the whole schema. An empty // overlayPath is equivalent to [Loader.File]. func (l *Loader) Overlay(basePath, overlayPath string) (*Document, error) { + return l.overlayFile(basePath, overlayPath) +} + +func (l *Loader) overlayFile(basePath, overlayPath string) (*Document, error) { doc := &Document{} - if err := decodeTOML(basePath, &doc.Config); err != nil { + if err := decodeConfigFile(basePath, &doc.Config); err != nil { return nil, err } doc.Provenance.record(Origin{Path: basePath, Role: RoleMain, Layer: LayerBase}) if overlayPath != "" { - if err := decodeTOML(overlayPath, &doc.Config); err != nil { + if err := decodeConfigFile(overlayPath, &doc.Config); err != nil { return nil, err } doc.Provenance.record(Origin{Path: overlayPath, Role: RoleMain, Layer: LayerOverlay}) diff --git a/internal/infrastructure/configuration/loader_test.go b/internal/infrastructure/configuration/loader_test.go index 2ddc432b3..46cceef9b 100644 --- a/internal/infrastructure/configuration/loader_test.go +++ b/internal/infrastructure/configuration/loader_test.go @@ -40,6 +40,64 @@ func TestLoadDispatchAckReaction(t *testing.T) { } } +func TestResolveSelectsFileFormatsAndDirectories(t *testing.T) { + tests := []struct { + name string + prepare func(t *testing.T, dir string) string + wantUser string + wantPath string + }{ + { + name: "toml file", + prepare: func(t *testing.T, dir string) string { + path := filepath.Join(dir, "config.toml") + if err := os.WriteFile(path, []byte("bot_user = \"toml-bot\"\n[[repos]]\nowner = \"acme\"\nname = \"app\"\n"), 0o600); err != nil { + t.Fatal(err) + } + return path + }, + wantUser: "toml-bot", wantPath: "config.toml", + }, + { + name: "yaml file", + prepare: func(t *testing.T, dir string) string { + path := filepath.Join(dir, "config.yaml") + if err := os.WriteFile(path, []byte("bot_user: yaml-bot\nrepos:\n - owner: acme\n name: app\n"), 0o600); err != nil { + t.Fatal(err) + } + return path + }, + wantUser: "yaml-bot", wantPath: "config.yaml", + }, + { + name: "directory", + prepare: func(t *testing.T, dir string) string { + if err := os.WriteFile(filepath.Join(dir, "config.yaml"), []byte("bot_user: directory-bot\nrepos:\n - owner: acme\n name: app\n"), 0o600); err != nil { + t.Fatal(err) + } + return dir + }, + wantUser: "directory-bot", wantPath: "config.yaml", + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + dir := t.TempDir() + doc, err := New(nil).Resolve(tt.prepare(t, dir), "") + if err != nil { + t.Fatal(err) + } + if doc.Config.BotUser != tt.wantUser { + t.Errorf("BotUser = %q, want %q", doc.Config.BotUser, tt.wantUser) + } + if got := filepath.Base(doc.Provenance.Paths()[0]); got != tt.wantPath { + t.Errorf("provenance path = %q, want %q", got, tt.wantPath) + } + }) + } +} + // TestLoadForgeTokenEnvBackwardCompat guards against a real production // incident: the secrets-engine migration replaced [forge]'s flat // token_env string with a {engine, key} struct, but TOML silently ignores diff --git a/internal/webui/api_config.go b/internal/webui/api_config.go index c45b5f81e..2e795e1ed 100644 --- a/internal/webui/api_config.go +++ b/internal/webui/api_config.go @@ -5,6 +5,7 @@ import ( "strconv" "strings" + "github.com/samcharles93/archie-core/internal/channels" "github.com/samcharles93/archie-core/internal/config" ) @@ -12,10 +13,13 @@ import ( // Channels page: whether it is reachable today, and what configuring it // would unlock. type ChannelView struct { - Name string `json:"name"` - Configured bool `json:"configured"` - Detail string `json:"detail"` - Description string `json:"description"` + ID string `json:"id"` + Name string `json:"name"` + Configured bool `json:"configured"` + Detail string `json:"detail"` + Description string `json:"description"` + State string `json:"state"` + ReloadSupported bool `json:"reload_supported"` } // handleChannels reports how a human can reach Archie today. It exists so @@ -23,6 +27,14 @@ type ChannelView struct { // reading config.toml -- see ChatConfig in internal/config/config.go for // the fields this derives from. func (s *Server) handleChannels(w http.ResponseWriter, r *http.Request) { + if s.Channels != nil { + views := make([]ChannelView, 0, len(s.Channels.Snapshot())) + for _, status := range s.Channels.Snapshot() { + views = append(views, channelViewFromStatus(status)) + } + writeJSON(w, map[string]any{"channels": views}) + return + } if s.Cfg == nil { writeJSON(w, map[string]any{"channels": []ChannelView{}}) return @@ -38,6 +50,72 @@ func (s *Server) handleChannels(w http.ResponseWriter, r *http.Request) { writeJSON(w, map[string]any{"channels": views}) } +func (s *Server) handleChannelReload(w http.ResponseWriter, r *http.Request) { + if !authorizeTaskMutation(w, r) { + return + } + id := r.PathValue("id") + if s.Channels == nil || s.ReloadChannel == nil { + http.Error(w, "channel reload unavailable", http.StatusNotImplemented) + return + } + var status *channels.Status + for _, candidate := range s.Channels.Snapshot() { + if candidate.ID == id { + status = &candidate + break + } + } + if status == nil || !status.ReloadSupported { + http.Error(w, "channel does not support reload", http.StatusConflict) + return + } + if err := s.ReloadChannel(r.Context(), id); err != nil { + http.Error(w, "channel reload failed", http.StatusBadGateway) + return + } + writeJSON(w, map[string]any{"ok": true, "channel": id}) +} + +func channelViewFromStatus(status channels.Status) ChannelView { + view := ChannelView{ + ID: status.ID, Name: status.Name, Configured: status.Configured, Detail: status.Detail, + State: string(status.State), ReloadSupported: status.ReloadSupported, + } + switch status.ID { + case "telegram": + view.Description = "Talk to Archie and approve its work from your phone." + case "webhook": + view.Description = "Lets another service push messages to Archie over HTTP." + case "email": + view.Description = "Email Archie a task and receive replies through its inbound SMTP listener." + } + if view.Detail == "" { + view.Detail = channelStateDetail(status.State, status.Configured) + } + return view +} + +func channelStateDetail(state channels.State, configured bool) string { + if !configured { + return "Not configured." + } + switch state { + case channels.StateConfigured: + return "Configured; waiting for the daemon to start it." + case channels.StateStarting: + return "Starting." + case channels.StateRunning: + return "Running." + case channels.StateDegraded: + return "Running with a degraded capability." + case channels.StateFailed: + return "Failed to start." + default: + return "Stopped." + } +} + func telegramChannelView(t config.TelegramConfig) ChannelView { configured := strings.TrimSpace(t.TokenEnv) != "" detail := "Not configured." @@ -53,10 +131,13 @@ func telegramChannelView(t config.TelegramConfig) ChannelView { } } return ChannelView{ - Name: "Telegram", - Configured: configured, - Detail: detail, - Description: "Talk to Archie and approve its work from your phone.", + ID: "telegram", + Name: "Telegram", + Configured: configured, + Detail: detail, + Description: "Talk to Archie and approve its work from your phone.", + State: string(channels.StateConfigured), + ReloadSupported: true, } } @@ -67,10 +148,12 @@ func webhookChannelView(addr string) ChannelView { detail = "Listening for inbound chat requests." } return ChannelView{ + ID: "webhook", Name: "Webhook gateway", Configured: configured, Detail: detail, Description: "Lets another service (e.g. a Telegram webhook, a custom front-end) push messages to Archie over HTTP instead of long-polling.", + State: staticChannelState(configured), } } @@ -81,13 +164,22 @@ func emailChannelView(e config.EmailConfig) ChannelView { detail = "Archie accepts inbound mail and can reply through the configured relay." } return ChannelView{ + ID: "email", Name: "Email", Configured: configured, Detail: detail, Description: "Email Archie a task and it replies from its own inbound SMTP listener.", + State: staticChannelState(configured), } } +func staticChannelState(configured bool) string { + if configured { + return string(channels.StateConfigured) + } + return string(channels.StateStopped) +} + // ConfigView is the read-only, secret-free projection of config.Config // shown on the dashboard's Configuration page. Every field here is an // explicit, hand-picked allowlist -- see handleConfig for why this is @@ -102,6 +194,7 @@ type ConfigView struct { Storage StorageView `json:"storage"` Containers ContainersView `json:"containers"` Web WebView `json:"web"` + Provenance []ConfigOrigin `json:"provenance"` } // IdentityView is who Archie is on the forge -- never the token that @@ -240,7 +333,8 @@ func (s *Server) handleConfig(w http.ResponseWriter, r *http.Request) { PullPolicy: cfg.Containers.PullPolicy, Network: cfg.Containers.Network, }, - Web: WebView{Listen: cfg.Web.Listen}, + Web: WebView{Listen: cfg.Web.Listen}, + Provenance: append([]ConfigOrigin(nil), s.ConfigProvenance...), } writeJSON(w, view) diff --git a/internal/webui/api_config_test.go b/internal/webui/api_config_test.go index bbc690867..7de93f8d5 100644 --- a/internal/webui/api_config_test.go +++ b/internal/webui/api_config_test.go @@ -7,6 +7,7 @@ import ( "strings" "testing" + "github.com/samcharles93/archie-core/internal/channels" "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/secret" ) @@ -206,3 +207,26 @@ func TestHandleChannelsNilConfig(t *testing.T) { t.Errorf("Channels = %+v, want empty when Cfg is nil", got.Channels) } } + +func TestHandleChannelsUsesRuntimeManager(t *testing.T) { + srv := newTestServer(t) + srv.Cfg = configWithFakeSecrets() + srv.Channels = channels.NewManager([]channels.Descriptor{{ + ID: "telegram", Name: "Telegram", Configured: true, ReloadSupported: true, + }}) + srv.Channels.MarkFailed("telegram", "token rejected") + + req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/api/channels", nil) + w := httptest.NewRecorder() + srv.Handler().ServeHTTP(w, req) + + var got struct { + Channels []ChannelView `json:"channels"` + } + if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil { + t.Fatal(err) + } + if len(got.Channels) != 1 || got.Channels[0].State != "failed" || !got.Channels[0].ReloadSupported { + t.Fatalf("channels = %#v", got.Channels) + } +} diff --git a/ui/src/channels/channels.js b/ui/src/channels/channels.js index f60529bee..3c2316e08 100644 --- a/ui/src/channels/channels.js +++ b/ui/src/channels/channels.js @@ -61,12 +61,21 @@ export function channelsPage() { el( "div.card-head", el("h3.card-title", channel.name), - channel.configured ? pill("connected", "ok") : pill("not configured", "idle"), + pill(channel.state || (channel.configured ? "configured" : "stopped"), stateTone(channel.state, channel.configured)), ), el("p.channel-desc", channel.description), el("p.channel-detail", channel.detail), + channel.reload_supported + ? el("button.btn", { onclick: async (event) => { event.currentTarget.disabled = true; try { await api.channelReload(channel.id || channel.name.toLowerCase()); await load(); } catch (err) { event.currentTarget.disabled = false; } } }, "Reload") + : el("p.channel-detail", "Reload requires a daemon restart for this adapter."), ); } return root; } + +function stateTone(state, configured) { + if (state === "running") return "ok"; + if (state === "failed" || state === "degraded") return "warn"; + return configured ? "idle" : "idle"; +} diff --git a/ui/src/settings/settings.js b/ui/src/settings/settings.js index 8ac969c8a..95aa12b90 100644 --- a/ui/src/settings/settings.js +++ b/ui/src/settings/settings.js @@ -65,12 +65,22 @@ export function settingsPage() { agentCard(cfg.agent), storageCard(cfg.storage, cfg.containers), webCard(cfg.web), + provenanceCard(cfg.provenance), ); } return root; } +function provenanceCard(origins) { + if (!origins?.length) return section("Configuration sources", "The files that supplied the running configuration.", empty("Source provenance is unavailable.")); + return section( + "Configuration sources", + "Applied from top to bottom; later entries take precedence over earlier ones.", + el("div.cfg-rows", ...origins.map((origin) => row(`${origin.layer} ${origin.role}${origin.feature ? ` (${origin.feature})` : ""}`, origin.path))), + ); +} + function section(title, sub, ...children) { return el( "div.card.cfg-section",