mesh-grants: grants-for keeps a bounded cache of the followed branches

The kept catalog revisions had no design line and their bound stood in
the code. They are now bounded per branch by the module's setting
grants-for-revisions-per-branch (default 4, oldest dropped, a run's
candidate counted within its branch's), read at the start from the file
the manifest writes, and kept only for the watched branches the part's
branch follower follows: a branch that leaves them is freed at the next
grants-for or catalog-revision event. A kept revision is a cache of the
catalog seat's own truth, never a state of the mesh.

Builds: design 47 G §441, §401; H H-A-195, H-A-193
This commit is contained in:
2026-11-20 21:51:43 +01:00
parent a62f7b40c1
commit 120a0554d6
5 changed files with 222 additions and 25 deletions
@@ -181,6 +181,13 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
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}}
// The setting grants-for-revisions-per-branch, read at the start, and the watched branches the part follows: grants-for
// keeps those branches' revisions alone, so many to a branch (design 47 H H-A-195).
perBranch, err := grants.RevisionsPerBranchSetting(strings.TrimSpace(getenv(grants.EnvRevisionsPerBranch)))
if err != nil {
return err
}
f.Part.RevisionsPerBranch, f.Part.Followed = perBranch, branches.Followed
f.Watch = fv
f.Part.ReadingRunning(nodeengine.StreamRunning)
// The catalog-revision event names each branch's newest revision, so grants-for asks the seat mesh-catalog's revision only
+83
View File
@@ -384,6 +384,9 @@ func (b *fakeBus) Call(key string, body any) (json.RawMessage, error) {
if n, numbered := b.revisionNumber[which]; numbered {
slices.SortFunc(out.Entries, func(x, y meshcatalog.CatalogEntry) int { return strings.Compare(x.Module, y.Module) })
out.Revision = &meshcatalog.CatalogRevision{Branch: in.Branch, Kind: "trunk", Revision: n}
if in.Group != "" {
out.Revision.Kind, out.Revision.Group, out.Revision.Heads = "candidate", in.Group, "h1"
}
for len(out.Entries) > 0 && out.Entries[0].Module <= in.After {
out.Entries = out.Entries[1:]
}
@@ -5211,6 +5214,86 @@ func TestGrantsFor(t *testing.T) {
}
}
// grants-for keeps what H-A-195 says of the catalog: so many revisions to a branch as the setting
// grants-for-revisions-per-branch says, a run's candidate counted within its branch's; only the followed branches', freed when
// one leaves them; and an event below the newest held is the numbering started again, which drops what is kept.
func TestGrantsForKeepsWhatItMay(t *testing.T) {
setting := func(t *testing.T, text string) int {
path := filepath.Join(t.TempDir(), "grants-for-revisions-per-branch")
if err := os.WriteFile(path, []byte(text), 0o600); err != nil {
t.Fatal(err)
}
n, err := grants.RevisionsPerBranchSetting(path)
if err != nil {
t.Fatal(err)
}
return n
}
hear := func(t *testing.T, p *grants.Part, revision, source int) {
ev := fmt.Sprintf(`{"v":1,"kind":"trunk","branch":"main","revision":%d,"source":%d}`, revision, source)
if err := p.HearCatalogRevision(context.Background(), []byte(ev)); err != nil {
t.Fatal(err)
}
}
for _, row := range []struct {
name string
// run asks the candidate by a run, else by the source revision 7; then is done after one grants-for; pages the
// revision pages the grants-for after it reads.
run bool
// perBranch is the part's bound from the start; 0 its default.
perBranch int
then func(t *testing.T, b *fakeBus, p *grants.Part, followed *[]string)
pages int
}{
{name: "the setting bounds a branch's revisions: with 2, the candidate is dropped once two newer are kept", pages: 2,
then: func(t *testing.T, b *fakeBus, p *grants.Part, _ *[]string) {
p.RevisionsPerBranch = setting(t, "2\n")
hear(t, p, 10, 0)
b.revisionNumber["newest"] = 10
_, _ = p.GrantsFor(meshgrants.GrantsForInput{Branch: "main", Source: "7"})
}},
{name: "a run's candidate counts within its branch's bound: with 1, the candidate and the newest each drop the other", run: true,
perBranch: 1, pages: 4, then: func(*testing.T, *fakeBus, *grants.Part, *[]string) {}},
{name: "a branch that leaves the watched branches frees its revisions", pages: 4,
then: func(t *testing.T, _ *fakeBus, p *grants.Part, followed *[]string) {
*followed = nil
_, _ = p.GrantsFor(meshgrants.GrantsForInput{Branch: "main", Source: "7"})
*followed = []string{"main"}
}},
{name: "an event below the newest held drops what is kept of the branch", pages: 4,
then: func(t *testing.T, _ *fakeBus, p *grants.Part, _ *[]string) { hear(t, p, 3, 0) }},
} {
t.Run(row.name, func(t *testing.T) {
b := fixture()
b.revision = map[string]map[string]string{"newest": {"mod-x": xManifest, "mod-y": xManifest}, "candidate": {"mod-x": xManifest, "mod-y": xManifest}}
b.revisionNumber = map[string]int64{"newest": 9, "candidate": 8}
followed := []string{"main"}
p := partOn(b)
p.Followed = func() []string { return followed }
p.RevisionsPerBranch = row.perBranch
in := meshgrants.GrantsForInput{Branch: "main", Source: "7"}
if row.run {
in = meshgrants.GrantsForInput{Branch: "main", Run: "r1"}
} else {
hear(t, p, 8, 7)
hear(t, p, 9, 8)
}
if got, err := p.GrantsFor(in); err != nil || got.Error != "" {
t.Fatalf("grants-for: %+v, %v", got, err)
}
row.then(t, b, p, &followed)
before := len(slices.DeleteFunc(slices.Clone(b.calls), func(c string) bool { return c != grants.CallRevision }))
_, _ = p.GrantsFor(in)
if got := len(slices.DeleteFunc(slices.Clone(b.calls), func(c string) bool { return c != grants.CallRevision })) - before; got != row.pages {
t.Errorf("grants-for read %d revision pages, want %d", got, row.pages)
}
})
}
if n, err := grants.RevisionsPerBranchSetting(filepath.Join(t.TempDir(), "none")); n != grants.DefaultRevisionsPerBranch || err != nil {
t.Errorf("with no file the setting is %d, %v; want its default", n, err)
}
}
// heldHalf is an assignment half holding rev, or none.
type heldHalf struct{ rev *meshwants.AssignmentRevision }
+106 -24
View File
@@ -5,7 +5,9 @@ import (
"encoding/json"
"errors"
"fmt"
"io/fs"
"maps"
"os"
"slices"
"sort"
"strconv"
@@ -15,6 +17,7 @@ import (
"git.novox.be/novox/mesh-contracts/identity-and-access/go/seats/meshgrants"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// **The seat mesh-grants' read `grants-for`** (design 47 G §441, §401, A-205): the grants a candidate would compose, per
@@ -29,13 +32,64 @@ const RunGroup = "run-"
// CallRevision is the seat mesh-catalog's `revision`, as the part calls it.
const CallRevision = "seat:" + meshcatalog.Seat + "." + meshcatalog.VerbRevision
// revisionsKeptPerBranch is how many catalog revisions of one branch grants-for keeps, the oldest read dropped first; twice
// as many source revisions are kept named by the revision taken in from each.
const revisionsKeptPerBranch = 4
// DefaultRevisionsPerBranch is the setting grants-for-revisions-per-branch's default (design 47 H H-A-195): how many catalog
// revisions of one branch grants-for keeps, a run's candidate counted within its branch's, the oldest read dropped first;
// twice as many source revisions are kept named by the revision taken in from each.
const DefaultRevisionsPerBranch = 4
// revisionsKept keeps the catalog revisions grants-for read, whole, as manifests by module: a revision never changes, so one
// read is read for good (as the runner keeps its revisionCache). Each is kept by the branch grants-for was asked of (escaped as
// a key name is), its kind, group, heads and number; the newest few of each branch are kept for the process's life. It also
// EnvRevisionsPerBranch names the file the manifest writes the setting grants-for-revisions-per-branch into.
const EnvRevisionsPerBranch = "MESH_GRANTS_REVISIONS_PER_BRANCH_FILE"
// RevisionsPerBranchSetting reads the setting grants-for-revisions-per-branch from its file, read at the start: a missing or
// empty file is its default, one that holds no positive whole number an error naming the file.
func RevisionsPerBranchSetting(path string) (int, error) {
if path == "" {
return DefaultRevisionsPerBranch, nil
}
raw, err := os.ReadFile(path)
if errors.Is(err, fs.ErrNotExist) {
return DefaultRevisionsPerBranch, nil
}
if err != nil {
return 0, err
}
v := strings.TrimSpace(string(raw))
if v == "" {
return DefaultRevisionsPerBranch, nil
}
n, err := strconv.Atoi(v)
if err != nil || n < 1 {
return 0, fmt.Errorf("%s holds %q, which is not a positive whole number", path, v)
}
return n, nil
}
// revisionsPerBranch is the part's bound of kept revisions per branch: its setting, else the default.
func (p *Part) revisionsPerBranch() int {
if p.RevisionsPerBranch > 0 {
return p.RevisionsPerBranch
}
return DefaultRevisionsPerBranch
}
// following frees what is kept of every branch the part follows no more, and says whether branch is followed: only a followed
// branch's revisions are kept (H-A-195). With no Followed (the tools) every branch is.
func (p *Part) following(branch string) bool {
if p.Followed == nil {
return true
}
followed := map[string]bool{}
for _, b := range p.Followed() {
followed[keys.EscapeName(b)] = true
}
p.revisions.free(followed)
return followed[branch]
}
// revisionsKept keeps the catalog revisions grants-for read, whole, as manifests by module (design 47 H H-A-195): a revision
// never changes, so one read is read for good (as the runner keeps its revisionCache), a cache of the catalog seat's own truth
// and never a state of the mesh. Each is kept by the branch grants-for was asked of (escaped as a key name is), its kind,
// group, heads and number; the newest few of each followed branch are kept in memory for the process's life. It also
// holds what the catalog-revision event names (H-A-193): each branch's newest trunk revision, and the revision each source
// revision was taken in as, so grants-for asks the seat mesh-catalog's revision only for a revision it does not hold, never
// to learn the newest.
@@ -70,7 +124,7 @@ func (k *revisionsKept) get(branch string, r meshcatalog.CatalogRevision) (map[s
return m, ok
}
func (k *revisionsKept) put(branch string, r meshcatalog.CatalogRevision, manifests map[string]catalogue.Manifest) {
func (k *revisionsKept) put(branch string, r meshcatalog.CatalogRevision, manifests map[string]catalogue.Manifest, max int) {
k.mu.Lock()
defer k.mu.Unlock()
k.init()
@@ -79,16 +133,48 @@ func (k *revisionsKept) put(branch string, r meshcatalog.CatalogRevision, manife
k.order[branch] = append(k.order[branch], key)
}
k.kept[key] = manifests
for len(k.order[branch]) > revisionsKeptPerBranch {
for len(k.order[branch]) > max {
delete(k.kept, k.order[branch][0])
k.order[branch] = k.order[branch][1:]
}
if r.Kind != "candidate" && r.Source != 0 {
k.sourceLocked(branch, r.Source, r.Revision)
k.sourceLocked(branch, r.Source, r.Revision, max)
}
}
func (k *revisionsKept) sourceLocked(branch string, source, revision int64) {
// free drops what is kept of each branch not in followed.
func (k *revisionsKept) free(followed map[string]bool) {
k.mu.Lock()
defer k.mu.Unlock()
for _, m := range []map[string]bool{boolsOf(k.order), boolsOf(k.newest), boolsOf(k.sources)} {
for branch := range m {
if !followed[branch] {
k.dropLocked(branch)
}
}
}
}
func boolsOf[V any](m map[string]V) map[string]bool {
out := map[string]bool{}
for k := range m {
out[k] = true
}
return out
}
// dropLocked drops everything kept of branch.
func (k *revisionsKept) dropLocked(branch string) {
for _, key := range k.order[branch] {
delete(k.kept, key)
}
delete(k.order, branch)
delete(k.newest, branch)
delete(k.sources, branch)
delete(k.sourced, branch)
}
func (k *revisionsKept) sourceLocked(branch string, source, revision int64, max int) {
if k.sources[branch] == nil {
k.sources[branch] = map[int64]int64{}
}
@@ -96,7 +182,7 @@ func (k *revisionsKept) sourceLocked(branch string, source, revision int64) {
k.sourced[branch] = append(k.sourced[branch], source)
}
k.sources[branch][source] = revision
for len(k.sourced[branch]) > 2*revisionsKeptPerBranch {
for len(k.sourced[branch]) > 2*max {
delete(k.sources[branch], k.sourced[branch][0])
k.sourced[branch] = k.sourced[branch][1:]
}
@@ -104,21 +190,16 @@ func (k *revisionsKept) sourceLocked(branch string, source, revision int64) {
// heard takes a trunk revision a catalog-revision event names as its branch's newest. One below the newest held is the
// numbering started again (design 47 H H-A-141): what is kept of the branch was of the earlier numbering, and is dropped.
func (k *revisionsKept) heard(branch string, revision, source int64) {
func (k *revisionsKept) heard(branch string, revision, source int64, max int) {
k.mu.Lock()
defer k.mu.Unlock()
k.init()
if held, ok := k.newest[branch]; ok && revision < held {
for _, key := range k.order[branch] {
delete(k.kept, key)
}
delete(k.order, branch)
delete(k.sources, branch)
delete(k.sourced, branch)
k.dropLocked(branch)
}
k.newest[branch] = revision
if source != 0 {
k.sourceLocked(branch, source, revision)
k.sourceLocked(branch, source, revision, max)
}
}
@@ -157,10 +238,10 @@ func (p *Part) HearCatalogRevision(_ context.Context, data []byte) error {
if err := json.Unmarshal(data, &ev); err != nil || ev.Revision <= 0 {
return fmt.Errorf("not a %s event: %.200s", meshcatalog.EventCatalogRevision, data)
}
if ev.Kind == "candidate" {
if ev.Kind == "candidate" || !p.following(ev.Branch) {
return nil
}
p.revisions.heard(ev.Branch, ev.Revision, ev.Source)
p.revisions.heard(ev.Branch, ev.Revision, ev.Source, p.revisionsPerBranch())
return nil
}
@@ -172,6 +253,7 @@ func (p *Part) HearCatalogRevision(_ context.Context, data []byte) error {
// revision though a newer one is written between them; a revision whose pages name another is not kept.
func (p *Part) revisionEntries(in meshcatalog.RevisionInput) (manifests map[string]catalogue.Manifest, none bool, err error) {
branch := in.Branch
followed := p.following(branch)
newestAsked := in.Group == "" && in.Heads == "" && in.Source == 0 && in.Revision == 0
if n, ok := p.revisions.known(in); ok {
if m, held := p.revisions.get(branch, meshcatalog.CatalogRevision{Revision: n}); held {
@@ -200,7 +282,7 @@ func (p *Part) revisionEntries(in meshcatalog.RevisionInput) (manifests map[stri
case a.Revision == nil:
keep = false
case first == nil:
if newestAsked {
if newestAsked && followed {
p.revisions.asked(branch, a.Revision.Revision)
}
if m, ok := p.revisions.get(branch, *a.Revision); ok {
@@ -225,8 +307,8 @@ func (p *Part) revisionEntries(in meshcatalog.RevisionInput) (manifests map[stri
manifests[e.Module] = m
}
if a.Next == "" || a.Next == in.After {
if keep && first != nil {
p.revisions.put(branch, *first, manifests)
if keep && first != nil && followed {
p.revisions.put(branch, *first, manifests, p.revisionsPerBranch())
}
return manifests, false, nil
}
@@ -194,6 +194,12 @@ type Part struct {
// SeatList is the seat list reader, which gates a module whose seats the list has not named (inputs.go, SeatGate); nil
// gates none.
SeatList SeatGate
// RevisionsPerBranch is the setting grants-for-revisions-per-branch, read at the start (grantsfor.go, design 47 H H-A-195);
// 0 is its default.
RevisionsPerBranch int
// Followed is the watched branches the part follows, as named (the branch follower's): grants-for keeps the revisions
// of these alone, and frees a branch's once it leaves them; nil in the tools, where every branch is kept.
Followed func() []string
cache Manifests
// revisions are the catalog revisions grants-for read, kept whole by their number (grantsfor.go).
+20 -1
View File
@@ -64,6 +64,16 @@
"seat:mesh-broker.list",
"seat:mesh-recovery.kept-points"
],
"config": {
"grants-for-revisions-per-branch": {
"type": "number",
"description": "how many catalog revisions of one watched branch the grants part keeps once read for grants-for, a run's candidate counted within its branch's, the oldest dropped first; each some 1.4 MB (design 47 H H-A-195).",
"minimum": 1,
"maximum": 32,
"trusted": false,
"default": 4
}
},
"emits": [
"asserted",
"grant-written",
@@ -156,6 +166,14 @@
"place": ".",
"unknown": "program"
},
{
"id": "grants-for-revisions-per-branch",
"type": "file",
"path": "${dir:state}/grants-for-revisions-per-branch",
"owner": "mesh-grants",
"mode": "0600",
"content": "${config:grants-for-revisions-per-branch}"
},
{
"id": "grants",
"type": "process",
@@ -165,7 +183,8 @@
"./mesh-grants"
],
"env": {
"MESH_BROKER_FILE": "${dir:state}/broker"
"MESH_BROKER_FILE": "${dir:state}/broker",
"MESH_GRANTS_REVISIONS_PER_BRANCH_FILE": "${dir:state}/grants-for-revisions-per-branch"
},
"user": "mesh-grants",
"health": {