Files
archie/internal/infrastructure/staterpc/client.go
T
sam f38e1a30c8 feat(statestore): carry control-plane apply status on the store contract
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.
2026-09-21 15:44:31 +10:00

536 lines
18 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.ConfigSnapshotStore = (*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
}
// 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)
}
// 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
}