refactor(staterpc,releaseupdate,agentexec,storecontract,worktree): cut comments down to what the code does

This commit is contained in:
sam committed 2026-10-03 22:00:43 +10:00
1 parent ddcb5a845b
commit a8b3dc55d0
22 files changed
+175 -822

No files matched your search

+7 -23
View File
@@ -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(
+2 -7
View File
@@ -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"`
}
+4 -13
View File
@@ -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 {
+4 -14
View File
@@ -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
+5 -37
View File
@@ -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,
+3 -17
View File
@@ -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 {
+11 -47
View File
@@ -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)
}
+2 -8
View File
@@ -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
+38 -150
View File
@@ -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
+2 -12
View File
@@ -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...)
+2 -5
View File
@@ -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 -85
View File
@@ -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 {
+5 -24
View File
@@ -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)
+7 -46
View File
@@ -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
+4 -10
View File
@@ -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")
+2 -7
View File
@@ -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"`
+3 -13
View File
@@ -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."
+3 -11
View File
@@ -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"`
+11 -53
View File
@@ -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 {
+15 -73
View File
@@ -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
View File
@@ -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)),