Merge commit '66df2aef' into feat/47-G-fix11-b1g

This commit is contained in:
2026-11-12 06:17:52 +01:00
36 changed files with 1349 additions and 216 deletions
@@ -1281,6 +1281,8 @@ type RevisionInput struct {
Heads string `json:"heads,omitempty"`
// a kept revision; absent: the newest of trunk, or of the candidate named
Revision int64 `json:"revision,omitempty"`
// a candidate's source revision: the revision of the branch's series taken in from it, with its entries (design 47 G section 441)
Source int64 `json:"source,omitempty"`
}
// RevisionAnswer is what revision answers.
@@ -266,6 +266,10 @@
"type": "string",
"description": "a candidate's heads"
},
"source": {
"type": "integer",
"description": "a candidate's source revision: the revision of the branch's series taken in from it, with its entries (design 47 G section 441)"
},
"after": {
"type": "string",
"description": "the last module of the page before; absent: the first page"
@@ -731,6 +731,8 @@ export interface RevisionInput {
"heads"?: string;
/** a kept revision; absent: the newest of trunk, or of the candidate named */
"revision"?: number;
/** a candidate's source revision: the revision of the branch's series taken in from it, with its entries (design 47 G section 441) */
"source"?: number;
}
/** is what revision answers. */
+90 -32
View File
@@ -2938,7 +2938,7 @@ func parseManifest(raw []byte, predefined catalogue.PredefinedList) (catalogue.M
}
}
problems = append(problems, invokeProblems(m)...)
problems = append(problems, waitProblems(m)...)
problems = append(problems, needsApprovalProblems(m)...)
problems = append(problems, replacesProblems(m)...)
problems = append(problems, UnitSettingProblems(m)...)
problems = append(problems, OwnerSettingProblems(m)...)
@@ -3390,43 +3390,103 @@ func replacesProblems(m catalogue.Manifest) []string {
return problems
}
// waitProblems judges the event families a module says a session may wait on (novox/hq ADR 0367 §2, §6):
// the tool runner's alone, each named whole — emitter and event, with no wildcard — and each once. Refused
// here, in the manifest's words, rather than at the composition of the bus's users.
func waitProblems(m catalogue.Manifest) []string {
if len(m.Waits) == 0 {
return nil
}
if !catalogue.IsToolRunner(m) {
return []string{fmt.Sprintf("%s says what a session waits on; only the tool runner's module (it says "+
"\"tool-runner\": true) declares waits (novox/hq ADR 0367 §2)", m.Module)}
}
// needsApprovalProblems refuses a mark the mesh cannot honour (design 46 *The approval mark* §4; design 34 every-event
// §32; ADR 0286 §4): a mark on a tool its tools do not list (where it lists them; a bundle's own tools are checked by
// the tool runner at load), on a verb its claims do not serve, or on an event neither its emits nor its streams' events
// carry; one name both one of its tools and one of its events; a tool or verb marked, or a held seat verb its seat
// marks, without operator-channel in uses (§7: a module marking only events needs none); and a tool or verb marked
// while every bundle it builds is run by one of its process resources, so its own program answers and no tool runner
// gates them. Each refusal names the entry and the rule.
func needsApprovalProblems(m catalogue.Manifest) []string {
var problems []string
seen := map[string]bool{}
for _, w := range m.Waits {
if strings.ContainsAny(w, "*>") {
problems = append(problems, fmt.Sprintf("%s waits on %q: a family is named one by one, never a "+
"wildcard (novox/hq ADR 0367 §2)", m.Module, w))
tools, events, served := map[string]bool{}, map[string]bool{}, map[string]map[string]bool{}
for _, t := range m.Tools {
tools[t] = true
}
for _, e := range m.Emits {
events[e] = true
}
for _, st := range m.Streams {
for _, e := range st.Events {
events[e] = true
}
}
for _, c := range m.Claims {
served[c.Name] = map[string]bool{}
for _, v := range c.ServesFor(m) {
served[c.Name][v] = true
}
}
var acts []string // the tools and verbs it marks, and the held seat verbs its seats mark
for _, e := range m.NeedsApproval {
seat, verb, dotted := strings.Cut(e, ".")
switch {
case tools[e] && events[e]:
problems = append(problems, fmt.Sprintf("%s marks %q in needs-approval, which names both one of its tools "+
"and one of its events: an entry names one thing (design 46 approval mark §4)", m.Module, e))
case events[e]:
case tools[e], dotted && served[seat][verb]:
acts = append(acts, e)
case dotted && served[seat] != nil:
problems = append(problems, fmt.Sprintf("%s marks the verb %q in needs-approval, which its claim of %s does "+
"not serve (ADR 0286 §4)", m.Module, e, seat))
case dotted:
problems = append(problems, fmt.Sprintf("%s marks %q in needs-approval, which is neither a verb its claims "+
"serve nor an event its emits or its streams' events carry (ADR 0286 §4; design 34 every-event §32)", m.Module, e))
case len(m.Tools) > 0:
problems = append(problems, fmt.Sprintf("%s marks the tool %q in needs-approval, which its tools do not list "+
"(ADR 0286 §4)", m.Module, e))
default: // a tool its bundle registers: the tool runner checks it at load (§4)
acts = append(acts, e)
}
}
marked := len(acts) > 0
for _, c := range m.Claims {
seat, ok := catalogue.SeatNamed(c.Name)
if !ok {
continue
}
tokens := strings.Split(w, ".")
whole := len(tokens) >= 2 && name.MatchString(tokens[0])
for _, t := range tokens[1:] {
whole = whole && waitToken.MatchString(t)
for _, v := range seat.Serves {
if v.NeedsApproval && served[c.Name][v.Name] {
acts = append(acts, c.Name+"."+v.Name)
}
}
if !whole {
problems = append(problems, fmt.Sprintf("%s waits on %q, which does not name an emitter and an "+
"event: a family is <emitter>.<event>, as consumes names one", m.Module, w))
continue
}
if seen[w] {
problems = append(problems, fmt.Sprintf("%s waits on %q twice", m.Module, w))
}
seen[w] = true
}
if len(acts) > 0 && !slices.Contains(m.Uses, "operator-channel") {
problems = append(problems, fmt.Sprintf("%s marks or holds a marked tool or verb (%s) without operator-channel in "+
"uses: its tool runner asks the operator through that seat (design 46 approval mark §4, §7)",
m.Module, strings.Join(acts, ", ")))
}
if marked && everyBundleRunByAProcess(m) {
problems = append(problems, fmt.Sprintf("%s marks a tool or verb while every bundle it builds is run by one of "+
"its process resources: its own program answers them and no tool runner gates them, so the mark would guard "+
"nothing (design 46 approval mark §4)", m.Module))
}
return problems
}
// everyBundleRunByAProcess says every artifact of kind bundle the module builds is the artifact of one of its process
// resources (none built is every one run so: no tool runner loads any).
func everyBundleRunByAProcess(m catalogue.Manifest) bool {
run := map[string]bool{}
for _, r := range m.Resources {
if r["type"] == "process" {
if a, ok := r["artifact"].(string); ok {
run[a] = true
}
}
}
if m.Build == nil {
return true
}
for _, a := range m.Build.Artifacts {
if a.Kind == "bundle" && !run[a.Name] {
return false
}
}
return true
}
// whileStoppedProblems judges one container's maintenance window against its own definition
// (novox/hq ADR 0189).
//
@@ -3646,8 +3706,6 @@ var renamed = map[string]string{
var toolName = regexp.MustCompile(`^[a-z0-9][a-z0-9_-]*$`)
var waitToken = regexp.MustCompile(`^[a-z0-9][a-z0-9_-]*$`)
var engineGeneric = map[string]string{
"database": "postgres-database, mssql-database, mariadb-database",
"db": "postgres-database, mssql-database, mariadb-database",
@@ -3156,28 +3156,56 @@ func caseAVerbWithAnUnknownKeyIsRefused(t *testing.T) {
}
}
// A family is named one by one, never by a wildcard, and only by the tool runner's module (ADR 0367 §2, §6):
// each refusal is said in the manifest's words, at parse, rather than at the composition of the bus's users.
func caseAWaitIsRefusedUnlessItNamesOneFamilyOfTheToolRunner(t *testing.T) {
for manifest, want := range map[string]string{
`{"module":"shop","version":"1.0","waits":["mesh-knowledge.reviewed"]}`: "only the tool runner's module",
`{"module":"node-tools","version":"1.0","waits":["mesh-knowledge.reviewed"]}`: "only the tool runner's module", // its name says nothing (issue 774)
`{"module":"node-tools","version":"1.0","tool-runner":true,"waits":["mesh-knowledge.*"]}`: "never a wildcard",
`{"module":"node-tools","version":"1.0","tool-runner":true,"waits":["**"]}`: "never a wildcard",
`{"module":"node-tools","version":"1.0","tool-runner":true,"waits":["mesh-knowledge.>"]}`: "never a wildcard",
`{"module":"node-tools","version":"1.0","tool-runner":true,"waits":["*.reviewed"]}`: "never a wildcard",
`{"module":"node-tools","version":"1.0","tool-runner":true,"waits":["reviewed"]}`: "does not name an emitter and an event",
`{"module":"node-tools","version":"1.0","tool-runner":true,"waits":["mesh-knowledge..reviewed"]}`: "does not name an emitter and an event",
`{"module":"node-tools","version":"1.0","tool-runner":true,"waits":["Mesh-Knowledge.reviewed x"]}`: "does not name an emitter and an event",
`{"module":"node-tools","version":"1.0","tool-runner":true,"waits":["a.b","a.b"]}`: "twice",
// EE-D4 (design 34 every-event §10; ADR 0670 §2, ADR 0578 §1): the manifest no longer names what a session waits on, so
// `waits` is a field the validator does not know: refused by the checker's Shelf naming it, set aside to wait by the
// indexer's ShelfWaiting; the tool runner's manifest without it is accepted.
func caseAManifestCarryingWaitsIsAFieldNotKnown(t *testing.T) {
raws := map[string][]byte{
"node-tools": []byte(`{"module":"node-tools","version":"1.0","tool-runner":true,"waits":["mesh-knowledge.reviewed"]}`),
"runner": []byte(`{"module":"runner","version":"1.0","tool-runner":true}`),
}
if strict, _ := Shelf(raws, nil, 0); len(strict) != 1 || !strings.Contains(strings.Join(strict["node-tools"], " "), "waits") {
t.Errorf("Shelf on a manifest carrying waits: %v", strict)
}
if refused, waits, _ := ShelfWaiting(raws, nil, 0, nil, nil); len(refused) != 0 ||
!reflect.DeepEqual(waits, map[string][]string{"node-tools": {"waits"}}) {
t.Errorf("ShelfWaiting on a manifest carrying waits: refused %v, waits %v", refused, waits)
}
}
// AM-D1 (design 46 approval mark §4, §21; design 34 every-event §32): a mark nothing enforces is refused, naming the
// entry and the rule; the login shell's and the forge's manifests of §21 are accepted, and a module marking only events
// needs no operator-channel.
func caseAMarkNothingEnforcesIsRefused(t *testing.T) {
const bundle = `"build":{"artifacts":[{"name":"tools","kind":"bundle","language":"typescript","entrypoints":["tools/index.js"]}]}`
const oc = `"uses":["operator-channel"]`
shell := `{"module":"zsh","claims":[{"name":"node-login-shell","scope":"node","serves":["execute"]}],"tools":["zsh_config"],` + bundle
for _, row := range []struct{ name, manifest, want string }{
{"a tool its tools do not list", `{"module":"shop","tools":["sell"],"needs-approval":["refund"],` + oc + `,` + bundle + `}`, "its tools do not list"},
{"a verb its claims do not serve", `{"module":"shop","claims":[{"name":"shop-till","serves":["price"]}],"tools":["price"],"needs-approval":["shop-till.refund"],` + oc + `,` + bundle + `}`, "does not serve"},
{"a marked tool without operator-channel", `{"module":"shop","tools":["sell"],"needs-approval":["sell"],` + bundle + `}`, "without operator-channel"},
{"a held seat verb its seat marks without operator-channel", shell + `}`, "without operator-channel"},
{"every bundle run by its own process", `{"module":"shop","tools":["sell"],"needs-approval":["sell"],` + oc + `,` + bundle +
`,"resources":[{"id":"serve","type":"process","artifact":"tools","user":"shop"}]}`, "every bundle it builds is run"},
{"one name a tool and an event", `{"module":"shop","tools":["sold"],"emits":["sold"],"needs-approval":["sold"],` + oc + `,` + bundle + `}`, "both one of its tools"},
{"an event it does not carry", `{"module":"shop","emits":["sold"],"needs-approval":["sold.again"]}`, "nor an event its emits"},
{"the login shell", shell + `,` + oc + `}`, ""},
{"the forge", `{"module":"forge","needs-approval":["gitea_branch_protection_loosen"],` + oc + `,"build":{"artifacts":[` +
`{"name":"code","kind":"bundle","language":"typescript","entrypoints":["tools/index.js"],"loads":["tools/index.js"]},` +
`{"name":"repositories","kind":"bundle","language":"typescript","entrypoints":["repositories/index.js"]}]},` +
`"resources":[{"id":"repositories","type":"process","artifact":"repositories","user":"forge"}]}`, ""},
{"only events, no operator-channel", `{"module":"shop","emits":["sold"],"streams":[{"name":"ledger","events":["booked"],"max-age-days":1,"max-mib":1}],"needs-approval":["sold","booked"]}`, ""},
} {
_, err := ParseManifest([]byte(manifest))
if err == nil {
t.Errorf("accepted: %s", manifest)
continue
}
if !strings.Contains(err.Error(), want) {
t.Errorf("%s refused for the wrong reason (want %q): %v", manifest, want, err)
var problems []string
WithSeats([]catalogue.Seat{{Name: "node-login-shell", Serves: []catalogue.Verb{{Name: "execute", NeedsApproval: true}}}}, func() {
_, problems = Manifest(versioned(t, []byte(row.manifest)), nil)
})
got := strings.Join(problems, "\n")
switch {
case row.want == "" && got != "":
t.Errorf("%s is refused: %s", row.name, got)
case row.want != "" && !strings.Contains(got, row.want):
t.Errorf("%s: problems %q, want one saying %q", row.name, got, row.want)
}
}
}
@@ -3983,7 +4011,7 @@ func caseNoModuleMayDeclareTheLoginShell(t *testing.T) {
t.Fatalf("declaring login-shell was not refused by name: %q", got)
}
// And a shell module claiming the mesh's seat, serving execute, is what the seat is for.
m, err := ParseManifest([]byte(`{"module":"zsh","tools":["execute"],` +
m, err := ParseManifest([]byte(`{"module":"zsh","tools":["execute"],"uses":["operator-channel"],` +
`"claims":[{"name":"node-login-shell","scope":"node"}]}`))
if err != nil {
t.Fatal(err)
@@ -6355,7 +6383,7 @@ func TestRulesBus(t *testing.T) {
t.Run("AServedValueNamingSomethingTheMeshDoesNotHaveIsRefused", caseAServedValueNamingSomethingTheMeshDoesNotHaveIsRefused)
t.Run("ASiteScopedProvisionIsRefused", caseASiteScopedProvisionIsRefused)
t.Run("AStateNameIsLocalAndOneToken", caseAStateNameIsLocalAndOneToken)
t.Run("AWaitIsRefusedUnlessItNamesOneFamilyOfTheToolRunner", caseAWaitIsRefusedUnlessItNamesOneFamilyOfTheToolRunner)
t.Run("AManifestCarryingWaitsIsAFieldNotKnown", caseAManifestCarryingWaitsIsAFieldNotKnown)
t.Run("AWorkQueueStreamIsReadByExactlyOneProcessOfItsModule", caseAWorkQueueStreamIsReadByExactlyOneProcessOfItsModule)
t.Run("AWorkQueueStreamsValuesAreBounded", caseAWorkQueueStreamsValuesAreBounded)
t.Run("AZoneMustNameOneOfTheModulesListens", caseAZoneMustNameOneOfTheModulesListens)
@@ -6391,6 +6419,7 @@ func TestRulesCatalogue(t *testing.T) {
// TestRulesManifests runs the tests of one kind as subtests, each by its former name.
func TestRulesManifests(t *testing.T) {
t.Run("AMalformedEnvironmentIsRefusedAtParse", caseAMalformedEnvironmentIsRefusedAtParse)
t.Run("AMarkNothingEnforcesIsRefused", caseAMarkNothingEnforcesIsRefused)
t.Run("AMalformedFamilyIsRefused", caseAMalformedFamilyIsRefused)
t.Run("AMalformedPromptIsRefused", caseAMalformedPromptIsRefused)
t.Run("AManifestIsJudgedAgainstTheListOfItsTree", caseAManifestIsJudgedAgainstTheListOfItsTree)
@@ -13,6 +13,8 @@ was mesh-controller's copy, which still held two modules that had left the catal
mesh-catalog b5dbfbb784507e211372a7c9640d91f7d6dadd84 modules/*/module.json, modules/*/files/**, modules/*/templates/**, predefined.json
mesh-host 233bb23bbcb1a829ce2a6164a31a5c5cc4f3d950 internal/apply/placement_guard.go
mesh-catalog 2d5358b8 (milestone 47/G's AM-K1) modules/zsh/module.json alone: the login shell uses operator-channel for
its seat's marked execute (design 46 approval mark §21), which the validator requires (§4)
To move them, from mesh-delivery's modules/mesh-delivery-indexer directory, with the two repositories checked out
beside mesh-delivery:
@@ -1,6 +1,6 @@
{
"module": "zsh",
"version": "1",
"version": "0.1",
"moved": true,
"capabilities": [
"package-manager"
@@ -14,6 +14,9 @@
]
}
],
"uses": [
"operator-channel"
],
"tools": [
"zsh_config"
],
@@ -11,10 +11,12 @@ import (
"os"
"path/filepath"
"slices"
"strings"
"testing"
"time"
"git.novox.be/novox/mesh-delivery/modules/mesh-grants/grantsstate"
sdkbc "git.novox.be/novox/mesh-sdk/go/buscompose"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/process"
"git.novox.be/novox/mesh-sdk/go/seal"
@@ -403,3 +405,221 @@ func manifestIn(t *testing.T, module string) catalogue.Manifest {
}
return m
}
// composedBus is a server loading the accounts composed from records, its conf file rewritten and reloaded by recompose.
type composedBus struct {
t *testing.T
s *server.Server
conf string
}
func startComposedBus(t *testing.T, records buscompose.Records) *composedBus {
dir := t.TempDir()
b := &composedBus{t: t, conf: filepath.Join(dir, "server.conf")}
b.write(records, dir)
opts, err := server.ProcessConfigFile(b.conf)
if err != nil {
t.Fatalf("the composed list is not the server's: %v", err)
}
opts.NoLog, opts.NoSigs = true, true
if b.s, err = server.NewServer(opts); err != nil {
t.Fatal(err)
}
go b.s.Start()
if !b.s.ReadyForConnections(30 * time.Second) {
t.Fatal("the bus did not come up")
}
t.Cleanup(b.s.Shutdown)
return b
}
func (b *composedBus) write(records buscompose.Records, dir string) {
users, err := buscompose.Users(records)
if err != nil {
b.t.Fatal(err)
}
for i := range users {
users[i].PasswordHash = "pw-" + users[i].Username()
}
accounts, err := buscompose.ComposeAccounts(users)
if err != nil {
b.t.Fatal(err)
}
if err := os.WriteFile(b.conf, []byte("listen: 127.0.0.1:-1\njetstream { store_dir: \""+dir+"\" }\n"+accounts), 0o600); err != nil {
b.t.Fatal(err)
}
}
// recompose writes the accounts composed from records again and has the server load them.
func (b *composedBus) recompose(records buscompose.Records) {
b.write(records, filepath.Dir(b.conf))
if err := b.s.Reload(); err != nil {
b.t.Fatalf("the server does not load the composed list again: %v", err)
}
}
// dial connects as a composed user; the server's refusals of its subscriptions and publishes arrive on refusals.
func (b *composedBus) dial(user string) (*nats.Conn, chan string) {
refusals := make(chan string, 16)
nc, err := nats.Connect(b.s.ClientURL(), nats.UserInfo(user, "pw-"+user), nats.CustomInboxPrefix("_INBOX."+user),
nats.ErrorHandler(func(_ *nats.Conn, _ *nats.Subscription, err error) { refusals <- err.Error() }))
if err != nil {
b.t.Fatalf("%s: %v", user, err)
}
b.t.Cleanup(nc.Close)
return nc, refusals
}
// refusedWithin waits, within a bound, for the server's refusal naming subject.
func refusedWithin(refusals chan string, subject string) bool {
bound := time.NewTimer(5 * time.Second)
defer bound.Stop()
for {
select {
case e := <-refusals:
if strings.Contains(e, "Permissions Violation") && strings.Contains(e, subject) {
return true
}
case <-bound.C:
return false
}
}
}
// theToolRunnerHearsEveryEventOnTheBus, run by TestTheGrantsPartWhole, defends design 34 every-event §9 and §27 on a
// real server (ADR 0670 §1, §3, ADR 0671 §1, §2): the tool runner's account, as composed, hears a module's event, a
// module stream's and a restricted stream's whose grant value names no tool runner, still after that value changes and
// the accounts are composed again; it publishes none of them, hears no accept or proof, and gets no durable consumer
// and no acknowledgement on the restricted stream; another module hears no event it does not consume, and a module
// consuming the restricted stream with no entry in its grant value gets no consumer and no read.
func theToolRunnerHearsEveryEventOnTheBus(t *testing.T) {
const ledger = "mesh.stream.shop.event.booked"
records := func(auditorEntry []string) buscompose.Records {
return buscompose.Records{Nodes: []string{"a"}, Assigned: map[string][]buscompose.Declared{"a": {
{Module: buscompose.GrantsModule},
{Module: "node-tools", ToolRunner: true},
{Module: "mesh-delivery-view", Emits: []string{"delivered"}},
{Module: "plex"},
{Module: "shop", Streams: []buscompose.ModuleStream{
{Module: "shop", Name: "SHOP", Events: []string{"opened"}, MaxAgeDays: 1, MaxMiB: 1},
{Module: "shop", Name: "LEDGER", Events: []string{"booked"}, MaxAgeDays: 1, MaxMiB: 1, Restricted: true}}},
{Module: "auditor", RunsAs: "auditor", Consumes: []string{"shop.booked"},
Hears: []buscompose.Heard{{Stream: "LEDGER", Emitter: "shop", Filters: auditorEntry, Restricted: true}}},
}}}
}
bus := startComposedBus(t, records(nil))
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
refusedIn := func() context.Context {
c, stop := context.WithTimeout(ctx, 2*time.Second)
t.Cleanup(stop)
return c
}
grantsConn, _ := bus.dial("a." + buscompose.GrantsModule)
grants, err := jetstream.New(grantsConn)
if err != nil {
t.Fatal(err)
}
for _, st := range []jetstream.StreamConfig{{Name: "SHOP", Subjects: []string{"mesh.stream.shop.event.opened"}},
{Name: "LEDGER", Subjects: []string{ledger}}} {
if _, err := grants.CreateStream(ctx, st); err != nil {
t.Fatalf("the grants part creates the declared stream %s: %v", st.Name, err)
}
}
runner, runnerRefused := bus.dial("a.node-tools")
heard := make(chan *nats.Msg, 16)
for _, s := range sdkbc.EveryEvent() {
if _, err := runner.ChanSubscribe(s, heard); err != nil {
t.Fatal(err)
}
}
if err := runner.Flush(); err != nil {
t.Fatal(err)
}
hears := func(subject, from string) {
t.Helper()
select {
case m := <-heard:
if m.Subject != subject {
t.Errorf("the tool runner heard %s, want %s published by %s", m.Subject, subject, from)
}
case <-time.After(5 * time.Second):
t.Errorf("the tool runner heard nothing, want %s published by %s", subject, from)
}
}
view, _ := bus.dial("a.mesh-delivery-view")
shop, _ := bus.dial("a.shop")
for _, e := range []struct {
conn *nats.Conn
subject, from string
}{
{view, "mesh.mod.mesh-delivery-view.event.delivered", "the view"},
{shop, "mesh.stream.shop.event.opened", "a module's stream"},
{shop, ledger, "a restricted stream whose grant names no tool runner"}} {
if err := e.conn.Publish(e.subject, []byte(`{}`)); err != nil {
t.Fatal(err)
}
if err := e.conn.Flush(); err != nil {
t.Fatal(err)
}
hears(e.subject, e.from)
}
// It publishes no event, and hears no accept nor proof (they are never events).
if err := runner.Publish("mesh.mod.mesh-delivery-view.event.delivered", []byte(`{}`)); err != nil {
t.Fatal(err)
}
if !refusedWithin(runnerRefused, "mesh.mod.mesh-delivery-view.event.delivered") {
t.Error("the tool runner published the view's event")
}
for _, s := range []string{"mesh.seat.channel.accept.show.k", "mesh.seat.intake.proof.code.k"} {
if _, err := runner.SubscribeSync(s); err != nil {
t.Fatal(err)
}
if !refusedWithin(runnerRefused, s) {
t.Errorf("the tool runner subscribed %s", s)
}
}
// No durable consumer, no acknowledgement on the restricted stream.
runnerJS, err := jetstream.New(runner)
if err != nil {
t.Fatal(err)
}
if _, err := runnerJS.CreateConsumer(refusedIn(), "LEDGER", jetstream.ConsumerConfig{Durable: "node-tools"}); err == nil {
t.Error("the tool runner made a durable consumer on the restricted stream")
}
if err := runner.Publish("$JS.ACK.LEDGER.node-tools.1.1.1.1.0", nil); err != nil {
t.Fatal(err)
}
if !refusedWithin(runnerRefused, "$JS.ACK.LEDGER") {
t.Error("the tool runner acknowledged on the restricted stream")
}
// Another module hears no event it does not consume.
plex, plexRefused := bus.dial("a.plex")
if _, err := plex.SubscribeSync("mesh.mod.mesh-delivery-view.event.delivered"); err != nil {
t.Fatal(err)
}
if !refusedWithin(plexRefused, "mesh.mod.mesh-delivery-view.event.delivered") {
t.Error("plex subscribed an event it does not consume")
}
// A consumer of the restricted stream with no entry in its grant value gets no consumer and no read.
auditor, _ := bus.dial("a.auditor")
auditorJS, err := jetstream.New(auditor)
if err != nil {
t.Fatal(err)
}
if _, err := auditorJS.CreateConsumer(refusedIn(), "LEDGER", jetstream.ConsumerConfig{Durable: "auditor"}); err == nil {
t.Error("a consumer with no entry made a durable consumer on the restricted stream")
}
if _, err := auditorJS.Stream(refusedIn(), "LEDGER"); err == nil {
t.Error("a consumer with no entry reads the restricted stream")
}
// The grant value changes and the accounts are composed again: the tool runner still hears the restricted stream.
bus.recompose(records([]string{ledger}))
if err := shop.Publish(ledger, []byte(`{}`)); err != nil {
t.Fatal(err)
}
if err := shop.Flush(); err != nil {
t.Fatal(err)
}
hears(ledger, "the restricted stream after its grant value changed")
}
@@ -627,6 +627,7 @@ func TestTheGrantsPartWhole(t *testing.T) {
// And what the part composes holds on a server that loads it (one integration test per module, the test budget).
t.Run("the composed grants hold on a server that loads them", theBusNodeFollowsTheSealedListUnderTheComposedGrants)
t.Run("the tool runner hears every event on a server that loads its grants", theToolRunnerHearsEveryEventOnTheBus)
}
// lockedLog is the part's log, read by the test while the part writes it.
@@ -11,6 +11,7 @@ import (
"sync"
"time"
"git.novox.be/novox/mesh-contracts/identity-and-access/go/seats/meshgrants"
"git.novox.be/novox/mesh-sdk/go/seatlist"
"git.novox.be/novox/mesh-sdk/go/views"
@@ -257,6 +258,23 @@ func toolsOf(p *grants.Part) []stdio.Tool {
"composed yet by this version of the part, with its step, the acting part, its version, since when, its bound (10 minutes) and " +
"clock-from (the start of this version's first pass), and which have passed their bound. Read-only.",
Run: func(map[string]any) (any, error) { return p.WaitsOf() }},
{Name: grants.ToolCallers, Description: "The callers each verb and each accepted kind of the seat definitions admits (design 47 G §83): " +
"the list the definition names, or the default of the verb's class. Name a seat, or a seat and a verb, or neither for every one. Read-only.",
Input: schema(map[string]string{"seat": "a seat's name (default: every seat)", "verb": "a verb or accepted kind (default: every one)"}),
Run: func(a map[string]any) (any, error) {
return p.Callers(grants.Answer(a, "seat"), grants.Answer(a, "verb"))
}},
{Name: grants.ToolWhyRefused, Description: "Why an account's call of a seat's verb is refused (design 47 G §83): the call subject the account " +
"lacks a grant for (the bus's own answer, nats_user_can) and the definition's callers that leave it out. Read-only.",
Input: schema(map[string]string{"account": "the bus user, e.g. g14.node-tools", "verb": "the verb as <seat>.<verb>", "node": "the node, for a node seat"}, "account", "verb"),
Run: func(a map[string]any) (any, error) {
return p.WhyRefused(grants.Answer(a, "account"), grants.Answer(a, "verb"), grants.Answer(a, "node"))
}},
{Name: meshgrants.Seat + "." + meshgrants.VerbGrantsFor,
Description: "The grants a candidate would compose, per module (design 47 G §441): the grants it would add and remove against the branch's newest.",
Run: func(a map[string]any) (any, error) {
return p.GrantsFor(meshgrants.GrantsForInput{Branch: grants.Answer(a, "branch"), Run: grants.Answer(a, "run"), Source: grants.Answer(a, "source")})
}},
{Name: grants.ToolRelease, Description: "Release one held granting wait by a person's act with why, recorded as a hand act " +
"(the seat mesh-hand-acts) before it is released (design 47 G §276). grants_waits lists them.",
Input: schema(map[string]string{"module": "the held entry's module", "why": "why, kept in the hand act"}, "module", "why"),
+58 -6
View File
@@ -29,6 +29,7 @@ import (
"git.novox.be/novox/mesh-contracts/go/seats/meshmoduleassigner"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
"git.novox.be/novox/mesh-contracts/identity-and-access/go/clients/meshvaultclient"
"git.novox.be/novox/mesh-contracts/identity-and-access/go/seats/meshgrants"
"git.novox.be/novox/mesh-contracts/identity-and-access/go/seats/meshnodeenroller"
"git.novox.be/novox/mesh-contracts/identity-and-access/go/seats/meshvault"
occ "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/clients/operatorchannelclient"
@@ -91,8 +92,11 @@ type fakeBus struct {
maxValue int
// entries are the catalog half's entries by fingerprint, the manifest each holds as the indexer's manifests state has it
// (entry); entriesAsked says every one is asked, not answered: the half cannot be read yet.
entries map[string]string
entriesAsked bool
entries map[string]string
entriesAsked bool
// revision is the catalog half of mesh-catalog's `revision`: the branch's `newest` and a `candidate` (a source or a group), each
// module's manifest.
revision map[string]map[string]string
catalogWaited []string
}
@@ -363,6 +367,21 @@ func (b *fakeBus) Call(key string, body any) (json.RawMessage, error) {
}
}
return json.Marshal(map[string]any{"users": out})
case grants.CallRevision:
var in meshcatalog.RevisionInput
raw, _ := json.Marshal(body)
_ = json.Unmarshal(raw, &in)
which := "newest"
if in.Group != "" || in.Source != 0 {
which = "candidate"
}
var out meshcatalog.RevisionAnswer
for module, manifest := range b.revision[which] {
var m map[string]any
_ = json.Unmarshal([]byte(manifest), &m)
out.Entries = append(out.Entries, meshcatalog.CatalogEntry{Module: module, Manifest: m})
}
return json.Marshal(out)
case grants.CallStreams:
if stream, _ := args["stream"].(string); stream != "" {
return json.Marshal(map[string]any{"detail": []map[string]any{{"name": stream, "consumer_detail": b.consumers[stream]}}})
@@ -602,10 +621,9 @@ func TestGrants(t *testing.T) {
if err != nil {
t.Fatalf("mesh-sdk cannot decode the manifest: %v", err)
}
// The part claims no seat: the seat mesh-grants served the lease write alone, which went with the controller
// (novox/hq ADR 0590 §3, issue 1126).
if m.Module != "mesh-grants" || len(m.Claims) != 0 {
t.Errorf("module %q claims %v: the part claims no seat", m.Module, m.Claims)
// The part claims the seat mesh-grants, which serves `grants-for` (design 47 G §401, §441).
if m.Module != "mesh-grants" || len(m.Claims) != 1 || m.Claims[0].Name != "mesh-grants" || !slices.Equal(m.Claims[0].Serves, []string{"grants-for"}) {
t.Errorf("module %q claims %v: the part claims the seat mesh-grants alone, serving grants-for", m.Module, m.Claims)
}
for _, row := range []struct {
what string
@@ -5095,3 +5113,37 @@ func TestAnOldStateSectionDeclaresItsCap(t *testing.T) {
}
}
}
// grants-for answers what the composed accounts gain and lose with a candidate's entries in place of the branch's newest (design
// 47 G §441, A-205): a tool the candidate adds is an added grant naming its verb, and an input that names no source nor run is
// refused.
func TestGrantsFor(t *testing.T) {
b := fixture()
candidateX := strings.Replace(strings.Replace(xManifest, `,"logs":[{"name":"history","max-age-days":30}]`, "", 1), `"state"`, `"emits":["hello"],"state"`, 1)
b.revision = map[string]map[string]string{"newest": {"mod-x": xManifest}, "candidate": {"mod-x": candidateX}}
p := partOn(b)
got, err := p.GrantsFor(meshgrants.GrantsForInput{Branch: "main", Run: "r1"})
if err != nil || got.Error != "" || len(got.Modules) != 1 || got.Modules[0].Module != "mod-x" {
t.Fatalf("grants-for: %+v, %v", got, err)
}
var verbs []string
for _, g := range got.Modules[0].Added {
verbs = append(verbs, g.Verb+" "+g.Subject)
}
if !slices.ContainsFunc(got.Modules[0].Added, func(g meshgrants.Grant) bool {
return g.Verb == "hello" && strings.HasPrefix(g.Subject, "mesh.mod.mod-x.")
}) {
t.Errorf("the event the candidate adds is not an added grant: %v / %+v", verbs, got.Modules[0])
}
if len(got.Modules[0].Removed) == 0 {
t.Error("the log the candidate drops is no removed grant")
}
b.revision["candidate"] = b.revision["newest"]
same, _ := p.GrantsFor(meshgrants.GrantsForInput{Branch: "main", Source: "7"})
if len(same.Modules) != 0 {
t.Errorf("a candidate equal to the newest changes grants: %+v", same.Modules)
}
if _, err := p.GrantsFor(meshgrants.GrantsForInput{Branch: "main"}); err == nil {
t.Error("grants-for with neither a source nor a run answered")
}
}
@@ -20,6 +20,7 @@ import (
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-builder/builds"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-sdk/go/announce"
sdkbc "git.novox.be/novox/mesh-sdk/go/buscompose"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/seatdef"
"github.com/nats-io/nats.go/jetstream"
@@ -60,6 +61,8 @@ func TestTheCopiedComposerComposesAsTheControllers(t *testing.T) {
t.Run("a module's ledger is written by its ledger account alone", aLedgerIsWrittenByItsLedgerAccountAlone)
t.Run("the bus module's process alone keeps every module's bus state and serves the broker's verbs", theBusModulesProcessKeepsBusState)
t.Run("a process serving a verb is granted its calls and chunk subjects, and the reverse goes to an account naming it", chunkSubjectsFollowTheAnswerer)
t.Run("the tool runner's runtime hears every event subject and nothing wider", theToolRunnerHearsEveryEvent)
t.Run("a per-machine state reaches its machine's keys below it and no other machine's", aPerMachineStateReachesItsMachinesKeys)
// ADR 0567 §3, §9: a node reads every key of the seat's assignments and its candidates (it composes with the whole
// proposal laid over), and none of its open proposals; it writes neither.
reads := strings.Join(NodeComposeReads("laptop"), " ")
@@ -1447,3 +1450,111 @@ func chunkSubjectsFollowTheAnswerer(t *testing.T) {
t.Errorf("the keeper's restore grant reaches a stream that is not restricted")
}
}
// EE-D2 (design 34 every-event §6, §8, §25, §27; ADR 0670 §1, §3, ADR 0671 §1): the runtime carrying the tool runner
// subscribes the three event subjects of mesh-sdk's EveryEvent, beside a module with a restricted stream, and nothing
// wider; it publishes no other module's or seat's event and derives no durable consumer or acknowledgement on that
// stream; a runtime carrying no tool runner gets none of the three.
func theToolRunnerHearsEveryEvent(t *testing.T) {
shop := func() Declared {
return Declared{Module: "shop", Serves: []string{"sell"}, Emits: []string{"sold"},
Streams: []ModuleStream{{Module: "shop", Name: "LEDGER", Events: []string{"booked"}, Restricted: true}}}
}
r := Records{Nodes: []string{"a", "b"}, Assigned: map[string][]Declared{
"a": {{Module: "node-tools", ToolRunner: true}, shop()},
"b": {shop()}}}
users, err := Users(r)
if err != nil {
t.Fatal(err)
}
every := sdkbc.EveryEvent()
if len(every) != 3 {
t.Fatalf("EveryEvent answers %v, want three subjects", every)
}
wider := []string{">", "mesh.>", "mesh.*.>", "mesh.seat.>", "mesh.mod.>", "mesh.stream.>"}
runners := 0
for _, u := range users {
p, err := PermissionsFor(u)
if err != nil {
t.Fatalf("%s: %v", u.Username(), err)
}
runs := false
for _, d := range u.Carries {
runs = runs || d.ToolRunner
}
for _, e := range every {
if slices.Contains(p.Subscribe, e) != runs {
t.Errorf("%s (tool runner %v) subscribes %s: %v", u.Username(), runs, e, !runs)
}
}
for _, s := range p.Subscribe {
if slices.Contains(wider, s) {
t.Errorf("%s subscribes %s, wider than every event", u.Username(), s)
}
}
if !runs {
continue
}
runners++
for _, s := range p.Subscribe {
if strings.HasPrefix(s, "$JS.") && strings.Contains(s, "LEDGER") {
t.Errorf("the tool runner's runtime hears %s on the restricted stream", s)
}
}
for _, s := range []string{"mesh.mod.other.event.x", "mesh.seat.mesh-catalog.event.manifest-accepted",
"mesh.stream.other.event.x"} {
if MayPublish(p, s) {
t.Errorf("the tool runner's runtime may publish another's event %s", s)
}
}
for _, s := range p.Publish {
if strings.Contains(s, "LEDGER") || strings.HasPrefix(s, "$JS.ACK.") {
t.Errorf("the tool runner's runtime may %s on the restricted stream", s)
}
}
}
if runners != 1 {
t.Errorf("%d runtimes carry the tool runner, want 1", runners)
}
}
// AM-D5 (design 46 approval mark §13): a per-machine state reaches its machine's key and the keys below it, `<node>.>`,
// and no other machine's, on the account and in the membership alike.
func aPerMachineStateReachesItsMachinesKeys(t *testing.T) {
runner := func() Declared {
return Declared{Module: "node-tools", ToolRunner: true,
State: []Bucket{{Module: "node-tools", Name: "approvals", PerMachine: true, KeyTTL: true, TTLSeconds: 172800}}}
}
r := Records{Nodes: []string{"a", "b"}, Assigned: map[string][]Declared{"a": {runner()}, "b": {runner()}}}
users, err := Users(r)
if err != nil {
t.Fatal(err)
}
const bucket = "node-tools_approvals"
found := false
for _, u := range users {
if u.Username() != "a.node-tools" {
continue
}
found = true
p, err := PermissionsFor(u)
if err != nil {
t.Fatal(err)
}
for key, reach := range map[string]bool{"a": true, "a.ask.1": true, "a.act.d": true, "b": false, "b.ask.1": false, "ab.ask.1": false} {
if MayPublish(p, "$KV."+bucket+"."+key) != reach {
t.Errorf("a's runner writes %s's key %s: %v", bucket, key, !reach)
}
if MayPublish(p, "$JS.API.DIRECT.GET.KV_"+bucket+".$KV."+bucket+"."+key) != reach {
t.Errorf("a's runner reads %s's key %s: %v", bucket, key, !reach)
}
}
}
if !found {
t.Fatal("no account a.node-tools composed")
}
// The membership names the machine's key, which reaches the keys below it in the same form (mesh-sdk membership).
if issued := stateIssuedFor(runner(), "a"); len(issued) != 1 || issued[0].Key != "a" || issued[0].Bucket != bucket {
t.Errorf("a's membership issues %+v", issued)
}
}
@@ -249,6 +249,11 @@ func boundOf(module string, bindings []membership.BusBinding) boundGrants {
case catalogue.StorageKeyValue:
if b.Bucket == base {
g.States = append(g.States, b.Local)
// Its object store beside it, `<state>-objects`, is its owner's alone (design 47 G §58, §91): the one bucket the
// binding names for this module's own state.
if b.Objects != "" && b.Objects == module+"_"+catalogue.StateObjectsName(b.Local) {
g.Objects = append(g.Objects, b.Objects)
}
}
case catalogue.StorageObjectStore:
if b.ObjectStore == base {
@@ -115,3 +115,6 @@ func callerNamed(user string, pub, sub []string) ([]string, []string) {
}
return unique(pub), unique(sub)
}
// SeatToolSubject is where a seat's verb is served: `mesh.seat.<seat>.tool.<verb>`, with the node last on a node seat.
func SeatToolSubject(s Seat, verb, node string) string { return seatToolSubject(s, verb, node) }
@@ -64,7 +64,6 @@ func MembershipFor(node string, d Declared, where Assignments) Membership {
m.Logs = append(logsIssuedFor(d), readLogsIssuedFor(withReadLogs(d, where.Logs))...)
m.Streams = streamsIssuedFor(d)
m.Hears = HeardIssuedFor(node, d)
m.Waits = waitsIssuedFor(d)
t := SeatTrafficOf(d.Module, d.Holds, d.Uses, d.Watches)
for _, s := range append(append([]Seat{}, d.Uses...), d.Watches...) {
if !s.Kinded {
@@ -29,23 +29,12 @@ func ModuleStreamSubject(module, event string) string {
// OnAModuleStream says a subject is one a module's own stream takes.
func OnAModuleStream(subject string) bool { return strings.HasPrefix(subject, moduleStreamPrefix) }
// WirePattern is a local event pattern as the bus spells it: `**` is `>`.
func WirePattern(local string) string {
parts := strings.Split(local, ".")
for i, p := range parts {
if p == "**" {
parts[i] = ">"
}
}
return strings.Join(parts, ".")
}
// A ModuleStream is one module's declared stream as the bus holds it.
type ModuleStream struct {
Module string
// Name is its name on the bus, `MAIL`.
Name string
// Events are the events it carries, as the bus spells them (WirePattern).
// Events are the events it carries, as the bus spells them (mesh-sdk buscompose.WirePattern).
Events []string
MaxAgeDays int
MaxMiB int
@@ -0,0 +1,69 @@
package buscompose
import "testing"
// Design 47 G §543, §544, §600: a build seat's ask names its asker, each queue has a named worker beside main's, an asker
// is granted the queues of its kinds under its own seat's name alone, and main's subject is the checker's and the builder's.
func TestNamedAsks(t *testing.T) {
build := Seat{Name: "node-build-go", Scope: "node", Accepts: []string{"delivery", "check", "recheck"}, PulledByKind: true,
AcceptCallers: map[string][]string{
"delivery": {"mesh-builds"},
"check": {"mesh-pipeline-runner", "mesh-catalog", "mesh-delivery-checker"},
"recheck": {"mesh-delivery-checker"},
}}
asker := func(module string, held ...string) Principal {
p := Principal{Kind: KindModule, Node: "one", Module: module, Uses: []Seat{build}}
for _, h := range held {
p.Holds = append(p.Holds, Seat{Name: h})
}
return p
}
const base = "mesh.seat.node-build-go.accept."
for _, c := range []struct {
who Principal
want map[string]bool
}{
{asker("runner-module", "mesh-pipeline-runner"), map[string]bool{
base + "check.mesh-pipeline-runner": true, base + "delivery.mesh-pipeline-runner": false,
base + "check.mesh-catalog": false, base + "check": false, base + "delivery": false}},
{asker("an-indexer", "mesh-catalog"), map[string]bool{
base + "check.mesh-catalog": true, base + "check.mesh-pipeline-runner": false, base + "recheck.mesh-catalog": false}},
{asker("the-builder", "mesh-builds"), map[string]bool{
base + "delivery.mesh-builds": true, base + "delivery": true, base + "check": true, base + "check.mesh-builds": false}},
{asker("the-checker", "mesh-delivery-checker"), map[string]bool{
base + "check.mesh-delivery-checker": true, base + "recheck.mesh-delivery-checker": true, base + "recheck": true,
base + "delivery.mesh-delivery-checker": false}},
{asker("a-stranger"), map[string]bool{base + "check": false, base + "delivery": false, base + "check.a-stranger": false}},
} {
perms, err := PermissionsFor(c.who)
if err != nil {
t.Fatal(err)
}
for subject, want := range c.want {
if got := MayPublish(perms, subject); got != want {
t.Errorf("%s may publish %s: %v, want %v", c.who.Module, subject, got, want)
}
}
}
// Each queue's workers: main's and the named one, filtered to subjects that overlap nothing.
held := Seat{Name: "node-build-go", Scope: "node", Accepts: []string{"delivery", "check"}, PulledByKind: true}
tr := SeatTrafficOf("go-module", []Seat{held}, nil, nil)
filters := map[string]string{}
for _, w := range tr.Workers {
filters[w.Consumer] = w.Filter
}
for consumer, filter := range map[string]string{
"SEAT_NODE_BUILD_GO_CHECK_worker": base + "check",
"SEAT_NODE_BUILD_GO_CHECK_named_worker": base + "check.*",
"SEAT_NODE_BUILD_GO_DELIVERY_worker": base + "delivery",
"SEAT_NODE_BUILD_GO_DELIVERY_named_worker": base + "delivery.*",
} {
if filters[consumer] != filter {
t.Errorf("worker %s filters %q, want %q", consumer, filters[consumer], filter)
}
}
_, consumers := SeatTrafficObjects([]Principal{{Kind: KindModule, Node: "one", Module: "go-module", Holds: []Seat{held}}})
if len(consumers) != 4 {
t.Errorf("the work queue's consumers: %d, want 4 (a main and a named worker for each of two queues)", len(consumers))
}
}
@@ -103,6 +103,10 @@ type Seat struct {
// PulledByKind says each accepted kind is a worker of its own on the seat's queue, filtered to that kind, which
// every holder pulls in the order Accepts lists them: the build seats' (novox/hq ADR 0525 §2, ADR 0536 §4).
PulledByKind bool
// AcceptCallers are, for a seat pulled by kind, the seats that may ask each of its queues, by queue: the `seat:<seat>`
// entries of the callers of the accepted kinds the definition puts on that queue (design 47 G §543, §600). The asker
// in a named ask's subject is the asking seat's name (A-163). Empty where the seat list is unread.
AcceptCallers map[string][]string
// HeldByTheEngine says every node's engine holds the seat on its own account (catalogue.Seat.HeldByTheEngine, novox/hq
// ADR 0563 §1): each of its events names the engine's machine as its last token (machineEvent).
HeldByTheEngine bool
@@ -1192,14 +1196,13 @@ func permissionsFor(p Principal) (Permissions, error) {
pub = append(pub, logGrants(d.Module, logNames(d.Logs))...)
pub = append(pub, readLogGrants(d.ReadLogs)...)
}
// **And the event families a session may wait on** (novox/hq ADR 0367 §2): the tool runner's module's own,
// named one by one in its manifest, as a plain subscription — no consumer is made for them, and no
// call or setting adds one.
waits, err := waitGrants(p.Carries)
if err != nil {
return Permissions{}, err
// **And every event subject** (design 34 every-event §6, §25; novox/hq ADR 0670 §1, ADR 0671 §1): the runtime
// carrying the tool runner hears every seat's, module's and module stream's events, a restricted stream
// included, as a plain subscription: no publish, no durable consumer, no acknowledgement and no deny is added
// for it, and a runtime carrying no tool runner gets none of them.
if slices.ContainsFunc(p.Carries, func(d Declared) bool { return d.ToolRunner }) {
sub = append(sub, sdkbc.EveryEvent()...)
}
sub = append(sub, waits...)
// **Never the traffic of a trusted holder** (novox/hq ADR 0259 §8): the machine's runtime runs as the
// operator's account, which every agent runs as, so a module saying warrants or speaking for a kind
// that proves its sender is never composed into it — refused here, naming it, whatever registration
@@ -20,7 +20,6 @@ type (
KindHeld = membership.KindHeld
StreamIssued = membership.StreamIssued
HeardIssued = membership.HeardIssued
WaitIssued = membership.WaitIssued
)
// AssignmentsStream holds every assignment's membership, the newest per subject.
@@ -35,6 +35,16 @@ const BuildAskMaxDeliver = 5
// KindedBenches are the seats that may be kinded (ADR 0234 §2): making another is a decision, recorded.
var KindedBenches = map[string]bool{"channel": true, "intake": true}
// NamedWorkerName is the worker of a pulled-by-kind seat's named asks, `accept.<queue>.<asker>`, beside the queue's own (WorkerName):
// two filters that overlap nothing, so the work queue takes both (design 47 G §544).
func NamedWorkerName(seat, queue string) string {
return "SEAT_" + upperSnake(seat) + "_" + upperSnake(queue) + "_named_worker"
}
// MainAskers are the seats that may publish a build seat's ask on main's subject `accept.<queue>`, which names no asker: the
// checker and the builder, until main's subject goes (design 47 G §543, §600, A-184).
var MainAskers = []string{"mesh-delivery-checker", "mesh-builds"}
// WorkerName is the worker a seat's holders pull from: one for the seat, or one per kind on a kinded bench.
func WorkerName(seat, kind string) string {
if kind == "" {
@@ -86,6 +96,9 @@ func SeatTrafficOf(module string, holds, uses, watches []Seat) SeatTraffic {
for _, a := range s.Accepts {
t.Workers = append(t.Workers, Worker{Stream: seatStreamName(s.Name), Consumer: WorkerName(s.Name, a),
Filter: "mesh.seat." + s.Name + ".accept." + a})
// Its named asks have a worker of their own (§544); a holder of G pulls it, one before G knows only main's.
t.Workers = append(t.Workers, Worker{Stream: seatStreamName(s.Name), Consumer: NamedWorkerName(s.Name, a),
Filter: "mesh.seat." + s.Name + ".accept." + a + ".*"})
}
} else if len(s.Accepts) > 0 {
stream := seatStreamName(s.Name)
@@ -121,7 +134,25 @@ func SeatTrafficOf(module string, holds, uses, watches []Seat) SeatTraffic {
if !s.isNewTraffic() {
continue
}
if s.PulledByKind {
// **An ask names its asker** (§543, §600): each asker is granted `accept.<queue>.<asker>` for the queues whose
// kinds it is a caller of, its name the seat it holds, and main's `accept.<queue>` is the checker's and the
// builder's alone.
for _, q := range s.Accepts {
for _, h := range holds {
if namesVerb(s.AcceptCallers[q], h.Name) {
t.Publish = append(t.Publish, seatSubject(s, "accept", q+"."+h.Name))
}
if namesVerb(MainAskers, h.Name) {
t.Publish = append(t.Publish, seatSubject(s, "accept", q))
}
}
}
}
for _, a := range s.Accepts {
if s.PulledByKind {
break
}
switch {
case namesVerb(s.ByCaller, a):
t.Publish = append(t.Publish, seatSubject(s, "accept", a+"."+module))
@@ -205,7 +236,7 @@ func (s Seat) isNewTraffic() bool {
// plainVerbs is a seat's accepts or emits with those the rules above compose taken out: a verb named by
// its caller and every verb of a kinded bench are composed by SeatTrafficOf and nowhere else.
func plainVerbs(s Seat, verbs []string) []string {
if s.Kinded {
if s.Kinded || s.PulledByKind {
return nil
}
var out []string
@@ -2,6 +2,7 @@ package buscompose
import (
"fmt"
sdkbc "git.novox.be/novox/mesh-sdk/go/buscompose"
"slices"
"strings"
"time"
@@ -36,8 +37,8 @@ type Bucket struct {
History int
// TTLSeconds is how long a value lives; zero is until replaced or deleted.
TTLSeconds int
// PerMachine says each machine's instance writes only the key named for its machine (novox/hq ADR
// 0260), and is granted that key and no other.
// PerMachine says each machine's instance writes only the key named for its machine and the keys below it (novox/hq
// ADR 0260; design 46 approval mark §13), and is granted those and no other machine's.
PerMachine bool
// KeyTTL says the bucket allows a time to live per key (novox/hq ADR 0433 §1): its owner writes each key with its
// own, and the server writes a delete marker, kept KeyTTLMarkerTTL, when it ends.
@@ -166,8 +167,11 @@ func stateGrants(a stateAccess) []string {
if machineKey == "" {
continue // a machine with no usable name reaches none of it
}
read(bucket, machineKey)
out = append(out, "$KV."+bucket+"."+machineKey)
// Its machine's key and the keys below it, no other machine's (design 46 approval mark §13).
for _, k := range sdkbc.PerMachineKeys(machineKey) {
read(bucket, k)
out = append(out, "$KV."+bucket+"."+k)
}
continue
}
read(bucket, "")
@@ -0,0 +1,38 @@
package buscompose
import (
"testing"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/membership"
)
// Design 47 G §58, §59, §91, §124: a state's `<state>-objects` store is its owner's alone, and a sent store is read, never
// written, by the modules it is for.
func TestStateObjectsAndSentStores(t *testing.T) {
owner, err := PermissionsFor(Principal{Kind: KindModule, Node: "one", Module: "shop", Bound: []membership.BusBinding{
{Local: "orders", Storage: catalogue.StorageKeyValue, Template: catalogue.TemplateState, Bucket: "shop_orders", Objects: "shop_orders-objects"}}})
if err != nil {
t.Fatal(err)
}
other, err := PermissionsFor(Principal{Kind: KindModule, Node: "one", Module: "bank"})
if err != nil {
t.Fatal(err)
}
for _, subject := range []string{"$O.shop_orders-objects.C.x", "$O.shop_orders-objects.M.x", "$JS.API.DIRECT.GET.OBJ_shop_orders-objects.x"} {
if !MayPublish(owner, subject) {
t.Errorf("the owner may not publish %s", subject)
}
if MayPublish(other, subject) {
t.Errorf("another module may publish %s", subject)
}
}
reader, err := PermissionsFor(Principal{Kind: KindModule, Node: "one", Module: "bank", ReadsObjects: []string{"shop_sent-objects"}})
if err != nil {
t.Fatal(err)
}
if !MayPublish(reader, "$JS.API.DIRECT.GET.OBJ_shop_sent-objects.x") || MayPublish(reader, "$O.shop_sent-objects.C.x") ||
MayPublish(reader, "$JS.API.DIRECT.GET.OBJ_other_sent-objects.x") {
t.Error("a reader of a sent store reads that one and writes none")
}
}
File diff suppressed because one or more lines are too long
@@ -56,9 +56,6 @@ type Declared struct {
// CatchUps are the module's own tools that bring a kept data forward after a restore of it, as its manifest's kept data
// name them (design 47 G §406, §631, A-108): the node-engine on a node that places the module is granted to call each.
CatchUps []string
// Waits are the event families a session may wait on through the tool runner, the tool runner's module's
// alone (novox/hq ADR 0367 §2): its account subscribes them for a call, through no consumer.
Waits []Wait
// State is the state it keeps, each a bucket its instances write (novox/hq ADR 0201).
State []Bucket
// Logs are the logs it keeps, each a stream its instances append to (novox/hq ADR 0297).
@@ -592,14 +589,14 @@ func Composed(d Declared) bool { return d.Module != EngineModule }
func CarriedByRunner(d Declared) bool { return Composed(d) && d.RunsAs == "" && runnerServes(d) }
// runnerServes says the machine's tool runner has something of this module to serve (novox/hq ADR 0436 §1,
// ADR 0437 §4, issue 1329): tools or loads it answers, a seat it holds, event families a session waits on,
// ADR 0437 §4, issue 1329): tools or loads it answers, a seat it holds,
// a bundle the runtime loads (Loads), or a check its health asks. A module with none of these is a process of its own on its own credential, and
// carrying it would hand every session on the machine the runner's account with that module's state, seat
// traffic and streams. A module with no account of its own (NoAccount) is spoken for by the runner, so it
// stays carried, and so does the runtime module itself. Whether the module has its own broker secret is not
// the test: a module with tools and its own credential is still carried (ADR 0175).
func runnerServes(d Declared) bool {
return d.ToolRunner || d.NoAccount || d.Loads || len(d.Serves) > 0 || len(d.Holds) > 0 || len(d.Waits) > 0 || len(d.Checks) > 0
return d.ToolRunner || d.NoAccount || d.Loads || len(d.Serves) > 0 || len(d.Holds) > 0 || len(d.Checks) > 0
}
// declaredStreamsOf is the stream of every bucket, log and stream a module placed anywhere declares, once each, in name
@@ -1,94 +0,0 @@
package buscompose
import (
"fmt"
"strings"
)
// What a session may wait on through the mesh MCP server (novox/hq ADR 0367).
//
// **A grant apart from `consumes`, and the tool runner's alone.** The tool runner's module names in its
// manifest the event families a session may wait on, one by one; the runtime's account is granted a plain
// subscription on those subjects and nothing wider — no durable consumer, no queue of its own — and its
// membership names the same list, from which `mesh_wait` refuses any other. Both are read from this one
// composition, so the grant and what the tool runner offers cannot disagree, and nothing but the manifest
// adds a family (§6).
// Wait is one event family the tool runner's module declares: its name as the manifest gives it, and the
// emitter — a seat or a module — and the event, as the inventory resolved them.
type Wait struct {
// Name is the family as the manifest names it, `<emitter>.<event>`: what a session asks for.
Name string
Emitter string
// Seat says the emitter is a seat, whose events live under the seat's namespace (novox/hq ADR 0121).
Seat bool
// Event is the event, with any further token the subject carries: `decided.claude-code`, the asker of a
// seat that names it last (ADR 0259 §3).
Event string
// Last names what the seat's event subject ends in — "kind" for a kinded bench, "asker" for a seat naming
// its caller (ADR 0259 §3) — and is empty for an event that ends at its name. A family needing it is waited
// on with it given, and refused without.
Last string
}
// WaitSubject is where a family's events land. Each token is checked before it becomes a subject: a
// wildcard, a dot inside a name or an empty token would widen the grant.
func WaitSubject(w Wait) (string, error) {
if !safeSubject.MatchString(w.Emitter) {
return "", fmt.Errorf("%q cannot name an emitter of a waited event: it would widen the subject", w.Emitter)
}
for _, t := range strings.Split(w.Event, ".") {
if !safeSubject.MatchString(t) {
return "", fmt.Errorf("%q cannot name a waited event: each of its names is plain, never a wildcard "+
"(novox/hq ADR 0367 §2)", w.Event)
}
}
if w.Last != "" && !strings.Contains(w.Event, ".") {
return "", fmt.Errorf("%s names no %s: %s's events are said for each %s, so a family is %s.%s.<%s>; "+
"without it no event would ever be heard (novox/hq ADR 0367 §5)",
w.Name, w.Last, w.Emitter, w.Last, w.Emitter, w.Event, w.Last)
}
if w.Seat {
return "mesh.seat." + w.Emitter + ".event." + w.Event, nil
}
return "mesh.mod." + w.Emitter + ".event." + w.Event, nil
}
// waitGrants is the subscription the tool runner's account is granted for its module's families, and an
// error for a carried module other than the tool runner's that declares any (ADR 0367 §2).
func waitGrants(carries []Declared) ([]string, error) {
var sub []string
for _, d := range carries {
if len(d.Waits) == 0 {
continue
}
if !d.ToolRunner {
return nil, fmt.Errorf("%s declares what a session waits on; only the tool runner's module (its manifest says "+
"tool-runner) does (novox/hq ADR 0367 §2)", d.Module)
}
for _, w := range d.Waits {
s, err := WaitSubject(w)
if err != nil {
return nil, err
}
sub = append(sub, s)
}
}
return sub, nil
}
// waitsIssuedFor is the families a membership names: the tool runner's module's, and nobody else's.
func waitsIssuedFor(d Declared) []WaitIssued {
if !d.ToolRunner {
return nil
}
var out []WaitIssued
for _, w := range d.Waits {
s, err := WaitSubject(w)
if err != nil {
continue // refused where the account is composed, which names it
}
out = append(out, WaitIssued{Event: w.Name, Subject: s})
}
return out
}
@@ -0,0 +1,139 @@
package grants
import (
"encoding/json"
"errors"
"fmt"
"slices"
"sort"
"strings"
"git.novox.be/novox/mesh-sdk/go/seatdef"
"mesh-grants/internal/buscompose"
)
// The tools that say who may call and why a call is refused (design 47 G §83, GR2).
const (
ToolCallers = "grants_callers"
ToolWhyRefused = "grants_why_refused"
)
// CallerLine is one verb's, or one accepted kind's, callers as a seat definition gives them.
type CallerLine struct {
Seat string `json:"seat"`
// Verb is the verb's name, or the accepted kind's.
Verb string `json:"verb"`
// Kind is `verb` or `accepts`.
Kind string `json:"kind"`
Class string `json:"class,omitempty"`
// Callers are the entries the verb admits: the list the definition names, or its class's default.
Callers []string `json:"callers"`
// Named says the definition names the list; false is the class's default (§391).
Named bool `json:"named"`
}
// definitions are the seat definitions the part composes from, or why it has none.
func (p *Part) definitions() (map[string]seatdef.Definition, error) {
d, ok := p.SeatList.(SeatDefinitions)
if !ok {
return nil, errors.New("the seat list is not read here: the definitions' callers are unknown")
}
defs := d.Definitions()
if len(defs) == 0 {
return nil, errors.New("the seat list holds no definitions yet")
}
return defs, nil
}
// CallerLines are the callers each verb and each accepted kind admits, from the definitions, of the seat named (every seat
// when empty) and the verb named (every verb when empty).
func CallerLines(defs map[string]seatdef.Definition, seat, verb string) []CallerLine {
var out []CallerLine
for _, d := range defs {
if seat != "" && d.Seat != seat {
continue
}
for _, v := range d.Verbs {
if verb == "" || v.Name == verb {
out = append(out, CallerLine{Seat: d.Seat, Verb: v.Name, Kind: "verb", Class: v.Class,
Callers: v.EffectiveCallers(), Named: v.Callers != nil && !v.Callers.IsText()})
}
}
for _, a := range d.Accepts {
if verb == "" || a.Name == verb {
l := CallerLine{Seat: d.Seat, Verb: a.Name, Kind: "accepts"}
if a.Callers != nil && !a.Callers.IsText() {
l.Callers, l.Named = a.Callers.List, true
}
out = append(out, l)
}
}
}
sort.Slice(out, func(i, j int) bool {
a, b := out[i], out[j]
return a.Seat+"\x00"+a.Kind+"\x00"+a.Verb < b.Seat+"\x00"+b.Kind+"\x00"+b.Verb
})
return out
}
// Callers answers the tool grants_callers.
func (p *Part) Callers(seat, verb string) (any, error) {
defs, err := p.definitions()
if err != nil {
return nil, err
}
lines := CallerLines(defs, seat, verb)
if len(lines) == 0 {
return nil, fmt.Errorf("no seat definition names a verb or an accepted kind matching seat %q verb %q", seat, verb)
}
return map[string]any{"callers": lines, "count": len(lines)}, nil
}
// WhyRefused answers the tool grants_why_refused: the grant an account lacks to call address (`<seat>.<verb>`), and the
// definition's line that leaves it out. The bus answers whether the account may publish the verb's call subject
// (nats.nats_user_can, the account's grants as the server holds them); the definition's callers say who was meant to.
func (p *Part) WhyRefused(account, address, node string) (any, error) {
seat, verb, ok := strings.Cut(address, ".")
if account == "" || !ok || seat == "" || verb == "" {
return nil, errors.New("why_refused names an account and a verb as <seat>.<verb>")
}
defs, err := p.definitions()
if err != nil {
return nil, err
}
lines := CallerLines(defs, seat, verb)
if len(lines) == 0 {
return nil, fmt.Errorf("no seat definition names the verb %s", address)
}
def := defs[seat]
s := buscompose.Seat{Name: seat, Scope: def.Scope}
subject := buscompose.CalledSubject(buscompose.SeatToolSubject(s, verb, node), account)
if subject == "" {
return nil, fmt.Errorf("%s is not the name of a bus user", account)
}
out := map[string]any{"account": account, "verb": address, "subject": subject, "definition": lines}
raw, err := p.Call.Call(CallUserCan, map[string]any{"user": account, "action": "publish", "subject": subject})
if err != nil {
out["bus"] = "not read: " + err.Error()
return out, nil
}
var can struct {
Allowed *bool `json:"allowed"`
}
_ = json.Unmarshal(raw, &can)
out["bus"] = json.RawMessage(raw)
switch {
case can.Allowed == nil:
out["says"] = "the bus's answer names no verdict; read it beside the definition's line"
case *can.Allowed:
out["says"] = "not refused at the bus: the account holds the grant to publish " + subject
default:
callers := lines[0].Callers
out["says"] = fmt.Sprintf("the account lacks the grant to publish %s; the definition admits %s (%s), and the grants part grants a call only to a caller one of those entries names",
subject, strings.Join(callers, ", "), map[bool]string{true: "named by the definition", false: "the class's default"}[lines[0].Named])
out["lacks"] = subject
out["admitted_by"] = slices.Clone(callers)
}
return out, nil
}
@@ -0,0 +1,57 @@
package grants
import (
"encoding/json"
"strings"
"testing"
"git.novox.be/novox/mesh-sdk/go/seatdef"
)
type defsGate struct{ defs map[string]seatdef.Definition }
func (defsGate) MayAct(...string) bool { return true }
func (g defsGate) Definitions() map[string]seatdef.Definition { return g.defs }
type canCall struct {
allowed bool
asked map[string]any
}
func (c *canCall) Call(key string, body any) (json.RawMessage, error) {
c.asked = body.(map[string]any)
return json.Marshal(map[string]any{"allowed": c.allowed})
}
// grants_callers and grants_why_refused read the definitions' callers (design 47 G §83): a verb that names none takes its
// class's default, and a refused account is told the call subject it lacks and the callers the definition admits.
func TestCallersAndWhyRefused(t *testing.T) {
defs := map[string]seatdef.Definition{"mesh-wants": {Seat: "mesh-wants", Scope: "mesh", Verbs: []seatdef.Verb{
{Name: "upgrade", Class: seatdef.ClassAct},
{Name: "entry", Callers: &seatdef.Callers{List: []string{"seat:mesh-pipeline-runner", "operator"}}},
}}}
lines := CallerLines(defs, "mesh-wants", "")
if len(lines) != 2 || lines[0].Verb != "entry" || !lines[0].Named || lines[1].Named ||
strings.Join(lines[1].Callers, ",") != "operator,sessions" {
t.Fatalf("lines: %+v", lines)
}
can := &canCall{}
p := &Part{SeatList: defsGate{defs}, Call: can}
got, err := p.WhyRefused("one.shop", "mesh-wants.upgrade", "")
if err != nil {
t.Fatal(err)
}
out := got.(map[string]any)
if out["lacks"] != "mesh.seat.mesh-wants.call.upgrade.one~shop" || can.asked["subject"] != out["lacks"] ||
!strings.Contains(out["says"].(string), "operator, sessions") {
t.Errorf("a refused caller: %+v", out)
}
can.allowed = true
got, _ = p.WhyRefused("one.shop", "mesh-wants.upgrade", "")
if _, lacks := got.(map[string]any)["lacks"]; lacks {
t.Errorf("an allowed caller lacks a grant: %+v", got)
}
if _, err := p.WhyRefused("one.shop", "mesh-wants.nothing", ""); err == nil {
t.Error("a verb no definition names was explained")
}
}
@@ -0,0 +1,188 @@
package grants
import (
"encoding/json"
"errors"
"fmt"
"maps"
"slices"
"sort"
"strconv"
"strings"
"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"
)
// **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
// revisionEntries reads a catalog graph revision's entries, page after page, as manifests by module. none says the branch has
// no revision yet.
func (p *Part) revisionEntries(in meshcatalog.RevisionInput) (manifests map[string]catalogue.Manifest, none bool, err error) {
manifests = map[string]catalogue.Manifest{}
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
}
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 {
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
}
@@ -190,6 +190,10 @@ type Inputs struct {
// EventSubjects are, by seat, the subjects of its events that carry parts, by the event's local name, as the definitions
// give them: where a node-scoped seat's event names its machine (buscompose.Seat.EventSubjects).
EventSubjects map[string]map[string]string
// AcceptCallers are, by pulled-by-kind seat and queue, the seats that may ask it (acceptCallersOf).
AcceptCallers map[string]map[string][]string
// VerbCallers are, by seat and verb, the callers each verb of the definitions admits (verbCallersOf).
VerbCallers map[string]map[string][]string
// Defined are the events a seat definition of the seat list defines, by local name, and mesh-sdk's finding events: the
// events a `*` emitter before them reaches each declaring module's own stream for (design 47 G §386, §474, §644).
Defined map[string]bool
@@ -370,6 +374,8 @@ func ReadInputs(r Reader, cache *Manifests) Inputs {
in.Kept = buscompose.KeptEventsOf(d.Definitions())
in.Chunked = buscompose.ChunkVerbsOf(d.Definitions())
in.EventSubjects = eventSubjectsOf(d.Definitions())
in.AcceptCallers = acceptCallersOf(d.Definitions())
in.VerbCallers = verbCallersOf(d.Definitions())
in.Defined = definedEventsOf(d.Definitions())
}
nodes := map[string]bool{}
@@ -135,3 +135,45 @@ func withEventSubjects(subjects map[string]map[string]string, d *buscompose.Decl
}
}
}
// acceptCallersOf is, by pulled-by-kind seat and then by queue, the seats that may ask the queue: the `seat:<seat>` entries
// of the callers of every accepted kind the definition puts on it (a kind's `stream` is its queue, else its name is). Never a
// name of the grants part's own: it reads the definitions' lists (design 47 G §543, §600, A-163).
func acceptCallersOf(defs map[string]seatdef.Definition) map[string]map[string][]string {
out := map[string]map[string][]string{}
for _, d := range defs {
if !d.PulledByKind {
continue
}
for _, a := range d.Accepts {
if a.Callers == nil || a.Callers.IsText() {
continue
}
queue := a.Name
if a.Stream != "" {
queue = a.Stream
}
for _, e := range a.Callers.List {
if seat, ok := strings.CutPrefix(e, seatdef.CallerSeatPrefix); ok && !slices.Contains(out[d.Seat][queue], seat) {
if out[d.Seat] == nil {
out[d.Seat] = map[string][]string{}
}
out[d.Seat][queue] = append(out[d.Seat][queue], seat)
}
}
}
}
return out
}
// withAcceptCallers gives each pulled-by-kind seat a declaration holds or uses the askers of its queues (Seat.AcceptCallers).
func withAcceptCallers(askers map[string]map[string][]string, d *buscompose.Declared) {
if len(askers) == 0 {
return
}
for _, list := range []*[]buscompose.Seat{&d.Holds, &d.Uses, &d.Watches} {
for i := range *list {
(*list)[i].AcceptCallers = askers[(*list)[i].Name]
}
}
}
@@ -0,0 +1,36 @@
package grants
import (
"slices"
"testing"
"git.novox.be/novox/mesh-sdk/go/seatdef"
)
// The askers of a build seat's queue are read from the definition's callers lists (design 47 G §543, §600, A-163): a kind's
// `stream` is its queue, a text callers names none, and only `seat:` entries are askers.
func TestAcceptCallersOf(t *testing.T) {
msg := func(name, stream string, callers ...string) seatdef.Message {
m := seatdef.Message{Name: name, Stream: stream}
if callers != nil {
m.Callers = &seatdef.Callers{List: callers}
}
return m
}
got := acceptCallersOf(map[string]seatdef.Definition{
"node-build-go": {Seat: "node-build-go", PulledByKind: true, Accepts: []seatdef.Message{
msg("check", "", "seat:mesh-catalog", "operator"),
msg("step", "check", "seat:mesh-pipeline-runner"),
msg("delivery", "", "seat:mesh-builds"),
{Name: "recheck", Callers: &seatdef.Callers{Text: "the checker"}},
}},
"other": {Seat: "other", Accepts: []seatdef.Message{msg("go", "", "seat:x")}},
})
if len(got) != 1 {
t.Fatalf("seats: %v, want node-build-go alone", got)
}
q := got["node-build-go"]
if !slices.Equal(q["check"], []string{"mesh-catalog", "mesh-pipeline-runner"}) || !slices.Equal(q["delivery"], []string{"mesh-builds"}) || len(q) != 2 {
t.Errorf("queues: %v", q)
}
}
+9 -24
View File
@@ -3,6 +3,7 @@ package grants
import (
"fmt"
"git.novox.be/novox/mesh-contracts/go/seats/meshbroker"
sdkbc "git.novox.be/novox/mesh-sdk/go/buscompose"
"maps"
"reflect"
"slices"
@@ -101,10 +102,14 @@ func records(in Inputs, union bool) (buscompose.Records, []Gap) {
d.Watches, d.Consumes, d.Hears, keptHeard = keptOutOfHearing(in.Kept, d.Watches, d.Consumes, d.Hears)
d.HearsAStream = d.HearsAStream || keptHeard
d.Reads, d.ReadsObjects, d.ReadsRefused = readsOfObjects(m.Module, node, d.Reads, d.ReadsRefused, declared, values)
// The sent stores of the modules it is for (design 47 G §59, §124), read from the catalog graph's manifests and the
// definitions' callers.
d.ReadsObjects = append(d.ReadsObjects, sentStoresRead(m, in.Manifests, in.VerbCallers)...)
// Its bindings as kept (bindings.go): the same source its membership's `bindings` is written from in this pass,
// so a grant and its binding are written together, never one before the other (issue 1966, the kind of issue 249).
d.Bindings = in.Bindings[m.Module]
withEventSubjects(in.EventSubjects, &d)
withAcceptCallers(in.AcceptCallers, &d)
return d
}
d := declare(m)
@@ -136,6 +141,7 @@ func records(in Inputs, union bool) (buscompose.Records, []Gap) {
out.Engine = &buscompose.Declared{Module: m.Module, Consumes: m.Consumes, Watches: watches, Invokes: m.Invokes,
State: bucketsFor(m, in.Nodes), Logs: logsOf(m), Streams: streamsOf(m)}
withEventSubjects(in.EventSubjects, out.Engine)
withAcceptCallers(in.AcceptCallers, out.Engine)
}
return out, gaps
}
@@ -146,7 +152,7 @@ func declaredFor(m catalogue.Manifest, seats map[string]catalogue.SeatDeclaratio
fromModules, watches := consumedOf(m, seats, declarers)
d := buscompose.Declared{
Module: m.Module, ToolRunner: catalogue.IsToolRunner(m), Emits: m.EmitsAll(), Consumes: fromModules, Watches: watches, Serves: m.Tools,
Invokes: m.Invokes, Waits: waitsOf(m, seats), State: bucketsOf(m), Reads: m.Reads, Logs: logsOf(m),
Invokes: m.Invokes, State: bucketsOf(m), Reads: m.Reads, Logs: logsOf(m),
Streams: streamsOf(m), Queues: queueOwnersOf(m), Processes: processesOf(m), ServesOwn: ownServesOf(m), Checks: catalogue.HealthChecks(m),
RunsAs: m.RunsAs, Issued: issuedTools(m),
// The keys its served values fill, which every node may read where it runs (issue 1126).
@@ -306,27 +312,6 @@ func loadsABundle(m catalogue.Manifest) bool {
return false
}
func waitsOf(m catalogue.Manifest, seats map[string]catalogue.SeatDeclaration) []buscompose.Wait {
var out []buscompose.Wait
for _, w := range m.Waits {
emitter, event, _ := strings.Cut(w, ".")
first, _, _ := strings.Cut(event, ".")
wait := buscompose.Wait{Name: w, Emitter: emitter, Event: event}
if s, isASeat := seats[emitter]; isASeat {
switch {
case s.Kinded && catalogue.SeatSays(s.Emits, first):
wait.Seat, wait.Last = true, "kind"
case s.NamedByCaller(first) && catalogue.SeatSays(s.Emits, first):
wait.Seat, wait.Last = true, "asker"
case catalogue.SeatSays(s.Emits, event):
wait.Seat = true
}
}
out = append(out, wait)
}
return out
}
func issuedTools(m catalogue.Manifest) []string {
var out []string
for _, o := range m.Provides {
@@ -430,7 +415,7 @@ func streamsOf(m catalogue.Manifest) []buscompose.ModuleStream {
for _, s := range m.Streams {
events := make([]string, 0, len(s.Events))
for _, e := range s.Events {
events = append(events, buscompose.WirePattern(e))
events = append(events, sdkbc.WirePattern(e))
}
out = append(out, buscompose.ModuleStream{Module: m.Module, Name: s.BusName(), Events: events,
MaxAgeDays: s.Days(), MaxMiB: s.Cap(), Restricted: s.Grant != nil,
@@ -512,7 +497,7 @@ func hearsOf(m catalogue.Manifest, declared map[string]catalogue.Manifest, node
for _, p := range parts {
h := buscompose.Heard{Stream: p.Stream.BusName(), Emitter: p.Emitter, Restricted: p.Stream.Grant != nil}
for _, pattern := range p.Patterns {
h.Filters = append(h.Filters, buscompose.ModuleStreamSubject(p.Emitter, buscompose.WirePattern(pattern)))
h.Filters = append(h.Filters, buscompose.ModuleStreamSubject(p.Emitter, sdkbc.WirePattern(pattern)))
}
out = append(out, h)
}
@@ -0,0 +1,86 @@
package grants
import (
"slices"
"strings"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/seatdef"
)
// **A module's sent store is read by the modules it is for** (design 47 G §59, §124): the grants part derives, from the
// catalog graph and the seat definitions, never from a manifest field, a standing read of `<module>_sent-objects` for the
// callers the module's seat definition names for the verbs it serves, and for the consumers whose `consumes` declare its
// events. The grant follows the catalog graph, so it is composed with each module's declaration at every pass.
// verbCallersOf is, by seat and verb, the callers each verb of the definitions admits (a verb naming none takes its class's
// default).
func verbCallersOf(defs map[string]seatdef.Definition) map[string]map[string][]string {
out := map[string]map[string][]string{}
for _, d := range defs {
for _, v := range d.Verbs {
if out[d.Seat] == nil {
out[d.Seat] = map[string][]string{}
}
out[d.Seat][v.Name] = v.EffectiveCallers()
}
}
return out
}
// admits says whether a verb's callers name the module: `invokers` (every module whose manifest invokes the verb), the module
// itself, or a seat it claims.
func admits(callers []string, m catalogue.Manifest) bool {
for _, c := range callers {
switch {
case c == seatdef.CallerInvokers, c == seatdef.CallerModulePrefix+m.Module:
return true
}
if seat, ok := strings.CutPrefix(c, seatdef.CallerSeatPrefix); ok && slices.ContainsFunc(m.Claims, func(x catalogue.Claim) bool { return x.Name == seat }) {
return true
}
}
return false
}
// sentStoresRead are the bus names of the sent stores the module m reads: of each module whose event it consumes (the module's
// own, or the seat a module claims), and of each module claiming a seat whose verb m invokes where the verb's callers admit m.
// Never m's own store, which its binding grants it.
func sentStoresRead(m catalogue.Manifest, all map[string]catalogue.Manifest, callers map[string]map[string][]string) []string {
claimants := func(name string) []string {
var out []string
if _, ok := all[name]; ok {
out = append(out, name)
}
for module, x := range all {
if slices.ContainsFunc(x.Claims, func(c catalogue.Claim) bool { return c.Name == name }) {
out = append(out, module)
}
}
return out
}
var stores []string
for _, c := range m.Consumes {
name, _, ok := strings.Cut(strings.TrimPrefix(c, "seat:"), ".")
if !ok || name == "*" {
continue
}
for _, module := range claimants(name) {
stores = append(stores, catalogue.SentObjectsName(module))
}
}
for _, in := range m.Invokes {
seat, verb, ok := catalogue.SeatInvoke(in)
if !ok || !admits(callers[seat][verb], m) {
continue
}
for module, x := range all {
if slices.ContainsFunc(x.Claims, func(c catalogue.Claim) bool { return c.Name == seat }) {
stores = append(stores, catalogue.SentObjectsName(module))
}
}
}
stores = slices.DeleteFunc(stores, func(s string) bool { return s == catalogue.SentObjectsName(m.Module) })
slices.Sort(stores)
return slices.Compact(stores)
}
@@ -0,0 +1,38 @@
package grants
import (
"slices"
"testing"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/seatdef"
)
// The sent stores a module reads follow the catalog graph (design 47 G §59, §124): the consumers of a module's events and the
// callers a seat's verb admits, and no other module.
func TestSentStoresRead(t *testing.T) {
holder := catalogue.Manifest{Module: "shop", Claims: []catalogue.Claim{{Name: "orders-seat"}}}
all := map[string]catalogue.Manifest{"shop": holder, "bank": {Module: "bank"}, "plain": {Module: "plain"}}
callers := map[string]map[string][]string{"orders-seat": {
"place": {"seat:billing", "module:plain"}, "list": seatdef.DefaultCallers(seatdef.ClassRead), "wipe": seatdef.DefaultCallers(seatdef.ClassAct)}}
for _, c := range []struct {
name string
m catalogue.Manifest
want []string
}{
{"consumes a module's event", catalogue.Manifest{Module: "bank", Consumes: []string{"shop.sold"}}, []string{"shop_sent-objects"}},
{"consumes a seat's event", catalogue.Manifest{Module: "bank", Consumes: []string{"orders-seat.sold"}}, []string{"shop_sent-objects"}},
{"invokes a verb that names its seat", catalogue.Manifest{Module: "bank", Claims: []catalogue.Claim{{Name: "billing"}},
Invokes: []string{"seat:orders-seat.place"}}, []string{"shop_sent-objects"}},
{"invokes a verb that names it", catalogue.Manifest{Module: "plain", Invokes: []string{"seat:orders-seat.place"}}, []string{"shop_sent-objects"}},
{"invokes a read, its callers include invokers", catalogue.Manifest{Module: "bank", Invokes: []string{"seat:orders-seat.list"}}, []string{"shop_sent-objects"}},
{"invokes an act no one names it for", catalogue.Manifest{Module: "bank", Invokes: []string{"seat:orders-seat.wipe"}}, nil},
{"invokes a verb that names others", catalogue.Manifest{Module: "bank", Invokes: []string{"seat:orders-seat.place"}}, nil},
{"declares neither", catalogue.Manifest{Module: "bank"}, nil},
{"its own store is its binding's", holder, nil},
} {
if got := sentStoresRead(c.m, all, callers); !slices.Equal(got, c.want) {
t.Errorf("%s: %v, want %v", c.name, got, c.want)
}
}
}
+3 -3
View File
@@ -14,8 +14,8 @@ import (
"mesh-grants/internal/buscompose"
)
// The part's tools, as its manifest lists them. The part claims no seat: the seat mesh-grants served the lease write
// alone, which went with the controller (novox/hq ADR 0590 §3, issue 1126).
// The part's tools, as its manifest lists them. The part claims the seat mesh-grants, which serves `grants-for` (design 47 G
// §401, §441); its own tools are named below.
const (
ToolGrants = "grants_grants"
ToolMembership = "grants_membership"
@@ -40,7 +40,7 @@ const (
// Tools is every tool, in the manifest's order.
var Tools = []string{ToolGrants, ToolMembership, ToolUserList, ToolComposeNow, ToolAssert, ToolAccounts, ToolConsumerMatch,
ToolAcceptHashes, ToolFirstViews, ToolFirstViewAgain, ToolRunning, ToolWaits, ToolRelease, ToolSeatList, ToolSeatListAgain}
ToolAcceptHashes, ToolFirstViews, ToolFirstViewAgain, ToolRunning, ToolWaits, ToolRelease, ToolSeatList, ToolSeatListAgain, ToolCallers, ToolWhyRefused}
// WritesGrants is what grants says of the part's own grants: written once the list the bus loaded carries a build's
// accounts, and the one key the assigner reads (ADR 0571 clause 9, which changes ADR 0547 clause 5).
+12 -1
View File
@@ -2,6 +2,15 @@
"module": "mesh-grants",
"version": "0.1",
"slug": "grants",
"claims": [
{
"name": "mesh-grants",
"scope": "mesh",
"serves": [
"grants-for"
]
}
],
"reads": [
"mesh-config.resolved",
"node-engine.have",
@@ -73,7 +82,9 @@
"grants_waits",
"grants_release",
"grants_seat_list",
"grants_seat_list_again"
"grants_seat_list_again",
"grants_callers",
"grants_why_refused"
],
"state": [
{