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
//! Control-plane messages carried inside transport frames.
use bytes::{Buf, BufMut, Bytes, BytesMut};
use pim_core::{FrameCodec, NodeId, PimError};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
/// Discriminator for [`ControlFrame`] payloads.
///
/// Tag values `0x01` and `0x02` were previously assigned to
/// `IpRequest` / `IpAssign`. They were removed when mesh addresses
/// became deterministic from each node's `NodeId` (no more dynamic
/// allocation handshake). The slots are kept reserved on the wire so
/// any straggling old daemon's frames decode to a clean error rather
/// than aliasing a future tag.
pub enum ControlType {
/// Peer is leaving and wants its state cleaned up promptly.
Goodbye = 0x03,
/// Session keys should be renegotiated.
Rekey = 0x04,
/// RTT probe request.
Ping = 0x05,
/// RTT probe response.
Pong = 0x06,
/// One-shot exchange of node identity metadata after handshake.
PeerInfo = 0x07,
/// Generic plugin-defined payload — see [`ControlFrame::PluginPayload`].
PluginPayload = 0x08,
}
impl ControlType {
/// Decode a raw control-type tag from the wire.
pub fn from_u8(v: u8) -> Result<Self, PimError> {
match v {
0x03 => Ok(Self::Goodbye),
0x04 => Ok(Self::Rekey),
0x05 => Ok(Self::Ping),
0x06 => Ok(Self::Pong),
0x07 => Ok(Self::PeerInfo),
0x08 => Ok(Self::PluginPayload),
other => Err(PimError::Protocol(format!(
"unknown control type: 0x{other:02x}"
))),
}
}
}
/// Multiplexed control message.
///
/// Layout: control_type(1) + body (variable, depends on type).
///
/// Mesh-essential variants (routing, liveness, identity) live here
/// directly. Optional features such as user messaging are carried
/// inside [`ControlFrame::PluginPayload`] so the daemon can be built
/// without those plugins compiled in.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ControlFrame {
/// Graceful disconnect notification.
Goodbye {
/// Node that is departing.
departing_id: NodeId,
/// Implementation-defined reason code.
reason: u8,
},
/// Request that the session be rekeyed.
Rekey,
/// Ping carrying an opaque nonce.
Ping {
/// Opaque value echoed by the corresponding pong.
nonce: u64,
},
/// Pong echoing a ping nonce.
Pong {
/// Opaque value copied from the ping request.
nonce: u64,
},
/// Identity metadata exchanged once after the session is established
/// so that peers can address each other by `NodeId` and end-to-end
/// encrypt to the recipient's static X25519 key.
PeerInfo {
/// X25519 public key derived from the sender's Ed25519 seed.
x25519_pub: [u8; 32],
/// Sender's friendly node name as configured locally (UTF-8,
/// length-prefixed by `u8` — capped at 255 bytes by the codec).
friendly_name: String,
},
/// Generic plugin-defined payload.
///
/// `kind` is an ASCII identifier (≤ 255 bytes) registered by a
/// [`pim-plugin`](https://crates.io/crates/pim-plugin)-style
/// plugin (e.g. `"messaging.msg"`). `body` is plugin-private and
/// opaque to the daemon — typically further encrypted/serialized
/// according to the plugin's own scheme.
///
/// Wire layout:
/// ```text
/// 0x08
/// kind_len (u8, 1..=255)
/// kind (kind_len bytes, ASCII)
/// body_len (u16 BE)
/// body (body_len bytes)
/// ```
PluginPayload {
/// Plugin-namespaced kind identifier.
kind: String,
/// Opaque payload bytes — interpretation is up to the plugin
/// claiming `kind`.
body: Bytes,
},
}
impl FrameCodec for ControlFrame {
fn encode(&self, buf: &mut BytesMut) {
match self {
ControlFrame::Goodbye {
departing_id,
reason,
} => {
buf.put_u8(ControlType::Goodbye as u8);
buf.put_slice(departing_id.as_bytes());
buf.put_u8(*reason);
}
ControlFrame::Rekey => {
buf.put_u8(ControlType::Rekey as u8);
}
ControlFrame::Ping { nonce } => {
buf.put_u8(ControlType::Ping as u8);
buf.put_u64(*nonce);
}
ControlFrame::Pong { nonce } => {
buf.put_u8(ControlType::Pong as u8);
buf.put_u64(*nonce);
}
ControlFrame::PeerInfo {
x25519_pub,
friendly_name,
} => {
buf.put_u8(ControlType::PeerInfo as u8);
buf.put_slice(x25519_pub);
let name_bytes = friendly_name.as_bytes();
let name_len = name_bytes.len().min(255) as u8;
buf.put_u8(name_len);
buf.put_slice(&name_bytes[..name_len as usize]);
}
ControlFrame::PluginPayload { kind, body } => {
buf.put_u8(ControlType::PluginPayload as u8);
let kind_bytes = kind.as_bytes();
let kind_len = kind_bytes.len().min(255) as u8;
buf.put_u8(kind_len);
buf.put_slice(&kind_bytes[..kind_len as usize]);
let body_len = body.len().min(u16::MAX as usize) as u16;
buf.put_u16(body_len);
buf.put_slice(&body[..body_len as usize]);
}
}
}
fn decode(buf: &mut BytesMut) -> Result<Self, PimError> {
if buf.is_empty() {
return Err(PimError::Protocol("control frame empty".into()));
}
let control_type = ControlType::from_u8(buf[0])?;
match control_type {
ControlType::Goodbye => {
if buf.len() < 18 {
// 1 + 16 + 1
return Err(PimError::Protocol("Goodbye too short".into()));
}
let mut id = [0u8; 16];
id.copy_from_slice(&buf[1..17]);
let reason = buf[17];
buf.advance(18);
Ok(ControlFrame::Goodbye {
departing_id: NodeId::from_bytes(id),
reason,
})
}
ControlType::Rekey => {
buf.advance(1);
Ok(ControlFrame::Rekey)
}
ControlType::Ping => {
if buf.len() < 9 {
return Err(PimError::Protocol("Ping too short".into()));
}
let nonce = (&buf[1..9]).get_u64();
buf.advance(9);
Ok(ControlFrame::Ping { nonce })
}
ControlType::Pong => {
if buf.len() < 9 {
return Err(PimError::Protocol("Pong too short".into()));
}
let nonce = (&buf[1..9]).get_u64();
buf.advance(9);
Ok(ControlFrame::Pong { nonce })
}
ControlType::PeerInfo => {
// 1 (tag) + 32 (x25519) + 1 (name_len) + N (name)
if buf.len() < 34 {
return Err(PimError::Protocol("PeerInfo too short".into()));
}
let mut x25519_pub = [0u8; 32];
x25519_pub.copy_from_slice(&buf[1..33]);
let name_len = buf[33] as usize;
let total = 34 + name_len;
if buf.len() < total {
return Err(PimError::Protocol(format!(
"PeerInfo truncated: need {total}, have {}",
buf.len()
)));
}
let friendly_name = match std::str::from_utf8(&buf[34..total]) {
Ok(s) => s.to_owned(),
Err(_) => {
return Err(PimError::Protocol(
"PeerInfo friendly_name not valid UTF-8".into(),
))
}
};
buf.advance(total);
Ok(ControlFrame::PeerInfo {
x25519_pub,
friendly_name,
})
}
ControlType::PluginPayload => {
// 1 (tag) + 1 (kind_len) + N (kind) + 2 (body_len) + M (body)
if buf.len() < 4 {
return Err(PimError::Protocol("PluginPayload too short".into()));
}
let kind_len = buf[1] as usize;
let body_len_off = 2 + kind_len;
if buf.len() < body_len_off + 2 {
return Err(PimError::Protocol(format!(
"PluginPayload header truncated: need {}, have {}",
body_len_off + 2,
buf.len()
)));
}
let kind = match std::str::from_utf8(&buf[2..body_len_off]) {
Ok(s) => s.to_owned(),
Err(_) => {
return Err(PimError::Protocol(
"PluginPayload kind not valid UTF-8".into(),
))
}
};
let body_len = (&buf[body_len_off..body_len_off + 2]).get_u16() as usize;
let total = body_len_off + 2 + body_len;
if buf.len() < total {
return Err(PimError::Protocol(format!(
"PluginPayload truncated: need {total}, have {}",
buf.len()
)));
}
let body = Bytes::copy_from_slice(&buf[body_len_off + 2..total]);
buf.advance(total);
Ok(ControlFrame::PluginPayload { kind, body })
}
}
}
}
#[cfg(test)]
mod tests;