ix_schema/

lib.rs

//! # ix-schema — a universal meta-interface for data structures
//!
//! `ix-schema` does not serialize anything itself. It is an **orchestrator**: a
//! `#[derive(Ix)]` type publishes a compile-time [`Manifest`] describing its
//! fields, memory layout and schema evolution. *Drivers* (adapters around
//! `serde`, `zerocopy`, …) read that manifest and do the real work, branching on
//! `const` data that folds away — no reflection, no runtime schema parsing.
//!
//! The crate is `#![no_std]` for normal builds; everything the manifest carries
//! is `const` and therefore free at runtime.
//!
//! ## The two manifests
//!
//! There are two strictly separate representations:
//!
//! * the **compile-time IR** that lives only inside the `ix-schema-derive` proc-macro
//!   while it analyses a struct, and
//! * the **`const` [`Manifest`]** emitted into your crate, read by drivers.
//!
//! This crate defines the second one — the contract every driver speaks.
#![cfg_attr(not(test), no_std)]
#![forbid(unsafe_code)]
#![warn(missing_docs)]
#![deny(rustdoc::broken_intra_doc_links, rustdoc::private_intra_doc_links)]

/// Derive a compile-time [`Manifest`] (and, with `migrate_from`, a type-safe
/// migration edge) for a struct or enum. See the crate-level docs for the
/// attributes.
pub use ix_schema_derive::Ix;

/// The compile-time description of a `#[derive(Ix)]` type.
///
/// Every field is `const`-foldable. Layout figures (size, align, offsets) are
/// produced by the compiler via [`core::mem`] in const context, so the manifest
/// is *guaranteed* to match the real in-memory layout — it is computed by the
/// same compiler that lays out the struct.
pub trait Ix {
    /// The semantic manifest for this type and schema version.
    const MANIFEST: Manifest<'static>;
}

/// A type-safe, compile-time migration edge from an older schema version `Prev`.
///
/// Modelled after [`From`]: `V2: MigrateFrom<V1>` declares that a `V1` value can
/// be lifted to `V2`. The derive macro generates the body field-by-field, so an
/// impossible transformation becomes a *type error*, not a runtime panic.
pub trait MigrateFrom<Prev: Ix>: Ix + Sized {
    /// Lift a value of the previous schema version into this one.
    fn migrate_from(prev: Prev) -> Self;
}

/// A multi-hop migration from an older schema `Self` to a later one `Target`.
///
/// Where [`MigrateFrom`] is a single edge (`V2` from `V1`), `Upgrade` is a whole
/// path (`V1` all the way to `V3`). Implementations are generated by
/// [`migrate_chain!`] as the composition of single-hop [`MigrateFrom`] calls, so
/// every hop is type-checked and the whole walk inlines to zero runtime cost.
pub trait Upgrade<Target> {
    /// Convert this value to `Target` by composing single-hop migrations.
    fn upgrade(self) -> Target;
}

/// Generate the transitive closure of [`Upgrade`] impls for a schema chain.
///
/// Given adjacent [`MigrateFrom`] edges (typically from `#[derive(Ix)]` with
/// `migrate_from`), this wires up *every* older-to-newer pair by composition —
/// most importantly the direct jump from the oldest version to the newest.
///
/// ```text
/// // V2: MigrateFrom<V1>, V3: MigrateFrom<V2> already exist (derived).
/// ix_schema::migrate_chain!(V1 => V2 => V3);
/// // now: V1: Upgrade<V2>, V2: Upgrade<V3>, and V1: Upgrade<V3> (composed).
/// let v3: V3 = some_v1.upgrade();
/// ```
#[macro_export]
macro_rules! migrate_chain {
    // Public entry: a chain of at least two versions.
    ($first:ty $(=> $rest:ty)+) => {
        $crate::migrate_chain!(@grow [$first] $(=> $rest)+);
    };

    // Inductive step: append `$new`, wiring up every seen type to it. `$pred` is
    // the immediately-previous version; `$older` are the earlier ancestors.
    (@grow [$pred:ty $(, $older:ty)*] => $new:ty $(=> $rest:ty)*) => {
        impl $crate::Upgrade<$new> for $pred {
            fn upgrade(self) -> $new {
                <$new as $crate::MigrateFrom<$pred>>::migrate_from(self)
            }
        }
        $(
            impl $crate::Upgrade<$new> for $older {
                fn upgrade(self) -> $new {
                    <$new as $crate::MigrateFrom<$pred>>::migrate_from(
                        <$older as $crate::Upgrade<$pred>>::upgrade(self),
                    )
                }
            }
        )*
        $crate::migrate_chain!(@grow [$new, $pred $(, $older)*] $(=> $rest)*);
    };

    // Base case: the chain is fully consumed.
    (@grow [$($seen:ty),+]) => {};
}

