Files
archie/internal/infrastructure/staterpc/client.go
T
sam d6f526ce4f feat(state): carry channel lifecycle from the Messaging Service to the dashboard
archie-core-8cda.6.8's carrier. The service now records channel lifecycle and has
nowhere to put it: /api/channels answered with nothing because
webui.Server.Channels had no production source, and reload answered 501 for the
same reason. This adds the surface the register decided on, following the split
archie-core-ymut established for config snapshots -- a pair of administrative RPCs
whose writer is one process and whose reader is the UI -- and wires both ends.

Wire and store: PutChannelStatus / ListChannelStatus, with ChannelStatus carrying
id, name, state, detail, configured, reload_supported and observed_at. The store
holds one row per channel and replaces the reported set, so a channel the reporter
no longer mentions is deleted rather than left standing as a stale "running"; an
empty report clears the table, because hosting no channels is a fact worth
reporting. A row without an id is refused: it could never be replaced or removed
by a later report.

Writer: the service publishes on every lifecycle transition through a coalescing
signal -- a burst of transitions is one write, since a reader only wants the latest
state of every channel -- plus a start-up report and a final report after shutdown,
so a stopped service leaves the store honest. A failed write is logged and retried
on the next signal; the dashboard losing channel state is worth a warning and never
worth failing a channel start over.

Reader: webui.Server.Channels becomes a source rather than a concrete manager, and
webui.RemoteChannelStatus reads the store the way RemoteConfigView reads the config
snapshot. A store it cannot reach reports nothing rather than a stale "running",
and a state the reader does not recognise is carried through rather than dropped.

The contract's own index gains the group in the same change that adds the RPCs --
a surface the grouped table does not list is one nobody finds -- and the count moves
to 51. The register records why the surface is the State Store rather than a
resource kind, and why reload gets its own surface rather than a field here: reading
status must not be able to retrigger an action, a transient request is not
distinguishable from state once anything polls it, and it would invert the
writer/reader relationship the precedent establishes.

Verified: task check exit 0. New coverage: the store's replace-the-set semantics
and its refusal of an id-less row, the reader's mapping including an unknown state,
and the publisher's start-up, transition and final reports.
2026-09-22 08:04:44 +10:00

570 lines
19 KiB
Go

