This should not happen; FromStr should not panic but instead return a variable.

While these are obvious garbage, you can see what's happening here—we're trying to index poorly into obvious garbage. Maybe don't do that!

Examples from my fuzzer:

"2620:132:b004:20::0o73".parse(); // panic
"2620:132:b004:20::0�73".parse(); // panic
"�ʦ2\n�d����3�".parse(); // panic
"䀀".parse(); // panic
"򜜜".parse(); // panic
"10.4.32.0/204:20::0/睝00MMMMMMMMMMMMMMMMMM����dMMMMMMM0#7�".parse(); // panic
"100.4.32.0/20::0/7睝Νŝ0  � ///// 0S3Ν�AŝE0�3Νŝ0S3Ν0W0S3Ν\nAŝ07睝Νŝ00S3Ν�Aŝ00�3Νŝ00S3    W:22G3Ν���3Νŝ00S3ʝ�A3ų\n\nŝ00W3΂� W W:22G W WD2@G�022222222222222222=:24\n0=:".parse(); // panic

The current ergonomics of Contains are… not the most fantastically optimal:

The problem with this is that all impls are constrained to From-convertible types (which is nice) but this means that some additional work is always done to first create a new Net.*Addr type and then take the address. In cases where we're checking IP containment, we only need to mask the provided IP; there's no need to create anything and copy bytes around.

I propose to add a type parameter to the Contains type and require the contains method to take that value. Ideally, without breaking existing code.

