refactor(setup,messaging,container,agentworker,discovery,memory,eventbus): cut comments down to what the code does
This commit is contained in:
1 parent
e10980dc33
commit
0cbb65c684
36 files changed
+179
-824
No files matched your search
@@ -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...),
|
||||
|
||||
@@ -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 {
|
||||
|
||||
@@ -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,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
|
||||
|
||||
@@ -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() },
|
||||
|
||||
@@ -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()
|
||||
|
||||
@@ -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 (
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
@@ -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)
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
@@ -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()) {
|
||||
|
||||
@@ -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,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:
|
||||
|
||||
Reference in new issue
Block a user