docs(eventbus,eventlogger,chimux): clarify review feedback; add exporter build-tag guidance

Author: intel352

modules/chimux/module.go

@@ -146,15 +146,19 @@ type ChiMuxModule struct {
 	subject       modular.Subject // Added for event observation
 	// disabledRoutes keeps track of routes that have been disabled at runtime.
 	// Keyed by HTTP method (uppercase) then the original registered pattern.
+	// A disabled route short‑circuits matching before reaching the underlying chi mux
+	// allowing dynamic feature flag style shutdown without removing the route from
+	// the registry (so it can be re‑enabled later). Patterns are stored exactly as
+	// originally registered to avoid ambiguity with chi's internal normalized form.
 	disabledRoutes map[string]map[string]bool
 	// disabledMu guards access to disabledRoutes for concurrent reads/writes.
 	disabledMu sync.RWMutex
 	// routeRegistry tracks registered routes with their methods for runtime management.
 	routeRegistry []struct{ method, pattern string }
 	// middleware tracking for runtime enable/disable
 	middlewareMu    sync.RWMutex
-	middlewares     map[string]*controllableMiddleware
-	middlewareOrder []string
+	middlewares     map[string]*controllableMiddleware // keyed by middleware name provided at registration
+	middlewareOrder []string                           // preserves deterministic application order for rebuilds
 }
 
 // NewChiMuxModule creates a new instance of the chimux module.

modules/eventbus/memory.go

@@ -214,8 +214,23 @@ func (m *MemoryEventBus) Publish(ctx context.Context, event Event) error {
 		return nil
 	}
 
-	// Optional rotation for fairness. We deliberately removed the previous random shuffle fallback
-	// (when rotation disabled) to preserve deterministic ordering and avoid per-publish RNG cost.
+	// Optional rotation for fairness.
+	// Rationale:
+	//   * Deterministic order when rotation disabled (stable slice) improves testability and
+	//     reasoning about delivery ordering.
+	//   * When rotation enabled we perform a logical rotation using an incrementing counter
+	//     rather than allocating + copying on every publish via append/slice tricks or
+	//     performing a random shuffle. This yields O(n) copies only when the starting offset
+	//     changes (and only for length > 1) with no RNG cost and avoids uint64->int casts
+	//     that would require additional lint suppression.
+	//   * Slice re-slicing with append could avoid an allocation in the start!=0 case, but the
+	//     explicit copy keeps the code straightforward and side-effect free (no aliasing that
+	//     could surprise future mutations) while cost is negligible relative to handler work.
+	//   * We intentionally do not randomize: fairness over time is achieved by round‑robin
+	//     style rotation (pubCounter % len) which ensures equal start positions statistically
+	//     without introducing randomness into delivery order for reproducibility.
+	// If performance profiling later shows this allocation hot, a specialized in-place rotate
+	// could be introduced guarded by benchmarks.
 	if m.config.RotateSubscriberOrder && len(allMatchingSubs) > 1 {
 		pc := atomic.AddUint64(&m.pubCounter, 1) - 1
 		ln := len(allMatchingSubs) // ln >= 2 here due to enclosing condition

modules/eventbus/metrics_exporters.go

@@ -21,10 +21,13 @@ package eventbus
 //   go exporter.Run(ctx)
 //   ... later cancel();
 //
-// NOTE: Prometheus and Datadog dependencies are optional. If you want to exclude one of these
-// exporters for a build, prefer Go build tags (e.g. //go:build !prometheus) with the exporter
-// implementation moved to a separate file guarded by that tag, rather than manual comment edits.
-// This file keeps both implementations active by default for convenience.
+// NOTE: Prometheus and Datadog dependencies are optional. If you want to exclude an exporter
+// from a particular build, prefer Go build tags instead of editing this file manually. Example:
+//   //go:build !prometheus
+//   // +build !prometheus
+// Move the Prometheus collector implementation into a prometheus_collector.go file guarded by
+// a complementary build tag (e.g. //go:build prometheus). This keeps the default experience
+// simple (both available) while allowing consumers to tailor binaries without forking.
 
 import (
 	"context"

modules/eventbus/module.go

@@ -149,7 +149,8 @@ type EventBusModule struct {
 	router    *EngineRouter
 	mutex     sync.RWMutex
 	isStarted bool
-	subject   modular.Subject // For event observation (guarded by mutex)
+	subject   modular.Subject // Observer notification target (lazy-created). Guarded by mutex; kept nil until a consumer
+	// requests observation to avoid allocation for apps that never observe bus events.
 }
 
 // DeliveryStats represents basic delivery outcomes for an engine or aggregate.

modules/eventlogger/module.go

@@ -603,7 +603,12 @@ func (m *EventLoggerModule) OnEvent(ctx context.Context, event cloudevents.Event
 				queueResult = nil
 				return
 			} else {
-				// Queue is full - drop oldest event and add new one
+				// Queue is full - drop oldest event and add new one. We log both the incoming event type
+				// and the dropped oldest event type for observability. This path intentionally avoids
+				// emitting an operational CloudEvent because the logger itself is not yet started; emitting
+				// here would risk recursive generation of events that also attempt to enqueue. Once started,
+				// pressure signals are emitted via BufferFull/EventDropped events on the hot path with
+				// safeguards to prevent amplification loops (see further below in non-started path logic).
 				var droppedEventType string
 				if len(m.eventQueue) > 0 {
 					// Capture dropped event type for debugging visibility then shift slice