net-wire 0.1.0

Allocation-free no_std wire views and codecs for network protocols.
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

use crate::error::ParseError;

use super::address::MacAddress;
use super::ether_type::EtherType;

pub(super) const HEADER_LENGTH: usize = 14;
const DESTINATION: core::ops::Range<usize> = 0..6;
const SOURCE: core::ops::Range<usize> = 6..12;
const ETHER_TYPE: core::ops::Range<usize> = 12..14;

/// A validated immutable borrow of one Ethernet II frame.
///
/// The fixed destination, source, and protocol-type header order follows
/// [RFC 894](https://www.rfc-editor.org/rfc/rfc894). Callers must remove any frame check
/// sequence (FCS) before parsing because every supplied byte after the fixed header is
/// payload.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct EthernetFrame<'a> {
    bytes: &'a [u8],
}

impl<'a> EthernetFrame<'a> {
    /// Validates and borrows an Ethernet II frame.
    ///
    /// The parser rejects inputs shorter than the 14-octet destination/source/type
    /// header described by [RFC 894](https://www.rfc-editor.org/rfc/rfc894). Every
    /// remaining supplied octet is exposed unchanged as payload; callers must remove any
    /// frame check sequence (FCS) before parsing. No minimum payload length is imposed by
    /// this wire view.
    pub fn parse(bytes: &'a [u8]) -> Result<Self, ParseError> {
        validate_frame_length(bytes.len())?;
        Ok(Self { bytes })
    }

    /// Returns the destination Ethernet address.
    ///
    /// RFC 894 places the destination address in the first six octets of the Ethernet
    /// header: <https://www.rfc-editor.org/rfc/rfc894>.
    #[inline]
    pub fn destination(&self) -> MacAddress {
        MacAddress::new(
            self.bytes[DESTINATION]
                .try_into()
                .expect("validated header"),
        )
    }

    /// Returns the source Ethernet address.
    ///
    /// RFC 894 places the source address immediately after the destination address:
    /// <https://www.rfc-editor.org/rfc/rfc894>.
    #[inline]
    pub fn source(&self) -> MacAddress {
        MacAddress::new(self.bytes[SOURCE].try_into().expect("validated header"))
    }

    /// Returns the Ethernet protocol type.
    ///
    /// RFC 894 places the two-octet protocol type after the source address and transmits
    /// it most-significant octet first: <https://www.rfc-editor.org/rfc/rfc894>.
    #[inline]
    pub fn ether_type(&self) -> EtherType {
        EtherType::new(u16::from_be_bytes(
            self.bytes[ETHER_TYPE].try_into().expect("validated header"),
        ))
    }

    /// Returns the payload bytes following the fixed Ethernet II header.
    ///
    /// This is the data field after the type field in the RFC 894 Ethernet encapsulation:
    /// <https://www.rfc-editor.org/rfc/rfc894>. The returned slice borrows the input.
    #[inline]
    pub fn payload(&self) -> &'a [u8] {
        &self.bytes[HEADER_LENGTH..]
    }

    /// Returns all represented frame bytes.
    ///
    /// The byte layout is the destination/source/type/payload order described by
    /// [RFC 894](https://www.rfc-editor.org/rfc/rfc894). Callers must remove any frame
    /// check sequence (FCS) before parsing; it cannot be distinguished from payload here.
    #[inline]
    pub fn as_bytes(&self) -> &'a [u8] {
        self.bytes
    }
}

/// A validated mutable borrow of one Ethernet II frame.
///
/// Its fixed header uses the destination, source, and protocol-type order described by
/// [RFC 894](https://www.rfc-editor.org/rfc/rfc894). Callers must remove any frame check
/// sequence (FCS) before parsing because every supplied byte after the fixed header is
/// payload.
#[derive(Debug, Eq, PartialEq)]
pub struct EthernetFrameMut<'a> {
    bytes: &'a mut [u8],
}

impl<'a> EthernetFrameMut<'a> {
    pub(super) fn from_validated(bytes: &'a mut [u8]) -> Self {
        Self { bytes }
    }

