engine

type BrokerController interface {
	StopBroker(ctx context.Context, name string) error
	StartBroker(ctx context.Context, name string) error
}

type Config struct {
	Kafka     kafka.Config
	Scenarios []*scenario.Scenario

	// Duration of zero means run until the context is cancelled.
	Duration time.Duration

	NoConsumers    bool
	RecreateTopics bool

	// SkipTopicCreation leaves topic management entirely alone: nothing is created and
	// nothing is deleted.
	//
	// It exists for clusters where khaos has no CreateTopics permission, which is the
	// normal case on a managed cluster, so conflating it with RecreateTopics (only
	// skipping the DELETE half) leaves exactly that user failing at startup on the
	// CreateTopics call.
	SkipTopicCreation bool

	// Seed makes generated data reproducible. A zero Seed means "pick one", and the
	// chosen value is reported so a run can be replayed.
	Seed uint64

	// Brokers is nil for external clusters, where broker faults are unavailable.
	Brokers BrokerController

	// Registry is the Schema Registry endpoint and its credentials.
	//
	// A bare URL is enough for the bundled local registry; Confluent Cloud and Aiven
	// require auth. An empty Registry.URL falls back to the scenario's own
	// `schema_registry:` block.
	Registry codec.RegistryConfig

	// LagPoll is how often to ask the brokers for real consumer-group lag. Zero disables
	// polling, which is the default.
	//
	// The self-reported Lag figure is produced-minus-consumed from khaos's own in-process
	// counters -- wrong the moment anything else touches the topic, and meaningless
	// across restarts. Real lag needs admin traffic and DESCRIBE rights, which a managed
	// cluster may not grant, so it is opt-in and MUST degrade to "unknown" rather than
	// failing the run.
	LagPoll time.Duration

	Logger *slog.Logger

	// Metrics is where per-message Prometheus counters are recorded, keyed by topic and
	// group as telemetry.Metrics defines. Nil disables it entirely -- every call site
	// checks before touching it, so an engine built without --metrics-addr pays nothing
	// beyond the nil check.
	Metrics *telemetry.Metrics
}

type Consumer struct {
	ID      scenario.ID
	Topic   string
	GroupID string
	Topics  []string
	Conf    scenario.ConsumerConf
	// contains filtered or unexported fields
}

type Engine struct {
	// contains filtered or unexported fields
}

type Event struct {
	At      time.Time
	Message string
	Level   EventLevel
}

type EventLevel = scenario.EventLevel

type FlowStat struct {
	Name      string
	Started   int64
	Completed int64
	Messages  int64
	Errors    int64

	// InFlight is the number of flow instances currently executing their step delays.
	// The pool is bounded and this depth is reported live.
	InFlight  int64
	Saturated int64 // times issuance blocked because the pool was full
}

type GroupStat struct {
	GroupID   string
	Consumers int
	Consumed  int64
	Failed    int64
	DLQ       int64
	Paused    int
}

type Producer struct {
	ID    scenario.ID
	Topic string
	// contains filtered or unexported fields
}

type Snapshot struct {
	At       time.Time
	Elapsed  time.Duration
	Scenario string

	// Deadline is the configured run duration; zero means run until interrupted.
	Deadline time.Duration

	Topics []TopicStat
	Flows  []FlowStat
	Events []Event

	TotalProduced int64
	TotalConsumed int64
	TotalErrors   int64
	Rebalances    int64

	// Healthy is false when the engine has recorded a condition it cannot recover from
	// on its own. It drives /healthz.
	Healthy  bool
	Stopping bool
}

type TopicStat struct {
	Topic    string
	Scenario string

	Produced   int64
	Consumed   int64
	Bytes      int64
	ProduceErr int64
	ConsumeErr int64
	Duplicates int64

	// CommitErr counts offsets khaos declined to commit or failed to commit.
	CommitErr int64

	// Failed, DLQ and Retries are only meaningful when failure simulation is enabled.
	Failed  int64
	DLQ     int64
	Retries int64

	// Lag is produced-minus-consumed from khaos's own counters -- a self-report, not
	// Kafka consumer lag. It is meaningless across restarts and wrong whenever anything
	// else produces to or consumes from the topic. It is always populated because it
	// costs nothing; BrokerLag is the real answer when the cluster will give one.
	Lag int64

	// BrokerLag is real committed-offset-vs-end-offset lag per group, summed over the
	// topic's partitions and populated only when lag polling is enabled (Config.LagPoll).
	//
	// Nil means "not measured" and MUST be rendered as unknown rather than zero: polling
	// off, the group not created yet, and a cluster that denies DESCRIBE on consumer
	// groups all land here, and none of them means the group has caught up. A group
	// missing from a non-nil map is unknown for the same reason -- the other groups
	// answered and it did not.
	BrokerLag map[string]int64

	Groups []GroupStat
}