Conformance Verbs

Diagram

The capabilities verb

The initial handshake where the client declares its roles and name. The harness uses this to determine which verbs the client is allowed to execute, as seen in client.py:100-108. The client must respond with roles (a comma-separated list) and a name identifier, as implemented in Program.cs:21-22.

The metadata verb

Retrieving partition information including log start offsets and high watermarks. The client requests metadata for a specific topic and iterates through the returned partition information to print the partition ID, the log start offset, and the high watermark, as demonstrated in Program.cs:105-108.

The produce verb and AckPolicy

Mechanics of record submission, the behavior of AckPolicy.None (returning immediately), and the handling of zero-length records. The ack parameter maps to specific policies:

The harness specifically checks that produce with none does not wait for a response, as an empty field is treated as a zero-length record which the broker may refuse (Program.cs:127-128).

The produce-keyed verb and partitioner logic

How the client-side partitioner selects a partition based on a key before the broker sees it, and validation against golden vectors. In this mode, the client performs the partitioning logic locally using the key, as seen in Program.cs:152. The correctness of this logic is validated by comparing the client's choice against "golden vectors" in partition_test.go:18-36.

The fetch verb and record truncation

Edge cases in fetching: handling truncated records when maxBytes is exceeded and empty responses at the high watermark. The client must handle cases where a record is larger than the requested maxBytes, resulting in a truncated response where answer.Truncated is true (Program.cs:85-87). It also handles empty responses when the fetch offset is at the high watermark (Program.cs:85).

Broker refusal as a result

The distinction between program failure and a valid broker refusal (e.g., error=CODE), and how exit codes are used to signal success. A broker refusal is considered a valid result of a command, not a failure of the client program; in such cases, the client prints error=CODE and exits with code 0 (Program.cs:61-65). A non-zero exit code is reserved for actual program failures, such as unknown verbs or missing environment variables (Program.cs:57-58).

Key files

Behaviour that surprises

• Immediate Return: When using AckPolicy.None, the client must not wait for a response from the broker; doing so causes a timeout in the harness (Program.cs:133).
• Refusal vs. Failure: A BrokerException is not a program error; the client must exit with 0 if the broker refuses a request, reporting the error via stdout instead (Program.cs:63-64).
• Client-Side Partitioning: In produce-keyed, the partition is chosen by the client using the key, meaning the broker never sees the key itself (Program.cs:141-142).