472: feat!: Use bon builder style instead of several methods

[martin-augment]

472: To review by AI

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

---

Walkthrough

This pull request refactors the Reader and Schema construction APIs to use builder patterns enabled by the bon crate. The Reader::with_schema() and Reader::with_schemata() methods are replaced with Reader::builder(input).schema(schema).build() chains. Schema::array() and Schema::map() methods are updated to accept optional attributes and return builders that require .build() finalization. Attribute-specific constructors (array_with_attributes, map_with_attributes) are removed. Tests and examples across the codebase are updated consistently to use the new builder patterns.

✨ Finishing Touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch pr-472-2026-02-19-14-08-25

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Summary of Changes

Hello @martin-augment, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly refactors the API for creating Reader and Schema objects by introducing a builder pattern. This change enhances the clarity and flexibility of object construction, allowing for more ergonomic and extensible initialization, especially when dealing with optional parameters like schemas or attributes. The adoption of the bon crate simplifies the implementation of these builders, leading to a more consistent and modern Rust API design.

Highlights

• Refactored Reader API: The Reader struct now utilizes a builder pattern for its construction, replacing direct new, with_schema, and with_schemata methods with a more flexible Reader::builder(...).schema(...).build() approach.
• Refactored Schema API: The Schema::array and Schema::map methods have been updated to also use a builder pattern, requiring a .build() call to finalize schema creation and allowing for optional attributes to be set via the builder.
• Introduced bon crate: The bon crate has been integrated to facilitate the generation of builder patterns for Reader and Schema structs, streamlining their API design.
• Updated all usages and tests: All existing code, including benchmarks, examples, documentation, and various test cases, has been updated to reflect the new builder-style API for Reader and Schema.

Changelog

• avro/benches/serde.rs
  • Updated Reader instantiation to use the new builder pattern.
• avro/examples/benchmark.rs
  • Updated Reader instantiation to use the new builder pattern.
• avro/src/decode.rs
  • Updated Schema::array and Schema::map calls to include .build().
• avro/src/documentation/dynamic.rs
  • Updated example code to use the Reader builder pattern.
• avro/src/encode.rs
  • Updated Schema::array and Schema::map calls to include .build().
• avro/src/lib.rs
  • Updated Reader instantiation to use the new builder pattern in tests.
• avro/src/reader.rs
  • Imported the bon crate for builder pattern generation.
  • Updated Schema::map call to include .build().
  • Refactored Reader constructor methods (new, with_schema, with_schemata) into a single builder pattern using the #[bon] macro.
  • Updated test cases to use the new Reader builder pattern.
• avro/src/schema/mod.rs
  • Imported the bon crate for builder pattern generation.
  • Applied the #[bon] macro to the Schema implementation.
  • Refactored Schema::map and Schema::array methods to use a builder pattern, replacing _with_attributes variants.
  • Updated test cases to use the new Schema::array(...).build() and Schema::map(...).build() syntax.
• avro/src/schema_compatibility.rs
  • Updated example code to use Schema::array(...).build().
• avro/src/schema_equality.rs
  • Updated test cases to use Schema::map(...).build() and Schema::array(...).build().
• avro/src/serde/derive.rs
  • Updated Schema::array and Schema::map calls to include .build().
• avro/src/serde/ser_schema.rs
  • Updated Reader instantiation to use the new builder pattern.
• avro/src/types.rs
  • Updated Schema::array calls to include .build().
• avro/src/writer.rs
  • Updated Schema::map call to include .build().
  • Updated Reader instantiation in tests to use the new builder pattern.
• avro/tests/schema.rs
  • Updated Reader instantiation to use the new builder pattern.
• avro/tests/shared.rs
  • Updated Reader instantiation to use the new builder pattern.
• avro/tests/to_from_avro_datum_schemata.rs
  • Updated Reader instantiation to use the new builder pattern.
• avro/tests/union_schema.rs
  • Updated Reader instantiation to use the new builder pattern.
• avro_derive/tests/derive.rs
  • Updated Reader instantiation to use the new builder pattern.
• avro_derive/tests/serde.rs
  • Updated Reader instantiation to use the new builder pattern.

Activity

• The pull request was created by martin-augment with the title '472: feat!: Use bon builder style instead of several methods'.
• The author requested review by AI, indicating that no human review has occurred yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request is a significant and well-executed refactoring that introduces the builder pattern for creating Reader and Schema objects, using the bon crate. This change improves the API by making object instantiation more explicit and flexible, especially for objects with multiple optional parameters. The updates have been applied consistently across the entire codebase, including documentation, examples, and tests. I have one minor suggestion to further improve code conciseness.

