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
949 lines
36 KiB
Go
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, ®); 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, ®) == 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)
|
|
}
|