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
This commit is contained in:
sam committed 2026-08-09 01:25:58 +10:00
1 parent 0d500a4ca9
commit 472d8d717c
9 files changed
+373 -14

No files matched your search

+89
View File
@@ -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
}
}
+25
View File
@@ -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)
}
}
@@ -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 {
@@ -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})
@@ -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
+103 -9
View File
@@ -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)
+24
View File
@@ -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)
}
}
+10 -1
View File
@@ -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";
}
+10
View File
@@ -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",