refactor(setup,messaging,container,agentworker,discovery,memory,eventbus): cut comments down to what the code does

This commit is contained in:
sam committed 2026-10-03 22:02:57 +10:00
1 parent e10980dc33
commit 0cbb65c684
36 files changed
+179 -824

No files matched your search

+4 -12
View File
@@ -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...),
+3 -12
View File
@@ -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 {
+16 -88
View File
@@ -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
+1 -7
View File
@@ -1,12 +1,6 @@
package agentworker
// version is stamped per release artifact via
// "-ldflags -X github.com/samcharles93/archie-core/internal/app/agentworker.version=<value>",
// 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
+3 -19
View File
@@ -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() },
+7 -22
View File
@@ -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()
+2 -6
View File
@@ -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 (
+6 -28
View File
@@ -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)
+4 -16
View File
@@ -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 {
@@ -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
+2 -4
View File
@@ -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
+28 -116
View File
@@ -53,15 +53,8 @@ type TaskPayload struct {
Inputs map[string]any `json:"inputs,omitempty"`
}
// WriteTaskJSON writes the task payload to <workspace>/.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 <workspace>/.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 {
@@ -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.
@@ -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, "'", `'\''`)
}
@@ -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.
@@ -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 {
@@ -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{})
}
@@ -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),
@@ -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 {
@@ -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 {
@@ -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
@@ -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)
+2 -23
View File
@@ -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
@@ -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)
@@ -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")
@@ -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
}
@@ -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 {
@@ -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
}
+2 -14
View File
@@ -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()) {
+2 -7
View File
@@ -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"`
+6 -34
View File
@@ -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 := ""
@@ -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 "<service>.<instance-id>" (dot-separated), and
// the installed marker key is "<service>". The dot separator is a deliberate
// deviation from the research sketch's "<service>/<instance-id>": 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,
// "<service>.<instance-id>". An installed bucket holds one permanent marker
// per service, "<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
@@ -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")
@@ -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.
@@ -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)
@@ -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: