icydb-core 0.67.1

IcyDB — A type-safe, embedded ORM and schema system for the Internet Computer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

//! Module: relation::save_validate
//! Responsibility: save-time strong relation existence/integrity validation.
//! Does not own: reverse-index mutation planning or delete-time relation blocking.
//! Boundary: executor save preflight delegates relation semantics to this module.

use crate::{
    db::{
        Db,
        relation::{
            StrongRelationTargetInfo, build_relation_target_raw_key,
            for_each_relation_target_value, strong_relation_target_from_kind,
        },
    },
    error::InternalError,
    model::entity::EntityModel,
    traits::{EntityKind, EntityValue},
    value::Value,
};

/// Return `true` when one entity model declares at least one strong relation target.
#[must_use]
pub(in crate::db) fn model_has_strong_relation_targets(model: &'static EntityModel) -> bool {
    model
        .fields()
        .iter()
        .any(|field| strong_relation_target_from_kind(&field.kind).is_some())
}

/// Validate strong relation references for one save candidate entity.
pub(in crate::db) fn validate_save_strong_relations<E>(
    db: &Db<E::Canister>,
    entity: &E,
) -> Result<(), InternalError>
where
    E: EntityKind + EntityValue,
{
    // Phase 1: identify strong relation fields and read declared relation values.
    for (field_index, field) in E::MODEL.fields.iter().enumerate() {
        let Some(relation) = strong_relation_target_from_kind(&field.kind) else {
            continue;
        };

        let value = entity.get_value_by_index(field_index).ok_or_else(|| {
            InternalError::executor_invariant(format!(
                "entity field missing: {} field={}",
                E::PATH,
                field.name
            ))
        })?;

        // Phase 2: validate each referenced relation key against target storage.
        for_each_relation_target_value(&value, |item| {
            validate_save_relation_value::<E>(db, field.name, relation, item)
        })?;
    }

    Ok(())
}

/// Validate one strong relation key against target-store membership.
fn validate_save_relation_value<E>(
    db: &Db<E::Canister>,
    field_name: &str,
    relation: StrongRelationTargetInfo,
    value: &Value,
) -> Result<(), InternalError>
where
    E: EntityKind + EntityValue,
{
    // Phase 1: normalize relation key into canonical target raw-key form.
    let raw_key = build_relation_target_raw_key(
        relation.target_entity_tag,
        relation.target_entity_name,
        value,
    )
    .map_err(|err| {
        InternalError::relation_target_raw_key_error(
            err,
            E::PATH,
            field_name,
            relation.target_path,
            relation.target_entity_name,
            value,
            "strong relation key not storage-compatible",
            "strong relation target name invalid",
        )
    })?;

    // Phase 2: resolve the target store and enforce key existence.
    let store = db
        .with_store_registry(|reg| reg.try_get_store(relation.target_store_path))
        .map_err(|err| {
            InternalError::strong_relation_target_store_missing(
                E::PATH,
                field_name,
                relation.target_path,
                relation.target_store_path,
                value,
                err,
            )
        })?;
    let exists = store.with_data(|s| s.contains_key(&raw_key));
    if !exists {
        return Err(InternalError::strong_relation_target_missing(
            E::PATH,
            field_name,
            relation.target_path,
            value,
        ));
    }

    Ok(())
}