[Parquet] Add ParquetMetadataPushDecoder (#8080)

# Which issue does this PR close?

- Part of #8000
- Closes #8164

# Rationale for this change

Metadata is needed when implementing a push decoder for Parquet:
- #7983

If we want to truly separate IO and CPU we also need a way to decode the
metadata without explicit IO, and hence this PR that provides a way to
decode metadata "push style" where it tells you what bytes are needed.
It follows the same API as the parquet push decoder

This PR also introduces some of the common infrastructure needed in the
parquet push decoder

# What changes are included in this PR?

1. Add `PushBuffers` to hold byte ranges
2. Add `DecodeResult` to communicate back to the caller 
3. Add `ParquetMetaDataPushDecoder` for decoding metadata


# Are these changes tested?

Yes, there are several fully working doc tests that show how to use this
API

# Are there any user-facing changes?

There is a new API

---------

Co-authored-by: Ed Seidl <[email protected]>
Co-authored-by: albertlockett <[email protected]>

Author: 3 people

parquet/src/errors.rs

@@ -52,6 +52,9 @@ pub enum ParquetError {
     /// Returned when a function needs more data to complete properly. The `usize` field indicates
     /// the total number of bytes required, not the number of additional bytes.
     NeedMoreData(usize),
+    /// Returned when a function needs more data to complete properly.
+    /// The `Range<u64>` indicates the range of bytes that are needed.
+    NeedMoreDataRange(std::ops::Range<u64>),
 }
 
 impl std::fmt::Display for ParquetError {
@@ -69,6 +72,9 @@ impl std::fmt::Display for ParquetError {
             }
             ParquetError::External(e) => write!(fmt, "External: {e}"),
             ParquetError::NeedMoreData(needed) => write!(fmt, "NeedMoreData: {needed}"),
+            ParquetError::NeedMoreDataRange(range) => {
+                write!(fmt, "NeedMoreDataRange: {}..{}", range.start, range.end)
+            }
         }
     }
 }

parquet/src/file/metadata/mod.rs

@@ -40,11 +40,10 @@
 //! metadata into parquet files. To work with metadata directly,
 //! the following APIs are available:
 //!
-//! * [`ParquetMetaDataReader`] for reading
+//! * [`ParquetMetaDataReader`] for reading from a reader for I/O
+//! * [`ParquetMetaDataPushDecoder`] for decoding from bytes without I/O
 //! * [`ParquetMetaDataWriter`] for writing.
 //!
-//! [`ParquetMetaDataReader`]: https://docs.rs/parquet/latest/parquet/file/metadata/struct.ParquetMetaDataReader.html
-//! [`ParquetMetaDataWriter`]: https://docs.rs/parquet/latest/parquet/file/metadata/struct.ParquetMetaDataWriter.html
 //!
 //! # Examples
 //!
@@ -92,6 +91,7 @@
 //!                         * Same name, different struct
 //! ```
 mod memory;
+mod push_decoder;
 pub(crate) mod reader;
 mod writer;
 
@@ -120,6 +120,7 @@ use crate::schema::types::{
 };
 #[cfg(feature = "encryption")]
 use crate::thrift::{TCompactSliceInputProtocol, TSerializable};
+pub use push_decoder::ParquetMetaDataPushDecoder;
 pub use reader::{FooterTail, PageIndexPolicy, ParquetMetaDataReader};
 use std::ops::Range;
 use std::sync::Arc;