Principle:Fede1024 Rust rdkafka Crate Public API Surface
| Knowledge Sources | |
|---|---|
| Domains | Crate_Architecture, API_Design, Documentation |
| Last Updated | 2026-02-07 19:00 GMT |
Overview
Principle of organizing a Rust crate's public API surface through deliberate module declarations, selective re-exports, and enforced documentation to provide a coherent and discoverable interface.
Description
A well-designed Rust crate root serves as both the entry point and the API contract. The Crate Public API Surface principle involves: (1) declaring public modules that group related functionality (producer, consumer, admin, etc.), (2) re-exporting the most commonly used types at the crate root for ergonomic imports, (3) enforcing #![forbid(missing_docs)] to guarantee all public items are documented, and (4) providing comprehensive crate-level documentation that covers features, usage patterns, client types, and configuration. The module hierarchy should mirror the mental model of the domain (Kafka has producers, consumers, configuration, messages, etc.).
Usage
Apply this principle when designing a Rust library crate. The crate root should be a curated facade: expose enough at the top level for common use cases (use rdkafka::ClientConfig) while keeping specialized types in their modules (use rdkafka::admin::NewTopic). The re-export set should be minimal and stable, as it forms the implicit API contract.
Theoretical Basis
Module Organization Pattern:
lib.rs (Crate Root)
├── Re-exports: ClientConfig, Message, Statistics, Offset, TopicPartitionList
├── pub mod admin — Cluster management
├── pub mod client — Core client abstraction
├── pub mod config — Configuration builder
├── pub mod consumer — Consumer types (Base, Stream)
├── pub mod error — Error types
├── pub mod groups — Consumer group metadata
├── pub mod message — Message types and traits
├── pub mod metadata — Cluster metadata wrappers
├── pub mod mocking — Mock cluster for testing
├── pub mod producer — Producer types (Base, Future, Threaded)
├── pub mod statistics — Statistics deserialization
├── pub mod topic_partition_list — Offset management
└── pub mod util — Runtime abstraction, utilities
Design Principles:
- Minimal re-exports: Only types needed in >50% of use cases
- Enforced docs: #![forbid(missing_docs)] catches undocumented additions
- Stable surface: Re-exports are the implicit semver contract
- Domain-aligned modules: Module names match Kafka concepts