Skip to main content

arrow_avro/
codec.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for additional information regarding copyright ownership
3// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements
4
5//! Codec for Mapping Avro and Arrow types.
6
7use crate::schema::{
8    AVRO_ENUM_SYMBOLS_METADATA_KEY, AVRO_FIELD_DEFAULT_METADATA_KEY, AVRO_NAME_METADATA_KEY,
9    AVRO_NAMESPACE_METADATA_KEY, Array, Attributes, ComplexType, Enum, Fixed, Map, Nullability,
10    PrimitiveType, Record, Schema, Type, TypeName, make_full_name,
11};
12use arrow_schema::{
13    ArrowError, DECIMAL128_MAX_PRECISION, DECIMAL256_MAX_PRECISION, DataType, Field, Fields,
14    IntervalUnit, TimeUnit, UnionFields, UnionMode,
15};
16#[cfg(feature = "small_decimals")]
17use arrow_schema::{DECIMAL32_MAX_PRECISION, DECIMAL64_MAX_PRECISION};
18use indexmap::IndexMap;
19use serde_json::Value;
20use std::collections::hash_map::Entry;
21use std::collections::{HashMap, HashSet};
22use std::fmt;
23use std::fmt::Display;
24use std::sync::Arc;
25use strum_macros::AsRefStr;
26
27/// Contains information about how to resolve differences between a writer's and a reader's schema.
28#[derive(Debug, Clone, PartialEq)]
29pub(crate) enum ResolutionInfo {
30    /// Indicates that the writer's type should be promoted to the reader's type.
31    Promotion(Promotion),
32    /// Indicates that a default value should be used for a field.
33    DefaultValue(AvroLiteral),
34    /// Provides mapping information for resolving enums.
35    EnumMapping(EnumMapping),
36    /// Provides resolution information for record fields.
37    Record(ResolvedRecord),
38    /// Provides mapping and shape info for resolving unions.
39    Union(ResolvedUnion),
40}
41
42/// Represents a literal Avro value.
43///
44/// This is used to represent default values in an Avro schema.
45#[derive(Debug, Clone, PartialEq)]
46pub(crate) enum AvroLiteral {
47    /// Represents a null value.
48    Null,
49    /// Represents a boolean value.
50    Boolean(bool),
51    /// Represents an integer value.
52    Int(i32),
53    /// Represents a long value.
54    Long(i64),
55    /// Represents a float value.
56    Float(f32),
57    /// Represents a double value.
58    Double(f64),
59    /// Represents a bytes value.
60    Bytes(Vec<u8>),
61    /// Represents a string value.
62    String(String),
63    /// Represents an enum symbol.
64    Enum(String),
65    /// Represents a JSON array default for an Avro array, containing element literals.
66    Array(Vec<AvroLiteral>),
67    /// Represents a JSON object default for an Avro map/struct, mapping string keys to value literals.
68    Map(IndexMap<String, AvroLiteral>),
69}
70
71/// Contains the necessary information to resolve a writer's record against a reader's record schema.
72#[derive(Debug, Clone, PartialEq)]
73pub(crate) struct ResolvedRecord {
74    /// Maps a writer's field index to the field's resolution against the reader's schema.
75    pub(crate) writer_fields: Arc<[ResolvedField]>,
76    /// A list of indices in the reader's schema for fields that have a default value.
77    pub(crate) default_fields: Arc<[usize]>,
78}
79
80/// Resolution information for record fields in the writer schema.
81#[derive(Debug, Clone, PartialEq)]
82pub(crate) enum ResolvedField {
83    /// Resolves to a field indexed in the reader schema.
84    /// The `AvroDataType` is the writer's type for this field, used by the Skipper
85    /// to correctly consume writer bytes when the whole record is being skipped.
86    ToReader(usize, AvroDataType),
87    /// For fields present in the writer's schema but not the reader's, this stores their data type.
88    /// This is needed to correctly skip over these fields during deserialization.
89    Skip(AvroDataType),
90}
91
92/// Defines the type of promotion to be applied during schema resolution.
93///
94/// Schema resolution may require promoting a writer's data type to a reader's data type.
95/// For example, an `int` can be promoted to a `long`, `float`, or `double`.
96#[derive(Debug, Clone, Copy, PartialEq, Eq)]
97pub(crate) enum Promotion {
98    /// Direct read with no data type promotion.
99    Direct,
100    /// Promotes an `int` to a `long`.
101    IntToLong,
102    /// Promotes an `int` to a `float`.
103    IntToFloat,
104    /// Promotes an `int` to a `double`.
105    IntToDouble,
106    /// Promotes a `long` to a `float`.
107    LongToFloat,
108    /// Promotes a `long` to a `double`.
109    LongToDouble,
110    /// Promotes a `float` to a `double`.
111    FloatToDouble,
112    /// Promotes a `string` to `bytes`.
113    StringToBytes,
114    /// Promotes `bytes` to a `string`.
115    BytesToString,
116}
117
118impl Display for Promotion {
119    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
120        match self {
121            Self::Direct => write!(formatter, "Direct"),
122            Self::IntToLong => write!(formatter, "Int->Long"),
123            Self::IntToFloat => write!(formatter, "Int->Float"),
124            Self::IntToDouble => write!(formatter, "Int->Double"),
125            Self::LongToFloat => write!(formatter, "Long->Float"),
126            Self::LongToDouble => write!(formatter, "Long->Double"),
127            Self::FloatToDouble => write!(formatter, "Float->Double"),
128            Self::StringToBytes => write!(formatter, "String->Bytes"),
129            Self::BytesToString => write!(formatter, "Bytes->String"),
130        }
131    }
132}
133
134/// Information required to resolve a writer union against a reader union (or single type).
135#[derive(Debug, Clone, PartialEq)]
136pub(crate) struct ResolvedUnion {
137    /// For each writer branch index, the reader branch index and how to read it.
138    /// `None` means the writer branch doesn't resolve against the reader.
139    pub(crate) writer_to_reader: Arc<[Option<(usize, ResolutionInfo)>]>,
140    /// Whether the writer schema at this site is a union
141    pub(crate) writer_is_union: bool,
142    /// Whether the reader schema at this site is a union
143    pub(crate) reader_is_union: bool,
144}
145
146/// Holds the mapping information for resolving Avro enums.
147///
148/// When resolving schemas, the writer's enum symbols must be mapped to the reader's symbols.
149#[derive(Debug, Clone, PartialEq, Eq)]
150pub(crate) struct EnumMapping {
151    /// A mapping from the writer's symbol index to the reader's symbol index.
152    pub(crate) mapping: Arc<[i32]>,
153    /// The index to use for a writer's symbol that is not present in the reader's enum
154    /// and a default value is specified in the reader's schema.
155    pub(crate) default_index: i32,
156}
157
158#[cfg(feature = "canonical_extension_types")]
159fn with_extension_type(codec: &Codec, field: Field) -> Field {
160    match codec {
161        Codec::Uuid => field.with_extension_type(arrow_schema::extension::Uuid),
162        _ => field,
163    }
164}
165
166/// An Avro datatype mapped to the arrow data model
167#[derive(Debug, Clone, PartialEq)]
168pub(crate) struct AvroDataType {
169    nullability: Option<Nullability>,
170    metadata: HashMap<String, String>,
171    codec: Codec,
172    pub(crate) resolution: Option<ResolutionInfo>,
173}
174
175impl AvroDataType {
176    /// Create a new [`AvroDataType`] with the given parts.
177    pub(crate) fn new(
178        codec: Codec,
179        metadata: HashMap<String, String>,
180        nullability: Option<Nullability>,
181    ) -> Self {
182        AvroDataType {
183            codec,
184            metadata,
185            nullability,
186            resolution: None,
187        }
188    }
189
190    #[inline]
191    fn new_with_resolution(
192        codec: Codec,
193        metadata: HashMap<String, String>,
194        nullability: Option<Nullability>,
195        resolution: Option<ResolutionInfo>,
196    ) -> Self {
197        Self {
198            nullability,
199            metadata,
200            codec,
201            resolution,
202        }
203    }
204
205    /// Returns an arrow [`Field`] with the given name
206    pub(crate) fn field_with_name(&self, name: &str) -> Field {
207        let mut nullable = self.nullability.is_some();
208        if !nullable && let Codec::Union(children, _, _) = self.codec() {
209            // If any encoded branch is `null`, mark field as nullable
210            if children.iter().any(|c| matches!(c.codec(), Codec::Null)) {
211                nullable = true;
212            }
213        }
214        let data_type = self.codec.data_type();
215        let field = Field::new(name, data_type, nullable).with_metadata(self.metadata.clone());
216        #[cfg(feature = "canonical_extension_types")]
217        return with_extension_type(&self.codec, field);
218        #[cfg(not(feature = "canonical_extension_types"))]
219        field
220    }
221
222    /// Returns a reference to the codec used by this data type
223    ///
224    /// The codec determines how Avro data is encoded and mapped to Arrow data types.
225    /// This is useful when we need to inspect or use the specific encoding of a field.
226    pub(crate) fn codec(&self) -> &Codec {
227        &self.codec
228    }
229
230    /// Returns the nullability status of this data type
231    ///
232    /// In Avro, nullability is represented through unions with null types.
233    /// The returned value indicates how nulls are encoded in the Avro format:
234    /// - `Some(Nullability::NullFirst)` - Nulls are encoded as the first union variant
235    /// - `Some(Nullability::NullSecond)` - Nulls are encoded as the second union variant
236    /// - `None` - The type is not nullable
237    pub(crate) fn nullability(&self) -> Option<Nullability> {
238        self.nullability
239    }
240
241    #[inline]
242    fn parse_default_literal(&self, default_json: &Value) -> Result<AvroLiteral, ArrowError> {
243        fn expect_string<'v>(
244            default_json: &'v Value,
245            data_type: &str,
246        ) -> Result<&'v str, ArrowError> {
247            match default_json {
248                Value::String(s) => Ok(s.as_str()),
249                _ => Err(ArrowError::SchemaError(format!(
250                    "Default value must be a JSON string for {data_type}"
251                ))),
252            }
253        }
254
255        fn parse_bytes_default(
256            default_json: &Value,
257            expected_len: Option<usize>,
258        ) -> Result<Vec<u8>, ArrowError> {
259            let s = expect_string(default_json, "bytes/fixed logical types")?;
260            let mut out = Vec::with_capacity(s.len());
261            for ch in s.chars() {
262                let cp = ch as u32;
263                if cp > 0xFF {
264                    return Err(ArrowError::SchemaError(format!(
265                        "Invalid codepoint U+{cp:04X} in bytes/fixed default; must be ≤ 0xFF"
266                    )));
267                }
268                out.push(cp as u8);
269            }
270            if let Some(len) = expected_len
271                && out.len() != len
272            {
273                return Err(ArrowError::SchemaError(format!(
274                    "Default length {} does not match expected fixed size {len}",
275                    out.len(),
276                )));
277            }
278            Ok(out)
279        }
280
281        fn parse_json_i64(default_json: &Value, data_type: &str) -> Result<i64, ArrowError> {
282            match default_json {
283                Value::Number(n) => n.as_i64().ok_or_else(|| {
284                    ArrowError::SchemaError(format!("Default {data_type} must be an integer"))
285                }),
286                _ => Err(ArrowError::SchemaError(format!(
287                    "Default {data_type} must be a JSON integer"
288                ))),
289            }
290        }
291
292        fn parse_json_f64(default_json: &Value, data_type: &str) -> Result<f64, ArrowError> {
293            match default_json {
294                Value::Number(n) => n.as_f64().ok_or_else(|| {
295                    ArrowError::SchemaError(format!("Default {data_type} must be a number"))
296                }),
297                _ => Err(ArrowError::SchemaError(format!(
298                    "Default {data_type} must be a JSON number"
299                ))),
300            }
301        }
302
303        // Handle JSON nulls per-spec: allowed only for `null` type or unions with null FIRST
304        if default_json.is_null() {
305            return match self.codec() {
306                Codec::Null => Ok(AvroLiteral::Null),
307                Codec::Union(encodings, _, _) if !encodings.is_empty()
308                    && matches!(encodings[0].codec(), Codec::Null) =>
309                    {
310                        Ok(AvroLiteral::Null)
311                    }
312                _ if self.nullability() == Some(Nullability::NullFirst) => Ok(AvroLiteral::Null),
313                _ => Err(ArrowError::SchemaError(
314                    "JSON null default is only valid for `null` type or for a union whose first branch is `null`"
315                        .to_string(),
316                )),
317            };
318        }
319        let lit = match self.codec() {
320            Codec::Null => {
321                return Err(ArrowError::SchemaError(
322                    "Default for `null` type must be JSON null".to_string(),
323                ));
324            }
325            Codec::Boolean => match default_json {
326                Value::Bool(b) => AvroLiteral::Boolean(*b),
327                _ => {
328                    return Err(ArrowError::SchemaError(
329                        "Boolean default must be a JSON boolean".to_string(),
330                    ));
331                }
332            },
333            Codec::Int32 | Codec::Date32 | Codec::TimeMillis => {
334                let i = parse_json_i64(default_json, "int")?;
335                if i < i32::MIN as i64 || i > i32::MAX as i64 {
336                    return Err(ArrowError::SchemaError(format!(
337                        "Default int {i} out of i32 range"
338                    )));
339                }
340                AvroLiteral::Int(i as i32)
341            }
342            Codec::Int64
343            | Codec::TimeMicros
344            | Codec::TimestampMillis(_)
345            | Codec::TimestampMicros(_)
346            | Codec::TimestampNanos(_) => AvroLiteral::Long(parse_json_i64(default_json, "long")?),
347            #[cfg(feature = "avro_custom_types")]
348            Codec::DurationNanos
349            | Codec::DurationMicros
350            | Codec::DurationMillis
351            | Codec::DurationSeconds => AvroLiteral::Long(parse_json_i64(default_json, "long")?),
352            #[cfg(feature = "avro_custom_types")]
353            Codec::Int8 => {
354                let i = parse_json_i64(default_json, "int")?;
355                if i < i8::MIN as i64 || i > i8::MAX as i64 {
356                    return Err(ArrowError::SchemaError(format!(
357                        "Default int8 {i} out of i8 range"
358                    )));
359                }
360                AvroLiteral::Int(i as i32)
361            }
362            #[cfg(feature = "avro_custom_types")]
363            Codec::Int16 => {
364                let i = parse_json_i64(default_json, "int")?;
365                if i < i16::MIN as i64 || i > i16::MAX as i64 {
366                    return Err(ArrowError::SchemaError(format!(
367                        "Default int16 {i} out of i16 range"
368                    )));
369                }
370                AvroLiteral::Int(i as i32)
371            }
372            #[cfg(feature = "avro_custom_types")]
373            Codec::UInt8 => {
374                let i = parse_json_i64(default_json, "int")?;
375                if i < 0 || i > u8::MAX as i64 {
376                    return Err(ArrowError::SchemaError(format!(
377                        "Default uint8 {i} out of u8 range"
378                    )));
379                }
380                AvroLiteral::Int(i as i32)
381            }
382            #[cfg(feature = "avro_custom_types")]
383            Codec::UInt16 => {
384                let i = parse_json_i64(default_json, "int")?;
385                if i < 0 || i > u16::MAX as i64 {
386                    return Err(ArrowError::SchemaError(format!(
387                        "Default uint16 {i} out of u16 range"
388                    )));
389                }
390                AvroLiteral::Int(i as i32)
391            }
392            #[cfg(feature = "avro_custom_types")]
393            Codec::UInt32 => {
394                let i = parse_json_i64(default_json, "long")?;
395                if i < 0 || i > u32::MAX as i64 {
396                    return Err(ArrowError::SchemaError(format!(
397                        "Default uint32 {i} out of u32 range"
398                    )));
399                }
400                AvroLiteral::Long(i)
401            }
402            #[cfg(feature = "avro_custom_types")]
403            Codec::Date64 | Codec::TimeNanos | Codec::TimestampSecs(_) => {
404                AvroLiteral::Long(parse_json_i64(default_json, "long")?)
405            }
406            #[cfg(feature = "avro_custom_types")]
407            Codec::UInt64 => AvroLiteral::Bytes(parse_bytes_default(default_json, Some(8))?),
408            #[cfg(feature = "avro_custom_types")]
409            Codec::Float16 => AvroLiteral::Bytes(parse_bytes_default(default_json, Some(2))?),
410            #[cfg(feature = "avro_custom_types")]
411            Codec::Time32Secs => {
412                let i = parse_json_i64(default_json, "int")?;
413                if i < i32::MIN as i64 || i > i32::MAX as i64 {
414                    return Err(ArrowError::SchemaError(format!(
415                        "Default time32-secs {i} out of i32 range"
416                    )));
417                }
418                AvroLiteral::Int(i as i32)
419            }
420            #[cfg(feature = "avro_custom_types")]
421            Codec::IntervalYearMonth => {
422                AvroLiteral::Bytes(parse_bytes_default(default_json, Some(4))?)
423            }
424            #[cfg(feature = "avro_custom_types")]
425            Codec::IntervalMonthDayNano => {
426                AvroLiteral::Bytes(parse_bytes_default(default_json, Some(16))?)
427            }
428            #[cfg(feature = "avro_custom_types")]
429            Codec::IntervalDayTime => {
430                AvroLiteral::Bytes(parse_bytes_default(default_json, Some(8))?)
431            }
432            Codec::Float32 => {
433                let f = parse_json_f64(default_json, "float")?;
434                if !f.is_finite() || f < f32::MIN as f64 || f > f32::MAX as f64 {
435                    return Err(ArrowError::SchemaError(format!(
436                        "Default float {f} out of f32 range or not finite"
437                    )));
438                }
439                AvroLiteral::Float(f as f32)
440            }
441            Codec::Float64 => AvroLiteral::Double(parse_json_f64(default_json, "double")?),
442            Codec::Utf8 | Codec::Utf8View | Codec::Uuid => {
443                AvroLiteral::String(expect_string(default_json, "string/uuid")?.to_string())
444            }
445            Codec::Binary => AvroLiteral::Bytes(parse_bytes_default(default_json, None)?),
446            Codec::Fixed(sz) => {
447                AvroLiteral::Bytes(parse_bytes_default(default_json, Some(*sz as usize))?)
448            }
449            Codec::Decimal(_, _, fixed_size) => {
450                AvroLiteral::Bytes(parse_bytes_default(default_json, *fixed_size)?)
451            }
452            Codec::Enum(symbols) => {
453                let s = expect_string(default_json, "enum")?;
454                if symbols.iter().any(|sym| sym == s) {
455                    AvroLiteral::Enum(s.to_string())
456                } else {
457                    return Err(ArrowError::SchemaError(format!(
458                        "Default enum symbol {s:?} not found in reader enum symbols"
459                    )));
460                }
461            }
462            Codec::Interval => AvroLiteral::Bytes(parse_bytes_default(default_json, Some(12))?),
463            Codec::List(item_dt) => match default_json {
464                Value::Array(items) => AvroLiteral::Array(
465                    items
466                        .iter()
467                        .map(|v| item_dt.parse_default_literal(v))
468                        .collect::<Result<_, _>>()?,
469                ),
470                _ => {
471                    return Err(ArrowError::SchemaError(
472                        "Default value must be a JSON array for Avro array type".to_string(),
473                    ));
474                }
475            },
476            Codec::Map(val_dt) => match default_json {
477                Value::Object(map) => {
478                    let mut out = IndexMap::with_capacity(map.len());
479                    for (k, v) in map {
480                        out.insert(k.clone(), val_dt.parse_default_literal(v)?);
481                    }
482                    AvroLiteral::Map(out)
483                }
484                _ => {
485                    return Err(ArrowError::SchemaError(
486                        "Default value must be a JSON object for Avro map type".to_string(),
487                    ));
488                }
489            },
490            Codec::Struct(fields) => match default_json {
491                Value::Object(obj) => {
492                    let mut out: IndexMap<String, AvroLiteral> =
493                        IndexMap::with_capacity(fields.len());
494                    for f in fields.as_ref() {
495                        let name = f.name().to_string();
496                        if let Some(sub) = obj.get(&name) {
497                            out.insert(name, f.data_type().parse_default_literal(sub)?);
498                        } else {
499                            // Cache metadata lookup once
500                            let stored_default =
501                                f.data_type().metadata.get(AVRO_FIELD_DEFAULT_METADATA_KEY);
502                            if stored_default.is_none()
503                                && f.data_type().nullability() == Some(Nullability::default())
504                            {
505                                out.insert(name, AvroLiteral::Null);
506                            } else if let Some(default_json) = stored_default {
507                                let v: Value =
508                                    serde_json::from_str(default_json).map_err(|e| {
509                                        ArrowError::SchemaError(format!(
510                                            "Failed to parse stored subfield default JSON for '{}': {e}",
511                                            f.name(),
512                                        ))
513                                    })?;
514                                out.insert(name, f.data_type().parse_default_literal(&v)?);
515                            } else {
516                                return Err(ArrowError::SchemaError(format!(
517                                    "Record default missing required subfield '{}' with non-nullable type {:?}",
518                                    f.name(),
519                                    f.data_type().codec()
520                                )));
521                            }
522                        }
523                    }
524                    AvroLiteral::Map(out)
525                }
526                _ => {
527                    return Err(ArrowError::SchemaError(
528                        "Default value for record/struct must be a JSON object".to_string(),
529                    ));
530                }
531            },
532            Codec::Union(encodings, _, _) => {
533                let Some(default_encoding) = encodings.first() else {
534                    return Err(ArrowError::SchemaError(
535                        "Union with no branches cannot have a default".to_string(),
536                    ));
537                };
538                default_encoding.parse_default_literal(default_json)?
539            }
540            #[cfg(feature = "avro_custom_types")]
541            Codec::RunEndEncoded(values, _) => values.parse_default_literal(default_json)?,
542        };
543        Ok(lit)
544    }
545
546    fn store_default(&mut self, default_json: &Value) -> Result<(), ArrowError> {
547        let json_text = serde_json::to_string(default_json).map_err(|e| {
548            ArrowError::ParseError(format!("Failed to serialize default to JSON: {e}"))
549        })?;
550        self.metadata
551            .insert(AVRO_FIELD_DEFAULT_METADATA_KEY.to_string(), json_text);
552        Ok(())
553    }
554
555    fn parse_and_store_default(&mut self, default_json: &Value) -> Result<AvroLiteral, ArrowError> {
556        let lit = self.parse_default_literal(default_json)?;
557        self.store_default(default_json)?;
558        Ok(lit)
559    }
560}
561
562/// A named [`AvroDataType`]
563#[derive(Debug, Clone, PartialEq)]
564pub(crate) struct AvroField {
565    name: String,
566    data_type: AvroDataType,
567}
568
569impl AvroField {
570    /// Returns the arrow [`Field`]
571    pub(crate) fn field(&self) -> Field {
572        self.data_type.field_with_name(&self.name)
573    }
574
575    /// Returns the [`AvroDataType`]
576    pub(crate) fn data_type(&self) -> &AvroDataType {
577        &self.data_type
578    }
579
580    /// Returns a new [`AvroField`] with Utf8View support enabled
581    ///
582    /// This will convert any Utf8 codecs to Utf8View codecs. This method is used to
583    /// enable potential performance optimizations in string-heavy workloads by using
584    /// Arrow's StringViewArray data structure.
585    ///
586    /// Returns a new `AvroField` with the same structure, but with string types
587    /// converted to use `Utf8View` instead of `Utf8`.
588    pub(crate) fn with_utf8view(&self) -> Self {
589        let mut field = self.clone();
590        if field.data_type.codec == Codec::Utf8 {
591            field.data_type.codec = Codec::Utf8View;
592        }
593        field
594    }
595
596    /// Returns the name of this Avro field
597    ///
598    /// This is the field name as defined in the Avro schema.
599    /// It's used to identify fields within a record structure.
600    pub(crate) fn name(&self) -> &str {
601        &self.name
602    }
603}
604
605impl<'a> TryFrom<&Schema<'a>> for AvroField {
606    type Error = ArrowError;
607
608    fn try_from(schema: &Schema<'a>) -> Result<Self, Self::Error> {
609        match schema {
610            Schema::Complex(ComplexType::Record(r)) => {
611                let mut resolver = Maker::new(false, false, Tz::default());
612                let data_type = resolver.make_data_type(schema, None, None)?;
613                Ok(AvroField {
614                    data_type,
615                    name: r.name.to_string(),
616                })
617            }
618            _ => Err(ArrowError::ParseError(format!(
619                "Expected record got {schema:?}"
620            ))),
621        }
622    }
623}
624
625/// Builder for an [`AvroField`]
626#[derive(Debug)]
627pub(crate) struct AvroFieldBuilder<'a> {
628    writer_schema: &'a Schema<'a>,
629    reader_schema: Option<&'a Schema<'a>>,
630    use_utf8view: bool,
631    strict_mode: bool,
632    tz: Tz,
633}
634
635impl<'a> AvroFieldBuilder<'a> {
636    /// Creates a new [`AvroFieldBuilder`] for a given writer schema.
637    pub(crate) fn new(writer_schema: &'a Schema<'a>) -> Self {
638        Self {
639            writer_schema,
640            reader_schema: None,
641            use_utf8view: false,
642            strict_mode: false,
643            tz: Tz::default(),
644        }
645    }
646
647    /// Sets the reader schema for schema resolution.
648    ///
649    /// If a reader schema is provided, the builder will produce a resolved `AvroField`
650    /// that can handle differences between the writer's and reader's schemas.
651    #[inline]
652    pub(crate) fn with_reader_schema(mut self, reader_schema: &'a Schema<'a>) -> Self {
653        self.reader_schema = Some(reader_schema);
654        self
655    }
656
657    /// Enable or disable Utf8View support
658    pub(crate) fn with_utf8view(mut self, use_utf8view: bool) -> Self {
659        self.use_utf8view = use_utf8view;
660        self
661    }
662
663    /// Enable or disable strict mode.
664    pub(crate) fn with_strict_mode(mut self, strict_mode: bool) -> Self {
665        self.strict_mode = strict_mode;
666        self
667    }
668
669    /// Sets the timezone representation for timestamps.
670    pub(crate) fn with_tz(mut self, tz: Tz) -> Self {
671        self.tz = tz;
672        self
673    }
674
675    /// Build an [`AvroField`] from the builder
676    pub(crate) fn build(self) -> Result<AvroField, ArrowError> {
677        match self.writer_schema {
678            Schema::Complex(ComplexType::Record(r)) => {
679                let mut resolver = Maker::new(self.use_utf8view, self.strict_mode, self.tz);
680                let data_type =
681                    resolver.make_data_type(self.writer_schema, self.reader_schema, None)?;
682                Ok(AvroField {
683                    name: r.name.to_string(),
684                    data_type,
685                })
686            }
687            _ => Err(ArrowError::ParseError(format!(
688                "Expected a Record schema to build an AvroField, but got {:?}",
689                self.writer_schema
690            ))),
691        }
692    }
693}
694
695/// Timezone representation for timestamps.
696///
697/// Avro only distinguishes between UTC and local time (no timezone), but Arrow supports
698/// any of the two identifiers of the UTC timezone: "+00:00" and "UTC".
699/// The data types using these time zone IDs behave identically, but are not logically equal.
700#[derive(Debug, Copy, Clone, PartialEq, Default)]
701pub enum Tz {
702    /// Represent Avro `timestamp-*` logical types with "+00:00" timezone ID
703    #[default]
704    OffsetZero,
705    /// Represent Avro `timestamp-*` logical types with "UTC" timezone ID
706    Utc,
707}
708
709impl Tz {
710    /// Returns the string identifier for this timezone representation
711    pub fn as_str(&self) -> &'static str {
712        match self {
713            Self::OffsetZero => "+00:00",
714            Self::Utc => "UTC",
715        }
716    }
717}
718
719impl Display for Tz {
720    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
721        f.write_str(self.as_str())
722    }
723}
724
725/// An Avro encoding
726///
727/// <https://avro.apache.org/docs/1.11.1/specification/#encodings>
728#[derive(Debug, Clone, PartialEq)]
729pub(crate) enum Codec {
730    /// Represents Avro null type, maps to Arrow's Null data type
731    Null,
732    /// Represents Avro boolean type, maps to Arrow's Boolean data type
733    Boolean,
734    /// Represents Avro int type, maps to Arrow's Int32 data type
735    Int32,
736    /// Represents Avro long type, maps to Arrow's Int64 data type
737    Int64,
738    /// Represents Avro float type, maps to Arrow's Float32 data type
739    Float32,
740    /// Represents Avro double type, maps to Arrow's Float64 data type
741    Float64,
742    /// Represents Avro bytes type, maps to Arrow's Binary data type
743    Binary,
744    /// String data represented as UTF-8 encoded bytes, corresponding to Arrow's StringArray
745    Utf8,
746    /// String data represented as UTF-8 encoded bytes with an optimized view representation,
747    /// corresponding to Arrow's StringViewArray which provides better performance for string operations
748    ///
749    /// The Utf8View option can be enabled via `ReadOptions::use_utf8view`.
750    Utf8View,
751    /// Represents Avro date logical type, maps to Arrow's Date32 data type
752    Date32,
753    /// Represents Avro time-millis logical type, maps to Arrow's Time32(TimeUnit::Millisecond) data type
754    TimeMillis,
755    /// Represents Avro time-micros logical type, maps to Arrow's Time64(TimeUnit::Microsecond) data type
756    TimeMicros,
757    /// Represents Avro timestamp-millis or local-timestamp-millis logical type
758    ///
759    /// Maps to Arrow's Timestamp(TimeUnit::Millisecond) data type
760    /// The parameter indicates whether the timestamp has a UTC timezone (Some) or is local time (None)
761    TimestampMillis(Option<Tz>),
762    /// Represents Avro timestamp-micros or local-timestamp-micros logical type
763    ///
764    /// Maps to Arrow's Timestamp(TimeUnit::Microsecond) data type
765    /// The parameter indicates whether the timestamp has a UTC timezone (Some) or is local time (None)
766    TimestampMicros(Option<Tz>),
767    /// Represents Avro timestamp-nanos or local-timestamp-nanos logical type
768    ///
769    /// Maps to Arrow's Timestamp(TimeUnit::Nanosecond) data type
770    /// The parameter indicates whether the timestamp has a UTC timezone (Some) or is local time (None)
771    TimestampNanos(Option<Tz>),
772    /// Represents Avro fixed type, maps to Arrow's FixedSizeBinary data type
773    /// The i32 parameter indicates the fixed binary size
774    Fixed(i32),
775    /// Represents Avro decimal type, maps to Arrow's Decimal32, Decimal64, Decimal128, or Decimal256 data types
776    ///
777    /// The fields are `(precision, scale, fixed_size)`.
778    /// - `precision` (`usize`): Total number of digits.
779    /// - `scale` (`Option<usize>`): Number of fractional digits.
780    /// - `fixed_size` (`Option<usize>`): Size in bytes if backed by a `fixed` type, otherwise `None`.
781    Decimal(usize, Option<usize>, Option<usize>),
782    /// Represents Avro Uuid type, a FixedSizeBinary with a length of 16.
783    Uuid,
784    /// Represents an Avro enum, maps to Arrow's Dictionary(Int32, Utf8) type.
785    ///
786    /// The enclosed value contains the enum's symbols.
787    Enum(Arc<[String]>),
788    /// Represents Avro array type, maps to Arrow's List data type
789    List(Arc<AvroDataType>),
790    /// Represents Avro record type, maps to Arrow's Struct data type
791    Struct(Arc<[AvroField]>),
792    /// Represents Avro map type, maps to Arrow's Map data type
793    Map(Arc<AvroDataType>),
794    /// Represents Avro duration logical type, maps to Arrow's Interval(IntervalUnit::MonthDayNano) data type
795    Interval,
796    /// Represents Avro union type, maps to Arrow's Union data type
797    Union(Arc<[AvroDataType]>, UnionFields, UnionMode),
798    /// Represents Avro custom logical type to map to Arrow Duration(TimeUnit::Nanosecond)
799    #[cfg(feature = "avro_custom_types")]
800    DurationNanos,
801    /// Represents Avro custom logical type to map to Arrow Duration(TimeUnit::Microsecond)
802    #[cfg(feature = "avro_custom_types")]
803    DurationMicros,
804    /// Represents Avro custom logical type to map to Arrow Duration(TimeUnit::Millisecond)
805    #[cfg(feature = "avro_custom_types")]
806    DurationMillis,
807    /// Represents Avro custom logical type to map to Arrow Duration(TimeUnit::Second)
808    #[cfg(feature = "avro_custom_types")]
809    DurationSeconds,
810    #[cfg(feature = "avro_custom_types")]
811    RunEndEncoded(Arc<AvroDataType>, u8),
812    /// Arrow Int8 custom logical type (arrow.int8)
813    #[cfg(feature = "avro_custom_types")]
814    Int8,
815    /// Arrow Int16 custom logical type (arrow.int16)
816    #[cfg(feature = "avro_custom_types")]
817    Int16,
818    /// Arrow UInt8 custom logical type (arrow.uint8)
819    #[cfg(feature = "avro_custom_types")]
820    UInt8,
821    /// Arrow UInt16 custom logical type (arrow.uint16)
822    #[cfg(feature = "avro_custom_types")]
823    UInt16,
824    /// Arrow UInt32 custom logical type (arrow.uint32)
825    #[cfg(feature = "avro_custom_types")]
826    UInt32,
827    /// Arrow UInt64 custom logical type (arrow.uint64) - stored as fixed(8)
828    #[cfg(feature = "avro_custom_types")]
829    UInt64,
830    /// Arrow Float16 custom logical type (arrow.float16) - stored as fixed(2)
831    #[cfg(feature = "avro_custom_types")]
832    Float16,
833    /// Arrow Date64 custom logical type (arrow.date64)
834    #[cfg(feature = "avro_custom_types")]
835    Date64,
836    /// Arrow Time64(Nanosecond) custom logical type (arrow.time64-nanosecond)
837    #[cfg(feature = "avro_custom_types")]
838    TimeNanos,
839    /// Arrow Time32(Second) custom logical type (arrow.time32-second)
840    #[cfg(feature = "avro_custom_types")]
841    Time32Secs,
842    /// Arrow Timestamp(Second) custom logical type (arrow.timestamp-second)
843    /// The bool indicates UTC (true) or local (false)
844    #[cfg(feature = "avro_custom_types")]
845    TimestampSecs(bool),
846    /// Arrow Interval(YearMonth) custom logical type (arrow.interval-year-month)
847    #[cfg(feature = "avro_custom_types")]
848    IntervalYearMonth,
849    /// Arrow Interval(MonthDayNano) custom logical type (arrow.interval-month-day-nano)
850    #[cfg(feature = "avro_custom_types")]
851    IntervalMonthDayNano,
852    /// Arrow Interval(DayTime) custom logical type (arrow.interval-day-time)
853    #[cfg(feature = "avro_custom_types")]
854    IntervalDayTime,
855}
856
857impl Codec {
858    fn data_type(&self) -> DataType {
859        match self {
860            Self::Null => DataType::Null,
861            Self::Boolean => DataType::Boolean,
862            Self::Int32 => DataType::Int32,
863            Self::Int64 => DataType::Int64,
864            Self::Float32 => DataType::Float32,
865            Self::Float64 => DataType::Float64,
866            Self::Binary => DataType::Binary,
867            Self::Utf8 => DataType::Utf8,
868            Self::Utf8View => DataType::Utf8View,
869            Self::Date32 => DataType::Date32,
870            Self::TimeMillis => DataType::Time32(TimeUnit::Millisecond),
871            Self::TimeMicros => DataType::Time64(TimeUnit::Microsecond),
872            Self::TimestampMillis(tz) => DataType::Timestamp(
873                TimeUnit::Millisecond,
874                tz.as_ref().map(|tz| tz.as_str().into()),
875            ),
876            Self::TimestampMicros(tz) => DataType::Timestamp(
877                TimeUnit::Microsecond,
878                tz.as_ref().map(|tz| tz.as_str().into()),
879            ),
880            Self::TimestampNanos(tz) => DataType::Timestamp(
881                TimeUnit::Nanosecond,
882                tz.as_ref().map(|tz| tz.as_str().into()),
883            ),
884            Self::Interval => DataType::Interval(IntervalUnit::MonthDayNano),
885            Self::Fixed(size) => DataType::FixedSizeBinary(*size),
886            Self::Decimal(precision, scale, _size) => {
887                let p = *precision as u8;
888                let s = scale.unwrap_or(0) as i8;
889                #[cfg(feature = "small_decimals")]
890                {
891                    if *precision <= DECIMAL32_MAX_PRECISION as usize {
892                        DataType::Decimal32(p, s)
893                    } else if *precision <= DECIMAL64_MAX_PRECISION as usize {
894                        DataType::Decimal64(p, s)
895                    } else if *precision <= DECIMAL128_MAX_PRECISION as usize {
896                        DataType::Decimal128(p, s)
897                    } else {
898                        DataType::Decimal256(p, s)
899                    }
900                }
901                #[cfg(not(feature = "small_decimals"))]
902                {
903                    if *precision <= DECIMAL128_MAX_PRECISION as usize {
904                        DataType::Decimal128(p, s)
905                    } else {
906                        DataType::Decimal256(p, s)
907                    }
908                }
909            }
910            Self::Uuid => DataType::FixedSizeBinary(16),
911            Self::Enum(_) => {
912                DataType::Dictionary(Box::new(DataType::Int32), Box::new(DataType::Utf8))
913            }
914            Self::List(f) => {
915                DataType::List(Arc::new(f.field_with_name(Field::LIST_FIELD_DEFAULT_NAME)))
916            }
917            Self::Struct(f) => DataType::Struct(f.iter().map(|x| x.field()).collect()),
918            Self::Map(value_type) => {
919                let val_field = value_type.field_with_name(Field::MAP_VALUE_FIELD_DEFAULT_NAME);
920                DataType::Map(
921                    Arc::new(Field::new(
922                        Field::MAP_ENTRIES_FIELD_DEFAULT_NAME,
923                        DataType::Struct(Fields::from(vec![
924                            Field::new(Field::MAP_KEY_FIELD_DEFAULT_NAME, DataType::Utf8, false),
925                            val_field,
926                        ])),
927                        false,
928                    )),
929                    false,
930                )
931            }
932            Self::Union(_, fields, mode) => DataType::Union(fields.clone(), *mode),
933            #[cfg(feature = "avro_custom_types")]
934            Self::DurationNanos => DataType::Duration(TimeUnit::Nanosecond),
935            #[cfg(feature = "avro_custom_types")]
936            Self::DurationMicros => DataType::Duration(TimeUnit::Microsecond),
937            #[cfg(feature = "avro_custom_types")]
938            Self::DurationMillis => DataType::Duration(TimeUnit::Millisecond),
939            #[cfg(feature = "avro_custom_types")]
940            Self::DurationSeconds => DataType::Duration(TimeUnit::Second),
941            #[cfg(feature = "avro_custom_types")]
942            Self::RunEndEncoded(values, bits) => {
943                let run_ends_dt = match *bits {
944                    16 => DataType::Int16,
945                    32 => DataType::Int32,
946                    64 => DataType::Int64,
947                    _ => unreachable!(),
948                };
949                DataType::RunEndEncoded(
950                    Arc::new(Field::new(
951                        Field::REE_RUN_ENDS_FIELD_DEFAULT_NAME,
952                        run_ends_dt,
953                        false,
954                    )),
955                    Arc::new(Field::new(
956                        Field::REE_VALUES_FIELD_DEFAULT_NAME,
957                        values.codec().data_type(),
958                        true,
959                    )),
960                )
961            }
962            #[cfg(feature = "avro_custom_types")]
963            Self::Int8 => DataType::Int8,
964            #[cfg(feature = "avro_custom_types")]
965            Self::Int16 => DataType::Int16,
966            #[cfg(feature = "avro_custom_types")]
967            Self::UInt8 => DataType::UInt8,
968            #[cfg(feature = "avro_custom_types")]
969            Self::UInt16 => DataType::UInt16,
970            #[cfg(feature = "avro_custom_types")]
971            Self::UInt32 => DataType::UInt32,
972            #[cfg(feature = "avro_custom_types")]
973            Self::UInt64 => DataType::UInt64,
974            #[cfg(feature = "avro_custom_types")]
975            Self::Float16 => DataType::Float16,
976            #[cfg(feature = "avro_custom_types")]
977            Self::Date64 => DataType::Date64,
978            #[cfg(feature = "avro_custom_types")]
979            Self::TimeNanos => DataType::Time64(TimeUnit::Nanosecond),
980            #[cfg(feature = "avro_custom_types")]
981            Self::Time32Secs => DataType::Time32(TimeUnit::Second),
982            #[cfg(feature = "avro_custom_types")]
983            Self::TimestampSecs(is_utc) => {
984                DataType::Timestamp(TimeUnit::Second, is_utc.then(|| "+00:00".into()))
985            }
986            #[cfg(feature = "avro_custom_types")]
987            Self::IntervalYearMonth => DataType::Interval(IntervalUnit::YearMonth),
988            #[cfg(feature = "avro_custom_types")]
989            Self::IntervalMonthDayNano => DataType::Interval(IntervalUnit::MonthDayNano),
990            #[cfg(feature = "avro_custom_types")]
991            Self::IntervalDayTime => DataType::Interval(IntervalUnit::DayTime),
992        }
993    }
994
995    /// Converts a string codec to use Utf8View if requested
996    ///
997    /// The conversion only happens if both:
998    /// 1. `use_utf8view` is true
999    /// 2. The codec is currently `Utf8`
1000    pub(crate) fn with_utf8view(self, use_utf8view: bool) -> Self {
1001        if use_utf8view && matches!(self, Self::Utf8) {
1002            Self::Utf8View
1003        } else {
1004            self
1005        }
1006    }
1007
1008    #[inline]
1009    fn union_field_name(&self) -> String {
1010        UnionFieldKind::from(self).as_ref().to_owned()
1011    }
1012}
1013
1014impl From<PrimitiveType> for Codec {
1015    fn from(value: PrimitiveType) -> Self {
1016        match value {
1017            PrimitiveType::Null => Self::Null,
1018            PrimitiveType::Boolean => Self::Boolean,
1019            PrimitiveType::Int => Self::Int32,
1020            PrimitiveType::Long => Self::Int64,
1021            PrimitiveType::Float => Self::Float32,
1022            PrimitiveType::Double => Self::Float64,
1023            PrimitiveType::Bytes => Self::Binary,
1024            PrimitiveType::String => Self::Utf8,
1025        }
1026    }
1027}
1028
1029/// Compute the exact maximum base‑10 precision that fits in `n` bytes for Avro
1030/// `fixed` decimals stored as two's‑complement unscaled integers (big‑endian).
1031///
1032/// Per Avro spec (Decimal logical type), for a fixed length `n`:
1033/// max precision = ⌊log₁₀(2^(8n − 1) − 1)⌋.
1034///
1035/// This function returns `None` if `n` is 0 or greater than 32 (Arrow supports
1036/// Decimal256, which is 32 bytes and has max precision 76).
1037const fn max_precision_for_fixed_bytes(n: usize) -> Option<usize> {
1038    // Precomputed exact table for n = 1..=32
1039    // 1:2, 2:4, 3:6, 4:9, 5:11, 6:14, 7:16, 8:18, 9:21, 10:23, 11:26, 12:28,
1040    // 13:31, 14:33, 15:35, 16:38, 17:40, 18:43, 19:45, 20:47, 21:50, 22:52,
1041    // 23:55, 24:57, 25:59, 26:62, 27:64, 28:67, 29:69, 30:71, 31:74, 32:76
1042    const MAX_P: [usize; 32] = [
1043        2, 4, 6, 9, 11, 14, 16, 18, 21, 23, 26, 28, 31, 33, 35, 38, 40, 43, 45, 47, 50, 52, 55, 57,
1044        59, 62, 64, 67, 69, 71, 74, 76,
1045    ];
1046    match n {
1047        1..=32 => Some(MAX_P[n - 1]),
1048        _ => None,
1049    }
1050}
1051
1052fn parse_decimal_attributes(
1053    attributes: &Attributes,
1054    fallback_size: Option<usize>,
1055    precision_required: bool,
1056) -> Result<(usize, usize, Option<usize>), ArrowError> {
1057    let precision = attributes
1058        .additional
1059        .get("precision")
1060        .and_then(|v| v.as_u64())
1061        .or(if precision_required { None } else { Some(10) })
1062        .ok_or_else(|| ArrowError::ParseError("Decimal requires precision".to_string()))?
1063        as usize;
1064    let scale = attributes
1065        .additional
1066        .get("scale")
1067        .and_then(|v| v.as_u64())
1068        .unwrap_or(0) as usize;
1069    let size = attributes
1070        .additional
1071        .get("size")
1072        .and_then(|v| v.as_u64())
1073        .map(|s| s as usize)
1074        .or(fallback_size);
1075    if precision == 0 {
1076        return Err(ArrowError::ParseError(
1077            "Decimal requires precision > 0".to_string(),
1078        ));
1079    }
1080    if scale > precision {
1081        return Err(ArrowError::ParseError(format!(
1082            "Decimal has invalid scale > precision: scale={scale}, precision={precision}"
1083        )));
1084    }
1085    if precision > DECIMAL256_MAX_PRECISION as usize {
1086        return Err(ArrowError::ParseError(format!(
1087            "Decimal precision {precision} exceeds maximum supported by Arrow ({DECIMAL256_MAX_PRECISION})"
1088        )));
1089    }
1090    if let Some(sz) = size {
1091        let max_p = max_precision_for_fixed_bytes(sz).ok_or_else(|| {
1092            ArrowError::ParseError(format!(
1093                "Invalid fixed size for decimal: {sz}, must be between 1 and 32 bytes"
1094            ))
1095        })?;
1096        if precision > max_p {
1097            return Err(ArrowError::ParseError(format!(
1098                "Decimal precision {precision} exceeds capacity of fixed size {sz} bytes (max {max_p})"
1099            )));
1100        }
1101    }
1102    Ok((precision, scale, size))
1103}
1104
1105#[derive(Debug, Clone, Copy, PartialEq, Eq, AsRefStr)]
1106#[strum(serialize_all = "snake_case")]
1107enum UnionFieldKind {
1108    Null,
1109    Boolean,
1110    Int,
1111    Long,
1112    Float,
1113    Double,
1114    Bytes,
1115    String,
1116    Date,
1117    TimeMillis,
1118    TimeMicros,
1119    TimestampMillisUtc,
1120    TimestampMillisLocal,
1121    TimestampMicrosUtc,
1122    TimestampMicrosLocal,
1123    TimestampNanosUtc,
1124    TimestampNanosLocal,
1125    Duration,
1126    Fixed,
1127    Decimal,
1128    Enum,
1129    Array,
1130    Record,
1131    Map,
1132    Uuid,
1133    Union,
1134}
1135
1136impl From<&Codec> for UnionFieldKind {
1137    fn from(c: &Codec) -> Self {
1138        match c {
1139            Codec::Null => Self::Null,
1140            Codec::Boolean => Self::Boolean,
1141            Codec::Int32 => Self::Int,
1142            Codec::Int64 => Self::Long,
1143            Codec::Float32 => Self::Float,
1144            Codec::Float64 => Self::Double,
1145            Codec::Binary => Self::Bytes,
1146            Codec::Utf8 | Codec::Utf8View => Self::String,
1147            Codec::Date32 => Self::Date,
1148            Codec::TimeMillis => Self::TimeMillis,
1149            Codec::TimeMicros => Self::TimeMicros,
1150            Codec::TimestampMillis(Some(Tz::OffsetZero)) => Self::TimestampMillisUtc,
1151            Codec::TimestampMillis(Some(Tz::Utc)) => Self::TimestampMillisUtc,
1152            Codec::TimestampMillis(None) => Self::TimestampMillisLocal,
1153            Codec::TimestampMicros(Some(Tz::OffsetZero)) => Self::TimestampMicrosUtc,
1154            Codec::TimestampMicros(Some(Tz::Utc)) => Self::TimestampMicrosUtc,
1155            Codec::TimestampMicros(None) => Self::TimestampMicrosLocal,
1156            Codec::TimestampNanos(Some(Tz::OffsetZero)) => Self::TimestampNanosUtc,
1157            Codec::TimestampNanos(Some(Tz::Utc)) => Self::TimestampNanosUtc,
1158            Codec::TimestampNanos(None) => Self::TimestampNanosLocal,
1159            Codec::Interval => Self::Duration,
1160            Codec::Fixed(_) => Self::Fixed,
1161            Codec::Decimal(..) => Self::Decimal,
1162            Codec::Enum(_) => Self::Enum,
1163            Codec::List(_) => Self::Array,
1164            Codec::Struct(_) => Self::Record,
1165            Codec::Map(_) => Self::Map,
1166            Codec::Uuid => Self::Uuid,
1167            Codec::Union(..) => Self::Union,
1168            #[cfg(feature = "avro_custom_types")]
1169            Codec::RunEndEncoded(values, _) => UnionFieldKind::from(values.codec()),
1170            #[cfg(feature = "avro_custom_types")]
1171            Codec::DurationNanos
1172            | Codec::DurationMicros
1173            | Codec::DurationMillis
1174            | Codec::DurationSeconds => Self::Duration,
1175            #[cfg(feature = "avro_custom_types")]
1176            Codec::Int8 | Codec::Int16 | Codec::UInt8 | Codec::UInt16 => Self::Int,
1177            #[cfg(feature = "avro_custom_types")]
1178            Codec::UInt32 | Codec::Date64 | Codec::TimeNanos | Codec::TimestampSecs(_) => {
1179                Self::Long
1180            }
1181            #[cfg(feature = "avro_custom_types")]
1182            Codec::Time32Secs => Self::TimeMillis, // Closest standard type
1183            #[cfg(feature = "avro_custom_types")]
1184            Codec::UInt64
1185            | Codec::Float16
1186            | Codec::IntervalYearMonth
1187            | Codec::IntervalMonthDayNano
1188            | Codec::IntervalDayTime => Self::Fixed,
1189        }
1190    }
1191}
1192
1193fn union_branch_name(dt: &AvroDataType) -> String {
1194    if let Some(name) = dt.metadata.get(AVRO_NAME_METADATA_KEY) {
1195        if name.contains('.') {
1196            // Full name
1197            return name.clone();
1198        }
1199        if let Some(ns) = dt.metadata.get(AVRO_NAMESPACE_METADATA_KEY) {
1200            return format!("{ns}.{name}");
1201        }
1202        return name.clone();
1203    }
1204    dt.codec.union_field_name()
1205}
1206
1207fn build_union_fields(encodings: &[AvroDataType]) -> Result<UnionFields, ArrowError> {
1208    let arrow_fields: Vec<Field> = encodings
1209        .iter()
1210        .map(|encoding| encoding.field_with_name(&union_branch_name(encoding)))
1211        .collect();
1212    let type_ids: Vec<i8> = (0..arrow_fields.len()).map(|i| i as i8).collect();
1213    UnionFields::try_new(type_ids, arrow_fields)
1214}
1215
1216/// Resolves Avro type names to [`AvroDataType`]
1217///
1218/// See <https://avro.apache.org/docs/1.11.1/specification/#names>
1219#[derive(Debug, Default)]
1220struct Resolver<'a> {
1221    map: HashMap<(&'a str, &'a str), AvroDataType>,
1222}
1223
1224impl<'a> Resolver<'a> {
1225    fn register(&mut self, name: &'a str, namespace: Option<&'a str>, schema: AvroDataType) {
1226        let (namespace, name) = name
1227            .rsplit_once('.')
1228            .unwrap_or_else(|| (namespace.unwrap_or(""), name));
1229        self.map.insert((namespace, name), schema);
1230    }
1231
1232    fn resolve(&self, name: &str, namespace: Option<&'a str>) -> Result<AvroDataType, ArrowError> {
1233        let (namespace, name) = name
1234            .rsplit_once('.')
1235            .unwrap_or_else(|| (namespace.unwrap_or(""), name));
1236        self.map
1237            .get(&(namespace, name))
1238            .ok_or_else(|| ArrowError::ParseError(format!("Failed to resolve {namespace}.{name}")))
1239            .cloned()
1240    }
1241}
1242
1243/// Returns the namespace of a named type.
1244///
1245/// A name containing a dot is a full name, so its namespace is taken from the name and both
1246/// the `namespace` attribute and the enclosing namespace are ignored.
1247///
1248/// See <https://avro.apache.org/docs/1.11.1/specification/#names>
1249fn named_type_namespace<'a>(
1250    name: &'a str,
1251    namespace: Option<&'a str>,
1252    enclosing_ns: Option<&'a str>,
1253) -> Option<&'a str> {
1254    match name.rsplit_once('.') {
1255        Some((ns, _)) => Some(ns),
1256        None => namespace.or(enclosing_ns),
1257    }
1258}
1259
1260fn full_name_set(name: &str, ns: Option<&str>, aliases: &[&str]) -> HashSet<String> {
1261    let mut out = HashSet::with_capacity(1 + aliases.len());
1262    let (full, _) = make_full_name(name, ns, None);
1263    out.insert(full);
1264    for a in aliases {
1265        let (fa, _) = make_full_name(a, None, ns);
1266        out.insert(fa);
1267    }
1268    out
1269}
1270
1271fn names_match(
1272    writer_name: &str,
1273    writer_namespace: Option<&str>,
1274    writer_aliases: &[&str],
1275    reader_name: &str,
1276    reader_namespace: Option<&str>,
1277    reader_aliases: &[&str],
1278) -> bool {
1279    let writer_set = full_name_set(writer_name, writer_namespace, writer_aliases);
1280    let reader_set = full_name_set(reader_name, reader_namespace, reader_aliases);
1281    // If the canonical full names match, or any alias matches cross-wise.
1282    !writer_set.is_disjoint(&reader_set)
1283}
1284
1285fn ensure_names_match(
1286    data_type: &str,
1287    writer_name: &str,
1288    writer_namespace: Option<&str>,
1289    writer_aliases: &[&str],
1290    reader_name: &str,
1291    reader_namespace: Option<&str>,
1292    reader_aliases: &[&str],
1293) -> Result<(), ArrowError> {
1294    if names_match(
1295        writer_name,
1296        writer_namespace,
1297        writer_aliases,
1298        reader_name,
1299        reader_namespace,
1300        reader_aliases,
1301    ) {
1302        Ok(())
1303    } else {
1304        Err(ArrowError::ParseError(format!(
1305            "{data_type} name mismatch writer={writer_name}, reader={reader_name}"
1306        )))
1307    }
1308}
1309
1310fn primitive_of(schema: &Schema) -> Option<PrimitiveType> {
1311    match schema {
1312        Schema::TypeName(TypeName::Primitive(primitive)) => Some(*primitive),
1313        Schema::Type(Type {
1314            r#type: TypeName::Primitive(primitive),
1315            ..
1316        }) => Some(*primitive),
1317        _ => None,
1318    }
1319}
1320
1321fn nullable_union_variants<'x, 'y>(
1322    variant: &'y [Schema<'x>],
1323) -> Option<(Nullability, &'y Schema<'x>)> {
1324    if variant.len() != 2 {
1325        return None;
1326    }
1327    let is_null = |schema: &Schema<'x>| {
1328        matches!(
1329            schema,
1330            Schema::TypeName(TypeName::Primitive(PrimitiveType::Null))
1331        )
1332    };
1333    match (is_null(&variant[0]), is_null(&variant[1])) {
1334        (true, false) => Some((Nullability::NullFirst, &variant[1])),
1335        (false, true) => Some((Nullability::NullSecond, &variant[0])),
1336        _ => None,
1337    }
1338}
1339
1340#[derive(Debug, Clone, PartialEq, Eq, Hash)]
1341enum UnionBranchKey {
1342    Named(String),
1343    Primitive(PrimitiveType),
1344    Array,
1345    Map,
1346}
1347
1348fn branch_key_of<'a>(s: &Schema<'a>, enclosing_ns: Option<&'a str>) -> Option<UnionBranchKey> {
1349    let (name, namespace) = match s {
1350        Schema::TypeName(TypeName::Primitive(p))
1351        | Schema::Type(Type {
1352            r#type: TypeName::Primitive(p),
1353            ..
1354        }) => return Some(UnionBranchKey::Primitive(*p)),
1355        Schema::TypeName(TypeName::Ref(name))
1356        | Schema::Type(Type {
1357            r#type: TypeName::Ref(name),
1358            ..
1359        }) => (name, None),
1360        Schema::Complex(ComplexType::Array(_)) => return Some(UnionBranchKey::Array),
1361        Schema::Complex(ComplexType::Map(_)) => return Some(UnionBranchKey::Map),
1362        Schema::Complex(ComplexType::Record(r)) => (&r.name, r.namespace),
1363        Schema::Complex(ComplexType::Enum(e)) => (&e.name, e.namespace),
1364        Schema::Complex(ComplexType::Fixed(f)) => (&f.name, f.namespace),
1365        Schema::Union(_) => return None,
1366    };
1367    let (full, _) = make_full_name(name, namespace, enclosing_ns);
1368    Some(UnionBranchKey::Named(full))
1369}
1370
1371fn union_first_duplicate<'a>(
1372    branches: &'a [Schema<'a>],
1373    enclosing_ns: Option<&'a str>,
1374) -> Option<String> {
1375    let mut seen = HashSet::with_capacity(branches.len());
1376    for schema in branches {
1377        if let Some(key) = branch_key_of(schema, enclosing_ns)
1378            && !seen.insert(key.clone())
1379        {
1380            let msg = match key {
1381                UnionBranchKey::Named(full) => format!("named type {full}"),
1382                UnionBranchKey::Primitive(p) => format!("primitive {}", p.as_ref()),
1383                UnionBranchKey::Array => "array".to_string(),
1384                UnionBranchKey::Map => "map".to_string(),
1385            };
1386            return Some(msg);
1387        }
1388    }
1389    None
1390}
1391
1392/// Resolves Avro type names to [`AvroDataType`]
1393///
1394/// See <https://avro.apache.org/docs/1.11.1/specification/#names>
1395struct Maker<'a> {
1396    resolver: Resolver<'a>,
1397    use_utf8view: bool,
1398    strict_mode: bool,
1399    tz: Tz,
1400}
1401
1402impl<'a> Maker<'a> {
1403    fn new(use_utf8view: bool, strict_mode: bool, tz: Tz) -> Self {
1404        Self {
1405            resolver: Default::default(),
1406            use_utf8view,
1407            strict_mode,
1408            tz,
1409        }
1410    }
1411
1412    #[cfg(feature = "avro_custom_types")]
1413    #[inline]
1414    fn propagate_nullability_into_ree(dt: &mut AvroDataType, nb: Nullability) {
1415        if let Codec::RunEndEncoded(values, bits) = dt.codec.clone() {
1416            let mut inner = (*values).clone();
1417            inner.nullability = Some(nb);
1418            dt.codec = Codec::RunEndEncoded(Arc::new(inner), bits);
1419        }
1420    }
1421
1422    fn make_data_type<'s>(
1423        &mut self,
1424        writer_schema: &'s Schema<'a>,
1425        reader_schema: Option<&'s Schema<'a>>,
1426        namespace: Option<&'a str>,
1427    ) -> Result<AvroDataType, ArrowError> {
1428        match reader_schema {
1429            Some(reader_schema) => self.resolve_type(writer_schema, reader_schema, namespace),
1430            None => self.parse_type(writer_schema, namespace),
1431        }
1432    }
1433
1434    /// Parses a [`AvroDataType`] from the provided `Schema` and the given `name` and `namespace`
1435    ///
1436    /// `name`: is the name used to refer to `schema` in its parent
1437    /// `namespace`: an optional qualifier used as part of a type hierarchy
1438    /// If the data type is a string, convert to use Utf8View if requested
1439    ///
1440    /// This function is used during the schema conversion process to determine whether
1441    /// string data should be represented as StringArray (default) or StringViewArray.
1442    ///
1443    /// `use_utf8view`: if true, use Utf8View instead of Utf8 for string types
1444    ///
1445    /// See [`Resolver`] for more information
1446    fn parse_type<'s>(
1447        &mut self,
1448        schema: &'s Schema<'a>,
1449        namespace: Option<&'a str>,
1450    ) -> Result<AvroDataType, ArrowError> {
1451        match schema {
1452            Schema::TypeName(TypeName::Primitive(p)) => Ok(AvroDataType::new(
1453                Codec::from(*p).with_utf8view(self.use_utf8view),
1454                Default::default(),
1455                None,
1456            )),
1457            Schema::TypeName(TypeName::Ref(name)) => self.resolver.resolve(name, namespace),
1458            Schema::Union(f) => {
1459                let null = f
1460                    .iter()
1461                    .position(|x| x == &Schema::TypeName(TypeName::Primitive(PrimitiveType::Null)));
1462                match (f.len() == 2, null) {
1463                    (true, Some(0)) => {
1464                        let mut field = self.parse_type(&f[1], namespace)?;
1465                        field.nullability = Some(Nullability::NullFirst);
1466                        #[cfg(feature = "avro_custom_types")]
1467                        Self::propagate_nullability_into_ree(&mut field, Nullability::NullFirst);
1468                        return Ok(field);
1469                    }
1470                    (true, Some(1)) => {
1471                        if self.strict_mode {
1472                            return Err(ArrowError::SchemaError(
1473                                "Found Avro union of the form ['T','null'], which is disallowed in strict_mode"
1474                                    .to_string(),
1475                            ));
1476                        }
1477                        let mut field = self.parse_type(&f[0], namespace)?;
1478                        field.nullability = Some(Nullability::NullSecond);
1479                        #[cfg(feature = "avro_custom_types")]
1480                        Self::propagate_nullability_into_ree(&mut field, Nullability::NullSecond);
1481                        return Ok(field);
1482                    }
1483                    _ => {}
1484                }
1485                // Validate: unions may not immediately contain unions
1486                if f.iter().any(|s| matches!(s, Schema::Union(_))) {
1487                    return Err(ArrowError::SchemaError(
1488                        "Avro unions may not immediately contain other unions".to_string(),
1489                    ));
1490                }
1491                // Validate: duplicates (named by full name; non-named by kind)
1492                if let Some(dup) = union_first_duplicate(f, namespace) {
1493                    return Err(ArrowError::SchemaError(format!(
1494                        "Avro union contains duplicate branch type: {dup}"
1495                    )));
1496                }
1497                // Parse all branches
1498                let children: Vec<AvroDataType> = f
1499                    .iter()
1500                    .map(|s| self.parse_type(s, namespace))
1501                    .collect::<Result<_, _>>()?;
1502                // Build Arrow layout once here
1503                let union_fields = build_union_fields(&children)?;
1504                Ok(AvroDataType::new(
1505                    Codec::Union(Arc::from(children), union_fields, UnionMode::Dense),
1506                    Default::default(),
1507                    None,
1508                ))
1509            }
1510            Schema::Complex(c) => match c {
1511                ComplexType::Record(r) => {
1512                    let namespace = named_type_namespace(r.name, r.namespace, namespace);
1513                    let mut metadata = r.attributes.field_metadata();
1514                    let fields = r
1515                        .fields
1516                        .iter()
1517                        .map(|field| {
1518                            Ok(AvroField {
1519                                name: field.name.to_string(),
1520                                data_type: self.parse_type(&field.r#type, namespace)?,
1521                            })
1522                        })
1523                        .collect::<Result<_, ArrowError>>()?;
1524                    metadata.insert(AVRO_NAME_METADATA_KEY.to_string(), r.name.to_string());
1525                    if let Some(ns) = namespace {
1526                        metadata.insert(AVRO_NAMESPACE_METADATA_KEY.to_string(), ns.to_string());
1527                    }
1528                    let field = AvroDataType {
1529                        nullability: None,
1530                        codec: Codec::Struct(fields),
1531                        metadata,
1532                        resolution: None,
1533                    };
1534                    self.resolver.register(r.name, namespace, field.clone());
1535                    Ok(field)
1536                }
1537                ComplexType::Array(a) => {
1538                    let field = self.parse_type(a.items.as_ref(), namespace)?;
1539                    Ok(AvroDataType {
1540                        nullability: None,
1541                        metadata: a.attributes.field_metadata(),
1542                        codec: Codec::List(Arc::new(field)),
1543                        resolution: None,
1544                    })
1545                }
1546                ComplexType::Fixed(f) => {
1547                    let size = f.size.try_into().map_err(|e| {
1548                        ArrowError::ParseError(format!("Overflow converting size to i32: {e}"))
1549                    })?;
1550                    let namespace = named_type_namespace(f.name, f.namespace, namespace);
1551                    let mut metadata = f.attributes.field_metadata();
1552                    metadata.insert(AVRO_NAME_METADATA_KEY.to_string(), f.name.to_string());
1553                    if let Some(ns) = namespace {
1554                        metadata.insert(AVRO_NAMESPACE_METADATA_KEY.to_string(), ns.to_string());
1555                    }
1556                    let field = match f.attributes.logical_type {
1557                        Some("decimal") => {
1558                            let (precision, scale, _) =
1559                                parse_decimal_attributes(&f.attributes, Some(size as usize), true)?;
1560                            AvroDataType {
1561                                nullability: None,
1562                                metadata,
1563                                codec: Codec::Decimal(precision, Some(scale), Some(size as usize)),
1564                                resolution: None,
1565                            }
1566                        }
1567                        Some("duration") => {
1568                            if size != 12 {
1569                                return Err(ArrowError::ParseError(format!(
1570                                    "Invalid fixed size for Duration: {size}, must be 12"
1571                                )));
1572                            }
1573                            AvroDataType {
1574                                nullability: None,
1575                                metadata,
1576                                codec: Codec::Interval,
1577                                resolution: None,
1578                            }
1579                        }
1580                        Some("uuid") => {
1581                            if size != 16 {
1582                                return Err(ArrowError::ParseError(format!(
1583                                    "Invalid fixed size for UUID: {size}, must be 16"
1584                                )));
1585                            }
1586                            metadata.insert("logicalType".into(), "uuid".into());
1587                            AvroDataType {
1588                                nullability: None,
1589                                metadata,
1590                                codec: Codec::Fixed(size),
1591                                resolution: None,
1592                            }
1593                        }
1594                        #[cfg(feature = "avro_custom_types")]
1595                        Some("arrow.uint64") if size == 8 => AvroDataType {
1596                            nullability: None,
1597                            metadata,
1598                            codec: Codec::UInt64,
1599                            resolution: None,
1600                        },
1601                        #[cfg(feature = "avro_custom_types")]
1602                        Some("arrow.float16") if size == 2 => AvroDataType {
1603                            nullability: None,
1604                            metadata,
1605                            codec: Codec::Float16,
1606                            resolution: None,
1607                        },
1608                        #[cfg(feature = "avro_custom_types")]
1609                        Some("arrow.interval-year-month") if size == 4 => AvroDataType {
1610                            nullability: None,
1611                            metadata,
1612                            codec: Codec::IntervalYearMonth,
1613                            resolution: None,
1614                        },
1615                        #[cfg(feature = "avro_custom_types")]
1616                        Some("arrow.interval-month-day-nano") if size == 16 => AvroDataType {
1617                            nullability: None,
1618                            metadata,
1619                            codec: Codec::IntervalMonthDayNano,
1620                            resolution: None,
1621                        },
1622                        #[cfg(feature = "avro_custom_types")]
1623                        Some("arrow.interval-day-time") if size == 8 => AvroDataType {
1624                            nullability: None,
1625                            metadata,
1626                            codec: Codec::IntervalDayTime,
1627                            resolution: None,
1628                        },
1629                        _ => AvroDataType {
1630                            nullability: None,
1631                            metadata,
1632                            codec: Codec::Fixed(size),
1633                            resolution: None,
1634                        },
1635                    };
1636                    self.resolver.register(f.name, namespace, field.clone());
1637                    Ok(field)
1638                }
1639                ComplexType::Enum(e) => {
1640                    let namespace = named_type_namespace(e.name, e.namespace, namespace);
1641                    let symbols = e
1642                        .symbols
1643                        .iter()
1644                        .map(|s| s.to_string())
1645                        .collect::<Arc<[String]>>();
1646                    let mut metadata = e.attributes.field_metadata();
1647                    let symbols_json = serde_json::to_string(&e.symbols).map_err(|e| {
1648                        ArrowError::ParseError(format!("Failed to serialize enum symbols: {e}"))
1649                    })?;
1650                    metadata.insert(AVRO_ENUM_SYMBOLS_METADATA_KEY.to_string(), symbols_json);
1651                    metadata.insert(AVRO_NAME_METADATA_KEY.to_string(), e.name.to_string());
1652                    if let Some(ns) = namespace {
1653                        metadata.insert(AVRO_NAMESPACE_METADATA_KEY.to_string(), ns.to_string());
1654                    }
1655                    let field = AvroDataType {
1656                        nullability: None,
1657                        metadata,
1658                        codec: Codec::Enum(symbols),
1659                        resolution: None,
1660                    };
1661                    self.resolver.register(e.name, namespace, field.clone());
1662                    Ok(field)
1663                }
1664                ComplexType::Map(m) => {
1665                    let val = self.parse_type(&m.values, namespace)?;
1666                    Ok(AvroDataType {
1667                        nullability: None,
1668                        metadata: m.attributes.field_metadata(),
1669                        codec: Codec::Map(Arc::new(val)),
1670                        resolution: None,
1671                    })
1672                }
1673            },
1674            Schema::Type(t) => {
1675                let mut field = self.parse_type(&Schema::TypeName(t.r#type.clone()), namespace)?;
1676                // https://avro.apache.org/docs/1.11.1/specification/#logical-types
1677                match (t.attributes.logical_type, &mut field.codec) {
1678                    (Some("decimal"), c @ Codec::Binary) => {
1679                        let (prec, sc, _) = parse_decimal_attributes(&t.attributes, None, false)?;
1680                        *c = Codec::Decimal(prec, Some(sc), None);
1681                    }
1682                    (Some("date"), c @ Codec::Int32) => *c = Codec::Date32,
1683                    (Some("time-millis"), c @ Codec::Int32) => *c = Codec::TimeMillis,
1684                    (Some("time-micros"), c @ Codec::Int64) => *c = Codec::TimeMicros,
1685                    (Some("timestamp-millis"), c @ Codec::Int64) => {
1686                        *c = Codec::TimestampMillis(Some(self.tz))
1687                    }
1688                    (Some("timestamp-micros"), c @ Codec::Int64) => {
1689                        *c = Codec::TimestampMicros(Some(self.tz))
1690                    }
1691                    (Some("local-timestamp-millis"), c @ Codec::Int64) => {
1692                        *c = Codec::TimestampMillis(None)
1693                    }
1694                    (Some("local-timestamp-micros"), c @ Codec::Int64) => {
1695                        *c = Codec::TimestampMicros(None)
1696                    }
1697                    (Some("timestamp-nanos"), c @ Codec::Int64) => {
1698                        *c = Codec::TimestampNanos(Some(self.tz))
1699                    }
1700                    (Some("local-timestamp-nanos"), c @ Codec::Int64) => {
1701                        *c = Codec::TimestampNanos(None)
1702                    }
1703                    (Some("uuid"), c @ Codec::Utf8) => {
1704                        // Map Avro string+logicalType=uuid into the UUID Codec,
1705                        // and preserve the logicalType in Arrow field metadata
1706                        // so writers can round-trip it correctly.
1707                        *c = Codec::Uuid;
1708                        field.metadata.insert("logicalType".into(), "uuid".into());
1709                    }
1710                    #[cfg(feature = "avro_custom_types")]
1711                    (Some("arrow.duration-nanos"), c @ Codec::Int64) => *c = Codec::DurationNanos,
1712                    #[cfg(feature = "avro_custom_types")]
1713                    (Some("arrow.duration-micros"), c @ Codec::Int64) => *c = Codec::DurationMicros,
1714                    #[cfg(feature = "avro_custom_types")]
1715                    (Some("arrow.duration-millis"), c @ Codec::Int64) => *c = Codec::DurationMillis,
1716                    #[cfg(feature = "avro_custom_types")]
1717                    (Some("arrow.duration-seconds"), c @ Codec::Int64) => {
1718                        *c = Codec::DurationSeconds
1719                    }
1720                    #[cfg(feature = "avro_custom_types")]
1721                    (Some("arrow.run-end-encoded"), _) => {
1722                        let bits_u8: u8 = t
1723                            .attributes
1724                            .additional
1725                            .get("arrow.runEndIndexBits")
1726                            .and_then(|v| v.as_u64())
1727                            .and_then(|n| u8::try_from(n).ok())
1728                            .ok_or_else(|| ArrowError::ParseError(
1729                                "arrow.run-end-encoded requires 'arrow.runEndIndexBits' (one of 16, 32, or 64)"
1730                                    .to_string(),
1731                            ))?;
1732                        if bits_u8 != 16 && bits_u8 != 32 && bits_u8 != 64 {
1733                            return Err(ArrowError::ParseError(format!(
1734                                "Invalid 'arrow.runEndIndexBits' value {bits_u8}; must be 16, 32, or 64"
1735                            )));
1736                        }
1737                        // Wrap the parsed underlying site as REE
1738                        let values_site = field.clone();
1739                        field.codec = Codec::RunEndEncoded(Arc::new(values_site), bits_u8);
1740                    }
1741                    // Arrow-specific integer width types
1742                    #[cfg(feature = "avro_custom_types")]
1743                    (Some("arrow.int8"), c @ Codec::Int32) => *c = Codec::Int8,
1744                    #[cfg(feature = "avro_custom_types")]
1745                    (Some("arrow.int16"), c @ Codec::Int32) => *c = Codec::Int16,
1746                    #[cfg(feature = "avro_custom_types")]
1747                    (Some("arrow.uint8"), c @ Codec::Int32) => *c = Codec::UInt8,
1748                    #[cfg(feature = "avro_custom_types")]
1749                    (Some("arrow.uint16"), c @ Codec::Int32) => *c = Codec::UInt16,
1750                    #[cfg(feature = "avro_custom_types")]
1751                    (Some("arrow.uint32"), c @ Codec::Int64) => *c = Codec::UInt32,
1752                    #[cfg(feature = "avro_custom_types")]
1753                    (Some("arrow.uint64"), c @ Codec::Fixed(8)) => *c = Codec::UInt64,
1754                    // Arrow Float16 stored as fixed(2)
1755                    #[cfg(feature = "avro_custom_types")]
1756                    (Some("arrow.float16"), c @ Codec::Fixed(2)) => *c = Codec::Float16,
1757                    // Arrow Date64 custom type
1758                    #[cfg(feature = "avro_custom_types")]
1759                    (Some("arrow.date64"), c @ Codec::Int64) => *c = Codec::Date64,
1760                    // Arrow time/timestamp types with second precision
1761                    #[cfg(feature = "avro_custom_types")]
1762                    (Some("arrow.time64-nanosecond"), c @ Codec::Int64) => *c = Codec::TimeNanos,
1763                    #[cfg(feature = "avro_custom_types")]
1764                    (Some("arrow.time32-second"), c @ Codec::Int32) => *c = Codec::Time32Secs,
1765                    #[cfg(feature = "avro_custom_types")]
1766                    (Some("arrow.timestamp-second"), c @ Codec::Int64) => {
1767                        *c = Codec::TimestampSecs(true)
1768                    }
1769                    #[cfg(feature = "avro_custom_types")]
1770                    (Some("arrow.local-timestamp-second"), c @ Codec::Int64) => {
1771                        *c = Codec::TimestampSecs(false)
1772                    }
1773                    // Arrow interval types
1774                    #[cfg(feature = "avro_custom_types")]
1775                    (Some("arrow.interval-year-month"), c @ Codec::Fixed(4)) => {
1776                        *c = Codec::IntervalYearMonth
1777                    }
1778                    #[cfg(feature = "avro_custom_types")]
1779                    (Some("arrow.interval-month-day-nano"), c @ Codec::Fixed(16)) => {
1780                        *c = Codec::IntervalMonthDayNano
1781                    }
1782                    #[cfg(feature = "avro_custom_types")]
1783                    (Some("arrow.interval-day-time"), c @ Codec::Fixed(8)) => {
1784                        *c = Codec::IntervalDayTime
1785                    }
1786                    (Some(logical), _) => {
1787                        // Insert unrecognized logical type into metadata map
1788                        field.metadata.insert("logicalType".into(), logical.into());
1789                    }
1790                    (None, _) => {}
1791                }
1792                if matches!(field.codec, Codec::Int64)
1793                    && let Some(unit) = t
1794                        .attributes
1795                        .additional
1796                        .get("arrowTimeUnit")
1797                        .and_then(|v| v.as_str())
1798                    && unit == "nanosecond"
1799                {
1800                    field.codec = Codec::TimestampNanos(Some(self.tz));
1801                }
1802                if !t.attributes.additional.is_empty() {
1803                    for (k, v) in &t.attributes.additional {
1804                        field.metadata.insert(k.to_string(), v.to_string());
1805                    }
1806                }
1807                Ok(field)
1808            }
1809        }
1810    }
1811
1812    fn resolve_type<'s>(
1813        &mut self,
1814        writer_schema: &'s Schema<'a>,
1815        reader_schema: &'s Schema<'a>,
1816        namespace: Option<&'a str>,
1817    ) -> Result<AvroDataType, ArrowError> {
1818        if let (Some(write_primitive), Some(read_primitive)) =
1819            (primitive_of(writer_schema), primitive_of(reader_schema))
1820        {
1821            return self.resolve_primitives(write_primitive, read_primitive, reader_schema);
1822        }
1823        match (writer_schema, reader_schema) {
1824            (Schema::Union(writer_variants), Schema::Union(reader_variants)) => {
1825                let writer_variants = writer_variants.as_slice();
1826                let reader_variants = reader_variants.as_slice();
1827                match (
1828                    nullable_union_variants(writer_variants),
1829                    nullable_union_variants(reader_variants),
1830                ) {
1831                    (Some((w_nb, w_nonnull)), Some((r_nb, r_nonnull))) => {
1832                        let mut dt = self.resolve_type(w_nonnull, r_nonnull, namespace)?;
1833                        let mut writer_to_reader = vec![None, None];
1834                        writer_to_reader[w_nb.non_null_index()] = Some((
1835                            r_nb.non_null_index(),
1836                            dt.resolution
1837                                .take()
1838                                .unwrap_or(ResolutionInfo::Promotion(Promotion::Direct)),
1839                        ));
1840                        dt.nullability = Some(w_nb);
1841                        dt.resolution = Some(ResolutionInfo::Union(ResolvedUnion {
1842                            writer_to_reader: Arc::from(writer_to_reader),
1843                            writer_is_union: true,
1844                            reader_is_union: true,
1845                        }));
1846                        #[cfg(feature = "avro_custom_types")]
1847                        Self::propagate_nullability_into_ree(&mut dt, w_nb);
1848                        Ok(dt)
1849                    }
1850                    _ => self.resolve_unions(writer_variants, reader_variants, namespace),
1851                }
1852            }
1853            (Schema::Union(writer_variants), reader_non_union) => {
1854                let writer_to_reader: Vec<Option<(usize, ResolutionInfo)>> = writer_variants
1855                    .iter()
1856                    .map(|writer| {
1857                        self.resolve_type(writer, reader_non_union, namespace)
1858                            .ok()
1859                            .map(|tmp| {
1860                                let resolution = tmp
1861                                    .resolution
1862                                    .unwrap_or(ResolutionInfo::Promotion(Promotion::Direct));
1863                                (0usize, resolution)
1864                            })
1865                    })
1866                    .collect();
1867                let mut dt = self.parse_type(reader_non_union, namespace)?;
1868                dt.resolution = Some(ResolutionInfo::Union(ResolvedUnion {
1869                    writer_to_reader: Arc::from(writer_to_reader),
1870                    writer_is_union: true,
1871                    reader_is_union: false,
1872                }));
1873                Ok(dt)
1874            }
1875            (writer_non_union, Schema::Union(reader_variants)) => {
1876                if let Some((nullability, non_null_branch)) =
1877                    nullable_union_variants(reader_variants)
1878                {
1879                    let mut dt = self.resolve_type(writer_non_union, non_null_branch, namespace)?;
1880                    #[cfg(feature = "avro_custom_types")]
1881                    Self::propagate_nullability_into_ree(&mut dt, nullability);
1882                    dt.nullability = Some(nullability);
1883                    // Ensure resolution is set to a non-Union variant to suppress
1884                    // reading the union tag which is the default behavior.
1885                    if dt.resolution.is_none() {
1886                        dt.resolution = Some(ResolutionInfo::Promotion(Promotion::Direct));
1887                    }
1888                    Ok(dt)
1889                } else {
1890                    let Some((match_idx, mut match_dt)) =
1891                        self.find_best_union_match(writer_non_union, reader_variants, namespace)
1892                    else {
1893                        return Err(ArrowError::SchemaError(
1894                            "Writer schema does not match any reader union branch".to_string(),
1895                        ));
1896                    };
1897                    // Steal the resolution info from the matching reader branch
1898                    // for the Union resolution, but preserve possible resolution
1899                    // information on its inner types.
1900                    // For other branches, resolution is irrelevant,
1901                    // so just parse them.
1902                    let resolution = match_dt
1903                        .resolution
1904                        .take()
1905                        .unwrap_or(ResolutionInfo::Promotion(Promotion::Direct));
1906                    let mut match_dt = Some(match_dt);
1907                    let children = reader_variants
1908                        .iter()
1909                        .enumerate()
1910                        .map(|(idx, variant)| {
1911                            if idx == match_idx {
1912                                Ok(match_dt.take().unwrap())
1913                            } else {
1914                                self.parse_type(variant, namespace)
1915                            }
1916                        })
1917                        .collect::<Result<Vec<_>, _>>()?;
1918                    let union_fields = build_union_fields(&children)?;
1919                    let mut dt = AvroDataType::new(
1920                        Codec::Union(children.into(), union_fields, UnionMode::Dense),
1921                        Default::default(),
1922                        None,
1923                    );
1924                    dt.resolution = Some(ResolutionInfo::Union(ResolvedUnion {
1925                        writer_to_reader: Arc::from(vec![Some((match_idx, resolution))]),
1926                        writer_is_union: false,
1927                        reader_is_union: true,
1928                    }));
1929                    Ok(dt)
1930                }
1931            }
1932            (
1933                Schema::Complex(ComplexType::Array(writer_array)),
1934                Schema::Complex(ComplexType::Array(reader_array)),
1935            ) => self.resolve_array(writer_array, reader_array, namespace),
1936            (
1937                Schema::Complex(ComplexType::Map(writer_map)),
1938                Schema::Complex(ComplexType::Map(reader_map)),
1939            ) => self.resolve_map(writer_map, reader_map, namespace),
1940            (
1941                Schema::Complex(ComplexType::Fixed(writer_fixed)),
1942                Schema::Complex(ComplexType::Fixed(reader_fixed)),
1943            ) => self.resolve_fixed(writer_fixed, reader_fixed, reader_schema, namespace),
1944            (
1945                Schema::Complex(ComplexType::Record(writer_record)),
1946                Schema::Complex(ComplexType::Record(reader_record)),
1947            ) => self.resolve_records(writer_record, reader_record, namespace),
1948            (
1949                Schema::Complex(ComplexType::Enum(writer_enum)),
1950                Schema::Complex(ComplexType::Enum(reader_enum)),
1951            ) => self.resolve_enums(writer_enum, reader_enum, reader_schema, namespace),
1952            (Schema::TypeName(TypeName::Ref(_)), _) => self.parse_type(reader_schema, namespace),
1953            (_, Schema::TypeName(TypeName::Ref(_))) => self.parse_type(reader_schema, namespace),
1954            _ => Err(ArrowError::NotYetImplemented(
1955                "Other resolutions not yet implemented".to_string(),
1956            )),
1957        }
1958    }
1959
1960    fn find_best_union_match(
1961        &mut self,
1962        writer: &Schema<'a>,
1963        reader_variants: &[Schema<'a>],
1964        namespace: Option<&'a str>,
1965    ) -> Option<(usize, AvroDataType)> {
1966        let mut first_resolution = None;
1967        for (reader_index, reader) in reader_variants.iter().enumerate() {
1968            if let Ok(dt) = self.resolve_type(writer, reader, namespace) {
1969                match &dt.resolution {
1970                    None | Some(ResolutionInfo::Promotion(Promotion::Direct)) => {
1971                        // An exact match is best, return immediately.
1972                        return Some((reader_index, dt));
1973                    }
1974                    Some(_) => {
1975                        if first_resolution.is_none() {
1976                            // Store the first valid promotion but keep searching for a direct match.
1977                            first_resolution = Some((reader_index, dt));
1978                        }
1979                    }
1980                }
1981            }
1982        }
1983        first_resolution
1984    }
1985
1986    fn resolve_unions<'s>(
1987        &mut self,
1988        writer_variants: &'s [Schema<'a>],
1989        reader_variants: &'s [Schema<'a>],
1990        namespace: Option<&'a str>,
1991    ) -> Result<AvroDataType, ArrowError> {
1992        let mut resolved_reader_encodings = HashMap::new();
1993        let writer_to_reader: Vec<Option<(usize, ResolutionInfo)>> = writer_variants
1994            .iter()
1995            .map(|writer| {
1996                self.find_best_union_match(writer, reader_variants, namespace)
1997                    .map(|(match_idx, mut match_dt)| {
1998                        let resolution = match_dt
1999                            .resolution
2000                            .take()
2001                            .unwrap_or(ResolutionInfo::Promotion(Promotion::Direct));
2002                        // TODO: check for overlapping reader variants?
2003                        // They should not be possible in a valid schema.
2004                        resolved_reader_encodings.insert(match_idx, match_dt);
2005                        (match_idx, resolution)
2006                    })
2007            })
2008            .collect();
2009        let reader_encodings: Vec<AvroDataType> = reader_variants
2010            .iter()
2011            .enumerate()
2012            .map(|(reader_idx, reader_schema)| {
2013                if let Some(resolved) = resolved_reader_encodings.remove(&reader_idx) {
2014                    Ok(resolved)
2015                } else {
2016                    self.parse_type(reader_schema, namespace)
2017                }
2018            })
2019            .collect::<Result<_, _>>()?;
2020        let union_fields = build_union_fields(&reader_encodings)?;
2021        let mut dt = AvroDataType::new(
2022            Codec::Union(reader_encodings.into(), union_fields, UnionMode::Dense),
2023            Default::default(),
2024            None,
2025        );
2026        dt.resolution = Some(ResolutionInfo::Union(ResolvedUnion {
2027            writer_to_reader: Arc::from(writer_to_reader),
2028            writer_is_union: true,
2029            reader_is_union: true,
2030        }));
2031        Ok(dt)
2032    }
2033
2034    fn resolve_array(
2035        &mut self,
2036        writer_array: &Array<'a>,
2037        reader_array: &Array<'a>,
2038        namespace: Option<&'a str>,
2039    ) -> Result<AvroDataType, ArrowError> {
2040        Ok(AvroDataType {
2041            nullability: None,
2042            metadata: reader_array.attributes.field_metadata(),
2043            codec: Codec::List(Arc::new(self.make_data_type(
2044                writer_array.items.as_ref(),
2045                Some(reader_array.items.as_ref()),
2046                namespace,
2047            )?)),
2048            resolution: None,
2049        })
2050    }
2051
2052    fn resolve_map(
2053        &mut self,
2054        writer_map: &Map<'a>,
2055        reader_map: &Map<'a>,
2056        namespace: Option<&'a str>,
2057    ) -> Result<AvroDataType, ArrowError> {
2058        Ok(AvroDataType {
2059            nullability: None,
2060            metadata: reader_map.attributes.field_metadata(),
2061            codec: Codec::Map(Arc::new(self.make_data_type(
2062                &writer_map.values,
2063                Some(&reader_map.values),
2064                namespace,
2065            )?)),
2066            resolution: None,
2067        })
2068    }
2069
2070    fn resolve_fixed<'s>(
2071        &mut self,
2072        writer_fixed: &Fixed<'a>,
2073        reader_fixed: &Fixed<'a>,
2074        reader_schema: &'s Schema<'a>,
2075        namespace: Option<&'a str>,
2076    ) -> Result<AvroDataType, ArrowError> {
2077        ensure_names_match(
2078            "Fixed",
2079            writer_fixed.name,
2080            writer_fixed.namespace,
2081            &writer_fixed.aliases,
2082            reader_fixed.name,
2083            reader_fixed.namespace,
2084            &reader_fixed.aliases,
2085        )?;
2086        if writer_fixed.size != reader_fixed.size {
2087            return Err(ArrowError::SchemaError(format!(
2088                "Fixed size mismatch for {}: writer={}, reader={}",
2089                reader_fixed.name, writer_fixed.size, reader_fixed.size
2090            )));
2091        }
2092        self.parse_type(reader_schema, namespace)
2093    }
2094
2095    fn resolve_primitives(
2096        &mut self,
2097        write_primitive: PrimitiveType,
2098        read_primitive: PrimitiveType,
2099        reader_schema: &Schema<'a>,
2100    ) -> Result<AvroDataType, ArrowError> {
2101        if write_primitive == read_primitive {
2102            return self.parse_type(reader_schema, None);
2103        }
2104        let promotion = match (write_primitive, read_primitive) {
2105            (PrimitiveType::Int, PrimitiveType::Long) => Promotion::IntToLong,
2106            (PrimitiveType::Int, PrimitiveType::Float) => Promotion::IntToFloat,
2107            (PrimitiveType::Int, PrimitiveType::Double) => Promotion::IntToDouble,
2108            (PrimitiveType::Long, PrimitiveType::Float) => Promotion::LongToFloat,
2109            (PrimitiveType::Long, PrimitiveType::Double) => Promotion::LongToDouble,
2110            (PrimitiveType::Float, PrimitiveType::Double) => Promotion::FloatToDouble,
2111            (PrimitiveType::String, PrimitiveType::Bytes) => Promotion::StringToBytes,
2112            (PrimitiveType::Bytes, PrimitiveType::String) => Promotion::BytesToString,
2113            _ => {
2114                return Err(ArrowError::ParseError(format!(
2115                    "Illegal promotion {write_primitive:?} to {read_primitive:?}"
2116                )));
2117            }
2118        };
2119        let mut datatype = self.parse_type(reader_schema, None)?;
2120        datatype.resolution = Some(ResolutionInfo::Promotion(promotion));
2121        Ok(datatype)
2122    }
2123
2124    // Resolve writer vs. reader enum schemas according to Avro 1.11.1.
2125    //
2126    // # How enums resolve (writer to reader)
2127    // Per “Schema Resolution”:
2128    // * The two schemas must refer to the same (unqualified) enum name (or match
2129    //   via alias rewriting).
2130    // * If the writer’s symbol is not present in the reader’s enum and the reader
2131    //   enum has a `default`, that `default` symbol must be used; otherwise,
2132    //   error.
2133    //   https://avro.apache.org/docs/1.11.1/specification/#schema-resolution
2134    // * Avro “Aliases” are applied from the reader side to rewrite the writer’s
2135    //   names during resolution. For robustness across ecosystems, we also accept
2136    //   symmetry here (see note below).
2137    //   https://avro.apache.org/docs/1.11.1/specification/#aliases
2138    //
2139    // # Rationale for this code path
2140    // 1. Do the work once at schema‑resolution time. Avro serializes an enum as a
2141    //    writer‑side position. Mapping positions on the hot decoder path is expensive
2142    //    if done with string lookups. This method builds a `writer_index to reader_index`
2143    //    vector once, so decoding just does an O(1) table lookup.
2144    // 2. Adopt the reader’s symbol set and order. We return an Arrow
2145    //    `Dictionary(Int32, Utf8)` whose dictionary values are the reader enum
2146    //    symbols. This makes downstream semantics match the reader schema, including
2147    //    Avro’s sort order rule that orders enums by symbol position in the schema.
2148    //    https://avro.apache.org/docs/1.11.1/specification/#sort-order
2149    // 3. Honor Avro’s `default` for enums. Avro 1.9+ allows a type‑level default
2150    //    on the enum. When the writer emits a symbol unknown to the reader, we map it
2151    //    to the reader’s validated `default` symbol if present; otherwise we signal an
2152    //    error at decoding time.
2153    //    https://avro.apache.org/docs/1.11.1/specification/#enums
2154    //
2155    // # Implementation notes
2156    // * We first check that enum names match or are*alias‑equivalent. The Avro
2157    //   spec describes alias rewriting using reader aliases; this implementation
2158    //   additionally treats writer aliases as acceptable for name matching to be
2159    //   resilient with schemas produced by different tooling.
2160    // * We build `EnumMapping`:
2161    //   - `mapping[i]` = reader index of the writer symbol at writer index `i`.
2162    //   - If the writer symbol is absent and the reader has a default, we store the
2163    //     reader index of that default.
2164    //   - Otherwise we store `-1` as a sentinel meaning unresolvable; the decoder
2165    //     must treat encountering such a value as an error, per the spec.
2166    // * We persist the reader symbol list in field metadata under
2167    //   `AVRO_ENUM_SYMBOLS_METADATA_KEY`, so consumers can inspect the dictionary
2168    //   without needing the original Avro schema.
2169    // * The Arrow representation is `Dictionary(Int32, Utf8)`, which aligns with
2170    //   Avro’s integer index encoding for enums.
2171    //
2172    // # Examples
2173    // * Writer `["A","B","C"]`, Reader `["A","B"]`, Reader default `"A"`
2174    //     `mapping = [0, 1, 0]`, `default_index = 0`.
2175    // * Writer `["A","B"]`, Reader `["B","A"]` (no default)
2176    //     `mapping = [1, 0]`, `default_index = -1`.
2177    // * Writer `["A","B","C"]`, Reader `["A","B"]` (no default)
2178    //     `mapping = [0, 1, -1]` (decode must error on `"C"`).
2179    fn resolve_enums(
2180        &mut self,
2181        writer_enum: &Enum<'a>,
2182        reader_enum: &Enum<'a>,
2183        reader_schema: &Schema<'a>,
2184        namespace: Option<&'a str>,
2185    ) -> Result<AvroDataType, ArrowError> {
2186        ensure_names_match(
2187            "Enum",
2188            writer_enum.name,
2189            writer_enum.namespace,
2190            &writer_enum.aliases,
2191            reader_enum.name,
2192            reader_enum.namespace,
2193            &reader_enum.aliases,
2194        )?;
2195        if writer_enum.symbols == reader_enum.symbols {
2196            return self.parse_type(reader_schema, namespace);
2197        }
2198        let reader_index: HashMap<&str, i32> = reader_enum
2199            .symbols
2200            .iter()
2201            .enumerate()
2202            .map(|(index, &symbol)| (symbol, index as i32))
2203            .collect();
2204        let default_index: i32 = match reader_enum.default {
2205            Some(symbol) => *reader_index.get(symbol).ok_or_else(|| {
2206                ArrowError::SchemaError(format!(
2207                    "Reader enum '{}' default symbol '{symbol}' not found in symbols list",
2208                    reader_enum.name,
2209                ))
2210            })?,
2211            None => -1,
2212        };
2213        let mapping: Vec<i32> = writer_enum
2214            .symbols
2215            .iter()
2216            .map(|&write_symbol| {
2217                reader_index
2218                    .get(write_symbol)
2219                    .copied()
2220                    .unwrap_or(default_index)
2221            })
2222            .collect();
2223        if self.strict_mode && mapping.iter().any(|&m| m < 0) {
2224            return Err(ArrowError::SchemaError(format!(
2225                "Reader enum '{}' does not cover all writer symbols and no default is provided",
2226                reader_enum.name
2227            )));
2228        }
2229        let mut dt = self.parse_type(reader_schema, namespace)?;
2230        dt.resolution = Some(ResolutionInfo::EnumMapping(EnumMapping {
2231            mapping: Arc::from(mapping),
2232            default_index,
2233        }));
2234        let reader_ns = named_type_namespace(reader_enum.name, reader_enum.namespace, namespace);
2235        self.resolver
2236            .register(reader_enum.name, reader_ns, dt.clone());
2237        Ok(dt)
2238    }
2239
2240    #[inline]
2241    fn build_writer_lookup(
2242        writer_record: &Record<'a>,
2243    ) -> (HashMap<&'a str, usize>, HashSet<&'a str>) {
2244        let mut map: HashMap<&str, usize> = HashMap::with_capacity(writer_record.fields.len() * 2);
2245        for (idx, wf) in writer_record.fields.iter().enumerate() {
2246            // Avro field names are unique; last-in wins are acceptable and match previous behavior.
2247            map.insert(wf.name, idx);
2248        }
2249        // Track ambiguous writer aliases (alias used by multiple writer fields)
2250        let mut ambiguous: HashSet<&str> = HashSet::new();
2251        for (idx, wf) in writer_record.fields.iter().enumerate() {
2252            for &alias in &wf.aliases {
2253                match map.entry(alias) {
2254                    Entry::Occupied(e) if *e.get() != idx => {
2255                        ambiguous.insert(alias);
2256                    }
2257                    Entry::Vacant(e) => {
2258                        e.insert(idx);
2259                    }
2260                    Entry::Occupied(_) => {}
2261                }
2262            }
2263        }
2264        (map, ambiguous)
2265    }
2266
2267    fn resolve_records(
2268        &mut self,
2269        writer_record: &Record<'a>,
2270        reader_record: &Record<'a>,
2271        namespace: Option<&'a str>,
2272    ) -> Result<AvroDataType, ArrowError> {
2273        ensure_names_match(
2274            "Record",
2275            writer_record.name,
2276            writer_record.namespace,
2277            &writer_record.aliases,
2278            reader_record.name,
2279            reader_record.namespace,
2280            &reader_record.aliases,
2281        )?;
2282        let writer_ns =
2283            named_type_namespace(writer_record.name, writer_record.namespace, namespace);
2284        let reader_ns =
2285            named_type_namespace(reader_record.name, reader_record.namespace, namespace);
2286        let mut reader_md = reader_record.attributes.field_metadata();
2287        reader_md.insert(
2288            AVRO_NAME_METADATA_KEY.to_string(),
2289            reader_record.name.to_string(),
2290        );
2291        if let Some(ns) = reader_ns {
2292            reader_md.insert(AVRO_NAMESPACE_METADATA_KEY.to_string(), ns.to_string());
2293        }
2294        // Build writer lookup and ambiguous alias set.
2295        let (writer_lookup, ambiguous_writer_aliases) = Self::build_writer_lookup(writer_record);
2296        let mut writer_to_reader: Vec<Option<usize>> = vec![None; writer_record.fields.len()];
2297        let mut reader_fields: Vec<AvroField> = Vec::with_capacity(reader_record.fields.len());
2298        // Capture default field indices during the main loop (one pass).
2299        let mut default_fields: Vec<usize> = Vec::new();
2300        for (reader_idx, r_field) in reader_record.fields.iter().enumerate() {
2301            // Direct name match, then reader aliases (a writer alias map is pre-populated).
2302            let mut match_idx = writer_lookup.get(r_field.name).copied();
2303            let mut matched_via_alias: Option<&str> = None;
2304            if match_idx.is_none() {
2305                for &alias in &r_field.aliases {
2306                    if let Some(i) = writer_lookup.get(alias).copied() {
2307                        if self.strict_mode && ambiguous_writer_aliases.contains(alias) {
2308                            return Err(ArrowError::SchemaError(format!(
2309                                "Ambiguous alias '{alias}' on reader field '{}' matches multiple writer fields",
2310                                r_field.name
2311                            )));
2312                        }
2313                        match_idx = Some(i);
2314                        matched_via_alias = Some(alias);
2315                        break;
2316                    }
2317                }
2318            }
2319            if let Some(wi) = match_idx {
2320                if writer_to_reader[wi].is_none() {
2321                    let w_schema = &writer_record.fields[wi].r#type;
2322                    let dt = self.make_data_type(w_schema, Some(&r_field.r#type), reader_ns)?;
2323                    writer_to_reader[wi] = Some(reader_idx);
2324                    reader_fields.push(AvroField {
2325                        name: r_field.name.to_owned(),
2326                        data_type: dt,
2327                    });
2328                    continue;
2329                } else if self.strict_mode {
2330                    // Writer field already mapped and strict_mode => error
2331                    let existing_reader = writer_to_reader[wi].unwrap();
2332                    let via = matched_via_alias
2333                        .map(|a| format!("alias '{a}'"))
2334                        .unwrap_or_else(|| "name match".to_string());
2335                    return Err(ArrowError::SchemaError(format!(
2336                        "Multiple reader fields map to the same writer field '{}' via {via} (existing reader index {existing_reader}, new reader index {reader_idx})",
2337                        writer_record.fields[wi].name
2338                    )));
2339                }
2340                // Non-strict and already mapped -> fall through to defaulting logic
2341            }
2342            // No match (or conflicted in non-strict mode): attach default per Avro spec.
2343            let mut dt = self.parse_type(&r_field.r#type, reader_ns)?;
2344            if let Some(default_json) = r_field.default.as_ref() {
2345                dt.resolution = Some(ResolutionInfo::DefaultValue(
2346                    dt.parse_and_store_default(default_json)?,
2347                ));
2348                default_fields.push(reader_idx);
2349            } else if dt.nullability() == Some(Nullability::NullFirst) {
2350                // The only valid implicit default for a union is the first branch (null-first case).
2351                dt.resolution = Some(ResolutionInfo::DefaultValue(
2352                    dt.parse_and_store_default(&Value::Null)?,
2353                ));
2354                default_fields.push(reader_idx);
2355            } else {
2356                return Err(ArrowError::SchemaError(format!(
2357                    "Reader field '{}' not present in writer schema must have a default value",
2358                    r_field.name
2359                )));
2360            }
2361            reader_fields.push(AvroField {
2362                name: r_field.name.to_owned(),
2363                data_type: dt,
2364            });
2365        }
2366        // Build writer field map.
2367        let writer_fields = writer_record
2368            .fields
2369            .iter()
2370            .enumerate()
2371            .map(|(writer_index, writer_field)| {
2372                let dt = self.parse_type(&writer_field.r#type, writer_ns)?;
2373                if let Some(reader_index) = writer_to_reader[writer_index] {
2374                    Ok(ResolvedField::ToReader(reader_index, dt))
2375                } else {
2376                    Ok(ResolvedField::Skip(dt))
2377                }
2378            })
2379            .collect::<Result<_, ArrowError>>()?;
2380        let resolved = AvroDataType::new_with_resolution(
2381            Codec::Struct(Arc::from(reader_fields)),
2382            reader_md,
2383            None,
2384            Some(ResolutionInfo::Record(ResolvedRecord {
2385                writer_fields,
2386                default_fields: Arc::from(default_fields),
2387            })),
2388        );
2389        // Register a resolved record by reader name+namespace for potential named type refs.
2390        self.resolver
2391            .register(reader_record.name, reader_ns, resolved.clone());
2392        Ok(resolved)
2393    }
2394}
2395
2396#[cfg(test)]
2397mod tests {
2398    use super::*;
2399    use crate::schema::{
2400        AVRO_ROOT_RECORD_DEFAULT_NAME, Array, Attributes, ComplexType, Field as AvroFieldSchema,
2401        Fixed, PrimitiveType, Record, Schema, Type, TypeName,
2402    };
2403    use indexmap::IndexMap;
2404    use serde_json::{self, Value};
2405
2406    fn create_schema_with_logical_type(
2407        primitive_type: PrimitiveType,
2408        logical_type: &'static str,
2409    ) -> Schema<'static> {
2410        let attributes = Attributes {
2411            logical_type: Some(logical_type),
2412            additional: Default::default(),
2413        };
2414
2415        Schema::Type(Type {
2416            r#type: TypeName::Primitive(primitive_type),
2417            attributes,
2418        })
2419    }
2420
2421    fn resolve_promotion(writer: PrimitiveType, reader: PrimitiveType) -> AvroDataType {
2422        let writer_schema = Schema::TypeName(TypeName::Primitive(writer));
2423        let reader_schema = Schema::TypeName(TypeName::Primitive(reader));
2424        let mut maker = Maker::new(false, false, Tz::default());
2425        maker
2426            .make_data_type(&writer_schema, Some(&reader_schema), None)
2427            .expect("promotion should resolve")
2428    }
2429
2430    fn mk_primitive(pt: PrimitiveType) -> Schema<'static> {
2431        Schema::TypeName(TypeName::Primitive(pt))
2432    }
2433    fn mk_union(branches: Vec<Schema<'_>>) -> Schema<'_> {
2434        Schema::Union(branches)
2435    }
2436
2437    #[test]
2438    fn test_date_logical_type() {
2439        let schema = create_schema_with_logical_type(PrimitiveType::Int, "date");
2440
2441        let mut maker = Maker::new(false, false, Tz::default());
2442        let result = maker.make_data_type(&schema, None, None).unwrap();
2443
2444        assert!(matches!(result.codec, Codec::Date32));
2445    }
2446
2447    #[test]
2448    fn test_time_millis_logical_type() {
2449        let schema = create_schema_with_logical_type(PrimitiveType::Int, "time-millis");
2450
2451        let mut maker = Maker::new(false, false, Tz::default());
2452        let result = maker.make_data_type(&schema, None, None).unwrap();
2453
2454        assert!(matches!(result.codec, Codec::TimeMillis));
2455    }
2456
2457    #[test]
2458    fn test_time_micros_logical_type() {
2459        let schema = create_schema_with_logical_type(PrimitiveType::Long, "time-micros");
2460
2461        let mut maker = Maker::new(false, false, Tz::default());
2462        let result = maker.make_data_type(&schema, None, None).unwrap();
2463
2464        assert!(matches!(result.codec, Codec::TimeMicros));
2465    }
2466
2467    #[test]
2468    fn test_timestamp_millis_logical_type() {
2469        for tz in [Tz::OffsetZero, Tz::Utc] {
2470            let schema = create_schema_with_logical_type(PrimitiveType::Long, "timestamp-millis");
2471
2472            let mut maker = Maker::new(false, false, tz);
2473            let result = maker.make_data_type(&schema, None, None).unwrap();
2474
2475            let Codec::TimestampMillis(Some(actual_tz)) = result.codec else {
2476                panic!("Expected TimestampMillis codec");
2477            };
2478            assert_eq!(actual_tz, tz);
2479        }
2480    }
2481
2482    #[test]
2483    fn test_timestamp_micros_logical_type() {
2484        for tz in [Tz::OffsetZero, Tz::Utc] {
2485            let schema = create_schema_with_logical_type(PrimitiveType::Long, "timestamp-micros");
2486
2487            let mut maker = Maker::new(false, false, tz);
2488            let result = maker.make_data_type(&schema, None, None).unwrap();
2489
2490            let Codec::TimestampMicros(Some(actual_tz)) = result.codec else {
2491                panic!("Expected TimestampMicros codec");
2492            };
2493            assert_eq!(actual_tz, tz);
2494        }
2495    }
2496
2497    #[test]
2498    fn test_timestamp_nanos_logical_type() {
2499        for tz in [Tz::OffsetZero, Tz::Utc] {
2500            let schema = create_schema_with_logical_type(PrimitiveType::Long, "timestamp-nanos");
2501
2502            let mut maker = Maker::new(false, false, tz);
2503            let result = maker.make_data_type(&schema, None, None).unwrap();
2504
2505            let Codec::TimestampNanos(Some(actual_tz)) = result.codec else {
2506                panic!("Expected TimestampNanos codec");
2507            };
2508            assert_eq!(actual_tz, tz);
2509        }
2510    }
2511
2512    #[test]
2513    fn test_local_timestamp_millis_logical_type() {
2514        let schema = create_schema_with_logical_type(PrimitiveType::Long, "local-timestamp-millis");
2515
2516        let mut maker = Maker::new(false, false, Tz::default());
2517        let result = maker.make_data_type(&schema, None, None).unwrap();
2518
2519        assert!(matches!(result.codec, Codec::TimestampMillis(None)));
2520    }
2521
2522    #[test]
2523    fn test_local_timestamp_micros_logical_type() {
2524        let schema = create_schema_with_logical_type(PrimitiveType::Long, "local-timestamp-micros");
2525
2526        let mut maker = Maker::new(false, false, Tz::default());
2527        let result = maker.make_data_type(&schema, None, None).unwrap();
2528
2529        assert!(matches!(result.codec, Codec::TimestampMicros(None)));
2530    }
2531
2532    #[test]
2533    fn test_local_timestamp_nanos_logical_type() {
2534        let schema = create_schema_with_logical_type(PrimitiveType::Long, "local-timestamp-nanos");
2535
2536        let mut maker = Maker::new(false, false, Tz::default());
2537        let result = maker.make_data_type(&schema, None, None).unwrap();
2538
2539        assert!(matches!(result.codec, Codec::TimestampNanos(None)));
2540    }
2541
2542    #[test]
2543    fn test_uuid_type() {
2544        let mut codec = Codec::Fixed(16);
2545        if let c @ Codec::Fixed(16) = &mut codec {
2546            *c = Codec::Uuid;
2547        }
2548        assert!(matches!(codec, Codec::Uuid));
2549    }
2550
2551    #[test]
2552    fn test_fixed_uuid_logical_type_metadata() {
2553        // Iceberg encodes UUID as fixed(16) + logicalType:uuid. Verify that arrow-avro
2554        // preserves the logicalType in Arrow field metadata so callers can detect UUID fields.
2555        // this is supported in avro starting from the 1.12.0 spec: https://avro.apache.org/docs/1.12.0/specification/#uuid
2556        let schema = Schema::Complex(ComplexType::Fixed(Fixed {
2557            name: "uuid_fixed",
2558            namespace: None,
2559            aliases: vec![],
2560            size: 16,
2561            attributes: Attributes {
2562                logical_type: Some("uuid"),
2563                additional: Default::default(),
2564            },
2565        }));
2566
2567        let mut maker = Maker::new(false, false, Tz::default());
2568        let result = maker.make_data_type(&schema, None, None).unwrap();
2569
2570        assert!(
2571            matches!(result.codec, Codec::Fixed(16)),
2572            "codec should be Fixed(16), got {:?}",
2573            result.codec
2574        );
2575        assert_eq!(
2576            result.metadata.get("logicalType").map(|s| s.as_str()),
2577            Some("uuid"),
2578            "logicalType metadata should be 'uuid'"
2579        );
2580    }
2581
2582    #[test]
2583    fn test_duration_logical_type() {
2584        let mut codec = Codec::Fixed(12);
2585
2586        if let c @ Codec::Fixed(12) = &mut codec {
2587            *c = Codec::Interval;
2588        }
2589
2590        assert!(matches!(codec, Codec::Interval));
2591    }
2592
2593    #[test]
2594    fn test_decimal_logical_type_not_implemented() {
2595        let codec = Codec::Fixed(16);
2596
2597        let process_decimal = || -> Result<(), ArrowError> {
2598            if let Codec::Fixed(_) = codec {
2599                return Err(ArrowError::NotYetImplemented(
2600                    "Decimals are not currently supported".to_string(),
2601                ));
2602            }
2603            Ok(())
2604        };
2605
2606        let result = process_decimal();
2607
2608        assert!(result.is_err());
2609        if let Err(ArrowError::NotYetImplemented(msg)) = result {
2610            assert!(msg.contains("Decimals are not currently supported"));
2611        } else {
2612            panic!("Expected NotYetImplemented error");
2613        }
2614    }
2615    #[test]
2616    fn test_unknown_logical_type_added_to_metadata() {
2617        let schema = create_schema_with_logical_type(PrimitiveType::Int, "custom-type");
2618
2619        let mut maker = Maker::new(false, false, Tz::default());
2620        let result = maker.make_data_type(&schema, None, None).unwrap();
2621
2622        assert_eq!(
2623            result.metadata.get("logicalType"),
2624            Some(&"custom-type".to_string())
2625        );
2626    }
2627
2628    #[test]
2629    fn test_string_with_utf8view_enabled() {
2630        let schema = Schema::TypeName(TypeName::Primitive(PrimitiveType::String));
2631
2632        let mut maker = Maker::new(true, false, Tz::default());
2633        let result = maker.make_data_type(&schema, None, None).unwrap();
2634
2635        assert!(matches!(result.codec, Codec::Utf8View));
2636    }
2637
2638    #[test]
2639    fn test_string_without_utf8view_enabled() {
2640        let schema = Schema::TypeName(TypeName::Primitive(PrimitiveType::String));
2641
2642        let mut maker = Maker::new(false, false, Tz::default());
2643        let result = maker.make_data_type(&schema, None, None).unwrap();
2644
2645        assert!(matches!(result.codec, Codec::Utf8));
2646    }
2647
2648    #[test]
2649    fn test_record_with_string_and_utf8view_enabled() {
2650        let field_schema = Schema::TypeName(TypeName::Primitive(PrimitiveType::String));
2651
2652        let avro_field = crate::schema::Field {
2653            name: "string_field",
2654            r#type: field_schema,
2655            default: None,
2656            doc: None,
2657            aliases: vec![],
2658        };
2659
2660        let record = Record {
2661            name: "test_record",
2662            namespace: None,
2663            aliases: vec![],
2664            doc: None,
2665            fields: vec![avro_field],
2666            attributes: Attributes::default(),
2667        };
2668
2669        let schema = Schema::Complex(ComplexType::Record(record));
2670
2671        let mut maker = Maker::new(true, false, Tz::default());
2672        let result = maker.make_data_type(&schema, None, None).unwrap();
2673
2674        if let Codec::Struct(fields) = &result.codec {
2675            let first_field_codec = &fields[0].data_type().codec;
2676            assert!(matches!(first_field_codec, Codec::Utf8View));
2677        } else {
2678            panic!("Expected Struct codec");
2679        }
2680    }
2681
2682    #[test]
2683    fn test_union_with_strict_mode() {
2684        let schema = Schema::Union(vec![
2685            Schema::TypeName(TypeName::Primitive(PrimitiveType::String)),
2686            Schema::TypeName(TypeName::Primitive(PrimitiveType::Null)),
2687        ]);
2688
2689        let mut maker = Maker::new(false, true, Tz::default());
2690        let result = maker.make_data_type(&schema, None, None);
2691
2692        assert!(result.is_err());
2693        match result {
2694            Err(ArrowError::SchemaError(msg)) => {
2695                assert!(msg.contains(
2696                    "Found Avro union of the form ['T','null'], which is disallowed in strict_mode"
2697                ));
2698            }
2699            _ => panic!("Expected SchemaError"),
2700        }
2701    }
2702
2703    #[test]
2704    fn test_resolve_int_to_float_promotion() {
2705        let result = resolve_promotion(PrimitiveType::Int, PrimitiveType::Float);
2706        assert!(matches!(result.codec, Codec::Float32));
2707        assert_eq!(
2708            result.resolution,
2709            Some(ResolutionInfo::Promotion(Promotion::IntToFloat))
2710        );
2711    }
2712
2713    #[test]
2714    fn test_resolve_int_to_double_promotion() {
2715        let result = resolve_promotion(PrimitiveType::Int, PrimitiveType::Double);
2716        assert!(matches!(result.codec, Codec::Float64));
2717        assert_eq!(
2718            result.resolution,
2719            Some(ResolutionInfo::Promotion(Promotion::IntToDouble))
2720        );
2721    }
2722
2723    #[test]
2724    fn test_resolve_long_to_float_promotion() {
2725        let result = resolve_promotion(PrimitiveType::Long, PrimitiveType::Float);
2726        assert!(matches!(result.codec, Codec::Float32));
2727        assert_eq!(
2728            result.resolution,
2729            Some(ResolutionInfo::Promotion(Promotion::LongToFloat))
2730        );
2731    }
2732
2733    #[test]
2734    fn test_resolve_long_to_double_promotion() {
2735        let result = resolve_promotion(PrimitiveType::Long, PrimitiveType::Double);
2736        assert!(matches!(result.codec, Codec::Float64));
2737        assert_eq!(
2738            result.resolution,
2739            Some(ResolutionInfo::Promotion(Promotion::LongToDouble))
2740        );
2741    }
2742
2743    #[test]
2744    fn test_resolve_float_to_double_promotion() {
2745        let result = resolve_promotion(PrimitiveType::Float, PrimitiveType::Double);
2746        assert!(matches!(result.codec, Codec::Float64));
2747        assert_eq!(
2748            result.resolution,
2749            Some(ResolutionInfo::Promotion(Promotion::FloatToDouble))
2750        );
2751    }
2752
2753    #[test]
2754    fn test_resolve_string_to_bytes_promotion() {
2755        let result = resolve_promotion(PrimitiveType::String, PrimitiveType::Bytes);
2756        assert!(matches!(result.codec, Codec::Binary));
2757        assert_eq!(
2758            result.resolution,
2759            Some(ResolutionInfo::Promotion(Promotion::StringToBytes))
2760        );
2761    }
2762
2763    #[test]
2764    fn test_resolve_bytes_to_string_promotion() {
2765        let result = resolve_promotion(PrimitiveType::Bytes, PrimitiveType::String);
2766        assert!(matches!(result.codec, Codec::Utf8));
2767        assert_eq!(
2768            result.resolution,
2769            Some(ResolutionInfo::Promotion(Promotion::BytesToString))
2770        );
2771    }
2772
2773    #[test]
2774    fn test_resolve_illegal_promotion_double_to_float_errors() {
2775        let writer_schema = Schema::TypeName(TypeName::Primitive(PrimitiveType::Double));
2776        let reader_schema = Schema::TypeName(TypeName::Primitive(PrimitiveType::Float));
2777        let mut maker = Maker::new(false, false, Tz::default());
2778        let result = maker.make_data_type(&writer_schema, Some(&reader_schema), None);
2779        assert!(result.is_err());
2780        match result {
2781            Err(ArrowError::ParseError(msg)) => {
2782                assert!(msg.contains("Illegal promotion"));
2783            }
2784            _ => panic!("Expected ParseError for illegal promotion Double -> Float"),
2785        }
2786    }
2787
2788    #[test]
2789    fn test_promotion_within_nullable_union_keeps_writer_null_ordering() {
2790        let writer = Schema::Union(vec![
2791            Schema::TypeName(TypeName::Primitive(PrimitiveType::Null)),
2792            Schema::TypeName(TypeName::Primitive(PrimitiveType::Int)),
2793        ]);
2794        let reader = Schema::Union(vec![
2795            Schema::TypeName(TypeName::Primitive(PrimitiveType::Double)),
2796            Schema::TypeName(TypeName::Primitive(PrimitiveType::Null)),
2797        ]);
2798        let mut maker = Maker::new(false, false, Tz::default());
2799        let result = maker.make_data_type(&writer, Some(&reader), None).unwrap();
2800        assert!(matches!(result.codec, Codec::Float64));
2801        assert_eq!(
2802            result.resolution,
2803            Some(ResolutionInfo::Union(ResolvedUnion {
2804                writer_to_reader: [
2805                    None,
2806                    Some((0, ResolutionInfo::Promotion(Promotion::IntToDouble)))
2807                ]
2808                .into(),
2809                writer_is_union: true,
2810                reader_is_union: true,
2811            }))
2812        );
2813        assert_eq!(result.nullability, Some(Nullability::NullFirst));
2814    }
2815
2816    #[test]
2817    fn test_resolve_writer_union_to_reader_non_union_partial_coverage() {
2818        let writer = mk_union(vec![
2819            mk_primitive(PrimitiveType::String),
2820            mk_primitive(PrimitiveType::Long),
2821        ]);
2822        let reader = mk_primitive(PrimitiveType::Bytes);
2823        let mut maker = Maker::new(false, false, Tz::default());
2824        let dt = maker.make_data_type(&writer, Some(&reader), None).unwrap();
2825        assert!(matches!(dt.codec(), Codec::Binary));
2826        let resolved = match dt.resolution {
2827            Some(ResolutionInfo::Union(u)) => u,
2828            other => panic!("expected union resolution info, got {other:?}"),
2829        };
2830        assert!(resolved.writer_is_union && !resolved.reader_is_union);
2831        assert_eq!(
2832            resolved.writer_to_reader.as_ref(),
2833            &[
2834                Some((0, ResolutionInfo::Promotion(Promotion::StringToBytes))),
2835                None
2836            ]
2837        );
2838    }
2839
2840    #[test]
2841    fn test_resolve_writer_non_union_to_reader_union_prefers_direct_over_promotion() {
2842        let writer = mk_primitive(PrimitiveType::Long);
2843        let reader = mk_union(vec![
2844            mk_primitive(PrimitiveType::Long),
2845            mk_primitive(PrimitiveType::Double),
2846        ]);
2847        let mut maker = Maker::new(false, false, Tz::default());
2848        let dt = maker.make_data_type(&writer, Some(&reader), None).unwrap();
2849        let resolved = match dt.resolution {
2850            Some(ResolutionInfo::Union(u)) => u,
2851            other => panic!("expected union resolution info, got {other:?}"),
2852        };
2853        assert!(!resolved.writer_is_union && resolved.reader_is_union);
2854        assert_eq!(
2855            resolved.writer_to_reader.as_ref(),
2856            &[Some((0, ResolutionInfo::Promotion(Promotion::Direct)))]
2857        );
2858    }
2859
2860    #[test]
2861    fn test_resolve_writer_non_union_to_reader_union_uses_promotion_when_needed() {
2862        let writer = mk_primitive(PrimitiveType::Int);
2863        let reader = mk_union(vec![
2864            mk_primitive(PrimitiveType::Null),
2865            mk_primitive(PrimitiveType::Long),
2866            mk_primitive(PrimitiveType::String),
2867        ]);
2868        let mut maker = Maker::new(false, false, Tz::default());
2869        let dt = maker.make_data_type(&writer, Some(&reader), None).unwrap();
2870        let resolved = match dt.resolution {
2871            Some(ResolutionInfo::Union(u)) => u,
2872            other => panic!("expected union resolution info, got {other:?}"),
2873        };
2874        assert_eq!(
2875            resolved.writer_to_reader.as_ref(),
2876            &[Some((1, ResolutionInfo::Promotion(Promotion::IntToLong)))]
2877        );
2878    }
2879
2880    #[test]
2881    fn test_resolve_writer_non_union_to_reader_union_preserves_inner_record_defaults() {
2882        // Writer: record Inner{a: int}
2883        // Reader: union [Inner{a: int, b: int default 42}, string]
2884        // The matching child (Inner) should preserve DefaultValue(Int(42)) on field b.
2885        let writer = Schema::Complex(ComplexType::Record(Record {
2886            name: "Inner",
2887            namespace: None,
2888            doc: None,
2889            aliases: vec![],
2890            fields: vec![AvroFieldSchema {
2891                name: "a",
2892                doc: None,
2893                r#type: mk_primitive(PrimitiveType::Int),
2894                default: None,
2895                aliases: vec![],
2896            }],
2897            attributes: Attributes::default(),
2898        }));
2899        let reader = mk_union(vec![
2900            Schema::Complex(ComplexType::Record(Record {
2901                name: "Inner",
2902                namespace: None,
2903                doc: None,
2904                aliases: vec![],
2905                fields: vec![
2906                    AvroFieldSchema {
2907                        name: "a",
2908                        doc: None,
2909                        r#type: mk_primitive(PrimitiveType::Int),
2910                        default: None,
2911                        aliases: vec![],
2912                    },
2913                    AvroFieldSchema {
2914                        name: "b",
2915                        doc: None,
2916                        r#type: mk_primitive(PrimitiveType::Int),
2917                        default: Some(Value::Number(serde_json::Number::from(42))),
2918                        aliases: vec![],
2919                    },
2920                ],
2921                attributes: Attributes::default(),
2922            })),
2923            mk_primitive(PrimitiveType::String),
2924        ]);
2925        let mut maker = Maker::new(false, false, Default::default());
2926        let dt = maker
2927            .make_data_type(&writer, Some(&reader), None)
2928            .expect("resolution should succeed");
2929        // Verify the union resolution structure
2930        let resolved = match dt.resolution.as_ref() {
2931            Some(ResolutionInfo::Union(u)) => u,
2932            other => panic!("expected union resolution info, got {other:?}"),
2933        };
2934        assert!(!resolved.writer_is_union && resolved.reader_is_union);
2935        assert_eq!(
2936            resolved.writer_to_reader.len(),
2937            1,
2938            "expected the non-union record to resolve to a union variant"
2939        );
2940        let resolution = match resolved.writer_to_reader.first().unwrap() {
2941            Some((0, resolution)) => resolution,
2942            other => panic!("unexpected writer-to-reader table value {other:?}"),
2943        };
2944        match resolution {
2945            ResolutionInfo::Record(ResolvedRecord {
2946                writer_fields,
2947                default_fields,
2948            }) => {
2949                assert_eq!(writer_fields.len(), 1);
2950                assert!(matches!(writer_fields[0], ResolvedField::ToReader(0, _)));
2951                assert_eq!(default_fields.len(), 1);
2952                assert_eq!(default_fields[0], 1);
2953            }
2954            other => panic!("unexpected resolution {other:?}"),
2955        }
2956        // The matching child (Inner at index 0) should have field b with DefaultValue
2957        let children = match dt.codec() {
2958            Codec::Union(children, _, _) => children,
2959            other => panic!("expected union codec, got {other:?}"),
2960        };
2961        let inner_fields = match children[0].codec() {
2962            Codec::Struct(f) => f,
2963            other => panic!("expected struct codec for Inner, got {other:?}"),
2964        };
2965        assert_eq!(inner_fields.len(), 2);
2966        assert_eq!(inner_fields[1].name(), "b");
2967        assert_eq!(
2968            inner_fields[1].data_type().resolution,
2969            Some(ResolutionInfo::DefaultValue(AvroLiteral::Int(42))),
2970            "field b should have DefaultValue(Int(42)) from schema resolution"
2971        );
2972    }
2973
2974    #[test]
2975    fn test_resolve_writer_union_to_reader_union_preserves_inner_record_defaults() {
2976        // Writer: record [string, Inner{a: int}]
2977        // Reader: union [Inner{a: int, b: int default 42}, string]
2978        // The matching child (Inner) should preserve DefaultValue(Int(42)) on field b.
2979        let writer = mk_union(vec![
2980            mk_primitive(PrimitiveType::String),
2981            Schema::Complex(ComplexType::Record(Record {
2982                name: "Inner",
2983                namespace: None,
2984                doc: None,
2985                aliases: vec![],
2986                fields: vec![AvroFieldSchema {
2987                    name: "a",
2988                    doc: None,
2989                    r#type: mk_primitive(PrimitiveType::Int),
2990                    default: None,
2991                    aliases: vec![],
2992                }],
2993                attributes: Attributes::default(),
2994            })),
2995        ]);
2996        let reader = mk_union(vec![
2997            Schema::Complex(ComplexType::Record(Record {
2998                name: "Inner",
2999                namespace: None,
3000                doc: None,
3001                aliases: vec![],
3002                fields: vec![
3003                    AvroFieldSchema {
3004                        name: "a",
3005                        doc: None,
3006                        r#type: mk_primitive(PrimitiveType::Int),
3007                        default: None,
3008                        aliases: vec![],
3009                    },
3010                    AvroFieldSchema {
3011                        name: "b",
3012                        doc: None,
3013                        r#type: mk_primitive(PrimitiveType::Int),
3014                        default: Some(Value::Number(serde_json::Number::from(42))),
3015                        aliases: vec![],
3016                    },
3017                ],
3018                attributes: Attributes::default(),
3019            })),
3020            mk_primitive(PrimitiveType::String),
3021        ]);
3022        let mut maker = Maker::new(false, false, Default::default());
3023        let dt = maker
3024            .make_data_type(&writer, Some(&reader), None)
3025            .expect("resolution should succeed");
3026        // Verify the union resolution structure
3027        let resolved = match dt.resolution.as_ref() {
3028            Some(ResolutionInfo::Union(u)) => u,
3029            other => panic!("expected union resolution info, got {other:?}"),
3030        };
3031        assert!(resolved.writer_is_union && resolved.reader_is_union);
3032        assert_eq!(resolved.writer_to_reader.len(), 2);
3033        let resolution = match resolved.writer_to_reader[1].as_ref() {
3034            Some((0, resolution)) => resolution,
3035            other => panic!("unexpected writer-to-reader table value {other:?}"),
3036        };
3037        match resolution {
3038            ResolutionInfo::Record(ResolvedRecord {
3039                writer_fields,
3040                default_fields,
3041            }) => {
3042                assert_eq!(writer_fields.len(), 1);
3043                assert!(matches!(writer_fields[0], ResolvedField::ToReader(0, _)));
3044                assert_eq!(default_fields.len(), 1);
3045                assert_eq!(default_fields[0], 1);
3046            }
3047            other => panic!("unexpected resolution {other:?}"),
3048        }
3049        // The matching child (Inner at index 0) should have field b with DefaultValue
3050        let children = match dt.codec() {
3051            Codec::Union(children, _, _) => children,
3052            other => panic!("expected union codec, got {other:?}"),
3053        };
3054        let inner_fields = match children[0].codec() {
3055            Codec::Struct(f) => f,
3056            other => panic!("expected struct codec for Inner, got {other:?}"),
3057        };
3058        assert_eq!(inner_fields.len(), 2);
3059        assert_eq!(inner_fields[1].name(), "b");
3060        assert_eq!(
3061            inner_fields[1].data_type().resolution,
3062            Some(ResolutionInfo::DefaultValue(AvroLiteral::Int(42))),
3063            "field b should have DefaultValue(Int(42)) from schema resolution"
3064        );
3065    }
3066
3067    #[test]
3068    fn test_resolve_both_nullable_unions_direct_match() {
3069        let writer = mk_union(vec![
3070            mk_primitive(PrimitiveType::Null),
3071            mk_primitive(PrimitiveType::String),
3072        ]);
3073        let reader = mk_union(vec![
3074            mk_primitive(PrimitiveType::String),
3075            mk_primitive(PrimitiveType::Null),
3076        ]);
3077        let mut maker = Maker::new(false, false, Tz::default());
3078        let dt = maker.make_data_type(&writer, Some(&reader), None).unwrap();
3079        assert!(matches!(dt.codec(), Codec::Utf8));
3080        assert_eq!(dt.nullability, Some(Nullability::NullFirst));
3081        assert_eq!(
3082            dt.resolution,
3083            Some(ResolutionInfo::Union(ResolvedUnion {
3084                writer_to_reader: [
3085                    None,
3086                    Some((0, ResolutionInfo::Promotion(Promotion::Direct)))
3087                ]
3088                .into(),
3089                writer_is_union: true,
3090                reader_is_union: true
3091            }))
3092        );
3093    }
3094
3095    #[test]
3096    fn test_resolve_both_nullable_unions_with_promotion() {
3097        let writer = mk_union(vec![
3098            mk_primitive(PrimitiveType::Null),
3099            mk_primitive(PrimitiveType::Int),
3100        ]);
3101        let reader = mk_union(vec![
3102            mk_primitive(PrimitiveType::Double),
3103            mk_primitive(PrimitiveType::Null),
3104        ]);
3105        let mut maker = Maker::new(false, false, Tz::default());
3106        let dt = maker.make_data_type(&writer, Some(&reader), None).unwrap();
3107        assert!(matches!(dt.codec(), Codec::Float64));
3108        assert_eq!(dt.nullability, Some(Nullability::NullFirst));
3109        assert_eq!(
3110            dt.resolution,
3111            Some(ResolutionInfo::Union(ResolvedUnion {
3112                writer_to_reader: [
3113                    None,
3114                    Some((0, ResolutionInfo::Promotion(Promotion::IntToDouble)))
3115                ]
3116                .into(),
3117                writer_is_union: true,
3118                reader_is_union: true
3119            }))
3120        );
3121    }
3122
3123    #[test]
3124    fn test_resolve_type_promotion() {
3125        let writer_schema = Schema::TypeName(TypeName::Primitive(PrimitiveType::Int));
3126        let reader_schema = Schema::TypeName(TypeName::Primitive(PrimitiveType::Long));
3127        let mut maker = Maker::new(false, false, Tz::default());
3128        let result = maker
3129            .make_data_type(&writer_schema, Some(&reader_schema), None)
3130            .unwrap();
3131        assert!(matches!(result.codec, Codec::Int64));
3132        assert_eq!(
3133            result.resolution,
3134            Some(ResolutionInfo::Promotion(Promotion::IntToLong))
3135        );
3136    }
3137
3138    #[test]
3139    fn test_nested_record_type_reuse_without_namespace() {
3140        let schema_str = r#"
3141        {
3142          "type": "record",
3143          "name": "Record",
3144          "fields": [
3145            {
3146              "name": "nested",
3147              "type": {
3148                "type": "record",
3149                "name": "Nested",
3150                "fields": [
3151                  { "name": "nested_int", "type": "int" }
3152                ]
3153              }
3154            },
3155            { "name": "nestedRecord", "type": "Nested" },
3156            { "name": "nestedArray", "type": { "type": "array", "items": "Nested" } },
3157            { "name": "nestedMap", "type": { "type": "map", "values": "Nested" } }
3158          ]
3159        }
3160        "#;
3161
3162        let schema: Schema = serde_json::from_str(schema_str).unwrap();
3163
3164        let mut maker = Maker::new(false, false, Tz::default());
3165        let avro_data_type = maker.make_data_type(&schema, None, None).unwrap();
3166
3167        if let Codec::Struct(fields) = avro_data_type.codec() {
3168            assert_eq!(fields.len(), 4);
3169
3170            // nested
3171            assert_eq!(fields[0].name(), "nested");
3172            let nested_data_type = fields[0].data_type();
3173            if let Codec::Struct(nested_fields) = nested_data_type.codec() {
3174                assert_eq!(nested_fields.len(), 1);
3175                assert_eq!(nested_fields[0].name(), "nested_int");
3176                assert!(matches!(nested_fields[0].data_type().codec(), Codec::Int32));
3177            } else {
3178                panic!(
3179                    "'nested' field is not a struct but {:?}",
3180                    nested_data_type.codec()
3181                );
3182            }
3183
3184            // nestedRecord
3185            assert_eq!(fields[1].name(), "nestedRecord");
3186            let nested_record_data_type = fields[1].data_type();
3187            assert_eq!(
3188                nested_record_data_type.codec().data_type(),
3189                nested_data_type.codec().data_type()
3190            );
3191
3192            // nestedArray
3193            assert_eq!(fields[2].name(), "nestedArray");
3194            if let Codec::List(item_type) = fields[2].data_type().codec() {
3195                assert_eq!(
3196                    item_type.codec().data_type(),
3197                    nested_data_type.codec().data_type()
3198                );
3199            } else {
3200                panic!("'nestedArray' field is not a list");
3201            }
3202
3203            // nestedMap
3204            assert_eq!(fields[3].name(), "nestedMap");
3205            if let Codec::Map(value_type) = fields[3].data_type().codec() {
3206                assert_eq!(
3207                    value_type.codec().data_type(),
3208                    nested_data_type.codec().data_type()
3209                );
3210            } else {
3211                panic!("'nestedMap' field is not a map");
3212            }
3213        } else {
3214            panic!("Top-level schema is not a struct");
3215        }
3216    }
3217
3218    #[test]
3219    fn test_nested_enum_type_reuse_with_namespace() {
3220        let schema_str = r#"
3221        {
3222          "type": "record",
3223          "name": "Record",
3224          "namespace": "record_ns",
3225          "fields": [
3226            {
3227              "name": "status",
3228              "type": {
3229                "type": "enum",
3230                "name": "Status",
3231                "namespace": "enum_ns",
3232                "symbols": ["ACTIVE", "INACTIVE", "PENDING"]
3233              }
3234            },
3235            { "name": "backupStatus", "type": "enum_ns.Status" },
3236            { "name": "statusHistory", "type": { "type": "array", "items": "enum_ns.Status" } },
3237            { "name": "statusMap", "type": { "type": "map", "values": "enum_ns.Status" } }
3238          ]
3239        }
3240        "#;
3241
3242        let schema: Schema = serde_json::from_str(schema_str).unwrap();
3243
3244        let mut maker = Maker::new(false, false, Tz::default());
3245        let avro_data_type = maker.make_data_type(&schema, None, None).unwrap();
3246
3247        if let Codec::Struct(fields) = avro_data_type.codec() {
3248            assert_eq!(fields.len(), 4);
3249
3250            // status
3251            assert_eq!(fields[0].name(), "status");
3252            let status_data_type = fields[0].data_type();
3253            if let Codec::Enum(symbols) = status_data_type.codec() {
3254                assert_eq!(symbols.as_ref(), &["ACTIVE", "INACTIVE", "PENDING"]);
3255            } else {
3256                panic!(
3257                    "'status' field is not an enum but {:?}",
3258                    status_data_type.codec()
3259                );
3260            }
3261
3262            // backupStatus
3263            assert_eq!(fields[1].name(), "backupStatus");
3264            let backup_status_data_type = fields[1].data_type();
3265            assert_eq!(
3266                backup_status_data_type.codec().data_type(),
3267                status_data_type.codec().data_type()
3268            );
3269
3270            // statusHistory
3271            assert_eq!(fields[2].name(), "statusHistory");
3272            if let Codec::List(item_type) = fields[2].data_type().codec() {
3273                assert_eq!(
3274                    item_type.codec().data_type(),
3275                    status_data_type.codec().data_type()
3276                );
3277            } else {
3278                panic!("'statusHistory' field is not a list");
3279            }
3280
3281            // statusMap
3282            assert_eq!(fields[3].name(), "statusMap");
3283            if let Codec::Map(value_type) = fields[3].data_type().codec() {
3284                assert_eq!(
3285                    value_type.codec().data_type(),
3286                    status_data_type.codec().data_type()
3287                );
3288            } else {
3289                panic!("'statusMap' field is not a map");
3290            }
3291        } else {
3292            panic!("Top-level schema is not a struct");
3293        }
3294    }
3295
3296    #[test]
3297    fn test_named_type_reuse_with_full_name() {
3298        // A name containing a dot is a full name, and types nested in a record
3299        // with a full name inherit the namespace from that name.
3300        let schema_str = r#"
3301        {
3302          "type": "record",
3303          "name": "record_ns.Record",
3304          "fields": [
3305            {
3306              "name": "status",
3307              "type": {
3308                "type": "enum",
3309                "name": "enum_ns.Status",
3310                "symbols": ["ACTIVE", "INACTIVE"]
3311              }
3312            },
3313            { "name": "backupStatus", "type": "enum_ns.Status" },
3314            {
3315              "name": "nested",
3316              "type": {
3317                "type": "record",
3318                "name": "Nested",
3319                "fields": [{ "name": "nested_int", "type": "int" }]
3320              }
3321            },
3322            { "name": "nestedAgain", "type": "record_ns.Nested" }
3323          ]
3324        }
3325        "#;
3326
3327        let schema: Schema = serde_json::from_str(schema_str).unwrap();
3328
3329        let mut maker = Maker::new(false, false, Tz::default());
3330        let avro_data_type = maker.make_data_type(&schema, None, None).unwrap();
3331
3332        let Codec::Struct(fields) = avro_data_type.codec() else {
3333            panic!("Top-level schema is not a struct");
3334        };
3335        assert_eq!(fields.len(), 4);
3336        assert!(matches!(fields[1].data_type().codec(), Codec::Enum(_)));
3337        assert_eq!(
3338            fields[1].data_type().codec().data_type(),
3339            fields[0].data_type().codec().data_type()
3340        );
3341        assert!(matches!(fields[3].data_type().codec(), Codec::Struct(_)));
3342        assert_eq!(
3343            fields[3].data_type().codec().data_type(),
3344            fields[2].data_type().codec().data_type()
3345        );
3346    }
3347
3348    #[test]
3349    fn test_resolve_from_writer_and_reader_defaults_root_name_for_non_record_reader() {
3350        let writer_schema = Schema::TypeName(TypeName::Primitive(PrimitiveType::String));
3351        let reader_schema = Schema::TypeName(TypeName::Primitive(PrimitiveType::String));
3352        let mut maker = Maker::new(false, false, Tz::default());
3353        let data_type = maker
3354            .make_data_type(&writer_schema, Some(&reader_schema), None)
3355            .expect("resolution should succeed");
3356        let field = AvroField {
3357            name: AVRO_ROOT_RECORD_DEFAULT_NAME.to_string(),
3358            data_type,
3359        };
3360        assert_eq!(field.name(), AVRO_ROOT_RECORD_DEFAULT_NAME);
3361        assert!(matches!(field.data_type().codec(), Codec::Utf8));
3362    }
3363
3364    fn json_string(s: &str) -> Value {
3365        Value::String(s.to_string())
3366    }
3367
3368    fn assert_default_stored(dt: &AvroDataType, default_json: &Value) {
3369        let stored = dt
3370            .metadata
3371            .get(AVRO_FIELD_DEFAULT_METADATA_KEY)
3372            .cloned()
3373            .unwrap_or_default();
3374        let expected = serde_json::to_string(default_json).unwrap();
3375        assert_eq!(stored, expected, "stored default metadata should match");
3376    }
3377
3378    #[test]
3379    fn test_validate_and_store_default_null_and_nullability_rules() {
3380        let mut dt_null = AvroDataType::new(Codec::Null, HashMap::new(), None);
3381        let lit = dt_null.parse_and_store_default(&Value::Null).unwrap();
3382        assert_eq!(lit, AvroLiteral::Null);
3383        assert_default_stored(&dt_null, &Value::Null);
3384        let mut dt_int = AvroDataType::new(Codec::Int32, HashMap::new(), None);
3385        let err = dt_int.parse_and_store_default(&Value::Null).unwrap_err();
3386        assert!(
3387            err.to_string()
3388                .contains("JSON null default is only valid for `null` type"),
3389            "unexpected error: {err}"
3390        );
3391        let mut dt_int_nf =
3392            AvroDataType::new(Codec::Int32, HashMap::new(), Some(Nullability::NullFirst));
3393        let lit2 = dt_int_nf.parse_and_store_default(&Value::Null).unwrap();
3394        assert_eq!(lit2, AvroLiteral::Null);
3395        assert_default_stored(&dt_int_nf, &Value::Null);
3396        let mut dt_int_ns =
3397            AvroDataType::new(Codec::Int32, HashMap::new(), Some(Nullability::NullSecond));
3398        let err2 = dt_int_ns.parse_and_store_default(&Value::Null).unwrap_err();
3399        assert!(
3400            err2.to_string()
3401                .contains("JSON null default is only valid for `null` type"),
3402            "unexpected error: {err2}"
3403        );
3404    }
3405
3406    #[test]
3407    fn test_validate_and_store_default_primitives_and_temporal() {
3408        let mut dt_bool = AvroDataType::new(Codec::Boolean, HashMap::new(), None);
3409        let lit = dt_bool.parse_and_store_default(&Value::Bool(true)).unwrap();
3410        assert_eq!(lit, AvroLiteral::Boolean(true));
3411        assert_default_stored(&dt_bool, &Value::Bool(true));
3412        let mut dt_i32 = AvroDataType::new(Codec::Int32, HashMap::new(), None);
3413        let lit = dt_i32
3414            .parse_and_store_default(&serde_json::json!(123))
3415            .unwrap();
3416        assert_eq!(lit, AvroLiteral::Int(123));
3417        assert_default_stored(&dt_i32, &serde_json::json!(123));
3418        let err = dt_i32
3419            .parse_and_store_default(&serde_json::json!(i64::from(i32::MAX) + 1))
3420            .unwrap_err();
3421        assert!(format!("{err}").contains("out of i32 range"));
3422        let mut dt_i64 = AvroDataType::new(Codec::Int64, HashMap::new(), None);
3423        let lit = dt_i64
3424            .parse_and_store_default(&serde_json::json!(1234567890))
3425            .unwrap();
3426        assert_eq!(lit, AvroLiteral::Long(1234567890));
3427        assert_default_stored(&dt_i64, &serde_json::json!(1234567890));
3428        let mut dt_f32 = AvroDataType::new(Codec::Float32, HashMap::new(), None);
3429        let lit = dt_f32
3430            .parse_and_store_default(&serde_json::json!(1.25))
3431            .unwrap();
3432        assert_eq!(lit, AvroLiteral::Float(1.25));
3433        assert_default_stored(&dt_f32, &serde_json::json!(1.25));
3434        let err = dt_f32
3435            .parse_and_store_default(&serde_json::json!(1e39))
3436            .unwrap_err();
3437        assert!(format!("{err}").contains("out of f32 range"));
3438        let mut dt_f64 = AvroDataType::new(Codec::Float64, HashMap::new(), None);
3439        let lit = dt_f64
3440            .parse_and_store_default(&serde_json::json!(std::f64::consts::PI))
3441            .unwrap();
3442        assert_eq!(lit, AvroLiteral::Double(std::f64::consts::PI));
3443        assert_default_stored(&dt_f64, &serde_json::json!(std::f64::consts::PI));
3444        let mut dt_str = AvroDataType::new(Codec::Utf8, HashMap::new(), None);
3445        let l = dt_str
3446            .parse_and_store_default(&json_string("hello"))
3447            .unwrap();
3448        assert_eq!(l, AvroLiteral::String("hello".into()));
3449        assert_default_stored(&dt_str, &json_string("hello"));
3450        let mut dt_strv = AvroDataType::new(Codec::Utf8View, HashMap::new(), None);
3451        let l = dt_strv
3452            .parse_and_store_default(&json_string("view"))
3453            .unwrap();
3454        assert_eq!(l, AvroLiteral::String("view".into()));
3455        assert_default_stored(&dt_strv, &json_string("view"));
3456        let mut dt_uuid = AvroDataType::new(Codec::Uuid, HashMap::new(), None);
3457        let l = dt_uuid
3458            .parse_and_store_default(&json_string("00000000-0000-0000-0000-000000000000"))
3459            .unwrap();
3460        assert_eq!(
3461            l,
3462            AvroLiteral::String("00000000-0000-0000-0000-000000000000".into())
3463        );
3464        let mut dt_bin = AvroDataType::new(Codec::Binary, HashMap::new(), None);
3465        let l = dt_bin.parse_and_store_default(&json_string("ABC")).unwrap();
3466        assert_eq!(l, AvroLiteral::Bytes(vec![65, 66, 67]));
3467        let err = dt_bin
3468            .parse_and_store_default(&json_string("€")) // U+20AC
3469            .unwrap_err();
3470        assert!(format!("{err}").contains("Invalid codepoint"));
3471        let mut dt_date = AvroDataType::new(Codec::Date32, HashMap::new(), None);
3472        let ld = dt_date
3473            .parse_and_store_default(&serde_json::json!(1))
3474            .unwrap();
3475        assert_eq!(ld, AvroLiteral::Int(1));
3476        let mut dt_tmill = AvroDataType::new(Codec::TimeMillis, HashMap::new(), None);
3477        let lt = dt_tmill
3478            .parse_and_store_default(&serde_json::json!(86_400_000))
3479            .unwrap();
3480        assert_eq!(lt, AvroLiteral::Int(86_400_000));
3481        let mut dt_tmicros = AvroDataType::new(Codec::TimeMicros, HashMap::new(), None);
3482        let ltm = dt_tmicros
3483            .parse_and_store_default(&serde_json::json!(1_000_000))
3484            .unwrap();
3485        assert_eq!(ltm, AvroLiteral::Long(1_000_000));
3486        let mut dt_ts_milli = AvroDataType::new(Codec::TimestampMillis(None), HashMap::new(), None);
3487        let l1 = dt_ts_milli
3488            .parse_and_store_default(&serde_json::json!(123))
3489            .unwrap();
3490        assert_eq!(l1, AvroLiteral::Long(123));
3491        let mut dt_ts_micro = AvroDataType::new(Codec::TimestampMicros(None), HashMap::new(), None);
3492        let l2 = dt_ts_micro
3493            .parse_and_store_default(&serde_json::json!(456))
3494            .unwrap();
3495        assert_eq!(l2, AvroLiteral::Long(456));
3496    }
3497
3498    #[cfg(feature = "avro_custom_types")]
3499    #[test]
3500    fn test_validate_and_store_default_custom_integer_ranges() {
3501        let mut dt_i8 = AvroDataType::new(Codec::Int8, HashMap::new(), None);
3502        let lit_i8 = dt_i8
3503            .parse_and_store_default(&serde_json::json!(i8::MAX))
3504            .unwrap();
3505        assert_eq!(lit_i8, AvroLiteral::Int(i8::MAX as i32));
3506        let err_i8_high = dt_i8
3507            .parse_and_store_default(&serde_json::json!(i8::MAX as i64 + 1))
3508            .unwrap_err();
3509        assert!(err_i8_high.to_string().contains("out of i8 range"));
3510        let err_i8_low = dt_i8
3511            .parse_and_store_default(&serde_json::json!(i8::MIN as i64 - 1))
3512            .unwrap_err();
3513        assert!(err_i8_low.to_string().contains("out of i8 range"));
3514
3515        let mut dt_i16 = AvroDataType::new(Codec::Int16, HashMap::new(), None);
3516        let lit_i16 = dt_i16
3517            .parse_and_store_default(&serde_json::json!(i16::MIN))
3518            .unwrap();
3519        assert_eq!(lit_i16, AvroLiteral::Int(i16::MIN as i32));
3520        let err_i16_high = dt_i16
3521            .parse_and_store_default(&serde_json::json!(i16::MAX as i64 + 1))
3522            .unwrap_err();
3523        assert!(err_i16_high.to_string().contains("out of i16 range"));
3524        let err_i16_low = dt_i16
3525            .parse_and_store_default(&serde_json::json!(i16::MIN as i64 - 1))
3526            .unwrap_err();
3527        assert!(err_i16_low.to_string().contains("out of i16 range"));
3528
3529        let mut dt_u8 = AvroDataType::new(Codec::UInt8, HashMap::new(), None);
3530        let lit_u8 = dt_u8
3531            .parse_and_store_default(&serde_json::json!(u8::MAX))
3532            .unwrap();
3533        assert_eq!(lit_u8, AvroLiteral::Int(u8::MAX as i32));
3534        let err_u8_neg = dt_u8
3535            .parse_and_store_default(&serde_json::json!(-1))
3536            .unwrap_err();
3537        assert!(err_u8_neg.to_string().contains("out of u8 range"));
3538        let err_u8_high = dt_u8
3539            .parse_and_store_default(&serde_json::json!(u8::MAX as i64 + 1))
3540            .unwrap_err();
3541        assert!(err_u8_high.to_string().contains("out of u8 range"));
3542
3543        let mut dt_u16 = AvroDataType::new(Codec::UInt16, HashMap::new(), None);
3544        let lit_u16 = dt_u16
3545            .parse_and_store_default(&serde_json::json!(u16::MAX))
3546            .unwrap();
3547        assert_eq!(lit_u16, AvroLiteral::Int(u16::MAX as i32));
3548        let err_u16_neg = dt_u16
3549            .parse_and_store_default(&serde_json::json!(-1))
3550            .unwrap_err();
3551        assert!(err_u16_neg.to_string().contains("out of u16 range"));
3552        let err_u16_high = dt_u16
3553            .parse_and_store_default(&serde_json::json!(u16::MAX as i64 + 1))
3554            .unwrap_err();
3555        assert!(err_u16_high.to_string().contains("out of u16 range"));
3556
3557        let mut dt_u32 = AvroDataType::new(Codec::UInt32, HashMap::new(), None);
3558        let lit_u32 = dt_u32
3559            .parse_and_store_default(&serde_json::json!(u32::MAX as i64))
3560            .unwrap();
3561        assert_eq!(lit_u32, AvroLiteral::Long(u32::MAX as i64));
3562        let err_u32_neg = dt_u32
3563            .parse_and_store_default(&serde_json::json!(-1))
3564            .unwrap_err();
3565        assert!(err_u32_neg.to_string().contains("out of u32 range"));
3566        let err_u32_high = dt_u32
3567            .parse_and_store_default(&serde_json::json!(u32::MAX as i64 + 1))
3568            .unwrap_err();
3569        assert!(err_u32_high.to_string().contains("out of u32 range"));
3570    }
3571
3572    #[test]
3573    fn test_validate_and_store_default_fixed_decimal_interval() {
3574        let mut dt_fixed = AvroDataType::new(Codec::Fixed(4), HashMap::new(), None);
3575        let l = dt_fixed
3576            .parse_and_store_default(&json_string("WXYZ"))
3577            .unwrap();
3578        assert_eq!(l, AvroLiteral::Bytes(vec![87, 88, 89, 90]));
3579        let err = dt_fixed
3580            .parse_and_store_default(&json_string("TOO LONG"))
3581            .unwrap_err();
3582        assert!(err.to_string().contains("Default length"));
3583        let mut dt_dec_fixed =
3584            AvroDataType::new(Codec::Decimal(10, Some(2), Some(3)), HashMap::new(), None);
3585        let l = dt_dec_fixed
3586            .parse_and_store_default(&json_string("abc"))
3587            .unwrap();
3588        assert_eq!(l, AvroLiteral::Bytes(vec![97, 98, 99]));
3589        let err = dt_dec_fixed
3590            .parse_and_store_default(&json_string("toolong"))
3591            .unwrap_err();
3592        assert!(err.to_string().contains("Default length"));
3593        let mut dt_dec_bytes =
3594            AvroDataType::new(Codec::Decimal(10, Some(2), None), HashMap::new(), None);
3595        let l = dt_dec_bytes
3596            .parse_and_store_default(&json_string("freeform"))
3597            .unwrap();
3598        assert_eq!(
3599            l,
3600            AvroLiteral::Bytes("freeform".bytes().collect::<Vec<_>>())
3601        );
3602        let mut dt_interval = AvroDataType::new(Codec::Interval, HashMap::new(), None);
3603        let l = dt_interval
3604            .parse_and_store_default(&json_string("ABCDEFGHIJKL"))
3605            .unwrap();
3606        assert_eq!(
3607            l,
3608            AvroLiteral::Bytes("ABCDEFGHIJKL".bytes().collect::<Vec<_>>())
3609        );
3610        let err = dt_interval
3611            .parse_and_store_default(&json_string("short"))
3612            .unwrap_err();
3613        assert!(err.to_string().contains("Default length"));
3614    }
3615
3616    #[test]
3617    fn test_validate_and_store_default_enum_list_map_struct() {
3618        let symbols: Arc<[String]> = ["RED".to_string(), "GREEN".to_string(), "BLUE".to_string()]
3619            .into_iter()
3620            .collect();
3621        let mut dt_enum = AvroDataType::new(Codec::Enum(symbols), HashMap::new(), None);
3622        let l = dt_enum
3623            .parse_and_store_default(&json_string("GREEN"))
3624            .unwrap();
3625        assert_eq!(l, AvroLiteral::Enum("GREEN".into()));
3626        let err = dt_enum
3627            .parse_and_store_default(&json_string("YELLOW"))
3628            .unwrap_err();
3629        assert!(err.to_string().contains("Default enum symbol"));
3630        let item = AvroDataType::new(Codec::Int64, HashMap::new(), None);
3631        let mut dt_list = AvroDataType::new(Codec::List(Arc::new(item)), HashMap::new(), None);
3632        let val = serde_json::json!([1, 2, 3]);
3633        let l = dt_list.parse_and_store_default(&val).unwrap();
3634        assert_eq!(
3635            l,
3636            AvroLiteral::Array(vec![
3637                AvroLiteral::Long(1),
3638                AvroLiteral::Long(2),
3639                AvroLiteral::Long(3)
3640            ])
3641        );
3642        let err = dt_list
3643            .parse_and_store_default(&serde_json::json!({"not":"array"}))
3644            .unwrap_err();
3645        assert!(err.to_string().contains("JSON array"));
3646        let val_dt = AvroDataType::new(Codec::Float64, HashMap::new(), None);
3647        let mut dt_map = AvroDataType::new(Codec::Map(Arc::new(val_dt)), HashMap::new(), None);
3648        let mv = serde_json::json!({"x": 1.5, "y": 2.5});
3649        let l = dt_map.parse_and_store_default(&mv).unwrap();
3650        let mut expected = IndexMap::new();
3651        expected.insert("x".into(), AvroLiteral::Double(1.5));
3652        expected.insert("y".into(), AvroLiteral::Double(2.5));
3653        assert_eq!(l, AvroLiteral::Map(expected));
3654        // Not object -> error
3655        let err = dt_map
3656            .parse_and_store_default(&serde_json::json!(123))
3657            .unwrap_err();
3658        assert!(err.to_string().contains("JSON object"));
3659        let mut field_a = AvroField {
3660            name: "a".into(),
3661            data_type: AvroDataType::new(Codec::Int32, HashMap::new(), None),
3662        };
3663        let field_b = AvroField {
3664            name: "b".into(),
3665            data_type: AvroDataType::new(
3666                Codec::Int64,
3667                HashMap::new(),
3668                Some(Nullability::NullFirst),
3669            ),
3670        };
3671        let mut c_md = HashMap::new();
3672        c_md.insert(AVRO_FIELD_DEFAULT_METADATA_KEY.into(), "\"xyz\"".into());
3673        let field_c = AvroField {
3674            name: "c".into(),
3675            data_type: AvroDataType::new(Codec::Utf8, c_md, None),
3676        };
3677        field_a.data_type.metadata.insert("doc".into(), "na".into());
3678        let struct_fields: Arc<[AvroField]> = Arc::from(vec![field_a, field_b, field_c]);
3679        let mut dt_struct = AvroDataType::new(Codec::Struct(struct_fields), HashMap::new(), None);
3680        let default_obj = serde_json::json!({"a": 7});
3681        let l = dt_struct.parse_and_store_default(&default_obj).unwrap();
3682        let mut expected = IndexMap::new();
3683        expected.insert("a".into(), AvroLiteral::Int(7));
3684        expected.insert("b".into(), AvroLiteral::Null);
3685        expected.insert("c".into(), AvroLiteral::String("xyz".into()));
3686        assert_eq!(l, AvroLiteral::Map(expected));
3687        assert_default_stored(&dt_struct, &default_obj);
3688        let req_field = AvroField {
3689            name: "req".into(),
3690            data_type: AvroDataType::new(Codec::Boolean, HashMap::new(), None),
3691        };
3692        let mut dt_bad = AvroDataType::new(
3693            Codec::Struct(Arc::from(vec![req_field])),
3694            HashMap::new(),
3695            None,
3696        );
3697        let err = dt_bad
3698            .parse_and_store_default(&serde_json::json!({}))
3699            .unwrap_err();
3700        assert!(
3701            err.to_string().contains("missing required subfield 'req'"),
3702            "unexpected error: {err}"
3703        );
3704        let err = dt_struct
3705            .parse_and_store_default(&serde_json::json!(10))
3706            .unwrap_err();
3707        err.to_string().contains("must be a JSON object");
3708    }
3709
3710    #[test]
3711    fn test_resolve_array_promotion_and_reader_metadata() {
3712        let mut w_add: HashMap<&str, Value> = HashMap::new();
3713        w_add.insert("who", json_string("writer"));
3714        let mut r_add: HashMap<&str, Value> = HashMap::new();
3715        r_add.insert("who", json_string("reader"));
3716        let writer_schema = Schema::Complex(ComplexType::Array(Array {
3717            items: Box::new(Schema::TypeName(TypeName::Primitive(PrimitiveType::Int))),
3718            attributes: Attributes {
3719                logical_type: None,
3720                additional: w_add,
3721            },
3722        }));
3723        let reader_schema = Schema::Complex(ComplexType::Array(Array {
3724            items: Box::new(Schema::TypeName(TypeName::Primitive(PrimitiveType::Long))),
3725            attributes: Attributes {
3726                logical_type: None,
3727                additional: r_add,
3728            },
3729        }));
3730        let mut maker = Maker::new(false, false, Tz::default());
3731        let dt = maker
3732            .make_data_type(&writer_schema, Some(&reader_schema), None)
3733            .unwrap();
3734        assert_eq!(dt.metadata.get("who"), Some(&"\"reader\"".to_string()));
3735        if let Codec::List(inner) = dt.codec() {
3736            assert!(matches!(inner.codec(), Codec::Int64));
3737            assert_eq!(
3738                inner.resolution,
3739                Some(ResolutionInfo::Promotion(Promotion::IntToLong))
3740            );
3741        } else {
3742            panic!("expected list codec");
3743        }
3744    }
3745
3746    #[test]
3747    fn test_resolve_array_writer_nonunion_items_reader_nullable_items() {
3748        let writer_schema = Schema::Complex(ComplexType::Array(Array {
3749            items: Box::new(Schema::TypeName(TypeName::Primitive(PrimitiveType::Int))),
3750            attributes: Attributes::default(),
3751        }));
3752        let reader_schema = Schema::Complex(ComplexType::Array(Array {
3753            items: Box::new(mk_union(vec![
3754                Schema::TypeName(TypeName::Primitive(PrimitiveType::Null)),
3755                Schema::TypeName(TypeName::Primitive(PrimitiveType::Int)),
3756            ])),
3757            attributes: Attributes::default(),
3758        }));
3759        let mut maker = Maker::new(false, false, Tz::default());
3760        let dt = maker
3761            .make_data_type(&writer_schema, Some(&reader_schema), None)
3762            .unwrap();
3763        if let Codec::List(inner) = dt.codec() {
3764            assert_eq!(inner.nullability(), Some(Nullability::NullFirst));
3765            assert!(matches!(inner.codec(), Codec::Int32));
3766            match inner.resolution.as_ref() {
3767                Some(ResolutionInfo::Promotion(Promotion::Direct)) => {}
3768                other => panic!("expected Union resolution, got {other:?}"),
3769            }
3770        } else {
3771            panic!("expected List codec");
3772        }
3773    }
3774
3775    #[test]
3776    fn test_resolve_fixed_success_name_and_size_match_and_alias() {
3777        let writer_schema = Schema::Complex(ComplexType::Fixed(Fixed {
3778            name: "MD5",
3779            namespace: None,
3780            aliases: vec!["Hash16"],
3781            size: 16,
3782            attributes: Attributes::default(),
3783        }));
3784        let reader_schema = Schema::Complex(ComplexType::Fixed(Fixed {
3785            name: "Hash16",
3786            namespace: None,
3787            aliases: vec![],
3788            size: 16,
3789            attributes: Attributes::default(),
3790        }));
3791        let mut maker = Maker::new(false, false, Tz::default());
3792        let dt = maker
3793            .make_data_type(&writer_schema, Some(&reader_schema), None)
3794            .unwrap();
3795        assert!(matches!(dt.codec(), Codec::Fixed(16)));
3796    }
3797
3798    #[cfg(feature = "avro_custom_types")]
3799    #[test]
3800    fn test_interval_month_day_nano_custom_logical_type_fixed16() {
3801        let schema = Schema::Complex(ComplexType::Fixed(Fixed {
3802            name: "ArrowIntervalMDN",
3803            namespace: None,
3804            aliases: vec![],
3805            size: 16,
3806            attributes: Attributes {
3807                logical_type: Some("arrow.interval-month-day-nano"),
3808                additional: Default::default(),
3809            },
3810        }));
3811        let mut maker = Maker::new(false, false, Default::default());
3812        let dt = maker.make_data_type(&schema, None, None).unwrap();
3813        assert!(matches!(dt.codec(), Codec::IntervalMonthDayNano));
3814        assert_eq!(
3815            dt.codec.data_type(),
3816            DataType::Interval(IntervalUnit::MonthDayNano)
3817        );
3818    }
3819
3820    #[test]
3821    fn test_resolve_records_mapping_default_fields_and_skip_fields() {
3822        let writer = Schema::Complex(ComplexType::Record(Record {
3823            name: "R",
3824            namespace: None,
3825            doc: None,
3826            aliases: vec![],
3827            fields: vec![
3828                crate::schema::Field {
3829                    name: "a",
3830                    doc: None,
3831                    r#type: Schema::TypeName(TypeName::Primitive(PrimitiveType::Int)),
3832                    default: None,
3833                    aliases: vec![],
3834                },
3835                crate::schema::Field {
3836                    name: "skipme",
3837                    doc: None,
3838                    r#type: Schema::TypeName(TypeName::Primitive(PrimitiveType::String)),
3839                    default: None,
3840                    aliases: vec![],
3841                },
3842                crate::schema::Field {
3843                    name: "b",
3844                    doc: None,
3845                    r#type: Schema::TypeName(TypeName::Primitive(PrimitiveType::Long)),
3846                    default: None,
3847                    aliases: vec![],
3848                },
3849            ],
3850            attributes: Attributes::default(),
3851        }));
3852        let reader = Schema::Complex(ComplexType::Record(Record {
3853            name: "R",
3854            namespace: None,
3855            doc: None,
3856            aliases: vec![],
3857            fields: vec![
3858                crate::schema::Field {
3859                    name: "b",
3860                    doc: None,
3861                    r#type: Schema::TypeName(TypeName::Primitive(PrimitiveType::Long)),
3862                    default: None,
3863                    aliases: vec![],
3864                },
3865                crate::schema::Field {
3866                    name: "a",
3867                    doc: None,
3868                    r#type: Schema::TypeName(TypeName::Primitive(PrimitiveType::Long)),
3869                    default: None,
3870                    aliases: vec![],
3871                },
3872                crate::schema::Field {
3873                    name: "name",
3874                    doc: None,
3875                    r#type: Schema::TypeName(TypeName::Primitive(PrimitiveType::String)),
3876                    default: Some(json_string("anon")),
3877                    aliases: vec![],
3878                },
3879                crate::schema::Field {
3880                    name: "opt",
3881                    doc: None,
3882                    r#type: Schema::Union(vec![
3883                        Schema::TypeName(TypeName::Primitive(PrimitiveType::Null)),
3884                        Schema::TypeName(TypeName::Primitive(PrimitiveType::Int)),
3885                    ]),
3886                    default: None, // should default to null because NullFirst
3887                    aliases: vec![],
3888                },
3889            ],
3890            attributes: Attributes::default(),
3891        }));
3892        let mut maker = Maker::new(false, false, Tz::default());
3893        let dt = maker
3894            .make_data_type(&writer, Some(&reader), None)
3895            .expect("record resolution");
3896        let fields = match dt.codec() {
3897            Codec::Struct(f) => f,
3898            other => panic!("expected struct, got {other:?}"),
3899        };
3900        assert_eq!(fields.len(), 4);
3901        assert_eq!(fields[0].name(), "b");
3902        assert_eq!(fields[1].name(), "a");
3903        assert_eq!(fields[2].name(), "name");
3904        assert_eq!(fields[3].name(), "opt");
3905        assert!(matches!(
3906            fields[1].data_type().resolution,
3907            Some(ResolutionInfo::Promotion(Promotion::IntToLong))
3908        ));
3909        let rec = match dt.resolution {
3910            Some(ResolutionInfo::Record(ref r)) => r.clone(),
3911            other => panic!("expected record resolution, got {other:?}"),
3912        };
3913        assert!(matches!(
3914            &rec.writer_fields[..],
3915            &[
3916                ResolvedField::ToReader(1, _),
3917                ResolvedField::Skip(_),
3918                ResolvedField::ToReader(0, _),
3919            ]
3920        ));
3921        assert_eq!(rec.default_fields.as_ref(), &[2usize, 3usize]);
3922        let ResolvedField::Skip(skip1) = &rec.writer_fields[1] else {
3923            panic!("should skip field 1")
3924        };
3925        assert!(matches!(skip1.codec(), Codec::Utf8));
3926        let name_md = &fields[2].data_type().metadata;
3927        assert_eq!(
3928            name_md.get(AVRO_FIELD_DEFAULT_METADATA_KEY),
3929            Some(&"\"anon\"".to_string())
3930        );
3931        let opt_md = &fields[3].data_type().metadata;
3932        assert_eq!(
3933            opt_md.get(AVRO_FIELD_DEFAULT_METADATA_KEY),
3934            Some(&"null".to_string())
3935        );
3936    }
3937
3938    #[test]
3939    fn test_named_type_alias_resolution_record_cross_namespace() {
3940        let writer_record = Record {
3941            name: "PersonV2",
3942            namespace: Some("com.example.v2"),
3943            doc: None,
3944            aliases: vec!["com.example.Person"],
3945            fields: vec![
3946                AvroFieldSchema {
3947                    name: "name",
3948                    doc: None,
3949                    r#type: Schema::TypeName(TypeName::Primitive(PrimitiveType::String)),
3950                    default: None,
3951                    aliases: vec![],
3952                },
3953                AvroFieldSchema {
3954                    name: "age",
3955                    doc: None,
3956                    r#type: Schema::TypeName(TypeName::Primitive(PrimitiveType::Int)),
3957                    default: None,
3958                    aliases: vec![],
3959                },
3960            ],
3961            attributes: Attributes::default(),
3962        };
3963        let reader_record = Record {
3964            name: "Person",
3965            namespace: Some("com.example"),
3966            doc: None,
3967            aliases: vec![],
3968            fields: writer_record.fields.clone(),
3969            attributes: Attributes::default(),
3970        };
3971        let writer_schema = Schema::Complex(ComplexType::Record(writer_record));
3972        let reader_schema = Schema::Complex(ComplexType::Record(reader_record));
3973        let mut maker = Maker::new(false, false, Tz::default());
3974        let result = maker
3975            .make_data_type(&writer_schema, Some(&reader_schema), None)
3976            .expect("record alias resolution should succeed");
3977        match result.codec {
3978            Codec::Struct(ref fields) => assert_eq!(fields.len(), 2),
3979            other => panic!("expected struct, got {other:?}"),
3980        }
3981    }
3982
3983    #[test]
3984    fn test_named_type_alias_resolution_enum_cross_namespace() {
3985        let writer_enum = Enum {
3986            name: "ColorV2",
3987            namespace: Some("org.example.v2"),
3988            doc: None,
3989            aliases: vec!["org.example.Color"],
3990            symbols: vec!["RED", "GREEN", "BLUE"],
3991            default: None,
3992            attributes: Attributes::default(),
3993        };
3994        let reader_enum = Enum {
3995            name: "Color",
3996            namespace: Some("org.example"),
3997            doc: None,
3998            aliases: vec![],
3999            symbols: vec!["RED", "GREEN", "BLUE"],
4000            default: None,
4001            attributes: Attributes::default(),
4002        };
4003        let writer_schema = Schema::Complex(ComplexType::Enum(writer_enum));
4004        let reader_schema = Schema::Complex(ComplexType::Enum(reader_enum));
4005        let mut maker = Maker::new(false, false, Tz::default());
4006        maker
4007            .make_data_type(&writer_schema, Some(&reader_schema), None)
4008            .expect("enum alias resolution should succeed");
4009    }
4010
4011    #[test]
4012    fn test_named_type_alias_resolution_fixed_cross_namespace() {
4013        let writer_fixed = Fixed {
4014            name: "Fx10V2",
4015            namespace: Some("ns.v2"),
4016            aliases: vec!["ns.Fx10"],
4017            size: 10,
4018            attributes: Attributes::default(),
4019        };
4020        let reader_fixed = Fixed {
4021            name: "Fx10",
4022            namespace: Some("ns"),
4023            aliases: vec![],
4024            size: 10,
4025            attributes: Attributes::default(),
4026        };
4027        let writer_schema = Schema::Complex(ComplexType::Fixed(writer_fixed));
4028        let reader_schema = Schema::Complex(ComplexType::Fixed(reader_fixed));
4029        let mut maker = Maker::new(false, false, Tz::default());
4030        maker
4031            .make_data_type(&writer_schema, Some(&reader_schema), None)
4032            .expect("fixed alias resolution should succeed");
4033    }
4034}