Files
mesh-delivery/modules/mesh-grants/cmd/mesh-grants/main.go
T

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
}