[gemini-code-assist]

This logic for determining the schemata can be expressed more concisely using unwrap_or_else and map, which is more idiomatic in Rust.

        let schemata = schemata.unwrap_or_else(|| schema.map(|s| vec![s]).unwrap_or_default());

[martin-augment]

value:good-to-have; category:bug; feedback: The Gemini AI reviewer is correct! The logic for determining the schemata could be simplified to a one-liner. This will make it easier to understand and to maintain.

[claude]

Code Review

This PR introduces the bon builder pattern to consolidate overlapping constructor APIs for Schema::array, Schema::map, and Reader. The intent is sound — reducing the proliferation of _with_attributes/_with_schema/_with_schemata variants. Here are my observations:

---

Issues

1. Semantic bug risk: schema ignored in schemata resolution when both are provided

In reader.rs, the new builder logic is:

let schemata = match schemata {
    Some(schemata) => schemata,   // schema is NOT included here
    None => match schema {
        Some(schema) => vec![schema],
        None => vec![],
    },
};

When a caller provides both .schema(s).schemata(v), the schema is used as reader_schema for value resolution but is not included in schemata passed to Block::new(). This matches the old with_schemata() behavior (which also omitted the primary schema from the schemata list), but by combining both options into one unified builder, users can now accidentally write:

Reader::builder(reader).schema(my_schema).schemata(my_external_schemas).build()

...and have my_schema absent from the schema resolution registry. The old separate methods made this impossible. This should be clearly documented on the builder function, or the implementation should merge schema into schemata when both are provided (with deduplication).

2. Reader::new() lost its doc comment

The doc comment that was on new() was removed but not re-added. The doc comment currently sits between new() and builder() with no blank line:

pub fn new(reader: R) -> AvroResult<Reader<'a, R>> {
    Reader::builder(reader).build()
}
/// Creates a `Reader` given something implementing the `io::Read` trait to read from.

This makes the comment appear to document builder(), not new(). The new() method needs its own doc comment restored.

3. Ergonomic regression for Schema::array / Schema::map

The simple case went from:

Schema::array(Schema::Int)

to:

Schema::array(Schema::Int).build()

This .build() call is required in every single usage — over 30 call sites updated in this PR alone. For a method that previously returned Schema directly, this is a meaningful ergonomic cost. The _with_attributes variant was rare, but array() and map() are used constantly in internal code and user code.

One alternative worth considering: keep Schema::array(items) returning Schema directly, and add a separate Schema::array_builder(items) (or similar) that returns the bon builder. That way the simple 90% case stays simple.

4. Uncovered new capability: schemata-only path on Reader

The new builder allows .schemata(v) without .schema(...), which was not possible before (previously you needed with_schemata which required a primary schema). This new code path has no test coverage. Is it intentional to support a reader with schemata but no primary reader schema? If so, a test should verify the behavior.

5. New bon proc-macro dependency

bon 3.9.0 is a new compile-time proc-macro dependency. For a library crate, this adds to downstream users' compile times and dependency surface. The tradeoff should be weighed: the previous approach had no additional dependencies but required separate methods.

---

Minor / Style

• Schema::map is missing its #[builder(finish_fn = build)] attribute in the diff (the map section at line ~319 shows pub fn map( without the attribute, while array has it). Please double-check that the map builder is correctly configured.
• #[bon] on the entire impl<'a, R: Read> Reader<'a, R> block subjects all methods (including simple accessors like writer_schema(), reader_schema(), user_metadata()) to bon's macro processing, even though only builder() uses it. Consider splitting the impl block or using a more targeted annotation.
• The doc comment on builder() says "Creates a Reader given something implementing..." — this is accurate for the builder call but reads oddly since builder() returns a builder, not a Reader. Clarifying the doc to say it "begins construction of a Reader..." would be more accurate.

---

What works well

• Consolidating three Reader constructors into one is a clear improvement.
• The breaking change is correctly flagged with ! in the commit message and PR title.
• The test coverage is comprehensive for the updated call sites.
• The implementation correctly preserves the should_resolve_schema flag logic.

[augmentcode]

🤖 Augment PR Summary

Summary: This PR updates the public API to use bon-generated builder patterns for constructing Readers and common Schemas.

Changes:

