diff --git a/modules/mesh-grants/cmd/mesh-grants/main.go b/modules/mesh-grants/cmd/mesh-grants/main.go index c09db75b..f9d392ea 100644 --- a/modules/mesh-grants/cmd/mesh-grants/main.go +++ b/modules/mesh-grants/cmd/mesh-grants/main.go @@ -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 diff --git a/modules/mesh-grants/grants_test.go b/modules/mesh-grants/grants_test.go index c2229f64..7b710dc2 100644 --- a/modules/mesh-grants/grants_test.go +++ b/modules/mesh-grants/grants_test.go @@ -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 } diff --git a/modules/mesh-grants/internal/grants/grantsfor.go b/modules/mesh-grants/internal/grants/grantsfor.go index 21b36ef5..11216665 100644 --- a/modules/mesh-grants/internal/grants/grantsfor.go +++ b/modules/mesh-grants/internal/grants/grantsfor.go @@ -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 } diff --git a/modules/mesh-grants/internal/grants/part.go b/modules/mesh-grants/internal/grants/part.go index 744f40a7..786065d8 100644 --- a/modules/mesh-grants/internal/grants/part.go +++ b/modules/mesh-grants/internal/grants/part.go @@ -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). diff --git a/modules/mesh-grants/module.json b/modules/mesh-grants/module.json index 29c8489b..75b3d55d 100644 --- a/modules/mesh-grants/module.json +++ b/modules/mesh-grants/module.json @@ -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": {