Files
mesh-delivery/modules/mesh-grants/internal/grants/assertions.go
T
jschoubben 380d4781e6 mesh-grants: bring a held kept stream to its definition's source filter
The kept stream of the runner's pipeline-ended was made at G's
definition, sourced by a three-part subject; H1 moved the event to
<branch>.<source>, so the stream took nothing in since 08:13 and the
assigner, which hears a kept event from its kept stream, heard no end.
createKept left every held kept stream as it was. It now brings a held
one's source filter from the events stream to the definition's in place
(a stream update, its messages and other settings kept, never made
again) and says the held and the composed filter in the journal and the
pass; the same holds for pipeline-started and wait-held.

Builds: design 47 H H-A-145 (hq design/47-H1-answers-59 0787704b), §746
2026-11-20 15:42:24 +01:00

373 lines
15 KiB
Go

package grants
import (
"encoding/json"
"errors"
"fmt"
"slices"
"sort"
"strings"
"sync"
"github.com/nats-io/nats.go/jetstream"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"mesh-grants/internal/buscompose"
)
// Item is one bucket, log or stream a manifest declares, as composed, beside what the bus holds of it.
type Item struct {
Kind string `json:"kind"`
Stream string `json:"stream"`
// Composed is what an assertion would ask for; Held what the bus holds, absent when it holds no such stream.
Composed Limits `json:"composed"`
Held *Limits `json:"held,omitempty"`
// Differences says how they differ, in words; empty when they agree in what can be read from here.
Differences []string `json:"differences,omitempty"`
// Created says what became of creating it when the bus lacked it: "created", or why not (issue 1790). Empty when
// the bus holds it or no creation was asked here.
Created string `json:"created,omitempty"`
}
// Limits are the facts of a stream an assertion sets and the bus module's nats_streams reads back. Its size cap is not
// read back by that tool, so it is composed and not compared.
type Limits struct {
Subjects []string `json:"subjects"`
Retention string `json:"retention"`
MaxAgeHours int `json:"max_age_hours,omitempty"`
MaxPerSubject int `json:"max_per_subject,omitempty"`
MaxBytes int64 `json:"max_bytes,omitempty"`
}
// Assertion is one module's declared buckets, logs and streams, composed and compared. Asserted says this pass created
// one the bus lacked (the operator, 2026-10-26 08:54); one the bus holds only ever gains subjects.
type Assertion struct {
Module string `json:"module"`
Manifest string `json:"manifest"`
Items []Item `json:"items"`
Asserted bool `json:"asserted"`
Says string `json:"says"`
}
// ShadowAsserts is what an assertion says where nothing may be created: in the tools, which ask the part's process.
const ShadowAsserts = "in the tools: composed and compared, nothing asserted (the part's process creates what the bus lacks)"
// CreatesMissing is what an assertion of the part's process says (the operator, 2026-10-26 08:54; issue 1790).
const CreatesMissing = "a bucket, log or stream the manifest declares and the bus lacks is created with the manifest's limits, once per " +
"manifest; a stream the bus holds only ever gains the subjects its manifest adds and has its size cap raised to the manifest's when that is larger " +
"(never lowered), and nothing is removed, deleted or otherwise changed, a difference is only said"
// Creator creates one stream the bus does not hold, with the configuration given, and never updates or deletes one: the
// part's process alone, whose account is granted the create of each declared stream by name (the operator, 2026-10-26
// 08:54). A stream the bus holds already answers ErrHeld.
type Creator interface {
CreateDeclared(cfg jetstream.StreamConfig) error
// AddSubjects adds subjects to a stream the bus holds and nothing else: the stream's subjects become the union of what
// it holds and add; no subject is removed, no limit, retention or other setting changed, the stream not recreated.
AddSubjects(stream string, add []string) error
// RaiseMaxBytes raises the size cap of a stream the bus holds to `to` when `to` is larger than the cap it holds, and
// changes nothing else (the operator, 2026-11-09 09:07: "raise only"). It answers the cap it held and whether it
// raised; a cap that is larger or equal, or an unbounded stream, is left as it is. It never lowers any limit.
RaiseMaxBytes(stream string, to int64) (from int64, raised bool, err error)
// SourceFilter brings the filter subject of a held stream's source from the stream `source` to `filter`, keeping its
// messages and every other setting, the stream not made again (design 47 H H-A-145). It answers the filter it held and
// whether it changed; a stream with no source from `source` is left as it is.
SourceFilter(stream, source, filter string) (from string, changed bool, err error)
}
// Raise is one held stream's size cap raised to the manifest's, said in the event and the journal.
type Raise struct {
Stream string `json:"stream"`
From int64 `json:"from"`
To int64 `json:"to"`
}
// ErrHeld is a create refused because the bus holds the stream already (made meanwhile): left as it is.
var ErrHeld = errors.New("the bus holds it already, so it is left as it is")
// Created words of an item.
const (
ItemCreated = "created"
ItemNotCreated = "not created: "
)
// Configs are the streams a manifest declares, as the controller asserts them at its start (mesh-sdk buscompose), by
// stream name. Pure.
func Configs(m catalogue.Manifest, nodes []string) map[string]jetstream.StreamConfig {
out := map[string]jetstream.StreamConfig{}
for _, b := range bucketsFor(m, nodes) {
c := buscompose.BucketStreamConfig(b)
out[c.Name] = c
}
for _, l := range logsOf(m) {
c := l.Config()
out[c.Name] = c
}
for _, s := range streamsOf(m) {
c := buscompose.ModuleStreamConfig(s)
out[c.Name] = c
}
for _, o := range objectsOf(m) {
c := buscompose.ObjectsStreamConfig(o)
out[c.Name] = c
}
return out
}
// creations remembers each stream created, by the manifest digest it was created at: created once per manifest, so a
// stream deleted since is not made again until a new manifest or a hand assert (grants_assert).
type creations struct {
mu sync.Mutex
made map[string]string
// raised is, by stream, the manifest digest at which its size cap was last compared with the manifest's, so the bus is
// asked for it once per manifest (a hand assert asks again).
raised map[string]string
// refused is, by stream, the refusal of the last addition of subjects (an overlap with another stream, say), so a
// refusal that stands is said once and not at every pass; a success or a different refusal says again.
refused map[string]string
}
// refusedAgain says whether this refusal of an addition to the stream was the last one said, and keeps it.
func (c *creations) refusedAgain(stream, why string) bool {
c.mu.Lock()
defer c.mu.Unlock()
if c.refused == nil {
c.refused = map[string]string{}
}
again := c.refused[stream] == why
c.refused[stream] = why
return again
}
func (c *creations) cleared(stream string) {
c.mu.Lock()
defer c.mu.Unlock()
delete(c.refused, stream)
}
func (c *creations) madeAt(stream string) string {
c.mu.Lock()
defer c.mu.Unlock()
return c.made[stream]
}
func (c *creations) raisedAt(stream string) string {
c.mu.Lock()
defer c.mu.Unlock()
return c.raised[stream]
}
func (c *creations) keepRaised(stream, digest string) {
c.mu.Lock()
defer c.mu.Unlock()
if c.raised == nil {
c.raised = map[string]string{}
}
c.raised[stream] = digest
}
func (c *creations) keep(stream, digest string) {
c.mu.Lock()
defer c.mu.Unlock()
if c.made == nil {
c.made = map[string]string{}
}
c.made[stream] = digest
}
// createMissing creates each item of a the bus lacks, with the manifest's limits, and says what became of it. It never
// touches an item the bus holds, and does nothing when what the bus holds was not read. force asks again a stream
// created at this manifest and gone since (a hand assert). It answers the streams created and the size caps raised.
func createMissing(c Creator, done *creations, a *Assertion, m catalogue.Manifest, nodes []string, force bool) ([]string, []Raise) {
cfgs := Configs(m, nodes)
var made []string
a.Says = CreatesMissing
for i := range a.Items {
it := &a.Items[i]
if it.Held != nil || !slices.Contains(it.Differences, "the bus holds no stream "+it.Stream) {
continue
}
if !force && done.madeAt(it.Stream) == a.Manifest {
it.Created = ItemNotCreated + "created at this manifest and gone since; grants_assert creates it again"
continue
}
cfg, ok := cfgs[it.Stream]
if !ok {
it.Created = ItemNotCreated + "no configuration composed for it"
continue
}
switch err := c.CreateDeclared(cfg); {
case err == nil:
it.Created = ItemCreated
done.keep(it.Stream, a.Manifest)
made = append(made, it.Kind+" "+it.Stream)
case errors.Is(err, ErrHeld):
it.Created = ItemNotCreated + ErrHeld.Error()
default:
it.Created = ItemNotCreated + err.Error() + " (tried again at the next event)"
}
}
// A stream the bus holds whose manifest names events it has no subject for gains those subjects, and only ever those: a
// subject the manifest dropped stays, limits and retention are left as they are (the operator, 2026-11-05).
for i := range a.Items {
it := &a.Items[i]
if it.Held == nil || it.Kind != "stream" {
continue
}
var add []string
for _, s := range it.Composed.Subjects {
if !slices.Contains(it.Held.Subjects, s) {
add = append(add, s)
}
}
if len(add) == 0 {
continue
}
if err := c.AddSubjects(it.Stream, add); err != nil {
why := "subjects " + strings.Join(add, ", ") + " not added: " + err.Error()
if done.refusedAgain(it.Stream, why) {
it.Created = why + " (said before; tried again at the next event)" // not ItemNotCreated: said once, not at every pass
} else {
it.Created = ItemNotCreated + why + " (tried again at the next event)"
}
continue
}
done.cleared(it.Stream)
it.Created = "subjects added: " + strings.Join(add, ", ")
made = append(made, "stream "+it.Stream+" gained "+strings.Join(add, ", "))
}
// A held stream, of any kind, whose manifest declares a larger size cap gets that cap, and no other limit changes: a
// cap the bus holds that is larger or equal stays (the operator, 2026-11-09 09:07). Compared once per manifest.
var raises []Raise
for i := range a.Items {
it := &a.Items[i]
if it.Held == nil || it.Composed.MaxBytes <= 0 || (!force && done.raisedAt(it.Stream) == a.Manifest) {
continue
}
from, raised, err := c.RaiseMaxBytes(it.Stream, it.Composed.MaxBytes)
if err != nil {
it.Created = ItemNotCreated + "size cap not raised: " + err.Error() + " (tried again at the next event)"
continue
}
done.keepRaised(it.Stream, a.Manifest)
if raised {
it.Created = fmt.Sprintf("size cap raised from %d to %d bytes", from, it.Composed.MaxBytes)
raises = append(raises, Raise{Stream: it.Stream, From: from, To: it.Composed.MaxBytes})
made = append(made, fmt.Sprintf("%s %s size cap raised from %d to %d bytes", it.Kind, it.Stream, from, it.Composed.MaxBytes))
}
}
if len(made) > 0 {
a.Asserted = true
}
return made, raises
}
// notCreated is each item of a creation refused, with why, as `<stream>: <why>`.
func notCreated(a Assertion) []string {
var out []string
for _, it := range a.Items {
if why, ok := strings.CutPrefix(it.Created, ItemNotCreated); ok && it.Created != "" {
out = append(out, it.Stream+": "+why)
}
}
return out
}
// Composed is a module's buckets, logs and streams as an assertion would ask for them. Pure.
func Composed(m catalogue.Manifest, nodes []string) []Item {
var out []Item
for _, b := range bucketsFor(m, nodes) {
per := b.History
if per < 1 {
per = 1
}
limits := Limits{Subjects: []string{"$KV." + b.Bucket() + ".>"}, Retention: string(buscompose.RetentionLimits),
MaxAgeHours: b.TTLSeconds / 3600, MaxPerSubject: per}
if max := b.MaxBytes(); max > 0 {
limits.MaxBytes = max
}
out = append(out, Item{Kind: "bucket", Stream: "KV_" + b.Bucket(), Composed: limits})
}
for _, l := range logsOf(m) {
c := l.Config()
out = append(out, Item{Kind: "log", Stream: l.Stream(), Composed: Limits{Subjects: set(c.Subjects),
Retention: string(buscompose.RetentionLimits), MaxAgeHours: int(c.MaxAge.Hours()), MaxBytes: c.MaxBytes}})
}
for _, s := range streamsOf(m) {
st := s.Stream()
out = append(out, Item{Kind: "stream", Stream: st.Name, Composed: Limits{Subjects: set(st.Subjects),
Retention: string(st.Retention), MaxAgeHours: st.MaxAge / 3600, MaxBytes: st.MaxBytes}})
}
for _, o := range objectsOf(m) {
c := buscompose.ObjectsStreamConfig(o)
out = append(out, Item{Kind: "objects", Stream: c.Name, Composed: Limits{Subjects: set(c.Subjects),
Retention: string(buscompose.RetentionLimits), MaxBytes: c.MaxBytes}})
}
return out
}
// HeldStreams reads every stream the bus holds through its module's nats_streams, by name.
func HeldStreams(c Caller) (map[string]Limits, error) {
held, _, err := HeldStreamsAndBytes(c)
return held, err
}
// HeldStreamsAndBytes is HeldStreams with each stream's size in bytes, by name (for Full).
func HeldStreamsAndBytes(c Caller) (map[string]Limits, map[string]int64, error) {
raw, err := c.Call(CallStreams, map[string]any{})
if err != nil {
return nil, nil, fmt.Errorf("%s: %w", CallStreams, err)
}
var got struct {
Detail []struct {
Name string `json:"name"`
Subjects []string `json:"subjects"`
Retention string `json:"retention"`
MaxAgeHours int `json:"max_age_hours"`
MaxPerSubject int `json:"max_per_subject"`
Bytes int64 `json:"bytes"`
} `json:"detail"`
}
if err := json.Unmarshal(unwrap(raw), &got); err != nil {
return nil, nil, fmt.Errorf("%s answered no streams: %w", CallStreams, err)
}
out, bytes := map[string]Limits{}, map[string]int64{}
for _, s := range got.Detail {
out[s.Name] = Limits{Subjects: set(s.Subjects), Retention: s.Retention, MaxAgeHours: s.MaxAgeHours, MaxPerSubject: s.MaxPerSubject}
bytes[s.Name] = s.Bytes
}
return out, bytes, nil
}
// Assert composes a module's items and compares each with what the bus holds; held nil is not read. It asserts nothing.
func Assert(module, digest string, m catalogue.Manifest, nodes []string, held map[string]Limits, heldErr error) Assertion {
a := Assertion{Module: module, Manifest: digest, Items: Composed(m, nodes), Says: ShadowAsserts}
for i := range a.Items {
it := &a.Items[i]
if heldErr != nil {
it.Differences = []string{"what the bus holds was not read: " + heldErr.Error()}
continue
}
h, ok := held[it.Stream]
if !ok {
it.Differences = []string{"the bus holds no stream " + it.Stream}
continue
}
it.Held = &h
if !slices.Equal(h.Subjects, it.Composed.Subjects) {
it.Differences = append(it.Differences, fmt.Sprintf("subjects %v held, %v composed", h.Subjects, it.Composed.Subjects))
}
if h.Retention != it.Composed.Retention {
it.Differences = append(it.Differences, fmt.Sprintf("retention %s held, %s composed", h.Retention, it.Composed.Retention))
}
if h.MaxAgeHours != it.Composed.MaxAgeHours {
it.Differences = append(it.Differences, fmt.Sprintf("age %d h held, %d h composed", h.MaxAgeHours, it.Composed.MaxAgeHours))
}
if it.Kind == "bucket" && max(h.MaxPerSubject, 1) != it.Composed.MaxPerSubject {
it.Differences = append(it.Differences, fmt.Sprintf("history %d held, %d composed", h.MaxPerSubject, it.Composed.MaxPerSubject))
}
}
sort.SliceStable(a.Items, func(i, j int) bool { return a.Items[i].Stream < a.Items[j].Stream })
return a
}