1use anyhow::{anyhow, ensure, Result};
11
12pub const ZMTP_VERSION_MAJOR: u8 = 3;
18pub const ZMTP_VERSION_MINOR: u8 = 1;
19
20pub const GREETING_SIZE: usize = 64;
22
23pub const MECHANISM_NULL: &[u8; 4] = b"NULL";
25
26pub const MAX_FRAME_SIZE: usize = 64 * 1024 * 1024;
28
29#[derive(Debug, Clone, Copy, PartialEq, Eq)]
35pub enum ZmqSocketType {
36 Req,
37 Rep,
38 Pub,
39 Sub,
40 XPub,
41 XSub,
42 Push,
43 Pull,
44}
45
46impl ZmqSocketType {
47 pub fn as_str(&self) -> &'static str {
49 match self {
50 Self::Req => "REQ",
51 Self::Rep => "REP",
52 Self::Pub => "PUB",
53 Self::Sub => "SUB",
54 Self::XPub => "XPUB",
55 Self::XSub => "XSUB",
56 Self::Push => "PUSH",
57 Self::Pull => "PULL",
58 }
59 }
60}
61
62impl std::str::FromStr for ZmqSocketType {
63 type Err = anyhow::Error;
64
65 fn from_str(s: &str) -> Result<Self> {
66 match s {
67 "REQ" => Ok(Self::Req),
68 "REP" => Ok(Self::Rep),
69 "PUB" => Ok(Self::Pub),
70 "SUB" => Ok(Self::Sub),
71 "XPUB" => Ok(Self::XPub),
72 "XSUB" => Ok(Self::XSub),
73 "PUSH" => Ok(Self::Push),
74 "PULL" => Ok(Self::Pull),
75 _ => Err(anyhow!("unknown socket type: {}", s)),
76 }
77 }
78}
79
80#[derive(Debug, Clone)]
82pub struct ZmtpFrame {
83 pub more: bool,
85 pub command: bool,
87 pub data: Vec<u8>,
89}
90
91#[derive(Debug, Clone)]
93pub struct ZmtpCommand {
94 pub name: String,
96 pub body: Vec<u8>,
98}
99
100impl ZmtpCommand {
101 pub fn parse(data: &[u8]) -> Result<Self> {
105 ensure!(!data.is_empty(), "Command frame body is empty");
106
107 let name_len = data[0] as usize;
108 ensure!(
109 name_len < data.len(),
110 "Command name truncated: need {} bytes, have {}",
111 1 + name_len,
112 data.len()
113 );
114
115 let name = std::str::from_utf8(&data[1..1 + name_len])?.to_owned();
116 let body = data[1 + name_len..].to_vec();
117
118 Ok(Self { name, body })
119 }
120}
121
122pub fn build_greeting() -> [u8; GREETING_SIZE] {
138 let mut greeting = [0u8; GREETING_SIZE];
139
140 greeting[0] = 0xFF;
142 greeting[9] = 0x7F;
143
144 greeting[10] = ZMTP_VERSION_MAJOR;
146 greeting[11] = ZMTP_VERSION_MINOR;
147
148 greeting[12..16].copy_from_slice(MECHANISM_NULL);
150
151 greeting
152}
153
154pub fn validate_greeting(greeting: &[u8]) -> Result<()> {
156 ensure!(
157 greeting.len() >= GREETING_SIZE,
158 "Greeting too short: {} bytes",
159 greeting.len()
160 );
161
162 ensure!(
163 greeting[0] == 0xFF,
164 "Invalid greeting signature byte 0: expected 0xFF"
165 );
166 ensure!(
167 greeting[1..9].iter().all(|&b| b == 0),
168 "Invalid greeting signature bytes 1-8: expected zeros"
169 );
170 ensure!(
171 greeting[9] == 0x7F,
172 "Invalid greeting signature byte 9: expected 0x7F"
173 );
174
175 ensure!(
177 greeting[10] == ZMTP_VERSION_MAJOR,
178 "ZMTP version mismatch: expected major {}, got {}",
179 ZMTP_VERSION_MAJOR,
180 greeting[10]
181 );
182
183 ensure!(
185 greeting[11] >= ZMTP_VERSION_MINOR,
186 "ZMTP version mismatch: expected minor >= {}, got {}",
187 ZMTP_VERSION_MINOR,
188 greeting[11]
189 );
190
191 let mechanism_name = &greeting[12..16];
193 ensure!(
194 mechanism_name == MECHANISM_NULL,
195 "ZMTP mechanism mismatch: expected NULL, got {:?}",
196 std::str::from_utf8(mechanism_name).unwrap_or("<invalid>")
197 );
198
199 ensure!(
201 greeting[16..32].iter().all(|&b| b == 0),
202 "ZMTP greeting has non-zero mechanism padding bytes"
203 );
204
205 ensure!(
207 greeting[32] == 0x00,
208 "NULL mechanism requires as-server=0x00, got 0x{:02X}",
209 greeting[32]
210 );
211
212 Ok(())
213}
214
215pub fn build_ready_metadata(socket_type: ZmqSocketType) -> Vec<u8> {
223 let name = b"Socket-Type";
224 let value = socket_type.as_str().as_bytes();
225
226 let mut buf = Vec::with_capacity(1 + name.len() + 4 + value.len());
227
228 buf.push(name.len() as u8);
229 buf.extend_from_slice(name);
230 buf.extend_from_slice(&(value.len() as u32).to_be_bytes());
231 buf.extend_from_slice(value);
232
233 buf
234}
235
236pub fn validate_ready_command(cmd: &ZmtpCommand) -> Result<()> {
238 ensure!(
239 cmd.name == "READY",
240 "Expected READY command, got {}",
241 cmd.name
242 );
243
244 let mut pos = 0;
245 let body = &cmd.body;
246
247 while pos < body.len() {
248 let name_len = body[pos] as usize;
249 pos += 1;
250
251 ensure!(
252 pos + name_len <= body.len(),
253 "READY metadata truncated at name"
254 );
255 let _name = std::str::from_utf8(&body[pos..pos + name_len])?;
256 pos += name_len;
257
258 ensure!(
259 pos + 4 <= body.len(),
260 "READY metadata truncated at value length"
261 );
262 let value_len =
263 u32::from_be_bytes([body[pos], body[pos + 1], body[pos + 2], body[pos + 3]]) as usize;
264 pos += 4;
265
266 ensure!(
267 pos + value_len <= body.len(),
268 "READY metadata truncated at value"
269 );
270 let _value = std::str::from_utf8(&body[pos..pos + value_len])?;
271 pos += value_len;
272 }
273
274 Ok(())
275}
276
277pub fn encode_frame(more: bool, command: bool, data: &[u8]) -> Vec<u8> {
283 let long = data.len() > 255;
284 let flags: u8 = (more as u8) | ((long as u8) << 1) | ((command as u8) << 2);
285
286 let header_len = 1 + if long { 8 } else { 1 };
287 let mut buf = Vec::with_capacity(header_len + data.len());
288 buf.push(flags);
289
290 if long {
291 buf.extend_from_slice(&(data.len() as u64).to_be_bytes());
292 } else {
293 buf.push(data.len() as u8);
294 }
295
296 buf.extend_from_slice(data);
297 buf
298}
299
300pub fn decode_frame(buf: &[u8]) -> Result<(ZmtpFrame, usize)> {
304 ensure!(!buf.is_empty(), "buffer empty");
305
306 let flags = buf[0];
307 let more = (flags & 0x01) != 0;
308 let long = (flags & 0x02) != 0;
309 let command = (flags & 0x04) != 0;
310
311 ensure!(
312 flags & 0xF8 == 0,
313 "ZMTP frame has reserved bits set: 0x{:02X}",
314 flags
315 );
316
317 let (size, header_len): (usize, usize) = if long {
318 ensure!(buf.len() >= 9, "buffer too short for long frame header");
319 let raw_size = u64::from_be_bytes([
320 buf[1], buf[2], buf[3], buf[4], buf[5], buf[6], buf[7], buf[8],
321 ]);
322 ensure!(
323 raw_size <= MAX_FRAME_SIZE as u64,
324 "frame size {} exceeds maximum {}",
325 raw_size,
326 MAX_FRAME_SIZE
327 );
328 (raw_size as usize, 9)
329 } else {
330 ensure!(buf.len() >= 2, "buffer too short for short frame header");
331 (buf[1] as usize, 2)
332 };
333
334 let total = header_len.checked_add(size).ok_or_else(|| {
335 anyhow!(
336 "frame size overflow: header_len={} + size={}",
337 header_len,
338 size
339 )
340 })?;
341 ensure!(
342 buf.len() >= total,
343 "buffer too short for frame body: need {}, have {}",
344 total,
345 buf.len()
346 );
347
348 let data = buf[header_len..header_len + size].to_vec();
349 Ok((
350 ZmtpFrame {
351 more,
352 command,
353 data,
354 },
355 header_len + size,
356 ))
357}
358
359pub fn encode_command(name: &str, body: &[u8]) -> Vec<u8> {
363 let name_bytes = name.as_bytes();
364 let mut cmd_body = Vec::with_capacity(1 + name_bytes.len() + body.len());
365 cmd_body.push(name_bytes.len() as u8);
366 cmd_body.extend_from_slice(name_bytes);
367 cmd_body.extend_from_slice(body);
368 encode_frame(false, true, &cmd_body)
369}
370
371pub fn encode_multipart(parts: &[&[u8]]) -> Vec<u8> {
375 let mut buf = Vec::new();
376 for (i, part) in parts.iter().enumerate() {
377 let more = i < parts.len() - 1;
378 buf.extend_from_slice(&encode_frame(more, false, part));
379 }
380 buf
381}
382
383pub fn decode_multipart(buf: &[u8]) -> Result<(Vec<Vec<u8>>, usize)> {
387 let mut parts = Vec::new();
388 let mut offset = 0;
389
390 loop {
391 ensure!(offset < buf.len(), "unexpected end of multipart message");
392 let (frame, consumed) = decode_frame(&buf[offset..])?;
393
394 ensure!(
395 !frame.command,
396 "unexpected command frame in multipart message"
397 );
398
399 let more = frame.more;
400 parts.push(frame.data);
401 offset += consumed;
402
403 if !more {
404 break;
405 }
406 }
407
408 Ok((parts, offset))
409}
410
411pub fn encode_multipart_flat(flat: &[u8]) -> Result<Vec<u8>> {
416 let parts = decode_flat_parts(flat)?;
417 let refs: Vec<&[u8]> = parts.iter().map(Vec::as_slice).collect();
418 Ok(encode_multipart(&refs))
419}
420
421pub fn decode_frames_to_flat(buf: &[u8]) -> Result<Vec<u8>> {
426 let mut result = Vec::new();
427 let mut offset = 0;
428
429 while offset < buf.len() {
430 let (frame, consumed) = decode_frame(&buf[offset..])?;
431
432 if frame.command {
434 offset += consumed;
435 continue;
436 }
437
438 result.extend_from_slice(&(frame.data.len() as u32).to_be_bytes());
439 result.extend_from_slice(&frame.data);
440 offset += consumed;
441
442 if !frame.more {
443 break;
444 }
445 }
446
447 Ok(result)
448}
449
450pub fn decode_flat_parts(flat: &[u8]) -> Result<Vec<Vec<u8>>> {
452 let mut parts = Vec::new();
453 let mut offset = 0;
454
455 while offset < flat.len() {
456 ensure!(
457 offset + 4 <= flat.len(),
458 "flat encoding truncated at length field"
459 );
460 let len = u32::from_be_bytes([
461 flat[offset],
462 flat[offset + 1],
463 flat[offset + 2],
464 flat[offset + 3],
465 ]) as usize;
466 offset += 4;
467
468 ensure!(
469 offset + len <= flat.len(),
470 "flat encoding truncated at data"
471 );
472 parts.push(flat[offset..offset + len].to_vec());
473 offset += len;
474 }
475
476 Ok(parts)
477}
478
479#[cfg(test)]
484#[allow(clippy::unwrap_used)]
485mod tests {
486 use super::*;
487
488 #[test]
489 fn greeting_roundtrip() {
490 let greeting = build_greeting();
491 assert_eq!(greeting.len(), GREETING_SIZE);
492 validate_greeting(&greeting).unwrap();
493 }
494
495 #[test]
496 fn greeting_rejects_bad_signature() {
497 let mut greeting = build_greeting();
498 greeting[0] = 0x00;
499 assert!(validate_greeting(&greeting).is_err());
500 }
501
502 #[test]
503 fn greeting_rejects_wrong_version() {
504 let mut greeting = build_greeting();
505 greeting[10] = 2; assert!(validate_greeting(&greeting).is_err());
507 }
508
509 #[test]
510 fn frame_short_roundtrip() {
511 let data = vec![0x42u8; 100];
512 let encoded = encode_frame(false, false, &data);
513 let (decoded, consumed) = decode_frame(&encoded).unwrap();
514
515 assert_eq!(consumed, encoded.len());
516 assert!(!decoded.more);
517 assert!(!decoded.command);
518 assert_eq!(decoded.data, data);
519 }
520
521 #[test]
522 fn frame_long_roundtrip() {
523 let data = vec![0xABu8; 500];
524 let encoded = encode_frame(false, false, &data);
525 let (decoded, consumed) = decode_frame(&encoded).unwrap();
526
527 assert_eq!(consumed, encoded.len());
528 assert!(!decoded.more);
529 assert!(!decoded.command);
530 assert_eq!(decoded.data, data);
531 assert_eq!(encoded[0] & 0x02, 0x02); }
533
534 #[test]
535 fn frame_more_flag() {
536 let data = b"test";
537 let encoded_more = encode_frame(true, false, data);
538 let encoded_last = encode_frame(false, false, data);
539
540 let (decoded_more, _) = decode_frame(&encoded_more).unwrap();
541 let (decoded_last, _) = decode_frame(&encoded_last).unwrap();
542
543 assert!(decoded_more.more);
544 assert!(!decoded_last.more);
545 }
546
547 #[test]
548 fn command_frame_roundtrip() {
549 let encoded = encode_command("READY", b"metadata");
550 let (frame, _) = decode_frame(&encoded).unwrap();
551
552 assert!(frame.command);
553 assert!(!frame.more);
554
555 let cmd = ZmtpCommand::parse(&frame.data).unwrap();
556 assert_eq!(cmd.name, "READY");
557 assert_eq!(cmd.body, b"metadata");
558 }
559
560 #[test]
561 fn multipart_roundtrip() {
562 let parts: Vec<&[u8]> = vec![b"identity", b"delimiter", b"payload"];
563 let encoded = encode_multipart(&parts);
564 let (decoded, consumed) = decode_multipart(&encoded).unwrap();
565
566 assert_eq!(consumed, encoded.len());
567 assert_eq!(decoded.len(), 3);
568 assert_eq!(decoded[0], b"identity");
569 assert_eq!(decoded[1], b"delimiter");
570 assert_eq!(decoded[2], b"payload");
571 }
572
573 #[test]
574 fn ready_metadata_roundtrip() {
575 let metadata = build_ready_metadata(ZmqSocketType::Rep);
576 let cmd_frame = encode_command("READY", &metadata);
577 let (frame, _) = decode_frame(&cmd_frame).unwrap();
578 let cmd = ZmtpCommand::parse(&frame.data).unwrap();
579 validate_ready_command(&cmd).unwrap();
580 }
581
582 #[test]
583 fn flat_encoding_roundtrip() {
584 let parts: Vec<&[u8]> = vec![b"hello", b"world"];
585 let encoded = encode_multipart(&parts);
586 let flat = decode_frames_to_flat(&encoded).unwrap();
587
588 let decoded_parts = decode_flat_parts(&flat).unwrap();
590 assert_eq!(decoded_parts.len(), 2);
591 assert_eq!(decoded_parts[0], b"hello");
592 assert_eq!(decoded_parts[1], b"world");
593
594 let re_encoded = encode_multipart_flat(&flat).unwrap();
596 let (re_decoded, _) = decode_multipart(&re_encoded).unwrap();
597 assert_eq!(re_decoded[0], b"hello");
598 assert_eq!(re_decoded[1], b"world");
599 }
600
601 #[test]
602 fn decode_frame_rejects_oversized() {
603 let mut buf = vec![0u8; 9];
605 buf[0] = 0x02; let oversized = (MAX_FRAME_SIZE as u64) + 1;
607 buf[1..9].copy_from_slice(&oversized.to_be_bytes());
608 assert!(decode_frame(&buf).is_err());
609 }
610
611 #[test]
612 fn decode_frame_rejects_overflow() {
613 let mut buf = vec![0u8; 9];
615 buf[0] = 0x02; buf[1..9].copy_from_slice(&u64::MAX.to_be_bytes());
617 assert!(decode_frame(&buf).is_err());
618 }
619
620 #[test]
621 fn greeting_rejects_mechanism_padding() {
622 let mut greeting = build_greeting();
623 greeting[20] = 0xFF; assert!(validate_greeting(&greeting).is_err());
625 }
626
627 #[test]
628 fn greeting_rejects_old_minor_version() {
629 let mut greeting = build_greeting();
630 greeting[11] = 0; assert!(validate_greeting(&greeting).is_err());
632 }
633
634 #[test]
635 fn decode_frames_to_flat_skips_commands() {
636 let cmd_frame = encode_command("READY", b"metadata");
638 let msg_frame = encode_frame(false, false, b"hello");
639 let mut buf = Vec::new();
640 buf.extend_from_slice(&cmd_frame);
642 buf[0] |= 0x01; buf.extend_from_slice(&msg_frame);
645
646 let flat = decode_frames_to_flat(&buf).unwrap();
647 let parts = decode_flat_parts(&flat).unwrap();
648 assert_eq!(parts.len(), 1);
649 assert_eq!(parts[0], b"hello");
650 }
651
652 #[test]
653 fn socket_type_roundtrip() {
654 for st in [
655 ZmqSocketType::Req,
656 ZmqSocketType::Rep,
657 ZmqSocketType::Pub,
658 ZmqSocketType::Sub,
659 ZmqSocketType::XPub,
660 ZmqSocketType::XSub,
661 ZmqSocketType::Push,
662 ZmqSocketType::Pull,
663 ] {
664 let s = st.as_str();
665 let parsed: ZmqSocketType = s.parse().unwrap();
666 assert_eq!(parsed, st);
667 }
668 }
669}