Files
mesh-delivery/modules/mesh-delivery-indexer/internal/index/pins.go
T
jschoubben cf93d30150 Names N3 (indexer): the indexer names its own buckets from its credential's module
Its 26 `<Module>_<state>` bucket constants (candidates, manifests, verdicts, packages, taken, the
control records, pins, pending and the rest), its consumers, findings and first views were named
from the constant Module; they are now index.Bucket(cred.Module, <state>), and its words name
the state where they named the bucket.

Builds: design 47 G A-296

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 19:18:56 +01:00

576 lines
21 KiB
Go

package index
import (
"context"
"encoding/json"
"errors"
"fmt"
"slices"
"sort"
"strconv"
"strings"
"time"
mcc "git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshconditionsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/process"
)
// The indexer keeps the records pinning each catalog graph revision and removes a revision only on an event (design 47 G §153,
// §178, §189, §215, §216, §579, A-169, A-171): its state pins holds one key per revision, `<branch>.<revision>` (the watched branch
// and the revision's number, the branch escaped as a name is), whose value lists the delivery record ids that pin it, and two more
// keys, `made` (written once, create-only, when the state is first used) and `pins-stated` (the `at` of the newest applied event of
// that name). Pins count only once a pins-stated later than made is applied.
const (
// PinsState is the state's name; PinsCapMiB is its cap in the manifest (about 1,800 keys of about 0.2 KiB).
PinsState = "pins"
PinsHistory = 1
PinsCapMiB = 4
// PinsMadeKey and PinsStatedKey are the two keys of the state that are no revision's.
PinsMadeKey = "made"
PinsStatedKey = "pins-stated"
// PinMissingKind is the finding of a pinned revision the indexer no longer holds.
PinMissingKind = "pin-missing"
// PinsTool reads the pins, UnpinTool removes one record's pin by hand.
PinsTool = "indexer_pins"
UnpinTool = "indexer_unpin"
)
// PinValue is one revision's key: the records pinning it, and whether the revision was not held when a record pinned it.
type PinValue struct {
Records []string `json:"records"`
Missing bool `json:"missing,omitempty"`
}
// PinStamp is the value of the keys made and pins-stated.
type PinStamp struct {
At time.Time `json:"at"`
}
// PinKey is a revision's key in the state pins.
func PinKey(branch string, revision int64) string {
return keys.EscapeName(branch) + "." + strconv.FormatInt(revision, 10)
}
// ParsePinKey is the branch and the revision a key of the state pins names; false for made, pins-stated and what is no revision's key.
func ParsePinKey(key string) (branch string, revision int64, ok bool) {
i := strings.LastIndex(key, ".")
if i <= 0 {
return "", 0, false
}
n, err := strconv.ParseInt(key[i+1:], 10, 64)
if err != nil {
return "", 0, false
}
b, err := keys.UnescapeName(key[:i])
if err != nil {
return "", 0, false
}
return b, n, true
}
// pinObject is the revision object a key names.
func pinObject(key string) (string, bool) {
branch, revision, ok := ParsePinKey(key)
if !ok {
return "", false
}
return RevisionObject(meshcatalog.CatalogRevision{Branch: branch, Revision: revision}), true
}
func (ix *Indexer) pinsStamp(ctx context.Context, key string) (PinStamp, bool, error) {
var s PinStamp
v, _, found, err := ix.Pins.Get(ctx, key)
if err != nil || !found {
return s, false, err
}
if err := json.Unmarshal(v, &s); err != nil {
return s, false, fmt.Errorf("%s.%s: %w", PinsState, key, err)
}
return s, true, nil
}
// PinsMade writes the key made once, create-only, when the state is first used; a made already written stays.
func (ix *Indexer) PinsMade(ctx context.Context) error {
if ix.Pins == nil {
return nil
}
data, err := json.Marshal(PinStamp{At: ix.now().UTC()})
if err != nil {
return err
}
if err := ix.Pins.Create(ctx, PinsMadeKey, data); err != nil && !errors.Is(err, ErrConflict) {
return fmt.Errorf("%s.%s: %w", PinsState, PinsMadeKey, err)
}
return nil
}
// pinsCounted says the pins count: a pins-stated later than made is applied.
func (ix *Indexer) pinsCounted(ctx context.Context) (bool, error) {
made, ok, err := ix.pinsStamp(ctx, PinsMadeKey)
if err != nil || !ok {
return false, err
}
stated, ok, err := ix.pinsStamp(ctx, PinsStatedKey)
if err != nil || !ok {
return false, err
}
return stated.At.After(made.At), nil
}
// HeardPins applies one event of the seat mesh-delivery the indexer's durable consumer gave it: pinned, freed, heads-replaced or
// pins-stated, by its subject. An error leaves the event unacknowledged, so the bus gives it again; one applied twice changes nothing.
func (ix *Indexer) HeardPins(ctx context.Context, subject string, body []byte) error {
if ix.Pins == nil {
return errors.New("the indexer keeps no state " + PinsState)
}
if err := ix.PinsMade(ctx); err != nil {
return err
}
switch subject {
case meshdelivery.SubjectPinned, meshdelivery.SubjectFreed:
var p meshdelivery.Pins
if err := json.Unmarshal(body, &p); err != nil {
return fmt.Errorf("%s is not a pins body: %w", subject, err)
}
for _, c := range p.Catalog {
key := PinKey(c.Branch, c.Revision)
if subject == meshdelivery.SubjectPinned {
if err := ix.pin(ctx, key, p.Record); err != nil {
return err
}
} else if err := ix.unpin(ctx, key, p.Record); err != nil {
return err
}
}
case meshdelivery.SubjectHeadsReplaced:
var h meshdelivery.HeadsReplacedEvent
if err := json.Unmarshal(body, &h); err != nil {
return fmt.Errorf("%s is not a heads-replaced body: %w", subject, err)
}
ix.DropCandidateGraph(ctx, h.Group, h.Heads, "mesh-delivery", "its event heads-replaced: the candidate's heads were replaced or its pull request closed")
case meshdelivery.SubjectPinsStated:
var s meshdelivery.PinsStatedEvent
if err := json.Unmarshal(body, &s); err != nil {
return fmt.Errorf("%s is not a pins-stated body: %w", subject, err)
}
err := write(ctx, ix.Pins, PinsStatedKey, func(old []byte, found bool) ([]byte, bool, error) {
var cur PinStamp
if found && json.Unmarshal(old, &cur) == nil && !s.At.After(cur.At) {
return nil, false, nil
}
data, err := json.Marshal(PinStamp{At: s.At.UTC()})
return data, false, err
})
if err != nil {
return err
}
default:
return fmt.Errorf("%s is no event of the pins", subject)
}
return nil
}
// pin adds a record's id to a revision's key by compare-and-set; a revision not held is marked missing and said.
func (ix *Indexer) pin(ctx context.Context, key, record string) error {
object, _ := pinObject(key)
missing := false
if ix.Revisions != nil {
if _, err := ix.Revisions.Get(ctx, object); errors.Is(err, ErrNoObject) {
missing = true
} else if err != nil {
return fmt.Errorf("%s cannot be read: %w", object, err)
}
}
err := write(ctx, ix.Pins, key, func(old []byte, found bool) ([]byte, bool, error) {
var v PinValue
if found {
if err := json.Unmarshal(old, &v); err != nil {
return nil, false, fmt.Errorf("%s.%s: %w", PinsState, key, err)
}
}
if !slices.Contains(v.Records, record) {
v.Records = append(v.Records, record)
slices.Sort(v.Records)
}
v.Missing = v.Missing || (missing && !found)
data, err := json.Marshal(v)
return data, false, err
})
if err != nil {
return err
}
if missing {
ix.sayPinMissing(ctx, key, record)
}
return nil
}
// unpin removes a record's id from a revision's key; a missing revision's key left with no record goes, and its finding.
func (ix *Indexer) unpin(ctx context.Context, key, record string) error {
var gone bool
err := write(ctx, ix.Pins, key, func(old []byte, found bool) ([]byte, bool, error) {
gone = false
if !found {
return nil, false, nil
}
var v PinValue
if err := json.Unmarshal(old, &v); err != nil {
return nil, false, fmt.Errorf("%s.%s: %w", PinsState, key, err)
}
v.Records = slices.DeleteFunc(v.Records, func(r string) bool { return r == record })
if v.Missing && len(v.Records) == 0 {
gone = true
return nil, true, nil
}
data, err := json.Marshal(v)
return data, false, err
})
if err == nil && gone {
ix.clearPinMissing(ctx, key)
}
return err
}
func pinFindingID(key string) string { return Module + ".pin." + key }
func (ix *Indexer) sayPinMissing(ctx context.Context, key, record string) {
if ix.Findings == nil {
return
}
object, _ := pinObject(key)
f := ix.observed(mcc.ScopeModule, pinFindingID(key), PinMissingKind,
fmt.Sprintf("the delivery record %s pins the catalog graph revision %s, which the indexer no longer holds", record, object),
"A delivery record points at a catalog graph revision the indexer does not keep",
"The indexer removed the revision, or never kept it, before the record pinned it. indexer_unpin removes the record's pin and clears this.", PinMissingKind)
if err := ix.Findings.Write(ctx, f); err != nil {
ix.logf("pins: the finding %s for %s is not written: %v", PinMissingKind, key, err)
}
}
func (ix *Indexer) clearPinMissing(ctx context.Context, key string) {
if ix.Findings == nil {
return
}
if err := ix.clearFinding(ctx, mcc.ScopeModule, pinFindingID(key), PinMissingKind, "no record pins "+key+" any more"); err != nil {
ix.logf("pins: the finding %s for %s is not cleared: %v", PinMissingKind, key, err)
}
}
// RevisionGroup says which watched branch's line a revision object belongs to, and its number; false for a candidate or an entry.
func RevisionGroup(name string) (group string, revision int64, ok bool) {
if n, ok := TrunkRevisionOf(name); ok {
return "", n, true
}
if rest, ok := strings.CutPrefix(name, "branch."); ok {
i := strings.LastIndex(rest, ".")
if i > 0 {
if n, err := strconv.ParseInt(rest[i+1:], 10, 64); err == nil {
return rest[:i], n, true
}
}
}
return "", 0, false
}
// CurrentRevisions are the kept revision objects that are current (§579): the newest of each watched branch, and every open
// candidate's, with why each is.
func CurrentRevisions(names []string) map[string]string {
newest := map[string]int64{}
for _, n := range names {
if g, r, ok := RevisionGroup(n); ok && r > newest[g] {
newest[g] = r
}
}
out := map[string]string{}
for _, n := range names {
if g, r, ok := RevisionGroup(n); ok && r == newest[g] {
out[n] = "the newest revision of its watched branch"
} else if strings.HasPrefix(n, "candidate.") {
out[n] = "an open candidate's"
}
}
return out
}
// JudgePins removes every kept revision no record pins and which is not current, entries no kept revision lists with them, and
// says room; at the start, when the consumer is caught up and the pins count, it judges every kept revision (§579). It judges on
// applying freed, on a revision ceasing to be current and on being caught up, never on a timer.
func (ix *Indexer) JudgePins(ctx context.Context) {
if ix.Pins == nil || ix.Revisions == nil {
return
}
ix.keepMu.Lock()
removed, err := ix.judgePinsLocked(ctx)
var dropped []string
if err == nil && len(removed) > 0 {
dropped, err = ix.removeUnlisted(ctx)
}
ix.keepMu.Unlock()
if err != nil {
ix.logf("pins: the revisions no record pins are not removed: %v", err)
}
if len(removed) > 0 {
ix.logf("pins: %d revisions removed (%s) with %d entries, no record pins them and none is current", len(removed), strings.Join(removed, ", "), len(dropped))
if _, err := ix.RoomAgain(ctx); err != nil {
ix.logf("pins: room is not evaluated: %v", err)
}
}
}
// judgePinsLocked removes the revisions; the caller holds keepMu. It removes none while the consumer is not caught up or the pins do
// not count yet.
func (ix *Indexer) judgePinsLocked(ctx context.Context) ([]string, error) {
if ix.PinsPending == nil {
return nil, nil
}
pending, err := ix.PinsPending(ctx)
if err != nil || pending != 0 {
return nil, err
}
counted, err := ix.pinsCounted(ctx)
if err != nil || !counted {
return nil, err
}
names, err := ix.Revisions.Names(ctx)
if err != nil {
return nil, err
}
current := CurrentRevisions(names)
pinned := map[string]bool{}
pinKeys, err := ix.Pins.Keys(ctx)
if err != nil {
return nil, err
}
for _, k := range pinKeys {
object, ok := pinObject(k)
if !ok {
continue
}
v, _, found, err := ix.Pins.Get(ctx, k)
if err != nil {
return nil, err
}
var pv PinValue
if found && json.Unmarshal(v, &pv) == nil && len(pv.Records) > 0 {
pinned[object] = true
}
}
var removed []string
for _, n := range names {
if _, _, ok := RevisionGroup(n); !ok || pinned[n] {
continue
}
if _, cur := current[n]; cur {
continue
}
if err := ix.Revisions.Delete(ctx, n); err != nil {
return removed, fmt.Errorf("%s: %w", n, err)
}
removed = append(removed, n)
}
for _, k := range pinKeys {
object, ok := pinObject(k)
if !ok || !slices.Contains(removed, object) {
continue
}
if v, rev, found, err := ix.Pins.Get(ctx, k); err == nil && found {
var pv PinValue
if json.Unmarshal(v, &pv) == nil && len(pv.Records) == 0 {
_ = ix.Pins.Delete(ctx, k, rev)
}
}
}
sort.Strings(removed)
return removed, nil
}
// Unpin removes one record's pin from a revision by hand (indexer_unpin), for a freed that was lost, and the removal rule then applies.
func (ix *Indexer) Unpin(ctx context.Context, revision, record, by, why string) TakenIn {
r := TakenIn{Module: "pins " + revision}
if ix.Pins == nil {
r.Answer = "the indexer keeps no state " + PinsState + ": nothing unpinned"
return r
}
if _, _, ok := ParsePinKey(revision); !ok {
r.Answer = revision + " is no key of the state " + PinsState + " as indexer_pins names them: nothing unpinned"
return r
}
if err := ix.unpin(ctx, revision, record); err != nil {
r.Answer = "the pin of " + record + " on " + revision + " could not be removed: " + err.Error()
ix.logf("%s", r.Answer)
return r
}
r.Stored = true
r.Answer = fmt.Sprintf("the pin of %s on %s is removed by %s (%s)", record, revision, by, why)
ix.logf("%s", r.Answer)
ix.JudgePins(ctx)
return r
}
// PinnedRevision is one revision of the state pins as indexer_pins lists it.
type PinnedRevision struct {
Revision string `json:"revision"`
Object string `json:"object"`
Records []string `json:"records"`
Missing bool `json:"missing,omitempty"`
Kept bool `json:"kept"`
// Current says it is current, Why in what way.
Current bool `json:"current,omitempty"`
Why string `json:"why,omitempty"`
}
// PinsAnswer is what indexer_pins answers.
type PinsAnswer struct {
Pins []PinnedRevision `json:"pins"`
// Unpinned are the kept revisions no record pins, current or not, and Current why each current one is.
Unpinned []string `json:"unpinned,omitempty"`
Made *time.Time `json:"made,omitempty"`
Stated *time.Time `json:"pins-stated,omitempty"`
// Counted says the pins count: a pins-stated later than made is applied.
Counted bool `json:"counted"`
// Fill is the state's bytes against its cap.
Fill meshcatalog.Fill `json:"fill"`
}
// ReadPins reads the state pins and the revisions kept, for indexer_pins.
func ReadPins(ctx context.Context, pins Store, o Objects) (PinsAnswer, error) {
ix := &Indexer{Pins: pins, Revisions: o}
var out PinsAnswer
names, err := o.Names(ctx)
if err != nil {
return out, fmt.Errorf("the catalog graph revisions cannot be read: %w", err)
}
current := CurrentRevisions(names)
pinnedObjects := map[string]bool{}
pinKeys, err := pins.Keys(ctx)
if err != nil {
return out, fmt.Errorf("the state %s cannot be read: %w", PinsState, err)
}
slices.Sort(pinKeys)
var bytes int64
for _, k := range pinKeys {
v, _, found, err := pins.Get(ctx, k)
if err != nil || !found {
continue
}
bytes += int64(len(k) + len(v))
if object, ok := pinObject(k); ok {
var pv PinValue
if err := json.Unmarshal(v, &pv); err != nil {
return out, fmt.Errorf("%s.%s: %w", PinsState, k, err)
}
why, cur := current[object]
p := PinnedRevision{Revision: k, Object: object, Records: pv.Records, Missing: pv.Missing, Kept: slices.Contains(names, object), Current: cur, Why: why}
if len(pv.Records) > 0 {
pinnedObjects[object] = true
}
out.Pins = append(out.Pins, p)
}
}
for _, n := range names {
if _, _, ok := RevisionGroup(n); ok && !pinnedObjects[n] {
out.Unpinned = append(out.Unpinned, n)
}
}
if s, ok, err := ix.pinsStamp(ctx, PinsMadeKey); err == nil && ok {
out.Made = &s.At
}
if s, ok, err := ix.pinsStamp(ctx, PinsStatedKey); err == nil && ok {
out.Stated = &s.At
}
out.Counted, _ = ix.pinsCounted(ctx)
out.Fill = meshcatalog.Fill{Bytes: bytes, Cap: PinsCapMiB << 20, Store: PinsState}
return out, nil
}
// PinsTools are indexer_pins (class read) and indexer_unpin (class act: an ask in takeins the indexer, the state's owner, applies;
// record says the hand act in the hand-act log before it is asked).
func PinsTools(pins Store, o Objects, ask func(key string, value []byte) (TakeInAsk, error), now func() time.Time, record func(what, why string) error) []stdio.Tool {
return []stdio.Tool{
{Name: PinsTool,
Description: "Every catalog graph revision a delivery record pins in the indexer's state pins (design 47 G §579): the revision's " +
"key `<branch>.<revision>`, the records pinning it, whether it was missing when pinned (finding pin-missing), whether it is " +
"kept and whether it is current and why; the kept revisions no record pins; when the state was made and when the newest " +
"pins-stated was applied, and whether pins count yet (a pins-stated later than made); and the state's fill against its cap. " +
"indexer_consumer reads the consumer the events come through; indexer_unpin removes one record's pin.",
Input: map[string]any{"type": "object", "properties": map[string]any{}},
Run: func(map[string]any) (any, error) {
return ReadPins(context.Background(), pins, o)
}},
{Name: UnpinTool,
Description: "Remove one record's pin from one revision of the indexer's state pins, for a freed that was lost; the removal rule " +
"then applies (a revision no record pins and not current goes). A hand act, recorded through mesh-hand-acts before it is asked. " +
"Clears the finding pin-missing of a missing revision left with no record. indexer_pins names the revisions and records.",
Input: map[string]any{"type": "object", "required": []string{"revision", "record", "why"}, "properties": map[string]any{
"revision": map[string]any{"type": "string", "description": "the revision's key `<branch>.<revision>`, as indexer_pins names it"},
"record": map[string]any{"type": "string", "description": "the delivery record's id"},
"why": map[string]any{"type": "string", "description": "why it is unpinned, in plain words"}}},
Run: func(args map[string]any) (any, error) {
str := func(k string) string { s, _ := args[k].(string); return strings.TrimSpace(s) }
revision, rec, why := str("revision"), str("record"), str("why")
if _, _, ok := ParsePinKey(revision); !ok || rec == "" || why == "" {
return nil, errors.New("name the revision as indexer_pins names it (revision) and the record (record) and say why (why): an unpin is a hand act, recorded through mesh-hand-acts")
}
data, err := json.Marshal(TakeInAsk{V: 1, UnpinRevision: revision, UnpinRecord: rec, Why: why, By: stdio.CallerOf(args), At: now().UTC()})
if err != nil {
return nil, err
}
if err := record("unpinned the record "+rec+" from the catalog graph revision "+revision+" by hand", why); err != nil {
return nil, fmt.Errorf("the hand act was not recorded through mesh-hand-acts, so nothing was unpinned: %w", err)
}
a, err := ask("unpin."+keys.EscapeName(revision)+"."+keys.EscapeName(rec), data)
if err != nil {
return nil, err
}
return a.Result, nil
}},
}
}
// ConsumerTool is indexer_consumer (class read): each durable consumer of the indexer as the process keeps it in the state consumers
// (process.ConsumerLedger, A-176): its stream, name, acknowledged sequence, the messages pending, the last event applied with its
// `at`, and when the oldest message delivered and not yet applied was delivered.
const ConsumerTool = "indexer_consumer"
// ConsumersAnswer is what indexer_consumer answers.
type ConsumersAnswer struct {
Consumers []process.ConsumerFacts `json:"consumers"`
}
// ReadConsumers reads the state consumers.
func ReadConsumers(ctx context.Context, st Store) (ConsumersAnswer, error) {
out := ConsumersAnswer{Consumers: []process.ConsumerFacts{}}
ks, err := st.Keys(ctx)
if err != nil {
return out, fmt.Errorf("the state %s cannot be read: %w", process.ConsumersState, err)
}
slices.Sort(ks)
for _, k := range ks {
v, _, found, err := st.Get(ctx, k)
if err != nil || !found {
continue
}
var f process.ConsumerFacts
if err := json.Unmarshal(v, &f); err != nil {
return out, fmt.Errorf("%s.%s: %w", process.ConsumersState, k, err)
}
out.Consumers = append(out.Consumers, f)
}
return out, nil
}
// ConsumerTools is indexer_consumer.
func ConsumerTools(st Store) []stdio.Tool {
return []stdio.Tool{{Name: ConsumerTool,
Description: "Each durable consumer of the indexer, as its process keeps it in the state consumers after each event it applies: its stream " +
"and name, the acknowledged sequence, the messages pending, the last event applied with its time, and when the oldest message delivered " +
"and not yet applied was delivered. The pins events (mesh-delivery's pinned, freed, heads-replaced and pins-stated) come through it; " +
"indexer_pins reads what they kept.",
Input: map[string]any{"type": "object", "properties": map[string]any{}},
Run: func(map[string]any) (any, error) { return ReadConsumers(context.Background(), st) }}}
}