Main execution lifecycle

Diagram

BooblikServer startup and transport selection

The server initialization begins by binding a ServerSocketChannel to the configured address and port BooblikServer.kt:134-140. Once bound, the server selects a transport mechanism based on the Transport enum BooblikServer.kt:25-34:

The acceptor loop and connection handling

The acceptor mechanism differs by transport. In SELECTOR mode, a coroutine runs a loop that calls serverChannel.accept() BooblikServer.kt:164-175, where transient exceptions are caught and logged to metrics to prevent the loop from dying. In VIRTUAL_THREADS mode, a platform thread runs the acceptor loop BooblikServer.kt:204-224. To ensure that a single failing client session does not crash the entire server, BooblikServer uses a SupervisorJob BooblikServer.kt:123, which isolates failures to the specific coroutine scope of that session.

Session lifecycle and FetchMode execution

A Session is established when a connection is accepted and configured BooblikServer.kt:182. The FetchMode determines how data is transferred from the log to the client BooblikServer.kt:37-43:

Graceful shutdown and the order of closure

The shutdown process is triggered by a JVM shutdown hook that ensures a specific sequence of closure to prevent data loss Main.kt:91-100. The order is strictly:

1. server.close() to stop accepting new connections.
2. background.cancel() to stop background tasks like retention.
3. broker.close() to ensure all writers finish flushing batches to disk before the underlying log is closed.

Smoke tests and distribution verification

The ci/smoke.sh script performs a full end-to-end verification of the distribution smoke.sh:30-34. It builds the installDist distribution, starts the broker, and uses a Python script to perform PRODUCE and FETCH operations over the wire. This verifies that the broker can recover its state from disk after a restart smoke.sh:130-142 and that the wire format (including CRC32C checksums) is correctly implemented.

Key files

Behaviour that surprising

• The BooblikServer uses a SupervisorJob BooblikServer.kt:123 specifically so that a client sending "nonsense" only kills its own session and not the entire server.
• The applyRetention function Main.kt:135 is the only place that decides when retention happens, as the Broker itself has no internal clock.
• The booblik.metrics.interval.millis setting Main.kt:118 allows disabling metrics by setting it to 0, which results in silent operation rather than an error.