/// A driver adapts an external representation (serde, zerocopy, …) to any
/// [`Ix`] type by reading its [`Manifest`].
///
/// All capability decisions are `const`: code that branches on
/// [`Driver::SUPPORTED`] is dead-code-eliminated, keeping drivers zero-cost.
pub trait Driver<T: Ix> {
    /// Whether this driver can losslessly handle `T`'s layout and schema.
    const SUPPORTED: bool;
}

/// The semantic manifest: the single source of truth drivers read.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Manifest<'a> {
    /// Fully spelled type name, e.g. `"my_crate::User"`.
    pub type_name: &'a str,
    /// The type's doc comment (joined `///` lines), or `""` if undocumented.
    pub doc: &'a str,
    /// Monotonic schema version (`1` for the first revision).
    pub schema_version: u32,
    /// In-memory layout of the type.
    pub layout: LayoutSpec,
    /// Fields in declaration order (for a struct; empty for an enum).
    pub fields: &'a [FieldSpec<'a>],
    /// Variants in declaration order (for a fieldless enum; empty for a struct).
    pub variants: &'a [VariantSpec<'a>],
    /// How this version relates to its predecessor.
    pub evolution: EvolutionSpec<'a>,
}

impl Manifest<'_> {
    /// Sum of the sizes of all fields, ignoring inter-field padding.
    #[must_use]
    pub const fn packed_field_bytes(&self) -> usize {
        let mut sum = 0;
        let mut i = 0;
        while i < self.fields.len() {
            sum += self.fields[i].size;
            i += 1;
        }
        sum
    }

    /// Bytes of *top-level* padding the compiler inserted between or after this
    /// type's own fields (`size - Σ field sizes`).
    ///
    /// This counts only inter-field and trailing padding at this level. It does
    /// **not** see padding nested *inside* a field's own type, so a struct whose
    /// only field is itself padded reports `0` here. A zerocopy driver therefore
    /// uses this as a necessary cross-check, not as the sole proof of no padding
    /// — the actual guarantee comes from `zerocopy`'s `IntoBytes` bound.
    #[must_use]
    pub const fn padding_bytes(&self) -> usize {
        self.layout.size.saturating_sub(self.packed_field_bytes())
    }

    /// Whether the layout has no *top-level* padding holes (`size` equals the sum
    /// of the field sizes). See [`Manifest::padding_bytes`] for the nested-padding
    /// caveat: a gap-free top level can still wrap a field type that is itself
    /// padded.
    #[must_use]
    pub const fn is_gap_free(&self) -> bool {
        self.padding_bytes() == 0
    }

    /// Whether `self` is a layout-compatible, append-only extension of `prev`:
    /// every field of `prev` is still present *under the same name*, at the same
    /// offset, size and type.
    ///
    /// This is the compile-time precondition for evolving a type while keeping old
    /// readers valid — new fields may only be appended, never inserted, reordered,
    /// resized or retyped. Two strictnesses worth calling out:
    /// * **Name is part of the contract.** Fields are matched by name, so a
    ///   *renamed* field — even at the same offset, size and type — counts as
    ///   absent and fails the check. That is stricter than raw byte layout (a
    ///   rename keeps the bytes) but correct for name-based formats; express a
    ///   rename as a migration (`rename_from`), not as an extension.
    /// * **Type is part of the contract.** A field silently changed from `u32` to
    ///   `f32` keeps the same offset and size but reinterprets the bytes, so it
    ///   must not pass.
    ///
    /// Pair with [`assert_compatible!`].
    #[must_use]
    pub const fn extends(&self, prev: &Manifest<'_>) -> bool {
        let mut i = 0;
        while i < prev.fields.len() {
            let want = prev.fields[i];
            let mut matched = false;
            let mut j = 0;
            while j < self.fields.len() {
                let have = self.fields[j];
                if str_eq(have.name, want.name) {
                    matched = have.offset == want.offset
                        && have.size == want.size
                        && str_eq(have.type_name, want.type_name);
                    break;
                }
                j += 1;
            }
            if !matched {
                return false;
            }
            i += 1;
        }
        true
    }
}

/// `const`-evaluable string equality (`PartialEq` for `str` is not `const`).
const fn str_eq(a: &str, b: &str) -> bool {
    let a = a.as_bytes();
    let b = b.as_bytes();
    if a.len() != b.len() {
        return false;
    }
    let mut i = 0;
    while i < a.len() {
        if a[i] != b[i] {
            return false;
        }
        i += 1;
    }
    true
}

/// Statically assert that `$new` is a layout-compatible, append-only extension
/// of `$old` (see [`Manifest::extends`]). Fails compilation if a carried field
/// was moved, resized or dropped — catching wire-format breakage before runtime.
///
/// ```text
/// ix_schema::assert_compatible!(EventV2 : EventV1);
/// ```
#[macro_export]
macro_rules! assert_compatible {
    ($new:ty : $old:ty) => {
        const _: () = ::core::assert!(
            <$new as $crate::Ix>::MANIFEST.extends(&<$old as $crate::Ix>::MANIFEST),
            ::core::concat!(
                stringify!($new),
                " is not a layout-compatible extension of ",
                stringify!($old),
            ),
        );
    };
}

/// In-memory layout of a type.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct LayoutSpec {
    /// `size_of::<T>()`.
    pub size: usize,
    /// `align_of::<T>()`.
    pub align: usize,
    /// The declared representation.
    pub repr: Repr,
}

/// The `#[repr(..)]` of a type, as far as it affects layout stability.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Repr {
    /// Default Rust representation (layout not guaranteed stable).
    Rust,
    /// `#[repr(C)]` — stable, FFI-compatible layout.
    C,
    /// `#[repr(transparent)]`.
    Transparent,
    /// `#[repr(packed(n))]` with the given alignment.
    Packed(usize),
}

/// Description of a single field within a [`Manifest`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct FieldSpec<'a> {
    /// Field identifier.
    pub name: &'a str,
    /// The field's doc comment (joined `///` lines), or `""` if undocumented.
    pub doc: &'a str,
    /// Spelled type, e.g. `"u32"`.
    pub type_name: &'a str,
    /// Byte offset within the struct (`offset_of!`).
    pub offset: usize,
    /// `size_of` of the field type.
    pub size: usize,
    /// `align_of` of the field type.
    pub align: usize,
    /// Schema version in which the field was introduced.
    pub since: u32,
}

/// How an enum variant carries its payload.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum VariantKind {
    /// No payload — `Variant`.
    Unit,
    /// Positional payload — `Variant(A, B)`.
    Tuple,
    /// Named payload — `Variant { a: A }`.
    Struct,
}

/// Description of a single payload field of a data-carrying enum variant.
///
/// Note the deliberate absence of an `offset`: Rust exposes no `const` way to
/// read the byte offset of a field *within an enum variant* (`offset_of!` covers
/// structs only). Rather than record a number it cannot verify — which would
/// break the manifest's "computed by the compiler, cannot drift" guarantee — ix
/// records only what it can prove: the field's name, spelled type, size and
/// alignment.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct VariantFieldSpec<'a> {
    /// Field name for a struct-like variant; `None` for a tuple position.
    pub name: Option<&'a str>,
    /// Spelled type, e.g. `"u32"`.
    pub type_name: &'a str,
    /// `size_of` of the field type.
    pub size: usize,
    /// `align_of` of the field type.
    pub align: usize,
}

