Skip to main content

hyprstream_rpc/
zmtp_framing.rs

1//! Pure ZMTP 3.1 framing — zero I/O, zero async, wasm32-safe.
2//!
3//! This module provides synchronous byte-manipulation functions for ZMTP 3.1
4//! frame encoding/decoding, greeting construction/validation, and command parsing.
5//! It is compiled on **all** targets (including wasm32) and serves as the single
6//! source of truth for ZMTP wire format logic.
7//!
8//! Async I/O wrappers live in `transport::zmtp_quic::ZmtpStream`.
9
10use anyhow::{anyhow, ensure, Result};
11
12// ============================================================================
13// Constants
14// ============================================================================
15
16/// ZMTP protocol version.
17pub const ZMTP_VERSION_MAJOR: u8 = 3;
18pub const ZMTP_VERSION_MINOR: u8 = 1;
19
20/// ZMTP greeting size (always 64 bytes).
21pub const GREETING_SIZE: usize = 64;
22
23/// ZMTP mechanism name for NULL (no encryption at ZMTP layer).
24pub const MECHANISM_NULL: &[u8; 4] = b"NULL";
25
26/// Maximum allowed frame size (64 MiB) — prevents unbounded allocation from malicious frames.
27pub const MAX_FRAME_SIZE: usize = 64 * 1024 * 1024;
28
29// ============================================================================
30// Types
31// ============================================================================
32
33/// ZMQ socket types for ZMTP handshake.
34#[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    /// Get the ZMTP socket type string.
48    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/// A parsed ZMTP frame (owned, no `Bytes` dependency).
81#[derive(Debug, Clone)]
82pub struct ZmtpFrame {
83    /// MORE flag: true if more frames follow in this message.
84    pub more: bool,
85    /// COMMAND flag: true if this is a command frame, false for message frame.
86    pub command: bool,
87    /// Frame body data.
88    pub data: Vec<u8>,
89}
90
91/// A parsed ZMTP command.
92#[derive(Debug, Clone)]
93pub struct ZmtpCommand {
94    /// Command name (e.g., "READY", "SUBSCRIBE", "CANCEL").
95    pub name: String,
96    /// Command-specific body.
97    pub body: Vec<u8>,
98}
99
100impl ZmtpCommand {
101    /// Parse a command from frame body data.
102    ///
103    /// Format: `<name-size (1 byte)><name><body>`
104    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
122// ============================================================================
123// Greeting
124// ============================================================================
125
126/// Build the 64-byte ZMTP greeting.
127///
128/// Format:
129/// ```text
130/// Bytes  0–9:  Signature: 0xFF + 8×0x00 + 0x7F
131/// Byte    10:  Version major: 0x03
132/// Byte    11:  Version minor: 0x01
133/// Bytes 12–31: Mechanism: "NULL" + 16×0x00 (padded to 20 bytes)
134/// Byte    32:  as-server: 0x00 (MUST be zero for NULL mechanism)
135/// Bytes 33–63: Reserved: 31×0x00
136/// ```
137pub fn build_greeting() -> [u8; GREETING_SIZE] {
138    let mut greeting = [0u8; GREETING_SIZE];
139
140    // Signature: 0xFF + 8 zeros + 0x7F
141    greeting[0] = 0xFF;
142    greeting[9] = 0x7F;
143
144    // Version: 3.1
145    greeting[10] = ZMTP_VERSION_MAJOR;
146    greeting[11] = ZMTP_VERSION_MINOR;
147
148    // Mechanism: "NULL" padded to 20 bytes
149    greeting[12..16].copy_from_slice(MECHANISM_NULL);
150
151    greeting
152}
153
154/// Validate a peer's ZMTP greeting.
155pub 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    // Check version (major must match)
176    ensure!(
177        greeting[10] == ZMTP_VERSION_MAJOR,
178        "ZMTP version mismatch: expected major {}, got {}",
179        ZMTP_VERSION_MAJOR,
180        greeting[10]
181    );
182
183    // Check minor version
184    ensure!(
185        greeting[11] >= ZMTP_VERSION_MINOR,
186        "ZMTP version mismatch: expected minor >= {}, got {}",
187        ZMTP_VERSION_MINOR,
188        greeting[11]
189    );
190
191    // Check mechanism is "NULL"
192    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    // Check mechanism padding (bytes 16..32 must be zero)
200    ensure!(
201        greeting[16..32].iter().all(|&b| b == 0),
202        "ZMTP greeting has non-zero mechanism padding bytes"
203    );
204
205    // For NULL mechanism, as-server MUST be 0x00 (RFC 37)
206    ensure!(
207        greeting[32] == 0x00,
208        "NULL mechanism requires as-server=0x00, got 0x{:02X}",
209        greeting[32]
210    );
211
212    Ok(())
213}
214
215// ============================================================================
216// READY metadata
217// ============================================================================
218
219/// Build READY metadata with size-prefixed property encoding (RFC 37).
220///
221/// Format: `<name-length (1 byte)><name><value-length (4 bytes BE)><value>`
222pub 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
236/// Validate a READY command.
237pub 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
277// ============================================================================
278// Frame encoding / decoding
279// ============================================================================
280
281/// Encode a single ZMTP frame to bytes.
282pub 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
300/// Decode a single ZMTP frame from a buffer.
301///
302/// Returns `(frame, bytes_consumed)`.
303pub 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
359/// Encode a ZMTP command frame.
360///
361/// Command frame body format: `<name-size (1 byte)><name><body>`
362pub 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
371/// Encode a multipart message as ZMTP frames.
372///
373/// Each part becomes one message frame (COMMAND=0). The last frame has MORE=0.
374pub 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
383/// Decode a multipart message from a buffer of concatenated ZMTP frames.
384///
385/// Returns `(parts, total_bytes_consumed)`.
386pub 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
411/// Encode multipart with flat encoding for WASM boundary.
412///
413/// Input: `[4B-len, data, 4B-len, data, ...]`
414/// Output: ZMTP-framed bytes.
415pub 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
421/// Decode ZMTP frames to flat encoding for WASM boundary.
422///
423/// Input: concatenated ZMTP frames.
424/// Output: `[4B-len, data, 4B-len, data, ...]`
425pub 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        // Skip command frames — only include message data frames
433        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
450/// Decode flat-encoded parts: `[4B-len, data, 4B-len, data, ...]`
451pub 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// ============================================================================
480// Tests
481// ============================================================================
482
483#[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; // Wrong major
506        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); // LONG bit set
532    }
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        // Flat format: [4B-len, data, 4B-len, data]
589        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        // Re-encode from flat
595        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        // Construct a long frame header claiming MAX_FRAME_SIZE + 1 bytes
604        let mut buf = vec![0u8; 9];
605        buf[0] = 0x02; // LONG flag
606        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        // Construct a long frame header with u64::MAX to trigger overflow
614        let mut buf = vec![0u8; 9];
615        buf[0] = 0x02; // LONG flag
616        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; // Non-zero in mechanism padding area (bytes 16..32)
624        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; // Minor version 0 < required 1
631        assert!(validate_greeting(&greeting).is_err());
632    }
633
634    #[test]
635    fn decode_frames_to_flat_skips_commands() {
636        // Build: command frame + message frame
637        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        // Set MORE on command frame so parsing continues
641        buf.extend_from_slice(&cmd_frame);
642        // Manually set MORE flag on the command frame
643        buf[0] |= 0x01; // MORE=1
644        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}