package staterpc
import (
"context"
"errors"
"io"
"time"
"google.golang.org/grpc"
controlpb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1"
pb "github.com/samcharles93/archie-core/internal/contracts/state/v1"
"github.com/samcharles93/archie-core/internal/domain/binding"
"github.com/samcharles93/archie-core/internal/domain/identity"
"github.com/samcharles93/archie-core/internal/domain/mapping"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
"github.com/samcharles93/archie-core/internal/domain/workflow/task"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/logging"
)
// Client is the single remote adapter wrapping one StateStoreServiceClient,
// asserted against whichever narrow Go interfaces its caller needs -- exactly
// as gatewayrpc.Client asserts both messaging.ChatContract and
// messaging.SessionStore. See docs/prds/state-store-contract.md §2.
type Client struct {
client pb.StateStoreServiceClient
controlPlane controlpb.ControlPlaneServiceClient
}
// NewClient wraps conn's generated client. Close is a no-op: the store
// service owns its own DB lifecycle (§11).
func NewClient(conn grpc.ClientConnInterface) *Client {
return &Client{client: pb.NewStateStoreServiceClient(conn), controlPlane: controlpb.NewControlPlaneServiceClient(conn)}
}
// ControlPlane returns the generic control-plane RPC client on the same authenticated connection.
func (c *Client) ControlPlane() controlpb.ControlPlaneServiceClient { return c.controlPlane }
// Close is a no-op; the remote store service owns its own DB lifecycle.
func (c *Client) Close() error { return nil }
var (
_ task.Store = (*Client)(nil)
_ storecontract.TaskStore = (*Client)(nil)
_ storecontract.TaskLogStore = (*Client)(nil)
_ storecontract.CaptureStore = (*Client)(nil)
_ storecontract.MappingStore = (*Client)(nil)
_ storecontract.BindingStore = (*Client)(nil)
_ storecontract.BindingDispatcher = (*Client)(nil)
_ storecontract.BindingTaskCreator = (*Client)(nil)
_ storecontract.PlaybookDispatcher = (*Client)(nil)
_ storecontract.ConfigSnapshotStore = (*Client)(nil)
_ storecontract.ChannelStatusStore = (*Client)(nil)
_ storecontract.ApplyStatusStore = (*Client)(nil)
_ identity.Repository = (*Client)(nil)
)
// Lifecycle
func (c *Client) EnqueueIssue(ctx context.Context, owner, repo string, number int, title, body, labels, identity string) (bool, error) {
r, err := c.client.EnqueueIssue(ctx, &pb.EnqueueIssueRequest{Owner: owner, Repo: repo, Number: int64(number), Title: title, Body: body, Labels: labels, Identity: identity})
if err != nil {
return false, unmapError(err)
}
return r.Inserted, nil
}
func (c *Client) EnqueueChatTask(ctx context.Context, owner, repo, title, body, wf, identity string) (*task.Task, error) {
r, err := c.client.EnqueueChatTask(ctx, &pb.EnqueueChatTaskRequest{Owner: owner, Repo: repo, Title: title, Body: body, Workflow: wf, Identity: identity})
if err != nil {
return nil, unmapError(err)
}
return taskValue(r.Task), nil
}
func (c *Client) ClaimNext(ctx context.Context) (*task.Task, error) {
r, err := c.client.ClaimNext(ctx, &pb.ClaimNextRequest{})
if err != nil {
return nil, unmapError(err)
}
if !r.Found {
return nil, nil
}
return taskValue(r.Task), nil
}
func (c *Client) ClaimByIssue(ctx context.Context, owner, repo string, number int) (*task.Task, error) {
r, err := c.client.ClaimByIssue(ctx, &pb.ClaimByIssueRequest{Owner: owner, Repo: repo, Number: int64(number)})
if err != nil {
return nil, unmapError(err)
}
if !r.Found {
return nil, nil
}
return taskValue(r.Task), nil
}
func (c *Client) Transition(ctx context.Context, taskID int64, from, to, detail string) error {
_, err := c.client.Transition(ctx, &pb.TransitionRequest{TaskId: taskID, From: from, To: to, Detail: detail})
return unmapError(err)
}
func (c *Client) Update(ctx context.Context, t *task.Task) error {
_, err := c.client.Update(ctx, &pb.UpdateRequest{Task: taskProto(t)})
return unmapError(err)
}
func (c *Client) Requeue(ctx context.Context, taskID int64, fromStatus, wf string) error {
_, err := c.client.Requeue(ctx, &pb.RequeueRequest{TaskId: taskID, FromStatus: fromStatus, Workflow: wf})
return unmapError(err)
}
func (c *Client) RecoverStale(ctx context.Context) (int64, error) {
r, err := c.client.RecoverStale(ctx, &pb.RecoverStaleRequest{})
if err != nil {
return 0, unmapError(err)
}
return r.Count, nil
}
// Archive / Retry
func (c *Client) ArchiveTask(ctx context.Context, taskID int64, fromStatus string, audit events.Event) (int64, error) {
r, err := c.client.ArchiveTask(ctx, &pb.ArchiveTaskRequest{TaskId: taskID, FromStatus: fromStatus, Audit: eventProto(audit)})
if err != nil {
return 0, unmapError(err)
}
return r.EventId, nil
}
func (c *Client) RetryTask(ctx context.Context, taskID int64, fromStatus, wf string) error {
_, err := c.client.RetryTask(ctx, &pb.RetryTaskRequest{TaskId: taskID, FromStatus: fromStatus, Workflow: wf})
return unmapError(err)
}
// Queries
func (c *Client) TaskByIssue(ctx context.Context, owner, repo string, number int) (*task.Task, error) {
r, err := c.client.TaskByIssue(ctx, &pb.TaskByIssueRequest{Owner: owner, Repo: repo, Number: int64(number)})
if err != nil {
return nil, unmapError(err)
}
if !r.Found {
return nil, nil
}
return taskValue(r.Task), nil
}
func (c *Client) OpenTaskByPR(ctx context.Context, owner, repo string, number int) (*task.Task, error) {
r, err := c.client.OpenTaskByPR(ctx, &pb.OpenTaskByPRRequest{Owner: owner, Repo: repo, Number: int64(number)})
if err != nil {
return nil, unmapError(err)
}
if !r.Found {
return nil, nil
}
return taskValue(r.Task), nil
}
func (c *Client) TaskByID(ctx context.Context, taskID int64) (*task.Task, error) {
r, err := c.client.TaskByID(ctx, &pb.TaskByIDRequest{TaskId: taskID})
if err != nil {
return nil, unmapError(err)
}
if !r.Found {
return nil, nil
}
return taskValue(r.Task), nil
}
func (c *Client) OpenPRs(ctx context.Context) ([]task.Task, error) {
r, err := c.client.OpenPRs(ctx, &pb.OpenPRsRequest{})
if err != nil {
return nil, unmapError(err)
}
return derefTasks(r.Tasks), nil
}
func (c *Client) ClearTerminalTasks(ctx context.Context) (int64, error) {
r, err := c.client.ClearTerminalTasks(ctx, &pb.ClearTerminalTasksRequest{})
if err != nil {
return 0, unmapError(err)
}
return r.Count, nil
}
func (c *Client) Tasks(ctx context.Context, limit int) ([]task.Task, error) {
r, err := c.client.Tasks(ctx, &pb.TasksRequest{Limit: int64(limit)})
if err != nil {
return nil, unmapError(err)
}
return derefTasks(r.Tasks), nil
}
func (c *Client) StatusCounts(ctx context.Context) (map[string]int, error) {
r, err := c.client.StatusCounts(ctx, &pb.StatusCountsRequest{})
if err != nil {
return nil, unmapError(err)
}
out := make(map[string]int, len(r.Counts))
for k, v := range r.Counts {
out[k] = int(v)
}
return out, nil
}
// Events
func (c *Client) InsertEvent(ctx context.Context, e events.Event) (int64, error) {
r, err := c.client.InsertEvent(ctx, &pb.InsertEventRequest{Event: eventProto(e)})
if err != nil {
return 0, unmapError(err)
}
return r.Id, nil
}
func (c *Client) EventsSince(ctx context.Context, sinceID int64, limit int) ([]events.Event, error) {
r, err := c.client.EventsSince(ctx, &pb.EventsSinceRequest{SinceId: sinceID, Limit: int64(limit)})
if err != nil {
return nil, unmapError(err)
}
return mapValues(r.Events, eventValue), nil
}
func (c *Client) TaskEvents(ctx context.Context, taskID int64) ([]events.Event, error) {
r, err := c.client.TaskEvents(ctx, &pb.TaskEventsRequest{TaskId: taskID})
if err != nil {
return nil, unmapError(err)
}
return mapValues(r.Events, eventValue), nil
}
func (c *Client) WorkflowStats(ctx context.Context) ([]storecontract.WorkflowStat, error) {
r, err := c.client.WorkflowStats(ctx, &pb.WorkflowStatsRequest{})
if err != nil {
return nil, unmapError(err)
}
return mapValues(r.Stats, workflowStatValue), nil
}
func (c *Client) StageStats(ctx context.Context) ([]storecontract.StageStat, error) {
r, err := c.client.StageStats(ctx, &pb.StageStatsRequest{})
if err != nil {
return nil, unmapError(err)
}
return mapValues(r.Stats, stageStatValue), nil
}
func (c *Client) TokensByDay(ctx context.Context, days int) ([]storecontract.DayTokens, error) {
r, err := c.client.TokensByDay(ctx, &pb.TokensByDayRequest{Days: int64(days)})
if err != nil {
return nil, unmapError(err)
}
return mapValues(r.Tokens, dayTokensValue), nil
}
// Capture
func (c *Client) InsertCapture(ctx context.Context, ce storecontract.CapturedEvent, retention time.Duration, maxEvents int) (int64, error) {
r, err := c.client.InsertCapture(ctx, &pb.InsertCaptureRequest{Capture: capturedEventProto(ce), RetentionSeconds: int64(retention.Seconds()), MaxEvents: int64(maxEvents)})
if err != nil {
return 0, unmapError(err)
}
return r.Id, nil
}
// ListCaptures calls StreamCaptures, not the deprecated unary ListCaptures
// RPC: a batch of large capture bodies in one unary response can exceed
// gRPC's 4MiB message cap (docs/prds/state-store-contract.md).
// PutConfigSnapshot publishes the dashboard's configuration projection. The
// server admits it on the administrative token only; a task-scoped grant
// cannot reach it (see TaskGrants).
func (c *Client) PutConfigSnapshot(ctx context.Context, snapshot storecontract.ConfigSnapshot) error {
_, err := c.client.PutConfigSnapshot(ctx, &pb.PutConfigSnapshotRequest{Snapshot: configSnapshotProto(snapshot)})
if err != nil {
return unmapError(err)
}
return nil
}
// ConfigSnapshot reads the published projection. found is false, with a nil
// error, before a daemon has published one.
func (c *Client) ConfigSnapshot(ctx context.Context) (storecontract.ConfigSnapshot, bool, error) {
reply, err := c.client.GetConfigSnapshot(ctx, &pb.GetConfigSnapshotRequest{})
if err != nil {
return storecontract.ConfigSnapshot{}, false, unmapError(err)
}
if !reply.Found {
return storecontract.ConfigSnapshot{}, false, nil
}
return configSnapshotValue(reply.Snapshot), true, nil
}
// PutChannelStatus publishes the channel state the hosting process observes.
// Administrative, like the config snapshot pair: the server admits it on the
// administrative token only, so a task-scoped grant cannot reach it.
func (c *Client) PutChannelStatus(ctx context.Context, channels []storecontract.ChannelStatus) error {
_, err := c.client.PutChannelStatus(ctx, &pb.PutChannelStatusRequest{Channels: channelStatusesProto(channels)})
if err != nil {
return unmapError(err)
}
return nil
}
// ChannelStatus reads every reported channel.
func (c *Client) ChannelStatus(ctx context.Context) ([]storecontract.ChannelStatus, error) {
reply, err := c.client.ListChannelStatus(ctx, &pb.ListChannelStatusRequest{})
if err != nil {
return nil, unmapError(err)
}
return channelStatusesValue(reply.Channels), nil
}
// PutApplyStatus reports what this process applied for one resource kind.
// Administrative, like the config snapshot pair: a task-scoped grant cannot
// reach it.
func (c *Client) PutApplyStatus(ctx context.Context, status storecontract.ApplyStatus) error {
_, err := c.client.PutApplyStatus(ctx, &pb.PutApplyStatusRequest{Status: applyStatusProto(status)})
if err != nil {
return unmapError(err)
}
return nil
}
// ListApplyStatus reads every process's report. An empty slice means nothing
// has reported yet, which is not an error.
func (c *Client) ListApplyStatus(ctx context.Context) ([]storecontract.ApplyStatus, error) {
reply, err := c.client.ListApplyStatus(ctx, &pb.ListApplyStatusRequest{})
if err != nil {
return nil, unmapError(err)
}
statuses := make([]storecontract.ApplyStatus, 0, len(reply.Statuses))
for _, status := range reply.Statuses {
statuses = append(statuses, applyStatusValue(status))
}
return statuses, nil
}
func (c *Client) ListCaptures(ctx context.Context, limit int) ([]storecontract.CapturedEvent, error) {
stream, err := c.client.StreamCaptures(ctx, &pb.StreamCapturesRequest{Limit: int64(limit)})
if err != nil {
return nil, unmapError(err)
}
var captures []storecontract.CapturedEvent
for {
r, err := stream.Recv()
if errors.Is(err, io.EOF) {
return captures, nil
}
if err != nil {
return nil, unmapError(err)
}
captures = append(captures, capturedEventValue(r.Capture))
}
}
// Mapping
func (c *Client) InsertMapping(ctx context.Context, m mapping.Mapping) (int64, error) {
r, err := c.client.InsertMapping(ctx, &pb.InsertMappingRequest{Mapping: mappingProto(m)})
if err != nil {
return 0, unmapError(err)
}
return r.Id, nil
}
func (c *Client) GetMapping(ctx context.Context, id int64) (*mapping.Mapping, error) {
r, err := c.client.GetMapping(ctx, &pb.GetMappingRequest{Id: id})
if err != nil {
return nil, unmapError(err)
}
if !r.Found {
return nil, nil
}
v := mappingValue(r.Mapping)
return &v, nil
}
func (c *Client) ListMappings(ctx context.Context) ([]mapping.Mapping, error) {
r, err := c.client.ListMappings(ctx, &pb.ListMappingsRequest{})
if err != nil {
return nil, unmapError(err)
}
return mapValues(r.Mappings, mappingValue), nil
}
func (c *Client) UpdateMapping(ctx context.Context, m mapping.Mapping) error {
_, err := c.client.UpdateMapping(ctx, &pb.UpdateMappingRequest{Mapping: mappingProto(m)})
return unmapError(err)
}
func (c *Client) DeleteMapping(ctx context.Context, id int64) error {
_, err := c.client.DeleteMapping(ctx, &pb.DeleteMappingRequest{Id: id})
return unmapError(err)
}
// Binding
func (c *Client) InsertBinding(ctx context.Context, b binding.Binding) (int64, error) {
r, err := c.client.InsertBinding(ctx, &pb.InsertBindingRequest{Binding: bindingProto(b)})
if err != nil {
return 0, unmapError(err)
}
return r.Id, nil
}
func (c *Client) GetBinding(ctx context.Context, id int64) (*binding.Binding, error) {
r, err := c.client.GetBinding(ctx, &pb.GetBindingRequest{Id: id})
if err != nil {
return nil, unmapError(err)
}
if !r.Found {
return nil, nil
}
v := bindingValue(r.Binding)
return &v, nil
}
func (c *Client) ListBindings(ctx context.Context) ([]binding.Binding, error) {
r, err := c.client.ListBindings(ctx, &pb.ListBindingsRequest{})
if err != nil {
return nil, unmapError(err)
}
return mapValues(r.Bindings, bindingValue), nil
}
func (c *Client) UpdateBinding(ctx context.Context, b binding.Binding) error {
_, err := c.client.UpdateBinding(ctx, &pb.UpdateBindingRequest{Binding: bindingProto(b)})
return unmapError(err)
}
func (c *Client) DeleteBinding(ctx context.Context, id int64) error {
_, err := c.client.DeleteBinding(ctx, &pb.DeleteBindingRequest{Id: id})
return unmapError(err)
}
func (c *Client) ApproveBinding(ctx context.Context, id int64) error {
_, err := c.client.ApproveBinding(ctx, &pb.ApproveBindingRequest{Id: id})
return unmapError(err)
}
// Dispatch
func (c *Client) ArmedBindingsForSource(ctx context.Context, source string) ([]binding.Binding, error) {
r, err := c.client.ArmedBindingsForSource(ctx, &pb.ArmedBindingsForSourceRequest{Source: source})
if err != nil {
return nil, unmapError(err)
}
return mapValues(r.Bindings, bindingValue), nil
}
func (c *Client) RecordDispatch(ctx context.Context, bindingID, bindingVersion, captureID, taskID int64) error {
_, err := c.client.RecordDispatch(ctx, &pb.RecordDispatchRequest{BindingId: bindingID, BindingVersion: bindingVersion, CaptureId: captureID, TaskId: taskID})
return unmapError(err)
}
// Playbook dispatch
func (c *Client) RecordPlaybookDispatch(ctx context.Context, playbookID, playbookVersion, eventID, actionID string) error {
_, err := c.client.RecordPlaybookDispatch(ctx, &pb.RecordPlaybookDispatchRequest{PlaybookId: playbookID, PlaybookVersion: playbookVersion, EventId: eventID, ActionId: actionID})
return unmapError(err)
}
func (c *Client) DeletePlaybookDispatches(ctx context.Context, playbookID string) error {
_, err := c.client.DeletePlaybookDispatches(ctx, &pb.DeletePlaybookDispatchesRequest{PlaybookId: playbookID})
return unmapError(err)
}
// ListUndispatchedCaptures calls StreamUndispatchedCaptures; see ListCaptures
// above.
func (c *Client) ListUndispatchedCaptures(ctx context.Context, sources []string, limit int) ([]storecontract.CapturedEvent, error) {
stream, err := c.client.StreamUndispatchedCaptures(ctx, &pb.StreamUndispatchedCapturesRequest{Sources: sources, Limit: int64(limit)})
if err != nil {
return nil, unmapError(err)
}
var captures []storecontract.CapturedEvent
for {
r, err := stream.Recv()
if errors.Is(err, io.EOF) {
return captures, nil
}
if err != nil {
return nil, unmapError(err)
}
captures = append(captures, capturedEventValue(r.Capture))
}
}
// BindingTaskCreator
func (c *Client) EnqueueBindingTask(ctx context.Context, owner, repo, title, body, wf, identity string, bindingID int64, bindingVersion int) (*task.Task, error) {
r, err := c.client.EnqueueBindingTask(ctx, &pb.EnqueueBindingTaskRequest{Owner: owner, Repo: repo, Title: title, Body: body, Workflow: wf, Identity: identity, BindingId: bindingID, BindingVersion: int64(bindingVersion)})
if err != nil {
return nil, unmapError(err)
}
return taskValue(r.Task), nil
}
// Task log
// TaskLog reads one task attempt's decoded log over the wire. found=false with
// a nil error is the attempt-has-no-log answer; a process with no reader at
// all comes back as an unavailable error, not as an empty page, so a caller
// can tell the two apart.
func (c *Client) TaskLog(ctx context.Context, taskID int64, attempt int, q logging.Query) (logging.TaskLogPage, error) {
r, err := c.client.ReadTaskLog(ctx, taskLogRequestProto(taskID, attempt, q))
if err != nil {
return logging.TaskLogPage{}, unmapError(err)
}
if !r.Found {
return logging.TaskLogPage{
Entries: []logging.Entry{},
Components: []string{},
}, nil
}
// Both collections are normalised: protobuf decodes an empty `repeated`
// field to nil, and a nil slice marshals to JSON null rather than an empty
// list, so the field's type would otherwise depend on whether it happened
// to have contents. mapValues owns the entries side.
components := r.Components
if components == nil {
components = []string{}
}
return logging.TaskLogPage{
Entries: mapValues(r.Entries, taskLogEntryValue),
Truncated: r.Truncated,
File: r.File,
Found: true,
Components: components,
}, nil
}
// TaskLogContent streams one attempt's log verbatim into w, for a download.
// found is false, with a nil error, when the attempt has no log file.
func (c *Client) TaskLogContent(ctx context.Context, taskID int64, attempt int, w io.Writer) (bool, error) {
stream, err := c.client.StreamTaskLogContent(ctx, &pb.StreamTaskLogContentRequest{TaskId: taskID, Attempt: int64(attempt)})
if err != nil {
return false, unmapError(err)
}
found := false
for {
r, err := stream.Recv()
if errors.Is(err, io.EOF) {
return found, nil
}
if err != nil {
return found, unmapError(err)
}
found = found || r.Found
if len(r.Chunk) == 0 {
continue
}
if _, err := w.Write(r.Chunk); err != nil {
return found, err
}
}
}
func derefTasks(in []*pb.Task) []task.Task {
if in == nil {
return nil
}
out := make([]task.Task, len(in))
for i, t := range in {
out[i] = *taskValue(t)
}
return out
}