dev/relay
Generated page
Model gemma-mtp, commit f508a4b65b3f, 2026-08-15, sources: 3. Edit the code or the hand-written documentation instead.
Diagram
Directional modes
The relay operates in one of two modes defined in Main.kt:83-86:
| Mode | Description | Position Ownership |
|---|---|---|
KAFKA_TO_BOOBLIK | Moves data from Kafka to booblik | Managed by Kafka via Consumer Groups (Directions.kt:46) |
BOOBLIK_TO_KAFKA | Moves data from booblik to Kafka | Managed locally via FileOffsetStore (Directions.kt:93) |
More: Directional modes
booblikToKafka
This mode consumes data from booblik and produces it to Kafka. Because the booblik broker does not remember reader positions, the relay uses a FileOffsetStore to manage state locally on the relay's volume (Directions.kt:93). To ensure at-least-once delivery, the producer is configured with acks=all (Directions.kt:102).
More: booblikToKafka
At-least-once delivery guarantees
The relay implements at-least-once delivery by ensuring the position is only updated after the destination has acknowledged the data. In kafkaToBooblik, consumer.commitSync() is called only after all records in a batch are sent to booblik (Directions.kt:71). In booblikToKafka, the checkpointing mechanism saves the position only after the kafka.flush() operation is complete (Directions.kt:119).
RelayStats
The monitoring surface is exposed via an HTTP server and provides real-time metrics through the Stats class (Main.kt:88). The RelayStats data class (Main.kt:129) includes:
relayed: Total count of relayed records.batches: Total number of batches processed.position: The last observed offset/position.restarts: Number of times the relay loop has restarted due to failures.lastFailure: The message of the last encountered exception.lastRecord: A 120-character sample of the last record.
RelayConfig
The relay is configured via environment variables as defined in Main.kt:142-176. The following parameters are available:
| Parameter | Environment Variable | Default Value |
|---|---|---|
name | RELAY_NAME | relay |
direction | RELAY_DIRECTION | KAFKA_TO_BOOBLIK |
brokerHost | BOOBLIK_HOST | 127.0.0.1 |
brokerPort | BOOBLIK_PORT | 9092 |
booblikTopic | BOOBLIK_TOPIC | mirrored |
kafkaBootstrap | KAFKA_BOOTSTRAP | kafka:9092 |
kafkaTopic | KAFKA_TOPIC | orders |
kafkaGroup | KAFKA_GROUP | booblik-relay |
stateDir | STATE_DIR | /var/lib/relay |
httpPort | HTTP_PORT | 8080 |
Key files
| File | Lines | What is there |
|---|---|---|
…/relay/build.gradle.kts | 1-9 | Dependencies for Kafka, Ktor, and Booblik client. |
…/relay/Directions.kt | 38-77 | Implementation of the kafkaToBooblik function. |
…/relay/Directions.kt | 89-124 | Implementation of the booblikToKafka function. |
…/relay/Main.kt | 47-81 | The main entry point and the execution loop. |
…/relay/Main.kt | 88-127 | The Stats class for tracking relay metrics. |
…/relay/Main.kt | 142-176 | The RelayConfig data class and environment loading logic. |
Behaviour that surprise
- The
kafkaToBooblikfunction usesconsumer.commitSync()(Directions.kt:71) to ensure that a crash between sending data and committing the offset results in a repeated batch rather than data loss. - The
booblikToKafkafunction requires an explicitkafka.flush()(Directions.kt:119) before thecheckpointingmechanism updates the localFileOffsetStoreto maintain delivery guarantees. - The
mainfunction (Main.kt:47) uses awhile(true)loop with atry-catchblock to ensure that the relay automatically restarts if a connection to either Kafka or booblik is lost.