Skip to main content

zond_engine/model/parse/
target.rs

1// Copyright (c) 2026 Erik Lening (hollowpointer) and Contributors
2//
3// This file is part of Zond Engine, licensed under the GNU Affero General
4// Public License, version 3 or later. See the LICENSE file for details, or
5// <https://www.gnu.org/licenses/agpl-3.0.html>.
6//
7// SPDX-License-Identifier: AGPL-3.0-or-later
8
9//! # Target Expressions
10//!
11//! What a scan target looks like written down, and how a stream of them becomes
12//! a [`TargetMap`].
13//!
14//! Every way of getting targets into the engine (a file, a form field, an argument
15//! list, a previous report) ends here, so the formats only decide where the tokens come
16//! from.
17//!
18//! ## The grammar
19//!
20//! A target expression is an address expression with an optional port
21//! specification after it:
22//!
23//! | Written | Address | Ports |
24//! |---|---|---|
25//! | `192.0.2.1` | `192.0.2.1` | the caller's default |
26//! | `192.0.2.1:80,443` | `192.0.2.1` | `80,443` |
27//! | `198.51.100.0/24:1-1024` | `198.51.100.0/24` | `1-1024` |
28//! | `2001:db8::1` | `2001:db8::1` | the caller's default |
29//! | `[2001:db8::1]:443` | `2001:db8::1` | `443` |
30//! | `fe80::1%en0` | `fe80::1%en0` | the caller's default |
31//! | `[fe80::1%en0]:22` | `fe80::1%en0` | `22` |
32//! | `scanme.example:22` | `scanme.example` | `22` |
33//! | `192.0.2.1:u:53` | `192.0.2.1` | `u:53` (UDP) |
34//!
35//! The address half goes to [`crate::model::parse::ip`]; this module only decides where
36//! the address ends and the ports begin.
37//!
38//! ## Where the ports begin
39//!
40//! `:` separates ports from addresses, appears inside IPv6 addresses, and appears in
41//! this engine's `u:53` spelling for a UDP port. Three rules settle it:
42//!
43//! 1. A token starting with `[` is an address up to the matching `]`,
44//!    optionally followed by `:` and a port specification.
45//! 2. **A dot before the first colon means the first colon separates.** No IPv6
46//!    address can have one: every dotted IPv6 form puts its dots in the last 32
47//!    bits, after at least one colon. So `192.0.2.1:u:53` and
48//!    `db.internal:u:53` are an address and its ports, however many colons
49//!    follow.
50//! 3. Otherwise, one colon separates and two or more are an IPv6 address.
51//!
52//! Rule 2 lets a UDP port be written without brackets on an IPv4 target or a dotted
53//! name.
54//!
55//! **`2001:db8::1:80` is an address, not port 80 on `2001:db8::1`**: it is a valid IPv6
56//! address. Write `[2001:db8::1]:80` for the port. A target with colons that is neither
57//! is refused with an error saying so; it is never tried as a hostname, since a
58//! hostname cannot contain a colon.
59//!
60//! ## Hostnames
61//!
62//! Whether a name may be looked up is [`crate::config::ZondConfig::no_dns`]'s business,
63//! and how is up to whoever built the resolver. So a name goes to a lookup supplied in
64//! [`TargetContext`], like keywords and interface zones. Without one, the hostname is
65//! refused with an error naming it.
66//!
67//! The lookup is called during parsing, synchronously. With many names, parse in two
68//! passes: collect them with [`TargetExpr::parse`], resolve them concurrently, then
69//! build with a lookup that reads the results.
70//!
71//! ## One unit per port specification
72//!
73//! [`TargetMapBuilder`] groups by port specification, so a file of 65,536 bare
74//! addresses becomes one unit. Order is first-seen, so two runs over the same input
75//! produce the same scan.
76//!
77//! The saving is in the number of units: each [`TargetSet`] canonicalizes itself and
78//! allocates its own port vector when iterated. On a 65,536-line file this is roughly
79//! 1.5x faster end to end, whether or not anything merged.
80//!
81//! ## When grouping stops paying
82//!
83//! Grouping costs an index lookup per line and pays only while lines share
84//! specifications. Reading a report back produces a distinct specification per host,
85//! and over 65,536 such units a builder keeping its index took 22.0 ms against the
86//! direct path's 12.7 ms.
87//!
88//! So the builder gives the index up when it earns nothing (see `MIN_REGROUPED_SHARE`),
89//! after which every expression becomes its own unit. That shape then costs 13.4 ms
90//! (1.05x the direct path, median of nine paired runs). Shapes that group keep the
91//! index.
92//!
93//! Once the index is gone, an address named twice on the same ports is asked twice,
94//! which is what a [`TargetMap`] means by counting gross. That only happens after a
95//! thousand expressions repeating a specification less than one time in sixteen.
96
97use std::collections::HashMap;
98use std::fmt;
99use std::net::IpAddr;
100
101use thiserror::Error;
102
103use crate::model::ip::set::IpSet;
104use crate::model::parse::ip::{IpParseError, ResolverFn, ZoneResolverFn, insert_expression};
105use crate::model::port::{PortSet, PortSetParseError};
106use crate::model::target::{TargetMap, TargetSet};
107
108/// Looks up the addresses a hostname stands for.
109///
110/// `None` and an empty vector both mean nothing to scan under that name, reported as
111/// [`TargetParseError::UnknownHost`]. A resolver that distinguishes a lookup failure
112/// from a name with no records reports that through its own channel.
113///
114/// `Sync`, for the reason [`ResolverFn`] is.
115pub type HostLookup<'a> = &'a (dyn Fn(&str) -> Option<Vec<IpAddr>> + Sync);
116
117/// The lookups a target expression may need, which read the host this process runs on.
118///
119/// Each is optional, and an expression needing one the caller did not supply is
120/// refused.
121///
122/// Build one with [`new`](Self::new) and the `with_*` methods, or with [`Default`], and
123/// assign fields directly where that reads better.
124#[must_use]
125#[non_exhaustive]
126#[derive(Default, Clone, Copy)]
127pub struct TargetContext<'a> {
128    /// Expands keywords such as `lan` into the addresses they stand for.
129    pub keywords: Option<ResolverFn<'a>>,
130    /// Resolves the `%interface` suffix on a link-local address to a scope id.
131    pub zones: Option<ZoneResolverFn<'a>>,
132    /// Resolves a hostname to addresses.
133    pub hosts: Option<HostLookup<'a>>,
134}
135
136impl<'a> TargetContext<'a> {
137    /// A context that can resolve nothing: literal addresses, ranges and CIDR
138    /// blocks only.
139    pub fn new() -> Self {
140        Self::default()
141    }
142
143    /// Sets the keyword resolver.
144    pub fn with_keywords(mut self, keywords: ResolverFn<'a>) -> Self {
145        self.keywords = Some(keywords);
146        self
147    }
148
149    /// Sets the interface-zone resolver.
150    pub fn with_zones(mut self, zones: ZoneResolverFn<'a>) -> Self {
151        self.zones = Some(zones);
152        self
153    }
154
155    /// Sets the hostname lookup.
156    pub fn with_hosts(mut self, hosts: HostLookup<'a>) -> Self {
157        self.hosts = Some(hosts);
158        self
159    }
160}
161
162impl fmt::Debug for TargetContext<'_> {
163    /// Reports which lookups are present, which is what debugging a refused target
164    /// needs.
165    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
166        f.debug_struct("TargetContext")
167            .field("keywords", &self.keywords.is_some())
168            .field("zones", &self.zones.is_some())
169            .field("hosts", &self.hosts.is_some())
170            .finish()
171    }
172}
173
174/// Why a target expression could not be turned into targets.
175///
176/// Every variant carries the expression it is about; an importer adds the line.
177#[non_exhaustive]
178#[derive(Debug, Clone, PartialEq, Eq, Error)]
179pub enum TargetParseError {
180    /// The token was empty.
181    #[error("a target expression cannot be empty")]
182    Empty,
183
184    /// The token held nothing but whitespace.
185    ///
186    /// Its own variant because a token of spaces looks like the gap between two
187    /// arguments, usually from a stray `\` in the shell.
188    #[error("a target of {0} space{1}; a stray '\\' in the shell?")]
189    Blank(usize, &'static str),
190
191    /// A bracketed address was never closed.
192    #[error("'{0}': a bracketed address must be closed with ']'")]
193    UnbalancedBracket(String),
194
195    /// Something followed the closing bracket other than a port specification.
196    #[error("'{0}': expected ':' and a port specification after ']'")]
197    TrailingText(String),
198
199    /// The separator was there and the port specification was not.
200    #[error("'{0}': the ':' is not followed by a port specification")]
201    EmptyPorts(String),
202
203    /// The address half named nothing scannable.
204    #[error("'{expression}': {source}")]
205    Address {
206        /// The whole expression, as written.
207        expression: String,
208        /// What the address grammar made of it.
209        #[source]
210        source: IpParseError,
211    },
212
213    /// The port half was not a port specification.
214    #[error("'{expression}': {source}")]
215    Ports {
216        /// The whole expression, as written.
217        expression: String,
218        /// What the port grammar made of it.
219        #[source]
220        source: PortSetParseError,
221    },
222
223    /// The address half is a hostname and the caller supplied no lookup.
224    #[error("'{0}': this is a hostname, and no host lookup was supplied to resolve it")]
225    NoHostLookup(String),
226
227    /// Not an address or a range, and shaped like no host name either.
228    ///
229    /// A typo: `192.0.2.300`, `10.10.10.*` and `10.10.10.0/` are addresses or ranges
230    /// written wrong. Never sent to a lookup, which would leak the range to a resolver.
231    #[error("'{0}': not a valid address, range or hostname")]
232    MistypedAddress(String),
233
234    /// Something with colons in it that is neither an address nor bracketed.
235    ///
236    /// A hostname cannot contain a colon. Almost always an IPv6 target that needs
237    /// brackets to carry its ports.
238    #[error(
239        "'{0}': not an address, and a hostname cannot contain ':'. \
240         An IPv6 target carrying ports must be bracketed, as in `[2001:db8::1]:443`"
241    )]
242    UnbracketedAddress(String),
243
244    /// The lookup returned nothing for the name.
245    #[error("'{0}': no address could be resolved for this name")]
246    UnknownHost(String),
247
248    /// The expression parsed and named nothing to scan.
249    ///
250    /// Reached through a keyword: a [`ResolverFn`] that returns without inserting an
251    /// address, as for `lan` on a host with no LAN. Distinct from
252    /// [`Empty`](Self::Empty) (a token with no expression) and
253    /// [`UnknownHost`](Self::UnknownHost) (a name nothing answered to). The engine's
254    /// own resolver always inserts on success, so only a caller-supplied resolver
255    /// reaches this.
256    #[error("'{0}': this named no addresses to scan")]
257    ResolvedToNothing(String),
258}
259
260/// Which of the two empties a token is: nothing at all, or whitespace.
261fn blank_or_empty(token: &str) -> TargetParseError {
262    let spaces = token.chars().count();
263    match spaces {
264        0 => TargetParseError::Empty,
265        1 => TargetParseError::Blank(1, ""),
266        _ => TargetParseError::Blank(spaces, "s"),
267    }
268}
269
270/// A target expression split into the part that says *what* and the part that
271/// says *where on it*.
272///
273/// Borrows from the token it was parsed out of, so splitting a large file costs
274/// no allocation.
275#[non_exhaustive]
276#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
277pub struct TargetExpr<'a> {
278    /// The address expression: a literal, a range, a CIDR block, a keyword or a
279    /// hostname, carrying its `%zone` suffix if it had one. Brackets, if there
280    /// were any, are stripped.
281    pub address: &'a str,
282    /// The port specification as written, if the expression carried one.
283    pub ports: Option<&'a str>,
284}
285
286impl<'a> TargetExpr<'a> {
287    /// Splits one token.
288    ///
289    /// Surrounding whitespace is trimmed. The halves are *not* validated here; the
290    /// grammars that own them check them when the expression is built into targets.
291    ///
292    /// # Examples
293    ///
294    /// ```
295    /// use zond_engine::model::parse::target::TargetExpr;
296    ///
297    /// let bare = TargetExpr::parse("192.0.2.1").unwrap();
298    /// assert_eq!(bare.address, "192.0.2.1");
299    /// assert_eq!(bare.ports, None);
300    ///
301    /// let with_ports = TargetExpr::parse("[2001:db8::1]:443").unwrap();
302    /// assert_eq!(with_ports.address, "2001:db8::1");
303    /// assert_eq!(with_ports.ports, Some("443"));
304    ///
305    /// // A bare IPv6 address is an address, never an address and a port.
306    /// let ambiguous = TargetExpr::parse("2001:db8::1:80").unwrap();
307    /// assert_eq!(ambiguous.address, "2001:db8::1:80");
308    /// assert_eq!(ambiguous.ports, None);
309    /// ```
310    pub fn parse(token: &'a str) -> Result<Self, TargetParseError> {
311        let trimmed = token.trim();
312        if trimmed.is_empty() {
313            return Err(blank_or_empty(token));
314        }
315        let token = trimmed;
316
317        if let Some(rest) = token.strip_prefix('[') {
318            let close = rest
319                .find(']')
320                .ok_or_else(|| TargetParseError::UnbalancedBracket(token.to_string()))?;
321            let address = &rest[..close];
322            let tail = &rest[close + 1..];
323
324            if address.is_empty() {
325                return Err(TargetParseError::Empty);
326            }
327
328            return match tail.strip_prefix(':') {
329                None if tail.is_empty() => Ok(Self {
330                    address,
331                    ports: None,
332                }),
333                None => Err(TargetParseError::TrailingText(token.to_string())),
334                Some("") => Err(TargetParseError::EmptyPorts(token.to_string())),
335                Some(ports) => Ok(Self {
336                    address,
337                    ports: Some(ports),
338                }),
339            };
340        }
341
342        let colons = token.matches(':').count();
343
344        // Every dotted IPv6 form (`::ffff:192.0.2.1` and relatives) puts the dots
345        // after at least one colon, so a dot first means IPv4 or a dotted
346        // hostname, and every later colon belongs to the ports, as in
347        // `192.0.2.1:u:53`.
348        let dotted_first = match (token.find('.'), token.find(':')) {
349            (Some(dot), Some(colon)) => dot < colon,
350            _ => false,
351        };
352
353        if colons >= 1 && (dotted_first || colons == 1) {
354            let (address, ports) = token.split_once(':').expect("a colon was found");
355            if address.is_empty() {
356                return Err(TargetParseError::Empty);
357            }
358            if ports.is_empty() {
359                return Err(TargetParseError::EmptyPorts(token.to_string()));
360            }
361            return Ok(Self {
362                address,
363                ports: Some(ports),
364            });
365        }
366
367        // No colon, or two or more with no dot in front: a whole address, no
368        // ports.
369        Ok(Self {
370            address: token,
371            ports: None,
372        })
373    }
374
375    /// The addresses the expression names, splitting the address half on commas.
376    ///
377    /// A comma separates addresses in the address half and is part of the
378    /// specification in the port half: `192.0.2.1:80,443` is one host on two ports,
379    /// `192.0.2.1,192.0.2.2:80` two hosts on one.
380    ///
381    /// Empty fields are skipped, so a trailing comma is not an error.
382    pub fn addresses(&self) -> impl Iterator<Item = &'a str> {
383        self.address
384            .split(',')
385            .map(str::trim)
386            .filter(|part| !part.is_empty())
387    }
388}
389
390/// How many expressions [`TargetMapBuilder`] watches before it will judge the
391/// shape of its input.
392///
393/// A thousand entries is a few tens of kilobytes and a tenth of a millisecond, so
394/// waiting costs nothing, and the judgement is made once and never revised.
395const GROUPING_SAMPLE: usize = 1_024;
396
397/// How little regrouping [`TargetMapBuilder`] will put up with before it stops
398/// paying for an index: fewer than one expression in this many joining a group
399/// that already existed.
400///
401/// Measured, grouping and the direct path cross between four and eight lines per port
402/// specification, and a distinct specification on every line took 22.0 ms against
403/// 12.7 ms.
404///
405/// Sixteen, well below the crossing, because the reading comes from a prefix and cannot
406/// be taken back. A file drawing from a pool of fewer than about eight thousand
407/// specifications repeats often enough within its first thousand lines to keep its
408/// index; larger pools would not pay anyway. A file that repeats only much later gives
409/// the index up and ends no worse off than the direct path.
410const MIN_REGROUPED_SHARE: usize = 16;
411
412/// Accumulates target expressions into a [`TargetMap`], one unit per distinct
413/// port specification for as long as that is worth doing.
414///
415/// Built incrementally, so an importer can stream a file of any size and decide what
416/// to do with a refused expression.
417///
418/// Grouping is abandoned on input that does not group; see `MIN_REGROUPED_SHARE` and
419/// the module documentation.
420#[derive(Debug, Clone)]
421pub struct TargetMapBuilder {
422    /// The ports an expression that names none is scanned on.
423    default_ports: PortSet,
424    /// The groups, in the order their port specification was first seen.
425    groups: Vec<(PortSet, IpSet)>,
426    /// Where each port specification's group sits in `groups`, while grouping
427    /// is still earning its keep.
428    ///
429    /// A map, since the number of distinct specifications is unbounded and untrusted
430    /// input must not make this quadratic.
431    ///
432    /// `None` once `MIN_REGROUPED_SHARE` says grouping buys nothing, which also frees
433    /// its memory.
434    index: Option<HashMap<PortSet, usize>>,
435    /// How many expressions have been accepted, which the rule above reads
436    /// against the group count.
437    accepted: usize,
438    /// Addresses accumulated so far, before overlapping expressions are merged.
439    ///
440    /// A running total, since it is read once per expression. See
441    /// [`gross_address_count`](Self::gross_address_count).
442    gross_addresses: u128,
443}
444
445impl TargetMapBuilder {
446    /// Starts a builder whose expressions take `default_ports` when they name
447    /// no ports of their own.
448    pub fn new(default_ports: PortSet) -> Self {
449        Self {
450            default_ports,
451            groups: Vec::new(),
452            index: Some(HashMap::new()),
453            accepted: 0,
454            gross_addresses: 0,
455        }
456    }
457
458    /// Parses one target expression and adds what it names.
459    ///
460    /// Nothing is added when the expression is refused.
461    pub fn push(&mut self, token: &str, ctx: &TargetContext<'_>) -> Result<(), TargetParseError> {
462        let expr = TargetExpr::parse(token)?;
463
464        let ports = match expr.ports {
465            Some(spec) => PortSet::parse_scan(spec).map_err(|source| TargetParseError::Ports {
466                expression: token.trim().to_string(),
467                source,
468            })?,
469            None => self.default_ports.clone(),
470        };
471
472        // Resolved into its own set first, so a refusal leaves the builder
473        // untouched.
474        let mut resolved = IpSet::new();
475        for address in expr.addresses() {
476            match insert_expression(address, &mut resolved, ctx.keywords, ctx.zones) {
477                Ok(()) => {}
478                // "Not an address", so possibly a name.
479                Err(IpParseError::Malformed(_)) => {
480                    self.resolve_host(address, &mut resolved, ctx)?;
481                }
482                Err(source) => {
483                    return Err(TargetParseError::Address {
484                        expression: token.trim().to_string(),
485                        source,
486                    });
487                }
488            }
489        }
490
491        if resolved.is_empty() {
492            return Err(TargetParseError::ResolvedToNothing(
493                token.trim().to_string(),
494            ));
495        }
496
497        // Counted from this expression's own ranges; see `gross_address_count`.
498        self.gross_addresses = self.gross_addresses.saturating_add(resolved.len_gross());
499        self.accepted += 1;
500
501        let existing = self
502            .index
503            .as_ref()
504            .and_then(|index| index.get(&ports).copied());
505
506        match existing {
507            Some(slot) => {
508                let target = &mut self.groups[slot].1;
509                for range in resolved.v4() {
510                    target.push_v4_range(*range);
511                }
512                for range in resolved.v6() {
513                    target.push_v6_range(*range);
514                }
515            }
516            None => {
517                let slot = self.groups.len();
518                if let Some(index) = self.index.as_mut() {
519                    index.insert(ports.clone(), slot);
520                }
521                self.groups.push((ports, resolved));
522            }
523        }
524
525        self.reconsider_grouping();
526
527        Ok(())
528    }
529
530    /// Drops the index once the groups have stopped earning it.
531    ///
532    /// Irreversible: once the index is gone, existing groups stay and every later
533    /// expression becomes its own unit.
534    fn reconsider_grouping(&mut self) {
535        if self.index.is_none() || self.accepted < GROUPING_SAMPLE {
536            return;
537        }
538
539        let regrouped = self.accepted - self.groups.len();
540        if regrouped * MIN_REGROUPED_SHARE < self.accepted {
541            self.index = None;
542        }
543    }
544
545    /// Looks a hostname up through the caller's lookup and records what it
546    /// stands for.
547    fn resolve_host(
548        &self,
549        name: &str,
550        into: &mut IpSet,
551        ctx: &TargetContext<'_>,
552    ) -> Result<(), TargetParseError> {
553        match host_name(name) {
554            HostName::Yes => {}
555            HostName::Unbracketed => {
556                return Err(TargetParseError::UnbracketedAddress(name.to_string()));
557            }
558            HostName::Mistyped => {
559                return Err(TargetParseError::MistypedAddress(name.to_string()));
560            }
561        }
562
563        let lookup = ctx
564            .hosts
565            .ok_or_else(|| TargetParseError::NoHostLookup(name.to_string()))?;
566
567        let addresses = lookup(name).unwrap_or_default();
568        if addresses.is_empty() {
569            return Err(TargetParseError::UnknownHost(name.to_string()));
570        }
571
572        for address in addresses {
573            into.insert(address);
574        }
575
576        Ok(())
577    }
578
579    /// How many groups have accumulated.
580    ///
581    /// The number of units [`build`](Self::build) will produce: on input that groups,
582    /// the number of distinct port specifications; otherwise, roughly the number of
583    /// expressions accepted. See the module documentation.
584    pub fn group_count(&self) -> usize {
585        self.groups.len()
586    }
587
588    /// How many addresses have accumulated across every group, counting an
589    /// address once per group it appears in.
590    ///
591    /// Merges ranges to answer, so a block counts what it holds. A caller checks a
592    /// scan-size budget against this: `::/0` costs nothing to hold and 2^128 addresses
593    /// to scan.
594    pub fn address_count(&mut self) -> u128 {
595        self.groups
596            .iter_mut()
597            .map(|(_, ips)| {
598                ips.canonicalize();
599                ips.len()
600            })
601            .fold(0u128, |total, count| total.saturating_add(count))
602    }
603
604    /// How many addresses have accumulated, counted before overlapping
605    /// expressions are merged.
606    ///
607    /// The constant-time counterpart to [`address_count`](Self::address_count), for a
608    /// budget checked once per expression. Walking the accumulated ranges instead made
609    /// a 65,536-line import take 3.2 s against 6.9 ms, growing with the square of the
610    /// line count.
611    ///
612    /// Never lower than the true count, so a budget check errs early.
613    pub fn gross_address_count(&self) -> u128 {
614        self.gross_addresses
615    }
616
617    /// Whether anything scannable has accumulated.
618    ///
619    /// Whether any group exists: [`push`](Self::push) refuses an expression naming no
620    /// addresses, so every group holds at least one.
621    pub fn is_empty(&self) -> bool {
622        self.groups.is_empty()
623    }
624
625    /// Finishes the map.
626    ///
627    /// Every group becomes a unit; none is empty (see [`is_empty`](Self::is_empty)).
628    pub fn build(self) -> TargetMap {
629        let mut map = TargetMap::new();
630        for (ports, ips) in self.groups {
631            map.add_unit(TargetSet::new(ips, ports));
632        }
633        map
634    }
635}
636
637/// Whether a token the address grammar refused is worth looking up as a host
638/// name, and if not, what it is instead.
639///
640/// [`IpParseError::Malformed`] says only "not an address", and many such tokens are not
641/// names either; telling the author what they wrote beats a lookup bound to fail.
642///
643/// ## Only something shaped like a name is a name
644///
645/// A token goes to a lookup only when it could be a host name: letters, digits, `-`,
646/// `_` and dots, with a last label holding at least one letter, and not three or more
647/// numbers ahead of that label. Everything else is a mistyped address or range.
648///
649/// The rule describes names because typos are open-ended: `10.10.10.*`,
650/// `10.10.1-5.1-254`, `10.10.10.0/` and `/0` fail in four different ways. The system
651/// resolver accepts `*` and `-` in a label and asks upstream, which would tell someone
652/// else's resolver what range is being scanned.
653///
654/// RFC 1123 §2.1 makes a host name's last label alphabetic, which keeps a name from
655/// reading as a dotted address. A letter anywhere in it counts, so `nas-1` resolves.
656/// `_` is allowed because such hosts exist on real networks; `*`, `/`, `%` and the like
657/// are not. Letters and digits include non-ASCII, so a name in its own script reaches a
658/// lookup that may encode it.
659///
660/// The second condition catches a stray letter: `10.10.10.1a`, `10.10.10.a` and
661/// `10.10.10.1-2.example` are IPv4 addresses or ranges with a slip. Names that embed an
662/// address put a non-numeric label between it and the last label
663/// (`192.0.2.1.sslip.example`, reverse names under `in-addr.arpa`), and a leading label
664/// with a letter, as in `3com.example`, is a name too.
665///
666/// ## Both passes ask this
667///
668/// The synchronous build asks before consulting the lookup, and `resolve::targets`'s
669/// collection pass asks before putting a name on the network, so the two cannot
670/// disagree.
671pub(crate) fn host_name(token: &str) -> HostName {
672    // A colon rules out a name. A port specification after the last colon is
673    // almost certainly an unbracketed IPv6 target; anything else is a wrong IPv6
674    // address, where advice about brackets would mislead.
675    if let Some((_, tail)) = token.rsplit_once(':') {
676        return if PortSet::try_from(tail).is_ok() {
677            HostName::Unbracketed
678        } else {
679            HostName::Mistyped
680        };
681    }
682
683    let name_character = |c: char| c.is_alphanumeric() || matches!(c, '-' | '_' | '.');
684    // A fully qualified name's trailing dot leaves an empty last label.
685    let last_label = token
686        .strip_suffix('.')
687        .unwrap_or(token)
688        .rsplit('.')
689        .next()
690        .unwrap_or_default();
691
692    // An octet or an octet range.
693    let numeric = |label: &str| {
694        label
695            .split('-')
696            .all(|part| !part.is_empty() && part.bytes().all(|byte| byte.is_ascii_digit()))
697    };
698    let leading: Vec<&str> = token
699        .strip_suffix('.')
700        .unwrap_or(token)
701        .rsplit('.')
702        .skip(1)
703        .collect();
704    let address_shaped = leading.len() >= 3 && leading.iter().all(|label| numeric(label));
705
706    if token.chars().all(name_character)
707        && last_label.chars().any(char::is_alphabetic)
708        && !address_shaped
709    {
710        HostName::Yes
711    } else {
712        HostName::Mistyped
713    }
714}
715
716/// What [`host_name`] concluded about a token the address grammar refused.
717#[derive(Debug, Clone, Copy, PartialEq, Eq)]
718pub(crate) enum HostName {
719    /// Worth resolving.
720    Yes,
721    /// An IPv6 address and ports, written without brackets.
722    Unbracketed,
723    /// Shaped like no name: an address or a range with a mistake in it.
724    Mistyped,
725}
726
727/// Parses a slice of target expressions into a [`TargetMap`].
728///
729/// For a caller with every target in memory that wants the first error; drive
730/// [`TargetMapBuilder`] directly for more control.
731pub fn to_target_map<S>(
732    targets: &[S],
733    default_ports: PortSet,
734    ctx: &TargetContext<'_>,
735) -> Result<TargetMap, TargetParseError>
736where
737    S: AsRef<str>,
738{
739    let mut builder = TargetMapBuilder::new(default_ports);
740    for target in targets {
741        builder.push(target.as_ref(), ctx)?;
742    }
743    Ok(builder.build())
744}
745
746// ╔════════════════════════════════════════════╗
747// ║ ████████╗███████╗███████╗████████╗███████╗ ║
748// ║ ╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝██╔════╝ ║
749// ║    ██║   █████╗  ███████╗   ██║   ███████╗ ║
750// ║    ██║   ██╔══╝  ╚════██║   ██║   ╚════██║ ║
751// ║    ██║   ███████╗███████║   ██║   ███████║ ║
752// ║    ╚═╝   ╚══════╝╚══════╝   ╚═╝   ╚══════╝ ║
753// ╚════════════════════════════════════════════╝
754
755#[cfg(test)]
756mod tests {
757    use super::*;
758
759    /// A context is `Send`, so a caller can resolve targets inside a spawned task.
760    #[test]
761    fn a_context_can_be_held_across_a_spawn() {
762        fn sent<T: Send + Sync>() {}
763
764        sent::<TargetContext<'static>>();
765    }
766    use crate::model::parse::ip::Keyword;
767    use crate::model::target::Target;
768    use std::net::Ipv4Addr;
769
770    fn ports(spec: &str) -> PortSet {
771        PortSet::try_from(spec).expect("test port specification parses")
772    }
773
774    /// Splitting at the first colon would read `fe80::1` as host `fe80` on port `:1`.
775    #[test]
776    fn an_ipv6_address_is_never_split_at_its_own_colons() {
777        for token in [
778            "fe80::1",
779            "2001:db8::1",
780            "2001:db8::1:80",
781            "fe80::1%en0",
782            "2001:db8::1-2001:db8::5",
783            "::1",
784        ] {
785            let expr = TargetExpr::parse(token).expect("parses");
786            assert_eq!(expr.address, token, "{token} lost part of its address");
787            assert_eq!(expr.ports, None, "{token} acquired ports it does not name");
788        }
789    }
790
791    /// Brackets work for every IPv6 address form.
792    #[test]
793    fn brackets_separate_an_ipv6_address_from_its_ports() {
794        let cases = [
795            ("[2001:db8::1]:443", "2001:db8::1", Some("443")),
796            ("[fe80::1%en0]:22", "fe80::1%en0", Some("22")),
797            ("[2001:db8::1]", "2001:db8::1", None),
798            (
799                "[2001:db8::]:80,443,u:53",
800                "2001:db8::",
801                Some("80,443,u:53"),
802            ),
803        ];
804
805        for (token, address, port_spec) in cases {
806            let expr = TargetExpr::parse(token).expect("parses");
807            assert_eq!(expr.address, address);
808            assert_eq!(expr.ports, port_spec);
809        }
810    }
811
812    #[test]
813    fn a_single_colon_separates_ports() {
814        let cases = [
815            ("192.0.2.1:80", "192.0.2.1", Some("80")),
816            ("198.51.100.0/24:1-1024", "198.51.100.0/24", Some("1-1024")),
817            ("198.51.100.1-50:80,443", "198.51.100.1-50", Some("80,443")),
818            ("scanme.example:22", "scanme.example", Some("22")),
819            ("  192.0.2.1:80  ", "192.0.2.1", Some("80")),
820        ];
821
822        for (token, address, port_spec) in cases {
823            let expr = TargetExpr::parse(token).expect("parses");
824            assert_eq!(expr.address, address);
825            assert_eq!(expr.ports, port_spec);
826        }
827    }
828
829    /// A dot before the first colon lets `u:` ports follow an IPv4 address or dotted
830    /// name without brackets.
831    #[test]
832    fn a_udp_port_needs_no_brackets_on_an_address_that_has_a_dot() {
833        let cases = [
834            ("192.0.2.1:u:53", "192.0.2.1", Some("u:53")),
835            ("192.0.2.1:u:53,u:161", "192.0.2.1", Some("u:53,u:161")),
836            (
837                "198.51.100.0/24:80,u:53",
838                "198.51.100.0/24",
839                Some("80,u:53"),
840            ),
841            ("db.internal:u:53", "db.internal", Some("u:53")),
842        ];
843
844        for (token, address, port_spec) in cases {
845            let expr = TargetExpr::parse(token).expect("parses");
846            assert_eq!(expr.address, address, "{token}");
847            assert_eq!(expr.ports, port_spec, "{token}");
848        }
849
850        // An IPv6 address is still whole.
851        for token in ["2001:db8::1", "::ffff:192.0.2.1", "2001:db8::192.0.2.1"] {
852            let expr = TargetExpr::parse(token).expect("parses");
853            assert_eq!(expr.address, token, "{token} was split");
854            assert_eq!(expr.ports, None, "{token} acquired ports");
855        }
856    }
857
858    /// A token with colons that is not an address is not reported as an unresolvable
859    /// host.
860    #[test]
861    fn an_unbracketed_ipv6_target_with_ports_says_what_to_do_about_it() {
862        let mut builder = TargetMapBuilder::new(ports("80"));
863
864        // Two colons, no dot in front: read as an address, and it is not one.
865        let err = builder
866            .push("2001:db8::zz:443", &TargetContext::new())
867            .expect_err("not an address");
868
869        assert!(
870            matches!(err, TargetParseError::UnbracketedAddress(_)),
871            "got {err:?}"
872        );
873        assert!(
874            err.to_string().contains("[2001:db8::1]:443"),
875            "the error has to show the way out: {err}"
876        );
877    }
878
879    /// A malformed expression is refused: `192.0.2.1:` must not scan the default ports.
880    #[test]
881    fn a_separator_without_a_port_specification_is_refused() {
882        assert!(matches!(
883            TargetExpr::parse("192.0.2.1:"),
884            Err(TargetParseError::EmptyPorts(_))
885        ));
886        assert!(matches!(
887            TargetExpr::parse("[2001:db8::1]:"),
888            Err(TargetParseError::EmptyPorts(_))
889        ));
890        assert!(matches!(
891            TargetExpr::parse("[2001:db8::1"),
892            Err(TargetParseError::UnbalancedBracket(_))
893        ));
894        assert!(matches!(
895            TargetExpr::parse("[2001:db8::1]443"),
896            Err(TargetParseError::TrailingText(_))
897        ));
898        assert!(matches!(
899            TargetExpr::parse(":80"),
900            Err(TargetParseError::Empty)
901        ));
902        // A token of spaces gets its own message.
903        let blank = TargetExpr::parse("   ").expect_err("whitespace is not a target");
904        assert!(
905            matches!(blank, TargetParseError::Blank(3, "s")),
906            "{blank:?}"
907        );
908        assert_eq!(
909            blank.to_string(),
910            "a target of 3 spaces; a stray '\\' in the shell?"
911        );
912
913        let one = TargetExpr::parse(" ").expect_err("a space is not a target");
914        assert_eq!(
915            one.to_string(),
916            "a target of 1 space; a stray '\\' in the shell?"
917        );
918
919        assert!(matches!(
920            TargetExpr::parse(""),
921            Err(TargetParseError::Empty)
922        ));
923    }
924
925    /// A port half naming no ports, such as `192.0.2.1:,`, is refused.
926    #[test]
927    fn a_port_specification_naming_nothing_is_refused() {
928        let mut builder = TargetMapBuilder::new(ports("80"));
929        let ctx = TargetContext::new();
930
931        let error = builder
932            .push("192.0.2.1:,", &ctx)
933            .expect_err("a port half naming nothing");
934        assert!(error.to_string().contains("names no ports"), "{error}");
935        assert!(builder.is_empty(), "and nothing was added");
936    }
937
938    /// One unit per port specification, not per input token.
939    #[test]
940    fn targets_are_grouped_by_port_specification_not_by_token() {
941        let mut builder = TargetMapBuilder::new(ports("80"));
942        let ctx = TargetContext::new();
943
944        for octet in 0..=255u8 {
945            let target = format!("192.0.2.{octet}");
946            builder.push(&target, &ctx).expect("parses");
947        }
948
949        assert_eq!(builder.group_count(), 1, "one port specification, one unit");
950        assert_eq!(builder.address_count(), 256);
951
952        let map = builder.build();
953        assert_eq!(map.units.len(), 1);
954        // 256 contiguous addresses on one port, merged into a single range.
955        assert_eq!(map.gross_targets().unwrap(), 256);
956    }
957
958    #[test]
959    fn distinct_port_specifications_get_distinct_units_in_first_seen_order() {
960        let mut builder = TargetMapBuilder::new(ports("80"));
961        let ctx = TargetContext::new();
962
963        builder.push("198.51.100.1:22", &ctx).unwrap();
964        builder.push("198.51.100.2:443", &ctx).unwrap();
965        builder.push("198.51.100.3:22", &ctx).unwrap();
966        builder.push("198.51.100.4", &ctx).unwrap();
967
968        assert_eq!(builder.group_count(), 3, "22, 443, and the default 80");
969
970        let map = builder.build();
971        assert_eq!(map.units[0].ports(), &ports("22"));
972        assert_eq!(map.units[0].ips().len(), 2, "198.51.100.1 and 198.51.100.3");
973        assert_eq!(map.units[1].ports(), &ports("443"));
974        assert_eq!(map.units[2].ports(), &ports("80"));
975    }
976
977    /// Two spellings of one port set are one group.
978    #[test]
979    fn port_specifications_group_by_what_they_mean_not_how_they_are_written() {
980        let mut builder = TargetMapBuilder::new(ports("80"));
981        let ctx = TargetContext::new();
982
983        builder.push("198.51.100.1:80,443", &ctx).unwrap();
984        builder.push("198.51.100.2:443,80", &ctx).unwrap();
985        builder.push("198.51.100.3:80-81,443", &ctx).unwrap();
986
987        assert_eq!(
988            builder.group_count(),
989            2,
990            "80 with 443 once, 80 through 81 with 443 once"
991        );
992    }
993
994    /// A keyword that resolved to nothing is not an empty expression.
995    ///
996    /// A caller's [`ResolverFn`] may insert nothing for `lan` on a host with no LAN;
997    /// that is [`TargetParseError::ResolvedToNothing`], not
998    /// [`TargetParseError::Empty`].
999    #[test]
1000    fn a_keyword_that_resolves_to_nothing_says_what_went_wrong() {
1001        fn resolves_to_nothing(_: Keyword, _: &mut IpSet) -> Result<(), IpParseError> {
1002            Ok(())
1003        }
1004
1005        let ctx = TargetContext::new().with_keywords(&resolves_to_nothing);
1006        let mut builder = TargetMapBuilder::new(ports("80"));
1007        let error = builder.push("lan", &ctx).expect_err("nothing was named");
1008
1009        assert_eq!(
1010            error,
1011            TargetParseError::ResolvedToNothing("lan".to_string()),
1012            "the word it was said about has to be in it"
1013        );
1014        assert!(!error.to_string().contains("cannot be empty"), "{error}");
1015
1016        // A token with nothing in it keeps its own error.
1017        assert_eq!(
1018            builder.push("   ", &ctx).expect_err("nothing was written"),
1019            TargetParseError::Blank(3, "s")
1020        );
1021        assert_eq!(
1022            builder.push("", &ctx).expect_err("nothing was written"),
1023            TargetParseError::Empty
1024        );
1025    }
1026
1027    /// A hostname with no lookup is an error, not silently skipped.
1028    #[test]
1029    fn a_hostname_without_a_lookup_is_refused_rather_than_skipped() {
1030        let mut builder = TargetMapBuilder::new(ports("80"));
1031
1032        let err = builder
1033            .push("scanme.example", &TargetContext::new())
1034            .expect_err("a hostname needs a lookup");
1035
1036        assert!(
1037            matches!(err, TargetParseError::NoHostLookup(ref name) if name == "scanme.example")
1038        );
1039        assert!(builder.is_empty(), "a refused target left nothing behind");
1040    }
1041
1042    #[test]
1043    fn a_hostname_resolves_through_the_callers_lookup() {
1044        let lookup = |name: &str| match name {
1045            "one.example" => Some(vec![IpAddr::V4(Ipv4Addr::new(198, 51, 100, 1))]),
1046            "two.example" => Some(vec![
1047                IpAddr::V4(Ipv4Addr::new(198, 51, 100, 2)),
1048                IpAddr::V4(Ipv4Addr::new(198, 51, 100, 3)),
1049            ]),
1050            _ => None,
1051        };
1052        let ctx = TargetContext::new().with_hosts(&lookup);
1053
1054        let mut builder = TargetMapBuilder::new(ports("80"));
1055        builder.push("one.example", &ctx).unwrap();
1056        builder.push("two.example:443", &ctx).unwrap();
1057
1058        assert_eq!(builder.address_count(), 3);
1059        assert_eq!(builder.group_count(), 2);
1060
1061        let err = builder
1062            .push("nowhere.example", &ctx)
1063            .expect_err("a name with no records is not a target");
1064        assert!(matches!(err, TargetParseError::UnknownHost(_)));
1065    }
1066
1067    /// A wrong address is not a hostname: no DNS query for `192.0.2.1/33`.
1068    #[test]
1069    fn a_malformed_address_is_reported_as_an_address() {
1070        let lookup = |_: &str| -> Option<Vec<IpAddr>> {
1071            panic!("a bad prefix must never be offered to a host lookup")
1072        };
1073        let ctx = TargetContext::new().with_hosts(&lookup);
1074
1075        let mut builder = TargetMapBuilder::new(ports("80"));
1076        let err = builder.push("192.0.2.1/33", &ctx).expect_err("refused");
1077
1078        assert!(matches!(
1079            err,
1080            TargetParseError::Address {
1081                source: IpParseError::InvalidPrefix(33),
1082                ..
1083            }
1084        ));
1085    }
1086
1087    /// A mistyped range such as `10.10.10.*` is not a hostname either, so no resolver
1088    /// learns which network is being scanned.
1089    #[test]
1090    fn a_mistyped_range_is_refused_without_a_lookup() {
1091        let lookup =
1092            |name: &str| -> Option<Vec<IpAddr>> { panic!("{name} was offered to a host lookup") };
1093        let ctx = TargetContext::new().with_hosts(&lookup);
1094
1095        for token in [
1096            "10.10.10.*",
1097            "10.10.1-5.1-254",
1098            "10.10.10.1-256",
1099            "10.10.10.0/",
1100            "/0",
1101            "192.0.2.300",
1102            "2001:db8::1-ff",
1103            "10.10.10.1a",
1104            "10.10.10.a",
1105            "10.10.10.1-2.example",
1106        ] {
1107            let mut builder = TargetMapBuilder::new(ports("80"));
1108            let err = builder.push(token, &ctx).expect_err(token);
1109
1110            assert!(
1111                matches!(err, TargetParseError::MistypedAddress(ref t) if t == token),
1112                "{token}: {err:?}"
1113            );
1114            // The concurrent collection pass asks the same question.
1115            assert_eq!(host_name(token), HostName::Mistyped, "{token}");
1116        }
1117    }
1118
1119    /// Whatever a resolver would plausibly answer for is still asked, including a
1120    /// trailing dot and a non-ASCII label.
1121    #[test]
1122    fn a_name_of_any_ordinary_shape_still_reaches_the_lookup() {
1123        for name in [
1124            "printer",
1125            "nas-1",
1126            "scanme.example",
1127            "scanme.example.",
1128            "host_1.corp.example",
1129            "3com.example",
1130            "bücher.example",
1131            "xn--bcher-kva.example",
1132            "0.pool.ntp.example",
1133            "192.0.2.1.sslip.example",
1134            "1.2.0.192.in-addr.arpa",
1135        ] {
1136            assert_eq!(host_name(name), HostName::Yes, "{name}");
1137        }
1138
1139        // A port specification after a colon: an IPv6 target that wanted brackets.
1140        assert_eq!(host_name("2001:db8::zz:443"), HostName::Unbracketed);
1141    }
1142
1143    #[test]
1144    fn a_malformed_port_specification_is_reported_as_ports() {
1145        let mut builder = TargetMapBuilder::new(ports("80"));
1146        let err = builder
1147            .push("198.51.100.1:http", &TargetContext::new())
1148            .expect_err("refused");
1149
1150        assert!(matches!(err, TargetParseError::Ports { .. }));
1151        assert!(builder.is_empty());
1152    }
1153
1154    /// The zone survives the split.
1155    #[test]
1156    fn a_bracketed_link_local_target_keeps_its_interface() {
1157        fn zones(name: &str) -> Option<u32> {
1158            (name == "en0").then_some(7)
1159        }
1160        let ctx = TargetContext::new().with_zones(&zones);
1161
1162        let mut builder = TargetMapBuilder::new(ports("80"));
1163        builder.push("[fe80::aa%en0]:22", &ctx).unwrap();
1164
1165        let map = builder.build();
1166        assert_eq!(map.units[0].ips().v6()[0].zone(), Some(7));
1167        assert_eq!(map.units[0].ports(), &ports("22"));
1168    }
1169
1170    /// A resolver can close over state, such as an interface table read once.
1171    #[test]
1172    fn a_resolver_may_close_over_what_it_needs_to_answer() {
1173        let interfaces = [("en0".to_string(), 7u32), ("utun3".to_string(), 12)];
1174        let zones = |name: &str| {
1175            interfaces
1176                .iter()
1177                .find(|(known, _)| known == name)
1178                .map(|(_, index)| *index)
1179        };
1180        let ctx = TargetContext::new().with_zones(&zones);
1181
1182        let mut builder = TargetMapBuilder::new(ports("80"));
1183        builder.push("[fe80::aa%utun3]:22", &ctx).expect("parses");
1184
1185        let map = builder.build();
1186        assert_eq!(map.units[0].ips().v6()[0].zone(), Some(12));
1187    }
1188
1189    /// The running total equals what walking the accumulated groups would give.
1190    #[test]
1191    fn the_running_address_total_matches_what_the_groups_hold() {
1192        let ctx = TargetContext::new();
1193        let mut builder = TargetMapBuilder::new(ports("80"));
1194
1195        for target in [
1196            "198.51.100.0/24",
1197            "198.51.100.5",
1198            "192.0.2.1:22",
1199            "2001:db8::/120",
1200            "203.0.113.1,203.0.113.2,203.0.113.3",
1201            "[fe80::1]:443",
1202        ] {
1203            builder.push(target, &ctx).expect("parses");
1204        }
1205
1206        let walked = builder
1207            .groups
1208            .iter()
1209            .fold(0u128, |total, (_, ips)| total + ips.len_gross());
1210
1211        assert_eq!(builder.gross_address_count(), walked);
1212        // Never below the merged figure.
1213        assert!(builder.gross_address_count() >= builder.address_count());
1214    }
1215
1216    /// A CIDR block counts every address it covers.
1217    #[test]
1218    fn address_count_reports_what_a_block_holds_not_what_was_written() {
1219        let mut builder = TargetMapBuilder::new(ports("80"));
1220        builder.push("10.0.0.0/8", &TargetContext::new()).unwrap();
1221
1222        assert_eq!(builder.address_count(), 16_777_216);
1223
1224        let mut everything = TargetMapBuilder::new(ports("80"));
1225        everything.push("::/0", &TargetContext::new()).unwrap();
1226        assert_eq!(everything.address_count(), u128::MAX);
1227    }
1228
1229    /// A comma separates addresses left of the port separator and ports right of it.
1230    #[test]
1231    fn a_comma_separates_addresses_before_the_ports_and_ports_after_them() {
1232        let ctx = TargetContext::new();
1233
1234        let mut hosts = TargetMapBuilder::new(ports("80"));
1235        hosts.push("198.51.100.1,198.51.100.2:443", &ctx).unwrap();
1236        assert_eq!(hosts.address_count(), 2);
1237        assert_eq!(hosts.build().units[0].ports(), &ports("443"));
1238
1239        let mut services = TargetMapBuilder::new(ports("80"));
1240        services.push("198.51.100.1:80,443", &ctx).unwrap();
1241        assert_eq!(services.address_count(), 1);
1242        assert_eq!(services.build().units[0].ports(), &ports("80,443"));
1243
1244        let mut bare = TargetMapBuilder::new(ports("80"));
1245        bare.push("198.51.100.1, 198.51.100.2 ,198.51.100.3", &ctx)
1246            .unwrap();
1247        assert_eq!(bare.address_count(), 3);
1248    }
1249
1250    /// The map a builder that grouped unconditionally would have produced.
1251    ///
1252    /// Computed independently of the builder.
1253    fn grouped_by_hand(tokens: &[String], default: &PortSet) -> Vec<(PortSet, Vec<Target>)> {
1254        let mut order: Vec<PortSet> = Vec::new();
1255        let mut groups: HashMap<PortSet, IpSet> = HashMap::new();
1256
1257        for token in tokens {
1258            let expr = TargetExpr::parse(token).expect("parses");
1259            let ports = match expr.ports {
1260                Some(spec) => PortSet::try_from(spec).expect("ports parse"),
1261                None => default.clone(),
1262            };
1263
1264            if !groups.contains_key(&ports) {
1265                order.push(ports.clone());
1266                groups.insert(ports.clone(), IpSet::new());
1267            }
1268
1269            let ips = groups.get_mut(&ports).expect("just inserted");
1270            for address in expr.addresses() {
1271                insert_expression(address, ips, None, None).expect("addresses parse");
1272            }
1273        }
1274
1275        order
1276            .into_iter()
1277            .map(|ports| {
1278                let ips = groups.remove(&ports).expect("one group per spelling");
1279                let unit = TargetSet::new(ips, ports.clone());
1280                (ports, unit.iter().collect())
1281            })
1282            .collect()
1283    }
1284
1285    /// Every unit of a map, as its ports and the targets it yields.
1286    fn units_of(map: &TargetMap) -> Vec<(PortSet, Vec<Target>)> {
1287        map.units
1288            .iter()
1289            .map(|unit| (unit.ports().clone(), unit.iter().collect()))
1290            .collect()
1291    }
1292
1293    /// The threshold changes how the builder works, not what it produces. Checked at
1294    /// three lengths around the sample size.
1295    #[test]
1296    fn the_map_is_the_same_either_side_of_the_grouping_threshold() {
1297        let ctx = TargetContext::new();
1298        let default = ports("80");
1299
1300        for count in [
1301            GROUPING_SAMPLE - 1,
1302            GROUPING_SAMPLE + 1,
1303            GROUPING_SAMPLE * 4,
1304        ] {
1305            let tokens: Vec<String> = (0..count)
1306                .map(|i| format!("10.0.{}.{}:{}", i / 256, i % 256, 1 + i))
1307                .collect();
1308
1309            let mut builder = TargetMapBuilder::new(default.clone());
1310            for token in &tokens {
1311                builder.push(token, &ctx).expect("parses");
1312            }
1313            let built = builder.build();
1314
1315            assert_eq!(
1316                units_of(&built),
1317                grouped_by_hand(&tokens, &default),
1318                "{count} expressions, none of them sharing a specification"
1319            );
1320        }
1321    }
1322
1323    /// A distinct specification on every line gives the index up; after that a
1324    /// specification already seen gets a unit of its own.
1325    #[test]
1326    fn a_file_that_never_groups_gives_the_index_up() {
1327        let mut builder = TargetMapBuilder::new(ports("80"));
1328        let ctx = TargetContext::new();
1329
1330        for i in 0..GROUPING_SAMPLE {
1331            let token = format!("10.0.{}.{}:{}", i / 256, i % 256, 1 + i);
1332            builder.push(&token, &ctx).expect("parses");
1333        }
1334        assert_eq!(builder.group_count(), GROUPING_SAMPLE);
1335
1336        // Port 1 has had a group since the first line; with the index gone it
1337        // gets a second.
1338        builder.push("10.9.9.9:1", &ctx).expect("parses");
1339        assert_eq!(builder.group_count(), GROUPING_SAMPLE + 1);
1340
1341        let map = builder.build();
1342        assert_eq!(map.units[0].ports(), &ports("1"));
1343        assert_eq!(map.units[GROUPING_SAMPLE].ports(), &ports("1"));
1344        assert_eq!(
1345            map.gross_targets().unwrap(),
1346            GROUPING_SAMPLE as u128 + 1,
1347            "both units are still scanned, on the ports they named"
1348        );
1349    }
1350
1351    /// A long file that groups keeps its index.
1352    #[test]
1353    fn a_file_that_groups_keeps_its_index_however_long_it_is() {
1354        let mut builder = TargetMapBuilder::new(ports("80"));
1355        let ctx = TargetContext::new();
1356
1357        for i in 0..GROUPING_SAMPLE * 4 {
1358            let token = format!("10.0.{}.{}", i / 256, i % 256);
1359            builder.push(&token, &ctx).expect("parses");
1360        }
1361
1362        assert_eq!(builder.group_count(), 1);
1363    }
1364
1365    /// One line in eight repeating a specification keeps the index; one in
1366    /// thirty-two does not.
1367    #[test]
1368    fn the_index_is_kept_or_given_up_on_how_much_actually_regroups() {
1369        let ctx = TargetContext::new();
1370        let lines = GROUPING_SAMPLE * 4;
1371
1372        for (every, kept) in [(8usize, true), (32, false)] {
1373            let mut builder = TargetMapBuilder::new(ports("80"));
1374            for i in 0..lines {
1375                // Every `every`th line repeats the specification before it.
1376                let spec = 1 + i - usize::from(i % every == every - 1);
1377                let token = format!("10.0.{}.{}:{}", i / 256, i % 256, spec);
1378                builder.push(&token, &ctx).expect("parses");
1379            }
1380
1381            let regrouped = lines / every;
1382            if kept {
1383                assert_eq!(
1384                    builder.group_count(),
1385                    lines - regrouped,
1386                    "one line in {every} joined the group before it"
1387                );
1388            } else {
1389                assert!(
1390                    builder.group_count() > lines - regrouped,
1391                    "one line in {every} is too little to keep an index for"
1392                );
1393            }
1394        }
1395    }
1396
1397    #[test]
1398    fn overlapping_targets_in_one_group_merge_rather_than_duplicate() {
1399        let mut builder = TargetMapBuilder::new(ports("80"));
1400        let ctx = TargetContext::new();
1401
1402        builder.push("10.0.0.0/24", &ctx).unwrap();
1403        builder.push("10.0.0.5", &ctx).unwrap();
1404        builder.push("10.0.0.128-10.0.1.10", &ctx).unwrap();
1405
1406        assert_eq!(builder.address_count(), 267, "0.0-1.10, counted once each");
1407        assert_eq!(builder.group_count(), 1);
1408    }
1409}