A heard entry of the membership carries its consumer's spec (H-A-472, seventh and eighth addenda) #210

Merged
mesh-tools merged 1 commits from fix/heard-issued-spec into main 2026-11-22 19:01:43 +00:00
2 changed files with 49 additions and 1 deletions
+26 -1
View File
@@ -167,12 +167,37 @@ type StreamIssued struct {
Subject string `json:"subject"`
}
// HeardIssued is one module stream an assignment hears (ADR 0363 §8).
// HeardIssued is one module stream an assignment hears (ADR 0363 §8), with its consumer's whole spec as the grants part
// composed it (design 47 H2, H-A-472 seventh addendum): a part that creates the consumer itself, such as the tool runner
// for a module's `_tools` twin, creates it from these and computes nothing. EVENTS is heard by an entry like any stream.
// The spec's fields are left out of the wire when unset, so a membership an older grants part wrote still reads (its
// entries carry no spec) and an older reader ignores them.
type HeardIssued struct {
Stream string `json:"stream"`
Consumer string `json:"consumer"`
// Filters are the subjects the consumer receives, already named for the twin, the again filter included.
Filters []string `json:"filters,omitempty"`
// AckWaitSeconds before an unacknowledged delivery is delivered again.
AckWaitSeconds int `json:"ack-wait-seconds,omitempty"`
// MaxDeliver is how often a message is handed over before the consumer gives it up; zero for no bound.
MaxDeliver int `json:"max-deliver,omitempty"`
// MaxAckPending is how many deliveries may stand unacknowledged at once; zero for the server's default.
MaxAckPending int `json:"max-ack-pending,omitempty"`
// DeliverPolicy is where the consumer starts: DeliverFromNow, DeliverLastPerSubject or DeliverAll.
DeliverPolicy string `json:"deliver-policy,omitempty"`
}
// HasSpec says the entry carries its consumer's spec, read as its filters being present (H-A-472 eighth addendum): a
// reader creates the consumer from the spec of an entry that has one, and binds by name an entry an older writer made.
func (h HeardIssued) HasSpec() bool { return len(h.Filters) > 0 }
// The deliver policies a heard entry names, the forms the grants part composes a consumer in.
const (
DeliverFromNow = "from-now"
DeliverLastPerSubject = "last-per-subject"
DeliverAll = "all"
)
// StateIssued is the state this membership issues its module's code by a local name, and whether it does: what every
// runtime that serves a module's state calls reads, so no reader keeps a second copy of the rule (novox/hq issue 1966).
// An entry of the old `state` list wins (ADR 0201); otherwise a binding of a key-value entry the module asks for in
+23
View File
@@ -96,6 +96,29 @@ func TestAMembershipRoundTripsAsIssued(t *testing.T) {
if got := issuing.StateNames(); !reflect.DeepEqual(got, []string{"holds", "repos"}) {
t.Errorf("StateNames = %v", got)
}
// H-A-472 (seventh addendum): a heard entry carries its consumer's whole spec and reads back whole; an entry an older
// grants part wrote, naming only the stream and the consumer, still reads, and one without a spec encodes as before.
heard := in
heard.Hears = []HeardIssued{{Stream: "EVENTS", Consumer: "ace_forge_tools",
Filters: []string{"mesh.events.forge-bridge.>", "mesh.again.ace_forge_tools.>"},
AckWaitSeconds: 30, MaxDeliver: 5, MaxAckPending: 1, DeliverPolicy: DeliverFromNow}}
heardRaw, _ := json.Marshal(heard)
var heardBack Membership
if err := json.Unmarshal(heardRaw, &heardBack); err != nil || !reflect.DeepEqual(heard, heardBack) ||
!strings.Contains(string(heardRaw), `"ack-wait-seconds":30,"max-deliver":5,"max-ack-pending":1,"deliver-policy":"from-now"`) {
t.Fatalf("a heard entry with its spec read back as %+v (%v): %s", heardBack, err, heardRaw)
}
var older Membership
if err := json.Unmarshal([]byte(`{"node":"ace","module":"forge","hears":[{"stream":"forge-bridge","consumer":"ace_forge"}]}`), &older); err != nil ||
!reflect.DeepEqual(older.Hears, []HeardIssued{{Stream: "forge-bridge", Consumer: "ace_forge"}}) {
t.Fatalf("an older heard entry read as %+v (%v)", older.Hears, err)
}
if !heardBack.Hears[0].HasSpec() || older.Hears[0].HasSpec() {
t.Fatalf("HasSpec: a new entry %v, an older one %v", heardBack.Hears[0].HasSpec(), older.Hears[0].HasSpec())
}
if bare, _ := json.Marshal(HeardIssued{Stream: "forge-bridge", Consumer: "ace_forge"}); string(bare) != `{"stream":"forge-bridge","consumer":"ace_forge"}` {
t.Fatalf("a heard entry without a spec encodes otherwise than before: %s", bare)
}
var wire map[string]json.RawMessage
_ = json.Unmarshal(raw, &wire)
for _, k := range []string{"receives", "mesh", "seat-traffic"} {