Files
mesh-sdk/go/process/module.go
T
jschoubben fedf9d2e7b Pull small batches in the event hub and keep slow handlers alive (H-A-281)
The hub pulled the bus client's default 500 messages per pull and handled
them one by one, so buffered messages outlived the 30 s ack wait and were
given again and handled twice (met live on the builder: 37 of 38
outstanding redelivered). HearEvents, the one pull of the hub and of
HearStream, now pulls at most twenty messages per pull and says in
progress for a message whose handler runs past a third of the consumer's
ack wait, read once from the bound consumer's information.

Builds: design 47 H H-A-281
2026-11-21 16:48:05 +01:00

165 lines
7.1 KiB
Go

package process
import (
"context"
"errors"
"fmt"
"strings"
"time"
"github.com/nats-io/nats.go"
"github.com/nats-io/nats.go/jetstream"
)
// What a module's own principal reaches on the bus beyond a process account's queue (novox/hq issue 1242): its
// own credential, its own stream and its durable consumer on the shared events stream. These helpers are the one
// place a long-running part of a module (a daemon the module's delivery runs) learns them, so no part hand-writes
// the connection, the subject spaces or the consumer's name.
// EventsStream is the shared stream every module's events (mesh.mod.<module>.event.>) are on; a module's consumer
// on it is the durable <node>_<module> the controller makes (mesh-controller internal/broker/nats.go
// consumerStream, consumerDurable).
const EventsStream = "EVENTS"
// BrokerFileEnv names the environment variable holding the path of the module's own broker credential.
const BrokerFileEnv = "MESH_BROKER_FILE"
// ReadBrokerAccount reads the module's own credential from the file BrokerFileEnv names in getenv.
func ReadBrokerAccount(getenv func(string) string) (Account, error) {
path := strings.TrimSpace(getenv(BrokerFileEnv))
if path == "" {
return Account{}, errors.New(BrokerFileEnv + " is not set, so there is no credential to hear the bus with")
}
return ReadAccount(path)
}
// DialOptions is the option list Dial connects with: named <node>.<module>, as the account's user on its own
// inbox prefix, reconnecting without limit and retrying a first connect that fails, pinned to the account's
// fingerprint when it carries one; opts follow, so a caller may add a handler or override one.
func (a Account) DialOptions(opts ...nats.Option) []nats.Option {
all := []nats.Option{
nats.Name(a.Node + "." + a.Module),
nats.UserInfo(a.User, a.Password),
nats.CustomInboxPrefix(a.InboxPrefix()),
nats.MaxReconnects(-1),
nats.RetryOnFailedConnect(true),
}
if strings.TrimSpace(a.Fingerprint) != "" {
all = append(all, nats.Secure(PinnedToFingerprint(a.Fingerprint)))
}
return append(all, opts...)
}
// Dial connects as the module's own principal and opens JetStream on the connection. The caller closes the
// connection.
func (a Account) Dial(opts ...nats.Option) (*nats.Conn, jetstream.JetStream, error) {
OwnBuild()
nc, err := nats.Connect(a.URL, a.DialOptions(opts...)...)
if err != nil {
return nil, nil, fmt.Errorf("connecting to the bus: %w", err)
}
js, err := jetstream.New(nc)
if err != nil {
nc.Close()
return nil, nil, err
}
return nc, js, nil
}
// EventSubject is where the module's event lands on the shared events stream: mesh.mod.<module>.event.<event>.
func (a Account) EventSubject(event string) string { return "mesh.mod." + a.Module + ".event." + event }
// StreamSubject is where the module's event lands on a stream of its own: mesh.stream.<module>.event.<event>
// (mesh-controller internal/broker/modstreams.go ModuleStreamSubject).
func (a Account) StreamSubject(event string) string { return ModuleStreamSubject(a.Module, event) }
// BusSubject is where the module's event lands on a stream it asked for by template: mesh.bus.<module>.<local>.<event>,
// <local> being the stream's local name in the module's `requires` (the bus module's keeper, PlanOf; A-41).
func (a Account) BusSubject(local, event string) string {
return "mesh.bus." + a.Module + "." + local + "." + event
}
// ModuleStreamSubject is where a module's event lands on that module's own stream, for a part that names another
// module's stream (the indexer hears the forge bridge's, the checker's) without holding its credential.
func ModuleStreamSubject(module, event string) string {
return "mesh.stream." + module + ".event." + event
}
// EventConsumerName is the module's durable consumer on a stream it is granted: <node>_<module>.
func (a Account) EventConsumerName() string { return a.Node + "_" + a.Module }
// EventConsumer binds the module's durable consumer on stream (EventsStream, or a stream of another module it is
// granted).
func (a Account) EventConsumer(ctx context.Context, js jetstream.JetStream, stream string) (jetstream.Consumer, error) {
return js.Consumer(ctx, stream, a.EventConsumerName())
}
// NamedEventConsumer binds the module's durable consumer named for a suffix on stream: <node>_<module>_<suffix>, beside
// EventConsumer's <node>_<module> (design 47 H §743, H-A-90: the indexer's one durable per watched branch).
func (a Account) NamedEventConsumer(ctx context.Context, js jetstream.JetStream, stream, suffix string) (jetstream.Consumer, error) {
return js.Consumer(ctx, stream, a.namedEventConsumerName(suffix))
}
func (a Account) namedEventConsumerName(suffix string) string {
return a.EventConsumerName() + "_" + suffix
}
// HearEvents pulls from cons, handing each message to handle, and says every error the bus reports while
// hearing through logf ("hearing the bus: ..."). The caller stops the returned context. A durable this process pulls
// already is refused (ConsumeOnce, design 47 H, H-A-196).
//
// It pulls at most hubPullMessages messages per pull, and says in progress to the bus for a message whose handler runs
// past a third of the consumer's ack wait, again at each further third until the handler returns (design 47 H, H-A-281):
// handlers run one by one, so a large pull's buffered messages would outlive the ack wait and be given again. The ack
// wait is read once, from the consumer's information as the bind read it.
func HearEvents(cons jetstream.Consumer, handle func(jetstream.Msg), logf func(string, ...any)) (jetstream.ConsumeContext, error) {
return hearEvents(cons, callerOutside(), handle, logf, realTicker)
}
// hubPullMessages is how many messages the event hub pulls at most per pull (design 47 H, H-A-281).
const hubPullMessages = 20
// ticker answers a channel ticking every d and its stop.
type ticker func(d time.Duration) (<-chan time.Time, func())
func realTicker(d time.Duration) (<-chan time.Time, func()) {
t := time.NewTicker(d)
return t.C, t.Stop
}
func hearEvents(cons jetstream.Consumer, binder string, handle func(jetstream.Msg), logf func(string, ...any), tick ticker) (jetstream.ConsumeContext, error) {
var ackWait time.Duration
if info := cons.CachedInfo(); info != nil {
ackWait = info.Config.AckWait
}
return ConsumeOnce(cons, binder, keptInProgress(handle, ackWait/3, tick), jetstream.PullMaxMessages(hubPullMessages),
jetstream.ConsumeErrHandler(func(_ jetstream.ConsumeContext, err error) {
logf("hearing the bus: %v", err)
}))
}
// keptInProgress is handle that says in progress for its message at every tick of every while the handler runs, the
// ticker stopped at the handler's return (design 47 H, H-A-281); with no every it is handle as it is.
func keptInProgress(handle func(jetstream.Msg), every time.Duration, tick ticker) jetstream.MessageHandler {
if every <= 0 {
return handle
}
return func(m jetstream.Msg) {
ticks, stop := tick(every)
done, ended := make(chan struct{}), make(chan struct{})
go func() {
defer close(ended)
for {
select {
case <-done:
return
case <-ticks:
_ = m.InProgress()
}
}
}()
defer func() { close(done); stop(); <-ended }()
handle(m)
}
}