Files
mesh-delivery/modules/mesh-delivery-indexer/internal/index/registrations.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

949 lines
36 KiB
Go

package index
import (
"context"
"encoding/json"
"errors"
"fmt"
"slices"
"sort"
"strings"
"sync"
"time"
mma "git.novox.be/novox/mesh-contracts/go/seats/meshmoduleassigner"
occ "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/clients/operatorchannelclient"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
gitseat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/git"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// A module's registration, and the trusted change of one (design 47 G §2 to §4, §10, §342, §343, §667): the indexer keeps each
// module's newest registration in its old state section registrations, one key per module, every version on its old
// streams section's stream registration-history, and writes a version only on the operator's warrant. A change waits for
// its warrant in the old state section proposals.
const (
// RegistrationsState is the old state section of the registrations, one key per module (§2).
RegistrationsState = "registrations"
// ProposalsState is the old state section of the changes that wait for their warrant (§667), capped at 4 MiB.
ProposalsState = "proposals"
// RegistrationHistoryStream is the old streams section that keeps every version of every registration (§2, §9).
RegistrationHistoryStream = "registration-history"
// RegistrationHistoryEvent is the event of the stream, one subject per module.
RegistrationHistoryEvent = "registration"
// SeedKey is the key of the first registrations' proposal (§8).
SeedKey = "seed"
// ProposalsTool, ProposalDropTool and SeedAgainTool are the tools of the proposals (§667, §8).
ProposalsTool = "indexer_proposals"
ProposalDropTool = "indexer_proposal_drop"
SeedAgainTool = "indexer_seed_again"
// ProposalLasts is how long the operator has to answer: the router's bound for an approval less ten minutes.
ProposalLasts = occ.ApproveLasts - 10*time.Minute
)
// The states of a proposal's key (§667): open while its warrant is awaited, then how it ended.
const (
ProposalOpen = "open"
ProposalApplied = "applied"
ProposalDeclined = "declined"
ProposalExpired = "expired"
ProposalRefused = "refused"
ProposalDropped = "dropped"
ProposalLost = "lost"
// ProposalSeedWaits is the seed's end that keeps the finding seed-waits (§8).
ProposalSeedWaits = "seed-waits"
)
const (
optionApprove = "approve"
optionDecline = "decline"
)
// The verbs of a trusted change.
const (
verbRegister = "register"
verbPolicy = "policy"
verbWatch = "watch"
verbUnwatch = "unwatch"
verbSeed = "seed"
)
// Proposal is one value of the state proposals: a change awaiting its warrant, whole, with its digest, the current ask's id,
// its caller and when it was asked; ended, it keeps its outcome (§667).
type Proposal struct {
V int `json:"v"`
Verb string `json:"verb"`
Module string `json:"module,omitempty"`
Branch string `json:"branch,omitempty"`
Change json.RawMessage `json:"change"`
// Was is the version of the registration the change was composed against (0 for none): a change warranted when the
// registration moved is refused, never written over the newer one.
Was int64 `json:"was"`
Lines []string `json:"lines"`
Digest string `json:"digest"`
Ask string `json:"ask"`
Caller string `json:"caller,omitempty"`
Why string `json:"why,omitempty"`
At time.Time `json:"at"`
// State is open, or how the key ended; Outcome says it in words; Ended is when.
State string `json:"state"`
Outcome string `json:"outcome,omitempty"`
Ended time.Time `json:"ended,omitzero"`
// Seed holds, for the seed's key, the registrations it proposes (§8).
Seed []meshcatalog.Registration `json:"seed,omitempty"`
}
// ProposalKey is the key of a change: <verb>.<module>, and for watch and unwatch <verb>.<module>.<branch>, each token
// escaped as a key's name is (§667).
func ProposalKey(verb, module, branch string) string {
k := verb + "." + keys.EscapeName(module)
if branch != "" {
k += "." + keys.EscapeName(branch)
}
return k
}
// RegistrationKey is a module's key in registrations.
func RegistrationKey(module string) string { return keys.EscapeName(module) }
// Registry is the registrations and the trusted changes of them. Its parts are the indexer's: the two states, the history
// stream, the event, the seat git's branch, the seat operator-channel's ask.
type Registry struct {
Registrations Store
Proposals Store
// History keeps one version on the stream registration-history, once under its key <module>.<version>; HistoryOf reads
// every version of one module, oldest first.
History func(ctx context.Context, r meshcatalog.Registration) error
HistoryOf func(ctx context.Context, module string) ([]meshcatalog.Registration, error)
// Say says the seat mesh-catalog's event registration-changed.
Say func(ctx context.Context, e meshcatalog.RegistrationChangedEvent) error
// Pruned is told after a registration changed which branches the module watches, so what is kept of its builds of a branch
// it no longer watches goes (registration-changed, design 47 G §374); nil prunes none.
Pruned func(ctx context.Context, module string, watched []string) error
// Branch reads a branch through the seat git; an empty branch asks the repository's default branch.
Branch func(repository, branch string) (gitseat.BranchAnswer, error)
// Placement reads a module's placements through the seat mesh-module-assigner's verb placement: one per watched branch a row
// of its assignments names, with the nodes that run the module from it (design 47 G §704, A-62).
Placement func(module string) ([]mma.ModulePlacement, error)
// Ask publishes an ask under the indexer's own name, Cancel takes it back, Where reads the router's own record of an
// ask, read under the indexer's module's name (state, and the warrant when it holds one; none when it holds no ask).
Ask func(a oc.Ask) error
Cancel func(id string) error
Where func(id string) (state string, w *oc.Warrant, err error)
// SeedWaits says the finding seed-waits naming the ask, and clears it (§8); nil says nothing.
SeedWaits func(ask string, waiting bool)
// Seed composes the first registrations (§8); nil proposes none.
Seed func(ctx context.Context) (SeedProposal, error)
Now func() time.Time
Logf func(string, ...any)
mu sync.Mutex
}
func (r *Registry) now() time.Time {
if r.Now != nil {
return r.Now().UTC()
}
return time.Now().UTC()
}
func (r *Registry) logf(format string, args ...any) {
if r.Logf != nil {
r.Logf(format, args...)
}
}
// Registration is one module's newest registration.
func (r *Registry) Registration(ctx context.Context, module string) (meshcatalog.Registration, bool, error) {
v, _, found, err := r.Registrations.Get(ctx, RegistrationKey(module))
if err != nil || !found {
return meshcatalog.Registration{}, false, err
}
var reg meshcatalog.Registration
if err := json.Unmarshal(v, &reg); err != nil {
return reg, false, fmt.Errorf("the registration of %s cannot be read: %w", module, err)
}
return reg, true, nil
}
// Registrations is the verb registrations (§4): every registration, or one module's, with its history.
func (r *Registry) RegistrationsAnswer(ctx context.Context, in meshcatalog.RegistrationsInput) (meshcatalog.RegistrationsAnswer, error) {
out := meshcatalog.RegistrationsAnswer{Registrations: []meshcatalog.Registration{}}
if in.Module != "" {
reg, found, err := r.Registration(ctx, in.Module)
if err != nil {
return out, err
}
if found {
out.Registrations = append(out.Registrations, reg)
}
if in.History && r.HistoryOf != nil {
if out.History, err = r.HistoryOf(ctx, in.Module); err != nil {
return out, fmt.Errorf("the history of %s cannot be read: %w", in.Module, err)
}
}
return out, nil
}
all, err := r.Registrations.Keys(ctx)
if err != nil {
return out, err
}
slices.Sort(all)
for _, k := range all {
v, _, found, err := r.Registrations.Get(ctx, k)
if err != nil {
return out, err
}
var reg meshcatalog.Registration
if found && json.Unmarshal(v, &reg) == nil {
out.Registrations = append(out.Registrations, reg)
}
}
return out, nil
}
// refused is the answer of a change that raises no ask.
func refused(module, reason, words string) meshcatalog.RegistrationAsked {
return meshcatalog.RegistrationAsked{Module: module, Refused: reason, Words: words}
}
// forbiddenBranch refuses the two names the catalog's keys use (§343); the refusal's reason is `reserved branch name`
// (design 47 G §704).
func forbiddenBranch(b string) string {
if b == "candidate" || b == "entry" {
return fmt.Sprintf("the branch %q cannot be watched: the catalog keeps its revisions under <branch>.<revision> beside the key forms candidate and entry", b)
}
return ""
}
// reviewRequired refuses code review as a required step (§3, §482).
func reviewRequired(s meshcatalog.StepStatuses) bool {
return s.Review == meshcatalog.StepStatusesApprovalRequired
}
// protect refuses a watched branch that is named as the catalog's keys are (reason `reserved branch name`, §704) or that
// the forge does not protect (reason `unprotected branch`, §5), naming it; both empty when every branch is accepted.
func (r *Registry) protect(repository string, branches []string) (reason, words string, err error) {
for _, b := range branches {
if w := forbiddenBranch(b); w != "" {
return meshcatalog.RegistrationAskedRefusedReservedBranchName, w, nil
}
a, err := r.Branch(repository, b)
if err != nil {
return "", "", fmt.Errorf("the seat git does not answer for %s %s: %w", repository, b, err)
}
if a.Error != "" {
return "", "", fmt.Errorf("the seat git cannot read %s %s: %s", repository, b, a.Error)
}
if !a.Protected {
return meshcatalog.RegistrationAskedRefusedUnprotectedBranch,
fmt.Sprintf("the branch %s of %s is not protected: no rule refuses a direct push and admits only merges", b, repository), nil
}
}
return "", "", nil
}
// stepLines names each step status a policy moves, one line each.
func stepLines(prefix string, old, next meshcatalog.StepStatuses) []string {
var lines []string
for _, s := range []struct {
name string
was, now string
}{{"approval", old.Approval, next.Approval}, {"composition", old.Composition, next.Composition},
{"integration", old.Integration, next.Integration}, {"lint", old.Lint, next.Lint},
{"code review", old.Review, next.Review}, {"unit tests", old.Unit, next.Unit}} {
if s.was != s.now {
lines = append(lines, fmt.Sprintf("%s%s: %s -> %s", prefix, s.name, cmpEmpty(s.was), cmpEmpty(s.now)))
}
}
return lines
}
func cmpEmpty(s string) string {
if s == "" {
return "none"
}
return s
}
// overlay puts the statuses a policy names over the ones the module keeps.
func overlay(base, over meshcatalog.StepStatuses) meshcatalog.StepStatuses {
for _, p := range []struct {
b *string
o string
}{{&base.Approval, over.Approval}, {&base.Composition, over.Composition},
{&base.Integration, over.Integration}, {&base.Lint, over.Lint}, {&base.Review, over.Review}, {&base.Unit, over.Unit}} {
if p.o != "" {
*p.b = p.o
}
}
return base
}
// compose is the registration a change makes of the one kept (none: found false), and the lines that say each value it moves.
func compose(verb string, cur meshcatalog.Registration, found bool, change json.RawMessage) (meshcatalog.Registration, []string, error) {
switch verb {
case verbRegister:
var in meshcatalog.RegisterInput
if err := json.Unmarshal(change, &in); err != nil {
return cur, nil, err
}
next := in.Registration
next.Version, next.Warrant, next.By, next.At = 0, "", "", nil
var lines []string
if !found {
lines = append(lines, fmt.Sprintf("%s: registered from %s at %s, watching %s", next.Module, next.Origin, next.Path, strings.Join(next.Branches, ", ")))
lines = append(lines, stepLines(next.Module+" ", meshcatalog.StepStatuses{}, next.Policy.Steps)...)
return next, lines, nil
}
if cur.Origin != next.Origin {
lines = append(lines, fmt.Sprintf("%s: origin %s -> %s", next.Module, cur.Origin, next.Origin))
}
if cur.Path != next.Path {
lines = append(lines, fmt.Sprintf("%s: manifest path %s -> %s", next.Module, cur.Path, next.Path))
}
for _, b := range next.Branches {
if !slices.Contains(cur.Branches, b) {
lines = append(lines, fmt.Sprintf("%s: watches %s", next.Module, b))
}
}
for _, b := range cur.Branches {
if !slices.Contains(next.Branches, b) {
lines = append(lines, fmt.Sprintf("%s: stops watching %s", next.Module, b))
}
}
lines = append(lines, stepLines(next.Module+" ", cur.Policy.Steps, next.Policy.Steps)...)
lines = append(lines, artifactLines(next.Module, cur.Policy, next.Policy)...)
return next, lines, nil
case verbPolicy:
var in meshcatalog.PolicyInput
if err := json.Unmarshal(change, &in); err != nil {
return cur, nil, err
}
next := cur
var lines []string
if in.Artifact != "" {
next.Policy.Artifacts = map[string]meshcatalog.StepStatuses{}
for k, v := range cur.Policy.Artifacts {
next.Policy.Artifacts[k] = v
}
was := cur.Policy.Artifacts[in.Artifact]
now := overlay(was, in.Steps)
next.Policy.Artifacts[in.Artifact] = now
lines = stepLines(fmt.Sprintf("%s:%s ", in.Module, in.Artifact), was, now)
} else {
next.Policy.Steps = overlay(cur.Policy.Steps, in.Steps)
lines = stepLines(in.Module+" ", cur.Policy.Steps, next.Policy.Steps)
}
return next, lines, nil
case verbWatch, verbUnwatch:
var in meshcatalog.WatchInput
if err := json.Unmarshal(change, &in); err != nil {
return cur, nil, err
}
next := cur
next.Branches = slices.Clone(cur.Branches)
var lines []string
if verb == verbWatch && !slices.Contains(cur.Branches, in.Branch) {
next.Branches = append(next.Branches, in.Branch)
lines = append(lines, fmt.Sprintf("%s: watches %s", in.Module, in.Branch))
}
if verb == verbUnwatch && slices.Contains(cur.Branches, in.Branch) {
next.Branches = slices.DeleteFunc(next.Branches, func(b string) bool { return b == in.Branch })
lines = append(lines, fmt.Sprintf("%s: stops watching %s", in.Module, in.Branch))
}
return next, lines, nil
}
return cur, nil, fmt.Errorf("%q is no change of a registration", verb)
}
func artifactLines(module string, old, next meshcatalog.Policy) []string {
names := map[string]bool{}
for k := range old.Artifacts {
names[k] = true
}
for k := range next.Artifacts {
names[k] = true
}
sorted := make([]string, 0, len(names))
for k := range names {
sorted = append(sorted, k)
}
sort.Strings(sorted)
var lines []string
for _, a := range sorted {
lines = append(lines, stepLines(module+":"+a+" ", old.Artifacts[a], next.Artifacts[a])...)
}
return lines
}
// Propose is the common path of the four verbs (§3): it checks the change, composes the lines it moves, keeps it in proposals
// under its key (a newer change of the same key replaces the open ask, ADR 0666 §12) and asks the operator, naming every value
// it moves and carrying the change's digest. It writes no registration.
func (r *Registry) Propose(ctx context.Context, verb, caller string, change json.RawMessage) (meshcatalog.RegistrationAsked, error) {
var module, branch, why string
switch verb {
case verbRegister:
var in meshcatalog.RegisterInput
if err := json.Unmarshal(change, &in); err != nil {
return meshcatalog.RegistrationAsked{}, fmt.Errorf("register takes a registration: %w", err)
}
module, why = in.Registration.Module, in.Why
case verbPolicy:
var in meshcatalog.PolicyInput
if err := json.Unmarshal(change, &in); err != nil {
return meshcatalog.RegistrationAsked{}, fmt.Errorf("policy takes a module and its steps: %w", err)
}
module, why = in.Module, in.Why
case verbWatch, verbUnwatch:
var in meshcatalog.WatchInput
if err := json.Unmarshal(change, &in); err != nil {
return meshcatalog.RegistrationAsked{}, fmt.Errorf("%s takes a module and a branch: %w", verb, err)
}
module, branch, why = in.Module, in.Branch, in.Why
default:
return meshcatalog.RegistrationAsked{}, fmt.Errorf("%q is no change of a registration", verb)
}
if strings.TrimSpace(module) == "" {
return meshcatalog.RegistrationAsked{}, errors.New("name the module (module)")
}
if (verb == verbWatch || verb == verbUnwatch) && branch == "" {
return meshcatalog.RegistrationAsked{}, errors.New("name the branch (branch)")
}
r.mu.Lock()
defer r.mu.Unlock()
cur, found, err := r.Registration(ctx, module)
if err != nil {
return meshcatalog.RegistrationAsked{}, err
}
if verb != verbRegister && !found {
return refused(module, meshcatalog.RegistrationAskedRefusedUnknownModule, module+" is not registered: register it first"), nil
}
// An unwatch of a branch a placement names is refused, naming the placement (§704, A-62).
if verb == verbUnwatch {
if r.Placement == nil {
return meshcatalog.RegistrationAsked{}, errors.New("the placements of a module are not asked of the seat mesh-module-assigner, so no branch is unwatched")
}
placed, err := r.Placement(module)
if err != nil {
return meshcatalog.RegistrationAsked{}, fmt.Errorf("the placements of %s are not read: %w", module, err)
}
for _, p := range placed {
if p.Branch == branch {
return refused(module, meshcatalog.RegistrationAskedRefusedPlaced,
fmt.Sprintf("the branch %s of %s is placed: %s run it from that branch", branch, module, strings.Join(p.Nodes, ", "))), nil
}
}
}
// register with no branch takes the repository's default branch (§342).
if verb == verbRegister {
var in meshcatalog.RegisterInput
_ = json.Unmarshal(change, &in)
if in.Registration.Origin == "" || in.Registration.Path == "" {
return meshcatalog.RegistrationAsked{}, errors.New("name the registration's origin and the path of its manifest")
}
if len(in.Registration.Branches) == 0 {
a, err := r.Branch(in.Registration.Origin, "")
if err != nil {
return meshcatalog.RegistrationAsked{}, fmt.Errorf("the seat git does not answer the default branch of %s: %w", in.Registration.Origin, err)
}
if a.Error != "" || a.Branch == "" {
return meshcatalog.RegistrationAsked{}, fmt.Errorf("the default branch of %s is not read: %s", in.Registration.Origin, a.Error)
}
in.Registration.Branches = []string{a.Branch}
if change, err = json.Marshal(in); err != nil {
return meshcatalog.RegistrationAsked{}, err
}
}
}
steps := []meshcatalog.StepStatuses{}
switch verb {
case verbRegister:
var in meshcatalog.RegisterInput
_ = json.Unmarshal(change, &in)
steps = append(steps, in.Registration.Policy.Steps)
for _, a := range in.Registration.Policy.Artifacts {
steps = append(steps, a)
}
case verbPolicy:
var in meshcatalog.PolicyInput
_ = json.Unmarshal(change, &in)
steps = append(steps, in.Steps)
}
for _, s := range steps {
if reviewRequired(s) {
return refused(module, meshcatalog.RegistrationAskedRefusedReviewRequired,
"code review is never a required step: no record binds a forge account to its bus identity, so no review can gate while its author cannot be told"), nil
}
}
next, lines, err := compose(verb, cur, found, change)
if err != nil {
return meshcatalog.RegistrationAsked{}, err
}
var branches []string
switch verb {
case verbRegister:
branches = next.Branches
case verbWatch:
branches = []string{branch}
}
if len(branches) > 0 {
reason, words, err := r.protect(next.Origin, branches)
if err != nil {
return meshcatalog.RegistrationAsked{}, err
}
if reason != "" {
return refused(module, reason, words), nil
}
}
if len(lines) == 0 {
return refused(module, meshcatalog.RegistrationAskedRefusedNothingMoves, "the change moves no value of "+module+"'s registration"), nil
}
p := Proposal{V: 1, Verb: verb, Module: module, Branch: branch, Change: change, Lines: lines, Caller: caller, Why: why, At: r.now(), State: ProposalOpen}
if found {
p.Was = cur.Version
}
if p.Digest, err = DigestOf(map[string]any{"verb": verb, "module": module, "change": json.RawMessage(change)}); err != nil {
return meshcatalog.RegistrationAsked{}, err
}
if err := r.keepAndAsk(ctx, ProposalKey(verb, module, branch), &p); err != nil {
return meshcatalog.RegistrationAsked{}, err
}
return meshcatalog.RegistrationAsked{Module: module, Ask: p.Ask, Lines: lines}, nil
}
// askID is the id of the ask of a change: it names the key's digest and time, so a newer change of the key is a new id.
func askID(key, digest string, at time.Time) string {
d := strings.TrimPrefix(digest, "sha256:")
if len(d) > 16 {
d = d[:16]
}
return fmt.Sprintf("reg-%s-%d", d, at.Unix())
}
// composeAsk is the ask of a proposal, composed again from it wherever it is checked.
func (p Proposal) composeAsk(key string) oc.Ask {
headline := "Change the registration of " + p.Module + "?"
if p.Verb == verbSeed {
headline = "Register the first modules?"
}
if r := []rune(headline); len(r) > occ.HeadlineLength {
headline = string(r[:occ.HeadlineLength-1]) + "…"
}
explain := strings.Join(p.Lines, "\n")
if p.Why != "" {
explain += "\nWhy: " + p.Why
}
explain += "\nDigest " + p.Digest
a := oc.Ask{ID: p.Ask, Headline: headline, Explanation: explain, Who: occ.Operator,
Expires: occ.FormatTime(p.At.Add(ProposalLasts)), OnExpiry: "nothing is written; the change waits to be proposed again",
About: "catalog.proposal." + key}
for _, o := range []struct{ id, label, does, level string }{
{optionApprove, "Approve", "the registration is written as these lines say", occ.Approve},
{optionDecline, "Decline", "nothing is written", occ.Acknowledge},
} {
opt := oc.Option{ID: o.id, Label: o.label, Does: o.does, Level: o.level}
if o.level != occ.Acknowledge {
opt.Binds, _ = occ.ActDigest(p.act())
}
a.Options = append(a.Options, opt)
}
return a
}
// act is what the Approve binds: the change's verb, its module and its digest (ADR 0286 §10).
func (p Proposal) act() occ.Act {
return occ.Act{"verb": p.Verb, "module": p.Module, "digest": p.Digest}
}
// keepAndAsk keeps the proposal under its key and publishes its ask; a newer change of the key replaces the open ask.
func (r *Registry) keepAndAsk(ctx context.Context, key string, p *Proposal) error {
p.Ask = askID(key, p.Digest, p.At)
ask := p.composeAsk(key)
if err := occ.Check(ask, p.At); err != nil {
return err
}
data, err := json.Marshal(p)
if err != nil {
return err
}
if err := write(ctx, r.Proposals, key, func(old []byte, found bool) ([]byte, bool, error) {
if found {
var o Proposal
if json.Unmarshal(old, &o) == nil && o.State == ProposalOpen && o.Ask == p.Ask {
return nil, false, fmt.Errorf("the same change is asked already, as %s", o.Ask)
}
}
return data, false, nil
}); err != nil {
return fmt.Errorf("the change could not be kept, so the operator was not asked: %w", err)
}
if err := r.Ask(ask); err != nil {
p.State, p.Outcome, p.Ended = ProposalRefused, "the ask could not be published: "+err.Error(), r.now()
_ = r.keep(ctx, key, p)
return fmt.Errorf("the operator could not be asked: %w", err)
}
return nil
}
func (r *Registry) keep(ctx context.Context, key string, p *Proposal) error {
data, err := json.Marshal(p)
if err != nil {
return err
}
return write(ctx, r.Proposals, key, func([]byte, bool) ([]byte, bool, error) { return data, false, nil })
}
// ProposalRow is one key of proposals as indexer_proposals lists it.
type ProposalRow struct {
Key string `json:"key"`
Verb string `json:"verb"`
Module string `json:"module,omitempty"`
State string `json:"state"`
Ask string `json:"ask"`
Caller string `json:"caller,omitempty"`
At time.Time `json:"at"`
Outcome string `json:"outcome,omitempty"`
Ended time.Time `json:"ended,omitzero"`
Lines []string `json:"lines,omitempty"`
Digest string `json:"digest"`
}
// ListProposals is the open and the ended keys with their asks and outcomes (indexer_proposals, class read).
func ListProposals(ctx context.Context, st Store) ([]ProposalRow, error) {
all, err := st.Keys(ctx)
if err != nil {
return nil, err
}
slices.Sort(all)
out := []ProposalRow{}
for _, k := range all {
v, _, found, err := st.Get(ctx, k)
if err != nil {
return nil, err
}
var p Proposal
if !found || json.Unmarshal(v, &p) != nil {
continue
}
out = append(out, ProposalRow{Key: k, Verb: p.Verb, Module: p.Module, State: p.State, Ask: p.Ask, Caller: p.Caller, At: p.At,
Outcome: p.Outcome, Ended: p.Ended, Lines: p.Lines, Digest: p.Digest})
}
return out, nil
}
func (r *Registry) load(ctx context.Context, key string) (Proposal, uint64, bool, error) {
v, rev, found, err := r.Proposals.Get(ctx, key)
if err != nil || !found {
return Proposal{}, 0, found, err
}
var p Proposal
if err := json.Unmarshal(v, &p); err != nil {
return p, rev, true, fmt.Errorf("the proposal %s cannot be read: %w", key, err)
}
return p, rev, true, nil
}
// end writes how a key ended, when it is still the open one of this ask.
func (r *Registry) end(ctx context.Context, key, ask, state, outcome string) error {
return write(ctx, r.Proposals, key, func(old []byte, found bool) ([]byte, bool, error) {
var p Proposal
if !found || json.Unmarshal(old, &p) != nil || p.Ask != ask || p.State != ProposalOpen {
return nil, false, nil
}
p.State, p.Outcome, p.Ended = state, outcome, r.now()
data, err := json.Marshal(p)
return data, false, err
})
}
// Drop is indexer_proposal_drop (class act): it cancels the key's open ask and ends the key dropped.
func (r *Registry) Drop(ctx context.Context, key, why, by string) (string, error) {
if strings.TrimSpace(why) == "" {
return "", errors.New("say why (why): a hand act is said in the hand-act log")
}
r.mu.Lock()
defer r.mu.Unlock()
p, _, found, err := r.load(ctx, key)
switch {
case err != nil:
return "", err
case !found:
return "", fmt.Errorf("no proposal %q is kept; indexer_proposals lists the keys", key)
case p.State != ProposalOpen:
return "", fmt.Errorf("the proposal %q ended %s, and has no open ask to drop", key, p.State)
}
if err := r.Cancel(p.Ask); err != nil {
return "", fmt.Errorf("the ask %s could not be cancelled: %w", p.Ask, err)
}
if err := r.end(ctx, key, p.Ask, ProposalDropped, fmt.Sprintf("dropped by %s: %s", by, why)); err != nil {
return "", err
}
if key == SeedKey && r.SeedWaits != nil {
r.SeedWaits(p.Ask, true)
}
r.logf("the proposal %s is dropped by %s (%s); its ask %s is cancelled", key, by, why, p.Ask)
return "the ask " + p.Ask + " is cancelled and the proposal " + key + " is dropped", nil
}
// Heard takes a warrant the router said for the indexer (§667 Heard). It is applied only when its ask's id is a key's current
// ask, its digest the key's, and when the router's own record of the ask holds it with Warrant.For, never the event's body
// alone. A warrant of a replaced ask writes nothing.
func (r *Registry) Heard(ctx context.Context, w oc.Warrant) error {
r.mu.Lock()
defer r.mu.Unlock()
key, p, err := r.findAsk(ctx, w.Ask)
if err != nil {
return err
}
if p == nil || p.State != ProposalOpen {
r.logf("the warrant of the ask %s (%s) matches no open proposal, so it writes nothing", w.Ask, w.Outcome)
return nil
}
if w.Outcome != occ.OutcomeChosen {
state := ProposalRefused
switch w.Outcome {
case oc.WarrantOutcomeExpired:
state = ProposalExpired
case oc.WarrantOutcomeCancelled:
state = ProposalDropped
case oc.WarrantOutcomeReplaced:
r.logf("the warrant of the ask %s says it was replaced by a newer ask of %s", w.Ask, key)
return nil
}
return r.endKey(ctx, key, *p, state, "the ask "+w.Outcome+": "+w.Words)
}
// The router's own record of the ask holds the warrant (ADR 0286 §26, §27, §36).
state, rec, err := r.Where(p.Ask)
if err != nil {
return fmt.Errorf("the router's record of %s cannot be read, so its warrant is left unapplied: %w", p.Ask, err)
}
if rec == nil {
return fmt.Errorf("the router's record of %s (%q) holds no warrant, so the warrant heard is left unapplied", p.Ask, state)
}
if rec.Ask != w.Ask || rec.Option != w.Option || rec.AskDigest != w.AskDigest || rec.Asker != w.Asker {
return r.endKey(ctx, key, *p, ProposalRefused, "the warrant heard is not the one the router's record holds")
}
o, err := occ.For(*rec, Module, p.composeAsk(key))
if err == nil {
err = occ.Performs(o, p.act())
}
if err != nil {
return r.endKey(ctx, key, *p, ProposalRefused, err.Error())
}
if o.ID == optionDecline {
return r.endKey(ctx, key, *p, ProposalDeclined, "declined: "+occ.Says(*rec))
}
if p.Verb == verbSeed {
return r.applySeed(ctx, key, *p, *rec)
}
return r.apply(ctx, key, *p, *rec)
}
func (r *Registry) endKey(ctx context.Context, key string, p Proposal, state, outcome string) error {
if key == SeedKey && state != ProposalApplied && r.SeedWaits != nil {
state = ProposalSeedWaits
r.SeedWaits(p.Ask, true)
}
if err := r.end(ctx, key, p.Ask, state, outcome); err != nil {
return err
}
r.logf("the proposal %s ended %s: %s", key, state, outcome)
return nil
}
// findAsk is the key whose current ask has the id.
func (r *Registry) findAsk(ctx context.Context, ask string) (string, *Proposal, error) {
all, err := r.Proposals.Keys(ctx)
if err != nil {
return "", nil, err
}
for _, k := range all {
p, _, found, err := r.load(ctx, k)
if err != nil || !found {
continue
}
if p.Ask == ask {
return k, &p, nil
}
}
return "", nil, nil
}
// apply writes a warranted change: its history version first (kept once under <module>.<version>), then the registration by
// compare-and-set, then the event; the key ends applied. A change composed against a registration that moved since is refused.
func (r *Registry) apply(ctx context.Context, key string, p Proposal, w oc.Warrant) error {
cur, found, err := r.Registration(ctx, p.Module)
if err != nil {
return err
}
if cur.Version != p.Was || (!found && p.Was != 0) {
return r.endKey(ctx, key, p, ProposalRefused, fmt.Sprintf("the registration of %s moved to version %d since the change was asked at version %d; ask it again", p.Module, cur.Version, p.Was))
}
next, _, err := compose(p.Verb, cur, found, p.Change)
if err != nil {
return r.endKey(ctx, key, p, ProposalRefused, err.Error())
}
return r.write(ctx, key, p, next, w)
}
func (r *Registry) write(ctx context.Context, key string, p Proposal, next meshcatalog.Registration, w oc.Warrant) error {
at := r.now()
next.V, next.Version, next.Warrant, next.By, next.At = 1, p.Was+1, w.Ask, p.Caller, &at
if r.History != nil {
if err := r.History(ctx, next); err != nil {
return fmt.Errorf("the version %d of %s is not kept on %s, so it is not written: %w", next.Version, next.Module, RegistrationHistoryStream, err)
}
}
data, err := json.Marshal(next)
if err != nil {
return err
}
err = write(ctx, r.Registrations, RegistrationKey(next.Module), func(old []byte, found bool) ([]byte, bool, error) {
var cur meshcatalog.Registration
if found && json.Unmarshal(old, &cur) == nil && cur.Version != p.Was {
return nil, false, fmt.Errorf("the registration of %s is at version %d, not %d", next.Module, cur.Version, p.Was)
}
return data, false, nil
})
if err != nil {
return err
}
if r.Say != nil {
if err := r.Say(ctx, meshcatalog.RegistrationChangedEvent{V: 1, Module: next.Module, Version: next.Version, Moved: p.Lines, By: p.Caller, Warrant: w.Ask, At: &at}); err != nil {
r.logf("registration-changed of %s %d is not said: %v", next.Module, next.Version, err)
}
}
if r.Pruned != nil {
if err := r.Pruned(ctx, next.Module, next.Branches); err != nil {
r.logf("the builds of %s on the branches it no longer watches are not pruned: %v", next.Module, err)
}
}
return r.endKey(ctx, key, p, ProposalApplied, fmt.Sprintf("applied as version %d of %s on %s", next.Version, next.Module, occ.Says(w)))
}
// Restart reads each open key at the indexer's start (§667 A restart): a decided ask is applied or ended, an open one waited on,
// and one the router no longer holds ended lost, said.
func (r *Registry) Restart(ctx context.Context) error {
all, err := r.Proposals.Keys(ctx)
if err != nil {
return err
}
slices.Sort(all)
var errs []error
for _, k := range all {
r.mu.Lock()
p, _, found, err := r.load(ctx, k)
r.mu.Unlock()
if err != nil || !found || p.State != ProposalOpen {
continue
}
state, w, err := r.Where(p.Ask)
switch {
case err != nil:
errs = append(errs, fmt.Errorf("%s: %w", k, err))
case state == "" && w == nil:
r.mu.Lock()
err := r.endKey(ctx, k, p, ProposalLost, "the router no longer holds the ask "+p.Ask)
r.mu.Unlock()
if err != nil {
errs = append(errs, err)
}
case w != nil:
if err := r.Heard(ctx, *w); err != nil {
errs = append(errs, err)
}
default:
r.logf("the proposal %s waits for the ask %s (%s)", k, p.Ask, state)
}
}
return errors.Join(errs...)
}
// RegistryAct is one act of the registrations asked through the takeins state (the way every tool of the indexer asks it):
// the verb (register, policy, watch, unwatch, registrations, drop or seed), its input as JSON, and for a drop the key.
type RegistryAct struct {
Verb string `json:"verb"`
Input json.RawMessage `json:"input,omitempty"`
Key string `json:"key,omitempty"`
Again bool `json:"again,omitempty"`
}
// The verbs of a RegistryAct that are no change of a registration.
const (
ActRegistrations = "registrations"
ActDrop = "drop"
ActSeed = "seed"
)
// NewRegistryAsk is the value and the key in takeins an act of the registrations is written under.
func NewRegistryAsk(act RegistryAct, why, by string, at time.Time) (string, []byte, error) {
if act.Verb == "" {
return "", nil, errors.New("name the act")
}
data, err := json.Marshal(TakeInAsk{V: 1, Registry: &act, Why: why, By: by, At: at.UTC()})
return "registry." + act.Verb + "." + at.UTC().Format("20060102T150405.000000000"), data, err
}
// Act answers one RegistryAct: the verb's answer as JSON in Registry, or why it could not be answered. seed is what the seed is
// composed from (the trunk's modules and what their build seats answered steps with).
func (r *Registry) Act(ctx context.Context, a TakeInAsk, seed func(context.Context) ([]SeedModule, error)) TakenIn {
out := TakenIn{Module: "registry"}
act := a.Registry
if act == nil {
out.Answer = "no registry act"
return out
}
var (
answer any
err error
)
switch act.Verb {
case verbRegister, verbPolicy, verbWatch, verbUnwatch:
answer, err = r.Propose(ctx, act.Verb, a.By, act.Input)
case ActRegistrations:
var in meshcatalog.RegistrationsInput
if len(act.Input) > 0 {
err = json.Unmarshal(act.Input, &in)
}
if err == nil {
answer, err = r.RegistrationsAnswer(ctx, in)
}
case ActDrop:
var said string
said, err = r.Drop(ctx, act.Key, a.Why, a.By)
answer = map[string]string{"answer": said}
case ActSeed:
var modules []SeedModule
if seed == nil {
err = errors.New("the seed is not composed by this indexer")
} else if modules, err = seed(ctx); err == nil {
var ask string
ask, err = r.ProposeSeed(ctx, modules, act.Again, a.By)
answer = map[string]string{"ask": ask}
}
default:
err = fmt.Errorf("%q is no act of the registrations", act.Verb)
}
if err != nil {
out.Answer = err.Error()
return out
}
out.Stored = true
if out.Registry, err = json.Marshal(answer); err != nil {
out.Stored, out.Answer = false, err.Error()
return out
}
out.Answer = act.Verb + " answered"
return out
}
// RegistryAct answers a registrations' act asked through takeins (design 47 G §3, §4, §8, §667).
func (ix *Indexer) RegistryAct(ctx context.Context, a TakeInAsk) TakenIn {
if ix.Registry == nil {
return TakenIn{Module: "registry", Answer: "this indexer keeps no registrations: their states are not bound yet"}
}
return ix.Registry.Act(ctx, a, ix.SeedModules)
}