Files
mesh-delivery/modules/mesh-grants/internal/grants/grantsfor.go
T
jschoubben 120a0554d6 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
2026-11-20 21:51:43 +01:00

444 lines
15 KiB
Go

package grants
import (
"context"
"encoding/json"
"errors"
"fmt"
"io/fs"
"maps"
"os"
"slices"
"sort"
"strconv"
"strings"
"sync"
"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
// module, added and removed against the branch's newest. The candidate's catalog half is taken by mesh-catalog's `revision` (a
// run by its group `run-<id>`, a source revision by the branch and `source`), the branch's newest by `revision` with the branch
// alone; the answer is what the composed memberships' permissions gain and lose with the candidate's entries swapped in for the
// branch's newest.
// RunGroup is the group of a run's candidate in mesh-catalog's `revision` (A-205).
const RunGroup = "run-"
// CallRevision is the seat mesh-catalog's `revision`, as the part calls it.
const CallRevision = "seat:" + meshcatalog.Seat + "." + meshcatalog.VerbRevision
// 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
// 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.
type revisionsKept struct {
mu sync.Mutex
order map[string][]string
kept map[string]map[string]catalogue.Manifest
newest map[string]int64
sources map[string]map[int64]int64
sourced map[string][]int64
}
// revisionKey names a revision of branch; every kind but a candidate's is the branch's own series.
func revisionKey(branch string, r meshcatalog.CatalogRevision) string {
if r.Kind != "candidate" {
r.Kind, r.Group, r.Heads = "trunk", "", ""
}
return strings.Join([]string{branch, r.Kind, r.Group, r.Heads, strconv.FormatInt(r.Revision, 10)}, "\x00")
}
func (k *revisionsKept) init() {
if k.kept == nil {
k.kept, k.order, k.newest = map[string]map[string]catalogue.Manifest{}, map[string][]string{}, map[string]int64{}
k.sources, k.sourced = map[string]map[int64]int64{}, map[string][]int64{}
}
}
func (k *revisionsKept) get(branch string, r meshcatalog.CatalogRevision) (map[string]catalogue.Manifest, bool) {
k.mu.Lock()
defer k.mu.Unlock()
m, ok := k.kept[revisionKey(branch, r)]
return m, ok
}
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()
key := revisionKey(branch, r)
if _, ok := k.kept[key]; !ok {
k.order[branch] = append(k.order[branch], key)
}
k.kept[key] = manifests
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, max)
}
}
// 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{}
}
if _, ok := k.sources[branch][source]; !ok {
k.sourced[branch] = append(k.sourced[branch], source)
}
k.sources[branch][source] = revision
for len(k.sourced[branch]) > 2*max {
delete(k.sources[branch], k.sourced[branch][0])
k.sourced[branch] = k.sourced[branch][1:]
}
}
// 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, max int) {
k.mu.Lock()
defer k.mu.Unlock()
k.init()
if held, ok := k.newest[branch]; ok && revision < held {
k.dropLocked(branch)
}
k.newest[branch] = revision
if source != 0 {
k.sourceLocked(branch, source, revision, max)
}
}
// asked takes the newest revision an ask answered, when no event named one since the start (H-A-193: it asks once).
func (k *revisionsKept) asked(branch string, revision int64) {
k.mu.Lock()
defer k.mu.Unlock()
k.init()
if _, ok := k.newest[branch]; !ok {
k.newest[branch] = revision
}
}
// known is the revision in names that the part knows the number of without asking: the branch's newest an event named, or
// the revision a source revision was taken in as; false when it knows none.
func (k *revisionsKept) known(in meshcatalog.RevisionInput) (int64, bool) {
k.mu.Lock()
defer k.mu.Unlock()
switch {
case in.Group != "" || in.Heads != "" || in.Revision != 0:
return 0, false
case in.Source != 0:
n, ok := k.sources[in.Branch][in.Source]
return n, ok
default:
n, ok := k.newest[in.Branch]
return n, ok
}
}
// HearCatalogRevision takes one catalog-revision event of the seat mesh-catalog, as the part's process hears it (design 47 H
// H-A-193): a trunk revision is its branch's newest, and the revision its source revision was taken in as; a candidate's moves
// nothing here. Data that is no such event is an error.
func (p *Part) HearCatalogRevision(_ context.Context, data []byte) error {
var ev meshcatalog.CatalogRevisionEvent
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" || !p.following(ev.Branch) {
return nil
}
p.revisions.heard(ev.Branch, ev.Revision, ev.Source, p.revisionsPerBranch())
return nil
}
// revisionEntries reads a catalog graph revision's entries, page after page, as manifests by module. none says the branch has
// no revision yet. A revision whose number the part knows (the branch's newest an event named, a source revision's) and holds
// is answered from what it holds with no read; one it knows but does not hold is read by that number. Otherwise a revision
// read whole is kept: once the first page of an answer names a revision that is kept, it is answered from what is kept,
// without the pages after it. The branch's newest is read on by the number its first page names, so its pages are of one
// 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 {
return m, false, nil
}
if newestAsked {
in.Revision = n
}
}
manifests = map[string]catalogue.Manifest{}
var first *meshcatalog.CatalogRevision
keep := true
for {
raw, err := p.Call.Call(CallRevision, in)
if err != nil {
return nil, false, fmt.Errorf("%s does not answer: %w", CallRevision, err)
}
var a meshcatalog.RevisionAnswer
if err := json.Unmarshal(raw, &a); err != nil {
return nil, false, fmt.Errorf("%s answered what is not a revision: %w", CallRevision, err)
}
if a.NoneYet {
return nil, true, nil
}
switch {
case a.Revision == nil:
keep = false
case first == nil:
if newestAsked && followed {
p.revisions.asked(branch, a.Revision.Revision)
}
if m, ok := p.revisions.get(branch, *a.Revision); ok {
return m, false, nil
}
first = a.Revision
if newestAsked {
in.Revision = a.Revision.Revision
}
case revisionKey(branch, *a.Revision) != revisionKey(branch, *first):
keep = false
}
for _, e := range a.Entries {
body, err := json.Marshal(e.Manifest)
if err != nil || len(e.Manifest) == 0 {
continue
}
m, err := catalogue.Decode(body)
if err != nil {
return nil, false, fmt.Errorf("the manifest of %s in the revision does not decode: %w", e.Module, err)
}
manifests[e.Module] = m
}
if a.Next == "" || a.Next == in.After {
if keep && first != nil && followed {
p.revisions.put(branch, *first, manifests, p.revisionsPerBranch())
}
return manifests, false, nil
}
in.After = a.Next
}
}
// grantsOfEntries is, by module, the subjects the composed accounts of that module may publish or subscribe, composed from in with
// the entries' manifests in place of the trunk's and of what runs.
func grantsOfEntries(in Inputs, entries map[string]catalogue.Manifest) (map[string]map[string]bool, error) {
in.Manifests = maps.Clone(in.Manifests)
in.Running = maps.Clone(in.Running)
for module, m := range entries {
in.Manifests[module] = m
for key := range in.Running {
if strings.HasSuffix(key, "."+module) {
delete(in.Running, key)
}
}
}
recs, _ := ListRecords(in)
users, refused, err := ComposeEach(recs)
if err != nil {
return nil, err
}
if len(refused) > 0 {
user := sortedKeys(refused)[0]
return nil, fmt.Errorf("the grants of %s do not compose: %s", user, refused[user])
}
out := map[string]map[string]bool{}
for _, u := range users {
_, module, ok := strings.Cut(u.User, ".")
if _, named := entries[module]; !ok || !named {
continue
}
if out[module] == nil {
out[module] = map[string]bool{}
}
for _, s := range append(slices.Clone(u.Publish), u.Subscribe...) {
out[module][s] = true
}
}
return out, nil
}
// verbOf names the verb, event or tool a subject is for: `mesh.seat.<seat>.<kind>.<name>…` and `mesh.mod.<module>.<kind>.<name>…`.
func verbOf(subject string) string {
parts := strings.Split(subject, ".")
if len(parts) >= 5 && parts[0] == "mesh" && (parts[1] == "seat" || parts[1] == "mod") {
return parts[4]
}
return ""
}
func grantList(subjects []string) []meshgrants.Grant {
out := []meshgrants.Grant{}
for _, s := range subjects {
out = append(out, meshgrants.Grant{Subject: s, Verb: verbOf(s)})
}
return out
}
// GrantsFor answers the verb grants-for.
func (p *Part) GrantsFor(in meshgrants.GrantsForInput) (meshgrants.GrantsFor, error) {
if in.Branch == "" {
return meshgrants.GrantsFor{}, errors.New("grants-for names the candidate's watched branch")
}
candidate := meshcatalog.RevisionInput{Branch: in.Branch}
switch {
case in.Run != "":
candidate.Group = RunGroup + in.Run
case in.Source != "":
n, err := strconv.ParseInt(in.Source, 10, 64)
if err != nil {
return meshgrants.GrantsFor{}, fmt.Errorf("the source revision %q is not a number", in.Source)
}
candidate.Source = n
default:
return meshgrants.GrantsFor{}, errors.New("grants-for names a source revision or a run")
}
cand, none, err := p.revisionEntries(candidate)
if err != nil || none {
return meshgrants.GrantsFor{Error: orWhy(err, "the candidate's catalog half is not held: the branch has no revision of it")}, nil
}
newest, none, err := p.revisionEntries(meshcatalog.RevisionInput{Branch: in.Branch})
if err != nil || none {
return meshgrants.GrantsFor{Error: orWhy(err, "the branch's newest catalog half is not held")}, nil
}
base := map[string]catalogue.Manifest{}
for module := range cand {
if m, ok := newest[module]; ok {
base[module] = m
}
}
input := p.inputs()
was, err := grantsOfEntries(input, base)
if err != nil {
return meshgrants.GrantsFor{Error: "the branch's newest does not compose: " + err.Error()}, nil
}
will, err := grantsOfEntries(input, cand)
if err != nil {
return meshgrants.GrantsFor{Error: "the candidate does not compose: " + err.Error()}, nil
}
var out meshgrants.GrantsFor
for _, module := range sortedKeys(will) {
var added, removed []string
for s := range will[module] {
if !was[module][s] {
added = append(added, s)
}
}
for s := range was[module] {
if !will[module][s] {
removed = append(removed, s)
}
}
if len(added)+len(removed) == 0 {
continue
}
sort.Strings(added)
sort.Strings(removed)
out.Modules = append(out.Modules, meshgrants.GrantsForModulesItem{Module: module, Added: grantList(added), Removed: grantList(removed)})
}
return out, nil
}
func orWhy(err error, why string) string {
if err != nil {
return err.Error()
}
return why
}