kafrust-protocol 0.2.27

Kafka wire protocol primitives for kafrust.
Documentation

kafrust-protocol

Crates.io Docs.rs CI

Kafka wire protocol primitives for kafrust.

kafrust-protocol is the runtime-free protocol crate used by the high-level kafrust client. It owns Kafka request and response encoding, response decoding, request/response headers, frame handling, and focused wire-format tests.

This crate is not a Kafka client by itself. Applications should normally depend on kafrust; this crate is public so protocol behavior can be inspected, tested, and reused where low-level Kafka messages are needed.

Design Goals

  • Keep Kafka API/version details explicit in type names.
  • Keep wire-format code small and easy to audit.
  • Avoid async runtime assumptions.
  • Avoid unsafe.
  • Add Kafka protocol surface only when encoding, decoding, and client behavior need it.

Implemented Areas

The 0.2.x protocol surface includes support used by the current high-level client paths:

  • primitive Kafka wire types
  • nullable and compact strings/bytes/arrays
  • tagged fields
  • request and response headers
  • frame encoding and decoding
  • ApiVersions v0
  • Metadata v1
  • Metadata v12 with topic UUIDs (KIP-848 assignment support)
  • CreateTopics v2
  • DeleteTopics v3
  • DescribeConfigs v1
  • DescribeGroups v1
  • ListGroups v1
  • DeleteGroups v1
  • IncrementalAlterConfigs v0
  • FindCoordinator v1
  • Produce v2 MessageSet and Produce v3 RecordBatch paths
  • Fetch v2, Fetch v4, and non-flexible Fetch v11 request/response decoding for MessageSet and RecordBatch records, including rack IDs and preferred read replicas in v11
  • JoinGroup v2 and JoinGroup v5
  • SyncGroup v2 and SyncGroup v3
  • Heartbeat v2 and Heartbeat v3
  • ConsumerGroupHeartbeat v0 (KIP-848 flexible protocol foundation)
  • LeaveGroup v3
  • OffsetFetch v2
  • OffsetCommit v2 and OffsetCommit v7
  • SaslHandshake v1
  • SaslAuthenticate v0
  • InitProducerId v0, AddPartitionsToTxn v0, AddOffsetsToTxn v0, TxnOffsetCommit v0, and EndTxn v0
  • classic consumer protocol subscription and assignment payloads

Encoding Example

use kafrust_protocol::api::api_versions::ApiVersionsRequestV0;

let request = ApiVersionsRequestV0 {
    correlation_id: 42,
    client_id: Some("kafrust".to_owned()),
};
let bytes = request.encode()?;

assert!(!bytes.is_empty());
# Ok::<(), kafrust_protocol::Error>(())

Decoding Example

use kafrust_protocol::api::api_versions::ApiVersionsResponseV0;
use kafrust_protocol::codec::Decoder;

let response_body = [
    0, 0,       // error_code
    0, 0, 0, 1, // api_keys length
    0, 18,      // ApiVersions api key
    0, 0,       // min version
    0, 4,       // max version
];

let mut decoder = Decoder::new(&response_body);
let response = ApiVersionsResponseV0::decode_body(&mut decoder)?;

assert_eq!(response.error_code, 0);
assert_eq!(response.api_keys.len(), 1);
# Ok::<(), kafrust_protocol::Error>(())

Compatibility

Protocol types can exist before a high-level client path is verified against a real broker. kafrust compatibility claims are made from the high-level client crate and repository docs, not from the presence of protocol structs alone.

The current 0.2.x client compatibility claim is Apache Kafka 3.7.2, 3.8.1, 3.9.1, and 4.3.1 single-node KRaft over PLAINTEXT, with the secured and three-broker client profiles verified against Kafka 3.7.2.

Current Limits

  • This crate does not implement a broker.
  • This crate does not perform network I/O.
  • Protocol coverage is intentionally incomplete.
  • SASL protocol structs do not perform authentication by themselves.
  • This crate provides wire-format primitives, not the high-level routing, retry, coordinator, or lifecycle behavior documented by kafrust.
  • Compression codecs, transaction and idempotent-producer protocol paths, and implemented admin API schemas still require high-level client verification before they support a new compatibility claim.
  • Public APIs are pre-1.0 and can change between minor versions.

Project Docs