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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright 2026 avatarsd LLC
/*!
* @brief PATH string ⇄ TLV conversion + validation (Unit 2).
*
* Mirrors the address-portion parsing of `core/src/path.cpp` (`path_t::parse`):
* a path is rooted at `/`, split on `/`, each segment validated (1..64 bytes,
* no reserved character `/ : . [ ] * ?`), at most [`MAX_SEGMENTS`] segments and
* [`MAX_PATH_BYTES`] total encoded body bytes. Vector-pinned: `path-sensor-temp`.
*
* Since RFC-0018 a `PATH` body is `opt.PL = 0` and holds packed `[u8 len][utf8]` segment
* RECORDS rather than `NAME` child TLVs, so everything here reads and writes the body
* directly. `NAME` itself is untouched — it still spells SETTINGS keys and `:schema`
* labels; the RFC removes it from `PATH` bodies only.
*
* The two accumulative bounds (segment count, total encoded body) sit at the
* construction/admission tier — [`split_path`] (count) and `tlv_builders::path`
* (bytes) on the way in from a string, and [`admit_path_tlv`] (both) on the way
* in from decoded bytes — never at decode
* ([`tlv_to_path`]), per `docs/reference/05-protocol-tlvs.md` §"Enforcement of the PATH
* constraints" and RFC-0023 §5.6.
*/
use String;
use Vec;
use crate;
use crate::;
/**
* @brief Split a rooted path string (`"/sensor/temp"`) into its validated segments
* (`["sensor", "temp"]`). The root `"/"` yields an empty slice (the graph root).
*
* The string must be rooted at `/`; trailing slashes are stripped (the root is
* preserved). Each segment is validated per [`validate_segment`].
*
* # Errors
* [`BuildError::NotRooted`] if not `/`-rooted, [`BuildError::SegmentLength`] /
* [`BuildError::ReservedChar`] on an invalid segment, or
* [`BuildError::TooManySegments`] beyond [`MAX_SEGMENTS`].
*/
/**
* @brief Convert a rooted path string into a PATH TLV (`type=0x06`, `PL=0`, packed body).
* Vector-pinned: `path-sensor-temp` (`"/sensor/temp"`).
*
* # Errors
* Any error from [`split_path`] or from building the [`Tlv`] (including
* [`BuildError::EmptyPath`] for the root, or [`BuildError::PathTooLong`]).
*/
/**
* @brief Convert a PATH TLV back into its rooted string form (`"/sensor/temp"`). A PATH
* with an empty body renders as the root `"/"`.
*
* This is the **decode tier**: it renders, it does not admit. The segment-count and
* total-length bounds are enforced by [`admit_path_tlv`] (and, on the encode side, by
* [`split_path`] / [`crate::tlv_builders::path`]) — see that function for why.
*
* Rendering IS canonical / key context — the caller wants a spelling it can look an address
* up by — so the RFC-0018 §5.4 `len == 0` escape is refused here rather than skipped.
*
* # Errors
* [`BuildError::TypeMismatch`] if the TLV is not a PATH or carries a structured body,
* [`BuildError::InvalidUtf8`] on a non-UTF-8 segment, or
* [`BuildError::SegmentLength`] / [`BuildError::ReservedChar`] on ragged framing, an escape
* record, or a segment that could not be rendered back into a re-splittable rooted string.
*/
/**
* @brief Admit a decoded PATH TLV as an *address* — the construction/admission-tier gate
* that `docs/reference/05-protocol-tlvs.md` §"Enforcement of the PATH constraints" names
* as the home of the length and segment-count limits (RFC-0023 §5.6).
*
* Call this where a foreign PATH stops being bytes and becomes an address a resolver will
* spell: before a vertex lookup, before storing a `SUBSCRIBER` target, before accepting a
* `FWD` `dst` as this node's own address. Do **not** call it on a `src` return route being
* forwarded on: that route accumulates a hop per forward and is legal at any byte-reachable
* depth, which is precisely why the bound does not live in [`tlv_to_path`].
*
* The predicate is the encode-time MUST of [`crate::tlv_builders::path`], evaluated over an
* already-decoded tree: `(records ≤ `[`MAX_SEGMENTS`]`) ∧ (each record a valid literal
* segment) ∧ (body ≤ `[`MAX_PATH_BYTES`]`)`. A PATH with an empty body is the graph root and
* is admitted. The RFC-0018 §5.4 escape is refused — admission is exactly the canonical/key
* door the escape is not admissible at.
*
* # Errors
* [`BuildError::TypeMismatch`] if the TLV is not a PATH or carries a structured body,
* [`BuildError::TooManySegments`] beyond [`MAX_SEGMENTS`], [`BuildError::PathTooLong`]
* beyond [`MAX_PATH_BYTES`], [`BuildError::InvalidUtf8`] on a non-UTF-8 segment, or
* [`BuildError::SegmentLength`] / [`BuildError::ReservedChar`] on ragged framing, an escape
* record, or an invalid segment.
*/