/// Description of a single enum variant.
///
/// A fieldless variant is fully described by its name and discriminant; a
/// data-carrying variant additionally lists its payload [`VariantFieldSpec`]s.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct VariantSpec<'a> {
    /// Variant identifier.
    pub name: &'a str,
    /// The variant's doc comment (joined `///` lines), or `""` if undocumented.
    pub doc: &'a str,
    /// The variant's integer discriminant, when the compiler can evaluate it in
    /// `const`: `Some` for a fieldless enum (emitted as `Self::Variant as i64`),
    /// `None` for a data-carrying enum, whose variants cannot be cast to an int.
    pub discriminant: Option<i64>,
    /// Whether the variant is unit, tuple, or struct shaped.
    pub kind: VariantKind,
    /// The variant's payload fields (empty for a unit variant). Offsets are
    /// intentionally absent — see [`VariantFieldSpec`].
    pub fields: &'a [VariantFieldSpec<'a>],
}

/// How a schema version relates to the one before it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct EvolutionSpec<'a> {
    /// The version this one migrates from, or `None` for the genesis version.
    pub migrates_from: Option<u32>,
    /// Field-level changes relative to the predecessor.
    pub changes: &'a [FieldChange<'a>],
}

impl EvolutionSpec<'_> {
    /// The genesis evolution: no predecessor, no changes.
    pub const GENESIS: EvolutionSpec<'static> = EvolutionSpec {
        migrates_from: None,
        changes: &[],
    };
}

/// A single field-level change between two adjacent schema versions.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FieldChange<'a> {
    /// A field introduced in this version.
    Added {
        /// Name of the new field.
        name: &'a str,
    },
    /// A field present in the predecessor but dropped here.
    Removed {
        /// Name of the dropped field.
        name: &'a str,
    },
    /// A field carried over under a new name.
    Renamed {
        /// Name in the predecessor.
        from: &'a str,
        /// Name in this version.
        to: &'a str,
    },
    /// A field whose type changed, requiring an explicit transform.
    Transformed {
        /// Name of the transformed field.
        name: &'a str,
    },
}

#[cfg(test)]
mod tests {
    use super::*;

    // A hand-written manifest exercising the const data model exactly as the
    // derive macro will emit it. Layout figures come from `core::mem`, so the
    // numbers are whatever the compiler actually chose for `Sample`.
    #[repr(C)]
    struct Sample {
        a: u32,
        b: u16,
    }

