fv-connect 0.1.0

FusionVault Conduit: read relational, file and REST sources into rows with mandatory access control pushed into the read, write results back with atomic promotion, and drive incremental base-ingest scans, changelogs and label normalisation checked against the published conformance vectors.
Documentation
//! Datasource bindings (the object-type schema's datasource block), pinned to the contract's
//! `binding` conformance vectors.
//!
//! Reads a manifest's ObjectType datasource declarations into the bindings the base-ingest scan
//! binds to: which table/catalog, incremental strategy, label columns, and multi-datasource shape. The
//! singular `datasource` form is sugar for one primary binding named "default" that claims everything;
//! the plural `datasources` form carries per-source claims + primary selection + independent checkpoint
//! keys. C1 `dataset` sugar resolves a pipeline-registry dataset apiName to (connector, table) via an
//! injected resolver. Types with neither declaration are simply not scanned.

use std::collections::BTreeMap;

use fv_value::{json_to_value, Value};
use serde_json::Value as J;

use crate::labels::LabelBinding;

/// Resolves a pipeline-registry dataset apiName → `(connector, table)` (C1 sugar). `None` = unresolved.
pub type DatasetResolver<'a> = dyn Fn(&str) -> Option<(String, String)> + 'a;

/// One ObjectType datasource binding. The normalization-relevant fields feed
/// [`LabelBinding`] via [`Binding::label_binding`]; the rest drive the scan (table, cursor, checkpoint).
#[derive(Debug, Clone, PartialEq)]
pub struct Binding {
    pub object_type: String,
    /// The connector `type` (ICEBERG / POSTGRES / MYSQL / …) the source is dispatched on.
    pub source_type: String,
    pub table: Option<String>,
    pub catalog: Option<String>,
    pub incremental_strategy: String,
    pub source_updated_at_column: Option<String>,
    pub correlation_token_column: Option<String>,
    pub label_columns: BTreeMap<String, String>,
    pub default_label: BTreeMap<String, Value>,
    pub on_missing_label: String,
    /// Unique per type; names `_prov.ds` + the per-source checkpoint. "default" = the singular sugar.
    pub name: String,
    /// Owns row labels + lifecycle (create/delete). The publish gate guarantees exactly one primary.
    pub primary: bool,
    /// The CLAIMS; empty = claims everything (singular sugar).
    pub properties: Vec<String>,
}

impl Binding {
    /// Per-(type, source) checkpoint key — sources tick independently. The "default" (singular-sugar)
    /// binding keeps the legacy bare-apiName key so existing checkpoints stay valid.
    pub fn checkpoint_key(&self) -> String {
        if self.name == "default" {
            self.object_type.clone()
        } else {
            format!("{}:{}", self.object_type, self.name)
        }
    }

    /// The normalization view of this binding (`labels::normalize_row`).
    pub fn label_binding(&self) -> LabelBinding {
        LabelBinding {
            label_columns: self.label_columns.clone(),
            default_label: self.default_label.clone(),
            on_missing_label: self.on_missing_label.clone(),
            properties: self.properties.clone(),
            correlation_token_column: self.correlation_token_column.clone(),
            source_updated_at_column: self.source_updated_at_column.clone(),
            primary: self.primary,
        }
    }
}

fn str_map(j: Option<&J>) -> BTreeMap<String, String> {
    j.and_then(J::as_object)
        .map(|o| {
            o.iter()
                .filter_map(|(k, v)| v.as_str().map(|s| (k.clone(), s.to_string())))
                .collect()
        })
        .unwrap_or_default()
}

fn str_vec(j: Option<&J>) -> Vec<String> {
    j.and_then(J::as_array)
        .map(|a| a.iter().filter_map(|v| v.as_str().map(String::from)).collect())
        .unwrap_or_default()
}

/// Parse one datasource declaration into a [`Binding`]. `primary_default` is the plural-vs-singular
/// default (the singular sugar is primary; plural entries default secondary). `resolve` turns a
/// `dataset` reference into (connector, table) when no explicit table is given (C1).
pub fn binding_from_definition(
    object_type: &str,
    ds: &J,
    primary_default: bool,
    resolve: Option<&DatasetResolver>,
) -> Binding {
    let mut table = ds.get("table").and_then(J::as_str).map(String::from);
    let mut catalog = ds.get("catalog").and_then(J::as_str).map(String::from);
    // C1 sugar: a datasource may name a pipeline-registry DATASET instead of an explicit table+catalog.
    if table.is_none() {
        if let (Some(dataset_ref), Some(r)) = (ds.get("dataset").and_then(J::as_str), resolve) {
            if let Some((connector, resolved_table)) = r(dataset_ref) {
                table = Some(resolved_table);
                catalog = Some(connector);
            }
        }
    }
    Binding {
        object_type: object_type.to_string(),
        source_type: ds.get("type").and_then(J::as_str).unwrap_or("ICEBERG").to_string(),
        table,
        catalog,
        incremental_strategy: ds
            .get("incrementalStrategy")
            .and_then(J::as_str)
            .unwrap_or("FULL_SNAPSHOT")
            .to_string(),
        source_updated_at_column: ds.get("sourceUpdatedAtColumn").and_then(J::as_str).map(String::from),
        correlation_token_column: ds.get("correlationTokenColumn").and_then(J::as_str).map(String::from),
        label_columns: str_map(ds.get("labelColumns")),
        default_label: ds
            .get("defaultLabel")
            .and_then(J::as_object)
            .map(|o| o.iter().map(|(k, v)| (k.clone(), json_to_value(v))).collect())
            .unwrap_or_default(),
        on_missing_label: ds
            .get("onMissingLabel")
            .and_then(J::as_str)
            .unwrap_or("DENY")
            .to_string(),
        name: ds.get("name").and_then(J::as_str).unwrap_or("default").to_string(),
        primary: ds.get("primary").and_then(J::as_bool).unwrap_or(primary_default),
        properties: str_vec(ds.get("properties")),
    }
}

/// Every ObjectType's datasource bindings, keyed by apiName — a LIST per type. The singular
/// `datasource` form resolves to one primary "default" binding; types with neither are not scanned.
pub fn bindings_from_definitions(defs: &J, resolve: Option<&DatasetResolver>) -> BTreeMap<String, Vec<Binding>> {
    let mut out = BTreeMap::new();
    for ot in defs.get("objectTypes").and_then(J::as_array).into_iter().flatten() {
        let api = match ot.get("apiName").and_then(J::as_str) {
            Some(a) => a,
            None => continue,
        };
        match ot.get("datasources").and_then(J::as_array) {
            // Plural entries default primary=false; the publish gate guarantees exactly one primary.
            Some(plural) if !plural.is_empty() => {
                out.insert(
                    api.to_string(),
                    plural
                        .iter()
                        .map(|ds| binding_from_definition(api, ds, false, resolve))
                        .collect(),
                );
            }
            _ => {
                if let Some(single) = ot.get("datasource").filter(|d| d.is_object()) {
                    out.insert(
                        api.to_string(),
                        vec![binding_from_definition(api, single, true, resolve)],
                    );
                }
            }
        }
    }
    out
}

/// The binding that owns lifecycle/labels (the publish gate guarantees exactly one).
pub fn primary_binding(bindings: &[Binding]) -> &Binding {
    bindings.iter().find(|b| b.primary).unwrap_or(&bindings[0])
}