The conformance executable

The conformance executable is a specialized Kotlin/Native binary designed to validate the Booblik protocol implementation by acting as a driver for specific verbs. Unlike standard clients, it is a fixture used by the conformance harness to ensure the broker adheres to the wire specification, specifically targeting edge cases in decoding and error reporting.

Diagram

The conformance and probe binaries

The module is structured to produce two distinct executables to keep the library surface clean. As noted in build.gradle.kts:8-11, a Kotlin/Native binary is linked from the target's own compilation; placing an entry point in the library would pollute the published klib and its ABI dump. Consequently, the module defines two separate binaries: the standard conformance client and a probe binary used for measurement (build.gradle.kts:26-31).

The main entry point and command verbs

The lifecycle of a conformance run begins with a capabilities check, where the executable responds with its roles and name (Main.kt:33-36). If not checking capabilities, it retrieves the broker address from the BOOBLIK_BROKER environment variable (Main.kt:40-44) and dispatches one of the following verbs:

The fetch decoding and truncated tail edge cases

The fetch implementation specifically tests the client's ability to handle partial data. It validates the truncated flag and truncatedRecordBytes when a record is larger than the maxBytes requested (Main.kt:156-158). This ensures the reader can distinguish between a state where they have caught up to the high watermark and a state where a record is simply too large to be fully read in one request.

The produce-keyed partitioner exercise

Because the broker does not see the key in the wire protocol, the client must perform the partitioning logic itself to ensure the data lands in the correct location. The produceKeyed verb uses topic.partitionFor(key) to determine the destination partition before calling the produce command (Main.kt:128-130).

The report error mechanism

The executable distinguishes between a client-side failure and a broker-side refusal. A successful operation requires ErrorCode.NONE (Main.kt:77). If the broker returns an error, it is reported via error=CODE on stdout, but the process still exits with code 0 because the refusal is a valid protocol result (Main.kt:19-20). A non-zero exit code is reserved for actual program failures.

The hex payload encoding

To allow for raw data transmission via command line arguments, the client provides a helper to transform hex-encoded strings into ByteArray objects (Main.kt:170-171).

Key files

Behaviour that surprises

• The main function uses exitProcess(2) for usage errors or missing environment variables, but returns a successful exit code even when the broker returns an ErrorCode (booblik-native-conformance/src/nativeMain/kotlin/ru/workinprogress/booblik/native/conformance/Main.kt:30, 67).
• The produceKeyed function performs the partitioning logic locally using topic.partitionFor because the broker is unaware of the key used for partitioning (Main.kt:128).