    impl Ix for Sample {
        const MANIFEST: Manifest<'static> = Manifest {
            type_name: "ix_schema::tests::Sample",
            doc: "",
            schema_version: 1,
            layout: LayoutSpec {
                size: core::mem::size_of::<Sample>(),
                align: core::mem::align_of::<Sample>(),
                repr: Repr::C,
            },
            fields: &[
                FieldSpec {
                    name: "a",
                    doc: "",
                    type_name: "u32",
                    offset: core::mem::offset_of!(Sample, a),
                    size: core::mem::size_of::<u32>(),
                    align: core::mem::align_of::<u32>(),
                    since: 1,
                },
                FieldSpec {
                    name: "b",
                    doc: "",
                    type_name: "u16",
                    offset: core::mem::offset_of!(Sample, b),
                    size: core::mem::size_of::<u16>(),
                    align: core::mem::align_of::<u16>(),
                    since: 1,
                },
            ],
            variants: &[],
            evolution: EvolutionSpec::GENESIS,
        };
    }

    #[test]
    fn manifest_reports_declared_shape() {
        let m = Sample::MANIFEST;
        assert_eq!(m.schema_version, 1);
        assert_eq!(m.layout.repr, Repr::C);
        assert_eq!(m.fields.len(), 2);
        assert_eq!(m.fields[0].name, "a");
        assert_eq!(m.fields[0].offset, 0);
        assert_eq!(m.evolution, EvolutionSpec::GENESIS);
    }

    #[test]
    fn padding_matches_real_layout() {
        // u32 + u16 = 6 bytes of data; #[repr(C)] rounds size up to 8 (align 4),
        // so exactly 2 padding bytes — computed by const fn, no runtime cost.
        let m = Sample::MANIFEST;
        assert_eq!(m.packed_field_bytes(), 6);
        assert_eq!(m.layout.size, 8);
        assert_eq!(m.padding_bytes(), 2);
        assert!(!m.is_gap_free());
    }

    // A driver whose support is decided entirely at compile time from the
    // manifest — the whole point of the orchestrator design.
    struct ZerocopyDriver;
    impl<T: Ix> Driver<T> for ZerocopyDriver {
        const SUPPORTED: bool = matches!(T::MANIFEST.layout.repr, Repr::C | Repr::Transparent)
            && T::MANIFEST.is_gap_free();
    }

    #[test]
    fn driver_support_folds_from_const_manifest() {
        // Sample is repr(C) but has padding, so a zerocopy driver must reject it.
        // The const block proves it during compilation; the runtime check keeps
        // the test observable.
        const { assert!(!<ZerocopyDriver as Driver<Sample>>::SUPPORTED) };
        let supported = <ZerocopyDriver as Driver<Sample>>::SUPPORTED;
        assert!(!supported);
    }

    #[test]
    fn retyping_a_carried_field_breaks_extends() {
        // Two manifests with one field each: same name, offset and size, but the
        // spelled type changes `u32` -> `f32`. The bytes would be reinterpreted,
        // so an append-only "extension" check must reject it. Proven at compile
        // time via the const block, confirmed at runtime for observability.
        const OLD: Manifest<'static> = Manifest {
            type_name: "X",
            doc: "",
            schema_version: 1,
            layout: LayoutSpec {
                size: 4,
                align: 4,
                repr: Repr::C,
            },
            fields: &[FieldSpec {
                name: "v",
                doc: "",
                type_name: "u32",
                offset: 0,
                size: 4,
                align: 4,
                since: 1,
            }],
            variants: &[],
            evolution: EvolutionSpec::GENESIS,
        };
        const NEW: Manifest<'static> = Manifest {
            type_name: "X",
            doc: "",
            schema_version: 2,
            layout: LayoutSpec {
                size: 4,
                align: 4,
                repr: Repr::C,
            },
            fields: &[FieldSpec {
                name: "v",
                doc: "",
                type_name: "f32",
                offset: 0,
                size: 4,
                align: 4,
                since: 1,
            }],
            variants: &[],
            evolution: EvolutionSpec::GENESIS,
        };
        const { assert!(!NEW.extends(&OLD)) };
        assert!(!NEW.extends(&OLD));
        // Sanity: an identical manifest still extends itself.
        assert!(OLD.extends(&OLD));
    }

    #[test]
    fn migration_trait_is_type_safe() {
        // Two adjacent schema versions wired by MigrateFrom; the body is what a
        // derive would emit. Field types must line up or this would not compile.
        #[repr(C)]
        struct V1 {
            id: u32,
        }
        #[repr(C)]
        struct V2 {
            id: u32,
            // introduced in v2
            flags: u8,
        }
        impl Ix for V1 {
            const MANIFEST: Manifest<'static> = Manifest {
                type_name: "V1",
                doc: "",
                schema_version: 1,
                layout: LayoutSpec {
                    size: core::mem::size_of::<V1>(),
                    align: core::mem::align_of::<V1>(),
                    repr: Repr::C,
                },
                fields: &[],
                variants: &[],
                evolution: EvolutionSpec::GENESIS,
            };
        }
        impl Ix for V2 {
            const MANIFEST: Manifest<'static> = Manifest {
                type_name: "V2",
                doc: "",
                schema_version: 2,
                layout: LayoutSpec {
                    size: core::mem::size_of::<V2>(),
                    align: core::mem::align_of::<V2>(),
                    repr: Repr::C,
                },
                fields: &[],
                variants: &[],
                evolution: EvolutionSpec {
                    migrates_from: Some(1),
                    changes: &[FieldChange::Added { name: "flags" }],
                },
            };
        }
        impl MigrateFrom<V1> for V2 {
            fn migrate_from(prev: V1) -> Self {
                V2 {
                    id: prev.id,
                    flags: 0,
                }
            }
        }

        let v2 = V2::migrate_from(V1 { id: 7 });
        assert_eq!(v2.id, 7);
        assert_eq!(v2.flags, 0);
        assert_eq!(V2::MANIFEST.evolution.migrates_from, Some(1));
    }
}