maxminddb/
within.rs

1//! Network iteration types.
2
3use std::cmp::Ordering;
4use std::net::{IpAddr, Ipv6Addr};
5
6use crate::decoder;
7use crate::error::MaxMindDbError;
8use crate::reader::Reader;
9use crate::result::{LookupResult, LookupSource, NetworkKind};
10
11/// Options for network iteration.
12///
13/// Controls which networks are yielded when iterating over the database
14/// with [`Reader::within()`] or [`Reader::networks()`].
15///
16/// # Example
17///
18/// ```
19/// use maxminddb::WithinOptions;
20///
21/// // Default options (skip aliases, skip networks without data, include empty values)
22/// let opts = WithinOptions::default();
23///
24/// // Include aliased networks (IPv4 networks via IPv6 aliases)
25/// let opts = WithinOptions::default().include_aliased_networks();
26///
27/// // Skip empty values and include networks without data
28/// let opts = WithinOptions::default()
29///     .skip_empty_values()
30///     .include_networks_without_data();
31/// ```
32#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
33pub struct WithinOptions {
34    /// Include IPv4 networks multiple times when accessed via IPv6 aliases.
35    include_aliased_networks: bool,
36    /// Include networks that have no associated data record.
37    include_networks_without_data: bool,
38    /// Skip networks whose data is an empty map or empty array.
39    skip_empty_values: bool,
40}
41
42impl WithinOptions {
43    /// Include IPv4 networks multiple times when accessed via IPv6 aliases.
44    ///
45    /// In IPv6 databases, IPv4 networks are stored at `::0/96`. However, the
46    /// same data is accessible through several IPv6 prefixes (e.g.,
47    /// `::ffff:0:0/96` for IPv4-mapped IPv6). By default, these aliases are
48    /// skipped to avoid yielding the same network multiple times.
49    ///
50    /// When enabled, the iterator will yield these aliased networks.
51    #[must_use]
52    pub fn include_aliased_networks(mut self) -> Self {
53        self.include_aliased_networks = true;
54        self
55    }
56
57    /// Include networks that have no associated data record.
58    ///
59    /// Some tree nodes point to "no data" (the node_count sentinel). By default
60    /// these are skipped. When enabled, these networks are yielded and
61    /// [`LookupResult::has_data()`] returns `false` for them.
62    #[must_use]
63    pub fn include_networks_without_data(mut self) -> Self {
64        self.include_networks_without_data = true;
65        self
66    }
67
68    /// Skip networks whose data is an empty map or empty array.
69    ///
70    /// Some databases store empty maps `{}` or empty arrays `[]` for records
71    /// without meaningful data. This option filters them out.
72    #[must_use]
73    pub fn skip_empty_values(mut self) -> Self {
74        self.skip_empty_values = true;
75        self
76    }
77}
78
79#[derive(Debug)]
80pub(crate) struct WithinNode {
81    pub(crate) node: usize,
82    pub(crate) ip_int: IpInt,
83    pub(crate) prefix_len: usize,
84}
85
86/// Iterator over IP networks within a CIDR range.
87///
88/// Created by [`Reader::within()`](crate::Reader::within) or
89/// [`Reader::networks()`](crate::Reader::networks). Yields
90/// [`LookupResult`] for each network in the database that falls
91/// within the specified range.
92///
93/// Networks are yielded in depth-first order through the search tree.
94/// Use [`LookupResult::decode()`](crate::LookupResult::decode) to
95/// deserialize the data for each result.
96///
97/// # Example
98///
99/// ```
100/// use maxminddb::{Reader, WithinOptions, geoip2};
101///
102/// let reader = Reader::open_readfile("test-data/test-data/GeoIP2-City-Test.mmdb").unwrap();
103/// for result in reader.within("89.160.20.0/24".parse().unwrap(), Default::default()).unwrap() {
104///     let lookup = result.unwrap();
105///     if let Some(city) = lookup.decode::<geoip2::City>().unwrap() {
106///         println!("{}: {:?}", lookup.network().unwrap(), city.city.names.english);
107///     }
108/// }
109/// ```
110#[derive(Debug)]
111pub struct Within<'de, S: AsRef<[u8]>> {
112    pub(crate) reader: &'de Reader<S>,
113    pub(crate) node_count: usize,
114    pub(crate) has_ipv4_subtree: bool,
115    pub(crate) stack: Vec<WithinNode>,
116    pub(crate) options: WithinOptions,
117}
118
119#[derive(Debug, Clone, Copy, PartialEq, Eq)]
120pub(crate) enum IpInt {
121    V4(u32),
122    V6(u128),
123}
124
125impl IpInt {
126    pub(crate) fn new(ip_addr: IpAddr) -> Self {
127        match ip_addr {
128            IpAddr::V4(v4) => IpInt::V4(v4.into()),
129            IpAddr::V6(v6) => IpInt::V6(v6.into()),
130        }
131    }
132
133    #[inline(always)]
134    pub(crate) fn get_bit(&self, index: usize) -> bool {
135        match self {
136            IpInt::V4(ip) => (ip >> (31 - index)) & 1 == 1,
137            IpInt::V6(ip) => (ip >> (127 - index)) & 1 == 1,
138        }
139    }
140
141    #[inline(always)]
142    pub(crate) fn set_bit(&mut self, index: usize) {
143        match self {
144            IpInt::V4(ip) => *ip |= 1 << (31 - index),
145            IpInt::V6(ip) => *ip |= 1 << (127 - index),
146        }
147    }
148
149    pub(crate) fn bit_count(&self) -> usize {
150        match self {
151            IpInt::V4(_) => 32,
152            IpInt::V6(_) => 128,
153        }
154    }
155
156    pub(crate) fn is_ipv4_in_ipv6(&self) -> bool {
157        match self {
158            IpInt::V4(_) => false,
159            IpInt::V6(ip) => *ip <= 0xFFFFFFFF,
160        }
161    }
162}
163
164impl<'de, S: AsRef<[u8]>> Iterator for Within<'de, S> {
165    type Item = Result<LookupResult<'de, S>, MaxMindDbError>;
166
167    fn next(&mut self) -> Option<Self::Item> {
168        while let Some(current) = self.stack.pop() {
169            let bit_count = current.ip_int.bit_count();
170
171            // Skip networks that are aliases for the IPv4 network (unless option is set)
172            if !self.options.include_aliased_networks
173                && self.reader.ipv4_start != 0
174                && current.node == self.reader.ipv4_start
175                && bit_count == 128
176                && !current.ip_int.is_ipv4_in_ipv6()
177            {
178                continue;
179            }
180
181            match current.node.cmp(&self.node_count) {
182                Ordering::Greater => {
183                    // This is a data node, emit it and we're done (until the following next call)
184                    // Resolve the pointer to a data offset
185                    let data_offset = match self.reader.resolve_data_pointer(current.node) {
186                        Ok(offset) => offset,
187                        Err(e) => return Some(Err(e)),
188                    };
189
190                    // Check if we should skip empty values
191                    if self.options.skip_empty_values {
192                        match self.is_empty_value_at(data_offset) {
193                            Ok(true) => continue, // Skip empty value
194                            Ok(false) => {}       // Not empty, proceed
195                            Err(e) => return Some(Err(e)),
196                        }
197                    }
198
199                    let network_kind = self.network_kind(&current);
200                    let ip_addr = network_ip_addr(network_kind, current.ip_int);
201
202                    return Some(Ok(LookupResult::new_found(
203                        self.reader,
204                        data_offset,
205                        current.prefix_len as u8,
206                        ip_addr,
207                        LookupSource::Iter,
208                        network_kind,
209                    )));
210                }
211                Ordering::Equal => {
212                    // Dead end (no data) - include if option is set
213                    if self.options.include_networks_without_data {
214                        let network_kind = self.network_kind(&current);
215                        let ip_addr = network_ip_addr(network_kind, current.ip_int);
216                        return Some(Ok(LookupResult::new_not_found(
217                            self.reader,
218                            current.prefix_len as u8,
219                            ip_addr,
220                            LookupSource::Iter,
221                            network_kind,
222                        )));
223                    }
224                    // Otherwise skip (current behavior)
225                }
226                Ordering::Less => {
227                    if current.prefix_len >= bit_count {
228                        return Some(Err(MaxMindDbError::invalid_database(
229                            "search tree appears to have a cycle or invalid structure (traversal exceeded the address bit length)",
230                        )));
231                    }
232                    // In order traversal of our children
233                    // right/1-bit
234                    let mut right_ip_int = current.ip_int;
235
236                    if current.prefix_len < bit_count {
237                        right_ip_int.set_bit(current.prefix_len);
238                    }
239
240                    self.push_child(current.node, 1, right_ip_int, current.prefix_len + 1);
241                    // left/0-bit
242                    self.push_child(current.node, 0, current.ip_int, current.prefix_len + 1);
243                }
244            }
245        }
246        None
247    }
248}
249
250impl<'de, S: AsRef<[u8]>> Within<'de, S> {
251    #[inline(always)]
252    fn network_kind(&self, node: &WithinNode) -> NetworkKind {
253        match node.ip_int {
254            IpInt::V4(_) if self.reader.metadata().ip_version == 6 && !self.has_ipv4_subtree => {
255                NetworkKind::V6
256            }
257            IpInt::V4(_) => NetworkKind::V4,
258            IpInt::V6(_)
259                if node.ip_int.is_ipv4_in_ipv6()
260                    && self.has_ipv4_subtree
261                    && node.prefix_len >= self.reader.ipv4_start_bit_depth =>
262            {
263                NetworkKind::V4InV6Subtree
264            }
265            IpInt::V6(_) => NetworkKind::V6,
266        }
267    }
268
269    fn push_child(
270        &mut self,
271        parent_node: usize,
272        direction: usize,
273        ip_int: IpInt,
274        prefix_len: usize,
275    ) {
276        let node = self.reader.read_node(parent_node, direction);
277        self.stack.push(WithinNode {
278            node,
279            ip_int,
280            prefix_len,
281        });
282    }
283
284    /// Check if the value at the given data offset is an empty map or array.
285    fn is_empty_value_at(&self, data_offset: usize) -> Result<bool, MaxMindDbError> {
286        let buf = &self.reader.buf.as_ref()[self.reader.pointer_base..];
287        let mut dec =
288            decoder::Decoder::new_with_limit(buf, data_offset, self.reader.data_section_len);
289        let (size, type_num) = dec.peek_type()?;
290        match type_num {
291            decoder::TYPE_MAP | decoder::TYPE_ARRAY => Ok(size == 0),
292            _ => Ok(false), // Non-container types are never "empty"
293        }
294    }
295}
296
297#[inline(always)]
298fn network_ip_addr(network_kind: NetworkKind, ip_int: IpInt) -> IpAddr {
299    let ip_addr = ip_int_to_addr(&ip_int);
300    match (network_kind, ip_int, ip_addr) {
301        // Low IPv6 tree keys are normally formatted as IPv4 addresses for IPv4
302        // subtree records. When the record is really IPv6, preserve the low
303        // IPv6 bits instead of collapsing the network to ::.
304        (NetworkKind::V6, IpInt::V6(ip), IpAddr::V4(_)) => IpAddr::V6(ip.into()),
305        // Defensive fallback for IPv4 CIDR iteration in IPv6 databases without
306        // an IPv4 subtree. Reader::within() should seed those as IpInt::V6(0).
307        (NetworkKind::V6, IpInt::V4(_), IpAddr::V4(_)) => IpAddr::V6(Ipv6Addr::UNSPECIFIED),
308        (_, _, ip_addr) => ip_addr,
309    }
310}
311
312/// Convert IpInt to IpAddr
313#[inline(always)]
314pub(crate) fn ip_int_to_addr(ip_int: &IpInt) -> IpAddr {
315    match ip_int {
316        IpInt::V4(ip) => IpAddr::V4((*ip).into()),
317        IpInt::V6(ip) => {
318            // Check if this is an IPv4-mapped IPv6 address.
319            if *ip <= 0xFFFFFFFF {
320                IpAddr::V4((*ip as u32).into())
321            } else {
322                IpAddr::V6((*ip).into())
323            }
324        }
325    }
326}
327
328#[cfg(test)]
329mod tests {
330    use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
331
332    use crate::result::NetworkKind;
333
334    use super::{network_ip_addr, IpInt};
335
336    #[test]
337    fn network_ip_addr_preserves_low_ipv6_bits() {
338        assert_eq!(
339            network_ip_addr(NetworkKind::V6, IpInt::V6(1)),
340            IpAddr::V6(Ipv6Addr::from(1_u128))
341        );
342    }
343
344    #[test]
345    fn network_ip_addr_formats_ipv4_subtree_records_as_ipv4() {
346        assert_eq!(
347            network_ip_addr(NetworkKind::V4InV6Subtree, IpInt::V6(1)),
348            IpAddr::V4(Ipv4Addr::from(1_u32))
349        );
350    }
351}
maxminddb/within.rs

maxminddb/
within.rs
