libtracer 0.13.0

Rust binding for libtracer — a lightweight decentralized graph-based networking protocol.
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
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright 2026 avatarsd LLC

/*!
 * @brief FWD remote-operation envelope — FWD TLV (`0x0F`) build/parse (Unit 4).
 *
 * The source-routed remote-operation frame (RFC-0004 §B/§D, ADR-0035). Mirrors
 * `bindings/typescript/packages/client/src/fwd.ts` and the terminus resolver of
 * `core/src/op_resolve.cpp`. Child order (RFC-0004 §B): `op`, `dst` (PATH),
 * `FIELD?` selector, `src` (PATH), then per-op:
 *   - REPLY: `kind` (VALUE u8), optional payload
 *   - WRITE: optional payload
 *   - AWAIT: optional `await_timeout` (VALUE u64 ns)
 *   - READ : nothing
 *
 * Vector-pinned: all nine vectors under `fwd/`.
 */

use alloc::string::String;
use alloc::vec::Vec;

use crate::error_registry::ErrCode;
use crate::field::{field_tlv, parse_field, FieldLevel};
use crate::path::path_to_tlv;
use crate::tlv_builders::{path as build_path, value_u64, value_u8, BuildError};
use crate::{type_code, Opt, Tlv};

/** @brief FWD `op` discriminant (RFC-0004 §B — the first child, a VALUE u8). */
pub mod fwd_op {
    /** @brief Read a vertex's last-known value. */
    pub const READ: u8 = 0;
    /** @brief Write a value / field (subscribe is a `:subscribers[]` field-write). */
    pub const WRITE: u8 = 1;
    /** @brief Await the next write, up to an optional timeout. */
    pub const AWAIT: u8 = 2;
    /** @brief A reply routed back along the accumulated `src`. */
    pub const REPLY: u8 = 3;

    /**
     * @brief The opcode field of the `op` byte — bits 5-0 (RFC-0024 §7.5).
     *
     * Bits 7-6 are FLAGS. A forwarder MUST mask before switching (RFC-0024 §9.3): an
     * unrecognised flag then degrades to the plain opcode instead of an unknown-opcode
     * reject, which is what makes a flag additive at all.
     */
    pub const OPCODE_MASK: u8 = 0x3F;

    /**
     * @brief `op` bit 7 — the bound-path MINT REQUEST (RFC-0024 §7.5).
     *
     * Set by an origin asking each host on the route to answer with its own vertex ref. It
     * costs ZERO request bytes: there is no free TLV `opt` bit, and a dedicated presence
     * child would spend a 4-byte header to express one. The request is a hint, never an
     * obligation — a host that will not mint answers the ordinary reply.
     */
    pub const FLAG_MINT_REQUEST: u8 = 0x80;
}

/** @brief FWD{REPLY} `kind` discriminant (RFC-0004 §D — a VALUE u8 after `src`). */
pub mod fwd_kind {
    /** @brief A successful result (payload is the RESULT value). */
    pub const RESULT: u8 = 0;
    /** @brief A failure (payload is `STATUS{ ERROR }`). */
    pub const ERROR: u8 = 1;
}

/**
 * @brief The registered wire ERROR code of a `tr::…` path, or 0 when unregistered.
 * The FWD error-path table is [`ErrCode`] itself (RFC-0002 §D).
 */
pub fn fwd_error_code_for_path(path: &str) -> u16 {
    ErrCode::from_path(path).map(ErrCode::code).unwrap_or(0)
}

/** @brief The canonical `tr::…` path of a registered wire ERROR code, or `None`. */
pub fn fwd_error_path(code: u16) -> Option<&'static str> {
    ErrCode::from_code(code).map(ErrCode::path)
}

/* -------------------------------------------------------------- FWD request --- */

/** @brief A `:field` selector for a FWD request: a raw string (parsed) or pre-built levels. */
pub enum FieldSel<'a> {
    /** @brief A `:field` selector string (see [`parse_field`]). */
    Str(&'a str),
    /** @brief Pre-parsed selector levels. */
    Levels(Vec<FieldLevel>),
}

