Builds: design 47 G A-373 (G-22-lead-answers-2.md) Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
388 lines
19 KiB
Go
388 lines
19 KiB
Go
// Command mesh-grants is the grants part (novox/hq ADR 0547 clauses 5 to 8, issue 1945): a process on its own bus
|
|
// credential that watches assignments, the assigner's wants, the indexer's manifests, the builder's builds, mesh-config's
|
|
// resolved values and the node agents' haves, and on every change composes each assignment's membership, the bus's user
|
|
// list and each manifest's buckets, logs and streams with the bus composer the controller uses (mesh-sdk buscompose).
|
|
//
|
|
// **Memberships are published for real** (the operator, 2026-10-25 22:31): since release 6 nobody publishes them, so a
|
|
// module placed since cannot serve its seat or reach a new state. Each is published in the part's own state memberships
|
|
// only when it differs from the one last published there. **A bucket, log or stream a manifest declares that the bus lacks is
|
|
// created** (the operator, 2026-10-26 08:54; issue 1790), once per manifest, with the manifest's limits, on the event
|
|
// that brought the manifest; one the bus holds is never changed. **The user list is written sealed to the bus node**
|
|
// (ADR 0547 clause 7) as an object of the part's own bucket named in `user-list.sealed`, which the bus node follows
|
|
// alone since the controller ended by its unassignment (novox/hq ADR 0590, issue 1126). **The grants** the assigner
|
|
// reads are written, and **the account consumers** made; a stream the bus holds gains only the subjects its manifest adds (a consumer the filters), never loses one or changes a limit; any other difference is only said.
|
|
//
|
|
// It holds no timer, and never exits for a refused read, write or publish: a refusal is said and tried again at the next
|
|
// event.
|
|
//
|
|
// Started by the tool runner, with no credential of its own, it serves those tools (a process never serves, ADR 0436).
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"io"
|
|
"log"
|
|
"os"
|
|
"os/signal"
|
|
"strings"
|
|
"sync"
|
|
"syscall"
|
|
"time"
|
|
|
|
"github.com/nats-io/nats.go"
|
|
"github.com/nats-io/nats.go/jetstream"
|
|
|
|
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
|
|
mcseat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
|
|
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
|
|
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshwantsclient"
|
|
"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/meshwants"
|
|
stdio "git.novox.be/novox/mesh-sdk/go"
|
|
"git.novox.be/novox/mesh-sdk/go/announce"
|
|
"git.novox.be/novox/mesh-sdk/go/membership"
|
|
"git.novox.be/novox/mesh-sdk/go/process"
|
|
"git.novox.be/novox/mesh-sdk/go/seatdef"
|
|
"git.novox.be/novox/mesh-sdk/go/seatlist"
|
|
|
|
"git.novox.be/novox/mesh-sdk/go/views"
|
|
|
|
"mesh-grants/internal/grants"
|
|
)
|
|
|
|
func main() {
|
|
if os.Getenv("MESH_BROKER_FILE") == "" {
|
|
if err := serveTools(); err != nil {
|
|
fmt.Fprintln(os.Stderr, "mesh-grants:", err)
|
|
os.Exit(1)
|
|
}
|
|
return
|
|
}
|
|
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
|
|
defer stop()
|
|
if err := run(ctx, os.Getenv, os.Stderr); err != nil {
|
|
fmt.Fprintln(os.Stderr, "mesh-grants:", err)
|
|
os.Exit(1)
|
|
}
|
|
}
|
|
|
|
// bindingsTiming is the bound and the waits of the first view of the bindings; zero is the design's (two minutes; from ten
|
|
// seconds, doubling, at most five minutes: design 25 bindings-first-view §5). The whole-module test sets small ones.
|
|
var bindingsTiming struct{ bound, wait, max time.Duration }
|
|
|
|
// keptStates is what the part keeps (ADR 0495 §2-§3): each readable, for the view and a session, but the wanted accounts,
|
|
// by the vault alone (ADR 0561 §2).
|
|
func keptStates() []announce.State { return grants.Announced() }
|
|
|
|
// run is the process: it returns when ctx ends, or when it has no credential or cannot dial the bus at all. A bucket or
|
|
// read the bus refuses never ends it.
|
|
func run(ctx context.Context, getenv func(string) string, logOut io.Writer) error {
|
|
logger := log.New(logOut, "mesh-grants: ", log.LstdFlags)
|
|
path := strings.TrimSpace(getenv("MESH_BROKER_FILE"))
|
|
if path == "" {
|
|
return errors.New("MESH_BROKER_FILE is not set, so there is no credential to read the bus with")
|
|
}
|
|
account, err := process.ReadAccount(path)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
f := &grants.Follower{Logf: logger.Printf}
|
|
conn, err := process.Connect(account, nats.Name(account.Node+"."+account.Module), nats.RetryOnFailedConnect(true),
|
|
nats.ReconnectHandler(func(*nats.Conn) { f.Wake() }))
|
|
if err != nil {
|
|
return err
|
|
}
|
|
defer conn.Close()
|
|
if err := conn.Keeps(keptStates()...); err != nil {
|
|
logger.Printf("what the part keeps could not be said on the bus, so its readers are not granted until it is: %v", err)
|
|
}
|
|
// The reads of other parts' state, on a connection of the same account: a read the bus refuses is said and composed
|
|
// past (busReader), never the end of the process.
|
|
opts := []nats.Option{
|
|
nats.Name(account.Node + "." + account.Module + ".reads"),
|
|
nats.UserInfo(account.User, account.Password),
|
|
nats.CustomInboxPrefix(account.InboxPrefix()),
|
|
nats.MaxReconnects(-1),
|
|
nats.RetryOnFailedConnect(true),
|
|
nats.ReconnectHandler(func(*nats.Conn) { f.Wake() }),
|
|
}
|
|
if strings.TrimSpace(account.Fingerprint) != "" {
|
|
opts = append(opts, nats.Secure(process.PinnedToFingerprint(account.Fingerprint)))
|
|
}
|
|
nc, err := nats.Connect(account.URL, opts...)
|
|
if err != nil {
|
|
return fmt.Errorf("connecting to the bus: %w", err)
|
|
}
|
|
defer nc.Close()
|
|
js, err := jetstream.New(nc)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
bus := newBusReader(ctx, js)
|
|
// The module has one durable consumer of EVENTS: one hub pulls it and hands each message to the part that hears it (the
|
|
// owners' views events, the seat mesh-catalog's verdicts and seat list events, the other seats' events the follower hears),
|
|
// started once all are registered.
|
|
hub := process.NewEventHub(logger.Printf)
|
|
defer hub.Stop()
|
|
// The owners' five states by their first views (ADR 0615, ADR 0622): asked through the part's own account, then
|
|
// followed on the owners' views families, which the hearing below hands them.
|
|
sayCond := sayVia(ctx, js, account.Module)
|
|
// The four findings the part says of what it waits for go through mesh-sdk's held finding writer (design 47 G §388, §529,
|
|
// A-51): it holds them, and states them at its start and when the keeper asks. It starts once its state is bound; what the
|
|
// part writes before is held and written at its start.
|
|
fw, err := views.NewHeldWriter(views.WriterConfig[mcseat.Finding, mcseat.FindingCleared, mcseat.FindingsStated, mcseat.FindingsAskedEvent]{
|
|
Module: account.Module, State: conn.State(grants.StateFindings), Node: account.Node, Kinds: grants.FindingKinds,
|
|
Asked: mcseat.SubjectFindingsAsked, JS: js, Conn: nc, Logf: logger.Printf})
|
|
if err != nil {
|
|
return err
|
|
}
|
|
findingsKV := process.AwaitBucket(ctx, js, nc, account.Module+"_"+grants.StateFindings,
|
|
"the part's findings are held and said when its state is bound", logger.Printf)
|
|
findingsKV.Ready(func(jetstream.KeyValue) {
|
|
if err := fw.Start(ctx); err != nil {
|
|
logger.Printf("the finding writer cannot start, its findings are kept in the state alone: %v", err)
|
|
}
|
|
})
|
|
sayFinding := grants.SayFinding(fw, account.Node, time.Now)
|
|
fv := grants.NewViews(func(tool string) func(context.Context, string) (views.Answer, error) {
|
|
return grants.TimedAsk(tool, views.AskVia(grants.Unwrapped(conn.Call), tool), time.Now, logger.Printf)
|
|
}, sayFinding, f.Wake, logger.Printf)
|
|
fv.Rest, fv.Watching = bus, bus
|
|
byState := map[string]*views.Follower{}
|
|
for _, v := range grants.FirstViews {
|
|
byState[v.State] = fv.Followers[v.Read]
|
|
}
|
|
hearViews := views.Hear(ctx, byState, logger.Printf)
|
|
// The catalog half (design 47 G §614, §684, A-5, A-52): the branch follower of meshcatalogclient, adopted on the part's views
|
|
// reader, which holds the part's finding writer, so the part's view-waits is the reader's. The reader hears the events of the
|
|
// views it follows; every other owner's views event is the five first views' above (Other). The reader's own first-views state
|
|
// is none: grants_first_views says the catalog half's views beside the others.
|
|
reader := &views.ProcessReader{Module: account.Module, Call: conn.Call, Logf: logger.Printf, Hub: hub, Other: hearViews,
|
|
Findings: func() views.WireWriter { return fw }}
|
|
branches, err := meshcatalogclient.FollowBranchesProcess(reader, conn.Call)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
branches.Logf = logger.Printf
|
|
branches.Changed = func(string, string, json.RawMessage, bool, time.Time) { f.Wake() }
|
|
branches.Entries.Changed = func(meshcatalogclient.EntryRow) { f.Wake() }
|
|
fv.Catalog = &grants.CatalogOf{Branches: branches, Context: ctx, Wake: f.Wake}
|
|
// The assignment half (design 46 approval mark §6, design 47 G §195): its first view by mesh-wants' revision, then its
|
|
// assignment-revision, on the same reader; each revision held composes again, since a node's reading may have changed.
|
|
assignment, _, err := meshwantsclient.WireAssignmentProcess(reader, conn.Call, func(meshwants.AssignmentRevision) { f.Wake() })
|
|
if err != nil {
|
|
return err
|
|
}
|
|
fv.Assignment = assignment
|
|
f.Part = &grants.Part{Read: fv, Call: conn, Store: grants.BigValues(ownStore{conn}, sealedObjects{ctx: ctx, js: js}), Emit: emitting{conn}, Views: fv, FirstViewContext: ctx,
|
|
Create: creating{ctx: ctx, js: js}, Consumers: creating{ctx: ctx, js: js}, NamedPurge: creating{ctx: ctx, js: js},
|
|
Objects: sealedObjects{ctx: ctx, js: js}, Purging: ownPurging{ctx: ctx, js: js, module: account.Module}, Logf: logger.Printf,
|
|
Bus: grants.BusAddress{URL: account.URL, Fingerprint: account.Fingerprint}}
|
|
f.Watch = fv
|
|
f.Part.ReadingRunning(nodeengine.StreamRunning)
|
|
f.HearKept = func() error { return hearRunning(ctx, account, js, f, logger.Printf) }
|
|
// The first view of the bindings (design 25 bindings-first-view): the seat mesh-broker's list, asked at each start and by
|
|
// hand, with the seat's events held until its answer is applied or its bound passes.
|
|
f.Part.Bindings = &grants.BindingsView{Say: sayFinding, Changed: f.Wake, Logf: logger.Printf,
|
|
Bound: bindingsTiming.bound, Wait: bindingsTiming.wait, MaxWait: bindingsTiming.max,
|
|
Ask: func(context.Context) (json.RawMessage, error) {
|
|
return grants.Unwrapped(conn.Call)(grants.CallBrokerList, map[string]any{})
|
|
}}
|
|
f.Part.Bindings.Start(ctx, f.Part)
|
|
// The restore points' names (design 47 G §565): the seat mesh-recovery's kept-points, a kept call asked at each start and on the
|
|
// seat's ended, point-removed and expiry-ended, until it answers.
|
|
f.Part.KeptPoints = &grants.KeptPointsView{Changed: f.Wake, Logf: logger.Printf,
|
|
Ask: func(context.Context) (json.RawMessage, error) {
|
|
return grants.Unwrapped(conn.Call)(grants.CallKeptPoints, map[string]any{})
|
|
}}
|
|
f.Part.KeptPoints.Start(ctx, f.Part)
|
|
// The seat list: read over the connection and the hub, given to catalogue at every change, and a pass composes again then.
|
|
gate := newSeatGate()
|
|
gate.Follow(seatlist.ProcessBus(conn.Call, hub), f.Wake, logger.Printf)
|
|
f.Part.SeatList = gate
|
|
f.Part.Say, f.Part.SayFinding = sayCond, sayFinding
|
|
fv.Start(ctx, f.Wake)
|
|
reader.Start(ctx, js, account, nil)
|
|
f.Asked = func(wake func()) error {
|
|
return conn.State(grants.StateUserList).Watch(grants.KeyAsked, func(c stdio.StateChange) error {
|
|
if !c.Current {
|
|
wake()
|
|
}
|
|
return nil
|
|
})
|
|
}
|
|
// The part makes this module's own durable consumer on EVENTS from the manifest's consumes (filtered on the two
|
|
// condition subjects and the vault's account-issued; ADR 0561 §6), as it makes every module's; it is pulled and every message acknowledged, so its pending never grows. Where it is not there yet the pass says so and
|
|
// hears again at the next change. The vault's bus-accounts is watched beside it, so a hash is composed either way.
|
|
//
|
|
// Beside EVENTS, the module streams its consumes reach (the bus module's own stream, whose created, recreated and
|
|
// dropped carry the bindings: ADR 0595 §1, §7), each on the durable consumer its own membership names; one not
|
|
// there yet is opened at the next change, and one opened is never opened twice.
|
|
opened := map[string]bool{}
|
|
registered := false
|
|
f.Hear = func(handle func(string, []byte)) error {
|
|
if !registered {
|
|
registered = true
|
|
// An owner's views event goes to the follower of its state, which acknowledges it (firstviews.go).
|
|
// The hub says when the bus made its consumer: a picture asked before then is asked again (views.Follower.ConsumerMade).
|
|
hub.OnBound(func(created time.Time) {
|
|
for _, f := range byState {
|
|
f.ConsumerMade(ctx, created)
|
|
}
|
|
})
|
|
// The seat mesh-catalog's verdict events go to the verdicts' first view (ADR 0622 §2), which takes each at its revision.
|
|
for _, event := range []string{meshcatalog.EventManifestAccepted, meshcatalog.EventManifestRefused} {
|
|
if err := hub.Handle("mesh.seat."+meshcatalog.Seat+".event."+event, func(m jetstream.Msg) {
|
|
if err := fv.HearVerdict(ctx, strings.TrimPrefix(m.Subject(), "mesh.seat."+meshcatalog.Seat+".event."), m.Data(), logger.Printf); err != nil {
|
|
logger.Printf("views: %s is not a verdict event, dropped: %v", m.Subject(), err)
|
|
_ = m.Term()
|
|
return
|
|
}
|
|
_ = m.Ack()
|
|
}); err != nil {
|
|
return err
|
|
}
|
|
}
|
|
// The other seats' events the part follows its passes by (Consumes).
|
|
for _, subject := range grants.SeatEventSubjects() {
|
|
if err := hub.Handle(subject, func(m jetstream.Msg) {
|
|
// The seat mesh-broker's events wait for the first view's answer, unacknowledged (design 25
|
|
// bindings-first-view §3): a restart finds them delivered again.
|
|
if strings.HasPrefix(m.Subject(), grants.BrokerEventPrefix) && f.Part.Bindings != nil {
|
|
var seq uint64
|
|
if md, err := m.Metadata(); err == nil {
|
|
seq = md.Sequence.Stream
|
|
}
|
|
if f.Part.Bindings.Hold(seq, m.Subject(), m.Data(), func() { _ = m.Ack() }) {
|
|
return
|
|
}
|
|
}
|
|
handle(m.Subject(), m.Data())
|
|
_ = m.Ack()
|
|
}); err != nil {
|
|
return err
|
|
}
|
|
}
|
|
}
|
|
if err := hub.Start(ctx, js, account); err != nil {
|
|
return err
|
|
}
|
|
gate.EventsLive()
|
|
hears, err := grants.OwnHears(ownStore{conn}, account.Node)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
for _, h := range hearsToOpen(hears, opened) {
|
|
cons, err := js.Consumer(ctx, h.Stream, h.Consumer)
|
|
if err != nil {
|
|
return fmt.Errorf("the consumer %s on %s: %w", h.Consumer, h.Stream, err)
|
|
}
|
|
if _, err := cons.Consume(func(m jetstream.Msg) {
|
|
handle(m.Subject(), m.Data())
|
|
_ = m.Ack()
|
|
}, jetstream.ConsumeErrHandler(func(_ jetstream.ConsumeContext, err error) { logger.Printf("hearing the bus: %v", err) })); err != nil {
|
|
return err
|
|
}
|
|
opened[h.Stream] = true
|
|
}
|
|
return nil
|
|
}
|
|
// Once, before the first pass writes a list's keys: the sealed lists' keys a delete left in the state user-list are
|
|
// purged (issue 1966), said with the count and the bytes before and after.
|
|
if sw, err := f.Part.SweepSealed(); err != nil {
|
|
logger.Printf("the sealed lists' keys of %s were not swept: %v", grants.StateUserList, err)
|
|
} else {
|
|
for _, e := range sw.Errors {
|
|
logger.Printf("%s", e)
|
|
}
|
|
logger.Printf("swept the sealed lists' keys of %s: %d marked by a delete and %d of lists no longer kept purged, the kept lists %v untouched (no index: %v); %d bytes before, %d after",
|
|
grants.StateUserList, sw.Marked, sw.Orphaned, sw.Kept, sw.NoIndex, sw.BytesBefore, sw.BytesAfter)
|
|
}
|
|
logger.Printf("started on the account %s: publishing memberships, writing grants and the user list sealed to the bus node, which it follows, and creating the account consumers (the heard-stream ones too) and the declared buckets, logs and streams the bus lacks; a held stream and a held consumer only ever gain the subjects and filters a manifest adds", account.User)
|
|
f.Run(ctx)
|
|
return nil
|
|
}
|
|
|
|
// hearsToOpen are the streams of the part's own membership no hearing has opened yet. A stream another hearing of the part
|
|
// binds its durable on (running: hearRunning, which reads it whole at the start before it follows) is left to that hearing:
|
|
// two readers of one durable each take the messages the other does not, and the event a reader of its own never hears is lost
|
|
// to it (the integration test of the whole part met it as a state running that stayed empty, 2026-11-12).
|
|
func hearsToOpen(hears []membership.HeardIssued, opened map[string]bool) []membership.HeardIssued {
|
|
var out []membership.HeardIssued
|
|
for _, h := range hears {
|
|
if !opened[h.Stream] && h.Stream != nodeengine.StreamRunning {
|
|
out = append(out, h)
|
|
}
|
|
}
|
|
return out
|
|
}
|
|
|
|
// hearing is the stream the part's running consumer is bound to, once.
|
|
var hearingRunning struct {
|
|
sync.Mutex
|
|
cc jetstream.ConsumeContext
|
|
}
|
|
|
|
// hearRunning binds the part's durable on the node-engine's kept stream running and keeps each event in the state running,
|
|
// then wakes a pass. It binds once; a call while it is bound does nothing, and an error (the stream or durable not made yet)
|
|
// is tried again at the next pass.
|
|
func hearRunning(ctx context.Context, account process.Account, js jetstream.JetStream, f *grants.Follower, logf func(string, ...any)) error {
|
|
hearingRunning.Lock()
|
|
defer hearingRunning.Unlock()
|
|
if hearingRunning.cc != nil {
|
|
return nil
|
|
}
|
|
// At each start the stream is read whole first (design 47 G §556, §641, A-19): HearSeatEvents reads a stream kept last per
|
|
// subject through an ordered consumer made for that one read, to the last of each, and follows the durable only after it.
|
|
// Until it ends the part acts on none of running and grants_first_views says the stream waiting (OnRead).
|
|
cc, err := account.HearSeatEvents(ctx, js, nodeengine.StreamRunning, func(m jetstream.Msg) {
|
|
changed, err := f.Part.HearRunning(m.Subject(), m.Data())
|
|
if err != nil {
|
|
logf("running: %v, dropped", err)
|
|
_ = m.Term()
|
|
return
|
|
}
|
|
_ = m.Ack()
|
|
if changed {
|
|
f.Wake()
|
|
}
|
|
}, logf, process.OnRead(func(state string) {
|
|
switch state {
|
|
case process.ReadWaiting:
|
|
f.Part.ReadingRunning(nodeengine.StreamRunning)
|
|
case process.ReadDone:
|
|
f.Part.RunningRead()
|
|
f.Wake()
|
|
}
|
|
}))
|
|
if err != nil {
|
|
return err
|
|
}
|
|
hearingRunning.cc = cc
|
|
return nil
|
|
}
|
|
|
|
// seatGate is the part's seat-list wiring (mesh-sdk seatlist.Part, ADR 0636 §1, §7) that also says the definitions the
|
|
// list holds, which the part makes each kept event's stream from.
|
|
type seatGate struct{ *seatlist.Part }
|
|
|
|
// seatListAgainCallers may read the seat list again (ADR 0636 §7): every operator's session and the healers. A call through
|
|
// the mesh MCP server is proved only as its machine's tool runner (<node>.node-tools, issue 627), so node-tools stands for an
|
|
// operator's session until a session is proved (issue 1966).
|
|
var seatListAgainCallers = []string{stdio.AnyPerson, "node-tools", "mesh-healers"}
|
|
|
|
func newSeatGate() *seatGate {
|
|
return &seatGate{seatlist.NewPart("grants", seatListAgainCallers)}
|
|
}
|
|
|
|
// Definitions are the seat definitions the reader holds; none before it has started.
|
|
func (g *seatGate) Definitions() map[string]seatdef.Definition {
|
|
if r := g.Reader(); r != nil {
|
|
return r.Definitions()
|
|
}
|
|
return nil
|
|
}
|