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:
1 parent
0d500a4ca9
commit
472d8d717c
9 files changed
+373
-14
No files matched your search
@@ -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
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
@@ -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";
|
||||
}
|
||||
@@ -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",
|
||||
|
||||
Reference in new issue
Block a user