cotis-modules-debug 0.1.0-alpha

Record, replay, and isolate Cotis layout and UI declaration pipelines
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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165

//! Type-level lists for deserializing type-erased leaf configs at replay time.
//!
//! During recording, leaf element configs (text, images, custom widgets) are serialized into
//! [`LeafConfigData`] blobs without preserving their Rust type. At replay, the
//! [`LeafConfigList`] chain tells the interpreter which concrete types to try, in order.
//!
//! # Building a leaf type list
//!
//! Start with [`LeafConfigListNil`] (the empty list) and extend it using [`LeafConfigList::new`]
//! or [`LeafConfigList::extend`]:
//!
//! ```rust,ignore
//! use cotis_modules_debug::serialize_targets::leaf_serialization::{LeafConfigList, LeafConfigListNil};
//!
//! // Single leaf type:
//! type Leafs = LeafConfigList<TextElementConfig<'static>, LeafConfigListNil>;
//! let leafs = Leafs::new();
//!
//! // Multiple leaf types (order matters — see below):
//! type Leafs = LeafConfigList<
//!     TextElementConfig<'static>,
//!     LeafConfigList<ImageElementConfig<'static>, LeafConfigListNil>,
//! >;
//! let leafs = LeafConfigList::<TextElementConfig<'static>, _>::extend();
//! ```
//!
//! # Deserialization order
//!
//! When replaying a [`LeafConfig`](super::SerializableInterfaceInstructions::LeafConfig)
//! instruction, the list tries to deserialize the JSON blob as the head type first. If that
//! fails, it recurses to the tail. **Put more specific leaf types before more general ones**
//! to avoid ambiguous matches.

use std::marker::PhantomData;

use cotis::element_configuring::{
    ConfigureElements, ConfigureLeafElements, OpenElement, OpenLeafElement,
};
use serde::de::DeserializeOwned;
use serde::{Deserialize, Serialize};

/// Terminal node of a [`LeafConfigList`] chain (empty list).
#[derive(Clone, Copy, Debug)]
pub struct LeafConfigListNil;

/// A type-level cons-list of leaf config types used for replay deserialization.
///
/// This is a phantom type: it carries no runtime data. Use [`new`](Self::new) to start a
/// one-element list, [`extend`](Self::extend) to prepend another type, or
/// [`new_long`](Self::new_long) when the full `Head`/`Tail` types are already known.
#[derive(Debug)]
pub struct LeafConfigList<Head, Tail>(PhantomData<(Head, Tail)>);

impl<Head, Tail> Clone for LeafConfigList<Head, Tail> {
    fn clone(&self) -> Self {
        *self
    }
}

impl<Head, Tail> Copy for LeafConfigList<Head, Tail> {}

impl<Head, Tail> LeafConfigList<Head, Tail> {
    /// Creates a one-element list with `Head` as the only leaf type.
    pub fn new() -> LeafConfigList<Head, LeafConfigListNil> {
        LeafConfigList(PhantomData)
    }

    /// Prepends `Head` to an existing `Head2`/`Tail2` list.
    pub fn extend<Head2, Tail2>() -> LeafConfigList<Head, LeafConfigList<Head2, Tail2>> {
        LeafConfigList(PhantomData)
    }

    /// Creates a list with the `Head` and `Tail` types already specified in the struct.
    pub fn new_long() -> LeafConfigList<Head, Tail> {
        LeafConfigList(PhantomData)
    }
}

/// Type-erased JSON storage for a leaf element config recorded during stage 1.
///
/// The concrete type is recovered at replay time using a [`LeafConfigList`] chain.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LeafConfigData {
    internal: Vec<u8>,
}

impl LeafConfigData {
    pub(crate) fn new<Head: Serialize>(config: &Head) -> LeafConfigData {
        Self {
            internal: serde_json::to_vec(&config).unwrap(),
        }
    }

    fn try_reconstruct<Head: DeserializeOwned>(&self) -> Option<Head> {
        serde_json::from_slice(&self.internal).ok()
    }
}

/// Type-level dispatch for replaying [`LeafConfigData`] against open elements.
///
/// Implemented automatically for [`LeafConfigList`] chains. Custom implementations are
/// rarely needed; build a [`LeafConfigList`] instead.
pub trait LeafConfigListCompatible<Configurer, ConfigType>
where
    Configurer: ConfigureElements<ConfigType>,
{
    /// Applies a leaf config blob to an open leaf element.
    fn configure(
        data: &LeafConfigData,
        configurer: &mut OpenLeafElement<'_, Configurer, ConfigType>,
    );

    /// Applies a leaf config blob to an open element (consuming it).
    fn configure_open(data: &LeafConfigData, configurer: OpenElement<'_, Configurer, ConfigType>);
}

impl<Head, Tail, Configurer, ConfigType> LeafConfigListCompatible<Configurer, ConfigType>
    for LeafConfigList<Head, Tail>
where
    Configurer: ConfigureLeafElements<Head> + ConfigureElements<ConfigType>,
    Tail: LeafConfigListCompatible<Configurer, ConfigType>,
    Head: DeserializeOwned,
{
    fn configure(
        data: &LeafConfigData,
        configurer: &mut OpenLeafElement<'_, Configurer, ConfigType>,
    ) {
        let reconstruction: Option<Head> = data.try_reconstruct();
        match reconstruction {
            Some(reconstruction) => {
                configurer.set_leaf_config(reconstruction);
            }
            None => {
                Tail::configure(data, configurer);
            }
        }
    }

    fn configure_open(data: &LeafConfigData, configurer: OpenElement<'_, Configurer, ConfigType>) {
        let reconstruction: Option<Head> = data.try_reconstruct();
        match reconstruction {
            Some(reconstruction) => {
                configurer.set_leaf_config(reconstruction);
            }
            None => {
                Tail::configure_open(data, configurer);
            }
        }
    }
}

impl<Configurer, ConfigType> LeafConfigListCompatible<Configurer, ConfigType> for LeafConfigListNil
where
    Configurer: ConfigureElements<ConfigType>,
{
    fn configure(
        _data: &LeafConfigData,
        _configurer: &mut OpenLeafElement<'_, Configurer, ConfigType>,
    ) {
    }

    fn configure_open(_data: &LeafConfigData, configurer: OpenElement<'_, Configurer, ConfigType>) {
        drop(configurer);
    }
}