Adds PutApplyStatus/ListApplyStatus so each process can report which version of a control-plane resource it is running, and the UI can read it back. docs/prds/control-plane-apply-status.md is the approved design. It goes on the State Store contract rather than the control plane, whose service is for editing a resource: a status report is not an edit. The config-snapshot pair is the precedent, and the deny-by-default arm of authorizesTaskScopedCall already refuses both new RPCs to a task grant, which TestOnlyAdminReportsApplyStatus pins. The row is keyed on (process, kind) and replaced in place, because a process re-stamps on an interval and nothing reads a history of re-stamps. An error leaves applied_version alone, so a rejected edit never erases the fact that an older version is live. The read is a list and an empty one is not an error, unlike the config snapshot's found=false singleton. Contract PRD inventory and RPC count follow in the same series. Relates to archie-core-pskb.
293 lines
14 KiB
Go
293 lines
14 KiB
Go
// Package storecontract is the ratified State Store contract as its
|
|
// consumers reference it: the producer-owned daemon/webui/intake store
|
|
// surfaces (docs/prds/state-store-contract.md §1, §2). It carries no
|
|
// persistence -- *store.Store (SQLite, transitional location) 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 (archie-core-8cda.5.6). Relocated from
|
|
// internal/store by the UI Service deletion gate; internal/store keeps
|
|
// type aliases so daemon-side callers are unaffected.
|
|
package storecontract
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
"io"
|
|
"time"
|
|
|
|
"github.com/samcharles93/archie-core/internal/domain/binding"
|
|
"github.com/samcharles93/archie-core/internal/domain/mapping"
|
|
"github.com/samcharles93/archie-core/internal/domain/workflow/task"
|
|
"github.com/samcharles93/archie-core/internal/events"
|
|
"github.com/samcharles93/archie-core/internal/logging"
|
|
)
|
|
|
|
// TaskStore is the full store surface the daemon needs.
|
|
// Consumers depend on TaskStore, never on a concrete type.
|
|
type TaskStore interface {
|
|
TaskLifecycle
|
|
TaskEvents
|
|
TaskQueries
|
|
TaskArchiver
|
|
TaskRetryer
|
|
}
|
|
|
|
// TaskLifecycle manages the core task state machine and enqueuing.
|
|
// Binding-triggered task creation lives on BindingTaskCreator, not here,
|
|
// so the lifecycle surface stays narrow and non-binding consumers (forge
|
|
// poll, chat spawn, drain loop) do not acquire a binding-specific shape.
|
|
type TaskLifecycle interface {
|
|
EnqueueIssue(ctx context.Context, owner, repo string, number int, title, body, labels, identity string) (bool, error)
|
|
EnqueueChatTask(ctx context.Context, owner, repo, title, body, wf, identity string) (*task.Task, error)
|
|
ClaimNext(ctx context.Context) (*task.Task, error)
|
|
ClaimByIssue(ctx context.Context, owner, repo string, number int) (*task.Task, error)
|
|
Transition(ctx context.Context, taskID int64, from, to, detail string) error
|
|
Update(ctx context.Context, t *task.Task) error
|
|
Requeue(ctx context.Context, taskID int64, fromStatus, workflow string) error
|
|
RecoverStale(ctx context.Context) (int64, error)
|
|
}
|
|
|
|
// TaskArchiver removes one terminal task's local record with an optimistic
|
|
// status guard. It is separate from the already broad lifecycle contract so
|
|
// consumers that only run tasks do not acquire an operator-only capability.
|
|
type TaskArchiver interface {
|
|
ArchiveTask(ctx context.Context, taskID int64, fromStatus string, audit events.Event) (eventID int64, err error)
|
|
}
|
|
|
|
// TaskRetryer atomically requeues recoverable work and accounts for the new
|
|
// attempt so a partial write cannot evade the retry cap.
|
|
type TaskRetryer interface {
|
|
RetryTask(ctx context.Context, taskID int64, fromStatus, workflow string) error
|
|
}
|
|
|
|
// TaskQueries groups read-only task accessors.
|
|
type TaskQueries interface {
|
|
TaskByIssue(ctx context.Context, owner, repo string, number int) (*task.Task, error)
|
|
OpenTaskByPR(ctx context.Context, owner, repo string, number int) (*task.Task, error)
|
|
TaskByID(ctx context.Context, taskID int64) (*task.Task, error)
|
|
OpenPRs(ctx context.Context) ([]task.Task, error)
|
|
ClearTerminalTasks(ctx context.Context) (int64, error)
|
|
Tasks(ctx context.Context, limit int) ([]task.Task, error)
|
|
StatusCounts(ctx context.Context) (map[string]int, error)
|
|
}
|
|
|
|
// TaskEvents groups observability and lifecycle methods.
|
|
type TaskEvents interface {
|
|
InsertEvent(ctx context.Context, e events.Event) (int64, error)
|
|
EventsSince(ctx context.Context, sinceID int64, limit int) ([]events.Event, error)
|
|
TaskEvents(ctx context.Context, taskID int64) ([]events.Event, error)
|
|
WorkflowStats(ctx context.Context) ([]WorkflowStat, error)
|
|
StageStats(ctx context.Context) ([]StageStat, error)
|
|
TokensByDay(ctx context.Context, days int) ([]DayTokens, error)
|
|
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. See docs/prds/event-capture-storage.md.
|
|
type CaptureStore interface {
|
|
InsertCapture(ctx context.Context, c CapturedEvent, retention time.Duration, maxEvents int) (int64, 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.
|
|
// See docs/architecture/migration-decisions.md, "Dashboard configuration page".
|
|
type ConfigSnapshotStore interface {
|
|
PutConfigSnapshot(ctx context.Context, snapshot ConfigSnapshot) error
|
|
ConfigSnapshot(ctx context.Context) (ConfigSnapshot, bool, error)
|
|
}
|
|
|
|
// ApplyStatusStore holds which version of each control-plane resource each
|
|
// process is running. Same split as ConfigSnapshotStore and for the same
|
|
// reason: the writers are the processes that apply a resource, the reader is
|
|
// the UI, and a task-scoped credential must reach neither.
|
|
// See docs/prds/control-plane-apply-status.md.
|
|
type ApplyStatusStore interface {
|
|
PutApplyStatus(ctx context.Context, status ApplyStatus) error
|
|
ListApplyStatus(ctx context.Context) ([]ApplyStatus, error)
|
|
}
|
|
|
|
// MappingStore persists payload field mappings (t2db.3). Deliberately
|
|
// separate from TaskStore and CaptureStore for the same reason those are
|
|
// split: the dashboard's mapping editor should only acquire the mapping
|
|
// surface, not the full task or capture APIs. See
|
|
// docs/prds/payload-field-mapping.md.
|
|
type MappingStore interface {
|
|
InsertMapping(ctx context.Context, m mapping.Mapping) (int64, error)
|
|
GetMapping(ctx context.Context, id int64) (*mapping.Mapping, error)
|
|
ListMappings(ctx context.Context) ([]mapping.Mapping, error)
|
|
UpdateMapping(ctx context.Context, m mapping.Mapping) error
|
|
DeleteMapping(ctx context.Context, id int64) error
|
|
}
|
|
|
|
// BindingStore persists playbook bindings (t2db.4 Phase B): 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
|
|
// docs/prds/playbook-binding.md.
|
|
type BindingStore interface {
|
|
InsertBinding(ctx context.Context, b binding.Binding) (int64, error)
|
|
GetBinding(ctx context.Context, id int64) (*binding.Binding, error)
|
|
ListBindings(ctx context.Context) ([]binding.Binding, error)
|
|
UpdateBinding(ctx context.Context, b binding.Binding) error
|
|
DeleteBinding(ctx context.Context, id int64) error
|
|
ApproveBinding(ctx context.Context, id int64) 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.
|
|
type BindingDispatcher interface {
|
|
ArmedBindingsForSource(ctx context.Context, source string) ([]binding.Binding, error)
|
|
RecordDispatch(
|
|
ctx context.Context,
|
|
bindingID int64,
|
|
bindingVersion int64,
|
|
captureID int64,
|
|
taskID int64,
|
|
) error
|
|
ListUndispatchedCaptures(ctx context.Context, sources []string, limit int) ([]CapturedEvent, error)
|
|
}
|
|
|
|
// BindingTaskCreator is the single-method consumer-facing surface for
|
|
// enqueueing a task triggered by a binding. Splitting it off TaskLifecycle
|
|
// keeps the lifecycle surface narrow (8 methods, the interfacebloat limit)
|
|
// and keeps the binding-specific shape on the binding interfaces.
|
|
type BindingTaskCreator interface {
|
|
EnqueueBindingTask(ctx context.Context, owner, repo, title, body, wf, identity string, bindingID int64, bindingVersion int) (*task.Task, 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 (docs/prds/ui-service-boundary.md).
|
|
//
|
|
// 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.
|
|
type TaskLogStore interface {
|
|
// TaskLog returns a page of one attempt's decoded log. attempt 0 selects
|
|
// the task's current attempt.
|
|
TaskLog(ctx context.Context, taskID int64, attempt int, q logging.Query) (logging.TaskLogPage, error)
|
|
// TaskLogContent writes one attempt's log verbatim to w, for a download.
|
|
// found is false, with a nil error, when the attempt has no log file.
|
|
TaskLogContent(ctx context.Context, taskID int64, attempt int, w io.Writer) (found bool, err error)
|
|
}
|
|
|
|
// CapturedEvent is one unbound inbound webhook capture: no workflow binding,
|
|
// no forge/task association -- just what arrived, from where, and when.
|
|
// See docs/prds/event-capture-storage.md.
|
|
type CapturedEvent struct {
|
|
ID int64 `json:"id"`
|
|
ReceivedAt time.Time `json:"received_at"`
|
|
Source string `json:"source"`
|
|
RemoteAddr string `json:"remote_addr"`
|
|
ContentType string `json:"content_type"`
|
|
// Headers and Body are redacted (webhookguard.RedactPayload) before
|
|
// they ever reach InsertCapture; the store persists what it is given.
|
|
Headers string `json:"headers"`
|
|
Body string `json:"body"`
|
|
Authenticated bool `json:"authenticated"`
|
|
}
|
|
|
|
// 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).
|
|
type ConfigSnapshot struct {
|
|
Schema string
|
|
Document []byte
|
|
PublishedAt 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.
|
|
type ApplyStatus struct {
|
|
Process string `json:"process"`
|
|
Kind string `json:"kind"`
|
|
AppliedVersion int64 `json:"applied_version"`
|
|
Error string `json:"error,omitempty"`
|
|
ReportedAt time.Time `json:"reported_at"`
|
|
}
|
|
|
|
// WorkflowStat is one row of the per-workflow metrics table.
|
|
type WorkflowStat struct {
|
|
Workflow string `json:"workflow"`
|
|
Runs int `json:"runs"`
|
|
Merged int `json:"merged"`
|
|
PROpen int `json:"pr_open"`
|
|
Parked int `json:"parked"`
|
|
AvgTokens int `json:"avg_tokens"`
|
|
AvgSteps float64 `json:"avg_steps"`
|
|
TotalToken int `json:"total_tokens"`
|
|
}
|
|
|
|
// StageStat is average stage duration and failure counts per stage.
|
|
type StageStat struct {
|
|
Workflow string `json:"workflow"`
|
|
Stage string `json:"stage"`
|
|
Runs int `json:"runs"`
|
|
AvgMs int `json:"avg_ms"`
|
|
Errors int `json:"errors"`
|
|
}
|
|
|
|
// DayTokens is token spend per UTC day.
|
|
type DayTokens struct {
|
|
Day string `json:"day"`
|
|
Tokens int `json:"tokens"`
|
|
}
|
|
|
|
// Sentinel errors, part of the wire contract: staterpc's
|
|
// mapError/unmapError match these by (code, canonical message) across the
|
|
// gRPC boundary, so their message strings are load-bearing and must never
|
|
// change (docs/prds/state-store-contract.md §4).
|
|
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")
|
|
// ErrBindingNotFound is returned when a binding ID does not exist.
|
|
ErrBindingNotFound = errors.New("store: binding not found")
|
|
// ErrBindingOverlap is returned when a binding's matcher overlaps an
|
|
// existing binding for the same source.
|
|
ErrBindingOverlap = errors.New("store: binding overlaps existing binding for source")
|
|
// 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 capture already has a
|
|
// dispatch ledger row (at-most-once dispatch).
|
|
ErrAlreadyDispatched = errors.New("store: binding already dispatched for capture")
|
|
// ErrMappingNotFound is returned when a mapping ID does not exist.
|
|
ErrMappingNotFound = errors.New("store: mapping not found")
|
|
)
|