• Implement the function on relevant types like so. (#82)
• Adjust the Display trait to give /-notation.
  • What comes after the / is <max> - count_ones.

As part of #26, we should include some kind of implementation for C-VALIDATE in all of the methods that require the NetAddr to be fully masked.

The worst case I can think of is a NetAddr that isn't masked, which doesn't really cause any harm as masking usually happens regardless. But, if somehow memory gets corrupted and a mask changes, the NetAddr's addr might be wrong. (Think: unsafeness through FFI or something ridiculous like that.)

I think it's sufficient to add debug_assert!'s. Could also add a feature for checks which would be on by default.

Worth some thinking.

I think I've finally settled on a way of doing this.

We need three "families" of traits, to be complete, I think.

• Net.*AddrAddressIterator is the simplest. This struct will cover iteration over a network's addresses, starting from the network address (or whatever the addr field contains, which should be asserted per #70.)
• Net.*AddrSubnetIterator is the second-simplest. This struct will cover iterating over a network's subnets. I will need to work out how to compute the next sibling of a given network.
  • So for example, iterating over a /24 in groups of /28's will require adding a certain offset rather than just 1.
  • Net.*AddrAddressIterator can be rewritten to just use a SubnetIterator with /32 or /128, and conversion overhead is pretty minimal.
• Net.*AddrSiblingIterator would yield a network's siblings until IP space is exhausted.

On each of the NetAddr, Netv4Addr, and Netv6Addr types, we need to implement:

• addresses(&self) -> Net.*AddrAddressIterator,
• subnets(&self, mask: Into<Ip.*Addr>) -> Net.*AddrSubnetIterator
• siblings(&self /*, any params???? */ ) -> Net.*AddrSiblingIterator

Conceptually, it's possible to have non-contiguous netmasks when you're building networks.

Some background I've found during research:

• IETF RFC 950 (1985) specifies that contiguous netmasks are not a requirement. Explicitly,

  Since the bits that identify the subnet are specified by a
  bitmask, they need not be adjacent in the address. However, we
  recommend that the subnet bits be contiguous and located as the
  most significant bits of the local address.

• IETF RFC 1519 (1993) (superseded by IETF RFC 4632, 2006) seems to require contiguous netmasks instead, though:

  An implementation following these rules should also be generalized,
  so that an arbitrary network number and mask are accepted for all
  routing destinations. The only outstanding constraint is that the
  mask must be left contiguous.

This comes down to a question of intention. I intend for this crate to be used in any networking scenario, and with this scope corner cases abound. I could foresee a network operator deciding that—despite it being a terrible practice—using non-contiguous netmasks is a good idea, and they might want to check only a certain subset of the netmask. The question at hand is: is it even feasible for non-contiguous netmasks to be specified?

• On the public internet, the answer is no. Since allocations are now based on left-contiguous netmasks only (per RFC1519 and 4632), it's not really possible to get something other than a /xx.
• But in the private space, the answer is maybe. For example, what if I (as the operator) wanted only to give out DHCP leases that were odd-numbered, within a subnet? Or noncontiguous groups of devices? There's nothing stopping me from doing so.

The problem is that supporting noncontiguous netmasks means we cannot use standard traits like core::ops::RangeBounds. Users might expect those to be implemented, or might not care very much.

This issue was generated by todo based on a TODO comment in eafc953 when #25 was merged. cc @rye.

Rust API Guidelines Checklist

• Naming (crate aligns with Rust naming conventions)
  • Casing conforms to RFC 430 (C-CASE)
  • Ad-hoc conversions follow as_, to_, into_ conventions (C-CONV)
  • Getter names follow Rust convention (C-GETTER)
  • Methods on collections that produce iterators follow iter, iter_mut, into_iter (C-ITER)
  • Iterator type names match the methods that produce them (C-ITER-TY)
  • Feature names are free of placeholder words (C-FEATURE)
  • Names use a consistent word order (C-WORD-ORDER)
• Interoperability (crate interacts nicely with other library functionality)
  • Types eagerly implement common traits (C-COMMON-TRAITS)
    • Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug,
      Display, Default
  • Conversions use the standard traits From, AsRef, AsMut (C-CONV-TRAITS)
  • Collections implement FromIterator and Extend (C-COLLECT)
  • Data structures implement Serde's Serialize, Deserialize (C-SERDE)
  • Types are Send and Sync where possible (C-SEND-SYNC)
  • Error types are meaningful and well-behaved (C-GOOD-ERR)
  • Binary number types provide Hex, Octal, Binary formatting (C-NUM-FMT)
  • Generic reader/writer functions take R: Read and W: Write by value (C-RW-VALUE)
• Macros (crate presents well-behaved macros)
  • Input syntax is evocative of the output (C-EVOCATIVE)
  • Macros compose well with attributes (C-MACRO-ATTR)
  • Item macros work anywhere that items are allowed (C-ANYWHERE)
  • Item macros support visibility specifiers (C-MACRO-VIS)
  • Type fragments are flexible (C-MACRO-TY)
• Documentation (crate is abundantly documented)
  • Crate level docs are thorough and include examples (C-CRATE-DOC)
  • All items have a rustdoc example (C-EXAMPLE)
  • Examples use ?, not try!, not unwrap (C-QUESTION-MARK)
  • Function docs include error, panic, and safety considerations (C-FAILURE)
  • Prose contains hyperlinks to relevant things (C-LINK)
  • Cargo.toml includes all common metadata (C-METADATA)
    • authors, description, license, homepage, documentation, repository,
      readme, keywords, categories
  • Crate sets html_root_url attribute "https://docs.rs/CRATE/X.Y.Z" (C-HTML-ROOT)
  • Release notes document all significant changes (C-RELNOTES)
  • Rustdoc does not show unhelpful implementation details (C-HIDDEN)
• Predictability (crate enables legible code that acts how it looks)
  • Smart pointers do not add inherent methods (C-SMART-PTR)
  • Conversions live on the most specific type involved (C-CONV-SPECIFIC)
  • Functions with a clear receiver are methods (C-METHOD)
  • Functions do not take out-parameters (C-NO-OUT)
  • Operator overloads are unsurprising (C-OVERLOAD)
  • Only smart pointers implement Deref and DerefMut (C-DEREF)
  • Constructors are static, inherent methods (C-CTOR)
• Flexibility (crate supports diverse real-world use cases)
  • Functions expose intermediate results to avoid duplicate work (C-INTERMEDIATE)
  • Caller decides where to copy and place data (C-CALLER-CONTROL)
  • Functions minimize assumptions about parameters by using generics (C-GENERIC)
  • Traits are object-safe if they may be useful as a trait object (C-OBJECT)
• Type safety (crate leverages the type system effectively)
  • Newtypes provide static distinctions (C-NEWTYPE)
  • Arguments convey meaning through types, not bool or Option (C-CUSTOM-TYPE)
  • Types for a set of flags are bitflags, not enums (C-BITFLAG)
  • Builders enable construction of complex values (C-BUILDER)
• Dependability (crate is unlikely to do the wrong thing)
  • Functions validate their arguments (C-VALIDATE)
  • Destructors never fail (C-DTOR-FAIL)
  • Destructors that may block have alternatives (C-DTOR-BLOCK)
• Debuggability (crate is conducive to easy debugging)
  • All public types implement Debug (C-DEBUG)
  • Debug representation is never empty (C-DEBUG-NONEMPTY)
• Future proofing (crate is free to improve without breaking users' code)
  • Sealed traits protect against downstream implementations (C-SEALED)
  • Structs have private fields (C-STRUCT-PRIVATE)
  • Newtypes encapsulate implementation details (C-NEWTYPE-HIDE)
  • Data structures do not duplicate derived trait bounds (C-STRUCT-BOUNDS)
• Necessities (to whom they matter, they really matter)
  • Public dependencies of a stable crate are stable (C-STABLE)
  • Crate and its dependencies have a permissive license (C-PERMISSIVE)

Would be nice to have.

More of a moving-files-around change, but this would be nice to have from an organization standpoint. I don't like having big files, and moving things to files ensures pub is properly applied from a testing standpoint.

It'd be nice to write tests for non-CIDR netaddr handling. I know (more or less for a fact) that I've been very selective about which things get CIDR handling, and which things don't.

Ideally, we would do so by manually writing corner cases.

Inspired by https://github.com/dspinhirne/netaddr-rb/blob/38a4a64300a2a9d228bcaf436bea8f368bc20fc5/lib/ipv4net.rb#L97-L104, write a method that allows for the computation of sibling networks. For example, the next sibling of 127.0.0.0/24 is 127.0.1.0/24?

• Verify what the netaddr gem does.
• Decide on a better path here, if one exists.

While this crate does fit the use case I have for it, (that is, parsing and manipulating crates in non-embedded use cases) it'd be nice to add no_std support in case someone wants to use this crate.

The main barrier here is that IpAddr is not part of core; it is in std::net.

Ipv4Addr and Ipv6Addr, unfortunately, are apparently wrappers over the system in and in6 things…, which unfortunately means it'll be non-trivial to port away.

I might need to implement Ip.*Addr things myself eventually.

Would be nice to have.

This will make me much happier.

One does not need to have such a directory. There is already a mechanism for integration tests; it is far better to put tests in the modules that they are testing.

• src/tests/netaddr/from/ipaddr.rs (#39, #48)
• src/tests/netaddr/merge.rs (#44)
• src/tests/netaddr/parse.rs (#51)
• src/tests/netaddr/from.rs (#39)
• src/tests/netaddr/broadcast.rs (#45)
• src/tests/netaddr/cmp.rs (#53)
• src/tests/netaddr/contains.rs (#54)
• src/tests/util.rs (#50)
• src/tests/util/gen_v4_mask.rs (#50)
• src/tests/util/gen_v6_mask.rs (#50)
• src/tests/netaddr.rs (#55)
• src/tests/netaddr_error.rs (#55)