Files
archie/internal/app/archiemessaging/compose.go
T
sam d6f526ce4f feat(state): carry channel lifecycle from the Messaging Service to the dashboard
archie-core-8cda.6.8's carrier. The service now records channel lifecycle and has
nowhere to put it: /api/channels answered with nothing because
webui.Server.Channels had no production source, and reload answered 501 for the
same reason. This adds the surface the register decided on, following the split
archie-core-ymut established for config snapshots -- a pair of administrative RPCs
whose writer is one process and whose reader is the UI -- and wires both ends.

Wire and store: PutChannelStatus / ListChannelStatus, with ChannelStatus carrying
id, name, state, detail, configured, reload_supported and observed_at. The store
holds one row per channel and replaces the reported set, so a channel the reporter
no longer mentions is deleted rather than left standing as a stale "running"; an
empty report clears the table, because hosting no channels is a fact worth
reporting. A row without an id is refused: it could never be replaced or removed
by a later report.

Writer: the service publishes on every lifecycle transition through a coalescing
signal -- a burst of transitions is one write, since a reader only wants the latest
state of every channel -- plus a start-up report and a final report after shutdown,
so a stopped service leaves the store honest. A failed write is logged and retried
on the next signal; the dashboard losing channel state is worth a warning and never
worth failing a channel start over.

Reader: webui.Server.Channels becomes a source rather than a concrete manager, and
webui.RemoteChannelStatus reads the store the way RemoteConfigView reads the config
snapshot. A store it cannot reach reports nothing rather than a stale "running",
and a state the reader does not recognise is carried through rather than dropped.

The contract's own index gains the group in the same change that adds the RPCs --
a surface the grouped table does not list is one nobody finds -- and the count moves
to 51. The register records why the surface is the State Store rather than a
resource kind, and why reload gets its own surface rather than a field here: reading
status must not be able to retrigger an action, a transient request is not
distinguishable from state once anything polls it, and it would invert the
writer/reader relationship the precedent establishes.

Verified: task check exit 0. New coverage: the store's replace-the-set semantics
and its refusal of an id-less row, the reader's mapping including an unknown state,
and the publisher's start-up, transition and final reports.
2026-09-22 08:04:44 +10:00

240 lines
7.6 KiB
Go