• Replaces Reader::with_schema / Reader::with_schemata call sites with Reader::builder(...).schema(...).schemata(...).build().
• Refactors Reader construction internals to centralize initialization logic in the new builder.
• Updates internal header parsing to use the new Schema::map(...).build() form when decoding file metadata.
• Converts Schema::array and Schema::map to builder-style constructors with optional attributes, removing the need for separate *_with_attributes helpers.
• Adjusts docs, examples, benches, unit tests, and derive-related tests to the new construction API.

Technical Notes: The new APIs allow optional reader schema and optional “schemata” inputs for resolving schema references, while making schema attributes configuration explicit via builder chaining.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. No suggestions at this time.

Comment augment review to trigger a new review at any time.

[martin-augment]

1. Semantic bug risk: schema ignored in schemata resolution when both are provided

In reader.rs, the new builder logic is:

let schemata = match schemata {
    Some(schemata) => schemata,   // schema is NOT included here
    None => match schema {
        Some(schema) => vec![schema],
        None => vec![],
    },
};

When a caller provides both .schema(s).schemata(v), the schema is used as reader_schema for value resolution but is not included in schemata passed to Block::new(). This matches the old with_schemata() behavior (which also omitted the primary schema from the schemata list), but by combining both options into one unified builder, users can now accidentally write:

Reader::builder(reader).schema(my_schema).schemata(my_external_schemas).build()

...and have my_schema absent from the schema resolution registry. The old separate methods made this impossible. This should be clearly documented on the builder function, or the implementation should merge schema into schemata when both are provided (with deduplication).

value:valid-but-wont-fix; category:bug; feedback: The Claude AI reviewer is correct! The new builder API indeed allows to construct a Reader without a reader schema in contrast to the old API. The schemata registry is needed only to resolve references in the reader schema, so it does not make much sense to set the schemata without a reader schema, but it also does not do any harm. Setting only the reader schema without schemata is totally OK

[martin-augment]

2. Reader::new() lost its doc comment

The doc comment that was on new() was removed but not re-added. The doc comment currently sits between new() and builder() with no blank line:

pub fn new(reader: R) -> AvroResult<Reader<'a, R>> {
    Reader::builder(reader).build()
}
/// Creates a `Reader` given something implementing the `io::Read` trait to read from.

This makes the comment appear to document builder(), not new(). The new() method needs its own doc comment restored.

value:good-to-have; category:documentation; feedback: The Claude AI reviewer is correct! The new() constructor was preserved to allow more ergonomic API for the simpler case when only a std::io::Read implementation is provided without a reader schema. The docstring should be restored!

[martin-augment]

3. Ergonomic regression for Schema::array / Schema::map

The simple case went from:

Schema::array(Schema::Int)

to:

Schema::array(Schema::Int).build()

This .build() call is required in every single usage — over 30 call sites updated in this PR alone. For a method that previously returned Schema directly, this is a meaningful ergonomic cost. The _with_attributes variant was rare, but array() and map() are used constantly in internal code and user code.

One alternative worth considering: keep Schema::array(items) returning Schema directly, and add a separate Schema::array_builder(items) (or similar) that returns the bon builder. That way the simple 90% case stays simple.

value:good-but-wont-fix; category:bug; feedback: The Claude AI reviewer is correct! The old API was shorter in the minimal case where only the Schema is provided but longer when the custom attributes and the default field were also provided. The new builder style API also allows adding more fields in the future without API breaks.

[martin-augment]

4. Uncovered new capability: schemata-only path on Reader

The new builder allows .schemata(v) without .schema(...), which was not possible before (previously you needed with_schemata which required a primary schema). This new code path has no test coverage. Is it intentional to support a reader with schemata but no primary reader schema? If so, a test should verify the behavior.

value:valid-but-wont-fix; category:bug; feedback: The Claude AI reviewer is correct! The new builder API indeed allows to construct a Reader without a reader schema in contrast to the old API. The schemata registry is needed only to resolve references in the reader schema, so it does not make much sense to set the schemata without a reader schema, but it also does not do any harm. Setting only the reader schema without schemata is totally OK

[martin-augment]

5. New bon proc-macro dependency

bon 3.9.0 is a new compile-time proc-macro dependency. For a library crate, this adds to downstream users' compile times and dependency surface. The tradeoff should be weighed: the previous approach had no additional dependencies but required separate methods.

value:annoying; category:bug; feedback: The Claude AI reviewer is not correct! The "bon" dependency was there already and it was used in few other places.