/** @brief A request to build a FWD frame. `op` selects the trailing-child layout. */
pub struct FwdRequest<'a> {
    /** @brief The operation (a [`fwd_op`] value). */
    pub op: u8,
    /** @brief Forward route: the unresolved destination path segments (the PATH `dst`). */
    pub dst: &'a [&'a str],
    /** @brief Accumulated return route: the originator's reply-endpoint segments (`src`). */
    pub src: &'a [&'a str],
    /** @brief Optional `:field` selector. */
    pub field: Option<FieldSel<'a>>,
    /**
     * @brief Optional payload node (a VALUE to WRITE, a SUBSCRIBER to subscribe, the
     * RESULT/STATUS of a REPLY). Embedded verbatim.
     */
    pub payload: Option<Tlv>,
    /** @brief REPLY only — the reply [`fwd_kind`] (defaults to RESULT). */
    pub kind: Option<u8>,
    /** @brief AWAIT only — the `await_timeout` in ns (absent ⇒ the responder default). */
    pub await_timeout_ns: Option<u64>,
}

impl<'a> FwdRequest<'a> {
    /** @brief A minimal request: `op`, `dst`, `src`; all optional fields cleared. */
    pub fn new(op: u8, dst: &'a [&'a str], src: &'a [&'a str]) -> FwdRequest<'a> {
        FwdRequest {
            op,
            dst,
            src,
            field: None,
            payload: None,
            kind: None,
            await_timeout_ns: None,
        }
    }
}

fn field_node(sel: &FieldSel) -> Result<Tlv, BuildError> {
    match sel {
        FieldSel::Str(s) => field_tlv(&parse_field(s)?),
        FieldSel::Levels(l) => field_tlv(l),
    }
}

/**
 * @brief Build a FWD TLV node (`type=0x0F`, `PL=1`) — the remote-operation envelope.
 * Children are assembled in the normative order for the request's `op`.
 * Vector-pinned: `fwd-read`, `fwd-write-value`, `fwd-await-timeout`,
 * `fwd-write-subscriber-field`, `fwd-reply-result`, `fwd-reply-error`,
 * `fwd-routed-mount-residual`, `fwd-routed-two-mount`, `fwd-src-accumulated`,
 * `fwd-wildcard-reject`.
 *
 * # Errors
 * Any error from building the `dst`/`src` PATHs, the FIELD selector, or an
 * invalid `op`.
 */
pub fn encode_fwd(req: &FwdRequest) -> Result<Tlv, BuildError> {
    let mut children = alloc::vec![value_u8(req.op), build_path(req.dst)?];
    if let Some(sel) = &req.field {
        children.push(field_node(sel)?);
    }
    children.push(build_path(req.src)?);

    if req.op == fwd_op::REPLY {
        children.push(value_u8(req.kind.unwrap_or(fwd_kind::RESULT)));
        if let Some(p) = &req.payload {
            children.push(p.clone());
        }
    } else if req.op == fwd_op::WRITE {
        if let Some(p) = &req.payload {
            children.push(p.clone());
        }
    } else if req.op == fwd_op::AWAIT {
        if let Some(ns) = req.await_timeout_ns {
            children.push(value_u64(ns));
        }
    }

    Ok(Tlv {
        type_code: type_code::FWD,
        opt: Opt::structured(),
        payload: Vec::new(),
        children,
        trailer: None,
    })
}

/**
 * @brief Convenience: build a FWD frame directly to encoded bytes.
 *
 * # Errors
 * Any error from [`encode_fwd`], or [`BuildError::InvalidPathRef`] when the codec refused the
 * tree. [`FwdRequest::payload`] is a caller-supplied [`Tlv`] embedded verbatim, so a request
 * whose payload node is an ill-formed `PATH_REF` reaches [`crate::encode`]'s refusal — which
 * is an empty `Vec`, and this wrapper has a `Result`, so it says so rather than answering
 * `Ok` over a frame that is silently nothing.
 */
pub fn encode_fwd_bytes(req: &FwdRequest) -> Result<Vec<u8>, BuildError> {
    let bytes = crate::encode(&encode_fwd(req)?);
    if bytes.is_empty() {
        return Err(BuildError::InvalidPathRef);
    }
    Ok(bytes)
}

/* --------------------------------------------------------------- FWD parse --- */

