Skip to main content

flow_runner/run/token/
mod.rs

1//! [`Token`]: where an instance is, as bytes the host stores and passes back
2//! to resume.
3//!
4//! A token is the signature `FTOK`, the token version, its fields as a CBOR
5//! array, and a checksum of all that.
6
7mod base64;
8pub(super) mod stored;
9
10use self::stored::{Stored, Text};
11use crate::common::checksum;
12use crate::common::error::{twice, InputError, RebindError};
13use crate::common::limits::{MAX_TOKEN_BYTES, MAX_TOKEN_NESTING, MAX_TOKEN_STATE};
14use crate::common::versions::{SEMANTICS_VERSION, TOKEN_VERSION};
15use crate::flow::{hex, Flow};
16use serde::de::{DeserializeOwned, IgnoredAny};
17use smol_str::SmolStr;
18use std::collections::HashMap;
19use std::fmt;
20
21/// Where an instance is: its node and the arguments it came with, its
22/// params and counters, and what it waits for. Store it with the instance,
23/// and pass it back to resume.
24///
25/// A token holds state, not identity: instances in the same state have equal
26/// tokens, so key instances by an id of your own. And it isn't signed: its
27/// checksum catches damage, not tampering. Keep tokens where only the host
28/// can change them, like any other state it trusts.
29#[derive(Clone, PartialEq, Eq, Hash)]
30pub struct Token(Vec<u8>);
31
32impl fmt::Debug for Token {
33    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
34        write!(f, "Token({})", self.to_base64())
35    }
36}
37
38impl Token {
39    /// A token from the bytes [`as_bytes`](Self::as_bytes) gave. It is checked
40    /// when used, not here.
41    pub fn from_bytes(bytes: Vec<u8>) -> Token {
42        Token(bytes)
43    }
44
45    /// The bytes to store.
46    pub fn as_bytes(&self) -> &[u8] {
47        &self.0
48    }
49
50    /// The bytes to store, without copying them.
51    pub fn into_bytes(self) -> Vec<u8> {
52        self.0
53    }
54
55    /// URL-safe base64 without padding, for storing as text.
56    pub fn to_base64(&self) -> String {
57        base64::encode(&self.0)
58    }
59
60    /// A token from the text [`to_base64`](Self::to_base64) gave. Padding
61    /// and the standard alphabet's `+` and `/` are read too.
62    pub fn from_base64(text: &str) -> Result<Token, InputError> {
63        base64::decode(text)
64            .map(Token)
65            .ok_or_else(|| InputError::corrupt("not valid base64"))
66    }
67
68    /// What the token says, read without a flow.
69    pub fn inspect(&self) -> Result<TokenInfo, InputError> {
70        let (_, hash, flow, node, _, _, sequence, asks, wake_at, ask): Fields<
71            IgnoredAny,
72            IgnoredAny,
73        > = fields(&self.0)?;
74        Ok(TokenInfo {
75            flow: flow.to_string(),
76            hash: hex(&hash),
77            node: node.to_string(),
78            sequence,
79            asks,
80            ask: ask.map(|ask| ask.to_string()),
81            wake_at,
82        })
83    }
84}
85
86/// What a [`Token`] says.
87#[derive(Debug, Clone, PartialEq, Eq)]
88pub struct TokenInfo {
89    /// The flow's name.
90    pub flow: String,
91    /// The version of the flow that made it, as [`Flow::hash`] shows it.
92    pub hash: String,
93    /// The node the instance is at.
94    pub node: String,
95    /// Goes up by one each time a run moves the instance: to another node or
96    /// other arguments, to another wake time, or into an ask. A run that
97    /// leaves the instance where it was hands back the same token, so use
98    /// this as a compare-and-swap version when saving.
99    pub sequence: u64,
100    /// Asks the instance has made so far.
101    pub asks: u64,
102    /// The ask the instance waits on an answer to.
103    pub ask: Option<String>,
104    /// When the instance wants a `tick`, in epoch seconds.
105    pub wake_at: Option<i64>,
106}
107
108const SIGNATURE: [u8; 4] = *b"FTOK";
109const VERSION_AT: usize = SIGNATURE.len();
110const FIELDS_AT: usize = VERSION_AT + 1;
111
112/// Room a new token starts with: typical tokens are about a hundred bytes.
113const TYPICAL_TOKEN_BYTES: usize = 128;
114
115/// What a token holds, in the order it stores it.
116#[derive(Debug, Clone)]
117pub(super) struct Data {
118    /// The [`SEMANTICS_VERSION`] it was made under.
119    pub semantics: u32,
120    /// The hash of the flow version that made it.
121    pub hash: Vec<u8>,
122    pub flow: Text,
123    pub node: Text,
124    pub args: Vec<Stored>,
125    pub params: Vec<(Text, Stored)>,
126    pub sequence: u64,
127    pub asks: u64,
128    pub wake_at: Option<i64>,
129    /// The ask the instance waits on an answer to.
130    pub ask: Option<Text>,
131}
132
133/// A token's fields on the wire: an array, not a map, so no field names,
134/// which halves a token's size. `inspect` skips the arguments and params.
135type Fields<Args, Params> = (
136    u32,
137    serde_bytes::ByteBuf,
138    Text,
139    Text,
140    Args,
141    Params,
142    u64,
143    u64,
144    Option<i64>,
145    Option<Text>,
146);
147
148impl Data {
149    pub(super) fn encode(&self) -> Token {
150        let fields = (
151            self.semantics,
152            serde_bytes::Bytes::new(&self.hash),
153            &self.flow,
154            &self.node,
155            &self.args,
156            &self.params,
157            self.sequence,
158            self.asks,
159            self.wake_at,
160            &self.ask,
161        );
162        let mut out = Vec::with_capacity(TYPICAL_TOKEN_BYTES);
163        out.extend_from_slice(&SIGNATURE);
164        out.push(TOKEN_VERSION);
165        ciborium::ser::into_writer(&fields, &mut out).expect("writing to a Vec can't fail");
166        checksum::append(&mut out);
167        Token(out)
168    }
169
170    /// The fields of a token for `flow`, made by this flow-runner or an
171    /// older one.
172    pub(super) fn decode(bytes: &[u8], flow: &Flow) -> Result<Data, InputError> {
173        let (semantics, hash, name, node, args, params, sequence, asks, wake_at, ask) =
174            fields(bytes)?;
175        if *name != *flow.name {
176            return Err(InputError::OtherFlow(name.to_string()));
177        }
178        if semantics > SEMANTICS_VERSION {
179            return Err(InputError::NewerToken);
180        }
181        Ok(Data {
182            semantics,
183            hash: hash.into_vec(),
184            flow: name,
185            node,
186            args,
187            params,
188            sequence,
189            asks,
190            wake_at,
191            ask,
192        })
193    }
194}
195
196/// A token's fields, once its signature, checksum and version check out.
197fn fields<Args, Params>(bytes: &[u8]) -> Result<Fields<Args, Params>, InputError>
198where
199    Args: DeserializeOwned,
200    Params: DeserializeOwned,
201{
202    if bytes.len() > MAX_TOKEN_BYTES {
203        return Err(InputError::corrupt("longer than any token"));
204    }
205    if !bytes.starts_with(&SIGNATURE) {
206        return Err(InputError::corrupt("not a flow token"));
207    }
208    let body = checksum::strip(bytes).ok_or_else(|| InputError::corrupt("checksum mismatch"))?;
209    match body.get(VERSION_AT) {
210        Some(&TOKEN_VERSION) => {}
211        Some(&version) if version > TOKEN_VERSION => return Err(InputError::NewerToken),
212        _ => return Err(InputError::corrupt("no known token version")),
213    }
214    let mut rest = &body[FIELDS_AT..];
215    let fields = ciborium::de::from_reader_with_recursion_limit(&mut rest, MAX_TOKEN_NESTING)
216        .map_err(|error| InputError::corrupt(format!("malformed: {error}")))?;
217    if !rest.is_empty() {
218        return Err(InputError::corrupt("bytes after its end"));
219    }
220    Ok(fields)
221}
222
223impl Flow {
224    /// Move a token to this version of the flow: its node must still exist,
225    /// take as many arguments, and continue an ask exactly when the token
226    /// waits on one, and each param it carries must still exist. The
227    /// instance stays where it was, with the same sequence number.
228    ///
229    /// Arguments travel by position, so a node whose parameters were renamed
230    /// or reordered takes them as they were. The host decides when rebinding
231    /// is safe, e.g. after fixing a flow that failed mid-instance.
232    pub fn rebind(&self, token: &Token) -> Result<Token, RebindError> {
233        let data = Data::decode(&token.0, self).map_err(RebindError::Token)?;
234        let Some(id) = self.node_by_name(&data.node) else {
235            return Err(RebindError::NodeGone(data.node.to_string()));
236        };
237        let node = &self.nodes[id.index()];
238        // a waiting token needs a node that takes the answer, and a parked
239        // token can't land on one, which only an answer may enter
240        if node.params.len() != data.args.len() || node.resumes_ask != data.ask.is_some() {
241            return Err(RebindError::NodeChanged(data.node.to_string()));
242        }
243        let mut carried: HashMap<SmolStr, Stored> = HashMap::with_capacity(data.params.len());
244        for (Text(name), value) in data.params {
245            if carried.contains_key(&name) {
246                let error = InputError::corrupt(twice("param", &name));
247                return Err(RebindError::Token(error));
248            }
249            if !self.param_positions.contains_key(&name) {
250                return Err(RebindError::ParamGone(name.to_string()));
251            }
252            carried.insert(name, value);
253        }
254        let params: Vec<(Text, Stored)> = self
255            .params
256            .iter()
257            .map(|param| {
258                // a param added since the token was made starts at its
259                // default, a literal, which is never too deep to store
260                let value = carried
261                    .remove(param.name.as_str())
262                    .unwrap_or_else(|| stored::encode(&param.default).unwrap_or(Stored::Null));
263                (Text(SmolStr::new(&param.name)), value)
264            })
265            .collect();
266        if stored::state_len(&data.args, &params) > MAX_TOKEN_STATE {
267            return Err(RebindError::TooLarge);
268        }
269        Ok(Data {
270            semantics: SEMANTICS_VERSION,
271            hash: self.hash.to_vec(),
272            params,
273            ..data
274        }
275        .encode())
276    }
277}