package process import ( "context" "fmt" "strings" "sync" "time" "github.com/nats-io/nats.go/jetstream" "git.novox.be/novox/mesh-sdk/go/seatdef" ) // EventHub is the one pull of a module's durable consumer on the shared events stream (novox/hq ADR 0635 ยง5): a module // has one durable, `_`, so two loops pulling it each take messages the other needs. Every part of the // module that hears events registers a handler by subject pattern, and the hub pulls once and hands each message to the // handler whose pattern it matches. A message no handler takes is acknowledged and said, never left to be redelivered. // The hub never makes the stream or the consumer: they are the controller's, and a bus without them is an error of Start. // // Register every handler, then Start once: a message heard before its handler is registered would be taken by none. type EventHub struct { logf func(string, ...any) mu sync.RWMutex routes []hubRoute cons jetstream.ConsumeContext bound []func(created time.Time) // kept are the module's durables on the kept seat events' streams it handles (StartKept). kept []jetstream.ConsumeContext } type hubRoute struct { pattern string handle func(jetstream.Msg) } // NewEventHub is a hub saying through logf (nil says nothing). func NewEventHub(logf func(string, ...any)) *EventHub { if logf == nil { logf = func(string, ...any) {} } return &EventHub{logf: logf} } // Handle registers handle for the subjects matching pattern (`*` one token, `>` the rest). The handler acknowledges // the message itself. A pattern that overlaps one registered (one matches every subject of the other) is refused, // so a message always has one taker. func (h *EventHub) Handle(pattern string, handle func(jetstream.Msg)) error { if pattern == "" || handle == nil { return fmt.Errorf("an event handler needs a subject pattern and a handler") } h.mu.Lock() defer h.mu.Unlock() for _, r := range h.routes { if subjectsOverlap(r.pattern, pattern) { return fmt.Errorf("the events %q overlap %q, already handled: a message has one taker", pattern, r.pattern) } } h.routes = append(h.routes, hubRoute{pattern, handle}) return nil } // OnBound registers f, told each time the hub binds the module's consumer, with when the bus made it. A consumer is made // from now (ADR 0443), so an event said before it was made is not delivered to it: a part that took a picture before // that must ask its owner again (views.Follower.ConsumerMade). So every handler of an event that ends a kept call's wait // (a callee's "my state changed") also registers here the call it makes on that event, made again once at each bind // (novox/hq ADR 0668; issue 1966). Register before Start. func (h *EventHub) OnBound(f func(created time.Time)) { h.mu.Lock() h.bound = append(h.bound, f) h.mu.Unlock() } // Patterns are the registered subject patterns, in order. func (h *EventHub) Patterns() []string { h.mu.RLock() defer h.mu.RUnlock() out := make([]string, len(h.routes)) for i, r := range h.routes { out[i] = r.pattern } return out } // Start binds the module's durable on the shared events stream and pulls it; a call after a start that took does // nothing. It makes no stream and no consumer: a consumer the bus does not hold yet is the error of this call, and a // later call (the module's next change of membership) binds it, so a part is not lost for the bus's order. func (h *EventHub) Start(ctx context.Context, js jetstream.JetStream, cred Account) error { h.mu.Lock() defer h.mu.Unlock() if h.cons != nil { return nil } cons, err := cred.EventConsumer(ctx, js, EventsStream) if err == nil { h.cons, err = HearEvents(cons, h.hear, h.logf) } if err != nil { return fmt.Errorf("the consumer %s on %s is not heard: %w", cred.EventConsumerName(), EventsStream, err) } if info, ierr := cons.Info(ctx); ierr != nil { h.logf("events: the consumer %s on %s is heard, but its information is not read (%v): a first view taken before it was made is not asked again", cred.EventConsumerName(), EventsStream, ierr) } else { h.logf("events: the consumer %s on %s is heard; the bus made it at %s", cred.EventConsumerName(), EventsStream, info.Created.UTC().Format(time.RFC3339)) for _, f := range h.bound { f(info.Created.UTC()) } } return nil } // StartUntilBound is Start that does not give up: when the module's consumer is not there yet it returns that error at // once, and tries again on a goroutine of its own, after each wait, until it binds or ctx ends; then live is called (nil // calls nothing), so a part that needs the events path live does what it does only then. wait returns false to stop // trying (nil waits five seconds or for ctx). The bus makes the consumer when the module's account is composed, which // says nothing a module can hear before the consumer exists, so the retry is a wait on that, bounded by ctx. func (h *EventHub) StartUntilBound(ctx context.Context, js jetstream.JetStream, cred Account, wait func(context.Context) bool, live func()) error { err := h.Start(ctx, js, cred) if err == nil { if live != nil { live() } return nil } if wait == nil { wait = func(ctx context.Context) bool { t := time.NewTimer(5 * time.Second) defer t.Stop() select { case <-ctx.Done(): return false case <-t.C: return true } } } go func() { for wait(ctx) && ctx.Err() == nil { if h.Start(ctx, js, cred) == nil { if live != nil { live() } return } } }() return err } // Stop ends the pull. func (h *EventHub) Stop() { h.mu.Lock() defer h.mu.Unlock() if h.cons != nil { h.cons.Stop() h.cons = nil } for _, cc := range h.kept { cc.Stop() } h.kept = nil } // StartKept binds, beside EVENTS, the module's durable on each kept seat event's stream (`SEAT__`) whose event a // registered pattern takes: a kept event is never on EVENTS, and the tool runner reads its own twin of that durable (lead // answer A-397), so the program hears it only here. Each stream bound is said, and each it cannot bind (no durable composed // for this module there, or the bus refuses) is said and passed over. It returns how many it bound. func (h *EventHub) StartKept(ctx context.Context, js jetstream.JetStream, cred Account) int { h.mu.RLock() var patterns []string for _, r := range h.routes { patterns = append(patterns, r.pattern) } h.mu.RUnlock() names := js.StreamNames(ctx) var streams []string for name := range names.Name() { streams = append(streams, name) } if err := names.Err(); err != nil { h.logf("events: the kept seat events' streams are not listed (%v): none of them is heard", err) } bound := 0 for _, stream := range streams { seat, event, ok := keptSeatEvent(stream) if !ok { continue } subject := "mesh.seat." + seat + ".event." + event taken := false for _, p := range patterns { if subjectMatches(p, subject) || subjectMatches(p, subject+".x") { taken = true break } } if !taken { continue } cc, err := cred.HearSeatEvents(ctx, js, stream, h.hear, h.logf) if err != nil { h.logf("events: the kept event %s.%s is not heard on %s: %v", seat, event, stream, err) continue } h.mu.Lock() h.kept = append(h.kept, cc) h.mu.Unlock() bound++ h.logf("events: the consumer %s on %s is heard (the kept event %s.%s)", cred.EventConsumerName(), stream, seat, event) } return bound } // keptSeatEvent is the seat and the event a kept seat event's stream carries, from its name `SEAT__` (seatdef.KeptStream): // a seat's and an event's names hold no underscore. func keptSeatEvent(stream string) (seat, event string, ok bool) { rest, isKept := strings.CutPrefix(stream, seatdef.KeptStreamPrefix) if !isKept { return "", "", false } seat, event, ok = strings.Cut(rest, "_") if !ok || seat == "" || event == "" || strings.Contains(event, "_") { return "", "", false } return seat, event, true } func (h *EventHub) hear(m jetstream.Msg) { h.mu.RLock() var take func(jetstream.Msg) for _, r := range h.routes { if subjectMatches(r.pattern, m.Subject()) { take = r.handle break } } h.mu.RUnlock() if take == nil { h.logf("events: %s is taken by no handler of this module, acknowledged", m.Subject()) _ = m.Ack() return } take(m) } // subjectMatches says whether subject is one the pattern (`*` one token, `>` the rest) names. func subjectMatches(pattern, subject string) bool { pt, st := strings.Split(pattern, "."), strings.Split(subject, ".") for i, t := range pt { if t == ">" { return len(st) > i } if i >= len(st) || (t != "*" && t != st[i]) { return false } } return len(pt) == len(st) } // subjectsOverlap says whether some subject matches both patterns. func subjectsOverlap(a, b string) bool { at, bt := strings.Split(a, "."), strings.Split(b, ".") for i := 0; ; i++ { if i >= len(at) || i >= len(bt) { return len(at) == len(bt) } if at[i] == ">" || bt[i] == ">" { return true } if at[i] != "*" && bt[i] != "*" && at[i] != bt[i] { return false } } }