From 0cbb65c684f54fe5f8537986e7ec3d4c4a043527 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 3 Oct 2026 22:02:57 +1000 Subject: [PATCH] refactor(setup,messaging,container,agentworker,discovery,memory,eventbus): cut comments down to what the code does --- internal/app/agentworker/mcp_providers.go | 16 +- internal/app/agentworker/mcp_sampling.go | 15 +- internal/app/agentworker/task_execution.go | 104 ++----------- internal/app/agentworker/version.go | 8 +- .../app/archiemessaging/channel_status.go | 22 +-- internal/app/archiemessaging/compose.go | 29 +--- internal/app/archiemessaging/options.go | 8 +- internal/app/archiemessaging/reconcile.go | 34 +---- internal/app/archiemessaging/supervise.go | 20 +-- .../app/archiemessaging/telegram_features.go | 36 +---- internal/container/kit.go | 6 +- internal/container/pool.go | 144 ++++-------------- .../configuration/setup/defaultprompter.go | 9 +- .../configuration/setup/envsink.go | 22 +-- .../configuration/setup/prompter.go | 14 +- .../configuration/setup/secretref.go | 5 - .../configuration/setup/setup.go | 62 ++------ .../configuration/setup/step_forge.go | 25 +-- .../configuration/setup/step_provider.go | 20 +-- .../infrastructure/eventbus/nats/client.go | 28 +--- .../infrastructure/eventbus/nats/config.go | 35 +---- .../infrastructure/eventbus/nats/consumer.go | 7 +- internal/infrastructure/eventbus/nats/doc.go | 25 +-- .../infrastructure/eventbus/nats/embedded.go | 18 +-- .../infrastructure/eventbus/nats/errors.go | 5 - .../infrastructure/eventbus/nats/message.go | 6 +- .../infrastructure/eventbus/nats/publisher.go | 6 +- .../infrastructure/memory/builtin_engine.go | 72 ++------- internal/infrastructure/memory/history.go | 16 +- internal/infrastructure/memory/marker.go | 9 +- internal/infrastructure/memory/parse.go | 40 +---- .../servicediscovery/nats/doc.go | 52 +------ .../servicediscovery/nats/errors.go | 5 - .../servicediscovery/nats/keys.go | 6 +- .../servicediscovery/nats/registrar.go | 17 +-- .../servicediscovery/nats/registry.go | 57 ++----- 36 files changed, 179 insertions(+), 824 deletions(-) diff --git a/internal/app/agentworker/mcp_providers.go b/internal/app/agentworker/mcp_providers.go index 5a4606cb6..7ec86bc47 100644 --- a/internal/app/agentworker/mcp_providers.go +++ b/internal/app/agentworker/mcp_providers.go @@ -25,11 +25,9 @@ type mcpProviderSet struct { type mcpProviderBuilder func(config.MCPServer, mcp.SamplingHandler) (toolprovider.Engine, string, error) -// startMCPProviders creates MCP transports from config, starts them, -// discovers tools, and registers them into a local registry. A non-nil -// sampling handler answers server-initiated sampling/createMessage requests -// (nil leaves the method refused, the client's own default). Returns nil when -// there are no servers configured. +// startMCPProviders starts the configured MCP servers and registers their +// tools. sampling answers sampling requests when non-nil. Returns nil with +// no servers. func startMCPProviders( ctx context.Context, servers []config.MCPServer, @@ -111,13 +109,7 @@ func mcpTransportForServer( if command == "" { return nil, fmt.Errorf("MCP stdio server %q requires a command", name) } - // storage.MCPNPMCacheMountDir is a shared Docker volume mounted on - // every task container (internal/storage's alwaysOnCacheVolumes), - // so an npx-launched MCP server reuses a warm npm cache across - // tasks instead of re-resolving/re-downloading from the registry - // in each fresh ephemeral container. Mirrors the daemon's own - // npx MCP servers (cmd/archied/main.go's npmCacheServerEnv), - // which persists across daemon restarts the same way. + // Share the npm cache volume across task containers. return mcp.NewStdioTransport(mcp.StdioTransportConfig{ Command: command, Args: append([]string(nil), server.Args...), diff --git a/internal/app/agentworker/mcp_sampling.go b/internal/app/agentworker/mcp_sampling.go index 6cb383f80..246b34615 100644 --- a/internal/app/agentworker/mcp_sampling.go +++ b/internal/app/agentworker/mcp_sampling.go @@ -14,22 +14,13 @@ import ( "github.com/samcharles93/archie-core/internal/tools/mcp" ) -// taskSamplingModel is the model a task-scoped MCP server's sampling request -// is answered with: the task's builder model, the same fallback an agent stage -// whose role is unset uses (workflow.AgentStage.resolveModel) and the same -// role the daemon's chat path falls back to. Empty means the task has no model -// to answer with. +// taskSamplingModel returns the task's builder model, or "". func taskSamplingModel(cfg config.TaskConfig) string { return strings.TrimSpace(cfg.Models["builder"]) } -// taskSamplingHandler answers an MCP server's sampling/createMessage request -// from the task's own model runtime, the same way the daemon's chat path -// answers it from its chat model. The worker hosts the same configured MCP -// servers as a chat turn, so without this a server's sampling request is -// answered on one path and refused on the other. A missing runtime or model is -// a refused request, never a dropped one: the client maps the returned error -// to a JSON-RPC error for that request alone. +// taskSamplingHandler answers MCP sampling requests with the task's model. +// Without a runtime or model the request is refused. func taskSamplingHandler(llm *runtime.Runtime, cfg config.TaskConfig) mcp.SamplingHandler { return func(ctx context.Context, req mcp.SamplingRequest) (mcp.SamplingResult, error) { if llm == nil { diff --git a/internal/app/agentworker/task_execution.go b/internal/app/agentworker/task_execution.go index b1becc0a3..89519a34b 100644 --- a/internal/app/agentworker/task_execution.go +++ b/internal/app/agentworker/task_execution.go @@ -25,13 +25,8 @@ import ( "github.com/samcharles93/archie-core/internal/worktree" ) -// hybridTrees implements workflow.Trees by splitting operations: Prepare -// and Push (network ops needing the daemon's forge credential) proxy over -// worktreerpc; CommitAll/Diff/ChangedFiles/ChangedLines are local git -// operations run directly against the container's bind-mounted worktree. -// -// Prepare returns the bind-mounted worktree that archied prepared before the -// container started. The sandbox has no remote prepare capability. +// hybridTrees implements workflow.Trees: Push goes to the daemon over +// worktreerpc; local git operations run on the bind-mounted worktree. type remoteTrees interface { Push(ctx context.Context) error } @@ -41,21 +36,12 @@ type hybridTrees struct { local *worktree.Manager localDir string branch string - // worktreeUID and worktreeGID are the daemon's own host UID/GID - // (WORKTREE_UID/WORKTREE_GID, set by containerEnv), or -1 when unset. The - // agent runs as root inside the container, so a commit it writes to the - // bind-mounted worktree lands owned by UID 0 on the host; Push reconciles - // ownership back to the daemon's UID before handing off, since the daemon - // -- running as its own non-root host user -- is the one that reads those - // objects to actually push. + // worktreeUID and worktreeGID are the daemon's host UID/GID, or -1. Push + // chowns the worktree back to them. worktreeUID, worktreeGID int } -// Prepare binds the task's already-prepared, bind-mounted worktree. The -// daemon positioned it before the container started, so this resolves the -// directory and branch rather than doing network work. A resume target (the -// PR branch a remediation continues) is returned verbatim; a fresh target uses -// the branch the daemon computed and persisted on the task row. +// Prepare returns the worktree the daemon already prepared and its branch. func (h *hybridTrees) Prepare(ctx context.Context, owner, repo, base string, issue int, title, body, labels string, target workflow.PrepareTarget) (dir, branch string, err error) { if target != workflow.PrepareFresh { return h.localDir, string(target), nil @@ -86,18 +72,8 @@ func (h *hybridTrees) reconcileOwnership(dir string) error { return chownTree(dir, h.worktreeUID, h.worktreeGID) } -// restoreWorktreeOwnership returns the deferred half of the ownership -// contract: the agent runs as root inside the container, so a run that ends -// without ever reaching CommitAll or Push (a gate failure that parks the task, -// a stage error, an early return) has to hand the bind-mounted worktree back to -// the daemon's own UID on its way out. The daemon is the process that later -// cleans and resets that directory as a non-root host user, and it cannot even -// unlink inside a root-owned directory -- so a parked attempt otherwise left a -// worktree the next attempt could not start from, no matter what the refresh -// did. -// -// Returns the func rather than deferring internally so the caller's own defer -// runs it at the caller's return, not at this function's. +// restoreWorktreeOwnership returns a func that chowns the worktree back to +// the daemon's UID, for every way a run can end. func restoreWorktreeOwnership(trees *hybridTrees, dir string, log *slog.Logger) func() { return func() { if err := trees.reconcileOwnership(dir); err != nil { @@ -122,37 +98,19 @@ func (h *hybridTrees) ChangedLines(ctx context.Context, dir, base string) (int, return h.local.ChangedLines(ctx, dir, base) } -// ChangedFileStats is the capability the workflow captures a change through. -// It is not part of workflow.Trees: it is asserted for as the unexported -// optional interface package workflow declares, so a Trees implementation -// without it degrades to no capture. Without this forwarder the in-container -// path -- which is every production run, archie-agent executing the whole -// workflow -- would be exactly that silent no-op. +// ChangedFileStats forwards to the local worktree manager. func (h *hybridTrees) ChangedFileStats(ctx context.Context, dir, base string) (task.ChangeStats, error) { return h.local.ChangedFileStats(ctx, dir, base) } -// HasUncommittedChanges is the capability the diff-rules placement guard reads -// to tell "nothing has changed" from "not committed yet". It is not part of -// workflow.Trees for the same reason ChangedFileStats is not, and without this -// forwarder the in-container path -- every production run -- would answer the -// guard for the wrong reason. +// HasUncommittedChanges forwards to the local worktree manager. func (h *hybridTrees) HasUncommittedChanges(ctx context.Context, dir string) (bool, error) { return h.local.HasUncommittedChanges(ctx, dir) } var _ workflow.Trees = (*hybridTrees)(nil) -// chownTree recursively chowns dir to uid:gid so the daemon -- running as -// its own host user -- can read loose objects the agent committed as root -// inside the container. -// -// Lchown, not Chown: a repo can legitimately track a symlink whose target -// doesn't exist inside the container (a relative link outside the -// checkout, or to a tool the image doesn't ship). Chown follows the link -// and fails on a dangling target, which would abort a push that would -// otherwise have succeeded -- worse than the permission error this is -// fixing. Lchown changes the link itself and never touches the target. +// chownTree recursively lchowns dir to uid:gid. func chownTree(dir string, uid, gid int) error { return filepath.WalkDir(dir, func(path string, _ fs.DirEntry, err error) error { if err != nil { @@ -200,12 +158,8 @@ func newTaskRunner(providers map[string]agentexec.Provider, log *slog.Logger) ag return agentexec.NewLoopRunner(agentexec.NewRuntime(providers), log) } -// applyToolLimits wires the task's carried tool policy and its agent -// profile's tool allowlist into a *LoopRunner: the result cap/spill, so a -// worker-executed stage enforces the same limits the daemon's own chat path -// applies (config.Config.Tools.Policy, carried non-secret via -// TaskConfig.ToolPolicy), and the tools the profile allows. A runner that -// isn't a *LoopRunner (e.g. a test fake) is left untouched. +// applyToolLimits sets the task's tool policy and allowlist on a +// *LoopRunner. Other runners are untouched. func applyToolLimits(agent agentexec.Runner, policy config.ToolPolicy, allow []string) { runner, ok := agent.(*agentexec.LoopRunner) if !ok { @@ -268,14 +222,6 @@ func runTask(ctx context.Context, req taskrun.Request, dependencies taskDependen worktreeUID: worktreeOwnerID(os.Getenv("WORKTREE_UID")), worktreeGID: worktreeOwnerID(os.Getenv("WORKTREE_GID")), } - // The agent process runs as root inside the container, so everything this - // run writes into the bind-mounted worktree is owned by UID 0 on the host; - // CommitAll and Push hand it back on the success path. Doing the same here - // covers every OTHER way a run can end -- a gate failure that parks the - // task, a stage error, an early return -- because the daemon is the one - // that later cleans and resets this directory, as its own non-root host - // user, and it cannot even unlink a root-owned directory. Without this, a - // parked attempt left a worktree the next attempt could not start from. defer restoreWorktreeOwnership(trees, workDir, log)() // The MCP providers a task hosts share the same model runtime its agent @@ -299,15 +245,7 @@ func runTask(ctx context.Context, req taskrun.Request, dependencies taskDependen } agent = persistentRunner{Runner: agent, enabled: req.Repo.PersistentStorage} - // A workflow run in this process publishes to an in-process *events.Bus - // the daemon cannot see -- archied and archie-agent are separate - // processes connected only by NATS. Without this bridge, tc.Emit is a - // silent no-op for every stage/outcome/park event this run produces, - // which is why the dashboard timeline showed nothing for any task - // executed through the container/NATS path. Nil - // dependencies.events (a caller with no NATS connection, e.g. tests - // that construct taskDependencies directly) leaves bus nil, and - // TaskContext.Emit is already nil-safe. + // Forward workflow events to the daemon over NATS. var bus *events.Bus if dependencies.events != nil { bus = events.NewBus() @@ -329,11 +267,7 @@ func runTask(ctx context.Context, req taskrun.Request, dependencies taskDependen Log: log, Guardrails: dependencies.guardrails, } - // pr-review reads an external pull request's data from workDir, which the - // daemon already populated before this task started (daemon's - // prefetchPRReview, writing under workDir/.archie-pr-review -- the same - // host directory Docker bind-mounts at storage.WorktreeMountDir) -- never - // over the network, and never with a forge credential in this process. + // pr-review reads the PR data the daemon prefetched into workDir. if req.Task.Workflow == "pr-review" { tc.PRSource = prsource.NewFromMount(filepath.Join(workDir, prsource.PrefetchDirName)) } @@ -358,14 +292,8 @@ func runTask(ctx context.Context, req taskrun.Request, dependencies taskDependen }, nil } -// CompilePinnedWorkflow resolves and compiles the immutable definition the task -// request carries, against this process's step vocabulary. Production execution -// and the workflow step-vocabulary contract test both enter through it. -// -// A request that carries no definition is routed and pinned from the shipped -// definitions, which writes the resolved workflow name, YAML, and digest back -// onto req and req.Task: the run's TaskContext carries that task record, so the -// pin has to land on the request the caller handed in. +// CompilePinnedWorkflow compiles the definition the request carries. With +// none, it pins one from the shipped definitions onto req and req.Task. func CompilePinnedWorkflow(req *taskrun.Request, steps *workflow.Manager) (workflow.Workflow, error) { // steps is this process's required step vocabulary, so a nil one is a wiring // mistake at the composition root (productionWorkerDependencies) rather than diff --git a/internal/app/agentworker/version.go b/internal/app/agentworker/version.go index c38c59cb2..04fb0ea68 100644 --- a/internal/app/agentworker/version.go +++ b/internal/app/agentworker/version.go @@ -1,12 +1,6 @@ package agentworker -// version is stamped per release artifact via -// "-ldflags -X github.com/samcharles93/archie-core/internal/app/agentworker.version=", -// the same mechanism internal/installtype uses for buildType -- see that -// package's doc comment for why this is baked in at build time rather than -// detected. Reported back to the daemon in every taskrun.Response -// (see task_execution.go) so it can observe the build actually running, -// not the one its own release pipeline expected. +// version is set at build time with -ldflags -X and reported to the daemon. var version = "dev" // Version reports the archie-agent build this worker process was built diff --git a/internal/app/archiemessaging/channel_status.go b/internal/app/archiemessaging/channel_status.go index 65e62aec3..d770474c9 100644 --- a/internal/app/archiemessaging/channel_status.go +++ b/internal/app/archiemessaging/channel_status.go @@ -39,15 +39,8 @@ func reloadable(instance *channelInstance) bool { return ok && gateway.Reload != nil } -// ReloadChannel asks one channel to re-read its configuration. A channel that -// does not support reload is refused with a reason rather than accepted and -// ignored: the dashboard offers the action on the strength of the capability its -// descriptor declares, so an accepted-then-nothing reload is a lie the operator -// has no way to see through. -// -// The reload itself is the channel's own seam -- the telegram front-end re-reads -// its token and allowlist -- so this function adds routing and a truthful -// refusal, not a second implementation. +// ReloadChannel asks one channel to reload its configuration, refusing +// channels that cannot. func (s *Service) ReloadChannel(_ context.Context, id string) error { for _, instance := range s.channels { if instance.name != id { @@ -65,16 +58,7 @@ func (s *Service) ReloadChannel(_ context.Context, id string) error { return fmt.Errorf("messaging: no channel %q", id) } -// lifecycleFor returns the report a channel writes its own state through. Each -// channel gets its own closure, so one channel's failure marks only itself -- -// which is the reason the manager is keyed by channel rather than being one flag -// on the service. -// -// Before this, Start handed every channel an empty channels.Lifecycle{}, so -// nothing recorded starting, running or failed anywhere and -// internal/channels/status.Manager had no production writer at all. -// The channels have always reported: all three call -// ReportStarting and ReportRunning on whichever lifecycle they are handed. +// lifecycleFor returns the lifecycle a channel reports its own state through. func (s *Service) lifecycleFor(id string) channels.Lifecycle { return channels.Lifecycle{ Starting: func() { s.status.MarkStarting(id); s.signalPublish() }, diff --git a/internal/app/archiemessaging/compose.go b/internal/app/archiemessaging/compose.go index bef98b99f..d7fc68a6e 100644 --- a/internal/app/archiemessaging/compose.go +++ b/internal/app/archiemessaging/compose.go @@ -33,11 +33,8 @@ type deps struct { Chat messaging.ChatContract Health *health.Registry Settings *messaging.SettingsCommand - // SettingsSource, when non-nil, enables the live channel-settings - // reconcile: the service re-reads the stored channel-settings resource on - // the apply-status restamp interval and restarts only the channels whose - // settings changed. Nil leaves the service with no live path, which is the - // honest state for a test or a process with no State Store. + // SettingsSource enables live channel-settings reconciliation. Nil disables + // it. SettingsSource chatSettingsSource // ApplyReporter records what this process applied. Nil reports nothing. ApplyReporter *applystatus.Reporter @@ -49,12 +46,8 @@ type deps struct { ReconcileInterval time.Duration } -// channelInstance is one composed channel and the runtime state that lets the -// service restart it alone. channel and cancel are guarded by mu; rebuild is -// immutable. The channel swaps when the stored settings change, which is what a -// restart is: build the replacement, stop the old run context, start the new -// instance. A channel with no in-place reload seam is therefore still -// reloadable. +// channelInstance is one composed channel and what is needed to restart it. +// mu guards channel and cancel. type channelInstance struct { name string rebuild func(ResolvedConfig) (channels.Channel, error) @@ -113,11 +106,8 @@ type Service struct { wg sync.WaitGroup } -// 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. +// compose builds the Service. ctx is the service lifetime. An invalid +// configured channel fails composition. func compose(ctx context.Context, d deps) (*Service, error) { srv := &Service{ cfg: d.Config, @@ -309,12 +299,7 @@ func (s *Service) Start(ctx context.Context) error { go s.runChannel(ctx, c) } - // Every configured channel has been handed its lifetime and the service - // blocks here serving them. Not earlier: a channel whose configuration is - // invalid fails composition, above, and READY must not precede it. Not - // later: a unit whose TimeoutStartSec expires first would restart a healthy - // process. Nothing is consumed until the unit says Type=notify, so this is - // inert on today's install. + // Notify systemd once every channel has started. sdnotify.Ready(s.log) <-ctx.Done() diff --git a/internal/app/archiemessaging/options.go b/internal/app/archiemessaging/options.go index d8800ca86..30b82ad8b 100644 --- a/internal/app/archiemessaging/options.go +++ b/internal/app/archiemessaging/options.go @@ -1,9 +1,5 @@ -// Package archiemessaging composes the standalone Messaging Service: the external -// channel connections (Telegram, email, webhook) served against a Gateway running -// over its gRPC contract. -// -// The Messaging Service owns channel persistent connections and dispatches -// turns directly to Gateway's ChatContract over gRPC. +// Package archiemessaging composes the Messaging Service: chat channel +// connections that send turns to the Gateway over gRPC. package archiemessaging import ( diff --git a/internal/app/archiemessaging/reconcile.go b/internal/app/archiemessaging/reconcile.go index b9dd4fc3e..92a7eb31b 100644 --- a/internal/app/archiemessaging/reconcile.go +++ b/internal/app/archiemessaging/reconcile.go @@ -20,12 +20,8 @@ type chatSettingsSource interface { RuntimeChatConfig(ctx context.Context, base config.ChatConfig) (config.ChatConfig, int64, error) } -// reconcileLoop re-reads the stored channel settings on the apply-status -// restamp interval until ctx ends. A poll rather than a stream: the restamp -// interval is the cadence every process already reports at, the messaging -// process has no other control-plane watch to share a reconnect ladder with, -// and a stored document that cannot be read must leave the running channels -// alone. +// reconcileLoop re-reads stored channel settings every restamp interval +// until ctx ends. func (s *Service) reconcileLoop(ctx context.Context) { ticker := time.NewTicker(s.reconcileInterval) defer ticker.Stop() @@ -41,13 +37,8 @@ func (s *Service) reconcileLoop(ctx context.Context) { } } -// reconcileOnce re-reads the stored channel settings and, when the version -// moved, applies the change to the running channels and records the outcome in +// reconcileOnce applies changed channel settings and records the outcome in // apply status. -// -// The file document is re-resolved first, exactly as the /restart path does, so -// the layering is the same projection boot used: the store overrides the file, -// and a field the store omits keeps the file's value. func (s *Service) reconcileOnce(ctx context.Context) error { base, err := Resolve(s.currentConfig().Options, s.log) if err != nil { @@ -102,22 +93,9 @@ func resolveChatSecrets(base ResolvedConfig, layered config.ChatConfig) (Resolve return next, nil } -// applyChannelSettings applies a freshly resolved chat config to the running -// channels. A channel restarts only when its own transport settings changed; -// every other channel keeps serving. It reports whether every requested restart -// was carried out, so a rebuild that failed is retried rather than recorded as -// applied. -// -// Machine-level settings do not restart a channel. The chat session defaults -// (workspace, filesystem access, max steps, rate limit) are not part of the -// messaging projection at all, and show_tool_calls is handed to the running -// Telegram gateway in place, so both apply to turns that start after the change -// rather than interrupting one in flight. -// -// The composed set and the listen addresses are fixed for the life of the -// process. Enabling or disabling a channel and rebinding a listen address are -// process bindings; the change is refused and reported for a restart instead of -// applied. +// applyChannelSettings restarts only channels whose transport settings +// changed and reports whether every restart succeeded. Enabling or +// disabling a channel or changing a listen address needs a process restart. func (s *Service) applyChannelSettings(next ResolvedConfig) (bool, error) { current := s.currentConfig() effective, outstanding := pinProcessBindings(current, next) diff --git a/internal/app/archiemessaging/supervise.go b/internal/app/archiemessaging/supervise.go index e7871b7f2..222608c82 100644 --- a/internal/app/archiemessaging/supervise.go +++ b/internal/app/archiemessaging/supervise.go @@ -8,15 +8,8 @@ import ( "github.com/samcharles93/archie-core/internal/channels" ) -// runChannel supervises one channel for the life of the service. It starts the -// channel and, when the channel stops because a restart was requested, starts -// the replacement. A channel that returns on its own is recorded and not -// restarted, so a channel whose configuration cannot run does not spin. -// -// The supervisor is per channel rather than one loop over every channel -// because a channel-settings change must restart exactly the channel whose -// settings changed: cancelling one run context stops one channel and leaves the -// rest serving. +// runChannel runs one channel and starts its replacement after a requested +// restart. A channel that exits on its own is not restarted. func (s *Service) runChannel(ctx context.Context, c *channelInstance) { defer s.wg.Done() for { @@ -74,13 +67,8 @@ func (s *Service) runChannel(ctx context.Context, c *channelInstance) { } } -// restartChannel stops the running channel id and starts a replacement built -// from next. The replacement is built before the running channel is touched, so -// a configuration this build cannot run leaves the running channel serving -// -// A channel that is not currently supervised is not restarted: it already -// stopped on its own, and resurrecting it here would race that exit. The caller -// reports it. +// restartChannel builds a replacement for channel id from next, then stops +// the old one and starts it. A channel not running is not restarted. func (s *Service) restartChannel(id string, next ResolvedConfig) error { c := s.instanceByID(id) if c == nil { diff --git a/internal/app/archiemessaging/telegram_features.go b/internal/app/archiemessaging/telegram_features.go index 5c2408370..0c2636017 100644 --- a/internal/app/archiemessaging/telegram_features.go +++ b/internal/app/archiemessaging/telegram_features.go @@ -32,33 +32,14 @@ func configureTelegram(ctx context.Context, g *telegram.Gateway, cfg ResolvedCon } } -// messagingRunningVersions reports the component versions this process can -// vouch for, for checking a relayed update report against -// (releaseupdate.Report.Verify). -// -// archie-messaging is one of the processes in the archied release set (the -// installer's GATEWAY_SERVICES), built from the same archied/v* tag and stamped -// with buildinfo.Version by every build site (install.sh, the updater, the -// release workflow and Taskfile). Its own compiled-in build is therefore -// evidence that the release the installer claims actually reached this host: a -// binary the update did not replace still reports the version it was built -// from, which Verify reads as drift rather than false success. Reading the -// version from the Gateway instead would report a different process's stamp, -// which is the failure mode the check exists to catch (see -// -// The agent is deliberately absent: every archie-agent process is task-scoped -// and observed only through daemon.AgentStatus, which this process does not -// hold, so it must report Unverified rather than be guessed. +// messagingRunningVersions reports this process's own build version for +// update verification. func messagingRunningVersions() map[string]string { return map[string]string{releaseupdate.ComponentDaemon: buildinfo.Version} } -// gatewayVersionReporter renders /version from the Gateway's own build block. -// It is read per call rather than captured at compose so an upgraded Gateway -// is reported without restarting this process, and bounded by the same -// dependency timeout the readiness probe uses so a hung Gateway answers the -// command instead of leaving the operator with no reply at all. The service -// context bounds it too, so a shutdown does not wait on an in-flight call. +// gatewayVersionReporter renders /version from the Gateway's build info, +// fetched per call with a timeout. func gatewayVersionReporter(ctx context.Context, chat messaging.ChatContract, timeout time.Duration) func() string { return func() string { callCtx := ctx @@ -78,13 +59,8 @@ func gatewayVersionReporter(ctx context.Context, chat messaging.ChatContract, ti } } -// updateService builds /update from this service's own [chat.telegram] -// commands, or nil when none is configured, which leaves the channel reporting -// the command as unconfigured. -// -// Enrich is deliberately unset: the daemon filled it from [nats], which this -// service must not decode, so the check command's own reported install type -// stands. +// updateService builds /update from [chat.telegram] commands, or nil when +// none are configured. func updateService(cfg ResolvedConfig) *releaseupdate.Service { if len(cfg.Telegram.UpdateCheckCommand) == 0 { return nil diff --git a/internal/container/kit.go b/internal/container/kit.go index 602dbce27..22d788b5d 100644 --- a/internal/container/kit.go +++ b/internal/container/kit.go @@ -38,10 +38,8 @@ type KitSpec struct { InstallDone func() } -// StartKit creates and starts a Kit container, then brings it to the state -// a harness may run in: install hooks run as their users, the Kit's files -// written as the harness user, and startup hooks run. A failing install or -// foreground startup hook removes the container and returns the hook's +// StartKit creates and starts a Kit container and runs its install and +// startup hooks. A failing hook removes the container and returns its // output. func StartKit(ctx context.Context, cli *client.Client, s KitSpec) (string, error) { var mounts []mount.Mount diff --git a/internal/container/pool.go b/internal/container/pool.go index 7a0c4deae..0faf14129 100644 --- a/internal/container/pool.go +++ b/internal/container/pool.go @@ -53,15 +53,8 @@ type TaskPayload struct { Inputs map[string]any `json:"inputs,omitempty"` } -// WriteTaskJSON writes the task payload to /.git/task.json. -// The workspace directory must already exist. -// -// It goes under .git deliberately. The workspace is the task worktree the -// agent commits from, and worktree.CommitAll stages with go-git's All -// option, which does not honour .gitignore or .git/info/exclude -- a brief -// at the worktree root is swept into the agent's commit and pushed onto the -// task branch. Nothing under .git can ever be tracked, which is the same -// reasoning that moved the prepared sentinel there. +// WriteTaskJSON writes the task payload to /.git/task.json, where +// it is never committed. func WriteTaskJSON(workspace string, payload TaskPayload) error { if workspace == "" { return fmt.Errorf("task.json: empty workspace path") @@ -114,11 +107,8 @@ type Pool struct { teardowns map[string]*containerTeardown } -// current returns the settings a new acquire should use: the live source when -// the pool has one, otherwise the construction-time Config. Only the fields a -// container-runtime-policies document can carry are taken from the live -// source; DockerClient, RequireHostGateway, RegistryAuth and GracePeriod stay -// construction-time, because none of them is part of that document. +// current returns the per-acquire settings from the live source when set, +// else the construction Config. func (p *Pool) current() Config { if p.live == nil { return p.cfg @@ -162,18 +152,10 @@ type Config struct { RequireHostGateway bool } -// NewPool connects to the Docker daemon, optionally pulls the image, -// and cleans up orphaned containers from a previous daemon crash. -// -// If cfg.DockerClient is set, it is reused (caller owns Close). -// Otherwise a new client is created via client.FromEnv (pool owns Close). -// -// live, when non-nil, is the pool's live source of the per-acquire settings a -// container-runtime-policies document can change (Image, MaxConcurrency, -// MaxUptime, PullPolicy, Network). It is read on every acquire, so a stored -// change reaches the next container without a restart; nil means cfg is fixed -// for the pool's life. DockerClient, RequireHostGateway, RegistryAuth and -// GracePeriod stay construction-time because the document never carries them. +// NewPool connects to Docker, optionally pulls the image and removes orphaned +// containers. A set cfg.DockerClient is reused and not closed. live, when +// non-nil, supplies Image, MaxConcurrency, MaxUptime, PullPolicy and Network +// on every acquire. func NewPool(ctx context.Context, cfg Config, live func() Config, log *slog.Logger) (*Pool, error) { cli := cfg.DockerClient if cli == nil { @@ -232,10 +214,8 @@ func NewPool(ctx context.Context, cfg Config, live func() Config, log *slog.Logg } // Acquire creates and starts a container from image (empty means the -// configured image) with the given mounts and environment variables. Mounts -// are provided by the caller (typically from a storage.Backend). If MaxUptime -// is set, the pool schedules a hard stop and remove of the container once -// that lifetime cap elapses, regardless of task state. +// configured one). With MaxUptime set, the container is stopped and removed +// once it elapses. func (p *Pool) Acquire(ctx context.Context, image string, mounts []storage.Mount, env []string) (*Container, error) { // One snapshot for the whole acquire: the image, pull policy, network, // concurrency cap and max-uptime cap are all read once, so a settings @@ -365,36 +345,15 @@ func (p *Pool) watchExit(ctx context.Context, id string) <-chan struct{} { return exited } -// containerTeardown is the one-shot teardown state for a live container: its -// armed max-uptime reaper, and whether Docker stop/remove has been claimed. -// -// Both the reaper and Release tear a container down, and Timer.Stop cannot -// unwind a callback that has already begun, so cancelling the timer is not -// enough to keep them from overlapping. Claiming decides the winner instead: -// exactly one path talks to Docker, and the loser skips straight to its own -// bookkeeping. +// containerTeardown is a live container's max-uptime timer and whether its +// Docker teardown has been claimed. type containerTeardown struct { timer *time.Timer closed bool } -// armMaxUptime schedules a hard stop and remove for a container once its -// lifetime cap elapses. The timer never touches p.active: Release (or Close) -// remains the only owner of the active slot. -// -// The entry and its timer are recorded in one critical section, so the -// callback cannot run ahead of the bookkeeping it needs: time.AfterFunc hands -// control to the callback as soon as the duration elapses, and the callback's -// first act is claimReaper, which takes p.mu. Holding p.mu across both the -// entry creation and the timer's creation is what makes that claim observe a -// container that is armed rather than one that is mid-arm -- a timer recorded -// after a callback had already fired (and a Release already forgotten the -// entry) left an unclosed entry behind, with a one-shot timer that would never -// fire again. -// -// The lock covers only bookkeeping: the callback runs on its own goroutine and -// nothing here waits on it, and every Docker call it makes happens after it -// has released p.mu. +// armMaxUptime schedules a stop and remove after maxUptime, recording the +// entry and timer under p.mu. func (p *Pool) armMaxUptime(ctx context.Context, maxUptime time.Duration, id string) { p.mu.Lock() defer p.mu.Unlock() @@ -422,14 +381,8 @@ func (p *Pool) reapMaxUptime(ctx context.Context, id string) { } } -// claimReaper reports whether the max-uptime callback owns this container's -// Docker teardown. The first claim wins; every later one is told to stay out. -// -// A missing entry is a loss, never a fresh claim: only armMaxUptime creates -// entries, so no entry means MaxUptime was never armed or Release has already -// forgotten the container -- in both cases the reaper has nothing to tear -// down. Creating one here is exactly how a callback that was still running -// when Release forgot the entry could resurrect it. +// claimReaper reports whether the max-uptime callback may tear the container +// down. A missing entry is a loss. func (p *Pool) claimReaper(id string) bool { p.mu.Lock() defer p.mu.Unlock() @@ -441,15 +394,8 @@ func (p *Pool) claimReaper(id string) bool { return true } -// claimRelease reports whether Release owns this container's Docker teardown. -// -// Unlike the reaper, Release is the path that always exists: MaxUptime == 0 -// arms no reaper at all, so the absence of an entry must still be a win here. -// The pool guarantees every acquired container is released exactly once, so by -// the time Release runs an entry can be missing only because a reaper was -// never armed -- an absent entry is never a live reaper in flight, since -// nothing but Release's forgetTeardown deletes one, and that runs after this -// claim. +// claimRelease reports whether Release may tear the container down. A +// missing entry is a win. func (p *Pool) claimRelease(id string) bool { p.mu.Lock() defer p.mu.Unlock() @@ -464,12 +410,7 @@ func (p *Pool) claimRelease(id string) bool { return true } -// forgetTeardown disarms the reaper and drops the container's bookkeeping, so -// the map does not grow for the life of the pool. Only Release calls this, as -// the last step of a teardown it claimed, and deleting the entry is final: the -// reaper's claimReaper looks the entry up and never creates one, so a callback -// that was already running when the entry went away finds nothing to claim -// instead of racing a fresh entry back into existence. +// forgetTeardown stops the timer and deletes the container's entry. func (p *Pool) forgetTeardown(id string) { p.mu.Lock() t := p.teardowns[id] @@ -496,18 +437,9 @@ func (p *Pool) teardownLocked(id string) *containerTeardown { return t } -// releaseDecision reports how Release should tear a container down: whether -// to honour the configured post-completion grace period, and what Docker -// stop timeout to request (nil means the container's configured timeout or -// the engine default; a non-nil zero means stop immediately with SIGKILL, -// skipping the graceful SIGTERM wait). -// -// A cancelled ctx means the release is happening because the task was -// stopped, not because it finished -- /stop is an emergency brake, so -// neither the grace period (meant for a task that completed on its own and -// might get a follow-up) nor a graceful stop (meant to let a healthy -// process wind down) apply. A still-live ctx is a normal completion, so -// both keep their existing meaning. +// releaseDecision reports whether Release honours the grace period and the +// stop timeout to use. A cancelled ctx skips the grace period and kills +// immediately. func releaseDecision(ctx context.Context, grace time.Duration) (honorGrace bool, stopTimeout *int) { if ctx.Err() != nil { zero := 0 @@ -530,18 +462,9 @@ func (p *Pool) Release(ctx context.Context, c *Container) { time.Sleep(p.cfg.GracePeriod) } - // Claim only now. MaxUptime is a cap from creation enforced regardless of - // task state, so the reaper must still be free to bite during the grace - // period above; claiming before the sleep would quietly extend the cap by - // GracePeriod. Losing the claim means the reaper already removed this - // container, so there is nothing left to stop. + // Claim after the grace period so MaxUptime still applies during it. if p.claimRelease(c.ID) { - // Detach from ctx before stopping. Release runs on the way out of a - // task, and the most important reason a task is on its way out is - // that it was cancelled -- at which point ctx is already dead, the - // graceful stop fails immediately, and the container is left to the - // forced remove below. Teardown is cleanup, so it gets its own - // deadline rather than inheriting the caller's cancellation. + // Stop with a fresh deadline even if ctx is cancelled. stopCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 10*time.Second) defer cancel() @@ -658,15 +581,8 @@ func (p *Pool) pullImage(ctx context.Context, ref string) error { return nil } -// registryAuthHeader renders p.cfg.RegistryAuth into the value the Engine API -// expects in ImagePullOptions.RegistryAuth (the base64url AuthConfig of the -// X-Registry-Auth header), or "" when no credential is configured. -// -// A credential that cannot be rendered degrades to an anonymous pull with a -// warning rather than failing the pull: one bad secret must not take every -// autonomous task down with it, and the warning is what makes the 401 a private -// registry will still answer explicable. A missing credential is silent -- it is -// the deployment shape that has no private registry. +// registryAuthHeader returns the X-Registry-Auth value, or "". A credential +// that cannot be rendered logs a warning and pulls anonymously. func (p *Pool) registryAuthHeader(cfg Config, ref string) string { if cfg.RegistryAuth == "" { return "" @@ -698,12 +614,8 @@ func encodeRegistryAuth(credential string) (string, error) { return base64.URLEncoding.EncodeToString(payload), nil } -// selfNetwork detects the user-defined Docker network the current -// process's own container is attached to, by inspecting the container -// named after our hostname (Docker sets a container's hostname to its -// short ID by default). Returns "" if we're not running in a container, -// the inspect fails, or we're only on the default bridge network -- in -// all of those cases Acquire falls back to Docker's normal default. +// selfNetwork returns the user-defined network this process's container is +// on, or "". func selfNetwork(ctx context.Context, cli *client.Client, log *slog.Logger) string { hostname, err := os.Hostname() if err != nil { diff --git a/internal/infrastructure/configuration/setup/defaultprompter.go b/internal/infrastructure/configuration/setup/defaultprompter.go index a6baaeef3..f5c6f526e 100644 --- a/internal/infrastructure/configuration/setup/defaultprompter.go +++ b/internal/infrastructure/configuration/setup/defaultprompter.go @@ -2,13 +2,8 @@ package setup import "context" -// DefaultPrompter answers every question with the prompt's own default and -// never touches a terminal. archied setup uses it for --defaults, so an -// unattended install resolves every question the baseline Params do not -// cover without prompting: ReadLine returns defaultValue, Select returns the -// first option, Confirm returns defaultYes, and ReadSecret returns "" (a -// secret has no default, and the steps treat a blank secret as "leave blank -// to configure later"). +// DefaultPrompter answers every prompt with its default without a terminal: +// the default value, the first option, defaultYes, and "" for secrets. type DefaultPrompter struct{} // Select returns the first option. diff --git a/internal/infrastructure/configuration/setup/envsink.go b/internal/infrastructure/configuration/setup/envsink.go index 9574523eb..e3c2fa8b5 100644 --- a/internal/infrastructure/configuration/setup/envsink.go +++ b/internal/infrastructure/configuration/setup/envsink.go @@ -9,18 +9,9 @@ import ( "strings" ) -// EnvFileSink is a SecretSink that stores secrets in the env file beside -// config.toml (${XDG_CONFIG_HOME:-~/.config}/archie/env by default). The -// daemon reads that file through systemd's EnvironmentFile, so the line -// format must match what install.sh's set_env_key has always written -- a -// single-quoted KEY='value' line, with an embedded single quote escaped as a -// backslash between two single quotes -- rather than any other -// plausible-looking format. -// -// Put buffers; nothing is written until Commit, and Commit rewrites the file -// atomically with mode 0600. The caller must only Commit once the config -// text referencing these secrets has been proven loadable, so a validation -// failure leaves neither a config nor a secret on disk. +// EnvFileSink stores secrets as KEY='value' lines in the env file beside +// config.toml. Put buffers; Commit rewrites the file atomically with mode +// 0600. Commit only after the config is proven loadable. type EnvFileSink struct { path string entries map[string]string @@ -104,11 +95,8 @@ func readEnvLines(path string) ([]string, error) { return strings.Split(text, "\n"), nil } -// escapeEnvValue renders value as the contents of a single-quoted -// systemd EnvironmentFile value: a literal single quote becomes a backslash -// between two single quotes. This is byte-for-byte what install.sh's -// set_env_key produces, so the Go sink and the shell helper cannot disagree -// about the on-disk format. +// escapeEnvValue escapes v for a single-quoted EnvironmentFile value, as +// install.sh's set_env_key does. func escapeEnvValue(v string) string { return strings.ReplaceAll(v, "'", `'\''`) } diff --git a/internal/infrastructure/configuration/setup/prompter.go b/internal/infrastructure/configuration/setup/prompter.go index f3ebc70dd..9e1fb33d8 100644 --- a/internal/infrastructure/configuration/setup/prompter.go +++ b/internal/infrastructure/configuration/setup/prompter.go @@ -1,19 +1,9 @@ -// Package setup builds a config.Config and the TOML edits to persist it, -// driven by archied's interactive first-run configuration flow. It has no -// terminal dependency of its own: everything it needs from a user-facing -// prompt surface is the [Prompter] interface below, so the step logic is -// testable end to end without a TTY. package setup import "context" -// Prompter is what setup's step logic needs from a prompt surface. The real -// implementation talks to a terminal (internal/infrastructure/ -// terminalprompt); tests drive steps through a fake. -// -// Every method takes a context so a step can be cancelled mid-prompt (e.g. -// Ctrl+C) rather than leaving the operator stuck at a prompt an outer -// timeout or signal has already decided to abandon. +// Prompter is the prompt surface setup asks questions through. Every method +// takes a context so a prompt can be cancelled. type Prompter interface { // Select presents options and returns the chosen index. Returns -1 and // ctx.Err() if ctx is done before an answer is given. diff --git a/internal/infrastructure/configuration/setup/secretref.go b/internal/infrastructure/configuration/setup/secretref.go index 54d634a24..0db730004 100644 --- a/internal/infrastructure/configuration/setup/secretref.go +++ b/internal/infrastructure/configuration/setup/secretref.go @@ -15,11 +15,6 @@ import ( var engineNameRe = regexp.MustCompile(`^[A-Za-z0-9_-]+$`) // ParseSecretRef parses an "engine:key" secret reference. -// -// A reference is not a secret. An engine name and a key name are not sensitive, -// which is exactly why a reference may be given as a parameter while a value may -// not: the value lives in the engine, and this flow never sees it. Setup writes -// the reference to TOML and stops there. func ParseSecretRef(s string) (config.SecretRef, error) { engine, key, ok := strings.Cut(s, ":") if !ok { diff --git a/internal/infrastructure/configuration/setup/setup.go b/internal/infrastructure/configuration/setup/setup.go index fd9d4fdb3..92b8df683 100644 --- a/internal/infrastructure/configuration/setup/setup.go +++ b/internal/infrastructure/configuration/setup/setup.go @@ -1,10 +1,5 @@ -// Package setup drives archied's interactive first-run configuration flow -// and produces the TOML edits to persist it. See the [Run] doc comment for -// why it returns edits rather than a config.Config: the whole point of this -// feature is to stop the config-writing code and the config-reading code -// disagreeing about the schema, and building a second, parallel -// representation to validate against would reintroduce exactly that risk -// inside setup itself. +// Package setup runs archied's first-run configuration flow and returns the +// TOML edits to persist it. package setup import ( @@ -16,14 +11,8 @@ import ( "github.com/samcharles93/archie-core/internal/infrastructure/configuration/tomlwrite" ) -// SecretSink is where setup sends the secret values a step collects. setup -// edits config.toml keys; it does not write the env file itself. Put is -// expected to buffer rather than write immediately -- the caller commits only -// once the config text setup produced has been proven loadable, so a -// validation failure after some secrets were already prompted for never -// leaves a secret written without the config that references it, or vice -// versa. [EnvFileSink] is the concrete implementation for the env file that -// sits beside config.toml; the caller owns the path and constructs it. +// SecretSink receives the secret values setup collects. Put buffers; the +// caller commits once the generated config is proven loadable. type SecretSink interface { // Put records that key (as looked up through engine) must resolve to // value once Commit is called. @@ -53,19 +42,8 @@ type ExistingValues struct { // value and let Run decide the flattening order. type tableEdits = map[string]map[string]string -// Params supplies pre-answered values for the setup flow's question sites. -// Each step consults Params first and only asks the Prompter when the -// corresponding field is unset, so an unattended install can state what it -// wants without a terminal and without matching against prompt text -- the -// brittleness class removed in 9a4f11c (prompt text is not a stable key for -// a flag-to-answer mapping). -// -// Provider is a config class ("openai", "anthropic", "openrouter", "gemini", -// "groq", "deepseek", "mistral", or "ollama" for the self-hosted path). Model -// is the bare model name; the step adds the "class/" prefix. TelegramUserIDs -// non-empty is the signal to configure Telegram -- the step already refuses -// an empty allowlist, so an empty slice means "ask" (or "skip" when the -// prompter's default is no). +// Params pre-answers setup questions; a step prompts only for unset fields. +// Provider is a config class; Model is the bare model name. type Params struct { BotUser string Operator string @@ -74,34 +52,22 @@ type Params struct { Provider string // openai | anthropic | openrouter | gemini | groq | deepseek | mistral | ollama Model string // bare model name; the step adds the "class/" prefix - // TelegramUserIDs is an access policy, not a credential: IDs are not secret. - // Non-empty means "configure Telegram". - // The three reference fields below name where an already-stored secret - // lives, as engine:key. A reference is not a secret -- an engine name and a - // key name are not sensitive -- which is why a reference may be - // parameterised while a value may not. When one is set the step writes the - // reference to TOML and asks nothing, because the value is already in the - // engine and setup does not own it. + // TelegramUserIDs non-empty configures Telegram. The reference fields name + // already-stored secrets as engine:key; when set, the step writes the + // reference without prompting. ForgeTokenRef config.SecretRef ProviderAPIKeyRef config.SecretRef TelegramTokenRef config.SecretRef TelegramUserIDs []int64 - // There is deliberately no secret-valued field here, for forge tokens, - // provider API keys or bot tokens alike. Secrets are set in a secret engine - // and this flow only ever writes a reference to one; a value in Params would - // arrive from a command line, landing in shell history and process listings, - // and would be a second way to set a secret that no engine knows about. - // Values reach an engine through SecretSink, from a prompt. + // Secret values are never parameters; they come from a prompt through + // SecretSink. } -// Run drives the interactive setup flow and returns the TOML edits to -// apply. It does not read or write any file itself: the caller renders the -// edits (tomlwrite.Generate against a fresh template, or tomlwrite.Apply -// against an existing config's bytes for a re-run) and must prove the -// result loads through a real configuration.Loader before installing it or -// calling secrets.Commit. +// Run drives the setup flow and returns the TOML edits to apply. It writes no +// files; the caller must load the result before installing it or committing +// secrets. func Run(ctx context.Context, p Prompter, discovery ModelDiscovery, secrets SecretSink, existing ExistingValues) ([]tomlwrite.Edit, error) { return RunParams(ctx, p, discovery, secrets, existing, Params{}) } diff --git a/internal/infrastructure/configuration/setup/step_forge.go b/internal/infrastructure/configuration/setup/step_forge.go index d1c44cb0e..b6aa9240f 100644 --- a/internal/infrastructure/configuration/setup/step_forge.go +++ b/internal/infrastructure/configuration/setup/step_forge.go @@ -9,11 +9,7 @@ import ( "github.com/samcharles93/archie-core/internal/infrastructure/configuration/tomlwrite" ) -// forgeToken names the env var a forge type's token is stored under. Used -// by both the config edit (forge.token = {engine="env", key=...}) and the -// secret sink, for the same reason cloudProviders is a single table in -// step_provider.go: the installer's original bug was these two writes -// disagreeing. +// forgeToken maps a forge type to the env var its token is stored under. var forgeToken = map[string]string{ "github": "ARCHIE_GITHUB_TOKEN", "gitea": "ARCHIE_GITEA_TOKEN", @@ -90,22 +86,9 @@ func forgeChoice(name string) (int, error) { } } -// stepForgeWithToken records the forge type and host and, when the operator -// supplies one, stores the token in the secret engine and writes only the -// reference to TOML. -// -// The token is always read from the prompt surface. A secret must never travel -// as a parameter: a value passed in would arrive from a command line, where it -// lands in shell history and every process listing, and it would be a second -// way for a secret to be set that no secret engine knows about. -// stepForgeWithToken records the forge type and host and writes a reference to -// the token when one is configured. -// -// A tokenRef means the value already lives in a secret engine, so setup writes -// the reference and asks nothing. Otherwise the token comes from a prompt, and -// only from a prompt: a value supplied as a parameter would arrive from a -// command line, where it lands in shell history and every process listing, and -// would be a second way to set a secret that no engine knows about. +// stepForgeWithToken records the forge type and host and the token +// reference: tokenRef when set, otherwise a token read from the prompt and +// stored in the secret engine. func stepForgeWithToken(ctx context.Context, p Prompter, secrets SecretSink, forgeType, host, tokenPrompt string, tokenRef config.SecretRef) (tableEdits, error) { edits := tableEdits{"forge": { "type": tomlwrite.String(forgeType), diff --git a/internal/infrastructure/configuration/setup/step_provider.go b/internal/infrastructure/configuration/setup/step_provider.go index d9ecc8640..8ba3bcfe7 100644 --- a/internal/infrastructure/configuration/setup/step_provider.go +++ b/internal/infrastructure/configuration/setup/step_provider.go @@ -28,16 +28,8 @@ var cloudProviders = []cloudProvider{ {name: "Mistral", class: "mistral", apiKeyEnv: "MISTRAL_API_KEY"}, } -// templateDefaultActiveProvider is the one provider table config.example. -// toml ships active by default: [providers.openai], with -// api_key = {engine="bws", key="OPENAI_API_KEY"}. bws is compiled in but -// requires the bws CLI on PATH; on a machine without it (the common case) -// resolving that key fails, and resolveProviderSecrets disables the provider -// with a warning rather than stopping the daemon. Neutralising the table is -// still setup's business: a provider the operator never chose should not be -// left advertised and unusable, with a warning they did not cause. Choosing any -// provider other than OpenAI, or choosing OpenAI but leaving its key blank, -// therefore replaces this table. +// templateDefaultActiveProvider is the provider config.example.toml enables +// by default. Setup replaces that table unless OpenAI is chosen with a key. const templateDefaultActiveProvider = "openai" func stepProvider(ctx context.Context, p Prompter, discovery ModelDiscovery, secrets SecretSink, params Params) (tableEdits, string, error) { @@ -150,12 +142,8 @@ func stepCloudProvider(ctx context.Context, p Prompter, secrets SecretSink, cp c return edits, cp.class + "/" + model, nil } -// cloudKeyEdit obtains the api_key edit by prompting. An empty return means -// "write no api_key and leave whatever the template has", which is the -// configure-later case. -// -// There is no key parameter. A value supplied as one would arrive from a -// command line and bypass the secret engine entirely; see Params. +// cloudKeyEdit prompts for the API key and returns its edit. Empty means +// configure later. func cloudKeyEdit(ctx context.Context, p Prompter, secrets SecretSink, cp cloudProvider) (string, error) { key, err := p.ReadSecret(ctx, fmt.Sprintf("%s API key: ", cp.name)) if err != nil { diff --git a/internal/infrastructure/eventbus/nats/client.go b/internal/infrastructure/eventbus/nats/client.go index af38cdeb2..544b5b0f1 100644 --- a/internal/infrastructure/eventbus/nats/client.go +++ b/internal/infrastructure/eventbus/nats/client.go @@ -26,12 +26,8 @@ type Client struct { log *slog.Logger } -// Connect dials the broker and provisions the stream and pull consumer. The -// stream uses file storage and the retention policy from Config.Retention -// (defaulting to work-queue for task distribution). -// -// On any failure the partially-built connection is closed before returning, so -// a failed Connect leaks nothing. +// Connect dials NATS and creates the stream and pull consumer. On failure it +// closes the connection. func Connect(ctx context.Context, cfg Config, log *slog.Logger) (*Client, error) { if err := cfg.Validate(); err != nil { return nil, err @@ -129,15 +125,8 @@ func (c *Client) Close() { c.log.Debug("nats connection closed") } -// CoreConn exposes the raw connection for the NATS-specific RPC layers -// (forgerpc, worktreerpc, natsrpc) that register their own core-NATS -// subscriptions. The State Store is a gRPC contract, not a core-NATS RPC. -// -// This is the single sanctioned escape hatch and exists only because those -// packages are themselves NATS infrastructure, not domain code. Domain and -// application packages must use [Publisher], [Consumer] or [Requester] -// instead; taking the connection there would put SDK types back into their -// imports, which is what this package exists to prevent. +// CoreConn returns the raw connection for the NATS RPC packages. Other +// packages use Publisher, Consumer or Requester. func (c *Client) CoreConn() (*nats.Conn, error) { return c.connection() } // connection returns the live connection, or ErrNotConnected. @@ -148,13 +137,8 @@ func (c *Client) connection() (*nats.Conn, error) { return c.conn, nil } -// Connected reports whether this client's connection to the broker is live. -// -// It reads the connection the client already holds. It deliberately does not -// dial to check reachability: a fresh connection would report the dial's -// success rather than this process's own bus being up, and it would put a -// network round trip with its own timeout inside a caller that may be a chat -// command handler. +// Connected reports whether the client's connection is live, without +// dialing. func (c *Client) Connected() bool { conn, err := c.connection() if err != nil { diff --git a/internal/infrastructure/eventbus/nats/config.go b/internal/infrastructure/eventbus/nats/config.go index 3278083e4..50c434fbf 100644 --- a/internal/infrastructure/eventbus/nats/config.go +++ b/internal/infrastructure/eventbus/nats/config.go @@ -36,12 +36,7 @@ type Config struct { // StreamName is the JetStream stream holding the bound subjects. StreamName string - // Subjects are the subjects the stream carries. Required. - // - // Composition supplies these rather than the package hardcoding them: the - // bus must not know which subjects belong to which domain, and archied - // and archie-agent previously declared the same stream separately, free - // to disagree about its subjects, retention and dedup window. + // Subjects are the stream's subjects. Required. Subjects []string // ConsumerName is the durable pull consumer Fetch reads from. @@ -52,25 +47,11 @@ type Config struct { // Required. FilterSubject string - // Retention is the stream's retention policy. Nil defaults to - // jetstream.WorkQueuePolicy (each message claimed by exactly one - // consumer), which is correct for ARCHIE_TASKS task distribution. A - // fan-out reaction stream passes jetstream.LimitsPolicy so every - // registered consumer sees every matching event; under WorkQueuePolicy a - // second consumer on an overlapping filter subject silently receives - // nothing (the trap documented in CLAUDE.md). The pointer form is what - // lets "unset" default to WorkQueuePolicy when the policy's zero value - // (LimitsPolicy) is a valid explicit choice. + // Retention is the stream's retention policy. Nil means WorkQueuePolicy; + // fan-out streams use FanOutRetention. Retention *jetstream.RetentionPolicy - // MaxAge is the maximum age of messages the stream retains. Nil leaves - // the stream unbounded by age, which is correct for ARCHIE_TASKS: under - // WorkQueuePolicy acked messages are discarded, so its only bound is - // outstanding work. The pointer form distinguishes "unset" (nil, - // unbounded, today's behaviour) from an explicit zero (also unbounded, - // but expressed on purpose), exactly like Retention. The fan-out - // reaction stream sets a finite MaxAge so acknowledged reactions cannot - // accumulate forever. + // MaxAge bounds message age. Nil or zero means unbounded. MaxAge *time.Duration // DedupWindow is how long JetStream remembers a Nats-Msg-Id, suppressing @@ -142,13 +123,7 @@ func (c Config) withDefaults() Config { return c } -// FanOutRetention returns a pointer to jetstream.LimitsPolicy for use as -// Config.Retention. It exists so composition can select fan-out retention -// without importing the NATS SDK: the retention policy type stays behind this -// package's boundary, like every other JetStream type. LimitsPolicy is the one -// policy that cannot be expressed by leaving Retention unset (withDefaults -// treats nil as WorkQueuePolicy), so the choice must be visible at the call -// site. +// FanOutRetention returns jetstream.LimitsPolicy for Config.Retention. func FanOutRetention() *jetstream.RetentionPolicy { policy := jetstream.LimitsPolicy return &policy diff --git a/internal/infrastructure/eventbus/nats/consumer.go b/internal/infrastructure/eventbus/nats/consumer.go index eeee691ce..929e45c46 100644 --- a/internal/infrastructure/eventbus/nats/consumer.go +++ b/internal/infrastructure/eventbus/nats/consumer.go @@ -9,11 +9,8 @@ import ( "github.com/samcharles93/archie-core/internal/eventbus" ) -// Fetch returns the next message from the pull consumer. -// -// It reports eventbus.ErrNoMessage when the poll timeout expires with nothing -// queued. The original API returned (nil, nil) in that case, which every -// caller had to remember to distinguish from a real message. +// Fetch returns the next message, or eventbus.ErrNoMessage when the poll +// times out. func (c *Client) Fetch(ctx context.Context) (eventbus.Message, error) { if _, err := c.connection(); err != nil { return nil, fmt.Errorf("fetch: %w", err) diff --git a/internal/infrastructure/eventbus/nats/doc.go b/internal/infrastructure/eventbus/nats/doc.go index 0f2f163a5..7f65b9c8d 100644 --- a/internal/infrastructure/eventbus/nats/doc.go +++ b/internal/infrastructure/eventbus/nats/doc.go @@ -1,25 +1,4 @@ // Package nats is the NATS JetStream transport for task distribution and -// agent communication. -// -// It is infrastructure: it owns the broker connection, stream and consumer -// lifecycle, and the wire encoding of messages. It does not own workflow -// routing, task state, or any other domain behaviour. -// -// The package deliberately keeps NATS SDK types behind its own boundary. -// Callers receive [Message], not jetstream.Msg, and publish [TaskEnvelope] or -// [Request], not *nats.Msg. That keeps the broker replaceable and stops SDK -// types leaking into domain packages, per -// -// Layout: -// -// config.go connection and stream/consumer tuning -// errors.go sentinel errors callers match on -// subjects.go subject naming, pure and dependency-free -// message.go wire payloads and the Message wrapper -// client.go connection lifecycle -// publisher.go publishing -// consumer.go fetching -// -// An absent URL selects the authenticated embedded broker; external URLs change -// broker placement only. There is no single-process autonomous fallback. +// agent messaging. NATS SDK types do not leave the package. An empty URL +// uses the embedded broker. package nats diff --git a/internal/infrastructure/eventbus/nats/embedded.go b/internal/infrastructure/eventbus/nats/embedded.go index 149282274..0f849dfaf 100644 --- a/internal/infrastructure/eventbus/nats/embedded.go +++ b/internal/infrastructure/eventbus/nats/embedded.go @@ -10,15 +10,8 @@ import ( "github.com/nats-io/nats-server/v2/server" ) -// EmbeddedServer owns an in-process NATS server with JetStream enabled. It -// wraps nats-server/v2/server.Server so the SDK type never leaks past this -// package: callers get only the client URL and Shutdown, never the server. -// -// The daemon embeds one of these for single-process deployments so reaction -// delivery and task distribution share the same transport whether NATS runs -// as a separate server or in-process. The daemon -// owns the lifecycle: StartEmbedded before dialing the client, Shutdown after -// the client closes. +// EmbeddedServer is an in-process NATS server with JetStream. Start it +// before dialing and shut it down after the client closes. type EmbeddedServer struct { srv *server.Server log *slog.Logger @@ -73,11 +66,8 @@ func StartEmbedded(ctx context.Context, opts EmbeddedOptions, log *slog.Logger) } srv.Start() - // Start is asynchronous; wait for the accept loop. If the daemon's ctx is - // already cancelled (shutdown racing boot), stop the server rather than - // wait the full readiness window. A ctx cancelled during the wait is - // tolerated: the wait is bounded, and a healthy server is ready in - // milliseconds. + // Wait for the server to accept connections, or stop it if ctx is already + // cancelled. if err := ctx.Err(); err != nil { srv.Shutdown() return nil, fmt.Errorf("embedded nats startup: %w", err) diff --git a/internal/infrastructure/eventbus/nats/errors.go b/internal/infrastructure/eventbus/nats/errors.go index 19ea128b0..fae778dab 100644 --- a/internal/infrastructure/eventbus/nats/errors.go +++ b/internal/infrastructure/eventbus/nats/errors.go @@ -3,9 +3,4 @@ package nats import "errors" // ErrInvalidConfig reports a Config that cannot produce a usable client. -// -// The delivery-outcome sentinels a caller matches on -- no message, not -// connected, no reply address -- belong to the broker-neutral contract in -// internal/eventbus, so a caller can handle them without knowing which broker -// is in use. This package returns those, not copies of them. var ErrInvalidConfig = errors.New("nats: invalid configuration") diff --git a/internal/infrastructure/eventbus/nats/message.go b/internal/infrastructure/eventbus/nats/message.go index 6a262f501..d865ed7aa 100644 --- a/internal/infrastructure/eventbus/nats/message.go +++ b/internal/infrastructure/eventbus/nats/message.go @@ -12,11 +12,7 @@ import ( // with the same value inside Config.DedupWindow are suppressed by the server. const idempotencyHeader = "Nats-Msg-Id" -// message adapts a jetstream.Msg to the broker-neutral contract. -// -// It is unexported: callers receive it as an eventbus.Message, so no consumer -// can reach the SDK type through it. Fetch once returned jetstream.Msg -// directly, which put the NATS SDK in every consumer's imports. +// message adapts a jetstream.Msg to eventbus.Message. type message struct { msg jetstream.Msg } diff --git a/internal/infrastructure/eventbus/nats/publisher.go b/internal/infrastructure/eventbus/nats/publisher.go index 0a7d35330..5d5989989 100644 --- a/internal/infrastructure/eventbus/nats/publisher.go +++ b/internal/infrastructure/eventbus/nats/publisher.go @@ -36,11 +36,7 @@ func (c *Client) publish(ctx context.Context, msg *nats.Msg) error { return nil } -// Request performs a core-NATS request/reply and returns the response payload. -// -// This exists so callers never need the raw connection: the original API -// exposed Conn() *nats.Conn, which put the SDK type in every caller's -// imports. +// Request performs a core NATS request and returns the reply payload. func (c *Client) Request(ctx context.Context, subject string, payload []byte) ([]byte, error) { conn, err := c.connection() if err != nil { diff --git a/internal/infrastructure/memory/builtin_engine.go b/internal/infrastructure/memory/builtin_engine.go index 24108d7be..c19a77adf 100644 --- a/internal/infrastructure/memory/builtin_engine.go +++ b/internal/infrastructure/memory/builtin_engine.go @@ -66,12 +66,8 @@ type BuiltinEngine struct { log *slog.Logger } -// NewBuiltinEngine builds an engine that persists each scope under its own -// subdirectory of root, named hex(sha256(scope.Key())): never the key or an -// id as a path component, so an opaque channel id can never traverse out of -// root and two ids a filesystem treats as equivalent can never collide. -// maxFileBytes <= 0 uses the store's own default for the live document; -// HISTORY.md always uses historyMaxFileBytes. +// NewBuiltinEngine stores each scope under root/hex(sha256(scope.Key())). +// maxFileBytes <= 0 uses the store default. func NewBuiltinEngine(root string, maxFileBytes int) *BuiltinEngine { return &BuiltinEngine{root: root, maxFileBytes: maxFileBytes, stores: make(map[string]*scopeStores)} } @@ -83,17 +79,7 @@ func (e *BuiltinEngine) Manifest() domainmemory.Manifest { return domainmemory.Manifest{RequiresNetwork: false} } -// Bind takes the registrar's clock, which stamps CreatedAt/UpdatedAt, and its -// optional logger. -// -// It deliberately ignores Registrar.Events. The only warn-level finding this -// engine produces is a scanner hit, and there is no ratified memory event -// vocabulary to emit it in: internal/events declares kinds for tasks, -// curators, workflow stages and scheduling, none for memory, and the -// composition binds no memory event sink at all (bootstrap registers the -// engine with an empty Registrar). Emitting an invented kind into a sink -// nobody binds would look wired and not be. The scanner's warning is a -// diagnostic, not an event, and goes to Registrar.Log (see scanContent). +// Bind takes the registrar's clock and logger. func (e *BuiltinEngine) Bind(host domainmemory.Registrar) { e.clock = host.Clock e.log = host.Log @@ -126,14 +112,8 @@ func (e *BuiltinEngine) now() time.Time { // ── storage ──────────────────────────────────────────────────────────── -// scopeStoresFor returns the scope's document pair, opening it on first use -// and caching it. create is false on every read path: a read must not leave -// a scope directory behind, and a scope nothing was ever written to answers -// as absent rather than as empty-but-created. -// -// Callers must have validated the scope already: Scope.Key() is empty for an -// invalid scope, and caching on "" would pool every invalid scope into one -// store under one directory. +// scopeStoresFor returns the scope's cached document pair. create is false +// for reads, which never create a directory. scope must be valid. func (e *BuiltinEngine) scopeStoresFor(scope domainmemory.Scope, create bool) (*scopeStores, bool, error) { key := scope.Key() e.mu.Lock() @@ -188,16 +168,8 @@ func sectionFor(kind string) (string, error) { return kind, nil } -// scanContent applies the family's scanner to content about to be persisted, -// before anything is written. -// -// A block-level threat fails the write loudly -- loudly, because a scanner -// hit that only logs is a control that looks wired and is not -- while a -// warn-level hit is stored and logged, which is what its level is documented -// to mean ("allow the write but emit a warning"). Warn covers the -// sensitive-data patterns: an API key, a token or a private key in stored -// content is worth an audit line even though it is not worth refusing the -// write over, and a warning that goes nowhere is the same as no scan at all. +// scanContent rejects content with a block-level scanner hit and logs +// warn-level hits. func (e *BuiltinEngine) scanContent(content string) error { result := contentScanner.ScanContent(content) switch result.Level { @@ -212,18 +184,8 @@ func (e *BuiltinEngine) scanContent(content string) error { return nil } -// storeContent returns the content a block will actually hold, so that the -// record Create and Update answer with is the record a later Get reads back -// rather than what the caller handed in. -// -// The trimming is what makes that true at the content's edges: builtin.Store -// trims a block, so content that begins or ends with whitespace would come -// back without it -- or, for whitespace that is itself a blank line, as an -// empty record. Content that is nothing but whitespace is rejected here for -// the same reason. Interior blank lines and "## " lines are the block -// format's own delimiters rather than whitespace at an edge, and are carried -// through instead: renderBlock escapes them and parseBlocks undoes it, so -// accepted content is never cut at one. +// storeContent returns content as it will be stored: trimmed, and rejected +// when empty. func storeContent(content string) (string, error) { trimmed := strings.TrimSpace(content) if trimmed == "" { @@ -332,11 +294,8 @@ func (e *BuiltinEngine) List(_ context.Context, scope domainmemory.Scope) ([]dom return orderHeads(records), nil } -// orderHeads returns heads most recently updated first. The input is in -// document order, which is creation order for a document this engine wrote; -// reversing before the stable sort makes creation order the tie-break for two -// records sharing an UpdatedAt, which is the common case for a coarse clock or -// one Create burst. +// orderHeads returns heads most recently updated first, ties in creation +// order. func orderHeads(records []domainmemory.Record) []domainmemory.Record { slices.Reverse(records) slices.SortStableFunc(records, func(a, b domainmemory.Record) int { @@ -400,14 +359,7 @@ func (e *BuiltinEngine) Update(_ context.Context, in domainmemory.RecordUpdate) return domainmemory.Record{}, notFound(in.Scope, in.ID) } - // Read the document as it is on disk before anything is decided from it. - // This engine caches the scope's document and rewrites it whole, so the - // copy it holds can be a whole write out of date -- the Expected check - // below would compare against a revision that is already superseded, and - // the rewrite that follows it would write the stale copy back over the - // current one. What this does not fix: the rewrite is still - // last-writer-wins for this record and every other one, between the reload - // and the write. + // Reload from disk before checking Expected. if err := stores.live.Reload(); err != nil { return domainmemory.Record{}, err } diff --git a/internal/infrastructure/memory/history.go b/internal/infrastructure/memory/history.go index efc42b518..b690dd6ab 100644 --- a/internal/infrastructure/memory/history.go +++ b/internal/infrastructure/memory/history.go @@ -18,14 +18,7 @@ const historyFileName = "HISTORY.md" // grouping by kind would be a second index over the same file. const historySectionName = "history" -// historyMaxFileBytes bounds each scope's HISTORY.md, deliberately far above -// the live document's bound (builtin's 100KB default, which is what -// production passes: bootstrap builds the engine with a 0 maxFileBytes). -// -// It has its own bound because history grows on every Update and every Forget -// while the live document does not. That question stays open; this bound only -// makes reaching it a deliberate, enormous amount of history rather than an -// accident. +// historyMaxFileBytes bounds each scope's HISTORY.md. const historyMaxFileBytes = 4 * 1024 * 1024 // appendHistory appends one retained state -- the record as it was while @@ -45,12 +38,7 @@ func appendHistory(h *builtin.Store, m markerData, content string, at time.Time, return nil } -// revisionsOf returns one record's retained states as HISTORY.md holds them, -// oldest first. Document order is append order, and a retained state is -// appended exactly when it stops being live, so no sort is needed -- or -// wanted: a crash between a history append and the live write leaves two -// entries for one revision, and sorting would not make -// that less true. +// revisionsOf returns one record's retained states, oldest first. func revisionsOf(h *builtin.Store, scope domainmemory.Scope, id domainmemory.RecordID) []domainmemory.Revision { var revisions []domainmemory.Revision for _, block := range parseBlocks(h.Render()) { diff --git a/internal/infrastructure/memory/marker.go b/internal/infrastructure/memory/marker.go index 12c1247ef..6bdcf3599 100644 --- a/internal/infrastructure/memory/marker.go +++ b/internal/infrastructure/memory/marker.go @@ -16,13 +16,8 @@ const ( markerSuffix = "-->" ) -// markerData is the provenance one block's marker carries. The same shape is -// written into a scope's live document and into its HISTORY.md; the last two -// fields are set only on a retained state, so a live block never carries -// them. -// -// json escapes newlines, so the marker is always exactly one line: a field -// containing one cannot break the block's first-line shape. +// markerData is a block's provenance. The last two fields are set only on +// retained states. JSON keeps the marker on one line. type markerData struct { ID string `json:"id"` Revision int `json:"revision"` diff --git a/internal/infrastructure/memory/parse.go b/internal/infrastructure/memory/parse.go index 824ae8492..86abbce64 100644 --- a/internal/infrastructure/memory/parse.go +++ b/internal/infrastructure/memory/parse.go @@ -6,19 +6,8 @@ import ( domainmemory "github.com/samcharles93/archie-core/internal/domain/memory" ) -// sectionHeaderPrefix matches the markdown store's own format (builtin's -// sectionHeaderPrefix is unexported): a "## " line starts a named section, -// and blocks within it are separated by one blank line. This package only -// reads back what it wrote through builtin.Store.Add, so it only needs that -// one documented format, not the general case builtin.Store itself parses. -// -// Those two delimiters are the format's structure, and builtin.Store owns -// them: a blank line ends a block and a "## " line starts a section, so -// content holding either would be read back as structure -- cut at the -// delimiter, the remainder unaddressable. Content is therefore escaped on -// the way out and unescaped on the way back (see encodeBlockContent), which -// keeps a record's content whole without giving the store a second format to -// parse. +// sectionHeaderPrefix starts a section in the store's format. Blank lines +// and "## " lines in content are escaped (see encodeBlockContent). const sectionHeaderPrefix = "## " // parsedBlock is one marked block read back out of a rendered document: the @@ -75,16 +64,8 @@ func renderBlock(m markerData, content string) (string, error) { // otherwise read as structure. const contentEscape = `\` -// encodeBlockContent escapes the content lines the store's format would -// otherwise read as its own structure -- a blank line ends a block, and a -// "## " line starts a section -- so that a record's content survives the -// write whole (see sectionHeaderPrefix). An empty line becomes one backslash, -// and a line already starting with a backslash or with "## " gains one, so -// the two are never ambiguous: everything is written verbatim except lines -// that start with a backslash, and every content line can therefore be -// recovered by dropping the backslash it starts with (decodeBlockContent). -// The common record -- one paragraph, no delimiter in sight -- is written -// exactly as the caller wrote it, so the document stays hand-editable. +// encodeBlockContent escapes blank lines and lines starting with "## " or a +// backslash by prefixing a backslash. decodeBlockContent reverses it. func encodeBlockContent(content string) string { lines := strings.Split(content, "\n") for i, line := range lines { @@ -112,17 +93,8 @@ func decodeBlockContent(text string) string { return strings.Join(lines, "\n") } -// parseBlocks reads every marked block out of a rendered document. -// -// A block with no marker, or one whose marker does not decode, was not -// written by this engine -- an operator hand-edited the file, or it predates -// the marker -- and is skipped. This engine's Store contract is only ever -// asked about records it assigned an id to, so inventing an id for an -// unmarked block would be a worse answer than not seeing it. -// -// Blocks are returned in document order, which is append order for a -// document this engine wrote, and therefore the order HISTORY.md's retained -// states come back in. +// parseBlocks returns the marked blocks in a document, in order. Unmarked or +// undecodable blocks are skipped. func parseBlocks(rendered string) []parsedBlock { var blocks []parsedBlock section := "" diff --git a/internal/infrastructure/servicediscovery/nats/doc.go b/internal/infrastructure/servicediscovery/nats/doc.go index b1c3ac0bb..2166ddf9c 100644 --- a/internal/infrastructure/servicediscovery/nats/doc.go +++ b/internal/infrastructure/servicediscovery/nats/doc.go @@ -1,48 +1,8 @@ -// Package nats is the NATS JetStream KV transport for service discovery. +// Package nats implements service discovery on NATS JetStream KV. // -// It implements the broker-neutral [servicediscovery.ServiceRegistry] contract -// against a JetStream KeyValue store, and additionally provides the -// registration side a service uses to announce itself. It is the fallback -// discovery mechanism for single-host, no-Kubernetes installs; the -// Kubernetes-native primary is a sibling implementation of the same contract. -// -// # Two buckets: presence versus liveness -// -// The NotInstalled/Down distinction (the governing semantic of -// [servicediscovery]) requires modelling a service's presence separately from -// any instance's liveness. NATS KV cannot express that with one bucket, -// because a bucket-wide TTL (needed so stale heartbeats expire) would also -// expire the "installed" record, collapsing Down into NotInstalled. So the -// implementation uses two buckets: -// -// - Registry bucket (heartbeats): one key per live instance, refreshed on a -// heartbeat interval and expired by a bucket-wide TTL. Presence of a key -// here means the instance is live. -// - Installed bucket (marker): one key per service, written once at first -// registration with no TTL, never expires. Presence of this marker means -// the service was installed; absence means never installed => NotInstalled. -// -// A service that registered once but whose instances have all gone is still -// installed (its marker persists) and simply has zero live endpoints, so -// [Client.Resolve] returns an empty slice with no error. Only a service that -// never wrote a marker resolves to [servicediscovery.ErrNotInstalled]. -// -// # Key scheme -// -// Instance heartbeat keys are "." (dot-separated), and -// the installed marker key is "". The dot separator is a deliberate -// deviation from the research sketch's "/": NATS KV -// watch filters match on dot-separated subject tokens, so a per-service watch -// of "curator.*" must see "curator.inst-1" as two tokens. A slash would make -// the whole key a single opaque token that no per-service wildcard can match. -// Consequently both service names and instance IDs must avoid the dot -// character; standard slugs and UUIDs satisfy that. -// -// Layout: -// -// config.go connection and bucket tuning, defaults and validation -// errors.go sentinel errors callers match on -// keys.go key scheme, pure and dependency-free -// registry.go the ServiceRegistry client (Resolve/Watch) -// registrar.go the registration side (announce + heartbeat) +// A heartbeat bucket holds one TTL'd key per live instance, +// ".". An installed bucket holds one permanent marker +// per service, "". A service with a marker and no live instances is +// installed with no endpoints; one with no marker is not installed. Names +// and IDs must not contain dots. package nats diff --git a/internal/infrastructure/servicediscovery/nats/errors.go b/internal/infrastructure/servicediscovery/nats/errors.go index 4f1d0d3fa..fae778dab 100644 --- a/internal/infrastructure/servicediscovery/nats/errors.go +++ b/internal/infrastructure/servicediscovery/nats/errors.go @@ -3,9 +3,4 @@ package nats import "errors" // ErrInvalidConfig reports a Config that cannot produce a usable client. -// -// The delivery-outcome sentinel a caller matches on -- NotInstalled -- belongs -// to the broker-neutral contract in internal/servicediscovery, so a caller can -// handle it without knowing which registry is in use. This package returns -// that, not a copy of it. var ErrInvalidConfig = errors.New("nats: invalid configuration") diff --git a/internal/infrastructure/servicediscovery/nats/keys.go b/internal/infrastructure/servicediscovery/nats/keys.go index d698f8388..75b0da1e9 100644 --- a/internal/infrastructure/servicediscovery/nats/keys.go +++ b/internal/infrastructure/servicediscovery/nats/keys.go @@ -2,11 +2,7 @@ package nats import "strings" -// keySeparator joins a service and an instance ID in a registry key. It is a -// dot rather than the research sketch's slash so that a per-service watch -// filter ("curator.*") matches "curator.inst-1" as two NATS subject tokens; -// a slash would make the whole key one opaque token no wildcard could match. -// See the package doc comment for the full reasoning. +// keySeparator joins a service and an instance ID in a registry key. const keySeparator = "." // endpointKey is the heartbeat bucket key for one live instance. diff --git a/internal/infrastructure/servicediscovery/nats/registrar.go b/internal/infrastructure/servicediscovery/nats/registrar.go index 51a9091f3..9542d66e9 100644 --- a/internal/infrastructure/servicediscovery/nats/registrar.go +++ b/internal/infrastructure/servicediscovery/nats/registrar.go @@ -14,20 +14,9 @@ import ( "github.com/samcharles93/archie-core/internal/servicediscovery" ) -// Register announces service's instance ep with the registry and keeps its -// heartbeat fresh until the returned Registration is unregistered or ctx is -// cancelled. -// -// It writes the service's durable installed marker once (idempotent: an -// existing marker is left alone) -- that marker is what makes the service -// "installed" rather than NotInstalled -- then writes a live heartbeat entry -// for ep and refreshes it on an interval. If the service's process stops -// without calling Unregister (its ctx is cancelled, or it crashes), the entry -// expires via the bucket TTL and watchers observe a Leave; only an explicit -// uninstall of the whole service removes the installed marker. -// -// ep.ID must be non-empty and must not contain the registry key separator; the -// service name must likewise avoid the separator (see the package doc). +// Register writes service's installed marker if missing and heartbeats ep +// until it is unregistered or ctx ends. ep.ID and service must not contain +// the key separator. func (c *Client) Register(ctx context.Context, service string, ep servicediscovery.Endpoint) (*Registration, error) { if ep.ID == "" { return nil, fmt.Errorf("register %s: %w: endpoint ID is required", service, ErrInvalidConfig) diff --git a/internal/infrastructure/servicediscovery/nats/registry.go b/internal/infrastructure/servicediscovery/nats/registry.go index 7a7d39b4e..b933e0b84 100644 --- a/internal/infrastructure/servicediscovery/nats/registry.go +++ b/internal/infrastructure/servicediscovery/nats/registry.go @@ -24,11 +24,8 @@ var _ servicediscovery.ServiceRegistry = (*Client)(nil) // presence matters; the value exists so the bucket is self-describing. var installedMarkerValue = []byte("installed") -// Client owns the NATS connection and the two registry buckets: a heartbeat -// bucket (one live endpoint per instance) and a durable installed bucket (one -// marker per service that has ever registered). It implements -// [servicediscovery.ServiceRegistry] and provides the registration side a -// service uses to announce itself. +// Client implements servicediscovery.ServiceRegistry and registration over +// the heartbeat and installed buckets. type Client struct { conn *nats.Conn kv jetstream.KeyValue // heartbeat bucket @@ -37,13 +34,8 @@ type Client struct { log *slog.Logger } -// Connect dials the broker and provisions the two registry buckets. The bucket -// that carries heartbeats is configured with a TTL so stale entries expire -// (with a marker TTL so watchers observe the expiry as a leave); the installed -// bucket has no TTL so a marker persists for the life of the install. -// -// On any failure the partially-built connection is closed before returning, so -// a failed Connect leaks nothing. +// Connect dials NATS and creates the heartbeat bucket (with TTL) and the +// installed bucket (without). On failure it closes the connection. func Connect(ctx context.Context, cfg Config, log *slog.Logger) (*Client, error) { cfg = cfg.withDefaults() if err := cfg.Validate(); err != nil { @@ -138,13 +130,8 @@ func (c *Client) Close() { c.log.Debug("service registry connection closed") } -// Resolve returns the current healthy endpoints for service. -// -// It returns servicediscovery.ErrNotInstalled when the service's installed -// marker is absent (the service was never installed). When the service is -// installed but has no live endpoint right now -- all its heartbeats expired or -// were unregistered -- it returns a possibly-empty slice and a nil error. That -// distinction is the contract's governing semantic; see the package doc. +// Resolve returns service's live endpoints, possibly none. It returns +// servicediscovery.ErrNotInstalled when the service has no marker. func (c *Client) Resolve(ctx context.Context, service string) ([]servicediscovery.Endpoint, error) { if err := c.requireInstalled(ctx, service); err != nil { return nil, err @@ -191,15 +178,9 @@ func (c *Client) Resolve(ctx context.Context, service string) ([]servicediscover return eps, nil } -// Watch returns a channel that emits Join and Leave events as service's -// membership changes, until ctx is cancelled. The channel is closed when ctx -// is cancelled. -// -// It returns servicediscovery.ErrNotInstalled when the service's installed -// marker is absent at call time. A service that is installed but has no live -// endpoint returns a live channel that simply does not emit until an endpoint -// joins. Watching a service that becomes installed only after this call returns -// requires re-calling Watch. +// Watch emits Join and Leave events for service until ctx ends, then closes +// the channel. It returns servicediscovery.ErrNotInstalled when the service +// has no marker. func (c *Client) Watch(ctx context.Context, service string) (<-chan servicediscovery.Event, error) { if err := c.requireInstalled(ctx, service); err != nil { return nil, err @@ -215,15 +196,8 @@ func (c *Client) Watch(ctx context.Context, service string) (<-chan servicedisco return out, nil } -// fanWatch translates KV updates into contract Events until ctx is cancelled or -// the underlying watcher closes. -// -// A live instance heartbeats by re-Putting its key, which the KV watch reports -// as another Put. That must not be re-emitted as a Join: only a genuine -// appearance of an ID (including its first appearance in the initial snapshot) -// is a Join, and only its genuine disappearance is a Leave. The known set -// deduplicates refreshes so the stream carries membership changes, not -// liveness pings. +// fanWatch converts KV updates to Join and Leave events until ctx ends, +// ignoring heartbeat refreshes. func (c *Client) fanWatch(ctx context.Context, service string, watcher jetstream.KeyWatcher, out chan<- servicediscovery.Event) { defer close(out) defer func() { _ = watcher.Stop() }() @@ -283,13 +257,8 @@ func (c *Client) requireInstalled(ctx context.Context, service string) error { return nil } -// eventFromEntry converts one KV entry into a contract Event. -// -// A Put is a Join, and its value carries the full endpoint. A delete or purge -// marker -- including one left by a heartbeat TTL expiry -- is a Leave; the -// value is gone, so it reconstructs the instance from the key with an empty -// address (the ID still identifies the instance). It reports false for an entry -// it cannot interpret. +// eventFromEntry converts a KV entry to an event: a Put is a Join, a delete +// or expiry a Leave. It reports false for an entry it cannot read. func eventFromEntry(service string, entry jetstream.KeyValueEntry) (servicediscovery.Event, bool) { switch entry.Operation() { case jetstream.KeyValuePut: