qubit-json 0.12.2

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Defines the serializer decorator for JSON object keys.

use std::cell::RefCell;
use std::fmt::Display;

use qubit_budget::ResourceQuantity;
use qubit_budget::json::JsonMeasurement;
use serde::Serialize;
use serde::Serializer;

use super::DisplayBudgetKind;
use super::JsonEncodeContext;
use crate::encode::JsonMapKeyKind;
use crate::encode::JsonSerializationErrorKind;
use crate::internal::JsonLexemeLength;
use crate::internal::JsonMapKey;

/// Decorates serde_json's map-key serializer with key-byte checks.
///
/// # Type Parameters
///
/// * `'context` - Lifetime of the shared traversal context borrow.
/// * `'transaction` - Lifetime of the underlying encoding transaction.
/// * `'budget` - Lifetime of the resource budget used by that transaction.
/// * `S` - Underlying Serde serializer receiving supported key values.
/// * `R` - Resource identity used by the encoding budget.
/// * `Q` - Quantity representation used by the encoding budget.
/// * `VALUE_LIMITS` - Whether emitted key lengths consume the value budget.
pub(in crate::encode::serializer) struct JsonKeyBudgetSerializer<
    'context,
    'transaction,
    'budget,
    S,
    R,
    Q,
    const VALUE_LIMITS: bool,
> where
    Q: ResourceQuantity,
{
    /// Underlying map-key serializer.
    pub(in crate::encode::serializer) inner: S,

    /// Shared traversal context.
    pub(in crate::encode::serializer) context:
        &'context RefCell<JsonEncodeContext<'transaction, 'budget, R, Q>>,
}

impl<S, R, Q, const VALUE_LIMITS: bool> JsonKeyBudgetSerializer<'_, '_, '_, S, R, Q, VALUE_LIMITS>
where
    S: Serializer,
    R: Clone,
    Q: ResourceQuantity,
{
    /// Checks and consumes one emitted key length, retaining any original
    /// error.
    ///
    /// # Parameters
    ///
    /// * `bytes` — UTF-8 byte length of the emitted key.
    ///
    /// # Returns
    ///
    /// `Ok(())` when no value limit applies or the key length is admitted.
    ///
    /// # Errors
    ///
    /// Returns the underlying serializer error created by the shared context
    /// when the value budget rejects the key.
    fn check(&self, bytes: usize) -> Result<(), S::Error> {
        if !VALUE_LIMITS {
            return Ok(());
        }
        self.context
            .borrow_mut()
            .admit(JsonMeasurement::Key { bytes })
    }

    /// Rejects one unsupported key shape through the shared stable error.
    ///
    /// # Parameters
    ///
    /// * `kind` — Unsupported map-key shape to report.
    ///
    /// # Returns
    ///
    /// The underlying serializer error for the unsupported key.
    fn unsupported(&self, kind: JsonMapKeyKind) -> S::Error {
        self.context
            .borrow_mut()
            .serialization_error(JsonSerializationErrorKind::UnsupportedMapKey { kind })
    }

    /// Rejects one non-finite key through the shared numeric error.
    ///
    /// # Returns
    ///
    /// The underlying serializer error for a non-finite float key.
    fn non_finite(&self) -> S::Error {
        self.context
            .borrow_mut()
            .serialization_error(JsonSerializationErrorKind::NonFiniteFloat)
    }
}

macro_rules! serialize_key_number {
    ($name:ident, signed $type:ty) => {
        #[doc = "Checks the serialized signed key length before forwarding it."]
        #[doc = ""]
        #[doc = "# Parameters"]
        #[doc = ""]
        #[doc = "* `value` — Signed integer key to serialize."]
        fn $name(self, value: $type) -> Result<Self::Ok, Self::Error> {
            if VALUE_LIMITS {
                self.check(JsonLexemeLength::signed_integer(value.into()))?;
            }
            self.inner.$name(value)
        }
    };
    ($name:ident, unsigned $type:ty) => {
        #[doc = "Checks the serialized unsigned key length before forwarding it."]
        #[doc = ""]
        #[doc = "# Parameters"]
        #[doc = ""]
        #[doc = "* `value` — Unsigned integer key to serialize."]
        fn $name(self, value: $type) -> Result<Self::Ok, Self::Error> {
            if VALUE_LIMITS {
                self.check(JsonLexemeLength::unsigned_integer(value.into()))?;
            }
            self.inner.$name(value)
        }
    };
}

