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.
153 lines
5.8 KiB
Go
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
|
|
}
|
|
}
|