Files
archie/internal/domain/binding/binding.go
T
sam ed1557c12e feat(edastore)!: move event capture and bindings onto PocketBase collections
The event-capture tables (captures, mappings, bindings, binding_dispatches,
playbook_dispatches) now live in PocketBase-owned collections and their ids
are opaque record ids rather than autoincrement integers. The task lifecycle
stays on SQLite: tasks/transitions/events carry FIFO claim ordering, id-cursor
pagination and the task-grant map, none of which gain anything from being
hand-editable. binding_dispatches.task_id is the single seam and stays an
integer addressing that store.

BREAKING: CapturedEvent.Id, Mapping.Id, Binding.Id and Binding.MappingId are
strings on the wire, as are the ids in the capture/mapping/binding requests.
RecordDispatchRequest.task_id is deliberately unchanged.

What the collections buy, beyond storage: a payload nobody has modelled yet is
inspectable, a mapping is editable at runtime, and a binding's relation to its
mapping is enforced. The old schema declared no FOREIGN KEY on that link, so a
dangling mapping_id was previously possible and is now refused.

Behaviour preserved deliberately, each recovered from the SQLite version
rather than reimplemented from memory:
  - draft -> pending_approval -> armed, with approval only from
    pending_approval and an edit always returning a binding for re-approval
  - one binding per source, guarded on insert, update and approve
  - an empty secret on update keeps the stored one, so an edit form that does
    not echo it back cannot silently disarm a binding
  - ErrMappingNotFound / ErrBindingNotFound on a missing delete target
  - sentinels are re-exported from storecontract, never redefined: staterpc
    matches on exact canonical message to rehydrate them, so a second
    definition would break errors.Is across the wire invisibly

Two implementation notes worth keeping:
  - at-most-once dispatch is now a unique index rather than INSERT OR IGNORE.
    Only the unique-violation maps to ErrAlreadyDispatched; any other save
    error is returned, because treating them all as "already recorded" would
    turn the ledger into a silent at-least-once dispatcher.
  - captures store received_at themselves at nanosecond precision in a
    fixed-width layout. PocketBase autodates are millisecond and record ids
    are random, so same-millisecond captures would otherwise order
    arbitrarily; the old store got insertion order free from autoincrement.
  - ListUndispatchedCaptures is raw SQL: the anti-join is a subquery and
    PocketBase's filter DSL is not SQL. A read fires no hooks either way.

Adds tool_calls, which had no persistence at all: tool calls only ever reached
the on-disk task log, readable as text but never queryable or watchable.
Nothing writes it yet.

The binding secret cipher moves with the bindings it protects.
2026-09-23 02:19:28 +10:00

153 lines
5.8 KiB
Go

// Package binding owns the playbook binding vocabulary: the matcher +
// mapping + workflow + state-machine entity that turns a captured webhook
// into an archie task. See docs/prds/webhook-intake-security.md and
// docs/prds/payload-field-mapping.md.
package binding
import (
"fmt"
"strings"
"time"
)
// Status is the binding lifecycle state. Mirrors telegram's
// dangerousAction / pendingApproval shape: armed is the only state that
// evaluates against incoming events; any edit drops armed back to
// pending_approval; only an explicit Approve call moves
// pending_approval -> armed.
type Status string
const (
StatusDraft Status = "draft"
StatusPendingApproval Status = "pending_approval"
StatusArmed Status = "armed"
)
// Matcher decides which captured events a binding applies to. Source is
// the only dimension today -- the path segment the sender POSTs to
// (e.g. "sentry"). Extend with additional predicates if a use case
// demands it; the storage column is plain TEXT so widening is
// non-breaking.
type Matcher struct {
Source string `json:"source"`
}
// Binding is the runtime-editable entity that ties a matcher, a payload
// mapping, and a workflow together. Bindings live in the store, not in
// config.toml, so operators can author them from the dashboard while the
// daemon runs.
//
// Version is bumped on every UpdateBinding so a later edit cannot
// silently rewrite the historical provenance of a task that already
// fired. Secret is the HMAC-SHA256 shared secret a sender must sign with
// for an event to be marked authenticated; it is never returned by
// GET handlers.
type Binding struct {
ID string `json:"id"`
Name string `json:"name"`
Matcher Matcher `json:"matcher"`
MappingID string `json:"mapping_id"`
Workflow string `json:"workflow"`
// Owner and Repo pin a binding to a specific configured repo, so a
// multi-repo deployment can dispatch correctly. Both empty means "no
// pin" -- resolveBindingRepo falls back to the single-configured-repo
// behaviour that predates this field. Setting only one is invalid
// (Validate rejects it): a pin is a complete owner/repo pair or not a
// pin at all, never a half-guess.
Owner string `json:"owner,omitempty"`
Repo string `json:"repo,omitempty"`
Version int `json:"version"`
Status Status `json:"status"`
Secret string `json:"secret,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
// minSecretLen is the floor for an acceptable shared secret. A trivially
// short secret makes accidental binding to a known HMAC trivial; the
// floor is chosen so a one-character typo cannot arm.
const minSecretLen = 16
// Validate checks a binding is well-formed before it is newly persisted.
// A non-empty Name, a non-empty Matcher.Source, a positive MappingID, a
// non-empty Workflow, and a sufficiently long Secret are all required.
// Workflow existence is checked at the API/store layer because the domain
// package does not import the workflow registry. Use ValidateForUpdate
// instead when editing an existing binding, where an empty Secret is a
// meaningful "keep the current one," not a missing value.
func (b Binding) Validate() error {
if err := b.validateCommon(); err != nil {
return err
}
if len(b.Secret) < minSecretLen {
return fmt.Errorf("binding: secret must be at least %d bytes", minSecretLen)
}
return nil
}
// ValidateForUpdate is Validate for the edit path: every other field is
// checked identically, but Secret is only length-checked when the caller
// actually supplied one. UpdateBinding's own store-layer contract already
// treats an empty Secret as "preserve the existing one" (COALESCE against
// NULLIF) -- rejecting that here at the validation gate before the store
// ever sees it would make the store's own documented behavior
// unreachable. A non-empty Secret (a genuine change) is still held to the
// same floor Validate enforces.
func (b Binding) ValidateForUpdate() error {
if err := b.validateCommon(); err != nil {
return err
}
if b.Secret != "" && len(b.Secret) < minSecretLen {
return fmt.Errorf("binding: secret must be at least %d bytes", minSecretLen)
}
return nil
}
func (b Binding) validateCommon() error {
if strings.TrimSpace(b.Name) == "" {
return fmt.Errorf("binding: name is required")
}
if strings.TrimSpace(b.Matcher.Source) == "" {
return fmt.Errorf("binding: matcher.source is required")
}
if strings.TrimSpace(b.MappingID) == "" {
return fmt.Errorf("binding: mapping_id is required")
}
if strings.TrimSpace(b.Workflow) == "" {
return fmt.Errorf("binding: workflow is required")
}
if (b.Owner == "") != (b.Repo == "") {
return fmt.Errorf("binding: owner and repo must both be set or both be empty")
}
return nil
}
// Matches reports whether the given captured event would match this
// binding's matcher. The Authenticated clause encodes t2db.5 point 1 --
// an unauthenticated event can never trigger a binding, no matter how
// well it would otherwise match.
//
// Note: the caller is expected to be the dispatch loop or the capture
// intake receiver, both of which receive a CapturedEvent with the
// Authenticated flag already set by HMAC verification. Matches is pure
// and has no I/O.
func (m Matcher) Matches(source string, authenticated bool) bool {
if !authenticated {
return false
}
return m.Source == source
}
// Normalize clamps an arbitrary string into a recognised Status, falling
// back to StatusDraft for any unknown value. The DB CHECK constraint
// already rejects bad strings at write time; Normalize is the API-edge
// guard for inputs that arrive before they ever reach the store.
func Normalize(s Status) Status {
switch s {
case StatusDraft, StatusPendingApproval, StatusArmed:
return s
default:
return StatusDraft
}
}