    /// Validates and mutably borrows an Ethernet II frame.
    ///
    /// The parser rejects inputs shorter than the 14-octet destination/source/type
    /// header described by [RFC 894](https://www.rfc-editor.org/rfc/rfc894). Every
    /// remaining supplied octet is payload and remains available for independent protocol
    /// parsing; callers must remove any frame check sequence (FCS) before parsing.
    pub fn parse(bytes: &'a mut [u8]) -> Result<Self, ParseError> {
        validate_frame_length(bytes.len())?;
        Ok(Self { bytes })
    }

    /// Returns the destination Ethernet address.
    ///
    /// RFC 894 assigns the first six header octets to the destination address:
    /// <https://www.rfc-editor.org/rfc/rfc894>.
    #[inline]
    pub fn destination(&self) -> MacAddress {
        MacAddress::new(
            self.bytes[DESTINATION]
                .try_into()
                .expect("validated header"),
        )
    }

    /// Returns the source Ethernet address.
    ///
    /// RFC 894 assigns the next six header octets to the source address:
    /// <https://www.rfc-editor.org/rfc/rfc894>.
    #[inline]
    pub fn source(&self) -> MacAddress {
        MacAddress::new(self.bytes[SOURCE].try_into().expect("validated header"))
    }

    /// Returns the Ethernet protocol type.
    ///
    /// RFC 894 places this two-octet, most-significant-octet-first field after the source
    /// address: <https://www.rfc-editor.org/rfc/rfc894>.
    #[inline]
    pub fn ether_type(&self) -> EtherType {
        EtherType::new(u16::from_be_bytes(
            self.bytes[ETHER_TYPE].try_into().expect("validated header"),
        ))
    }

    /// Replaces the destination Ethernet address.
    ///
    /// This writes the first six header octets assigned to the destination address by
    /// [RFC 894](https://www.rfc-editor.org/rfc/rfc894).
    #[inline]
    pub fn set_destination(&mut self, address: MacAddress) {
        self.bytes[DESTINATION].copy_from_slice(&address.octets());
    }

    /// Replaces the source Ethernet address.
    ///
    /// This writes the six header octets assigned to the source address by
    /// [RFC 894](https://www.rfc-editor.org/rfc/rfc894).
    #[inline]
    pub fn set_source(&mut self, address: MacAddress) {
        self.bytes[SOURCE].copy_from_slice(&address.octets());
    }

    /// Replaces the Ethernet protocol type.
    ///
    /// This writes the most-significant-octet-first type field specified by
    /// [RFC 894](https://www.rfc-editor.org/rfc/rfc894).
    #[inline]
    pub fn set_ether_type(&mut self, ether_type: EtherType) {
        self.bytes[ETHER_TYPE].copy_from_slice(&ether_type.raw().to_be_bytes());
    }

    /// Returns the payload bytes following the fixed Ethernet II header.
    ///
    /// This borrows the data field after the type field in RFC 894's encapsulation:
    /// <https://www.rfc-editor.org/rfc/rfc894>.
    #[inline]
    pub fn payload(&self) -> &[u8] {
        &self.bytes[HEADER_LENGTH..]
    }

    /// Returns mutable payload bytes following the fixed Ethernet II header.
    ///
    /// This mutably borrows the data field after the type field in RFC 894's
    /// encapsulation: <https://www.rfc-editor.org/rfc/rfc894>.
    #[inline]
    pub fn payload_mut(&mut self) -> &mut [u8] {
        &mut self.bytes[HEADER_LENGTH..]
    }

    /// Returns all represented frame bytes.
    ///
    /// The represented order is destination, source, type, then payload as described by
    /// [RFC 894](https://www.rfc-editor.org/rfc/rfc894).
    #[inline]
    pub fn as_bytes(&self) -> &[u8] {
        self.bytes
    }

    /// Returns all represented mutable frame bytes.
    ///
    /// The represented order is destination, source, type, then payload as described by
    /// [RFC 894](https://www.rfc-editor.org/rfc/rfc894).
    #[inline]
    pub fn as_bytes_mut(&mut self) -> &mut [u8] {
        self.bytes
    }
}

fn validate_frame_length(available: usize) -> Result<(), ParseError> {
    if available < HEADER_LENGTH {
        return Err(ParseError::Truncated {
            minimum: HEADER_LENGTH,
            available,
        });
    }
    Ok(())
}