package archiemessaging
import (
"context"
"fmt"
"log/slog"
"net"
"strconv"
"sync"
"github.com/samcharles93/archie-core/internal/channels"
"github.com/samcharles93/archie-core/internal/channels/email"
"github.com/samcharles93/archie-core/internal/channels/status"
"github.com/samcharles93/archie-core/internal/channels/telegram"
"github.com/samcharles93/archie-core/internal/channels/webhook"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/health"
"github.com/samcharles93/archie-core/internal/domain/messaging"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
"github.com/samcharles93/archie-core/internal/secret"
)
type deps struct {
// ChannelStatus is where the service publishes channel lifecycle for the
// dashboard. Optional: nil leaves the report in-process only.
ChannelStatus storecontract.ChannelStatusStore
Config ResolvedConfig
Log *slog.Logger
Chat messaging.ChatContract
Health *health.Registry
Settings *messaging.SettingsCommand
}
type channelInstance struct {
name string
channel channels.Channel
}
// Service manages the lifecycle of the extracted Messaging Service and its
// channel adapters.
type Service struct {
// status owns channel lifecycle facts, one entry per composed channel. It is
// the single writer channels report through (see lifecycleFor), and the
// producer a dashboard surface reads.
status *status.Manager
// statusWriter publishes that report where the dashboard reads it. Nil means
// this composition has no store to publish to, which is the honest state for a
// test or a process run without one.
statusWriter storecontract.ChannelStatusStore
// publish coalesces a burst of transitions into one write: a reader only ever
// wants the latest state of every channel.
publish chan struct{}
cfg ResolvedConfig
log *slog.Logger
chat messaging.ChatContract
health *health.Registry
channels []channelInstance
mu sync.Mutex
running bool
stop func()
}
// compose builds the Service from resolved configuration. ctx is the service
// lifetime: seams a channel invokes later (the Gateway version lookup) derive
// their calls from it, so a shutdown cancels them. A channel whose
// configuration is present but invalid fails composition rather than being
// dropped: a front-end the operator configured must never silently not run.
func compose(ctx context.Context, d deps) (*Service, error) {
srv := &Service{
cfg: d.Config,
log: d.Log,
chat: d.Chat,
health: d.Health,
}
if d.Config.TelegramToken != "" {
if len(d.Config.Telegram.AllowedUserIDs) == 0 {
d.Log.Warn("chat.telegram has no allowed_user_ids: every sender will be rejected. " +
"Add your Telegram user id to chat.telegram.allowed_user_ids to enable the bot.")
}
tg := telegram.New(d.Config.TelegramToken, d.Config.Telegram.AllowedUserIDs, d.Log)
tg.Settings = d.Settings
configureTelegram(ctx, tg, d.Config, d.Chat, d.Log)
if err := srv.add("telegram", tg, telegramValidateConfigMap(d.Config.Telegram)); err != nil {
return nil, err
}
}
if d.Config.Email.ListenAddr != "" {
em := email.New(d.Config.Email.ListenAddr, d.Config.Email.RelayAddr, d.Log)
if err := srv.add("email", em, map[string]any{
"listen_addr": d.Config.Email.ListenAddr,
"relay_addr": d.Config.Email.RelayAddr,
}); err != nil {
return nil, err
}
}
if d.Config.WebhookAddr != "" {
host, port := parseListenAddr(d.Config.WebhookAddr, "0.0.0.0", 8644)
wh := webhook.New(host, port, webhookRoutes(d.Config.Webhook, d.Config.WebhookSecret), d.Log)
if err := srv.add("webhook", wh, map[string]any{"host": host, "port": port}); err != nil {
return nil, err
}
}
srv.status = status.NewManager(channelDescriptors(srv.channels))
srv.statusWriter = d.ChannelStatus
srv.publish = make(chan struct{}, 1)
return srv, nil
}
// add validates a channel against its own ConfigSchema contract and
// registers it.
func (s *Service) add(name string, ch channels.Channel, cfg map[string]any) error {
if err := ch.ValidateConfig(cfg); err != nil {
return fmt.Errorf("chat.%s config invalid: %w", name, err)
}
s.channels = append(s.channels, channelInstance{name: name, channel: ch})
return nil
}
// telegramValidateConfigMap builds the map Gateway.ValidateConfig expects
// from the typed config, carrying whichever credential source is set
// (token takes precedence, matching resolveTelegramToken).
func telegramValidateConfigMap(cfg config.TelegramConfig) map[string]any {
m := map[string]any{"token_env": cfg.TokenEnv}
if cfg.Token != (secret.SecretRef{}) {
m["token"] = map[string]any{"engine": cfg.Token.Engine, "key": cfg.Token.Key}
}
return m
}
func webhookRoutes(route config.WebhookRoute, secretValue string) []webhook.RouteConfig {
path := route.Path
if path == "" {
path = "/webhook"
}
return []webhook.RouteConfig{{
Path: path,
Secret: secretValue,
Template: route.Template,
DeliverTo: route.DeliverTo,
}}
}
func parseListenAddr(addr, defaultHost string, defaultPort int) (string, int) {
if addr == "" {
return defaultHost, defaultPort
}
host, portStr, err := net.SplitHostPort(addr)
if err != nil {
return defaultHost, defaultPort
}
port, err := strconv.Atoi(portStr)
if err != nil {
return defaultHost, defaultPort
}
return host, port
}
// Start launches the configured messaging channels.
func (s *Service) Start(ctx context.Context) error {
s.mu.Lock()
if s.running {
s.mu.Unlock()
return fmt.Errorf("messaging service is already running")
}
s.running = true
ctx, cancel := context.WithCancel(ctx)
s.stop = cancel
s.mu.Unlock()
s.log.Info("messaging service started", "gateway_target", s.cfg.Options.Gateway.Target, "channels", len(s.channels))
if s.statusWriter != nil {
go s.publishLoop(ctx)
// Report the composed set before any channel reports itself, so a dashboard
// opened during startup shows configured channels rather than none.
s.signalPublish()
}
var wg sync.WaitGroup
for _, ch := range s.channels {
c := ch
wg.Go(func() {
s.log.Info("starting channel", "name", c.name)
if err := c.channel.Start(ctx, s.chat, s.lifecycleFor(c.name)); err != nil && ctx.Err() == nil {
// The channel could not run: say so on the operator's surface, not
// only in the log, which is the difference between a dashboard that
// shows a dead channel and one that shows nothing at all.
s.status.MarkFailed(c.name, err.Error())
s.log.Error("channel stopped with error", "name", c.name, "err", err)
return
}
// A channel that returns without an error has stopped, either because
// the service was asked to or because its own loop ended.
s.status.MarkStopped(c.name, "")
})
}
<-ctx.Done()
for _, ch := range s.channels {
shutdownCtx, shutdownCancel := context.WithTimeout(context.WithoutCancel(ctx), s.cfg.Options.ShutdownTimeout)
if err := ch.channel.Stop(shutdownCtx); err != nil {
s.log.Warn("channel stop failed", "name", ch.name, "err", err)
}
shutdownCancel()
}
wg.Wait()
if s.statusWriter != nil {
// The final report carries the stopped states the loop above recorded.
// Its own context, because ctx is already cancelled.
finalCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), s.cfg.Options.ShutdownTimeout)
defer cancel()
if err := s.publishStatus(finalCtx); err != nil {
s.log.Warn("publishing final channel status failed", "err", err)
}
}
return nil
}
// Stop stops the messaging service and its channels.
func (s *Service) Stop() {
s.mu.Lock()
defer s.mu.Unlock()
if !s.running {
return
}
s.running = false
if s.stop != nil {
s.stop()
}
s.log.Info("messaging service stopped")
}