booblik-app

What this module is responsible for

The booblik-app module serves as the entry point for the Booblik broker. It manages the application lifecycle, from parsing configuration and initializing core components like the Broker and BooblikServer to managing background tasks for metrics and retention. It also provides a specialized health check utility to verify the broker's responsiveness.

Diagram

BooblikConfig

Configuration is handled by the BooblikConfig data class, which ensures that the broker only boots if all parameters are valid. The loading logic follows a strict precedence: environment variables override properties files, which in turn override default values (BooblikConfig.kt:77-91).

The configuration parameters are parsed as follows:

Validation is performed during initialization to prevent runtime failures (BooblikConfig.kt:49-55).

More: BooblikConfig

Main execution lifecycle

The startup sequence begins in Main.kt, where the configuration is loaded and the Broker and BooblikServer are initialized (Main.kt:34-73). Once the server starts listening, the main thread enters a waiting state using a CountDownLatch (Main.kt:90-103).

A shutdown hook is registered to ensure a graceful exit: it closes the server first, then cancels background coroutines, and finally closes the broker to ensure all data batches reach the disk (Main.kt:92-98).

More: Main execution lifecycle

Metrics reporting and retention

The application launches two primary background coroutines using a SupervisorJob to manage long-running tasks (Main.kt:84-86).

• Metrics Reporting: The reportMetrics function calculates rates by comparing snapshots of the Metrics object over a specified interval (Main.kt:113-125).
• Retention Policy: The applyRetention function periodically triggers the broker to remove segments based on configured time or size limits (Main.kt:135-144).

More: Metrics reporting and retention

Health check mechanism

The Health object provides a standalone utility to verify that the broker is not just accepting TCP connections, but is actually capable of processing requests (Health.kt:20-21). It performs a METADATA request via a BooblikClient.

To prevent the health check from hanging if the broker is unresponsive, the check uses a worker thread with a join timeout (Health.kt:66-73). A successful check requires a MetadataResult with an ErrorCode.NONE (Health.kt:81-84).

Build and distribution

The module is configured via build.gradle.kts as a Kotlin JVM application (build.gradle.kts:1-11). It uses the application plugin to define the main entry point and customizes the distribution to include a specific health check script (build.gradle.kts:29-46).

The application's runtime behavior is influenced by JVM arguments, which are explicitly printed at startup to ensure the running profile matches the intended one (Main.kt:44-45).

Key files

Behaviour that surprise

• BooblikConfig.load will throw an exception if a configuration file is explicitly provided but cannot be found, rather than silently using defaults (BooblikConfig.kt:82-86).
• The Health check uses a separate thread to bound the request time, because a blocking read on a SocketChannel does not respond to SO_TIMEOUT (Health.kt:47-49).
• Main.kt uses a CountDownLatch to keep the main thread alive, ensuring the process doesn't exit until the shutdown hook completes (Main.kt:90-103).