/** @brief A parsed FWD frame, its children read positionally (RFC-0004 §B order). */
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ParsedFwd {
    /** @brief The operation (a [`fwd_op`] value). */
    pub op: u8,
    /** @brief The `dst` route child — a `PATH`, or a `PATH_REF` when [`Self::dst_bound`]. */
    pub dst: Tlv,
    /** @brief The optional FIELD selector child. */
    pub field: Option<Tlv>,
    /** @brief The `src` route child — a `PATH`, or a `PATH_REF` on a reply to a bound op. */
    pub src: Tlv,
    /** @brief The reply [`fwd_kind`] (REPLY frames only). */
    pub kind: Option<u8>,
    /** @brief The payload TLV child (WRITE payload / REPLY result), if present. */
    pub payload: Option<Tlv>,
    /** @brief The AWAIT `await_timeout` ns, if present. */
    pub await_timeout_ns: Option<u64>,
    /** @brief `op` bit 7 was set — the origin asked for a bound-path mint (RFC-0024 §7.5). */
    pub mint_request: bool,
    /** @brief `dst` is a `PATH_REF` (`0x14`), not a canonical `PATH` (RFC-0024 §4). */
    pub dst_bound: bool,
    /**
     * @brief The trailing reverse-direction list a mint-flagged FORWARDED request carries —
     * a `PATH_REF_REVERSE` (`0x15`), RFC-0024 §7.1 amendments 1 and 2.
     *
     * Identified by its TYPE, never by its position: a `WRITE`'s payload is whatever stands
     * in the payload slot as long as it is not this code, INCLUDING a raw `PATH_REF`. The
     * origin never emits the child, so this is `None` on every frame a client builds.
     */
    pub reverse: Option<Tlv>,
}

fn u8_of(t: &Tlv) -> u8 {
    t.payload.first().copied().unwrap_or(0)
}

/**
 * @brief Parse an already-decoded FWD [`Tlv`] positionally (RFC-0004 §B).
 *
 * # Errors
 * [`BuildError::TypeMismatch`] if the TLV is not a FWD or is missing a required
 * `op` / `dst` / `src` child.
 */
pub fn parse_fwd_tlv(fwd: &Tlv) -> Result<ParsedFwd, BuildError> {
    if fwd.type_code != type_code::FWD {
        return Err(BuildError::TypeMismatch);
    }
    let ch = &fwd.children;
    let mut i = 0;
    if ch.get(i).map(|c| c.type_code) != Some(type_code::VALUE) {
        return Err(BuildError::TypeMismatch);
    }
    // The opcode is `op & 0x3F`; bits 7-6 are flags (RFC-0024 §7.5, normative in §9.3).
    // Switching on the raw byte would make a mint-flagged READ an unknown opcode here.
    let op_byte = u8_of(&ch[i]);
    let op = op_byte & fwd_op::OPCODE_MASK;
    let mint_request = op_byte & fwd_op::FLAG_MINT_REQUEST != 0;
    i += 1;
    // Two address forms (RFC-0024 §4): a canonical PATH, or a bound PATH_REF whose body
    // shape the grammar has already checked. What an element MEANS is node-scoped, so a
    // binding core carries one and never interprets it.
    let dst_bound = ch.get(i).map(|c| c.type_code) == Some(type_code::PATH_REF);
    if !dst_bound && ch.get(i).map(|c| c.type_code) != Some(type_code::PATH) {
        return Err(BuildError::TypeMismatch);
    }
    let dst = ch[i].clone();
    i += 1;
    let mut field = None;
    if ch.get(i).map(|c| c.type_code) == Some(type_code::FIELD) {
        field = Some(ch[i].clone());
        i += 1;
    }
    // `src` takes either form too: a reply to a bound operation echoes the request's `dst`.
    let src_kind = ch.get(i).map(|c| c.type_code);
    if src_kind != Some(type_code::PATH) && src_kind != Some(type_code::PATH_REF) {
        return Err(BuildError::TypeMismatch);
    }
    let src = ch[i].clone();
    i += 1;

    let mut kind = None;
    let mut payload = None;
    let mut await_timeout_ns = None;
    if op == fwd_op::REPLY {
        if ch.get(i).map(|c| c.type_code) == Some(type_code::VALUE) {
            kind = Some(u8_of(&ch[i]));
            i += 1;
        }
        if i < ch.len() {
            payload = Some(ch[i].clone());
        }
    } else if op == fwd_op::WRITE {
        // The reverse list is told from the payload by its TYPE (RFC-0024 §7.1 amendment 2),
        // so a raw `PATH_REF` payload is a payload and only `0x15` is the list.
        if ch
            .get(i)
            .is_some_and(|c| c.type_code != type_code::PATH_REF_REVERSE)
        {
            payload = Some(ch[i].clone());
            i += 1;
        }
    } else if op == fwd_op::AWAIT {
        if let Some(c) = ch.get(i) {
            if c.type_code == type_code::VALUE && c.payload.len() >= 8 {
                await_timeout_ns = Some(c.payload_uint());
                i += 1;
            }
        }
    }

    // Licensed only on a mint-flagged request (§7.1 amendment 1): on an unflagged frame a
    // trailing `0x15` binds no route and stays unparsed.
    let reverse = if mint_request {
        ch.get(i)
            .filter(|c| c.type_code == type_code::PATH_REF_REVERSE)
            .cloned()
    } else {
        None
    };

    Ok(ParsedFwd {
        op,
        dst,
        field,
        src,
        kind,
        payload,
        await_timeout_ns,
        mint_request,
        dst_bound,
        reverse,
    })
}

