Files
archie/internal/domain/taskactions/service.go
T

309 lines
11 KiB
Go

// Package taskactions owns operator task mutations shared by chat and dashboard.
package taskactions
import (
"context"
"errors"
"fmt"
"strings"
"github.com/samcharles93/archie-core/internal/domain/identity"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/taskstate"
)
var (
ErrNotFound = errors.New("task not found")
ErrConflict = errors.New("task action conflict")
ErrUnavailable = errors.New("runtime task control is unavailable")
)
// Task is the state needed to authorize and apply an operator action.
type Task struct {
ID int64
Owner, Repo, Identity, Status, Stage, ParkReason string
IssueNumber, RetryCount int
ForgeBacked bool
// Attempt is the run the operator acted on. It is stamped onto the event
// this action records so an intervention is attributable to the run it
// changed course -- without it a retry or a stop is indistinguishable
// between attempts on the timeline.
Attempt int
}
// Actor is the identity that performed an action, and the principal whose
// authority permitted it.
//
// The two are separate fields because an agent acting under a person's standing
// approval is not the same fact as a person acting: a record that collapsed
// them would answer "who approved this" with the wrong identity. An empty
// Principal means UNATTRIBUTED -- no authority was recorded, which is a
// different fact from the actor authorising itself.
type Actor struct {
Identity identity.IdentityID
Kind identity.Kind
Principal identity.IdentityID
}
// ActorFor builds an actor from the identity a credential resolved to. The kind
// travels with the actor so an event can record that an agent acted without a
// consumer having to resolve the identity to find out.
func ActorFor(value identity.Identity) Actor {
return Actor{Identity: value.ID, Kind: value.Kind}
}
// ActorFromScope builds an actor for a caller whose identity archie knows but did
// not derive from a credential: a chat channel's bound identity. The kind is not
// known here, so the action is recorded as an agent's rather than a person's, and
// the authority it acted under is recorded separately when it is known.
func ActorFromScope(id string) Actor {
return Actor{Identity: identity.IdentityID(id)}
}
// AuthorisedBy records where an action's authority came from.
func (a Actor) AuthorisedBy(principal identity.IdentityID) Actor {
a.Principal = principal
return a
}
// Human reports whether a person performed the action. Only a human's action is
// recorded as a human's: the event kind describes the actor.
func (a Actor) Human() bool { return a.Kind == identity.KindUser }
// Attributed reports whether the action is attributed to an identity. An action
// with no identity is still recorded -- refusing it would hide the action from
// the timeline -- but its record claims nothing about who performed it, and its
// kind says so.
func (a Actor) Attributed() bool { return strings.TrimSpace(string(a.Identity)) != "" }
// describe renders the attribution for a human reading a task timeline.
func (a Actor) describe(verb string) string {
if !a.Attributed() {
return verb + " with no recorded actor"
}
text := verb + " by " + string(a.Identity)
if a.Kind != "" {
text += " (" + string(a.Kind) + ")"
}
if a.Principal != "" {
return text + ", authorised by " + string(a.Principal)
}
return text + ", no authorising principal"
}
// approvedKind and rejectedKind name what happened and who did it. There is no
// single kind for an approval: an agent's approval recorded as a human's is the
// falsehood this trio exists to prevent, and an action with no verified actor
// is recorded as a task-level event rather than credited to anyone.
func approvedKind(actor Actor) string {
switch {
case actor.Human():
return events.KindHumanApproved
case actor.Attributed():
return events.KindAgentApproved
default:
return events.KindTaskApproved
}
}
func rejectedKind(actor Actor) string {
switch {
case actor.Human():
return events.KindHumanRejected
case actor.Attributed():
return events.KindAgentRejected
default:
return events.KindTaskRejected
}
}
type Store interface {
TaskByID(context.Context, int64) (*Task, error)
Transition(context.Context, int64, string, string, string) error
Requeue(context.Context, int64, string, string) error
RetryTask(context.Context, int64, string, string) error
ArchiveTask(context.Context, int64, string, events.Event) (int64, error)
InsertEvent(context.Context, events.Event) (int64, error)
}
// Service runs in the daemon, which owns execution cancellation and events.
type Service struct {
Store Store
MaxRetries func(*Task) int
CancelTask func(int64) bool
CloseIssue func(context.Context, string, string, int, string) error
RemoveLogs func(int64) error
Publish func(events.Event)
Warn func(string, ...any)
}
// Apply scopes chat requests to an identity. A nil scope denotes a caller
// authenticated across identities, which is the dashboard's own credential;
// scope limits which task a chat identity may act on, and never says who acted.
//
// The actor is not derived from scope: scope is which tasks a caller may touch,
// actor is who touched one, and the two are only equal by coincidence.
func (s Service) Apply(ctx context.Context, scope *string, actor Actor, id int64, action taskstate.Action) error {
task, err := s.Store.TaskByID(ctx, id)
if err != nil {
return err
}
if task == nil {
return fmt.Errorf("task %d: %w", id, ErrNotFound)
}
if scope != nil && task.Identity != *scope {
return fmt.Errorf("task %d belongs to %q, not %q", id, task.Identity, *scope)
}
if err := taskstate.CheckAction(task.Status, action); err != nil {
return fmt.Errorf("%w: %w", ErrConflict, err)
}
mutation, err := s.apply(ctx, task, actor, action)
if err != nil {
return err
}
if mutation.verb != "" && task.ForgeBacked {
s.closeRejectedIssue(ctx, task, actor, mutation.verb)
}
s.emit(ctx, mutation.event)
return nil
}
type outcome struct {
event events.Event
verb string
}
// apply performs the store mutation for one action and returns the event to
// record alongside it. Errors from the store are returned unwrapped: the
// caller maps them to a response, and the rules-level errors (ErrConflict)
// were already checked above.
func (s Service) apply(ctx context.Context, task *Task, actor Actor, action taskstate.Action) (outcome, error) {
o := outcome{event: s.attributed(task, actor)}
switch action {
case taskstate.ActionApprove:
err := s.Store.Requeue(ctx, task.ID, "waiting_human", "implement")
o.event.Kind, o.event.Detail = approvedKind(actor), actor.describe("approved")
return o, err
case taskstate.ActionRetry:
return s.applyRetry(ctx, task, actor, o)
case taskstate.ActionStop:
return s.applyStop(ctx, task, actor, o)
case taskstate.ActionReject:
o.event.Kind, o.event.Detail, o.verb = rejectedKind(actor), actor.describe("rejected"), "rejected"
if task.Status == "running" && s.CancelTask != nil {
s.CancelTask(task.ID)
}
return o, s.Store.Transition(ctx, task.ID, task.Status, "closed_wont_do", actor.describe("declined"))
case taskstate.ActionCancel, taskstate.ActionAbandon:
return s.applyCancelOrAbandon(ctx, task, action, actor, o)
case taskstate.ActionArchive:
return s.applyArchive(ctx, task, actor, o)
default:
return o, fmt.Errorf("unsupported task action %q", action)
}
}
// attributed builds the event skeleton every action carries: the task, the run
// and both identities. Every event this service records passes through here, so
// no action can be recorded without its attribution.
func (s Service) attributed(task *Task, actor Actor) events.Event {
return events.Event{
TaskID: task.ID,
Repo: task.Owner + "/" + task.Repo,
Issue: task.IssueNumber,
Attempt: task.Attempt,
ActorID: string(actor.Identity),
ActorKind: string(actor.Kind),
PrincipalID: string(actor.Principal),
}
}
func (s Service) applyRetry(ctx context.Context, task *Task, actor Actor, o outcome) (outcome, error) {
limit := 0
if s.MaxRetries != nil {
limit = s.MaxRetries(task)
}
if limit > 0 && task.RetryCount >= limit {
reason := fmt.Sprintf("max retries reached (%d/%d)", task.RetryCount, limit)
if err := s.Store.Transition(ctx, task.ID, "parked", "dead", reason); err != nil {
s.warn("transition to dead failed", "task", task.ID, "err", err)
} else {
o.event.Kind, o.event.Detail = events.KindTaskDead, reason
s.emit(ctx, o.event)
}
return o, fmt.Errorf("%w: %s", ErrConflict, reason)
}
err := s.Store.RetryTask(ctx, task.ID, "parked", "")
o.event.Kind, o.event.Detail = events.KindTaskRetried, actor.describe("retried")
o.event.Data = map[string]any{"retry_count": task.RetryCount + 1, "previous_stage": task.Stage, "previous_reason": task.ParkReason}
return o, err
}
func (s Service) applyStop(ctx context.Context, task *Task, actor Actor, o outcome) (outcome, error) {
if s.CancelTask == nil {
return o, ErrUnavailable
}
o.event.Kind, o.event.Detail = events.KindTaskStopped, actor.describe("stopped")+"; recoverable work remains parked"
if !s.CancelTask(task.ID) {
o.event.Detail = "no active execution was found; recoverable work was parked, " + actor.describe("stopped")
}
return o, s.Store.Transition(ctx, task.ID, "running", "parked", o.event.Detail)
}
func (s Service) applyCancelOrAbandon(ctx context.Context, task *Task, action taskstate.Action, actor Actor, o outcome) (outcome, error) {
if action == taskstate.ActionAbandon {
// Abandoning ends archie's run, not the issue: no verb, so the issue
// stays open for a human.
o.event.Kind, o.event.Detail = events.KindTaskAbandoned, actor.describe("abandoned")
return o, s.Store.Transition(ctx, task.ID, "parked", "closed_wont_do", o.event.Detail)
}
o.event.Kind, o.event.Detail, o.verb = events.KindTaskCancelled, actor.describe("cancelled"), "cancelled"
return o, s.Store.Transition(ctx, task.ID, "queued", "closed_wont_do", o.event.Detail)
}
func (s Service) applyArchive(ctx context.Context, task *Task, actor Actor, o outcome) (outcome, error) {
o.event.Kind, o.event.Detail = events.KindTaskArchiveRequested, actor.describe("archive requested")
id, err := s.Store.ArchiveTask(ctx, task.ID, task.Status, o.event)
if err != nil {
return o, err
}
o.event.ID = id
if s.RemoveLogs != nil {
if cleanupErr := s.RemoveLogs(task.ID); cleanupErr != nil {
s.warn("task log cleanup failed", "task", task.ID, "err", cleanupErr)
}
}
return o, nil
}
func (s Service) closeRejectedIssue(ctx context.Context, task *Task, actor Actor, verb string) {
if s.CloseIssue == nil {
s.warn("task rejected but no forge is wired; the issue stays open and will be re-polled", "task", task.ID)
return
}
comment := fmt.Sprintf("Closing: this task was %s in archie (%s). Reopen the issue to have archie pick it up again.", verb, actor.describe("actioned"))
if err := s.CloseIssue(ctx, task.Owner, task.Repo, task.IssueNumber, comment); err != nil {
s.warn("closing rejected issue failed; it stays open and will be re-polled", "task", task.ID, "err", err)
}
}
func (s Service) emit(ctx context.Context, e events.Event) {
if e.ID == 0 {
id, err := s.Store.InsertEvent(ctx, e)
if err != nil {
s.warn("operator activity persistence failed", "kind", e.Kind, "task", e.TaskID, "err", err)
} else {
e.ID = id
}
}
if s.Publish != nil {
s.Publish(e)
}
}
func (s Service) warn(msg string, args ...any) {
if s.Warn != nil {
s.Warn(msg, args...)
}
}