fix(proto): preserve Parquet source and sink state

[buraksenn]

Which issue does this PR close?

• Closes Destructure proto hooks for the Parquet source and sink #24620.

Rationale for this change

Parquet source and sink protobuf hooks accessed fields individually and silently dropped source metadata prefetch hints and sink sorting-column metadata. This changed performance characteristics and omitted metadata from files written after a plan round trip.

What changes are included in this PR?

• Exhaustively destructure ParquetSource, ParquetSink, and their protobuf messages.
• Preserve ParquetSource::metadata_size_hint with a checked integer conversion.
• Preserve ParquetSink::sorting_columns, including the distinction between None and an empty list.
• Explicitly document source/sink fields that are reconstructed or runtime-only.
• Document the generated Rust API migration in the DataFusion 56.0.0 upgrade guide.

#24930 already preserves reverse_row_groups and sort_order_for_reorder; this PR builds on that behavior rather than duplicating it.

The protobuf wire changes are additive and backward compatible.

What is the testing strategy for this PR?

Physical-plan round-trip coverage verifies:

• Metadata-size hints preserve None, zero, a normal value, and usize::MAX.
• Parquet sorting columns preserve None, an empty list, and populated lists.
• Both fields survive binary protobuf and public JSON API round trips.

Both regression tests were ablation-checked and fail when their corresponding field is omitted from serialization.

Validated with:

• cargo test -p datafusion-proto --test proto_integration --features json (262 passed)
• cargo clippy -p datafusion-datasource-parquet -p datafusion-proto --all-features --tests -- -D warnings
• cargo fmt --all -- --check
• ./ci/scripts/doc_prettier_check.sh --write --allow-dirty

Are there any user-facing changes?

Parquet scan metadata prefetch hints and sink sorting-column metadata now survive protobuf plan round trips. The protobuf wire additions are backward compatible.

Adding metadata_size_hint to the generated public ParquetScanExecNode Rust struct and sorting_columns to ParquetSink is a source-level API change for callers using exhaustive struct literals. Such callers must initialize the new fields (use None to retain previous behavior) or use ..Default::default(). This migration is documented in the DataFusion 56.0.0 upgrade guide.

[github-actions]

Thank you for opening this pull request!

Reviewer note: cargo-semver-checks reported the current version number is not SemVer-compatible with the changes in this pull request (compared against the base branch).

Details

     Cloning apache/main
    Building datafusion-datasource-parquet v55.0.0 (current)
       Built [  51.179s] (current)
     Parsing datafusion-datasource-parquet v55.0.0 (current)
      Parsed [   0.038s] (current)
    Building datafusion-datasource-parquet v55.0.0 (baseline)
       Built [  51.900s] (baseline)
     Parsing datafusion-datasource-parquet v55.0.0 (baseline)
      Parsed [   0.038s] (baseline)
    Checking datafusion-datasource-parquet v55.0.0 -> v55.0.0 (no change; assume patch)
     Checked [   0.232s] 223 checks: 223 pass, 31 skip
     Summary no semver update required
    Finished [ 105.179s] datafusion-datasource-parquet
    Building datafusion-proto v55.0.0 (current)
       Built [  57.271s] (current)
     Parsing datafusion-proto v55.0.0 (current)
      Parsed [   0.020s] (current)
    Building datafusion-proto v55.0.0 (baseline)
       Built [  57.871s] (baseline)
     Parsing datafusion-proto v55.0.0 (baseline)
      Parsed [   0.021s] (baseline)
    Checking datafusion-proto v55.0.0 -> v55.0.0 (no change; assume patch)
     Checked [   0.155s] 223 checks: 223 pass, 31 skip
     Summary no semver update required
    Finished [ 116.749s] datafusion-proto
    Building datafusion-proto-models v55.0.0 (current)
       Built [  26.707s] (current)
     Parsing datafusion-proto-models v55.0.0 (current)
      Parsed [   0.141s] (current)
    Building datafusion-proto-models v55.0.0 (baseline)
       Built [  26.346s] (baseline)
     Parsing datafusion-proto-models v55.0.0 (baseline)
      Parsed [   0.141s] (baseline)
    Checking datafusion-proto-models v55.0.0 -> v55.0.0 (no change; assume patch)
     Checked [   2.303s] 223 checks: 222 pass, 1 fail, 0 warn, 31 skip

--- failure constructible_struct_adds_field: struct exhaustively constructible through public API adds field ---

Description:
A pub struct that could be exhaustively constructed with a literal using only public API has a new pub field, breaking existing exhaustive literals.
        ref: https://doc.rust-lang.org/reference/expressions/struct-expr.html
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.50.0/src/lints/constructible_struct_adds_field.ron

Failed in:
  field ParquetScanExecNode.metadata_size_hint in /home/runner/work/datafusion/datafusion/datafusion/proto-models/src/generated/prost.rs:2004
  field ParquetScanExecNode.metadata_size_hint in /home/runner/work/datafusion/datafusion/datafusion/proto-models/src/generated/prost.rs:2004
  field ParquetSink.sorting_columns in /home/runner/work/datafusion/datafusion/datafusion/proto-models/src/generated/prost.rs:1534
  field ParquetSink.sorting_columns in /home/runner/work/datafusion/datafusion/datafusion/proto-models/src/generated/prost.rs:1534

     Summary semver requires new major version: 1 major and 0 minor checks failed
    Finished [  57.024s] datafusion-proto-models

[codecov-commenter]

Codecov Report

❌ Patch coverage is 78.81356% with 50 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.06%. Comparing base (92746a9) to head (6756909).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
datafusion/proto-models/src/generated/pbjson.rs	74.34%	20 Missing and 19 partials ⚠️
datafusion/datasource-parquet/src/sink.rs	86.53%	2 Missing and 5 partials ⚠️
datafusion/datasource-parquet/src/source.rs	87.50%	0 Missing and 4 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #25057      +/-   ##
==========================================
+ Coverage   81.74%   82.06%   +0.32%     
==========================================
  Files        1128     1128              
  Lines      416645   416850     +205     
  Branches   416645   416850     +205     
==========================================
+ Hits       340580   342092    +1512     
+ Misses      55998    54328    -1670     
- Partials    20067    20430     +363     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.