rivet/types/
mod.rs

1//! Rivet's internal type system.
2//!
3//! See `rivet_roadmap.md` §Epic 14 (Warehouse Load Layer). North Star —
4//! *"No silent type degradation"* — is enforced architecturally by
5//! routing every source-column type through the pipeline:
6//!
7//! ```text
8//! Source Native Type
9//!     ↓
10//! SourceColumn  ← what the driver knows about the column
11//!     ↓
12//! RivetType     ← canonical, vendor-independent type
13//!     ↓
14//! TypePolicy    ← strict / lossy / unsupported decisions  (Chunk 4)
15//!     ↓
16//! Arrow DataType + Field metadata  ← physical export type
17//! ```
18//!
19//! This module owns the first three boxes. The fourth (Arrow) is built by
20//! [`mapping::build_arrow_field`]; the fifth (TypePolicy) lands in Chunk 4
21//! of the type-safety milestones (see roadmap §18).
22//!
23//! ## Layer
24//!
25//! Layer-classification (ADR-0003): this module is **planning-layer** — it
26//! only describes / classifies types. It must not perform I/O, log
27//! metrics, or hold any pipeline state. Vendor mappers live in
28//! `crate::source::*` and call into this module.
29
30mod cursor;
31pub mod decimal;
32mod fidelity;
33mod mapping;
34mod override_type;
35pub mod policy;
36mod rivet_type;
37mod source_column;
38pub mod target;
39
40pub use cursor::CursorState;
41pub use fidelity::TypeFidelity;
42// Public surface for contract/integration tests; not referenced from the binary.
43#[allow(unused_imports)]
44pub use mapping::{TypeMapping, build_arrow_field, derive_fidelity, rivet_type_to_arrow};
45pub use override_type::parse_type_str;
46pub use rivet_type::{RivetType, TimeUnit};
47pub use source_column::SourceColumn;
48// ColumnOverride is the planned public API for column type overrides (Chunk 6).
49#[allow(unused_imports)]
50pub use source_column::ColumnOverride;
51
52/// Per-export column type overrides: column name → declared [`RivetType`].
53///
54/// Built at plan time from the `columns:` map in `rivet.yaml` (roadmap §8).
55/// Passed to [`crate::source::Source::export`] so drivers can use the
56/// declared precision/scale instead of autodetected (often unavailable) metadata.
57pub type ColumnOverrides = std::collections::HashMap<String, RivetType>;
58
59#[cfg(test)]
60mod tests {
61    use super::*;
62    use crate::types::mapping::{META_FIDELITY, META_LOGICAL_TYPE, META_NATIVE_TYPE};
63    use arrow::datatypes::DataType;
64
65    /// Top-level smoke test: feeding a typical PostgreSQL `payments` table
66    /// through `SourceColumn → RivetType → Arrow Field` produces the schema
67    /// shape demanded by the roadmap's §20 "Definition of Done":
68    ///
69    /// ```text
70    /// id          bigint          int64            Int64                  exact
71    /// amount      numeric(18,2)   decimal(18,2)    Decimal128(18,2)       exact
72    /// created_at  timestamptz     timestamp_tz     Timestamp(us, UTC)     exact
73    /// payload     jsonb           json             Utf8 + metadata        logical_string
74    /// ```
75    #[test]
76    fn end_to_end_payments_schema_matches_definition_of_done() {
77        let cols: Vec<(SourceColumn, RivetType)> = vec![
78            (
79                SourceColumn::simple("id", "bigint", false),
80                RivetType::Int64,
81            ),
82            (
83                SourceColumn::decimal("amount", "numeric", false, 18, 2),
84                RivetType::Decimal {
85                    precision: 18,
86                    scale: 2,
87                },
88            ),
89            (
90                SourceColumn::simple("created_at", "timestamptz", false),
91                RivetType::Timestamp {
92                    unit: TimeUnit::Microsecond,
93                    timezone: Some("UTC".into()),
94                },
95            ),
96            (
97                SourceColumn::simple("payload", "jsonb", true),
98                RivetType::Json,
99            ),
100        ];
101
102        let mappings: Vec<TypeMapping> = cols
103            .into_iter()
104            .map(|(s, t)| TypeMapping::from_source(&s, t))
105            .collect();
106
107        // Fidelity matrix mirrors the table in the Definition of Done.
108        assert_eq!(mappings[0].fidelity, TypeFidelity::Exact);
109        assert_eq!(mappings[1].fidelity, TypeFidelity::Exact);
110        assert_eq!(mappings[2].fidelity, TypeFidelity::Exact);
111        assert_eq!(mappings[3].fidelity, TypeFidelity::LogicalString);
112
113        // Arrow types are exactly what the roadmap demands — no Utf8 fallback for decimal.
114        assert_eq!(mappings[0].arrow_type, Some(DataType::Int64));
115        assert_eq!(mappings[1].arrow_type, Some(DataType::Decimal128(18, 2)));
116        assert!(matches!(
117            mappings[2].arrow_type,
118            Some(DataType::Timestamp(_, Some(_)))
119        ));
120        assert_eq!(mappings[3].arrow_type, Some(DataType::Utf8));
121
122        // Field-level metadata is preserved end-to-end.
123        let amount_field = build_arrow_field(&mappings[1]).expect("amount");
124        assert_eq!(
125            amount_field
126                .metadata()
127                .get(META_NATIVE_TYPE)
128                .map(String::as_str),
129            Some("numeric")
130        );
131        assert_eq!(
132            amount_field
133                .metadata()
134                .get(META_FIDELITY)
135                .map(String::as_str),
136            Some("exact")
137        );
138
139        let payload_field = build_arrow_field(&mappings[3]).expect("payload");
140        assert_eq!(
141            payload_field
142                .metadata()
143                .get(META_LOGICAL_TYPE)
144                .map(String::as_str),
145            Some("json")
146        );
147    }
148
149    /// Keep `rivet_type_to_arrow` / `derive_fidelity` re-exports live for
150    /// `tests/type_roundtrip` contract tests and downstream tooling.
151    #[test]
152    fn mapping_helpers_reexported_for_contract_tests() {
153        let dec = RivetType::Decimal {
154            precision: 18,
155            scale: 2,
156        };
157        assert!(matches!(
158            rivet_type_to_arrow(&dec),
159            Some(DataType::Decimal128(18, 2))
160        ));
161        assert_eq!(derive_fidelity(&dec), TypeFidelity::Exact);
162    }
163}
rivet/types/mod.rs

rivet/types/
mod.rs
