ethox 0.0.2

A standalone network stack for user-space networking and unikernels
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
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

//! CIDR, relevant rfc1519, rfc4632.
//!
use crate::layer::{Error, Result};
use crate::managed::{List, Slice};
use crate::time::{Expiration, Instant};
use crate::wire::ip::{v4, v6, Address, Cidr, Subnet};

/// A prefix of addresses that should be routed via a router
#[derive(Debug, Clone, Copy)]
pub struct Route {
    /// The network routed through this route.
    ///
    /// Better only set actual networks here. Although host identifiers (where not all bits outside
    /// the subnet mask are zero) and broadcast (where these bits are all ones) are accepted, they
    /// may lead to unexpected routing decisions.
    pub net: Subnet,

    /// Next hop for this network.
    pub next_hop: Address,

    /// Expired routes are never considered.
    pub expires_at: Expiration,
}

impl Route {
    /// A route without specified target.
    ///
    /// May be used as a placeholder for storage where the address is not assigned yet and where
    /// the more specific placeholders `ipv4_invalid` and `ipv6_invalid` are less precise.
    pub fn unspecified() -> Self {
        Route {
            net: Cidr::new(Address::v4(0, 0, 0, 0), 0).subnet(),
            next_hop: Address::Unspecified,
            expires_at: Expiration::Never,
        }
    }

    /// Establishes a routing `0.0.0.0/0` to `0.0.0.0`.
    ///
    /// You can freely use this as an initializer for a slice of routes. Network addresses within
    /// `0.0.0.0/8` are only valid as source addresses.
    pub fn ipv4_invalid() -> Self {
        Route {
            net: Cidr::new(Address::v4(0, 0, 0, 0), 0).subnet(),
            next_hop: Address::v4(0, 0, 0, 0).into(),
            expires_at: Expiration::Never,
        }
    }

    /// A route `::/0` to the reserved, 'unspecified' `::/128` address.
    pub fn ipv6_invalid() -> Self {
        Route {
            net: Cidr::new(Address::v6(0, 0, 0, 0, 0, 0, 0, 0), 0).subnet(),
            next_hop: Address::v6(0, 0, 0, 0, 0, 0, 0, 0).into(),
            expires_at: Expiration::Never,
        }
    }

    /// Returns a route match `0.0.0.0/0` via the `gateway`, with no expiry.
    ///
    /// This route is a worst match for all addresses so that it can be used as a sink, for
    /// example.
    pub fn new_ipv4_gateway(gateway: v4::Address) -> Route {
        Route {
            net: Cidr::new(Address::v4(0, 0, 0, 0), 0).subnet(),
            next_hop: gateway.into(),
            expires_at: Expiration::Never,
        }
    }

    /// Returns a route match `::/0` via the `gateway`, with no expiry.
    ///
    /// This route is a worst match for all addresses so that it can be used as a sink, for
    /// example.
    pub fn new_ipv6_gateway(gateway: v6::Address) -> Route {
        Route {
            net: Cidr::new(Address::v6(0, 0, 0, 0, 0, 0, 0, 0), 0).subnet(),
            next_hop: gateway.into(),
            expires_at: Expiration::Never,
        }
    }
}

/// A routing table.
///
/// # Examples
///
/// On systems with heap, this table can be created with:
///
/// ```rust
/// # #[cfg(feature = "std")] {
/// use ethox::layer::ip::{Route, Routes};
/// use ethox::managed::List;
/// 
/// let mut routes_storage = vec![Route::unspecified(); 10];
/// let mut routes = Routes::new(routes_storage);
/// # }
/// ```
///
/// On systems without heap, use:
///
/// ```rust
/// use ethox::layer::ip::{Route, Routes};
///
/// let mut routes_storage = [Route::unspecified(); 10];
/// let mut routes = Routes::new(&mut routes_storage[..]);
/// ```
#[derive(Debug)]
pub struct Routes<'a> {
    storage: List<'a, Route>,
}

impl<'a> Routes<'a> {
    /// Creates an empty routing tables.
    ///
    /// The storage is not touched but no element within it is used for route searching by default.
    /// See `import` for creating routes from a pre-filled list.
    pub fn new<T>(storage: T) -> Self
        where T: Into<Slice<'a, Route>>
    {
        Routes::import(List::new(storage.into()))
    }

    /// Creates a routing tables. The backing storage is **not** cleared
    /// upon creation.
    pub fn import(storage: List<'a, Route>) -> Self {
        Routes { storage }
    }

    /// Update the routes of this node.
    pub fn update<F: FnOnce(&mut [Route])>(&mut self, f: F) {
        f(&mut self.storage);
    }

    /// Add a default ipv6 gateway (ie. "ip -6 route add ::/0 via `gateway`").
    ///
    /// On success, returns the previous default route, if any.
    pub fn add_route(&mut self, route: Route) -> Result<()> {
        match self.storage.push() {
            Some(place) => Ok(*place = route),
            None => Err(Error::Exhausted),
        }
    }

