The conformance client contract

Diagram

The CLI Verb Interface

The client is invoked using a specific command-line structure where the first argument determines the action performed. As defined in client.py:25-29, the mapping of verbs to actions is as follows:

The capabilities Declaration

Before testing logic, the harness calls the capabilities verb to understand what the client is capable of. According to Main.kt:43-46, the client must declare its roles (such as producer or consumer) and its name. The harness uses this to decide whether to skip certain checks, such as fetch for a producer-only client (client.py:39).

The produce and produce-keyed Mechanics

There is a critical distinction between standard production and keyed production:

• Standard produce: The caller specifies the partition directly. If ack=none is used, the client must return immediately without reading a response (Main.kt:124-126).
• produce-keyed: The client is responsible for selecting the partition. The client must first fetch metadata to discover available partitions and then use a partitioner to select one based on the key (Main.kt:154-158).

The fetch and truncated Edge Case

When fetching data, the client must handle cases where the response is incomplete. If a record is larger than the maxBytes requested, the broker may return a truncated response. In this scenario, the client must report the truncatedRecordBytes and the highWatermark (Main.kt:182-183). This prevents the caller from misinterpreting a partial record as the end of the log.

Exit Codes and Error Reporting

The contract distinguishes between protocol-level errors and client-level failures:

• Protocol Errors: If the broker refuses a request (e.g., UNKNOWN_TOPIC_OR_PARTITION), the client must report this via stdout using the format error=CODE and exit with code 0 (Main.kt:96).
• Client Failures: Any exception that is not a protocol error (such as a network failure or a crash) results in a non-zero exit code and a diagnostic message on stderr (Main.kt:85-86).

Key files

Behaviour that surprises

• Immediate Return on none: In the produce function, if the AckPolicy is NONE, the client must not attempt to read a response from the socket, as the broker will not send one (Main.kt:124-126).
• Metadata-Driven Partitioning: In produceKeyed, the client must not rely on a hardcoded partition count; it must fetch the actual partition list from the broker via sendMetadata to ensure the Partitioner.Fnv1a logic matches the broker's view (Main.kt:149-157).