impl<'context, 'transaction, 'budget, S, R, Q, const VALUE_LIMITS: bool> Serializer
    for JsonKeyBudgetSerializer<'context, 'transaction, 'budget, S, R, Q, VALUE_LIMITS>
where
    S: Serializer,
    R: Clone,
    Q: ResourceQuantity,
{
    /// Output type produced by the underlying serializer.
    type Ok = S::Ok;
    /// Error type returned by the underlying serializer.
    type Error = S::Error;
    /// Sequence serializer type supplied by the underlying serializer.
    type SerializeSeq = S::SerializeSeq;
    /// Tuple serializer type supplied by the underlying serializer.
    type SerializeTuple = S::SerializeTuple;
    /// Tuple-struct serializer type supplied by the underlying serializer.
    type SerializeTupleStruct = S::SerializeTupleStruct;
    /// Tuple-variant serializer type supplied by the underlying serializer.
    type SerializeTupleVariant = S::SerializeTupleVariant;
    /// Map serializer type supplied by the underlying serializer.
    type SerializeMap = S::SerializeMap;
    /// Struct serializer type supplied by the underlying serializer.
    type SerializeStruct = S::SerializeStruct;
    /// Struct-variant serializer type supplied by the underlying serializer.
    type SerializeStructVariant = S::SerializeStructVariant;

    /// Checks the boolean key length before forwarding it.
    ///
    /// # Parameters
    ///
    /// * `value` — Boolean key to serialize.
    fn serialize_bool(self, value: bool) -> Result<Self::Ok, Self::Error> {
        self.check(if value { 4 } else { 5 })?;
        self.inner.serialize_bool(value)
    }

    serialize_key_number!(serialize_i8, signed i8);
    serialize_key_number!(serialize_i16, signed i16);
    serialize_key_number!(serialize_i32, signed i32);
    serialize_key_number!(serialize_i64, signed i64);
    serialize_key_number!(serialize_u8, unsigned u8);
    serialize_key_number!(serialize_u16, unsigned u16);
    serialize_key_number!(serialize_u32, unsigned u32);
    serialize_key_number!(serialize_u64, unsigned u64);

    /// Charges and emits one full-range signed integer key as decimal text.
    ///
    /// # Parameters
    ///
    /// * `value` — Signed integer key to serialize.
    fn serialize_i128(self, value: i128) -> Result<Self::Ok, Self::Error> {
        let text = JsonMapKey::signed_wide(value);
        if VALUE_LIMITS {
            self.check(text.len())?;
        }
        self.inner.serialize_str(&text)
    }

    /// Charges and emits one full-range unsigned integer key as decimal text.
    ///
    /// # Parameters
    ///
    /// * `value` — Unsigned integer key to serialize.
    fn serialize_u128(self, value: u128) -> Result<Self::Ok, Self::Error> {
        let text = JsonMapKey::unsigned_wide(value);
        if VALUE_LIMITS {
            self.check(text.len())?;
        }
        self.inner.serialize_str(&text)
    }

    /// Checks a finite `f32` key length before forwarding it.
    ///
    /// # Parameters
    ///
    /// * `value` — Finite floating-point key to serialize.
    fn serialize_f32(self, value: f32) -> Result<Self::Ok, Self::Error> {
        if !value.is_finite() {
            return Err(self.non_finite());
        }
        if VALUE_LIMITS {
            self.check(JsonLexemeLength::finite_f32(value))?;
        }
        self.inner.serialize_f32(value)
    }

    /// Checks a finite `f64` key length before forwarding it.
    ///
    /// # Parameters
    ///
    /// * `value` — Finite floating-point key to serialize.
    fn serialize_f64(self, value: f64) -> Result<Self::Ok, Self::Error> {
        if !value.is_finite() {
            return Err(self.non_finite());
        }
        if VALUE_LIMITS {
            self.check(JsonLexemeLength::finite_f64(value))?;
        }
        self.inner.serialize_f64(value)
    }

    /// Checks the UTF-8 key length before forwarding a character.
    ///
    /// # Parameters
    ///
    /// * `value` — Character key to serialize.
    fn serialize_char(self, value: char) -> Result<Self::Ok, Self::Error> {
        if VALUE_LIMITS {
            self.check(value.len_utf8())?;
        }
        self.inner.serialize_char(value)
    }

    /// Checks the string key length before forwarding it.
    ///
    /// # Parameters
    ///
    /// * `value` — String key to serialize.
    fn serialize_str(self, value: &str) -> Result<Self::Ok, Self::Error> {
        if VALUE_LIMITS {
            self.check(value.len())?;
        }
        self.inner.serialize_str(value)
    }

    /// Rejects byte keys as unsupported JSON object keys.
    ///
    /// # Parameters
    ///
    /// * `_value` — Byte sequence, which JSON object keys do not support.
    fn serialize_bytes(self, _value: &[u8]) -> Result<Self::Ok, Self::Error> {
        Err(self.unsupported(JsonMapKeyKind::Bytes))
    }

    /// Rejects an absent optional key as unsupported.
    fn serialize_none(self) -> Result<Self::Ok, Self::Error> {
        Err(self.unsupported(JsonMapKeyKind::None))
    }

    /// Serializes a present optional key through this decorator.
    ///
    /// # Type Parameters
    ///
    /// * `T` — Serializable type of the optional key value.
    ///
    /// # Parameters
    ///
    /// * `value` — Present key value to serialize through this decorator.
    fn serialize_some<T>(self, value: &T) -> Result<Self::Ok, Self::Error>
    where
        T: Serialize + ?Sized,
    {
        value.serialize(self)
    }

    /// Rejects a unit key as unsupported.
    fn serialize_unit(self) -> Result<Self::Ok, Self::Error> {
        Err(self.unsupported(JsonMapKeyKind::Unit))
    }

    /// Rejects a unit-struct key as unsupported.
    ///
    /// # Parameters
    ///
    /// * `_name` — Unit-struct name supplied by Serde.
    fn serialize_unit_struct(self, _name: &'static str) -> Result<Self::Ok, Self::Error> {
        Err(self.unsupported(JsonMapKeyKind::UnitStruct))
    }

    /// Checks a unit-variant key name before forwarding it.
    ///
    /// # Parameters
    ///
    /// * `name` — Enum name supplied by Serde.
    /// * `variant_index` — Variant index supplied by Serde.
    /// * `variant` — Variant name emitted as the key.
    fn serialize_unit_variant(
        self,
        name: &'static str,
        variant_index: u32,
        variant: &'static str,
    ) -> Result<Self::Ok, Self::Error> {
        if VALUE_LIMITS {
            self.check(variant.len())?;
        }
        self.inner
            .serialize_unit_variant(name, variant_index, variant)
    }

    /// Serializes a newtype key through this decorator.
    ///
    /// # Type Parameters
    ///
    /// * `T` — Serializable type wrapped by the newtype.
    ///
    /// # Parameters
    ///
    /// * `_name` — Newtype name supplied by Serde.
    /// * `value` — Wrapped value to serialize through this decorator.
    fn serialize_newtype_struct<T>(
        self,
        _name: &'static str,
        value: &T,
    ) -> Result<Self::Ok, Self::Error>
    where
        T: Serialize + ?Sized,
    {
        value.serialize(self)
    }

    /// Rejects newtype-variant keys as unsupported JSON object keys.
    ///
    /// # Type Parameters
    ///
    /// * `T` — Serializable type of the rejected variant value.
    ///
    /// # Parameters
    ///
    /// * `_name` — Enum name supplied by Serde.
    /// * `_variant_index` — Variant index supplied by Serde.
    /// * `_variant` — Variant name supplied by Serde.
    /// * `_value` — Variant payload, which JSON object keys do not support.
    fn serialize_newtype_variant<T>(
        self,
        _name: &'static str,
        _variant_index: u32,
        _variant: &'static str,
        _value: &T,
    ) -> Result<Self::Ok, Self::Error>
    where
        T: Serialize + ?Sized,
    {
        Err(self.unsupported(JsonMapKeyKind::NewtypeVariant))
    }

    /// Rejects sequence keys as unsupported JSON object keys.
    ///
    /// # Parameters
    ///
    /// * `_len` — Optional sequence length hint supplied by Serde.
    fn serialize_seq(self, _len: Option<usize>) -> Result<Self::SerializeSeq, Self::Error> {
        Err(self.unsupported(JsonMapKeyKind::Sequence))
    }

    /// Rejects tuple keys as unsupported JSON object keys.
    ///
    /// # Parameters
    ///
    /// * `_len` — Tuple element count supplied by Serde.
    fn serialize_tuple(self, _len: usize) -> Result<Self::SerializeTuple, Self::Error> {
        Err(self.unsupported(JsonMapKeyKind::Tuple))
    }

    /// Rejects tuple-struct keys as unsupported JSON object keys.
    ///
    /// # Parameters
    ///
    /// * `_name` — Tuple-struct name supplied by Serde.
    /// * `_len` — Tuple-struct field count supplied by Serde.
    fn serialize_tuple_struct(
        self,
        _name: &'static str,
        _len: usize,
    ) -> Result<Self::SerializeTupleStruct, Self::Error> {
        Err(self.unsupported(JsonMapKeyKind::TupleStruct))
    }

    /// Rejects tuple-variant keys as unsupported JSON object keys.
    ///
    /// # Parameters
    ///
    /// * `_name` — Enum name supplied by Serde.
    /// * `_variant_index` — Variant index supplied by Serde.
    /// * `_variant` — Variant name supplied by Serde.
    /// * `_len` — Variant field count supplied by Serde.
    fn serialize_tuple_variant(
        self,
        _name: &'static str,
        _variant_index: u32,
        _variant: &'static str,
        _len: usize,
    ) -> Result<Self::SerializeTupleVariant, Self::Error> {
        Err(self.unsupported(JsonMapKeyKind::TupleVariant))
    }

    /// Rejects map keys as unsupported JSON object keys.
    ///
    /// # Parameters
    ///
    /// * `_len` — Optional map length hint supplied by Serde.
    fn serialize_map(self, _len: Option<usize>) -> Result<Self::SerializeMap, Self::Error> {
        Err(self.unsupported(JsonMapKeyKind::Map))
    }

    /// Rejects struct keys as unsupported JSON object keys.
    ///
    /// # Parameters
    ///
    /// * `_name` — Struct name supplied by Serde.
    /// * `_len` — Struct field count supplied by Serde.
    fn serialize_struct(
        self,
        _name: &'static str,
        _len: usize,
    ) -> Result<Self::SerializeStruct, Self::Error> {
        Err(self.unsupported(JsonMapKeyKind::Struct))
    }

    /// Rejects struct-variant keys as unsupported JSON object keys.
    ///
    /// # Parameters
    ///
    /// * `_name` — Enum name supplied by Serde.
    /// * `_variant_index` — Variant index supplied by Serde.
    /// * `_variant` — Variant name supplied by Serde.
    /// * `_len` — Variant field count supplied by Serde.
    fn serialize_struct_variant(
        self,
        _name: &'static str,
        _variant_index: u32,
        _variant: &'static str,
        _len: usize,
    ) -> Result<Self::SerializeStructVariant, Self::Error> {
        Err(self.unsupported(JsonMapKeyKind::StructVariant))
    }

    /// Formats, accounts, and forwards a display-based key.
    ///
    /// # Type Parameters
    ///
    /// * `T` — Displayable value whose formatted text becomes the key.
    ///
    /// # Parameters
    ///
    /// * `value` — Value formatted and serialized as the key.
    fn collect_str<T>(self, value: &T) -> Result<Self::Ok, Self::Error>
    where
        T: Display + ?Sized,
    {
        let text = JsonEncodeContext::collect_display::<S::Error, _>(
            self.context,
            value,
            DisplayBudgetKind::Key,
            1,
        )?;
        self.inner.serialize_str(&text)
    }

    /// Reports the underlying serializer's human-readable mode.
    #[inline(always)]
    fn is_human_readable(&self) -> bool {
        self.inner.is_human_readable()
    }
}