    /// Find the next hop for a destination address.
    ///
    /// The timestamp ensures that only valid entries are used. If multiple matching routes are
    /// found then the one with the shortest subnet prefix is preferred.
    pub fn lookup(&self, addr: Address, timestamp: Instant)
        -> Option<Address>
    {
        assert!(addr.is_unicast());

        // The rules say to find the subnet with longest prefix.
        let mut best_match = None;
        for route in self.storage.iter() {
            // Ignored expired routes.
            if Expiration::When(timestamp) > route.expires_at {
                continue;
            }

            // Ignored routes with mismatching net.
            if !route.net.contains(addr) {
                continue;
            }

            // Fill the best_match if none at all yet.
            let best = best_match.get_or_insert(route);
            // Prefer shortest route. Fails if just filled.
            if best.net.prefix_len() < route.net.prefix_len() {
                *best = route;
            }
        }
        best_match.map(|route| route.next_hop)
    }
}

#[cfg(test)]
mod test {
    use super::*;

    mod mock {
        use crate::wire::ip::v6::{Address as Ipv6Address, Cidr as Ipv6Cidr};

        pub(crate) const ADDR_1A: Ipv6Address = Ipv6Address(
                [0xfe, 0x80, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 1]);
        pub(crate) const ADDR_1B: Ipv6Address = Ipv6Address(
                [0xfe, 0x80, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 13]);
        pub(crate) const ADDR_1C: Ipv6Address = Ipv6Address(
                [0xfe, 0x80, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 42]);
        pub(crate) fn cidr_1() -> Ipv6Cidr {
            Ipv6Cidr::new(Ipv6Address(
                    [0xfe, 0x80, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0]), 64)
        }

        pub(crate) const ADDR_2A: Ipv6Address = Ipv6Address(
                [0xfe, 0x80, 0, 0, 0, 0, 51, 100, 0, 0, 0, 0, 0, 0, 0, 1]);
        pub(crate) const ADDR_2B: Ipv6Address = Ipv6Address(
                [0xfe, 0x80, 0, 0, 0, 0, 51, 100, 0, 0, 0, 0, 0, 0, 0, 21]);
        pub(crate) fn cidr_2() -> Ipv6Cidr {
            Ipv6Cidr::new(Ipv6Address(
                    [0xfe, 0x80, 0, 0, 0, 0, 51, 100, 0, 0, 0, 0, 0, 0, 0, 0]), 64)
        }
    }

    use self::mock::*;

    #[test]
    fn test_fill() {
        let routes_storage = vec![Route::ipv4_invalid(); 3];
        let mut routes = Routes::new(routes_storage);

        assert_eq!(routes.lookup(ADDR_1A.into(), Instant::from_millis(0)), None);
        assert_eq!(routes.lookup(ADDR_1B.into(), Instant::from_millis(0)), None);
        assert_eq!(routes.lookup(ADDR_1C.into(), Instant::from_millis(0)), None);
        assert_eq!(routes.lookup(ADDR_2A.into(), Instant::from_millis(0)), None);
        assert_eq!(routes.lookup(ADDR_2B.into(), Instant::from_millis(0)), None);

        let route = Route {
            net: cidr_1().subnet().into(),
            next_hop: ADDR_1A.into(),
            expires_at: Expiration::Never,
        };

        routes.add_route(route)
            .expect("Can add single route");

        assert_eq!(routes.lookup(ADDR_1A.into(), Instant::from_millis(0)), Some(ADDR_1A.into()));
        assert_eq!(routes.lookup(ADDR_1B.into(), Instant::from_millis(0)), Some(ADDR_1A.into()));
        assert_eq!(routes.lookup(ADDR_1C.into(), Instant::from_millis(0)), Some(ADDR_1A.into()));
        assert_eq!(routes.lookup(ADDR_2A.into(), Instant::from_millis(0)), None);
        assert_eq!(routes.lookup(ADDR_2B.into(), Instant::from_millis(0)), None);

        let route2 = Route {
            net: cidr_2().subnet().into(),
            next_hop: ADDR_2A.into(),
            expires_at: Expiration::When(Instant::from_millis(10)),
        };

        routes.add_route(route2)
            .expect("Can add second route");

        assert_eq!(routes.lookup(ADDR_1A.into(), Instant::from_millis(0)), Some(ADDR_1A.into()));
        assert_eq!(routes.lookup(ADDR_1B.into(), Instant::from_millis(0)), Some(ADDR_1A.into()));
        assert_eq!(routes.lookup(ADDR_1C.into(), Instant::from_millis(0)), Some(ADDR_1A.into()));
        assert_eq!(routes.lookup(ADDR_2A.into(), Instant::from_millis(0)), Some(ADDR_2A.into()));
        assert_eq!(routes.lookup(ADDR_2B.into(), Instant::from_millis(0)), Some(ADDR_2A.into()));

        assert_eq!(routes.lookup(ADDR_1A.into(), Instant::from_millis(10)), Some(ADDR_1A.into()));
        assert_eq!(routes.lookup(ADDR_1B.into(), Instant::from_millis(10)), Some(ADDR_1A.into()));
        assert_eq!(routes.lookup(ADDR_1C.into(), Instant::from_millis(10)), Some(ADDR_1A.into()));
        assert_eq!(routes.lookup(ADDR_2A.into(), Instant::from_millis(10)), Some(ADDR_2A.into()));
        assert_eq!(routes.lookup(ADDR_2B.into(), Instant::from_millis(10)), Some(ADDR_2A.into()));
    }
}