chore(testing): add eventloop tests, improve test coverage (#61)

* chore(testing): add eventloop tests, improve test coverage

* chore(testing): reduce flaky testing count, supress logs

Author: Izzette

Makefile

@@ -44,8 +44,7 @@ benchmark: tmp/coverage ## Run the benchmarks
 .PHONY: test-flakiness
 test-flakiness: tmp/coverage ## Run the unit tests with a high count to ensure they are not flaky
 	@echo "🧪 running the unit tests with a high count to ensure they are not flaky …"
-	# Yes, we really can run the tests 10000 times in just a few seconds
-	go test -timeout 2m -count 10000 -failfast -skip '^Example' ./...
+	go test -timeout 2m -count 100 -failfast -skip '^Example' ./...
 
 .PHONY: lint
 lint: ## Run the linters

doc/ARCHITECTURE.md

@@ -11,9 +11,11 @@ The Events API is also monitored to gather the `image_pull` metric type.
 ### Data-flow
 
 The [`main`](../cmd/kube-transition-metrics/main.go) function starts the
-[`PodCollector`](../internal/statistics/pod_collector.go), the
-[`PodStatisticEventLoop`](../internal/statistics/event_loop.go), the
-[`ImagePullStatisticEventLoop`](../internal/statistics/event_loop.go), and the HTTP server.
+[`PodCollector`](../internal/statistics/types/types.go), the
+[`PodStatisticEventLoop`](../internal/statistics/types/types.go), the
+[`ImagePullStatisticEventLoop`](../internal/statistics/types/types.go), and the HTTP server.
+`PodCollector` is an interface defined in [`internal/statistics/types`](../internal/statistics/types/types.go),
+implemented by the private `podCollector` struct in [`internal/statistics`](../internal/statistics/pod_collector.go).
 The `PodCollector` gets the list of currently existing pods.
 Any pods created before the `PodCollector` starts up cannot be tracked, as we missed crucial milestones in the Pod's
 life-cycle.
@@ -41,9 +43,9 @@ title: "kube-transition-metrics Data-flow"
 ---
 flowchart TD
     main["./cmd/kube-transition-metrics.main()"]
-    PodCollector["./internal/statistics.PodCollector"]
-    PodStatisticEventLoop["./internal/statistics.PodStatisticEventLoop"]
-    ImagePullStatisticEventLoop["./internal/statistics.ImagePullStatisticEventLoop"]
+    PodCollector["./internal/statistics/types.PodCollector"]
+    PodStatisticEventLoop["./internal/statistics/types.PodStatisticEventLoop"]
+    ImagePullStatisticEventLoop["./internal/statistics/types.ImagePullStatisticEventLoop"]
     imagePullCollector["./internal/statistics.imagePullCollector"]
     Stdout["/dev/stdout"]
 
@@ -63,24 +65,24 @@ flowchart TD
 
 ### Pod Collector zoom-in
 
-The `PodCollector` goroutine receives added, modified, and deleted Pod events from the Kubernetes API.
-When Pods are added, the `PodCollector` sends an event to the `PodStatisticEventLoop` to create a new tracked
+The `podCollector` goroutine receives added, modified, and deleted Pod events from the Kubernetes API.
+When Pods are added, the `podCollector` sends an event to the `PodStatisticEventLoop` to create a new tracked
 [`PodStatistic`](../internal/statistics/state/pod.go), and launches a new `imagePullCollector` routine to track Events
 involving the Pod UID.
-When Pods are modified, the `PodStatisticEventLoop` receives an event to update the `PodStatistic`.
-When Pods are deleted , the `PodStatisticEventLoop` receives an event to remove the `PodStatistic` from tracking,
-then the `imagePullCollector` routine is canceled for this Pod.
+When Pods are modified, the `podCollector` sends an event to the `PodStatisticEventLoop` to update the `PodStatistic`.
+When Pods are deleted, the `podCollector` sends an event to the `PodStatisticEventLoop` to remove the `PodStatistic`
+from tracking, then the `imagePullCollector` routine is canceled for this Pod.
 
 ```mermaid
 ---
 title: "kube-transition-metrics Pod Collector"
 ---
 flowchart TD
-    PodCollector["./internal/statistics.PodCollector"]
+    PodCollector["./internal/statistics/types.PodCollector"]
     imagePullCollector["./internal/statistics.imagePullCollector"]
     PodsWatch["k8s.io/api/core/v1.PodInterface"]
     Pod["k8s.io/api/core/v1.Pod"]
-    PodStatisticEventLoop["./internal/statistics.PodStatisticEventLoop"]
+    PodStatisticEventLoop["./internal/statistics/types.PodStatisticEventLoop"]
 
     PodCollector
         -->|"Watch(...)"| PodsWatch
@@ -108,7 +110,7 @@ flowchart TD
     imagePullCollector["./internal/statistics.imagePullCollector"]
     EventsWatch["k8s.io/api/core/v1.EventInterface"]
     Event["k8s.io/api/core/v1.Event"]
-    ImagePullStatisticEventLoop["./internal/statistics.ImagePulltatisticEventLoop"]
+    ImagePullStatisticEventLoop["./internal/statistics/types.ImagePullStatisticEventLoop"]
 
     imagePullCollector
         -->|"Watch(...)"| EventsWatch
@@ -122,7 +124,9 @@ flowchart TD
 
 The data model for the pod statistics is composed of the following main components:
 
-- `PodStatisticEventLoop`: The main event loop that handles the [`PodStatistics`](../internal/statistics/state/pod.go)
+- [`PodStatisticEventLoop`](../internal/statistics/types/types.go): An interface defined in
+  `internal/statistics/types`, implemented by the private `podStatisticEventLoop` in `internal/statistics`.
+  The main event loop that handles the [`PodStatistics`](../internal/statistics/state/pod.go)
   and has exclusive access to modify the statistics through dispatched events.
 - `PodStatistics`: The statistics for all tracked pods, which contains a map of pod UIDs to their respective
   `PodStatistic` as well as a list of UIDs that should not be tracked.
@@ -141,7 +145,7 @@ The data model for the pod statistics is composed of the following main componen
 title: "kube-transition-metrics Pod Statistic Data Model"
 ---
 flowchart TD
-    PodStatisticEventLoop["./internal/statistics.PodStatisticEventLoop"]
+    PodStatisticEventLoop["./internal/statistics/types.PodStatisticEventLoop"]
     PodStatistics["./internal/statistics/state.PodStatistics"]
     PodStatistic["./internal/statistics/state.PodStatistic"]
     blacklistUIDs["[]k8s.io/apimachinery/pkg/types.UID"]
@@ -163,8 +167,10 @@ flowchart TD
 
 The data model for the image pull statistics is composed of the following main components:
 
-- [`ImagePullStatisticEventLoop`](../internal/statistics/event_loop.go): The main event loop that handles the
-  `PodImagePullStatistic` and has exclusive access to modify the statistics through dispatched events.
+- [`ImagePullStatisticEventLoop`](../internal/statistics/types/types.go): An interface defined in
+  `internal/statistics/types`, implemented by the private `imagePullStatisticEventLoop` in `internal/statistics`.
+  The main event loop that handles the `PodImagePullStatistic` and has exclusive access to modify the statistics
+  through dispatched events.
 - [`ImagePullStatistics`](../internal/statistics/state/image_pull.go): The statistics for all tracked pods, which
   contains a map of pod UIDs to their respective `PodImagePullStatistic`.
 - `PodImagePullStatistic`: A collection of the
@@ -176,7 +182,7 @@ The data model for the image pull statistics is composed of the following main c
 title: "kube-transition-metrics Image Pull Statistic Data Model"
 ---
 flowchart TD
-    ImagePullStatisticEventLoop["./internal/statistics.ImagePullStatisticEventLoop"]
+    ImagePullStatisticEventLoop["./internal/statistics/types.ImagePullStatisticEventLoop"]
     ImagePullStatistics["./internal/statistics/state.ImagePullStatistics"]
     PodImagePullStatistic["./internal/statistics/state.PodImagePullStatistic"]
     ContainerImagePullStatistic["./internal/statistics/state.ContainerImagePullStatistic"]

internal/statistics/event_loop.go

@@ -21,18 +21,21 @@ import (
 	apimachinerytypes "k8s.io/apimachinery/pkg/types"
 )
 
-// PodStatisticEventLoop loops over pod statistic events sent by collectors to track and update metrics.
-type PodStatisticEventLoop struct {
+// podStatisticEventLoop loops over pod statistic events sent by collectors to track and update metrics.
+type podStatisticEventLoop struct {
 	safeconcurrencytypes.EventLoop[*state.PodStatistics]
 
 	options      *options.Options
 	watcherChan  <-chan struct{}
 	metricOutput io.Writer
 }
 
-// NewStatisticEventLoop creates a new StatisticEventHandler which filters out events for the provided
+// NewStatisticEventLoop creates a new podStatisticEventLoop which filters out events for the provided
 // initialSyncBlacklist Pod UIDs.
-func NewStatisticEventLoop(options *options.Options, metricOutput io.Writer) *PodStatisticEventLoop {
+//
+// The returned *podStatisticEventLoop implements
+// [github.com/BackMarket-oss/kube-transition-metrics/internal/statistics/types.PodStatisticEventLoop].
+func NewStatisticEventLoop(options *options.Options, metricOutput io.Writer) *podStatisticEventLoop {
 	s := state.NewPodStatistics([]apimachinerytypes.UID{})
 	snapshot := snapshot.NewCopyable[*state.PodStatistics](s)
 
@@ -43,33 +46,33 @@ func NewStatisticEventLoop(options *options.Options, metricOutput io.Writer) *Po
 	//nolint:gosec // We already check that options.StatisticEventQueueLength is less than 0, and panic otherwise.
 	buffer := uint(options.StatisticEventQueueLength)
 
-	return &PodStatisticEventLoop{
+	return &podStatisticEventLoop{
 		options:      options,
 		EventLoop:    eventloop.NewBuffered[*state.PodStatistics](snapshot, buffer),
 		metricOutput: metricOutput,
 	}
 }
 
 // Start starts the event loop and begins watching the state of the event loop.
-// Start implements [eventloop.EventLoop.Start].
-func (el *PodStatisticEventLoop) Start() {
+// Start implements [safeconcurrencytypes.EventLoop.Start].
+func (el *podStatisticEventLoop) Start() {
 	el.EventLoop.Start()
 	// EventLoop.Start() will panic if the event loop is already started, so we can be sure to do this assignment only
 	// once.
 	el.watcherChan = eventloop.WatchState(context.TODO(), el.EventLoop, el.watcher)
 }
 
 // Close closes the event loop and waits for the watcher to finish.
-// Close implements [eventloop.EventLoop.Close].
-func (el *PodStatisticEventLoop) Close() {
+// Close implements [safeconcurrencytypes.EventLoop.Close].
+func (el *podStatisticEventLoop) Close() {
 	el.EventLoop.Close()
 	// Wait for the watcher to finish too.
 	<-el.watcherChan
 }
 
 // Send sends an event to the event loop and tracks the time it took to process the event.
-// Send implements [eventloop.EventLoop.Send].
-func (el *PodStatisticEventLoop) Send(
+// Send implements [safeconcurrencytypes.EventLoop.Send].
+func (el *podStatisticEventLoop) Send(
 	ctx context.Context,
 	event safeconcurrencytypes.Event[*state.PodStatistics],
 ) (safeconcurrencytypes.GenerationID, error) {
@@ -94,7 +97,8 @@ func (el *PodStatisticEventLoop) Send(
 }
 
 // PodUpdate sends an event to update the pod statistic for a pod based on the latest Kubernetes Pod.
-func (el *PodStatisticEventLoop) PodUpdate(
+// PodUpdate implements [types.PodStatisticEventLoop.PodUpdate].
+func (el *podStatisticEventLoop) PodUpdate(
 	ctx context.Context,
 	pod *corev1.Pod,
 ) (safeconcurrencytypes.GenerationID, error) {
@@ -108,7 +112,8 @@ func (el *PodStatisticEventLoop) PodUpdate(
 
 // PodDelete sends an event to stop tracking the pod statistic for a pod after it has been deleted from the Kubernetes
 // API.
-func (el *PodStatisticEventLoop) PodDelete(
+// PodDelete implements [types.PodStatisticEventLoop.PodDelete].
+func (el *podStatisticEventLoop) PodDelete(
 	ctx context.Context,
 	pod *corev1.Pod,
 ) (safeconcurrencytypes.GenerationID, error) {
@@ -120,7 +125,8 @@ func (el *PodStatisticEventLoop) PodDelete(
 }
 
 // PodResync sends an event to resync the event loop if the Kubernetes Watch API times out and events are lost.
-func (el *PodStatisticEventLoop) PodResync(
+// PodResync implements [types.PodStatisticEventLoop.PodResync].
+func (el *podStatisticEventLoop) PodResync(
 	ctx context.Context,
 	blacklistUIDs []apimachinerytypes.UID,
 ) (safeconcurrencytypes.GenerationID, error) {
@@ -131,7 +137,7 @@ func (el *PodStatisticEventLoop) PodResync(
 }
 
 // watcher watches the state of the event loop and updates the prometheus metrics.
-func (el *PodStatisticEventLoop) watcher(
+func (el *podStatisticEventLoop) watcher(
 	ctx context.Context,
 	s safeconcurrencytypes.StateSnapshot[*state.PodStatistics],
 ) bool {
@@ -140,9 +146,9 @@ func (el *PodStatisticEventLoop) watcher(
 	return true
 }
 
-// ImagePullStatisticEventLoop loops over image pull statistic events sent by collectors to track and update metrics for
+// imagePullStatisticEventLoop loops over image pull statistic events sent by collectors to track and update metrics for
 // image pulls.
-type ImagePullStatisticEventLoop struct {
+type imagePullStatisticEventLoop struct {
 	safeconcurrencytypes.EventLoop[*state.ImagePullStatistics]
 
 	options      *options.Options
@@ -151,7 +157,10 @@ type ImagePullStatisticEventLoop struct {
 }
 
 // NewImagePullStatisticEventLoop creates a new ImagePullStatisticEventLoop.
-func NewImagePullStatisticEventLoop(options *options.Options, metricOutput io.Writer) *ImagePullStatisticEventLoop {
+//
+// The returned *imagePullStatisticEventLoop implements
+// [github.com/BackMarket-oss/kube-transition-metrics/internal/statistics/types.ImagePullStatisticEventLoop].
+func NewImagePullStatisticEventLoop(options *options.Options, metricOutput io.Writer) *imagePullStatisticEventLoop {
 	s := state.NewImagePullStatistics()
 	snapshot := snapshot.NewCopyable[*state.ImagePullStatistics](s)
 
@@ -162,30 +171,33 @@ func NewImagePullStatisticEventLoop(options *options.Options, metricOutput io.Wr
 	//nolint:gosec // We already check that options.StatisticEventQueueLength is less than 0, and panic otherwise.
 	buffer := uint(options.StatisticEventQueueLength)
 
-	return &ImagePullStatisticEventLoop{
+	return &imagePullStatisticEventLoop{
 		EventLoop:    eventloop.NewBuffered[*state.ImagePullStatistics](snapshot, buffer),
 		options:      options,
 		metricOutput: metricOutput,
 	}
 }
 
 // Start starts the event loop and begins watching the state of the event loop.
-func (el *ImagePullStatisticEventLoop) Start() {
+// Start implements [safeconcurrencytypes.EventLoop.Start].
+func (el *imagePullStatisticEventLoop) Start() {
 	el.EventLoop.Start()
 	// EventLoop.Start() will panic if the event loop is already started, so we can be sure to do this assignment only
 	// once.
 	el.watcherChan = eventloop.WatchState(context.TODO(), el.EventLoop, el.watcher)
 }
 
 // Close closes the event loop and waits for the watcher to finish.
-func (el *ImagePullStatisticEventLoop) Close() {
+// Close implements [safeconcurrencytypes.EventLoop.Close].
+func (el *imagePullStatisticEventLoop) Close() {
 	el.EventLoop.Close()
 	// Wait for the watcher to finish too.
 	<-el.watcherChan
 }
 
 // Send sends an event to the event loop and tracks the time it took to process the event.
-func (el *ImagePullStatisticEventLoop) Send(
+// Send implements [safeconcurrencytypes.EventLoop.Send].
+func (el *imagePullStatisticEventLoop) Send(
 	ctx context.Context,
 	event safeconcurrencytypes.Event[*state.ImagePullStatistics],
 ) (safeconcurrencytypes.GenerationID, error) {
@@ -211,7 +223,8 @@ func (el *ImagePullStatisticEventLoop) Send(
 
 // ImagePullUpdate sends an event to update the image pull statistic for a pod from the latest Kubernetes Event for
 // image pulling related events.
-func (el *ImagePullStatisticEventLoop) ImagePullUpdate(
+// ImagePullUpdate implements [types.ImagePullStatisticEventLoop.ImagePullUpdate].
+func (el *imagePullStatisticEventLoop) ImagePullUpdate(
 	ctx context.Context,
 	pod *corev1.Pod,
 	k8sEvent *corev1.Event,
@@ -226,7 +239,8 @@ func (el *ImagePullStatisticEventLoop) ImagePullUpdate(
 
 // ImagePullDelete sends an event to delete the image pull statistic for a pod after the image pull is no longer being
 // tracked.
-func (el *ImagePullStatisticEventLoop) ImagePullDelete(
+// ImagePullDelete implements [types.ImagePullStatisticEventLoop.ImagePullDelete].
+func (el *imagePullStatisticEventLoop) ImagePullDelete(
 	ctx context.Context,
 	pod *corev1.Pod,
 ) (safeconcurrencytypes.GenerationID, error) {
@@ -238,7 +252,7 @@ func (el *ImagePullStatisticEventLoop) ImagePullDelete(
 }
 
 // watcher watches the state of the event loop and updates the prometheus metrics.
-func (el *ImagePullStatisticEventLoop) watcher(
+func (el *imagePullStatisticEventLoop) watcher(
 	ctx context.Context,
 	s safeconcurrencytypes.StateSnapshot[*state.ImagePullStatistics],
 ) bool {