The view's tools already read indexer_pending's {held: [{branch, source, why, since}]} through
view.DecodeHeldTakeIns at the joined base; the take-in package's earlier PendingAnswer,
PendingWait and DecodePendingAnswer, read by nothing since, go with their test.
Builds: design 47 H H-A-102, H-A-97
Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
235 lines
10 KiB
Go
235 lines
10 KiB
Go
// Package takein is the indexer's take-in contract (novox/hq ADR 0633 §1, §5): the events it publishes on its own stream
|
|
// `take-in` while a source revision waits (its message unread, lost or held for room) or a delivery group is gathered, their keys, and the
|
|
// answer of its tool indexer_pending. The indexer writes them; the watchman and the view read them. It is the indexer's
|
|
// own package: one module owns these types, so they live with it and not in mesh-sdk (the operator, 2026-11-04).
|
|
package takein
|
|
|
|
import (
|
|
"encoding/json"
|
|
"fmt"
|
|
"reflect"
|
|
"strings"
|
|
"time"
|
|
|
|
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshdeliveryclient"
|
|
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
|
|
"git.novox.be/novox/mesh-sdk/go/keys"
|
|
)
|
|
|
|
// Merge is one merge a take-in event or a wait holds: the repository as `<owner>/<name>`, its pull request and the
|
|
// merge commit the forge made of it.
|
|
type Merge struct {
|
|
Repository string `json:"repository"`
|
|
Number int `json:"number"`
|
|
Merge string `json:"merge"`
|
|
}
|
|
|
|
// checkRepository refuses a repository that is not `<owner>/<name>`: one slash, neither part empty.
|
|
func checkRepository(repository string) error {
|
|
owner, name, ok := strings.Cut(repository, "/")
|
|
if !ok || owner == "" || name == "" || strings.Contains(name, "/") {
|
|
return fmt.Errorf("delivery: the repository %q is not <owner>/<name>, with exactly one slash", repository)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// decode reads a value of keys.Version, refusing another or none with keys.ErrUnknownVersion, as mesh-sdk
|
|
// delivery's values are read.
|
|
func decode(data []byte, into any) error {
|
|
var probe struct {
|
|
V *int `json:"v"`
|
|
}
|
|
if err := json.Unmarshal(data, &probe); err != nil {
|
|
return fmt.Errorf("delivery: value is not JSON: %w", err)
|
|
}
|
|
if probe.V == nil || *probe.V != keys.Version {
|
|
return fmt.Errorf("%w: this reader reads %d", keys.ErrUnknownVersion, keys.Version)
|
|
}
|
|
if err := json.Unmarshal(data, into); err != nil {
|
|
return fmt.Errorf("delivery: value does not fit its shape: %w", err)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// The take-in events (novox/hq ADR 0633 §1, §5): the indexer's ordinary events, `take-in.pending` and `take-in.taken`, on
|
|
// the path its other events take (the module's event subject; its manifest's emits), with no stream of its own. A wait
|
|
// starts with `take-in.pending` and ends with `take-in.taken`, whoever ended it (the named indexer, a revert, a hand
|
|
// take-in or a drop); the wait's key is in the body (TakeIn.Key), since an emitted event names one event and a key is
|
|
// no event name. A reader that starts later asks the waits of indexer_pending, not a replay.
|
|
const (
|
|
TakeInPending = "pending"
|
|
TakeInTaken = "taken"
|
|
// TakeInPendingEvent and TakeInTakenEvent are the two events' names, relative to the indexer.
|
|
TakeInPendingEvent = "take-in." + TakeInPending
|
|
TakeInTakenEvent = "take-in." + TakeInTaken
|
|
)
|
|
|
|
// What waits in a take-in event: a source revision for the indexer build it names, or a delivery group for its end.
|
|
const (
|
|
TakeInRevision = "revision"
|
|
TakeInGroup = "group"
|
|
)
|
|
|
|
// PendingKey is the key of one held merge in the indexer's pending state, and the key a revision's take-in events
|
|
// carry (its oldest merge's): `m.<the merge's stream sequence, 20 digits>`, so the key order is the merge order.
|
|
func PendingKey(seq uint64) string { return fmt.Sprintf("m.%020d", seq) }
|
|
|
|
// GroupTakeInKey is the key a group's take-in events carry while it is gathered: `g.<group>`, with every character a
|
|
// bus subject cannot carry (a space, `*`, `>`) written `_`. The event's body names the group exactly.
|
|
func GroupTakeInKey(group string) string {
|
|
return "g." + strings.Map(func(r rune) rune {
|
|
if r == '*' || r == '>' || r <= ' ' || r == 0x7f {
|
|
return '_'
|
|
}
|
|
return r
|
|
}, group)
|
|
}
|
|
|
|
// TakeInEvent is the name of the take-in event of the given kind: `take-in.<pending|taken>`.
|
|
func TakeInEvent(kind string) (string, error) {
|
|
if kind != TakeInPending && kind != TakeInTaken {
|
|
return "", fmt.Errorf("delivery: the take-in kind %q is not pending or taken", kind)
|
|
}
|
|
return "take-in." + kind, nil
|
|
}
|
|
|
|
// ParseTakeInEvent is the inverse of TakeInEvent: the kind of a take-in event's name.
|
|
func ParseTakeInEvent(event string) (kind string, err error) {
|
|
k, ok := strings.CutPrefix(event, "take-in.")
|
|
if !ok {
|
|
return "", fmt.Errorf("delivery: %q is not a take-in event, take-in.<pending|taken>", event)
|
|
}
|
|
if _, err := TakeInEvent(k); err != nil {
|
|
return "", fmt.Errorf("delivery: %q is not a take-in event: %w", event, err)
|
|
}
|
|
return k, nil
|
|
}
|
|
|
|
func checkTakeInKey(key string) error {
|
|
if !strings.HasPrefix(key, "m.") && !strings.HasPrefix(key, "g.") {
|
|
return fmt.Errorf("delivery: the take-in key %q is neither m.<sequence> nor g.<group>", key)
|
|
}
|
|
for _, tok := range strings.Split(key, ".") {
|
|
if tok == "" || strings.ContainsAny(tok, "*> \t\r\n") {
|
|
return fmt.Errorf("delivery: the take-in key %q is not a bus subject's tokens", key)
|
|
}
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// TakeIn is the body of a take-in event. Kind is the event's kind and Key its key. What says what waits: a revision
|
|
// (Key its oldest merge's PendingKey) or a group being gathered (Key its
|
|
// GroupTakeInKey, Members every approved member with its head, Merges the members held so far). Merges are the merges
|
|
// it holds, oldest first; Since is when the wait began. A `taken` event names the same once the wait ended; By and Why
|
|
// name a hand act (a hand take-in, or a drop, Dropped), and are carried by nothing else.
|
|
type TakeIn struct {
|
|
V int `json:"v"`
|
|
Kind string `json:"kind"`
|
|
Key string `json:"key"`
|
|
What string `json:"what"`
|
|
Merges []Merge `json:"merges"`
|
|
Group string `json:"group,omitempty"`
|
|
Members []meshdeliveryclient.Head `json:"members,omitempty"`
|
|
WaitsFor string `json:"waits-for,omitempty"`
|
|
Since time.Time `json:"since"`
|
|
By string `json:"by,omitempty"`
|
|
Why string `json:"why,omitempty"`
|
|
Dropped bool `json:"dropped,omitempty"`
|
|
// Lost are the keys of merges whose message the forge bridge's stream no longer holds: they are not taken in, and the
|
|
// revision waits until indexer_drop_pending drops them (issue 1585).
|
|
Lost []string `json:"lost,omitempty"`
|
|
// Refused is why the revision is refused: the cycle with a build edge its catalog graph would hold (design 47 G §49). The
|
|
// revision waits, and says why here, as it says what it lost.
|
|
Refused string `json:"refused,omitempty"`
|
|
// Branch, Source and Entries are what a take-in took in (design 47 G §476, §493, §648): the watched branch, the source
|
|
// revision it makes of that branch, and one entry per module it wrote. Every taken event of one take-in carries the same;
|
|
// a taken event that ends a wait without a take-in (a group's end, a drop) carries none and starts no pipeline.
|
|
Branch string `json:"branch,omitempty"`
|
|
Source int64 `json:"source,omitempty"`
|
|
// Revision is the catalog graph revision of the branch the take-in made (A-448): the pipelines of its entries start at it.
|
|
Revision int64 `json:"revision,omitempty"`
|
|
Entries []meshcatalog.TakeInEntry `json:"entries,omitempty"`
|
|
}
|
|
|
|
func (t TakeIn) check() error {
|
|
if _, err := TakeInEvent(t.Kind); err != nil {
|
|
return err
|
|
}
|
|
if err := checkTakeInKey(t.Key); err != nil {
|
|
return err
|
|
}
|
|
if len(t.Merges) == 0 {
|
|
return fmt.Errorf("delivery: the take-in event %s names no merge", t.Key)
|
|
}
|
|
for _, m := range t.Merges {
|
|
if err := checkRepository(m.Repository); err != nil {
|
|
return err
|
|
}
|
|
if m.Merge == "" {
|
|
return fmt.Errorf("delivery: the take-in event %s names a merge of %s without its commit", t.Key, m.Repository)
|
|
}
|
|
}
|
|
if t.Since.IsZero() {
|
|
return fmt.Errorf("delivery: the take-in event %s does not say since when it waits", t.Key)
|
|
}
|
|
switch t.What {
|
|
case TakeInRevision:
|
|
if !strings.HasPrefix(t.Key, "m.") {
|
|
return fmt.Errorf("delivery: a revision's take-in key is its oldest merge's m.<sequence>, not %q", t.Key)
|
|
}
|
|
if t.Kind == TakeInPending && len(t.Lost) == 0 && t.Refused == "" {
|
|
return fmt.Errorf("delivery: a pending revision %s names the merges it lost or its refusal", t.Key)
|
|
}
|
|
case TakeInGroup:
|
|
if t.Group == "" {
|
|
return fmt.Errorf("delivery: a group's take-in event %s names its group", t.Key)
|
|
}
|
|
if t.Key != GroupTakeInKey(t.Group) {
|
|
return fmt.Errorf("delivery: the take-in key of the group %q is %s, not %s", t.Group, GroupTakeInKey(t.Group), t.Key)
|
|
}
|
|
if t.WaitsFor != "" {
|
|
return fmt.Errorf("delivery: a group being gathered waits for its end, not for an indexer build")
|
|
}
|
|
default:
|
|
return fmt.Errorf("delivery: a take-in event's what %q is not revision or group", t.What)
|
|
}
|
|
if t.Kind != TakeInTaken && (t.By != "" || t.Why != "" || t.Dropped) {
|
|
return fmt.Errorf("delivery: only a taken event names the hand act that ended a wait")
|
|
}
|
|
if t.Kind != TakeInTaken && (t.Source != 0 || len(t.Entries) > 0) {
|
|
return fmt.Errorf("delivery: only a taken event names the source revision and the entries taken in")
|
|
}
|
|
if len(t.Entries) > 0 && (t.Branch == "" || t.Source <= 0) {
|
|
return fmt.Errorf("delivery: the taken event %s names entries without its watched branch and source revision", t.Key)
|
|
}
|
|
if (t.Why != "" || t.Dropped) && t.By == "" {
|
|
return fmt.Errorf("delivery: a hand act's take-in event names who acted (by)")
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// EncodeTakeIn is t as JSON at Version; it refuses what its kind and what do not carry.
|
|
func EncodeTakeIn(t TakeIn) ([]byte, error) {
|
|
if err := t.check(); err != nil {
|
|
return nil, err
|
|
}
|
|
t.V = keys.Version
|
|
return json.Marshal(t)
|
|
}
|
|
|
|
// DecodeTakeIn reads a take-in event's body; it refuses an unknown version (ErrUnknownVersion) and what EncodeTakeIn
|
|
// refuses.
|
|
func DecodeTakeIn(data []byte) (TakeIn, error) {
|
|
var t TakeIn
|
|
if err := decode(data, &t); err != nil {
|
|
return TakeIn{}, err
|
|
}
|
|
if err := t.check(); err != nil {
|
|
return TakeIn{}, err
|
|
}
|
|
return t, nil
|
|
}
|
|
|
|
// SameTakeIn says whether two take-in bodies are the same value.
|
|
func SameTakeIn(a, b TakeIn) bool { return reflect.DeepEqual(a, b) }
|