package buscompose

// A Consumer is a durable subscription the controller creates on a module's behalf. A module
// declares what it reacts to, never how delivery works, so it does not name these and cannot
// misconfigure them.
type Consumer struct {
	Name   string
	Stream string
	// Filters are the subjects this consumer receives. One consumer per module with several
	// filters, rather than one per consumed event: its ack subject is derived from its name, and
	// a module with five consumers would need five ack permissions to ack its own deliveries.
	Filters []string
	// Queue is the queue group, set for a seat's worker so that "exactly one holder" survives a
	// seat later being relaxed to several. Authority and delivery are kept separate on purpose.
	Queue string
	// Push asks the server to deliver to a subject rather than wait to be pulled.
	//
	// For the mesh's own consumer, where the controller wants every message to arrive in the one
	// loop it already runs: pulling would mean a second goroutine fetching batches and handing
	// them over, and a loop that acts on one message at a time is the property the store window
	// depends on. A queue group implies this, because a group has nothing to pull from.
	Push bool
	// TakesOverFrom names a consumer of the same stream whose filter this one takes over (issue 973): made while
	// that consumer still filters this one's subject, it starts after what that consumer has acknowledged, so a
	// message the old one held unacknowledged is not lost to the change. Otherwise it starts as FromNow says.
	TakesOverFrom string
	// DeliverSubject, when set, is where a push consumer delivers instead of DeliverSubjectFor's.
	DeliverSubject string
	// AckWaitSeconds before an unacknowledged delivery is redelivered.
	AckWaitSeconds int
	// MaxDeliver is how often a message is handed over before the consumer gives it up; zero for no
	// bound. What a consumer gives up is kept in DEAD_LETTERS by the controller (novox/hq issue 330).
	MaxDeliver int
	// MaxAckPending is how many deliveries the server lets stand unacknowledged at once; zero for
	// the server's default, which is many. **One, for a consumer handled one at a time**
	// (novox/hq issue 175): a handler that builds for minutes keeps its own message alive with a
	// heartbeat, but everything handed over behind it times out unacknowledged and comes back —
	// and a merge that came back rebuilt what it had just built, five times over on 2026-09-30.
	// With one outstanding, the server holds the rest, and the heartbeat is keeping the message.
	MaxAckPending int
	// FromNow makes a consumer that does not exist yet start at the stream's end rather than its
	// beginning (novox/hq issue 248). For a consumer that reacts to announcements — a merge, a build's
	// outcome — on a stream that keeps a week of them: the server's default, everything the stream
	// holds, replays every merge and every build of that week as if it had just happened. A consumer
	// that exists keeps where it is, whatever this says; only its making is decided here.
	FromNow bool
	Why     string
	// Resettable says why this consumer may be re-made to deliver from now by the mesh itself, with
	// nobody asked (novox/hq to-be 45 §7, healer H4): what a reset drops, something else catches up.
	// Empty for every consumer where nothing would — a module's, whose events would be lost to it.
	// Not a property of the consumer on the bus: nothing here is sent to the server.
	Resettable string
}

// ModuleConsumer is one module's durable consumer, with the module and node it is for.
type ModuleConsumer struct {
	Node, Module string
	Consumer     Consumer
}