refactor(staterpc,releaseupdate,agentexec,storecontract,worktree): cut comments down to what the code does
This commit is contained in:
1 parent
ee5f59e189
commit
2fc11b60e1
22 files changed
+175
-822
No files matched your search
@@ -40,13 +40,9 @@ type LoopRunner struct {
|
||||
// Limits bounds the size of tool results fed back into the stage. The
|
||||
// zero value applies no limits.
|
||||
Limits ToolLimits
|
||||
// AllowTools is the agent profile's allowlist over the tools archie adds
|
||||
// (central/MCP, repository scripts and skill plugins). Empty allows them
|
||||
// all. A stage's capture tools are how it returns structured results, so
|
||||
// they are never filtered. The agent loop's built-in file tools are not
|
||||
// covered either: ai-sdk agentloop registers them itself with no filter
|
||||
// hook, so they are always present (read-only when the stage asks), and
|
||||
// restricting them needs an ai-sdk change.
|
||||
// AllowTools is the profile's allowlist over archie-added tools. Empty allows
|
||||
// all. Capture tools and agentloop's built-in file tools are never
|
||||
// filtered.
|
||||
AllowTools []string
|
||||
}
|
||||
|
||||
@@ -62,16 +58,8 @@ func NewLoopRunner(
|
||||
return runner
|
||||
}
|
||||
|
||||
// workspaceToolset names the central-registry toolset a task agent must not
|
||||
// inherit. Those tools are rooted at the chat workspace, not the task's
|
||||
// worktree, and they reach the filesystem through their own handlers -- so
|
||||
// agentloop's ReadOnly and ProtectPaths, which gate only the tools agentloop
|
||||
// registers itself, do not apply to them. A feasibility stage running
|
||||
// ReadOnly could otherwise write, and a TDD fix stage could edit the very
|
||||
// tests it is being graded against.
|
||||
//
|
||||
// This is an invariant of task execution rather than a deployment choice, so
|
||||
// it is not configurable.
|
||||
// workspaceToolset is the central toolset a task agent never gets: its tools
|
||||
// work on the chat workspace and bypass ReadOnly and ProtectPaths.
|
||||
const workspaceToolset = "workspace"
|
||||
|
||||
func (r *LoopRunner) Run(ctx context.Context, workspace string, req Request, report ToolCallReporter) (Result, error) {
|
||||
@@ -357,12 +345,8 @@ func isNonEmptyString(object map[string]json.RawMessage, field string) bool {
|
||||
return ok && json.Unmarshal(raw, &text) == nil && strings.TrimSpace(text) != ""
|
||||
}
|
||||
|
||||
// scriptToolSet exposes run_go_script: interpreting a Yaegi Go script
|
||||
// bundled with a skill or living
|
||||
// anywhere else in the workspace, and returning what it printed. This is
|
||||
// how an agent following a skill's instructions ("run scripts/gitleaks.go
|
||||
// to scan for secrets") actually executes a .go helper without a Go
|
||||
// toolchain in the sandbox.
|
||||
// scriptToolSet exposes run_go_script, which runs a Yaegi Go script from the
|
||||
// workspace and returns its output.
|
||||
func scriptToolSet(workspace string) core.ToolSet {
|
||||
return core.ToolSet{
|
||||
"run_go_script": core.NewTypedTool(
|
||||
|
||||
@@ -52,13 +52,8 @@ type CaptureTool struct {
|
||||
RequiredFields []string `json:"required_fields,omitempty"`
|
||||
NonEmptyStrings []string `json:"non_empty_strings,omitempty"`
|
||||
BooleanFields []string `json:"boolean_fields,omitempty"`
|
||||
// RequiredWhenTrue makes fields required only when a boolean field in
|
||||
// the same call is true, keyed by that boolean's name. It exists because
|
||||
// a flat RequiredFields entry cannot express "name a workflow, but only
|
||||
// when you have said one is needed": the alternatives were forcing a
|
||||
// meaningless answer on the other branch, or accepting the omission and
|
||||
// defaulting it, which lets the model skip the decision entirely.
|
||||
// A named field must also be a non-empty string when the trigger is true.
|
||||
// RequiredWhenTrue lists fields that must be non-empty strings when the named
|
||||
// boolean field is true.
|
||||
RequiredWhenTrue map[string][]string `json:"required_when_true,omitempty"`
|
||||
MaxCalls int `json:"max_calls,omitempty"`
|
||||
}
|
||||
|
||||
@@ -15,12 +15,8 @@ import (
|
||||
// turn-sized output allowance on a single request.
|
||||
const DefaultSamplingMaxTokens = 4096
|
||||
|
||||
// SamplingMessages maps a server's sampling messages onto chat messages. Both
|
||||
// MCP sampling host paths use it -- the daemon's chat handler and the agent
|
||||
// worker's task handler -- so the same server is answered the same way
|
||||
// wherever the client runs. A non-text content block or an unknown role is
|
||||
// rejected rather than silently dropped: answering from a partial prompt would
|
||||
// be a wrong answer, not a degraded one.
|
||||
// SamplingMessages converts sampling messages to chat messages. Non-text
|
||||
// content and unknown roles are errors.
|
||||
func SamplingMessages(req protocol.SamplingRequest) ([]chat.Message, error) {
|
||||
if len(req.Messages) == 0 {
|
||||
return nil, errors.New("mcp sampling: the request has no messages")
|
||||
@@ -44,13 +40,8 @@ func SamplingMessages(req protocol.SamplingRequest) ([]chat.Message, error) {
|
||||
return messages, nil
|
||||
}
|
||||
|
||||
// SamplingMaxTokens bounds a delegated completion to the request's own
|
||||
// maxTokens, falling back to DefaultSamplingMaxTokens, and never past the
|
||||
// model's own output ceiling (zero when the ceiling is unknown). A
|
||||
// reasoning-class model gets no bound at all: its provider rejects the
|
||||
// `max_tokens` parameter the chat-completions provider emits for a non-zero
|
||||
// bound. Both the daemon's chat path and the agent worker answer sampling
|
||||
// with this, so the same server gets the same bound on either path.
|
||||
// SamplingMaxTokens returns the request's maxTokens or the default, capped at
|
||||
// the model's ceiling. Reasoning models get no bound.
|
||||
func SamplingMaxTokens(requested, modelCeiling int, reasoning bool) int {
|
||||
maxTokens := requested
|
||||
if maxTokens <= 0 {
|
||||
|
||||
@@ -6,10 +6,6 @@ import (
|
||||
)
|
||||
|
||||
// Agent observability subjects.
|
||||
//
|
||||
// These belong to this package because it defines what an agent request and
|
||||
// response mean. They previously sat in the NATS package, which made the
|
||||
// transport the owner of Archie's agent protocol.
|
||||
const (
|
||||
// SubjectSystemWildcard matches every task's system subject, for a
|
||||
// daemon subscribing to all of them at once with a single core NATS
|
||||
@@ -46,11 +42,8 @@ func subjectForTask(taskID int64, kind string) string {
|
||||
return subjectAgentPrefix + strconv.FormatInt(taskID, 10) + "." + kind
|
||||
}
|
||||
|
||||
// TaskIDFromSystemSubject extracts the task ID from a subject produced by
|
||||
// SubjectForSystem, for a daemon demuxing a SubjectSystemWildcard
|
||||
// subscription. Rejects (0, false) for anything that isn't exactly that
|
||||
// shape, rather than parsing a partial or wrong-kind subject into a
|
||||
// misleading task ID.
|
||||
// TaskIDFromSystemSubject extracts the task ID from a SubjectForSystem
|
||||
// subject.
|
||||
func TaskIDFromSystemSubject(subject string) (int64, bool) {
|
||||
if !strings.HasPrefix(subject, subjectAgentPrefix) || !strings.HasSuffix(subject, subjectSystemSuffix) {
|
||||
return 0, false
|
||||
@@ -63,11 +56,8 @@ func TaskIDFromSystemSubject(subject string) (int64, bool) {
|
||||
return id, true
|
||||
}
|
||||
|
||||
// TaskIDFromEventsSubject extracts the task ID from a subject produced by
|
||||
// SubjectForEvents, for a daemon demuxing a SubjectEventsWildcard
|
||||
// subscription. Rejects (0, false) for anything that isn't exactly that
|
||||
// shape, rather than parsing a partial or wrong-kind subject into a
|
||||
// misleading task ID.
|
||||
// TaskIDFromEventsSubject extracts the task ID from a SubjectForEvents
|
||||
// subject.
|
||||
func TaskIDFromEventsSubject(subject string) (int64, bool) {
|
||||
if !strings.HasPrefix(subject, subjectAgentPrefix) || !strings.HasSuffix(subject, subjectEventsSuffix) {
|
||||
return 0, false
|
||||
|
||||
@@ -10,41 +10,14 @@ import (
|
||||
"github.com/samcharles93/archie-core/internal/logging"
|
||||
)
|
||||
|
||||
// LogPublisher is the minimal capability SystemLogHandler needs: fire a
|
||||
// message at a subject without waiting for a reply. Declared here rather
|
||||
// than taking *nats.go's Conn or eventbus.Bus so the handler can be tested
|
||||
// with a fake and never gains capabilities (subscribe, request/reply) it has
|
||||
// no use for. *nats.Conn already satisfies this with no adapter needed.
|
||||
// LogPublisher publishes a message to a subject without waiting.
|
||||
type LogPublisher interface {
|
||||
Publish(subject string, data []byte) error
|
||||
}
|
||||
|
||||
// SystemLogHandler tees slog records to a wrapped handler -- normally the
|
||||
// agent's own stderr, kept for an operator attached to a live container --
|
||||
// and additionally publishes each one, JSON-encoded as a logging.Entry, to
|
||||
// SubjectForSystem(taskID): the return channel documented in subjects.go for
|
||||
// "log dumps, health... observability" that previously had no publisher.
|
||||
//
|
||||
// The wire payload is a marshaled logging.Entry -- {"time","level","msg",
|
||||
// "fields":{...}} -- meant to be round-tripped with json.Unmarshal straight
|
||||
// back into a logging.Entry. This is deliberately NOT the same shape
|
||||
// logging.decode() parses: decode() reads raw slog JSON *log lines* off
|
||||
// disk, where every non-{time,level,msg} key sits at the top level and
|
||||
// decode() moves it into Fields itself. Handing decode() this payload
|
||||
// instead of json.Unmarshal would nest everything one level too deep, under
|
||||
// a literal "fields" key, and silently lose every real field name. A future
|
||||
// consumer of this subject must unmarshal directly
|
||||
// into logging.Entry, not call decode() on these bytes.
|
||||
//
|
||||
// Publishing is fire-and-forget. A core NATS Publish call is already
|
||||
// non-blocking -- it queues to the connection's outbound buffer and returns,
|
||||
// and the client itself drops writes rather than blocking once its
|
||||
// reconnect buffer is full -- so this handler does not duplicate that
|
||||
// behaviour with a second, home-grown bounded queue. A publish or marshal
|
||||
// failure is reported once via the wrapped handler and then swallowed: log
|
||||
// shipping must never block or fail the run it is reporting on, and a dead
|
||||
// NATS connection is already visible through every stage subsequently
|
||||
// failing to report its own result.
|
||||
// SystemLogHandler writes slog records to a wrapped handler and publishes
|
||||
// each as a JSON logging.Entry to SubjectForSystem(taskID). Publish failures
|
||||
// are reported once and never block.
|
||||
type SystemLogHandler struct {
|
||||
next slog.Handler
|
||||
pub LogPublisher
|
||||
@@ -86,12 +59,7 @@ func (h *SystemLogHandler) Handle(ctx context.Context, record slog.Record) error
|
||||
return h.next.Handle(ctx, record)
|
||||
}
|
||||
|
||||
// warnAtMostOnce reports the first system-log delivery failure (marshal or
|
||||
// publish, either way this record's own history is now missing on the
|
||||
// daemon side) via the wrapped handler, then goes quiet -- a dead
|
||||
// connection would otherwise turn every subsequent line into a second
|
||||
// failure notice on stderr, drowning out the output an operator is trying
|
||||
// to read.
|
||||
// warnAtMostOnce reports the first publish failure only.
|
||||
func (h *SystemLogHandler) warnAtMostOnce(ctx context.Context, at time.Time, cause error) {
|
||||
h.warnOnce.Do(func() {
|
||||
warning := slog.NewRecord(at, slog.LevelWarn,
|
||||
|
||||
@@ -7,27 +7,13 @@ import (
|
||||
"github.com/samcharles93/archie-core/internal/events"
|
||||
)
|
||||
|
||||
// EventPublisher is the minimal capability needed to ship a task's
|
||||
// observability events to the daemon over NATS: fire a message at a subject
|
||||
// without waiting for a reply. Declared here rather than taking *nats.go's
|
||||
// Conn so ForwardTaskEvents can be tested with a fake. *nats.Conn already
|
||||
// satisfies this with no adapter needed.
|
||||
// EventPublisher publishes a message to a subject without waiting.
|
||||
type EventPublisher interface {
|
||||
Publish(subject string, data []byte) error
|
||||
}
|
||||
|
||||
// ForwardTaskEvents relays every event published on sub to pub, JSON-encoded,
|
||||
// on SubjectForEvents(taskID), until sub is closed.
|
||||
//
|
||||
// A workflow.TaskContext built inside an archie-agent worker publishes to an
|
||||
// in-process *events.Bus the daemon cannot see -- the worker and the daemon
|
||||
// are separate processes connected only by NATS. This is the bridge that
|
||||
// makes those Emit calls (stage progress, outcome, parking) reach the
|
||||
// daemon's events table and dashboard timeline.
|
||||
//
|
||||
// A marshal or publish failure is logged and the loop continues: one missing
|
||||
// event must never abort the ones after it, and event shipping must never
|
||||
// block or fail the workflow run it is reporting on.
|
||||
// ForwardTaskEvents publishes every event from sub to SubjectForEvents(taskID)
|
||||
// until sub closes. Failures are logged.
|
||||
func ForwardTaskEvents(sub *events.Sub, pub EventPublisher, taskID int64, log *slog.Logger) {
|
||||
subject := SubjectForEvents(taskID)
|
||||
for e := range sub.C {
|
||||
|
||||
@@ -13,23 +13,14 @@ import (
|
||||
"github.com/samcharles93/archie-core/internal/tools"
|
||||
)
|
||||
|
||||
// ToolLimits are the configured result limits for one chat turn or agent
|
||||
// stage. It holds only settings, never accumulated state, so it is safe to
|
||||
// store on a long-lived runner and share across tasks.
|
||||
//
|
||||
// A negative limit means no limit; see config.ToolPolicy for why zero cannot
|
||||
// carry that meaning.
|
||||
// ToolLimits are the tool result limits for one turn or stage. A negative
|
||||
// limit means none.
|
||||
type ToolLimits struct {
|
||||
MaxResultChars int
|
||||
SpillDir string
|
||||
}
|
||||
|
||||
// EnsureSpillDir creates the spill directory if one is configured.
|
||||
//
|
||||
// Call it once at startup. Without it the directory never exists, and a
|
||||
// failed spill write falls back to inline truncation -- spilling looks
|
||||
// configured and does nothing. An empty SpillDir is not an error: it
|
||||
// selects inline truncation deliberately.
|
||||
// EnsureSpillDir creates the spill directory if one is set.
|
||||
func (l ToolLimits) EnsureSpillDir() error {
|
||||
if l.SpillDir == "" {
|
||||
return nil
|
||||
@@ -137,21 +128,9 @@ func (o ToolSetOptions) excludes(entry tools.ToolEntry) bool {
|
||||
return slices.Contains(o.ExcludeToolsets, entry.Toolset)
|
||||
}
|
||||
|
||||
// BuildToolSet converts every currently-available entry in reg into an
|
||||
// ai-sdk core.ToolSet, ready to pass as core.GenerateOptions.Tools for a
|
||||
// multi-step chat turn. A nil registry (memory/tools disabled) returns
|
||||
// an empty set. Invalid availability callbacks and dynamic schemas return
|
||||
// errors instead of panicking or silently hiding an advertised tool.
|
||||
//
|
||||
// core.Tool.Execute exchanges JSON-encoded strings with the model;
|
||||
// tools.Handler exchanges a decoded map. The returned Execute functions
|
||||
// do the JSON <-> map translation and surface decode failures as errors
|
||||
// rather than silently dropping malformed model input.
|
||||
//
|
||||
// This is the only path from a registered tools.ToolEntry to a model, so it is
|
||||
// also where result limits are enforced. The model runtime owns the tool loop
|
||||
// and decides what to invoke, so archie cannot gate a batch -- but it builds
|
||||
// every Execute closure here, which makes per-call accounting reachable.
|
||||
// BuildToolSet converts reg's available entries into an ai-sdk ToolSet,
|
||||
// translating JSON input and enforcing result limits. A nil registry returns
|
||||
// an empty set.
|
||||
func BuildToolSet(reg *tools.Registry, opts ToolSetOptions) (aicore.ToolSet, error) {
|
||||
if reg == nil {
|
||||
return aicore.ToolSet{}, nil
|
||||
@@ -159,13 +138,7 @@ func BuildToolSet(reg *tools.Registry, opts ToolSetOptions) (aicore.ToolSet, err
|
||||
return BuildToolSetFrom(reg.All(), opts)
|
||||
}
|
||||
|
||||
// BuildToolSetFrom converts a loose slice of entries under the same rules as
|
||||
// [BuildToolSet].
|
||||
//
|
||||
// It exists for tools that are bound per turn rather than registered globally
|
||||
// -- the task tools carry the calling gateway's identity, so there is one set
|
||||
// of them per gateway and they cannot live in the process-wide registry. Pass
|
||||
// the same ToolSetOptions to both calls so a single turn shares one budget.
|
||||
// BuildToolSetFrom is BuildToolSet over a slice of entries.
|
||||
func BuildToolSetFrom(entries []tools.ToolEntry, opts ToolSetOptions) (aicore.ToolSet, error) {
|
||||
set := aicore.ToolSet{}
|
||||
for _, entry := range entries {
|
||||
@@ -223,14 +196,8 @@ func safeResolvedSchema(entry tools.ToolEntry) (schema tools.JSONSchema, err err
|
||||
return entry.ResolvedSchema(), nil
|
||||
}
|
||||
|
||||
// toolExecute adapts a tools.ToolEntry's Handler to core.Tool's
|
||||
// Execute(ctx, jsonInput string) (jsonOutput string, err error) shape, and
|
||||
// applies the turn's result accounting.
|
||||
//
|
||||
// The cap is applied to the marshalled payload rather than to the handler's
|
||||
// return value, because the marshalled form is what actually reaches the
|
||||
// model: JSON escaping can change the length materially, so capping the Go
|
||||
// value would bound the wrong string.
|
||||
// toolExecute adapts a ToolEntry's handler to an ai-sdk Execute and caps the
|
||||
// marshalled result.
|
||||
func toolExecute(entry tools.ToolEntry, opts ToolSetOptions) func(context.Context, string) (string, error) {
|
||||
limit := opts.resultLimit(entry)
|
||||
return func(ctx context.Context, input string) (result string, err error) {
|
||||
@@ -275,11 +242,8 @@ func requireApproval(ctx context.Context, entry tools.ToolEntry, opts ToolSetOpt
|
||||
}
|
||||
decision, err := opts.Approval.RequestApproval(approveCtx, entry.Name, desc)
|
||||
if err != nil {
|
||||
// Distinguish a tool-level timeout (our own deadline) from a
|
||||
// turn-level cancellation (/stop). A turn cancellation must
|
||||
// propagate as a context error; a tool timeout must surface as
|
||||
// a plain error so the model can report it instead of the turn
|
||||
// aborting.
|
||||
// A tool timeout is a plain error; a turn cancellation stays a context
|
||||
// error.
|
||||
if (errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled)) && ctx.Err() == nil {
|
||||
return fmt.Errorf("tool %s: approval timed out after %v", entry.Name, tools.ToolApprovalTimeout)
|
||||
}
|
||||
|
||||
@@ -7,14 +7,8 @@ import (
|
||||
"time"
|
||||
)
|
||||
|
||||
// EventCursorLayout is the fixed-width UTC layout every persisted event's at
|
||||
// column and every EventsSince cursor is built with. Fixed width is the whole
|
||||
// point: time.RFC3339Nano trims trailing zeros, so a whole-second row
|
||||
// ("...05Z") and a full-precision row ("...05.123456789Z") would compare out
|
||||
// of chronological order as strings. With nine fractional digits always
|
||||
// present, lexicographic order is chronological order. It mirrors edastore's
|
||||
// capturedAtLayout, which exists for the same reason; the two stores now share
|
||||
// this rule.
|
||||
// EventCursorLayout is the fixed-width UTC layout for event times and cursors,
|
||||
// so string order is time order.
|
||||
const EventCursorLayout = "2006-01-02T15:04:05.000000000Z"
|
||||
|
||||
// cursorSeparator joins the sort key and the row id inside a cursor. The sort
|
||||
|
||||
@@ -1,16 +1,5 @@
|
||||
// Package storecontract is the ratified State Store contract as its
|
||||
// consumers reference it: the producer-owned daemon/webui/intake store
|
||||
// surfaces. It carries no
|
||||
// persistence -- internal/infrastructure/postgres and *staterpc.Client (the
|
||||
// remote adapter) both satisfy these interfaces --
|
||||
// so a process that only holds the contracts, such as the archie-ui
|
||||
// dashboard process, can reference them without linking the SQL
|
||||
// implementation.
|
||||
//
|
||||
// It is hand-written and lives in the domain layer (which owns required
|
||||
// contracts), NOT under internal/contracts: that tree is the buf generate
|
||||
// output and is wiped and regenerated by tools/proto.sh, which would
|
||||
// delete a hand-written file there.
|
||||
// Package storecontract defines the State Store interfaces its consumers use,
|
||||
// without an implementation.
|
||||
package storecontract
|
||||
|
||||
import (
|
||||
@@ -57,56 +46,31 @@ type TaskLifecycle interface {
|
||||
RecoverStale(ctx context.Context) (int64, error)
|
||||
}
|
||||
|
||||
// TaskParker is the classified park write, kept off TaskLifecycle so that
|
||||
// interface stays under the repo's 8-method cap. It mirrors Transition with
|
||||
// a park class attached (taskstate.ParkClass); the class is normalized
|
||||
// store-side, so an empty or unknown value becomes needs_human rather than
|
||||
// an error -- a park that predates classification must not fail because its
|
||||
// caller did not know the vocabulary.
|
||||
// TaskParker parks a task with a park class. Unknown classes become
|
||||
// needs_human.
|
||||
type TaskParker interface {
|
||||
ParkTask(ctx context.Context, taskID int64, from, detail, class string) error
|
||||
}
|
||||
|
||||
// StepRecorder records the StepExecutions of one running WorkflowExecution.
|
||||
// It is deliberately separate
|
||||
// from TaskLifecycle, which is exactly at the interfacebloat cap: the same
|
||||
// two methods also sit on the workflow engine's mid-run facade (task.Store),
|
||||
// which is what a container's run credential calls.
|
||||
// StepRecorder records a running execution's steps.
|
||||
type StepRecorder interface {
|
||||
StartStep(ctx context.Context, s task.StepStart) (int64, events.Event, error)
|
||||
FinishStep(ctx context.Context, s task.StepFinish) (events.Event, error)
|
||||
}
|
||||
|
||||
// ExecutionCanceller is the one cancel path:
|
||||
// one
|
||||
// transaction moves every non-terminal StepExecution of the execution's
|
||||
// current attempt to cancelled and the execution itself to the status the
|
||||
// operator action names (parked or closed_wont_do, as the transition table
|
||||
// routes). The daemon then cancels the in-memory context that was delivering
|
||||
// the run: the store is the record of cancellation, the context cancel is
|
||||
// only the delivery mechanism, so a lost cancel still leaves the store
|
||||
// correct and the worker's next step write fails ErrStaleTransition. It is a
|
||||
// dashboard, API and dispatch action, so a task-scoped grant never reaches
|
||||
// it; the Authorizer decides.
|
||||
// ExecutionCanceller cancels an execution and its current attempt's open
|
||||
// steps in one transaction.
|
||||
type ExecutionCanceller interface {
|
||||
CancelExecution(ctx context.Context, taskID int64, reason, to string) ([]int64, error)
|
||||
}
|
||||
|
||||
// StepReader lists one execution's recorded steps -- the dashboard run
|
||||
// detail's read. Separate from
|
||||
// StepRecorder: this is a dashboard/API/dispatch action (Authorizer: read on
|
||||
// the run), never task-scoped-grant callable the way StartStep/FinishStep
|
||||
// are.
|
||||
// StepReader lists one execution's recorded steps.
|
||||
type StepReader interface {
|
||||
ListSteps(ctx context.Context, executionID int64, attempt int) ([]task.StepExecution, error)
|
||||
}
|
||||
|
||||
// HarnessSecretStore persists one org's OAuth token set per credential binding
|
||||
// service. The setup terminal writes the first capture (an `update` action on
|
||||
// the secret, Authorizer-gated); the egress proxy's token-endpoint interception
|
||||
// overwrites it on every refresh with no Authorizer check of its own -- it acts
|
||||
// as the run, not as an operator. Encrypted at rest under its own domain
|
||||
// separator.
|
||||
// HarnessSecretStore stores one org's OAuth token set per credential binding
|
||||
// service, encrypted at rest.
|
||||
type HarnessSecretStore interface {
|
||||
GetHarnessSecret(ctx context.Context, org, service string) (harnesssecret.Secret, error)
|
||||
PutHarnessSecret(ctx context.Context, s harnesssecret.Secret) error
|
||||
@@ -127,17 +91,9 @@ type TaskRetryer interface {
|
||||
RetryTask(ctx context.Context, taskID int64, fromStatus, workflow, retryMode string) error
|
||||
}
|
||||
|
||||
// ReviewGateResponder is the operator's answer to the review gate:
|
||||
// one guarded write
|
||||
// beside RetryTask/BeginRemediation that fills in the review gate document
|
||||
// the caller computed (the outcome, the selection or the instructions), and
|
||||
// -- for a re-review only -- increments rereview_rounds and requeues, under
|
||||
// one transition-table guard and one from-status check. A re-review that has
|
||||
// spent its rounds is refused with ErrRereviewCapReached and writes nothing,
|
||||
// so the cap cannot be raced past; an approve requeues with no counter.
|
||||
//
|
||||
// The caller computes the gate document from the task row it read; the write
|
||||
// is the only place rereview_rounds ever increments.
|
||||
// ReviewGateResponder records the operator's review-gate answer. A re-review
|
||||
// increments rereview_rounds and requeues; one past the cap returns
|
||||
// ErrRereviewCapReached and writes nothing.
|
||||
type ReviewGateResponder interface {
|
||||
RespondReviewGate(ctx context.Context, taskID int64, fromStatus, gate string, rereview bool, maxRounds int) error
|
||||
}
|
||||
@@ -178,34 +134,20 @@ type TaskEvents interface {
|
||||
Close() error
|
||||
}
|
||||
|
||||
// CaptureStore persists unbound inbound webhook captures -- events with no
|
||||
// workflow binding and no task association. Deliberately separate from
|
||||
// TaskStore: a consumer that only needs capture (the intake HTTP handler)
|
||||
// should not acquire the full task-lifecycle surface, mirroring why
|
||||
// TaskArchiver is split out above.
|
||||
// CaptureStore persists inbound webhook captures.
|
||||
type CaptureStore interface {
|
||||
InsertCapture(ctx context.Context, c CapturedEvent, retention time.Duration, maxEvents int) (string, error)
|
||||
ListCaptures(ctx context.Context, limit int) ([]CapturedEvent, error)
|
||||
}
|
||||
|
||||
// ConfigSnapshotStore holds the running configuration as the dashboard renders
|
||||
// it: the owner of configuration publishes, the process that displays it reads.
|
||||
// Separate from every other store surface because it is the only one whose
|
||||
// writer is the daemon and whose reader is the UI, and because a task-scoped
|
||||
// credential must never reach the writer.
|
||||
// ConfigSnapshotStore holds the published configuration view.
|
||||
type ConfigSnapshotStore interface {
|
||||
PutConfigSnapshot(ctx context.Context, snapshot ConfigSnapshot) error
|
||||
ConfigSnapshot(ctx context.Context) (ConfigSnapshot, bool, error)
|
||||
}
|
||||
|
||||
// ChannelStatusStore holds channel runtime state as the process HOSTING the
|
||||
// channels observes it. Same split as ConfigSnapshotStore and for the same
|
||||
// reason: the writer is the Messaging Service, the reader is the UI process, and
|
||||
// a task-scoped credential must reach neither.
|
||||
//
|
||||
// It is runtime state rather than a settings document -- a channel that is
|
||||
// failed is not a document anybody edits -- which is why it is not a
|
||||
// ControlPlaneService resource kind.
|
||||
// ChannelStatusStore holds channel runtime state published by the process
|
||||
// hosting the channels.
|
||||
type ChannelStatusStore interface {
|
||||
// PutChannelStatus records the reporting process's whole set: a channel it no
|
||||
// longer reports is removed rather than left behind, because a stale "running"
|
||||
@@ -253,11 +195,8 @@ type EventTypeStore interface {
|
||||
ListEventTypes(ctx context.Context) ([]eventtype.EventType, error)
|
||||
}
|
||||
|
||||
// BindingStore persists playbook bindings: CRUD and the draft ->
|
||||
// pending_approval -> armed state machine. Split off from TaskStore and
|
||||
// MappingStore so the webui binding editor does not acquire the full task or
|
||||
// mapping surfaces. Dispatch-time helpers live in BindingDispatcher; the daemon
|
||||
// depends on both. See
|
||||
// BindingStore persists bindings and their draft -> pending_approval ->
|
||||
// armed states.
|
||||
type BindingStore interface {
|
||||
InsertBinding(ctx context.Context, b binding.Binding) (string, error)
|
||||
GetBinding(ctx context.Context, id string) (*binding.Binding, error)
|
||||
@@ -267,11 +206,8 @@ type BindingStore interface {
|
||||
ApproveBinding(ctx context.Context, id string) error
|
||||
}
|
||||
|
||||
// SourceStore persists capture sources and their signing setting.
|
||||
// The path is the key and never
|
||||
// changes. Secrets cross this surface in plaintext; the store encrypts them
|
||||
// at rest. Signing transitions are decided by the source domain and written
|
||||
// with an expected-from guard, so two operators cannot race an approval.
|
||||
// SourceStore persists capture sources keyed by path. Secrets are encrypted
|
||||
// at rest; signing transitions use an expected-from guard.
|
||||
type SourceStore interface {
|
||||
InsertSource(ctx context.Context, s source.Source) error
|
||||
// GetSource returns (nil, nil) for an unknown path.
|
||||
@@ -281,12 +217,8 @@ type SourceStore interface {
|
||||
SetSourceSecret(ctx context.Context, path, secret string) error
|
||||
}
|
||||
|
||||
// BindingDispatcher is the dispatch-loop surface over the bindings store:
|
||||
// look up armed bindings for HMAC verification, list captures that still
|
||||
// need dispatching, and record the at-most-once ledger row. The
|
||||
// dispatcher's task-creation call (EnqueueBindingTask) lives on a separate
|
||||
// BindingTaskCreator interface so the dispatcher does not depend on the
|
||||
// full TaskStore just to spawn one task.
|
||||
// BindingDispatcher looks up armed bindings, lists undispatched captures and
|
||||
// records dispatches.
|
||||
type BindingDispatcher interface {
|
||||
ArmedBindingsForSource(ctx context.Context, source string) ([]binding.Binding, error)
|
||||
RecordDispatch(
|
||||
@@ -310,43 +242,19 @@ type BindingTaskCreator interface {
|
||||
EnqueueBindingTask(ctx context.Context, owner, repo, title, body, wf, identity, bindingID string, bindingVersion int, inputs map[string]any) (*task.Task, error)
|
||||
}
|
||||
|
||||
// WorkflowCaller is the consumer surface a workflow.call step crosses to
|
||||
// start its callee and read it back while waiting.
|
||||
// It is the workflow engine's own task.Caller contract, satisfied by the
|
||||
// PostgreSQL store and *staterpc.Client alike -- the same shape as
|
||||
// workflow.Store. The caller task ID is explicit so both the wire grant and
|
||||
// the store's own row check answer the same question: is this call this
|
||||
// task's call?
|
||||
// WorkflowCaller starts a workflow.call callee and reads it back.
|
||||
type WorkflowCaller = task.Caller
|
||||
|
||||
// PlaybookDispatcher is the idempotency-ledger surface for side-effecting
|
||||
// playbook actions.
|
||||
// RecordPlaybookDispatch writes the (playbook, version, event, action) row
|
||||
// BEFORE the action's side effect fires -- the deliberate reverse of
|
||||
// BindingDispatcher.RecordDispatch -- so a duplicate returns
|
||||
// ErrAlreadyDispatched and the caller skips the invoke rather than repeating
|
||||
// a non-revocable side effect. DeletePlaybookDispatches deletes one
|
||||
// playbook's ledger rows on explicit request only: a playbook file missing at
|
||||
// boot may be an unmounted directory, and reclaiming on that would let
|
||||
// redelivered events fire again. There is deliberately no *sql.Tx: any
|
||||
// transaction stays server-side inside the store.
|
||||
// PlaybookDispatcher records a playbook action dispatch before its side
|
||||
// effect runs, returning ErrAlreadyDispatched for a duplicate.
|
||||
// DeletePlaybookDispatches deletes one playbook's records.
|
||||
type PlaybookDispatcher interface {
|
||||
RecordPlaybookDispatch(ctx context.Context, playbookID, playbookVersion, eventID, actionID string) error
|
||||
DeletePlaybookDispatches(ctx context.Context, playbookID string) error
|
||||
}
|
||||
|
||||
// TaskLogStore reads one task attempt's persisted log. Deliberately separate
|
||||
// from TaskQueries: the log is not a row, it is a file the logging package
|
||||
// owns the format of, and a process that can read the task board should not
|
||||
// have to acquire a log reader to do it. The dashboard's UI process is the
|
||||
// consumer this exists for -- it holds no daemon-local file handle, so the
|
||||
// read crosses the State Store contract.
|
||||
//
|
||||
// Found=false with a nil error is the not-found convention every read here
|
||||
// uses, and it is load-bearing: "this attempt has no log" is not "this
|
||||
// process cannot read logs". The second one is an error
|
||||
// (logging.ErrTaskLogsUnavailable), because a caller that conflates them
|
||||
// reports a configuration change where none is needed.
|
||||
// TaskLogStore reads one task attempt's log. Found=false means no log;
|
||||
// ErrTaskLogsUnavailable means this process cannot read logs.
|
||||
type TaskLogStore interface {
|
||||
// TaskLog returns a page of one attempt's decoded log. attempt 0 selects
|
||||
// the task's current attempt.
|
||||
@@ -382,14 +290,8 @@ type CapturedEvent struct {
|
||||
// a valid signature, or a source approved to take unsigned events.
|
||||
func (c CapturedEvent) Dispatchable() bool { return c.Authenticated || c.Unsigned }
|
||||
|
||||
// ConfigSnapshot is the running configuration as the dashboard renders it,
|
||||
// published by whoever owns configuration for whoever displays it.
|
||||
//
|
||||
// Document is opaque here on purpose: its shape belongs to the producer and
|
||||
// the page that reads it, not to storage, and Schema names that shape so a
|
||||
// reader can refuse a document it does not understand. It is secret-free by
|
||||
// construction at the producer (the projection carries an API key's
|
||||
// environment variable name and whether it resolved, never a value).
|
||||
// ConfigSnapshot is the published, secret-free configuration view. Schema
|
||||
// names Document's shape.
|
||||
type ConfigSnapshot struct {
|
||||
Schema string
|
||||
Document []byte
|
||||
@@ -410,15 +312,9 @@ type ChannelStatus struct {
|
||||
ObservedAt time.Time
|
||||
}
|
||||
|
||||
// ApplyStatus is one process's report about one control-plane resource kind.
|
||||
//
|
||||
// AppliedVersion is the version that process is running. Error is set when the
|
||||
// process could not apply what the store returned, and leaves AppliedVersion
|
||||
// at the last version it did apply, so a rejected edit never erases the fact
|
||||
// that an older one is live. ReportedAt is re-stamped on an interval: a record
|
||||
// older than the staleness window belongs to a process that has stopped
|
||||
// running, which is the only way this surface can tell a live process from a
|
||||
// dead one.
|
||||
// ApplyStatus is one process's report on one resource kind. On error,
|
||||
// AppliedVersion stays at the last applied version. ReportedAt is
|
||||
// re-stamped periodically.
|
||||
type ApplyStatus struct {
|
||||
Process string `json:"process"`
|
||||
Kind string `json:"kind"`
|
||||
@@ -463,12 +359,8 @@ var (
|
||||
// ErrStaleTransition is returned when a task transition's expected
|
||||
// from status does not match the task's current status.
|
||||
ErrStaleTransition = errors.New("store: stale transition: task status does not match expected from status")
|
||||
// ErrIllegalTransition is returned when a task's current status and the
|
||||
// requested status form a pair the shared taskstate transition table
|
||||
// does not route: the move
|
||||
// would have executed against a truthful from, but the table forbids
|
||||
// it. Distinct from ErrStaleTransition, which covers a from that does
|
||||
// not match the row's actual status.
|
||||
// ErrIllegalTransition is returned when the transition table does not allow
|
||||
// the status pair.
|
||||
ErrIllegalTransition = errors.New("store: illegal transition: status pair is not in the transition table")
|
||||
// ErrInvalidStep is returned when a step-execution request names a kind the
|
||||
// store does not record or a step whose identifying fields do not resolve.
|
||||
@@ -482,12 +374,8 @@ var (
|
||||
// ErrBindingTransition is returned when a binding state transition is
|
||||
// rejected by the draft -> pending_approval -> armed machine.
|
||||
ErrBindingTransition = errors.New("store: binding state transition rejected")
|
||||
// ErrAlreadyDispatched is returned when a dedup ledger already holds the
|
||||
// dispatch key: binding_dispatches for the (binding_id, capture_id) pair,
|
||||
// or playbook_dispatches for the (playbook_id, playbook_version,
|
||||
// event_id, action_id) tuple. Both ledgers are at-most-once guarantees;
|
||||
// the sentinel is shared so a caller treats "already recorded" the same
|
||||
// way across the two surfaces.
|
||||
// ErrAlreadyDispatched is returned when a dispatch ledger already holds the
|
||||
// key.
|
||||
ErrAlreadyDispatched = errors.New("store: binding already dispatched for capture")
|
||||
// ErrCallNotYours is returned when a workflow.call status read names a
|
||||
// task that is not a callee of the calling task, or the caller itself
|
||||
|
||||
@@ -11,24 +11,14 @@ import (
|
||||
// Metadata, never a URL.
|
||||
const tokenMetadataKey = "state-store-token"
|
||||
|
||||
// UnaryClientTokenInterceptor attaches token to every outgoing call's
|
||||
// metadata under tokenMetadataKey. One token covers a task's container
|
||||
// lifetime so it does not need to be
|
||||
// refreshed mid-connection. Used by the agent's long-lived client
|
||||
// connection to the State Store's bridge-address listener.
|
||||
// UnaryClientTokenInterceptor attaches token to every outgoing call.
|
||||
func UnaryClientTokenInterceptor(token string) grpc.UnaryClientInterceptor {
|
||||
return func(ctx context.Context, method string, req, reply any, cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {
|
||||
return invoker(metadata.AppendToOutgoingContext(ctx, tokenMetadataKey, token), method, req, reply, cc, opts...)
|
||||
}
|
||||
}
|
||||
|
||||
// StreamClientTokenInterceptor attaches token to the outgoing stream's
|
||||
// context, covering the server-streaming read RPCs (StreamCaptures,
|
||||
// StreamUndispatchedCaptures) the unary interceptor cannot see. Without it
|
||||
// those calls reach a token-protected listener with no credential and the
|
||||
// server's stream interceptor refuses them, leaving the capture batch reads
|
||||
// -- the ones moved onto streams precisely so a large batch crosses -- with
|
||||
// no working path.
|
||||
// StreamClientTokenInterceptor attaches token to every outgoing stream.
|
||||
func StreamClientTokenInterceptor(token string) grpc.StreamClientInterceptor {
|
||||
return func(ctx context.Context, desc *grpc.StreamDesc, cc *grpc.ClientConn, method string, streamer grpc.Streamer, opts ...grpc.CallOption) (grpc.ClientStream, error) {
|
||||
return streamer(metadata.AppendToOutgoingContext(ctx, tokenMetadataKey, token), desc, cc, method, opts...)
|
||||
|
||||
@@ -114,11 +114,8 @@ func (c *Client) Transition(ctx context.Context, taskID int64, from, to, detail
|
||||
return unmapError(err)
|
||||
}
|
||||
|
||||
// StartStep and FinishStep record the run's step executions
|
||||
// under the run credential, which
|
||||
// the State Store's grant interceptor scopes to the execution the requests
|
||||
// name. Each returns the transition's persisted event for the caller's
|
||||
// post-commit publish.
|
||||
// StartStep and FinishStep record step executions and return the persisted
|
||||
// event.
|
||||
func (c *Client) StartStep(ctx context.Context, s task.StepStart) (int64, events.Event, error) {
|
||||
r, err := c.client.StartStep(ctx, &pb.StartStepRequest{
|
||||
ExecutionId: s.ExecutionID, Attempt: int64(s.Attempt),
|
||||
|
||||
@@ -11,16 +11,9 @@ import (
|
||||
"google.golang.org/grpc/keepalive"
|
||||
)
|
||||
|
||||
// Dial returns a State Store contract client for target, applying the
|
||||
// transport security boundary: a
|
||||
// loopback target dials insecure with no credential, while a non-loopback
|
||||
// target requires a bearer token and fails closed without one. The returned
|
||||
// cleanup closes the connection; Client.Close is a no-op because the store
|
||||
// service owns its own DB lifecycle.
|
||||
//
|
||||
// The rule lives here rather than in a composition root so the server side
|
||||
// (which decides whether to install the token interceptors) and every client
|
||||
// that dials it share one implementation.
|
||||
// Dial returns a State Store client for target. A loopback target dials
|
||||
// insecure; any other target requires a token. The cleanup closes the
|
||||
// connection.
|
||||
func Dial(target, token string, options ...grpc.DialOption) (*Client, func(), error) {
|
||||
target = strings.TrimSpace(target)
|
||||
if target == "" {
|
||||
@@ -38,24 +31,7 @@ func Dial(target, token string, options ...grpc.DialOption) (*Client, func(), er
|
||||
}
|
||||
opts := []grpc.DialOption{
|
||||
grpc.WithTransportCredentials(insecure.NewCredentials()),
|
||||
// Client keepalive. grpc-go's default client keepalive time is
|
||||
// infinity (internal/transport.defaultClientKeepaliveTime), so a
|
||||
// connection that half-opens under an idle client -- peer gone, socket
|
||||
// still ESTABLISHED -- produces no error here. That is load-bearing for
|
||||
// this dial because the control-plane Watch stream is silent by design
|
||||
// while the watched resource's version is unchanged
|
||||
// (internal/app/controlplane's Watch): with neither peer writing,
|
||||
// neither notices, and the caller's watch stays frozen for the life of
|
||||
// the process with no error and no log.
|
||||
//
|
||||
// Time 10s is the soonest a dead peer can be detected: gRPC clamps a
|
||||
// client ping interval up to internal.KeepaliveMinPingTime (10s), and
|
||||
// 10s of connection-level silence costs one HTTP/2 PING, which is far
|
||||
// below the traffic this link already carries (the store service polls
|
||||
// its store every 250ms per watch). Timeout 5s bounds detection at
|
||||
// ~15s: a PING the peer does not ACK within 5s tears the transport
|
||||
// down, turning a half-open connection into a stream error the caller
|
||||
// can act on.
|
||||
// Keepalive detects a dead peer on an otherwise silent watch stream.
|
||||
grpc.WithKeepaliveParams(ClientKeepaliveParams()),
|
||||
}
|
||||
if token != "" {
|
||||
@@ -75,18 +51,8 @@ func Dial(target, token string, options ...grpc.DialOption) (*Client, func(), er
|
||||
return NewClient(conn), func() { _ = conn.Close() }, nil
|
||||
}
|
||||
|
||||
// ClientKeepaliveParams are the client keepalive settings Dial installs; see
|
||||
// Dial's option comment for why each value is what it is. PermitWithoutStream
|
||||
// is deliberately left false (the library default): the pings this dial needs
|
||||
// are covered by an active stream, and pinging a connection with no streams is
|
||||
// what a peer's keepalive enforcement policy records as a ping strike --
|
||||
// against the State Store's default policy a streamless ping draws GOAWAY
|
||||
// too_many_pings and would churn connections that are healthy today.
|
||||
//
|
||||
// It is the dialer's half of the keepalive agreement with
|
||||
// ServerKeepalivePolicy, so it is exported: the side that installs a server
|
||||
// option reads the interval this dialer actually pings at from here rather
|
||||
// than restating it.
|
||||
// ClientKeepaliveParams are Dial's keepalive settings: ping after 10s idle,
|
||||
// 5s timeout, no pings without streams.
|
||||
func ClientKeepaliveParams() keepalive.ClientParameters {
|
||||
return keepalive.ClientParameters{
|
||||
Time: 10 * time.Second,
|
||||
@@ -100,50 +66,13 @@ func ClientKeepaliveParams() keepalive.ClientParameters {
|
||||
// ServerKeepaliveOption carries the arithmetic.
|
||||
const serverKeepaliveMinTime = 5 * time.Second
|
||||
|
||||
// ServerKeepaliveOption returns the server half of the keepalive agreement
|
||||
// Dial's clients enter, for the composition that serves the State Store
|
||||
// contract to install on its grpc.Server (internal/app/archied's
|
||||
// stateStoreServerOpts installs it on every listener).
|
||||
//
|
||||
// The two sides have to agree on one number. A ping arriving less than
|
||||
// EnforcementPolicy.MinTime after the previous ping is a strike, and the server
|
||||
// answers the third strike with GOAWAY too_many_pings (maxPingStrikes is 2; a
|
||||
// write on that transport is what resets the counter). grpc's default policy
|
||||
// MinTime is 5 minutes while the client above pings every 10 seconds, so a
|
||||
// connection that carries no write for ~40s -- which is what a watch is while
|
||||
// the watched resource's version is unchanged -- is torn down where before the
|
||||
// client keepalive existed it stayed up. A process that writes on the same
|
||||
// transport every 30s (the apply-status re-stamp, applystatus.RestampInterval)
|
||||
// resets the counter often enough to hide this; an idle connection is what it
|
||||
// kills, and a keepalive that disconnects is worse than no keepalive.
|
||||
//
|
||||
// MinTime is 5s, half the client's ping interval. The client's interval is the
|
||||
// larger of its Time and grpc's KeepaliveMinPingTime clamp -- 10s, so no caller
|
||||
// can ask for faster pings -- and its keepalive loop arms its timer Time ahead
|
||||
// and re-arms it only later, on read activity, so consecutive pings are never
|
||||
// closer than ~10s apart. A 5s floor thus separates every ping from a strike by
|
||||
// a factor of two, worth more than Go's timer granularity and any scheduling
|
||||
// delay, which can only push pings further apart. A MinTime of 10s would sit
|
||||
// exactly on the boundary the clamp already enforces, where a ping a
|
||||
// microsecond early is a strike; 5 minutes is the defect itself.
|
||||
//
|
||||
// The floor is not a blanket exemption: a ping arriving less than 5s after the
|
||||
// previous one, and any ping on a connection with no stream, still strikes.
|
||||
// PermitWithoutStream stays false, matching the client, which never pings a
|
||||
// connection with no streams: every client this server has is a staterpc.Dial
|
||||
// -- the daemon's control-plane client, the archie-ui dashboard, archie-
|
||||
// messaging and the archie-agent container -- so permitting streamless pings
|
||||
// would only relax a setting none of them exercises.
|
||||
// ServerKeepaliveOption returns the server keepalive enforcement matching
|
||||
// Dial's clients: pings at least 5s apart are allowed while a stream is open.
|
||||
func ServerKeepaliveOption() grpc.ServerOption {
|
||||
return grpc.KeepaliveEnforcementPolicy(ServerKeepalivePolicy())
|
||||
}
|
||||
|
||||
// ServerKeepalivePolicy returns the policy ServerKeepaliveOption installs as a
|
||||
// value. A grpc.ServerOption is a closure over unexported grpc state with no
|
||||
// accessor, so the option cannot be read back once built; this value is
|
||||
// therefore the handle the agreement is held to -- a caller installing the
|
||||
// option can assert the policy it is built from, and ClientKeepaliveParams
|
||||
// gives the interval that policy must stay below.
|
||||
// ServerKeepalivePolicy returns the policy ServerKeepaliveOption installs.
|
||||
func ServerKeepalivePolicy() keepalive.EnforcementPolicy {
|
||||
return keepalive.EnforcementPolicy{
|
||||
MinTime: serverKeepaliveMinTime,
|
||||
@@ -151,11 +80,8 @@ func ServerKeepalivePolicy() keepalive.EnforcementPolicy {
|
||||
}
|
||||
}
|
||||
|
||||
// TargetIsLoopback reports whether addr's host is a loopback address. Both
|
||||
// literal loopback IPs (127.0.0.1, ::1) and the "localhost" hostname count;
|
||||
// everything else (including the wildcard 0.0.0.0 and DNS names) is treated
|
||||
// as network-reachable and therefore non-loopback. It applies to a listen
|
||||
// address and a dial target alike -- the same host decides both.
|
||||
// TargetIsLoopback reports whether addr's host is a loopback IP or
|
||||
// "localhost".
|
||||
func TargetIsLoopback(addr string) (bool, error) {
|
||||
host, _, err := net.SplitHostPort(addr)
|
||||
if err != nil {
|
||||
|
||||
@@ -43,12 +43,7 @@ var (
|
||||
errBindingTaskCreatorUnavailable = status.Error(codes.Unavailable, "binding task creator unavailable")
|
||||
errPlaybookDispatcherUnavailable = status.Error(codes.Unavailable, "playbook dispatcher unavailable")
|
||||
errWorkflowCallerUnavailable = status.Error(codes.Unavailable, "workflow caller unavailable")
|
||||
// errTaskLogsUnavailable is the "this process cannot read task logs at
|
||||
// all" answer, and it is deliberately distinct from a found=false read
|
||||
// result: only the first is a deployment matter. A dashboard that receives
|
||||
// this reports that the log cannot be read here; it must never turn it
|
||||
// into "task logging was not enabled for this run", which is what the
|
||||
// absent-handle path used to do.
|
||||
// errTaskLogsUnavailable reports that this process cannot read task logs.
|
||||
errTaskLogsUnavailable = status.Error(codes.Unavailable, msgTaskLogsUnavailable)
|
||||
)
|
||||
|
||||
@@ -129,12 +124,8 @@ type Deps struct {
|
||||
// Denials records and lists denial records. Optional: nil disables the
|
||||
// pair with codes.Unavailable.
|
||||
Denials access.DenialStore
|
||||
// TaskLogs reads one task attempt's persisted log out of the state
|
||||
// directory this process owns. Optional, and nil is the honest default for
|
||||
// a store service that shares no state directory with the daemon:
|
||||
// ReadTaskLog then answers codes.Unavailable, which the dashboard reports
|
||||
// as "this process cannot read logs" rather than as "this attempt has no
|
||||
// log". Conflating those two is the bug this contract exists to fix.
|
||||
// TaskLogs reads task attempt logs. Nil answers ReadTaskLog with
|
||||
// Unavailable.
|
||||
TaskLogs storecontract.TaskLogStore
|
||||
Log *slog.Logger
|
||||
}
|
||||
@@ -165,13 +156,7 @@ func (s *server) logErr(rpc string, err error) error {
|
||||
return mapError(err)
|
||||
}
|
||||
|
||||
// validationFailure answers a write the owning feature's own Validate refused.
|
||||
// The domain-managed kinds (identities, captures, mappings, bindings) are
|
||||
// advertised in the control-plane catalog but are not stored as generic
|
||||
// documents, so it is these RPC handlers -- not the catalog -- that must apply
|
||||
// the feature's rule. The rule itself stays in the domain package; this only
|
||||
// translates its error for the wire, and it is deliberately not codes.Internal
|
||||
// (an unjudged value is the caller's fault, not this process's).
|
||||
// validationFailure maps a domain validation error to InvalidArgument.
|
||||
func validationFailure(err error) error {
|
||||
return status.Error(codes.InvalidArgument, err.Error())
|
||||
}
|
||||
@@ -221,11 +206,7 @@ func (s *server) Transition(ctx context.Context, r *pb.TransitionRequest) (*pb.T
|
||||
return &pb.TransitionResponse{}, nil
|
||||
}
|
||||
|
||||
// StartStep and FinishStep are the step-execution writes.
|
||||
// Each is the store's own
|
||||
// transaction -- guarded row write plus the event row -- and the store's
|
||||
// response carries the persisted event back for the caller's post-commit
|
||||
// publish.
|
||||
// StartStep and FinishStep write a step transition and return its event.
|
||||
func (s *server) StartStep(ctx context.Context, r *pb.StartStepRequest) (*pb.StartStepResponse, error) {
|
||||
if s.deps.Steps == nil {
|
||||
return nil, status.Error(codes.Unavailable, "step recorder unavailable")
|
||||
|
||||
@@ -91,20 +91,14 @@ func (g *TaskGrants) taskFor(token string) int64 {
|
||||
}
|
||||
|
||||
// authorizesTaskScopedCall reports whether a task-scoped token may make this
|
||||
// call: only when the RPC is in taskScopedTargets and targets taskID. Every
|
||||
// other RPC, including grant registration, is refused, so a task grant only
|
||||
// narrows. workflow.call and step-execution writes carry the caller's own task
|
||||
// ID; the handler checks step membership, so this never reads the database.
|
||||
// call: only RPCs in taskScopedTargets that target taskID.
|
||||
func authorizesTaskScopedCall(fullMethod string, req any, taskID int64) bool {
|
||||
target := taskScopedTargets[fullMethod]
|
||||
return target != nil && target(req) == taskID
|
||||
}
|
||||
|
||||
// taskScopedTargets maps each RPC a task grant may ever authorize to the
|
||||
// function naming the task ID its request targets (0 for a request it cannot
|
||||
// read). Held as data so the sanctioned widenings stop growing a switch: a
|
||||
// new authorized RPC registers one row here, and the deny-by-default rule
|
||||
// above covers everything else.
|
||||
// taskScopedTargets maps each RPC a task grant may call to the task ID its
|
||||
// request targets.
|
||||
var taskScopedTargets = map[string]func(any) int64{
|
||||
pb.StateStoreService_Update_FullMethodName: func(req any) int64 {
|
||||
r, ok := req.(*pb.UpdateRequest)
|
||||
|
||||
@@ -41,15 +41,7 @@ func timeValue(t *timestamppb.Timestamp) time.Time {
|
||||
return t.AsTime()
|
||||
}
|
||||
|
||||
// mapValues maps a slice of proto values to domain values, always returning a
|
||||
// non-nil result for empty input.
|
||||
//
|
||||
// Protobuf decodes an empty `repeated` field to nil, and Go marshals a nil
|
||||
// slice to JSON null rather than []. Returning nil here made every decoded
|
||||
// collection field's JSON type depend on whether it happened to have contents,
|
||||
// and made the wire path disagree with the local path, which normalises its own
|
||||
// slices. []B{} for empty input keeps the shape stable at every call site
|
||||
// without making each one remember to guard.
|
||||
// mapValues maps a slice, returning an empty non-nil slice for empty input.
|
||||
func mapValues[A, B any](in []A, f func(A) B) []B {
|
||||
if len(in) == 0 {
|
||||
return []B{}
|
||||
@@ -417,27 +409,13 @@ const (
|
||||
// errors.Is on the client without changing behaviour visibly.
|
||||
msgRereviewCapReached = "store: re-review cap reached"
|
||||
msgInternal = "state store: internal error"
|
||||
// msgTaskLogsUnavailable is the public phrase for "this service has no
|
||||
// task-log reader". It is a wire contract like the sentinels above: the
|
||||
// client rehydrates logging.ErrTaskLogsUnavailable from (Unavailable, this
|
||||
// message), and a caller depends on that to tell "this process cannot read
|
||||
// logs" from "this attempt has no log".
|
||||
// msgTaskLogsUnavailable is part of the wire contract for
|
||||
// ErrTaskLogsUnavailable.
|
||||
msgTaskLogsUnavailable = "task log reader unavailable"
|
||||
)
|
||||
|
||||
// mapError converts a store sentinel error into a structured gRPC status
|
||||
// carrying a short, public, stable message -- never the raw wrapped chain
|
||||
// (which may contain SQL, provider detail, or secrets). Infra errors map to
|
||||
// codes.Internal with a sanitised message; the caller is expected to log the
|
||||
// full error server-side before calling mapError.
|
||||
//
|
||||
// A context cancellation/deadline raised by the store must retain its identity,
|
||||
// not be folded into codes.Internal: gRPC-Go surfaces
|
||||
// context.Canceled/DeadlineExceeded to the client only for those exact codes,
|
||||
// and the agent's workflow consumer depends on errors.Is(err,
|
||||
// context.DeadlineExceeded) to distinguish an interrupted stage from a failed
|
||||
// one. So a context error maps to its own gRPC code (and unmapError rehydrates
|
||||
// it back to the sentinel).
|
||||
// mapError converts a store sentinel to a gRPC status with a stable public
|
||||
// message; other errors become Internal. Context errors keep their codes.
|
||||
func mapError(err error) error {
|
||||
if err == nil {
|
||||
return nil
|
||||
@@ -456,25 +434,8 @@ func mapError(err error) error {
|
||||
return status.Error(codes.Internal, msgInternal)
|
||||
}
|
||||
|
||||
// unmapError rehydrates a gRPC status error back to the store sentinel it
|
||||
// came from, so a caller's errors.Is(err, storecontract.ErrX) keeps working across
|
||||
// the wire. A non-status error (e.g. a transport failure) is returned
|
||||
// unchanged.
|
||||
//
|
||||
// The deadline/cancel identity must survive too: the agent's
|
||||
// deadlineStore bounds each Store call with context.WithTimeout, and the
|
||||
// workflow consumer checks errors.Is(err, context.DeadlineExceeded) to
|
||||
// decide whether a stage was interrupted by shutdown rather than failed
|
||||
// (workflow.go). gRPC-Go surfaces an expired or cancelled context as a
|
||||
// *status.Error whose code is DeadlineExceeded or Canceled, so we rehydrate
|
||||
// those back to the standard context sentinels -- otherwise the consumer
|
||||
// would (wrongly) park a task that was merely interrupted.
|
||||
//
|
||||
// Unavailable carries one message this package owns: the absent task-log
|
||||
// reader. It is rehydrated for the same reason the error sentinels are --
|
||||
// the dashboard's whole bug was rendering "this process cannot read logs" as
|
||||
// "the attempt has no log", and only the typed error makes that distinction
|
||||
// available to a caller.
|
||||
// unmapError turns a gRPC status back into its store sentinel, context error
|
||||
// or ErrTaskLogsUnavailable. Non-status errors are returned unchanged.
|
||||
func unmapError(err error) error {
|
||||
if err == nil {
|
||||
return nil
|
||||
|
||||
@@ -36,21 +36,15 @@ func (c CommandCatalog) Check(ctx context.Context) (Snapshot, error) {
|
||||
return snapshot, nil
|
||||
}
|
||||
|
||||
// CommandInstaller runs the deployment's own install command. HealthURL is
|
||||
// the base URL its restart tooling must poll for /healthz -- only this
|
||||
// process knows which address it actually serves, so a script left to guess
|
||||
// one rolls back releases that came up healthy. Empty
|
||||
// leaves ARCHIE_HEALTH_URL as the environment already has it.
|
||||
// CommandInstaller runs the deployment's install command. HealthURL is
|
||||
// passed as ARCHIE_HEALTH_URL when set.
|
||||
type CommandInstaller struct {
|
||||
Command []string
|
||||
HealthURL string
|
||||
}
|
||||
|
||||
// Install runs the configured command and streams its stdout to progress
|
||||
// line by line as the command emits it -- the earlier CombinedOutput-based
|
||||
// version buffered everything until exit, so callers saw nothing until the
|
||||
// whole update either finished or failed. One stdout line may be a
|
||||
// structured Result instead of prose; see updateResultSentinel.
|
||||
// Install runs the command, streaming stdout lines to progress. One line may
|
||||
// be a structured Result.
|
||||
func (i CommandInstaller) Install(ctx context.Context, snapshot Snapshot, meta InstallMeta, progress func(string)) (Result, error) {
|
||||
if len(i.Command) == 0 {
|
||||
return Result{}, fmt.Errorf("update install command is empty")
|
||||
|
||||
@@ -7,13 +7,8 @@ import (
|
||||
"os"
|
||||
)
|
||||
|
||||
// Report is the phase-2 outcome of an update: whether the daemon came back
|
||||
// up healthy after restarting, written by whichever process determined that
|
||||
// (the deployment's restart/health-check tooling) and read, relayed to
|
||||
// Channel/ChatID/ThreadID, and cleared by whichever archied process boots
|
||||
// next -- which may be the newly installed version (success) or the
|
||||
// previous one, if a crash-loop forced a rollback before this code could
|
||||
// ever run on the new version.
|
||||
// Report is an update's post-restart outcome, written by the restart tooling
|
||||
// and relayed by the next archied boot.
|
||||
type Report struct {
|
||||
Channel string `json:"channel"`
|
||||
ChatID int64 `json:"chat_id"`
|
||||
|
||||
@@ -8,12 +8,7 @@ import (
|
||||
"github.com/samcharles93/archie-core/internal/events"
|
||||
)
|
||||
|
||||
// ReportEvent turns a phase-2 Report, plus its verification against
|
||||
// the versions actually running, into the activity-stream event the
|
||||
// dashboard renders. Unlike Telegram's formatPendingReport, this ships the
|
||||
// structured Verification rather than pre-rendered prose, so the frontend
|
||||
// controls presentation -- the two channels' operators read the same facts
|
||||
// through different UIs, not necessarily the same sentence.
|
||||
// ReportEvent turns a Report and its verification into a dashboard event.
|
||||
func ReportEvent(report Report, running map[string]string) events.Event {
|
||||
verification := report.Verify(running)
|
||||
drift := make([]map[string]any, 0, len(verification.Drift))
|
||||
@@ -40,13 +35,8 @@ func ReportEvent(report Report, running map[string]string) events.Event {
|
||||
}
|
||||
}
|
||||
|
||||
// summarizeReport is the one-line summary shown in the dashboard's
|
||||
// activity feed, which renders event.Detail generically for every event
|
||||
// kind (see ui/src/dashboard/dashboard.js activityRow). It condenses the
|
||||
// same facts internal/channels/telegram/update.go's formatPendingReport
|
||||
// spells out at length -- not a byte-identical wording, since the two
|
||||
// surfaces render differently, but the same four outcomes: confirmed,
|
||||
// drifted, unverified, or rolled back.
|
||||
// summarizeReport returns a one-line summary: confirmed, drifted, unverified
|
||||
// or rolled back.
|
||||
func summarizeReport(report Report, verification Verification) string {
|
||||
if report.RolledBack {
|
||||
return "Update failed its health check and was rolled back to the previous version."
|
||||
|
||||
@@ -1,11 +1,6 @@
|
||||
package releaseupdate
|
||||
|
||||
// InstallMeta identifies who to notify once an installed update finishes
|
||||
// restarting. The process that calls Install returns before the daemon
|
||||
// actually restarts (the reference installer queues the restart through a
|
||||
// detached unit so restarting archied.service doesn't kill the installer
|
||||
// mid-run), so this identity has to survive the restart on disk -- see
|
||||
// Report and WritePendingReport.
|
||||
// InstallMeta identifies who to notify after the update restarts.
|
||||
type InstallMeta struct {
|
||||
Channel string
|
||||
ChatID int64
|
||||
@@ -24,11 +19,8 @@ type ComponentResult struct {
|
||||
Status string `json:"status"` // "updated", "unchanged", or "failed"
|
||||
}
|
||||
|
||||
// Result is the structured outcome of the synchronous phase of an install:
|
||||
// fetch/build/install, before any restart happens. Previous and Installed
|
||||
// map a component ID to its version. Field names are snake_case in JSON to
|
||||
// match the install script's ARCHIE_UPDATE_RESULT sentinel line -- see
|
||||
// command.go and scripts/archie-update-install.
|
||||
// Result is the outcome of an install before restart. Previous and Installed
|
||||
// map component IDs to versions.
|
||||
type Result struct {
|
||||
Previous map[string]string `json:"previous"`
|
||||
Installed map[string]string `json:"installed"`
|
||||
|
||||
@@ -23,11 +23,8 @@ type Catalog interface {
|
||||
Check(context.Context) (Snapshot, error)
|
||||
}
|
||||
|
||||
// Installer applies an approved update. It reports only work it has actually
|
||||
// started; callers remain responsible for telling users the final result.
|
||||
// The returned Result covers only the synchronous phase (fetch/build/
|
||||
// install) -- whether a subsequent restart actually came up healthy is
|
||||
// reported later, out of band, via a Report (see pending_report.go).
|
||||
// Installer applies an approved update. The restart outcome is reported
|
||||
// later as a Report.
|
||||
type Installer interface {
|
||||
Install(context.Context, Snapshot, InstallMeta, func(string)) (Result, error)
|
||||
}
|
||||
@@ -38,15 +35,8 @@ type Component struct {
|
||||
Installed string
|
||||
Available string
|
||||
Changelog string
|
||||
// InstallType and Reference describe how this component is actually
|
||||
// deployed -- "binary"/"container"/"embedded"/"external", and a
|
||||
// deployment-specific pointer such as an image digest or a NATS URL.
|
||||
// The external check command that populates Installed/Available cannot
|
||||
// know either of these: it reports what version exists, not how this
|
||||
// particular instance was installed. See Service.Enrich, which fills
|
||||
// them in from sources that actually know (this process's own build
|
||||
// stamp, an observed archie-agent version, deployment configuration for
|
||||
// a third-party dependency this repo doesn't build).
|
||||
// InstallType and Reference describe how this component is deployed, filled
|
||||
// by Service.Enrich.
|
||||
InstallType string
|
||||
Reference string
|
||||
}
|
||||
@@ -93,25 +83,11 @@ type Service struct {
|
||||
Installer Installer
|
||||
StatePath string
|
||||
|
||||
// InstallType gates Install: it must be a value the release pipeline
|
||||
// actually stamps (see package installtype), never "" or
|
||||
// installtype.Unknown, or Install refuses to run the configured
|
||||
// Installer at all. The composition root wires this from
|
||||
// installtype.Type() -- Service itself never reads that package
|
||||
// directly, so a test can exercise every InstallType without touching
|
||||
// process-wide state.
|
||||
// InstallType must be a stamped install type, or Install refuses to run.
|
||||
InstallType string
|
||||
|
||||
// Enrich supplies InstallType/Reference for a known component ID (see
|
||||
// ComponentDaemon, ComponentAgent, ComponentNATS), using sources the
|
||||
// external check command has no way to know -- this process's own
|
||||
// compiled-in installtype.Type(), an archie-agent version actually
|
||||
// observed at runtime (daemon.AgentStatus), or deployment configuration
|
||||
// for a third-party dependency archie doesn't build. Optional: nil (or
|
||||
// a component ID Enrich doesn't recognise, or an empty installType
|
||||
// return) leaves whatever the check command itself reported untouched,
|
||||
// so a check command that DOES report its own value is never silently
|
||||
// overwritten.
|
||||
// Enrich returns a component's install type and reference. Nil or an empty
|
||||
// result leaves the check command's values.
|
||||
Enrich func(componentID string) (installType, reference string)
|
||||
|
||||
mu sync.Mutex
|
||||
@@ -193,12 +169,7 @@ func (s *Service) Defer(ctx context.Context, recipient int64, expected Snapshot)
|
||||
// instance was actually deployed.
|
||||
var ErrUnknownInstallType = errors.New("refusing to install: install type is unknown")
|
||||
|
||||
// ErrInstallInProgress is returned by Install when another install is
|
||||
// already running. Telegram and the web dashboard each keep their own
|
||||
// local "already in progress" flag for a quick UI response, but both are
|
||||
// wired to the same Service in production -- this is the one guard that
|
||||
// actually sees both, since a caller-local bool would let one adapter start
|
||||
// a second install while the other's is still copying binaries.
|
||||
// ErrInstallInProgress is returned when another install is running.
|
||||
var ErrInstallInProgress = errors.New("an update is already in progress")
|
||||
|
||||
// installTimeout bounds an install after it has been deliberately detached
|
||||
@@ -206,17 +177,8 @@ var ErrInstallInProgress = errors.New("an update is already in progress")
|
||||
// script would hold the in-progress lock forever.
|
||||
const installTimeout = 30 * time.Minute
|
||||
|
||||
// Install runs the configured Installer. The context it hands the
|
||||
// Installer is intentionally NOT ctx: ctx belongs to whatever triggered the
|
||||
// update (a chat message handler cancelled by /restart, an HTTP request
|
||||
// cancelled by a client disconnect), and exec.CommandContext SIGKILLs its
|
||||
// child the instant that context is cancelled. The install script backs up
|
||||
// and overwrites the live binaries with plain, non-atomic copies -- a kill
|
||||
// mid-copy can leave the daemon unable to start, with the one thing that
|
||||
// could roll that back (the watchdog) never launched because the script
|
||||
// never reached that line. Detaching the install from ctx, bounded by
|
||||
// installTimeout instead, is what actually makes the caller's own
|
||||
// lifecycle safe to interrupt without corrupting an in-flight update.
|
||||
// Install runs the Installer under installTimeout, detached from ctx so a
|
||||
// cancelled caller cannot kill an install mid-copy.
|
||||
func (s *Service) Install(ctx context.Context, snapshot Snapshot, meta InstallMeta, progress func(string)) (Result, error) {
|
||||
if s == nil || s.Installer == nil {
|
||||
return Result{}, errors.New("update installation is not configured")
|
||||
@@ -269,11 +231,7 @@ func saveDeferrals(path string, state deferrals) error {
|
||||
return writeFileAtomic(path, data)
|
||||
}
|
||||
|
||||
// writeFileAtomic writes data to path via a temp file in the same
|
||||
// directory, synced and renamed into place, so a reader never observes a
|
||||
// partially written file. Shared by saveDeferrals and WritePendingReport --
|
||||
// both are small JSON state files under the same operational directory
|
||||
// (cfg.WorkDir) with the same durability requirement.
|
||||
// writeFileAtomic writes data to path through a synced temp file and rename.
|
||||
func writeFileAtomic(path string, data []byte) error {
|
||||
dir := filepath.Dir(path)
|
||||
if err := os.MkdirAll(dir, 0o700); err != nil {
|
||||
|
||||
@@ -5,69 +5,35 @@ import (
|
||||
"strings"
|
||||
)
|
||||
|
||||
// Component IDs used by the reference install script and watchdog in the
|
||||
// Result and Report JSON documents (scripts/archie-update-install,
|
||||
// scripts/archie-update-watchdog). They are named here because the
|
||||
// composition root has to key its running-version map by exactly these
|
||||
// strings for verification to match anything -- a typo would otherwise
|
||||
// silently downgrade every component to "unverifiable" and restore the
|
||||
// false-success behaviour this file exists to prevent.
|
||||
// Component IDs used by the install script and watchdog.
|
||||
const (
|
||||
ComponentDaemon = "daemon"
|
||||
ComponentAgent = "agent"
|
||||
// ComponentNATS identifies the NATS server in a Snapshot's Components,
|
||||
// by the same convention -- a third-party dependency archie doesn't
|
||||
// build and Report never claims to have installed, but Service.Enrich
|
||||
// can still describe from deployment configuration (embedded vs
|
||||
// external, and the URL an external server was configured with).
|
||||
// ComponentNATS identifies the NATS server.
|
||||
ComponentNATS = "nats"
|
||||
)
|
||||
|
||||
// Version placeholders that carry no release information. Both mean "nobody
|
||||
// recorded a real version here", and neither may be compared as though it
|
||||
// were one: doing so turns a healthy update whose bookkeeping went missing
|
||||
// into a reported failure.
|
||||
//
|
||||
// - VersionUnknown is what the reference watchdog substitutes when it
|
||||
// cannot tell what was installed ("${ARCHIE_UPDATE_INSTALLED_GATEWAY:-unknown}").
|
||||
// - VersionDev is what an unstamped build reports for itself: it is the
|
||||
// default of gatewayVersion/runtimeVersion in cmd/archied, of
|
||||
// GATEWAY_VERSION in Dockerfile.archied, and of the version Taskfile.yml
|
||||
// falls back to when git describes no tag. A plain `go build` or an
|
||||
// untagged image is therefore "dev", not a release.
|
||||
// Placeholder versions that are never compared: VersionUnknown from the
|
||||
// watchdog, VersionDev from unstamped builds.
|
||||
const (
|
||||
VersionUnknown = "unknown"
|
||||
VersionDev = "dev"
|
||||
)
|
||||
|
||||
// VersionDrift is one component whose reported install the running system
|
||||
// contradicts: the installer said it put Claimed into service, but the
|
||||
// component itself reports it is running Running. Both are the versions as
|
||||
// recorded rather than normalized, so an operator sees the strings the two
|
||||
// sides actually wrote; renderers should trim them for display.
|
||||
// VersionDrift is a component running a different version than the one
|
||||
// claimed installed.
|
||||
type VersionDrift struct {
|
||||
ID string
|
||||
Claimed string
|
||||
Running string
|
||||
|
||||
// RunningIsPrevious reports whether the version actually running is the
|
||||
// one this update set out to replace. True is the ordinary case -- the
|
||||
// install silently did nothing and the pre-update process is still there
|
||||
// answering the health probe. False means what is running is neither the
|
||||
// installed version nor the replaced one, and a caller must NOT describe
|
||||
// that as "still on the old release": it does not know what happened,
|
||||
// and asserting a cause it cannot support is the same defect as the
|
||||
// false success this type exists to catch.
|
||||
// RunningIsPrevious reports whether the running version is the one the
|
||||
// update replaced.
|
||||
RunningIsPrevious bool
|
||||
}
|
||||
|
||||
// Verification is the outcome of checking a Report's claims against the
|
||||
// versions actually running. Every component the Report claims to have
|
||||
// installed lands in exactly one of the three sets.
|
||||
//
|
||||
// Unverified is not a lesser Drift: a caller that cannot tell the two apart
|
||||
// will either cry wolf over components that simply cannot self-report, or
|
||||
// keep asserting success it never checked. Both have shipped here.
|
||||
// Verification sorts each claimed component into confirmed, drifted or
|
||||
// unverified.
|
||||
type Verification struct {
|
||||
// Confirmed lists component IDs whose claimed version matches what the
|
||||
// component reports for itself, in ID order.
|
||||
@@ -81,23 +47,9 @@ type Verification struct {
|
||||
Unverified []string
|
||||
}
|
||||
|
||||
// Verify compares what r claims was installed against the versions actually
|
||||
// running now.
|
||||
//
|
||||
// This exists because a Report is entirely self-reported. The reference
|
||||
// watchdog decides "passed" from an HTTP health probe, which proves only
|
||||
// that *a* daemon is answering -- if the new binary never actually made it
|
||||
// into service, the previous one answers the probe just as happily, and the
|
||||
// watchdog then copies the version the installer *intended* into Installed.
|
||||
// The result reads as a successful upgrade to a version that is not running.
|
||||
// That is not hypothetical: it shipped, and a task run immediately after a
|
||||
// reported-successful update hit the exact bug the update was supposed to
|
||||
// fix.
|
||||
//
|
||||
// running maps a component ID (see ComponentDaemon and ComponentAgent) to
|
||||
// the version that component reports for itself -- archied's own compiled-in
|
||||
// build version, for instance, which no installer can talk it out of. A
|
||||
// component absent from running is Unverified, not drifting.
|
||||
// Verify compares the versions r claims were installed with the versions
|
||||
// components report running. Components absent from running are
|
||||
// unverified.
|
||||
func (r Report) Verify(running map[string]string) Verification {
|
||||
var result Verification
|
||||
for id, claimed := range r.Installed {
|
||||
@@ -133,18 +85,8 @@ func IsRecordedVersion(version string) bool {
|
||||
return ok
|
||||
}
|
||||
|
||||
// comparableVersion reduces a recorded version to the form both sides of a
|
||||
// comparison can be expected to agree on, and reports whether it carries any
|
||||
// usable information at all.
|
||||
//
|
||||
// Normalization is deliberately minimal: surrounding whitespace, and a
|
||||
// single leading "v" or "V" so an installer that records the git tag
|
||||
// "v1.9.11" matches a binary stamped "1.9.11" (the reference installer
|
||||
// strips that prefix itself, but nothing forces another deployment shape
|
||||
// to). Everything else is compared exactly -- an installer is expected to
|
||||
// record the version it stamped, not a differently formatted description of
|
||||
// it, and guessing at looser equivalences here would start hiding the very
|
||||
// mismatches this check is for.
|
||||
// comparableVersion trims whitespace and a leading "v", and reports whether
|
||||
// the version is real.
|
||||
func comparableVersion(version string) (string, bool) {
|
||||
normalized := strings.TrimSpace(version)
|
||||
if len(normalized) > 0 && (normalized[0] == 'v' || normalized[0] == 'V') {
|
||||
|
||||
+31
-158
@@ -1,20 +1,6 @@
|
||||
// Package worktree owns archied's git operations: fresh clone per task,
|
||||
// branch, commit as the bot identity, push, diff stats, cleanup. The
|
||||
// daemon performs these deterministically -- the model's shell tool never
|
||||
// drives git.
|
||||
//
|
||||
// Implemented with go-git rather than by shelling out to the git binary.
|
||||
// Two consequences are worth knowing:
|
||||
//
|
||||
// - The forge token never leaves the process. The previous
|
||||
// implementation wrote a GIT_ASKPASS helper script and exported the
|
||||
// token into every child environment; authentication is now an
|
||||
// in-process http.BasicAuth value.
|
||||
// - There is no per-repo object cache. go-git can clone with shared
|
||||
// alternates but has no equivalent of `--dissociate`, so a cached
|
||||
// bare repo would remain a live dependency of every worktree built
|
||||
// from it and expiring one would corrupt running tasks. Each task
|
||||
// gets an independent full clone instead.
|
||||
// Package worktree performs archied's git operations with go-git: clone,
|
||||
// branch, commit, push, diff and cleanup. Each task gets an independent full
|
||||
// clone.
|
||||
package worktree
|
||||
|
||||
import (
|
||||
@@ -43,16 +29,8 @@ import (
|
||||
"github.com/samcharles93/archie-core/internal/domain/workflow/task"
|
||||
)
|
||||
|
||||
// preparedSentinel marks a worktree as fully cloned, branched and
|
||||
// configured. Its presence is what makes Prepare idempotent: the daemon
|
||||
// may prepare a worktree before the task container is acquired.
|
||||
//
|
||||
// It lives inside .git deliberately. The previous implementation kept it
|
||||
// in the working tree and hid it via .git/info/exclude, which worked
|
||||
// because `git add -A` honours that file -- go-git's Add does NOT, so the
|
||||
// sentinel was committed and pushed onto every task branch. Nothing under.
|
||||
// git can ever be tracked, so placing it here removes the failure mode
|
||||
// rather than papering over it.
|
||||
// preparedSentinel marks a worktree as prepared, making Prepare idempotent.
|
||||
// It lives in .git so it is never committed.
|
||||
const preparedSentinel = ".git/archie-prepared"
|
||||
|
||||
type Manager struct {
|
||||
@@ -94,12 +72,7 @@ func ValidCoordinates(owner, repo string, issue int) bool {
|
||||
owner != "." && owner != ".." && repo != "." && repo != ".."
|
||||
}
|
||||
|
||||
// auth builds the HTTP credential for clone, fetch and push.
|
||||
//
|
||||
// Forges accept a personal access token as the password with any
|
||||
// non-empty username, so the bot's own name is used. A nil return means
|
||||
// no token was configured and go-git attempts an anonymous request,
|
||||
// which is correct for a public read.
|
||||
// auth returns the HTTP credential, or nil for anonymous access.
|
||||
func (m *Manager) auth() []gitclient.Option {
|
||||
if m.Token == "" {
|
||||
return nil
|
||||
@@ -120,32 +93,16 @@ func (m *Manager) signature() *object.Signature {
|
||||
return &object.Signature{Name: m.BotUser, Email: m.BotEmail, When: time.Now()}
|
||||
}
|
||||
|
||||
// Target selects the commit a prepared worktree is positioned at.
|
||||
//
|
||||
// The zero value is Fresh: a run that starts new work is reset onto
|
||||
// origin/<base>. A non-empty Target is a resume: the worktree is reset onto
|
||||
// origin/<that branch>, continuing the work an earlier attempt already pushed.
|
||||
//
|
||||
// The branch travels with the choice rather than being recomputed from the
|
||||
// title, because a resume must land on the branch the open pull request lives
|
||||
// on: a retitled issue would otherwise name a branch that does not exist.
|
||||
//
|
||||
// It is a string rather than a bool or an enum precisely so the branch to
|
||||
// resume onto is carried by the choice; a bool would force a second parameter
|
||||
// and let a caller select a resume without naming what it resumes onto.
|
||||
// Target is the branch a worktree is positioned on. Empty (Fresh) resets onto
|
||||
// origin/<base>; a branch name resumes onto origin/<branch>.
|
||||
type Target string
|
||||
|
||||
// Fresh is the fresh-run target: reset onto origin/<base>.
|
||||
const Fresh Target = ""
|
||||
|
||||
// Prepare creates (or reuses) the task's clone and positions it on target,
|
||||
// returning the worktree directory and the branch it is on.
|
||||
//
|
||||
// A missing clone is created for either target. That is what lets a resume
|
||||
// recover a worktree the terminal cleanup, an expired volume or a different
|
||||
// host removed before a retry. Fresh lands it on origin/<base>; a resume lands
|
||||
// it on origin/<branch> and fails closed when that branch is not on the remote
|
||||
// rather than falling back to base.
|
||||
// Prepare clones the task's worktree if missing and positions it on target,
|
||||
// returning its directory and branch. A resume fails if the branch is not on
|
||||
// the remote.
|
||||
func (m *Manager) Prepare(
|
||||
ctx context.Context,
|
||||
owner, repo, base string,
|
||||
@@ -289,12 +246,7 @@ func (m *Manager) refresh(ctx context.Context, dir, base, branch string) error {
|
||||
return resetOnto(r, dir, branch, baseHash, remoteBase(base))
|
||||
}
|
||||
|
||||
// resume re-syncs an already-prepared worktree onto its branch's remote tip
|
||||
// without resetting to base, so a remediation can continue work on the PR
|
||||
// branch an earlier attempt already pushed. It is refresh's complement: refresh
|
||||
// resets to origin/<base> for a fresh run; resume resets to origin/<branch> so
|
||||
// the committed PR work survives. It is reached through Prepare's Target, and
|
||||
// the worktree it opens is one Prepare has already cloned when it was missing.
|
||||
// resume resets an existing worktree onto origin/<branch>.
|
||||
func (m *Manager) resume(ctx context.Context, dir, branch string) error {
|
||||
r, err := git.PlainOpen(dir)
|
||||
if err != nil {
|
||||
@@ -314,21 +266,8 @@ func (m *Manager) resume(ctx context.Context, dir, branch string) error {
|
||||
return resetOnto(r, dir, branch, *tip, remoteBase(branch))
|
||||
}
|
||||
|
||||
// resetOnto discards the worktree's current contents and points branch at
|
||||
// commit, leaving a clean tree that matches commit.
|
||||
//
|
||||
// The ORDER here is the substance of the function, and it is deliberately the
|
||||
// opposite of the checkout-then-reset-then-clean it replaced. A previous
|
||||
// attempt -- an interrupted stage, a killed container, or a build run inside
|
||||
// the root sandbox -- can leave a path whose type contradicts the tree being
|
||||
// reset onto as well as untracked output beside it. go-git's reset cannot
|
||||
// write a file where a directory sits, nor create a directory through a file;
|
||||
// it failed with `openat <path>: is a directory` / `not a directory` before it
|
||||
// could apply anything, and the Create-fallback that used to follow reported
|
||||
// that as a branch that already existed. Clearing the worktree against the
|
||||
// TARGET tree first removes exactly those conflicts -- an on-disk directory the
|
||||
// tree declares as a file is untracked, and so is a file the tree declares as a
|
||||
// directory -- so the reset that follows has nothing left to collide with.
|
||||
// resetOnto removes everything the target tree does not contain, then points
|
||||
// branch at commit with a clean tree.
|
||||
func resetOnto(r *git.Repository, dir, branch string, commit plumbing.Hash, label string) error {
|
||||
target, err := commitTree(r, commit)
|
||||
if err != nil {
|
||||
@@ -351,21 +290,8 @@ func resetOnto(r *git.Repository, dir, branch string, commit plumbing.Hash, labe
|
||||
return nil
|
||||
}
|
||||
|
||||
// checkOutBranch switches the worktree to branch, creating it at commit when it
|
||||
// does not exist yet.
|
||||
//
|
||||
// Whether the branch exists is resolved from the reference store rather than
|
||||
// inferred from a failed checkout. A checkout fails for reasons that have
|
||||
// nothing to do with a missing branch -- most often a path in the working tree
|
||||
// the tree cannot be written over -- and treating any such failure as "the
|
||||
// branch does not exist yet" produced `a branch named "refs/heads/<branch>"
|
||||
// already exists`: it named a branch that was never the problem and hid the
|
||||
// real cause from the park reason an operator reads to decide what to do.
|
||||
//
|
||||
// Creating from an explicit commit rather than from HEAD matters too: a branch
|
||||
// removed while HEAD still pointed at it (a renamed branch, a half-finished
|
||||
// refresh) made go-git's create path read an unresolvable HEAD and fail with
|
||||
// "reference not found" instead of creating the branch.
|
||||
// checkOutBranch checks out branch, creating it at commit if it does not
|
||||
// exist.
|
||||
func checkOutBranch(r *git.Repository, wt *git.Worktree, branch string, commit plumbing.Hash) error {
|
||||
ref := plumbing.NewBranchReferenceName(branch)
|
||||
opts := &git.CheckoutOptions{Branch: ref, Force: true}
|
||||
@@ -397,13 +323,7 @@ func commitTree(r *git.Repository, commit plumbing.Hash) (*object.Tree, error) {
|
||||
return tree, nil
|
||||
}
|
||||
|
||||
// cleanUntracked removes every path under dir that tree does not contain:
|
||||
// untracked files, whole directories of build output, and any path whose type
|
||||
// on disk contradicts what the tree declares.
|
||||
//
|
||||
// It is given the tree the worktree is being reset ONTO, not HEAD: the point is
|
||||
// to leave nothing behind that the incoming tree cannot be written over, and
|
||||
// on a retry HEAD is one of the things being replaced.
|
||||
// cleanUntracked removes every path under dir that tree does not contain.
|
||||
func cleanUntracked(dir string, tree *object.Tree) error {
|
||||
files := make(map[string]struct{})
|
||||
dirs := make(map[string]struct{})
|
||||
@@ -424,12 +344,7 @@ func cleanUntracked(dir string, tree *object.Tree) error {
|
||||
}
|
||||
rel = filepath.ToSlash(rel)
|
||||
if rel == ".git" {
|
||||
// SkipDir on a non-directory skips the rest of the *parent*
|
||||
// directory -- at the worktree root, the whole walk. .git is a
|
||||
// file, not a directory, in a linked worktree, so returning
|
||||
// SkipDir there would abandon cleaning entirely. Either shape
|
||||
// is left untouched; only the directory shape needs descent
|
||||
// suppressed.
|
||||
// Leave a .git file or directory alone.
|
||||
if entry.IsDir() {
|
||||
return filepath.SkipDir
|
||||
}
|
||||
@@ -490,14 +405,7 @@ func (m *Manager) setIdentity(r *git.Repository) error {
|
||||
}
|
||||
cfg.User.Name = m.BotUser
|
||||
cfg.User.Email = m.BotEmail
|
||||
// Pin signing off for this repository.
|
||||
//
|
||||
// go-git honours the host's global git config, and it cannot sign:
|
||||
// it has no gpg fallback, only an ObjectSigner plugin. A developer
|
||||
// or CI image with commit.gpgSign=true set globally would therefore
|
||||
// make every bot commit fail with "cannot auto-sign commit". The
|
||||
// daemon's behaviour must not depend on the ambient git config of
|
||||
// whatever machine it happens to run on.
|
||||
// Disable commit signing; go-git cannot sign.
|
||||
cfg.Raw.Section("commit").SetOption("gpgsign", "false")
|
||||
if err := r.SetConfig(cfg); err != nil {
|
||||
return fmt.Errorf("write repo config: %w", err)
|
||||
@@ -639,12 +547,8 @@ func (m *Manager) patch(ctx context.Context, dir, base string) (*object.Patch, e
|
||||
return p, err
|
||||
}
|
||||
|
||||
// patchFromMergeBase is patch plus the commit the diff was actually taken
|
||||
// against. That commit is the merge base of base and HEAD, which is NOT base's
|
||||
// tip once anyone has landed on the base branch since this branch diverged.
|
||||
// A capture records it beside the file list it measured, so the two describe
|
||||
// one change set: re-resolving origin/<base> on the side would name the new
|
||||
// tip instead.
|
||||
// patchFromMergeBase returns the patch and the merge-base commit it was taken
|
||||
// against.
|
||||
func (m *Manager) patchFromMergeBase(ctx context.Context, dir, base string) (*object.Patch, plumbing.Hash, error) {
|
||||
r, err := git.PlainOpen(dir)
|
||||
if err != nil {
|
||||
@@ -680,15 +584,8 @@ func (m *Manager) patchFromMergeBase(ctx context.Context, dir, base string) (*ob
|
||||
return p, bases[0].Hash, nil
|
||||
}
|
||||
|
||||
// HasUncommittedChanges reports whether the worktree holds work no commit has
|
||||
// captured yet: staged, unstaged or untracked. Ignored files do not count, the
|
||||
// same rule CommitAll's own status check applies when it decides whether there
|
||||
// is anything to commit.
|
||||
//
|
||||
// It exists because Diff cannot answer this: Diff reports what the branch has
|
||||
// committed against the merge base and never reads the worktree, so a stage
|
||||
// that must inspect the committed change has no way to tell "nothing has
|
||||
// changed" from "the change is not committed yet" without this.
|
||||
// HasUncommittedChanges reports whether the worktree has staged, unstaged or
|
||||
// untracked changes, ignoring ignored files.
|
||||
func (m *Manager) HasUncommittedChanges(ctx context.Context, dir string) (bool, error) {
|
||||
if err := ctx.Err(); err != nil {
|
||||
return false, err
|
||||
@@ -772,14 +669,8 @@ func (m *Manager) ChangedFiles(ctx context.Context, dir, base string) ([]string,
|
||||
// a change across types is a typechange.
|
||||
const fileTypeMask = 0o170000
|
||||
|
||||
// ChangedFileStats reports what HEAD changed against base, as the per-file
|
||||
// status and line counts one attempt's capture records. It reuses patch's
|
||||
// three-dot semantics: diffing against the remote tip instead would attribute
|
||||
// every commit landed on base since the branch started to this task.
|
||||
//
|
||||
// ChangedLines, Diff and ChangedFiles stay the shape stages call; this is the
|
||||
// same measurement with the detail a capture needs, so there is still exactly
|
||||
// one diff path -- and it reports the base that path diffed against.
|
||||
// ChangedFileStats reports HEAD's per-file changes against the merge base
|
||||
// with base.
|
||||
func (m *Manager) ChangedFileStats(ctx context.Context, dir, base string) (task.ChangeStats, error) {
|
||||
// The diffed base is the merge base patchFromMergeBase diffed against, not
|
||||
// base's tip: the recorded pair has to describe the file list beside it.
|
||||
@@ -797,13 +688,7 @@ func (m *Manager) ChangedFileStats(ctx context.Context, dir, base string) (task.
|
||||
}
|
||||
|
||||
patches := p.FilePatches()
|
||||
// Paths come from FilePatches and counts from Stats, joined by position,
|
||||
// because Stats() carries one entry per patch that produced textual chunks
|
||||
// and SKIPS the rest (binary files, and any change whose content is
|
||||
// identical). Reading the two lists off the same index would shift every
|
||||
// later file's counts onto the wrong path as soon as one binary file is in
|
||||
// the change. Totals come from Stats so they agree with ChangedLines, which
|
||||
// sums the same list.
|
||||
// Stats has no entry for binary or content-identical files.
|
||||
stats := p.Stats()
|
||||
next := 0
|
||||
files := make([]task.FileChange, 0, len(patches))
|
||||
@@ -864,11 +749,7 @@ func fileChange(fp fdiff.FilePatch) task.FileChange {
|
||||
return change
|
||||
}
|
||||
|
||||
// Snapshot exports HEAD's tracked files into a fresh, empty destDir with no.
|
||||
// git directory: file contents only, no commit history, branch name, or reflog.
|
||||
// Used to build the reviewer's isolated workspace -- stripping.git is what
|
||||
// makes the implementer's reasoning (commit messages, branch name, history)
|
||||
// structurally unreachable rather than merely undisclosed.
|
||||
// Snapshot exports HEAD's tracked files into destDir, without .git.
|
||||
func (m *Manager) Snapshot(ctx context.Context, dir, destDir string) error {
|
||||
r, err := git.PlainOpen(dir)
|
||||
if err != nil {
|
||||
@@ -954,11 +835,8 @@ func remoteBase(base string) string {
|
||||
return "refs/remotes/" + git.DefaultRemoteName + "/" + base
|
||||
}
|
||||
|
||||
// CheckoutPR materialises an existing pull request's head commit in a fresh
|
||||
// full clone so the caller can Diff it against its base and Snapshot it for
|
||||
// operator-triggered review. The head must already be pushed to the same
|
||||
// repository (archie's own PRs always are); a cross-repo or deleted head is
|
||||
// refused rather than half-reviewed. The returned cleanup removes the clone.
|
||||
// CheckoutPR clones a pull request's head into a fresh directory. The head
|
||||
// must be in the same repository. The cleanup removes the clone.
|
||||
func (m *Manager) CheckoutPR(ctx context.Context, owner, repo, headRef, baseRef string) (dir string, cleanup func(), err error) {
|
||||
if m.WorkDir != "" {
|
||||
if err := os.MkdirAll(m.WorkDir, 0o755); err != nil {
|
||||
@@ -1003,13 +881,8 @@ func (m *Manager) CheckoutPR(ctx context.Context, owner, repo, headRef, baseRef
|
||||
return dir, cleanup, nil
|
||||
}
|
||||
|
||||
// resolveBase finds the commit the task branch is compared against.
|
||||
//
|
||||
// The fully-qualified remote-tracking ref is tried first because that is
|
||||
// what a clone produces and it cannot be shadowed. The bare "origin/<base>"
|
||||
// revision is tried second so that resolution stays as permissive as
|
||||
// `git diff origin/<base>...HEAD` was -- git resolves that short form
|
||||
// against refs/heads too, and repositories built that way exist.
|
||||
// resolveBase resolves the base commit from refs/remotes/origin/<base>, then
|
||||
// origin/<base>.
|
||||
func resolveBase(r *git.Repository, base string) (plumbing.Hash, error) {
|
||||
candidates := []plumbing.Revision{
|
||||
plumbing.Revision(remoteBase(base)),
|
||||
|
||||
Reference in new issue
Block a user