/**
 * @brief Decode a complete FWD frame's bytes into its parsed children.
 *
 * # Errors
 * [`BuildError::TypeMismatch`] if the frame is not a decodable FWD (a codec
 * fault surfaces as `TypeMismatch`; use [`crate::decode`] directly for the
 * underlying [`crate::Error`]).
 */
pub fn decode_fwd(bytes: &[u8]) -> Result<ParsedFwd, BuildError> {
    let tlv = crate::decode(bytes).map_err(|_| BuildError::TypeMismatch)?;
    parse_fwd_tlv(&tlv)
}

/**
 * @brief The `dst` route of a parsed FWD in string form.
 *
 * # Errors
 * A PATH-decode error.
 */
pub fn fwd_dst_path(fwd: &ParsedFwd) -> Result<String, BuildError> {
    crate::path::tlv_to_path(&fwd.dst)
}

/**
 * @brief The `src` (accumulated return route) of a parsed FWD in string form.
 *
 * # Errors
 * A PATH-decode error.
 */
pub fn fwd_src_path(fwd: &ParsedFwd) -> Result<String, BuildError> {
    crate::path::tlv_to_path(&fwd.src)
}

/* ------------------------------------------------------------- reply errors --- */

/**
 * @brief The ERROR TLV of a `kind=ERROR` reply's `STATUS{ ERROR }` payload, or `None`.
 *
 * The **first ERROR child of the STATUS, at whatever position** — never `children[0]`.
 * reference/05 §`0x09` gives a STATUS "one or more ERROR TLVs and optional DESCRIPTION
 * text" and pins no order over them; RFC-0002 §C pins position only one level down,
 * INSIDE the ERROR ("its first child is the identity"). A reader that demands position 0
 * refuses a documented STATUS shape and answers code 0, which is what it also answers for
 * a STATUS carrying no ERROR at all.
 *
 * Vector-pinned by `fwd/fwd-reply-error-after-description` (the DESCRIPTION written
 * first), which the TypeScript binding pins against the same bytes so the two cores
 * cannot drift apart on it again (#878).
 */
fn reply_error_tlv(reply: &ParsedFwd) -> Option<&Tlv> {
    let status = reply.payload.as_ref()?;
    if status.type_code == type_code::STATUS {
        return status.first_child(type_code::ERROR);
    }
    None
}

/**
 * @brief The registered wire ERROR code of a `kind=ERROR` reply's
 * `STATUS{ ERROR{ VALUE u16 } }` payload (RFC-0002), or 0 when absent or when
 * the ERROR carries the string-form identity (see [`reply_error_path`]).
 */
pub fn reply_error_code(reply: &ParsedFwd) -> u16 {
    if let Some(err) = reply_error_tlv(reply) {
        if let Some(id) = err.children.first() {
            if id.type_code == type_code::VALUE && id.payload.len() >= 2 {
                return id.payload[0] as u16 | ((id.payload[1] as u16) << 8);
            }
        }
    }
    0
}

/**
 * @brief The string-form `tr::…` identity of a `kind=ERROR` reply's
 * `STATUS{ ERROR{ NAME } }` payload (RFC-0002), or `None` when the reply carries
 * no ERROR or a registered-code identity (see [`reply_error_code`]).
 *
 * # Errors
 * [`BuildError::InvalidUtf8`] if the NAME identity is not valid UTF-8.
 */
pub fn reply_error_path(reply: &ParsedFwd) -> Result<Option<String>, BuildError> {
    if let Some(err) = reply_error_tlv(reply) {
        if let Some(id) = err.children.first() {
            if id.type_code == type_code::NAME {
                return Ok(Some(id.payload_str()?.into()));
            }
        }
    }
    Ok(None)
}

/**
 * @brief Convenience: build a `dst`/`src` PATH from a rooted string (for callers that
 * have string paths rather than segment slices).
 *
 * # Errors
 * A path validation error.
 */
pub fn path_tlv_from_str(text: &str) -> Result<Tlv, BuildError> {
    path_to_tlv(text)
}