Skip to main content

bgpkit_snap/
lib.rs

1//! bgpkit-snap v4: an immutable container for prefix tries.
2//!
3//! The container owns framing, identity and integrity. It knows nothing about
4//! what a trie holds beyond the value type's `TYPE_ID`, and nothing about what a
5//! client section means. See `docs/format.md`.
6
7#![deny(missing_docs)]
8// The only unsafe in this crate is the two archived-trie accessors, which read bytes
9// `open` already byte-checked; everything else must stay safe.
10#![deny(unsafe_code)]
11
12use std::fmt;
13
14use ipnet::{IpNet, Ipv4Net, Ipv6Net};
15use prefix_trie::rkyv::ArchivedPrefixMap;
16use prefix_trie::{AsView, PrefixMap, TrieView};
17use rkyv::rancor::Error as RkyvError;
18
19/// The address types this crate takes and returns, re-exported so a caller cannot
20/// end up on another version of `ipnet` than the one in its signatures. Unlike the
21/// archive re-export this one is complete: no macro expands `::ipnet::` paths.
22pub use ipnet;
23
24/// The archived trie types `Snapshot::v4`/`v6` return, re-exported so a caller that
25/// names them does not have to pin this crate's `prefix-trie` version itself.
26pub use prefix_trie;
27
28/// The archive library this crate builds value types on, re-exported so a
29/// caller can name the same version in a signature.
30///
31/// It does not remove the dependency: `#[derive(rkyv::Archive)]` expands to paths
32/// rooted at `rkyv`, so a crate that derives needs `rkyv` in its own manifest even
33/// though this re-export exists.
34pub use rkyv;
35use rkyv::util::AlignedVec;
36use std::io::Write;
37
38pub mod header;
39pub mod journal;
40pub mod profile;
41
42pub use header::{
43    Entry, Header, StreamRef, ENTRY_LEN, FLAG_STREAM, FLAG_WINDOW, HEADER_LEN, ID_V4, ID_V6,
44    KIND_PAYLOAD, KIND_V4, KIND_V6,
45};
46
47/// The serializer `rkyv::to_bytes` builds, so the value bound can name it.
48pub type HighSer<'a> =
49    rkyv::api::high::HighSerializer<AlignedVec, rkyv::ser::allocator::ArenaHandle<'a>, RkyvError>;
50
51/// The developer guide ships inside the crate so its examples are doctests: a
52/// signature change breaks `cargo test --doc` instead of leaving the page wrong.
53/// The module is private, so the guide is not rendered in the API docs.
54#[doc = include_str!("../docs/bgpkit-snap-developer-guide.md")]
55mod guide {}
56
57// ---------------------------------------------------------------- errors
58
59/// Every way this crate refuses.
60///
61/// `#[non_exhaustive]`: a new refusal is a change to the crate, not to the caller's
62/// match, so a caller needs a catch-all arm.
63#[derive(Debug)]
64#[non_exhaustive]
65pub enum Error {
66    /// An operating-system call failed; `source()` gives the original.
67    Io(std::io::Error),
68    /// The first eight bytes are not this container's magic.
69    BadMagic,
70    /// The layout version in the header is not one this build reads.
71    BadVersion(u16),
72    /// A header field is out of range or contradicts another.
73    BadHeader(&'static str),
74    /// The header's checksum does not match its contents.
75    BadHeaderCrc,
76    /// The file ends before the structure it declares.
77    Truncated {
78        /// Bytes the structure needs.
79        need: usize,
80        /// Bytes present.
81        have: usize,
82    },
83    /// The section table is not a table this format allows.
84    BadSectionTable(&'static str),
85    /// Section ids are not strictly ascending, or a section is missing.
86    SectionOrder,
87    /// The object carries a required section this reader does not implement.
88    UnknownRequiredSection(u16),
89    /// A section's four-byte kind tag does not belong to its id.
90    BadSectionKind(u16),
91    /// The object holds another value type than the one this reader asked for.
92    TypeMismatch {
93        /// `TYPE_ID` recorded in the header.
94        expected: String,
95        /// `TYPE_ID` of the reader.
96        found: String,
97    },
98    /// The content id in the header does not match the bytes.
99    ContentId,
100    /// Another writer holds this journal's lock. Retry later; this is not damage.
101    Locked,
102    /// A caller-supplied option is not something a writer can emit.
103    BadOpts(&'static str),
104    /// A section id the caller supplied is not usable here.
105    BadSectionId(u16),
106    /// A prefix the caller supplied has host bits set.
107    BadPrefix(String),
108    /// A section's body is not a valid archive of the type this reader asked for.
109    BadArchive(u16),
110    /// The directory or object was written under a different configuration than the
111    /// one this call was made with, and adopting it would reinterpret the bytes.
112    ConfigMismatch(String),
113    /// A value could not be encoded, or an archived value could not be decoded.
114    BadValue,
115    /// A journal record or its state is not a record this build can act on.
116    BadRecord(&'static str),
117    /// The object a journal was attached to is gone or is no longer that object. A
118    /// journal is a log of changes to one object, so this is not damage to the log:
119    /// point the journal at the object it was attached to, or the log means nothing.
120    BaseLost(String),
121    /// Records were lost: the next sequence number on disk is not the expected one.
122    SequenceGap {
123        /// The sequence number the journal expected next.
124        expected: u64,
125        /// The sequence number the segment holds.
126        found: u64,
127    },
128}
129
130impl fmt::Display for Error {
131    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
132        match self {
133            Error::Io(e) => write!(f, "io: {e}"),
134            Error::BadMagic => write!(f, "not a snap object"),
135            Error::BadVersion(v) => write!(f, "unsupported format version {v}"),
136            Error::BadHeader(why) => write!(f, "bad header: {why}"),
137            Error::BadHeaderCrc => write!(f, "header crc mismatch"),
138            Error::Truncated { need, have } => write!(f, "truncated: need {need}, have {have}"),
139            Error::BadSectionTable(why) => write!(f, "bad section table: {why}"),
140            Error::SectionOrder => write!(f, "sections are not in ascending id order"),
141            Error::UnknownRequiredSection(id) => write!(
142                f,
143                "section {id} is required but this reader does not know it; \
144                 open the object with a validator that implements it"
145            ),
146            Error::BadSectionKind(id) => write!(f, "section {id} has an unexpected kind tag"),
147            Error::TypeMismatch { expected, found } => {
148                write!(
149                    f,
150                    "value type mismatch: expected {expected}, found {found:?}"
151                )
152            }
153            Error::ContentId => write!(f, "content id mismatch"),
154            Error::Locked => write!(f, "another writer holds this journal"),
155            Error::BadOpts(what) => write!(f, "bad writer option: {what}"),
156            Error::BadSectionId(id) => write!(f, "section id {id} cannot be used here"),
157            Error::BadPrefix(p) => write!(f, "prefix {p} has host bits set"),
158            Error::BadArchive(id) => {
159                write!(f, "section {id} is not an archive of this value type")
160            }
161            Error::ConfigMismatch(why) => write!(f, "{why}"),
162            Error::BadValue => write!(f, "value could not be decoded"),
163            Error::BadRecord(what) => write!(f, "journal record: {what}"),
164            Error::BaseLost(what) => write!(f, "journal base: {what}"),
165            Error::SequenceGap { expected, found } => {
166                write!(
167                    f,
168                    "journal sequence gap: expected {expected}, found {found}"
169                )
170            }
171        }
172    }
173}
174
175impl std::error::Error for Error {
176    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
177        match self {
178            Error::Io(e) => Some(e),
179            _ => None,
180        }
181    }
182}
183
184impl From<std::io::Error> for Error {
185    fn from(e: std::io::Error) -> Self {
186        Error::Io(e)
187    }
188}
189
190// ---------------------------------------------------------------- coverage
191
192/// How much of an address space a tree's entries cover.
193///
194/// A tuple of options could not tell "this family has no entries" from "this family
195/// is covered end to end" (an IPv6 tree holding `::/0` covers 2^128 addresses, which
196/// does not fit in the count).
197#[derive(Debug, Clone, Copy, PartialEq, Eq)]
198pub enum Count {
199    /// The tree holds no entry for this family.
200    NoEntries,
201    /// The whole address space is claimed.
202    All,
203    /// That many distinct addresses are covered; overlapping entries count once.
204    Exact(u128),
205}
206
207impl Count {
208    /// The number of addresses covered, when it is a number. `All` is the whole
209    /// space, which no `u128` holds for IPv6; `NoEntries` is zero.
210    pub fn exact(self) -> Option<u128> {
211        match self {
212            Count::NoEntries => Some(0),
213            Count::Exact(n) => Some(n),
214            Count::All => None,
215        }
216    }
217}
218
219impl std::fmt::Display for Count {
220    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
221        match self {
222            Count::NoEntries => f.write_str("0"),
223            Count::Exact(n) => write!(f, "{n}"),
224            Count::All => f.write_str("all"),
225        }
226    }
227}
228
229/// The answer to `Snapshot::address_counts`.
230#[derive(Debug, Clone, Copy, PartialEq, Eq)]
231pub struct AddressCounts {
232    /// Coverage of the IPv4 tree.
233    pub v4: Count,
234    /// Coverage of the IPv6 tree.
235    pub v6: Count,
236}
237
238// ---------------------------------------------------------------- values
239
240/// The one-attribute way to make a value type: it adds `rkyv`'s derives for you.
241#[cfg(feature = "derive")]
242pub use bgpkit_snap_derive::snap_value;
243/// The derive, re-exported so a caller writes `bgpkit_snap::SnapValue` for both the
244/// trait and `#[derive(SnapValue)]`. The macro lives in a namespace of its own, so the
245/// name is not taken twice.
246#[cfg(feature = "derive")]
247pub use bgpkit_snap_derive::SnapValue;
248
249/// A value type that can live in a trie.
250///
251/// `#[derive(SnapValue)]` only writes the id; the archive impls come from `rkyv`. The
252/// diagnostics below say that once, where the compiler would otherwise print rkyv's
253/// strategy types.
254#[diagnostic::on_unimplemented(
255    message = "`{Self}` cannot be stored in a snapshot",
256    label = "not a value type",
257    note = "a value type needs `Clone`, rkyv's `Archive` and `Serialize`, and `SnapValue` for its id:",
258    note = "#[derive(Clone, rkyv::Archive, rkyv::Serialize, rkyv::Deserialize, bgpkit_snap::SnapValue)]",
259    note = "#[snap(type_id = \"your.type:v1\")]"
260)]
261pub trait SnapValue: rkyv::Archive + Clone + for<'a> rkyv::Serialize<HighSer<'a>> {
262    /// Stable identifier, e.g. `snap.u32:v1`.
263    ///
264    /// At most 31 bytes of printable ASCII, no space, quote or backslash, and not
265    /// empty: it is stored verbatim in the header and compared on every open, so a
266    /// value that cannot round-trip through those bytes is rejected at `finish`.
267    const TYPE_ID: &'static str;
268
269    /// Bring the value into canonical form before it is written. The default is
270    /// a no-op; override it when the value has an order that does not come from
271    /// its own fields.
272    fn canonicalize(&mut self) {}
273}
274
275impl SnapValue for u8 {
276    const TYPE_ID: &str = "snap.u8:v1";
277}
278
279impl SnapValue for u16 {
280    const TYPE_ID: &str = "snap.u16:v1";
281}
282
283impl SnapValue for u32 {
284    const TYPE_ID: &str = "snap.u32:v1";
285}
286
287impl SnapValue for u64 {
288    const TYPE_ID: &str = "snap.u64:v1";
289}
290
291impl SnapValue for u128 {
292    const TYPE_ID: &str = "snap.u128:v1";
293}
294
295/// Decode a value from archived bytes, used by the journal.
296pub trait Codec: SnapValue + Sized {
297    /// Encode a value the way this container stores it.
298    fn encode(value: &Self) -> Result<Vec<u8>, Error>;
299    /// Decode a value that was stored this way.
300    fn decode(bytes: &[u8]) -> Result<Self, Error>;
301}
302
303impl<T> Codec for T
304where
305    T: SnapValue,
306    T::Archived: for<'a> rkyv::bytecheck::CheckBytes<rkyv::api::high::HighValidator<'a, RkyvError>>
307        + rkyv::Deserialize<T, rkyv::api::high::HighDeserializer<RkyvError>>,
308{
309    fn encode(value: &Self) -> Result<Vec<u8>, Error> {
310        rkyv::to_bytes::<RkyvError>(value)
311            .map(|b| b.to_vec())
312            .map_err(|_| Error::BadValue)
313    }
314
315    fn decode(bytes: &[u8]) -> Result<Self, Error> {
316        rkyv::from_bytes::<T, RkyvError>(bytes).map_err(|_| Error::BadValue)
317    }
318}
319
320// ---------------------------------------------------------------- writer
321
322/// The identity of the tree a journal writes.
323///
324/// A journal refuses a checkpoint that belongs to another tree, so the id is what
325/// stops two feeds from writing into one directory. `from_name` exists because
326/// hand-writing sixteen bytes is the kind of detail a caller gets wrong silently.
327#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
328pub struct TreeId([u8; 16]);
329
330impl TreeId {
331    /// The id as the sixteen bytes a header carries.
332    pub const fn from_bytes(bytes: [u8; 16]) -> Self {
333        Self(bytes)
334    }
335
336    /// A stable id for a human name: the first 16 bytes of its BLAKE3 hash.
337    ///
338    /// The same name always gives the same id, so a service that starts with
339    /// `TreeId::from_name("wayback-roas")` reopens its own journal and a typo in
340    /// the name gives a different journal instead of silently adopting this one.
341    pub fn from_name(name: &str) -> Self {
342        let mut out = [0u8; 16];
343        out.copy_from_slice(&blake3::hash(name.as_bytes()).as_bytes()[..16]);
344        Self(out)
345    }
346
347    /// The same sixteen bytes, for a caller comparing it with a header.
348    pub const fn as_bytes(&self) -> &[u8; 16] {
349        &self.0
350    }
351}
352
353impl From<[u8; 16]> for TreeId {
354    fn from(bytes: [u8; 16]) -> Self {
355        Self(bytes)
356    }
357}
358
359impl std::fmt::Display for TreeId {
360    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
361        for b in self.0 {
362            write!(f, "{b:02x}")?;
363        }
364        Ok(())
365    }
366}
367
368/// One section the caller supplies next to the tries: an arena, a sidecar, any
369/// bytes the profile owns. `id` is 16 or higher, `kind` is a four-byte tag, and
370/// `required` makes a reader that does not implement the id refuse the object.
371#[derive(Clone, Copy)]
372pub struct ExtraSection<'a> {
373    /// Section id; 16 or higher for a profile section.
374    pub id: u16,
375    /// Four-byte kind tag a validator can branch on.
376    pub kind: [u8; 4],
377    /// A reader that does not implement this id must refuse the object.
378    pub required: bool,
379    /// The section body, exactly as it will be written.
380    pub bytes: &'a [u8],
381}
382
383/// Everything a writer declares about the object.
384pub struct Opts<'a> {
385    /// unix seconds UTC, written into the header. `created_at` is deliberately
386    /// outside the content id, so this is provenance rather than identity.
387    pub created_at: i64,
388    /// Stream coordinates, written as given: `Writer::finish` sets the flag and stores
389    /// the `tree_id`, `generation` and `base_seq` the caller passed. A journal
390    /// overwrites them with its own, because a checkpoint belongs to that stream.
391    pub stream: Option<StreamRef>,
392    /// Coverage claim, `(first_ts, last_ts)` in unix seconds.
393    pub window: Option<(i64, i64)>,
394    /// Sections your profile owns; the tries and the id are the writer's.
395    pub extras: &'a [ExtraSection<'a>],
396}
397
398impl Opts<'_> {
399    /// The options most writers want: the current time, no window, no extras.
400    ///
401    /// There is no `Default`: a default would have to invent a creation time, and
402    /// an invented one is a valid header with false provenance.
403    pub fn now() -> Self {
404        Self {
405            created_at: chrono::Utc::now().timestamp(),
406            stream: None,
407            window: None,
408            extras: &[],
409        }
410    }
411}
412
413/// Builds one object in memory, then writes it in one piece.
414///
415/// A writer is not a store: it holds the whole tree, so a build larger than RAM is
416/// out of scope by design.
417pub struct Writer<T: SnapValue> {
418    v4: PrefixMap<Ipv4Net, T>,
419    v6: PrefixMap<Ipv6Net, T>,
420}
421
422impl<T: SnapValue> Default for Writer<T> {
423    fn default() -> Self {
424        Self::new()
425    }
426}
427
428impl<T: SnapValue> Writer<T> {
429    /// An empty writer.
430    pub fn new() -> Self {
431        Self {
432            v4: PrefixMap::new(),
433            v6: PrefixMap::new(),
434        }
435    }
436
437    /// Store `value` under `prefix`, replacing any value already there.
438    ///
439    /// The prefix must be canonical (`addr() == network()`); a prefix with host
440    /// bits set is refused with `Error::BadPrefix` in every build, because silently
441    /// storing it under its network address would make the key you asked for and
442    /// the key you get back differ.
443    pub fn insert(&mut self, prefix: IpNet, mut value: T) -> Result<(), Error> {
444        if prefix.addr() != prefix.network() {
445            // storing it under its network address would make the key you asked
446            // for and the key you get back differ, and two inputs would collide
447            return Err(Error::BadPrefix(prefix.to_string()));
448        }
449        value.canonicalize();
450        match prefix {
451            IpNet::V4(p) => {
452                self.v4.insert(p, value);
453            }
454            IpNet::V6(p) => {
455                self.v6.insert(p, value);
456            }
457        }
458        Ok(())
459    }
460
461    /// Insert many entries, stopping at the first prefix that is refused.
462    ///
463    /// `Writer` deliberately does not implement `Extend`: a set that silently
464    /// drops the entries it could not store is worse than a loop that stops.
465    pub fn insert_many(
466        &mut self,
467        entries: impl IntoIterator<Item = (IpNet, T)>,
468    ) -> Result<(), Error> {
469        for (prefix, value) in entries {
470            self.insert(prefix, value)?;
471        }
472        Ok(())
473    }
474
475    /// How many prefixes the writer holds.
476    pub fn len(&self) -> usize {
477        self.v4.len() + self.v6.len()
478    }
479
480    /// Whether the writer holds nothing.
481    pub fn is_empty(&self) -> bool {
482        self.len() == 0
483    }
484
485    /// Build the object. The caller writes the returned bytes wherever it likes.
486    pub fn finish(self, opts: &Opts<'_>) -> Result<Vec<u8>, Error> {
487        let created_at = opts.created_at;
488
489        let v4_bytes = rkyv::to_bytes::<RkyvError>(&self.v4).map_err(|_| Error::BadValue)?;
490        let v6_bytes = rkyv::to_bytes::<RkyvError>(&self.v6).map_err(|_| Error::BadValue)?;
491
492        // sections in ascending id order, each starting on a 16-byte boundary
493        let mut sections: Vec<(Entry, &[u8])> = Vec::new();
494        // both family sections are written even when a family holds nothing: an object
495        // whose shape depends on its contents makes every client carry the "which
496        // families are in this file" question. A reader still has to accept a missing
497        // family, because objects written before this rule exist.
498        sections.push((
499            Entry {
500                id: ID_V4,
501                kind: KIND_V4,
502                required: false,
503                len: v4_bytes.len() as u64,
504            },
505            &v4_bytes,
506        ));
507        sections.push((
508            Entry {
509                id: ID_V6,
510                kind: KIND_V6,
511                required: false,
512                len: v6_bytes.len() as u64,
513            },
514            &v6_bytes,
515        ));
516        // the counts section carries no data the tries need, so it stays optional: a
517        // reader that does not know it skips it, and one that does can report the entry
518        // count without decoding a value
519        let counts = header::Counts {
520            entries: self.len() as u64,
521            v4: self.v4.len() as u64,
522            v6: self.v6.len() as u64,
523        };
524        let counts_bytes = counts.encode();
525        sections.push((
526            Entry {
527                id: header::ID_STATS,
528                kind: header::KIND_STATS,
529                required: false,
530                len: header::STATS_LEN as u64,
531            },
532            &counts_bytes,
533        ));
534
535        let mut extras: Vec<&ExtraSection<'_>> = opts.extras.iter().collect();
536        extras.sort_by_key(|e| e.id);
537        for extra in extras {
538            if extra.id < header::FIRST_PROFILE_ID {
539                return Err(Error::BadHeader("extra section id is below 16"));
540            }
541            // the family kinds live at ids 2 and 3 and nowhere else, so an extra
542            // claiming one would build an object the reader refuses
543            if extra.kind == KIND_V4 || extra.kind == KIND_V6 {
544                return Err(Error::BadHeader("extra section uses a family kind"));
545            }
546            if sections.iter().any(|(e, _)| e.id == extra.id) {
547                return Err(Error::BadHeader("duplicate section id"));
548            }
549            sections.push((
550                Entry {
551                    id: extra.id,
552                    kind: extra.kind,
553                    required: extra.required,
554                    len: extra.bytes.len() as u64,
555                },
556                extra.bytes,
557            ));
558        }
559        sections.sort_by_key(|(e, _)| e.id);
560
561        let table_len = sections.len() * ENTRY_LEN;
562        let mut body: Vec<u8> = Vec::new();
563        let mut table: Vec<u8> = Vec::with_capacity(table_len);
564        for (entry, bytes) in &sections {
565            while !(HEADER_LEN + table_len + body.len()).is_multiple_of(16) {
566                body.push(0);
567            }
568            table.extend_from_slice(&entry.encode());
569            body.extend_from_slice(bytes);
570        }
571        let file_len = (HEADER_LEN + table_len + body.len()) as u64;
572
573        let mut type_id = [0u8; 32];
574        let id_bytes = T::TYPE_ID.as_bytes();
575        if id_bytes.is_empty() {
576            return Err(Error::BadHeader("type id is empty"));
577        }
578        if id_bytes.len() > 31 {
579            return Err(Error::BadHeader("type id is longer than 31 bytes"));
580        }
581        type_id[..id_bytes.len()].copy_from_slice(id_bytes);
582
583        let (flags, tree_id, generation, base_seq) = match opts.stream {
584            Some(s) => (FLAG_STREAM, s.tree_id, s.generation, s.base_seq),
585            None => (0, [0u8; 16], [0u8; 16], 0),
586        };
587        let (flags, window) = match opts.window {
588            Some((from, to)) => (flags | FLAG_WINDOW, [from, to]),
589            None => (flags, [0, 0]),
590        };
591
592        let mut head = Header {
593            flags,
594            tree_id,
595            generation,
596            base_seq,
597            type_id,
598            file_len,
599            section_count: sections.len() as u32,
600            section_table_len: table_len as u32,
601            window,
602            created_at,
603            content_id: [0u8; 32],
604        };
605        // the hash covers header[0..HASH_END]; content_id cannot hash itself, so
606        // it is filled in after the first encode
607        let mut prefix = head.encode();
608        let mut h = blake3::Hasher::new();
609        h.update(b"bgpkit-snap-v4\0");
610        h.update(&prefix[..header::HASH_END]);
611        h.update(&table);
612        for (_, bytes) in &sections {
613            h.update(bytes);
614        }
615        head.content_id = *h.finalize().as_bytes();
616
617        let mut out = Vec::with_capacity(file_len as usize);
618        prefix = head.encode();
619        // a writer must not produce an object its own reader rejects: the
620        // semantic rules live in Header::parse, so run them on the bytes here
621        Header::parse(&prefix)?;
622        out.extend_from_slice(&prefix);
623        out.extend_from_slice(&table);
624        out.extend_from_slice(&body);
625        debug_assert_eq!(out.len() as u64, file_len);
626        Ok(out)
627    }
628
629    /// Build the object and write it to `path` in one call, returning the number
630    /// of bytes written. The file is written beside the target and renamed, so a
631    /// reader never sees a half-written object.
632    pub fn finish_to(
633        self,
634        path: impl AsRef<std::path::Path>,
635        opts: &Opts<'_>,
636    ) -> Result<u64, Error> {
637        let bytes = self.finish(opts)?;
638        let path = path.as_ref();
639        // one temp name per call: two writers to one path must not share a temp
640        static NEXT_TEMP: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
641        let n = NEXT_TEMP.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
642        let tmp = path.with_extension(format!("snap.{}.{n}.tmp", std::process::id()));
643        let written = (|| -> std::io::Result<()> {
644            let mut f = std::fs::File::create(&tmp)?;
645            f.write_all(&bytes)?;
646            f.sync_all()
647        })();
648        if let Err(e) = written {
649            // the caller's existing object is still where it was; a temp file left
650            // here would sit beside it forever
651            let _ = std::fs::remove_file(&tmp);
652            return Err(Error::Io(e));
653        }
654        if let Err(e) = std::fs::rename(&tmp, path) {
655            // a complete object left beside the target would sit there forever
656            let _ = std::fs::remove_file(&tmp);
657            return Err(Error::Io(e));
658        }
659        if let Some(dir) = path.parent() {
660            let _ = std::fs::File::open(dir).and_then(|d| d.sync_all());
661        }
662        Ok(bytes.len() as u64)
663    }
664}
665
666// ---------------------------------------------------------------- merge
667
668/// How many entries an object records, without naming a value type.
669///
670/// The writer records this in section 4 precisely so the number survives a reader that
671/// does not know `T`: a trie's node layout depends on the value type, so counting from the
672/// bytes needs the type, while reading three `u64`s does not. An object written before the
673/// section existed answers `None`.
674pub fn recorded_counts(raw: &[u8]) -> Result<Option<header::Counts>, Error> {
675    let header = Header::parse(raw)?;
676    header.check_layout(raw.len())?;
677    let table_end = HEADER_LEN + header.section_table_len as usize;
678    let sections = parse_sections(raw, &header, table_end)?;
679    Ok(sections
680        .iter()
681        .find(|s| s.entry.id == header::ID_STATS)
682        .and_then(|s| header::Counts::parse(&raw[s.offset..s.offset + s.len])))
683}
684
685/// The section table and each section's range in the file.
686///
687/// Split out of the typed reader because nothing here needs the value type: the layout,
688/// the padding and the id/kind pairing are properties of the container, and a caller that
689/// only wants the counts should not have to name a value type to get them.
690fn parse_sections(raw: &[u8], header: &Header, table_end: usize) -> Result<Vec<SectionRef>, Error> {
691    let table = &raw[HEADER_LEN..table_end];
692    let mut sections: Vec<SectionRef> = Vec::new();
693    let mut cursor = table_end;
694    let mut prev_id = 0u16;
695    for i in 0..header.section_count as usize {
696        let entry = Entry::parse(&table[i * ENTRY_LEN..(i + 1) * ENTRY_LEN])?;
697        if entry.id <= prev_id && i > 0 {
698            return Err(Error::SectionOrder);
699        }
700        // every section starts at the next 16-byte boundary at or after the
701        // previous end, so the offset is computed and never stored
702        while !cursor.is_multiple_of(16) {
703            let Some(byte) = raw.get(cursor) else {
704                return Err(Error::Truncated {
705                    need: cursor + 1,
706                    have: raw.len(),
707                });
708            };
709            if *byte != 0 {
710                return Err(Error::BadSectionTable("padding is not zero"));
711            }
712            cursor += 1;
713        }
714        let len = entry.len as usize;
715        let Some(end) = cursor.checked_add(len) else {
716            return Err(Error::BadSectionTable("section length overflows"));
717        };
718        if end > raw.len() {
719            return Err(Error::Truncated {
720                need: end,
721                have: raw.len(),
722            });
723        }
724        sections.push(SectionRef {
725            entry,
726            offset: cursor,
727            len,
728        });
729        prev_id = entry.id;
730        cursor = end;
731    }
732    if cursor != raw.len() {
733        return Err(Error::BadSectionTable("sections do not end the file"));
734    }
735
736    for SectionRef { entry, len, .. } in &sections {
737        if entry.id == header::ID_STATS && *len != header::STATS_LEN {
738            return Err(Error::BadSectionTable(
739                "count section is not the fixed 32 bytes",
740            ));
741        }
742    }
743
744    // the family sections must be the kind they claim, which is the guard
745    // against reading an IPv4 archive as IPv6
746    for SectionRef { entry, .. } in &sections {
747        match entry.id {
748            ID_V4 if entry.kind != KIND_V4 => return Err(Error::BadSectionKind(entry.id)),
749            ID_V6 if entry.kind != KIND_V6 => return Err(Error::BadSectionKind(entry.id)),
750            header::ID_STATS if entry.kind != header::KIND_STATS => {
751                return Err(Error::BadSectionKind(entry.id))
752            }
753            _ => {}
754        }
755        // and the reverse: a family kind lives at its normative id, so an
756        // object cannot dodge a reader by putting it somewhere else
757        match entry.kind {
758            KIND_V4 if entry.id != ID_V4 => return Err(Error::BadSectionKind(entry.id)),
759            KIND_V6 if entry.id != ID_V6 => return Err(Error::BadSectionKind(entry.id)),
760            header::KIND_STATS if entry.id != header::ID_STATS => {
761                return Err(Error::BadSectionKind(entry.id))
762            }
763            _ => {}
764        }
765    }
766    Ok(sections)
767}
768
769impl<T: SnapValue> Snapshot<T> {
770    /// Merge several objects into one, later inputs winning where they hold the same
771    /// prefix.
772    ///
773    /// This is what a daily merge is: build one object per collector or per hour,
774    /// then fold them. "Overlap" means the same key: a later `/8` and an earlier
775    /// `/16` are different entries and both survive, because a merge cannot know
776    /// whether you meant one to cover the other.
777    ///
778    /// What a merge refuses, and why:
779    ///
780    /// - an input carrying a section of its own (id 16 or above). The values may
781    ///   point into that section, and a merged object that drops it would open
782    ///   cleanly while its handles pointed at nothing.
783    /// - `opts.extras`, for the same reason; a profile builds its own object.
784    ///
785    /// The stream coordinates are dropped: several streams are not one stream. A
786    /// window is claimed only when every input declares one and the intervals form a
787    /// continuous chain; disjoint inputs claim nothing, because a single `window`
788    /// is a validity claim over its whole span.
789    pub fn merge_last_wins(inputs: &[&Snapshot<T>], opts: &Opts<'_>) -> Result<Vec<u8>, Error>
790    where
791        T::Archived: rkyv::Deserialize<T, rkyv::api::high::HighDeserializer<RkyvError>>,
792    {
793        Self::merge_with(inputs, opts, |_, _, later| Some(later))
794    }
795
796    /// The same, with `combine` deciding a collision on the same prefix.
797    ///
798    /// `combine(prefix, earlier, later)` returns the value to keep, or `None` to
799    /// leave the prefix out of the result *of this fold*. That is not a withdrawal:
800    /// absence in a later input never reaches `combine`, and a third input holding
801    /// the prefix puts it back. A tombstone would have to be a value the caller
802    /// understands, which is what a value type is for.
803    ///
804    /// Both values are owned: a merge that has to look at two archived values and
805    /// then write one cannot avoid building at least one of them. The prefix is
806    /// passed because a resolution that depends on the key (interning a handle into
807    /// a rebuilt arena, say) cannot be written without it.
808    pub fn merge_with(
809        inputs: &[&Snapshot<T>],
810        opts: &Opts<'_>,
811        mut combine: impl FnMut(IpNet, T, T) -> Option<T>,
812    ) -> Result<Vec<u8>, Error>
813    where
814        T::Archived: rkyv::Deserialize<T, rkyv::api::high::HighDeserializer<RkyvError>>,
815    {
816        if !opts.extras.is_empty() {
817            return Err(Error::BadOpts(
818                "a merge cannot carry a caller section: merge refuses inputs that hold \
819                 sections of their own, so there is nothing to keep it consistent with",
820            ));
821        }
822        for snap in inputs {
823            for entry in snap.entries() {
824                if entry.id >= crate::header::FIRST_PROFILE_ID {
825                    return Err(Error::BadOpts(
826                        "a merge cannot take an object that carries its own section: the \
827                         values may point into it, and the merged object would not have it",
828                    ));
829                }
830            }
831        }
832
833        let mut merged: std::collections::HashMap<IpNet, T> = std::collections::HashMap::new();
834        for snap in inputs {
835            for (prefix, value) in snap.iter() {
836                let value =
837                    rkyv::deserialize::<T, RkyvError>(value).map_err(|_| Error::BadValue)?;
838                match merged.remove(&prefix) {
839                    None => {
840                        merged.insert(prefix, value);
841                    }
842                    Some(earlier) => {
843                        if let Some(next) = combine(prefix, earlier, value) {
844                            merged.insert(prefix, next);
845                        }
846                    }
847                }
848            }
849        }
850
851        let window = match opts.window {
852            Some(w) => Some(w),
853            None => Self::covers_one_span(inputs),
854        };
855
856        let mut writer = Writer::<T>::new();
857        writer.insert_many(merged)?;
858        let opts = Opts {
859            created_at: opts.created_at,
860            stream: None,
861            window,
862            extras: &[],
863        };
864        writer.finish(&opts)
865    }
866
867    /// The union of the inputs' windows, or `None` when they do not form one
868    /// continuous span.
869    ///
870    /// `window` says "this value is valid across this range", so two inputs covering
871    /// `(100,200)` and `(300,400)` cannot claim `(100,400)`: nobody observed the
872    /// hole between them.
873    fn covers_one_span(inputs: &[&Snapshot<T>]) -> Option<(i64, i64)> {
874        if inputs.is_empty() {
875            return None;
876        }
877        let mut spans = Vec::with_capacity(inputs.len());
878        for snap in inputs {
879            spans.push(snap.header().window()?);
880        }
881        spans.sort_unstable();
882        let (mut from, mut to) = spans[0];
883        for (a, b) in spans.into_iter().skip(1) {
884            if a > to {
885                return None;
886            }
887            to = to.max(b);
888            from = from.min(a);
889        }
890        Some((from, to))
891    }
892}
893
894// ---------------------------------------------------------------- owned view
895
896/// The same queries `Snapshot` answers, returning values you own.
897///
898/// `snap.lpm(..)` hands back `&T::Archived`, which is the point of the format but
899/// forces every caller to name the archived type. `snap.owned()` answers the same
900/// questions with `T`. Both views exist for every value-returning query, which is
901/// what a pair of `*_owned` methods got wrong: they covered two queries out of five.
902pub struct Owned<'a, T: SnapValue> {
903    snap: &'a Snapshot<T>,
904}
905
906impl<T: SnapValue> Snapshot<T> {
907    /// Every value-returning query, with the value deserialized.
908    pub fn owned(&self) -> Owned<'_, T> {
909        Owned { snap: self }
910    }
911}
912
913impl<T: SnapValue> Owned<'_, T>
914where
915    T::Archived: rkyv::Deserialize<T, rkyv::api::high::HighDeserializer<RkyvError>>,
916{
917    /// A value whose `Deserialize` refuses is an error, not an absence: returning
918    /// `None` would make `len()` disagree with `iter().count()` and hide a broken
919    /// value type behind a lookup miss.
920    fn decode(value: &T::Archived) -> Result<T, Error> {
921        rkyv::deserialize::<T, RkyvError>(value).map_err(|_| Error::BadValue)
922    }
923
924    /// How many prefixes the object holds.
925    ///
926    /// The table's section count is `entries().len()`; this is the same number
927    /// `Snapshot::len` gives, because an owned view holds no sections of its own.
928    pub fn len(&self) -> usize {
929        self.snap.len()
930    }
931
932    /// Whether the object holds no prefixes.
933    pub fn is_empty(&self) -> bool {
934        self.snap.is_empty()
935    }
936
937    /// The entry stored exactly at `prefix`.
938    pub fn get_exact(&self, prefix: IpNet) -> Result<Option<T>, Error> {
939        match self.snap.get_exact(prefix) {
940            Some(value) => Ok(Some(Self::decode(value)?)),
941            None => Ok(None),
942        }
943    }
944
945    /// The most specific stored entry covering `addr`.
946    pub fn search(&self, addr: std::net::IpAddr) -> Result<Option<(IpNet, T)>, Error> {
947        match self.snap.search(addr) {
948            Some((prefix, value)) => Ok(Some((prefix, Self::decode(value)?))),
949            None => Ok(None),
950        }
951    }
952
953    /// The most specific stored entry covering `prefix`.
954    pub fn lpm(&self, prefix: IpNet) -> Result<Option<(IpNet, T)>, Error> {
955        match self.snap.lpm(prefix) {
956            Some((prefix, value)) => Ok(Some((prefix, Self::decode(value)?))),
957            None => Ok(None),
958        }
959    }
960
961    /// The least specific stored entry covering `prefix`.
962    pub fn spm(&self, prefix: IpNet) -> Result<Option<(IpNet, T)>, Error> {
963        match self.snap.spm(prefix) {
964            Some((prefix, value)) => Ok(Some((prefix, Self::decode(value)?))),
965            None => Ok(None),
966        }
967    }
968
969    /// Every stored entry covering `prefix`, in trie order (least specific first).
970    pub fn cover(&self, prefix: IpNet) -> Result<Vec<(IpNet, T)>, Error> {
971        self.snap
972            .cover(prefix)
973            .into_iter()
974            .map(|(p, v)| Ok((p, Self::decode(v)?)))
975            .collect()
976    }
977
978    /// `prefix` itself when stored, plus every stored entry under it.
979    pub fn children(&self, prefix: IpNet) -> Result<Vec<(IpNet, T)>, Error> {
980        self.snap
981            .children(prefix)
982            .into_iter()
983            .map(|(p, v)| Ok((p, Self::decode(v)?)))
984            .collect()
985    }
986
987    /// The whole object, IPv4 then IPv6.
988    ///
989    /// Materialised, unlike the archived view: an owned value has to be built, so a
990    /// lazy iterator would only move that allocation into the loop body.
991    pub fn iter(&self) -> Result<Vec<(IpNet, T)>, Error> {
992        self.snap
993            .iter()
994            .map(|(p, v)| Ok((p, Self::decode(v)?)))
995            .collect()
996    }
997
998    /// The values alone, IPv4 then IPv6. Materialised, like `iter`.
999    pub fn values(&self) -> Result<Vec<T>, Error> {
1000        self.snap.values().map(|v| Self::decode(v)).collect()
1001    }
1002
1003    /// Entries at or after `prefix` in trie order, within `prefix`'s family.
1004    pub fn iter_from(&self, prefix: IpNet, inclusive: bool) -> Result<Vec<(IpNet, T)>, Error> {
1005        self.snap
1006            .iter_from(prefix, inclusive)
1007            .map(|(p, v)| Ok((p, Self::decode(v)?)))
1008            .collect()
1009    }
1010}
1011
1012// ---------------------------------------------------------------- reader
1013
1014/// One section as a validator sees it: the table row and where its bytes are.
1015#[derive(Debug, Clone, Copy)]
1016pub struct SectionRef {
1017    /// The table row: id, kind, required flag and body length.
1018    pub entry: Entry,
1019    /// Byte offset of the section body in the whole object.
1020    pub offset: usize,
1021    /// Length of the section body.
1022    pub len: usize,
1023}
1024
1025/// What a validator may inspect when an object is opened.
1026pub struct SnapshotView<'a> {
1027    /// The parsed header: type, identity, stream coordinates, coverage window.
1028    pub header: &'a Header,
1029    /// One row per section, in table order.
1030    pub sections: &'a [SectionRef],
1031    bytes: &'a [u8],
1032    table: &'a [u8],
1033}
1034
1035impl SnapshotView<'_> {
1036    /// The raw bytes of section `id`, exactly as written.
1037    pub fn section_bytes(&self, id: u16) -> Option<&[u8]> {
1038        self.sections
1039            .iter()
1040            .find(|s| s.entry.id == id)
1041            .map(|s| &self.bytes[s.offset..s.offset + s.len])
1042    }
1043
1044    /// The table entry for section `id`: its id, kind, required flag and length.
1045    /// `knows` only runs for required sections, so a profile that also wants to
1046    /// check the kind of an optional one does it here.
1047    pub fn entry(&self, id: u16) -> Option<&Entry> {
1048        self.sections
1049            .iter()
1050            .find(|s| s.entry.id == id)
1051            .map(|s| &s.entry)
1052    }
1053
1054    /// Raw table bytes, for a reader that only wants to enumerate sections.
1055    pub fn table(&self) -> &[u8] {
1056        self.table
1057    }
1058}
1059
1060/// Container-level verification that needs no value type: header, layout,
1061/// section table, trailing bytes and the content id. What it cannot check is
1062/// that a section body is a valid archive of its declared type; a reader with
1063/// the type does that on open.
1064pub fn verify_bytes(raw: &[u8]) -> Result<Header, Error> {
1065    let header = Header::parse(raw)?;
1066    header.check_layout(raw.len())?;
1067
1068    let table_start = HEADER_LEN;
1069    let table_end = table_start + header.section_table_len as usize;
1070    let table = &raw[table_start..table_end];
1071
1072    let mut cursor = table_end;
1073    let mut prev_id = 0u16;
1074    for i in 0..header.section_count as usize {
1075        let entry = Entry::parse(&table[i * ENTRY_LEN..(i + 1) * ENTRY_LEN])?;
1076        if entry.id <= prev_id && i > 0 {
1077            return Err(Error::SectionOrder);
1078        }
1079        match entry.id {
1080            ID_V4 if entry.kind != KIND_V4 => return Err(Error::BadSectionKind(entry.id)),
1081            ID_V6 if entry.kind != KIND_V6 => return Err(Error::BadSectionKind(entry.id)),
1082            _ => {}
1083        }
1084        match entry.kind {
1085            KIND_V4 if entry.id != ID_V4 => return Err(Error::BadSectionKind(entry.id)),
1086            KIND_V6 if entry.id != ID_V6 => return Err(Error::BadSectionKind(entry.id)),
1087            _ => {}
1088        }
1089        while !cursor.is_multiple_of(16) {
1090            // untrusted bytes: the alignment walk must not run off the end of the
1091            // file, which a crafted object can aim at
1092            let Some(byte) = raw.get(cursor) else {
1093                return Err(Error::Truncated {
1094                    need: cursor + 1,
1095                    have: raw.len(),
1096                });
1097            };
1098            if *byte != 0 {
1099                return Err(Error::BadSectionTable("padding is not zero"));
1100            }
1101            cursor += 1;
1102        }
1103        let Some(end) = cursor.checked_add(entry.len as usize) else {
1104            return Err(Error::BadSectionTable("section length overflows"));
1105        };
1106        if end > raw.len() {
1107            return Err(Error::Truncated {
1108                need: end,
1109                have: raw.len(),
1110            });
1111        }
1112        cursor = end;
1113        prev_id = entry.id;
1114    }
1115    if cursor != raw.len() {
1116        return Err(Error::BadSectionTable("sections do not end the file"));
1117    }
1118
1119    let mut h = blake3::Hasher::new();
1120    h.update(b"bgpkit-snap-v4\0");
1121    h.update(&raw[..header::HASH_END]);
1122    h.update(table);
1123    let mut cursor = table_end;
1124    for i in 0..header.section_count as usize {
1125        let entry = Entry::parse(&table[i * ENTRY_LEN..(i + 1) * ENTRY_LEN])?;
1126        while !cursor.is_multiple_of(16) {
1127            cursor += 1;
1128        }
1129        if cursor + entry.len as usize > raw.len() {
1130            return Err(Error::Truncated {
1131                need: cursor + entry.len as usize,
1132                have: raw.len(),
1133            });
1134        }
1135        h.update(&raw[cursor..cursor + entry.len as usize]);
1136        cursor += entry.len as usize;
1137    }
1138    if h.finalize().as_bytes() != &header.content_id {
1139        return Err(Error::ContentId);
1140    }
1141    Ok(header)
1142}
1143
1144/// Profile-side validation, run once at open before any value is handed out.
1145pub trait Validator {
1146    /// Does this validator implement the section behind `entry`? A required
1147    /// section that nobody knows is refused with its id.
1148    fn knows(&self, _entry: &Entry) -> bool {
1149        false
1150    }
1151
1152    /// Cross-section checks (for example handle ranges) run here.
1153    fn validate(&self, _view: &SnapshotView<'_>) -> Result<(), Error> {
1154        Ok(())
1155    }
1156}
1157
1158struct NoValidator;
1159impl Validator for NoValidator {}
1160
1161/// An immutable object, validated once and then queried in memory.
1162///
1163/// The bytes are owned, not mapped: `open` reads the file, checks the container and
1164/// both trie archives, and hands back something that answers lookups without further
1165/// parsing.
1166pub struct Snapshot<T: SnapValue> {
1167    bytes: AlignedVec,
1168    header: Header,
1169    sections: Vec<SectionRef>,
1170    table_range: (usize, usize),
1171    _t: std::marker::PhantomData<T>,
1172}
1173
1174impl<T: SnapValue> fmt::Debug for Snapshot<T> {
1175    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1176        f.debug_struct("Snapshot")
1177            .field("content_id", &self.header.content_id_hex())
1178            .field("sections", &self.sections.len())
1179            .finish()
1180    }
1181}
1182
1183impl<T: SnapValue> Snapshot<T> {
1184    /// Read and validate an object from a path.
1185    pub fn open(path: impl AsRef<std::path::Path>) -> Result<Self, Error>
1186    where
1187        T::Archived:
1188            for<'a> rkyv::bytecheck::CheckBytes<rkyv::api::high::HighValidator<'a, RkyvError>>,
1189    {
1190        Self::from_bytes(&std::fs::read(path.as_ref())?)
1191    }
1192
1193    /// The same, for a profile whose sections this reader implements.
1194    pub fn open_with(
1195        path: impl AsRef<std::path::Path>,
1196        validator: &dyn Validator,
1197    ) -> Result<Self, Error>
1198    where
1199        T::Archived:
1200            for<'a> rkyv::bytecheck::CheckBytes<rkyv::api::high::HighValidator<'a, RkyvError>>,
1201    {
1202        Self::from_bytes_with(&std::fs::read(path.as_ref())?, validator)
1203    }
1204
1205    /// Validate an object already in memory.
1206    pub fn from_bytes(raw: &[u8]) -> Result<Self, Error>
1207    where
1208        T::Archived:
1209            for<'a> rkyv::bytecheck::CheckBytes<rkyv::api::high::HighValidator<'a, RkyvError>>,
1210    {
1211        Self::from_bytes_with(raw, &NoValidator)
1212    }
1213
1214    /// The same, for a profile whose sections this reader implements.
1215    pub fn from_bytes_with(raw: &[u8], validator: &dyn Validator) -> Result<Self, Error>
1216    where
1217        T::Archived:
1218            for<'a> rkyv::bytecheck::CheckBytes<rkyv::api::high::HighValidator<'a, RkyvError>>,
1219    {
1220        let header = Header::parse(raw)?;
1221        header.check_layout(raw.len())?;
1222
1223        let mut aligned = AlignedVec::with_capacity(raw.len());
1224        aligned.extend_from_slice(raw);
1225
1226        let table_start = HEADER_LEN;
1227        let table_end = table_start + header.section_table_len as usize;
1228        let table = &aligned[table_start..table_end];
1229
1230        let sections = parse_sections(&aligned, &header, table_end)?;
1231
1232        // identity: header prefix, table, every section
1233        let mut h = blake3::Hasher::new();
1234        h.update(b"bgpkit-snap-v4\0");
1235        h.update(&aligned[..header::HASH_END]);
1236        h.update(table);
1237        for SectionRef {
1238            offset: off, len, ..
1239        } in &sections
1240        {
1241            h.update(&aligned[*off..*off + *len]);
1242        }
1243        if *h.finalize().as_bytes() != header.content_id {
1244            return Err(Error::ContentId);
1245        }
1246
1247        let declared = header.type_id_str();
1248        if declared != T::TYPE_ID {
1249            return Err(Error::TypeMismatch {
1250                expected: T::TYPE_ID.to_string(),
1251                found: declared,
1252            });
1253        }
1254
1255        let snap = Snapshot {
1256            bytes: aligned,
1257            header,
1258            sections,
1259            table_range: (table_start, table_end),
1260            _t: std::marker::PhantomData,
1261        };
1262
1263        let view = snap.view();
1264        for SectionRef { entry, .. } in &snap.sections {
1265            let known = matches!(entry.id, ID_V4 | ID_V6 | header::ID_STATS);
1266            if entry.required && !known && !validator.knows(entry) {
1267                return Err(Error::UnknownRequiredSection(entry.id));
1268            }
1269        }
1270        snap.validate_archives()?;
1271        validator.validate(&view)?;
1272        Ok(snap)
1273    }
1274
1275    /// The table bytes, for a reader that wants to list sections without
1276    /// touching the body.
1277    pub fn table_bytes(&self) -> &[u8] {
1278        &self.bytes[self.table_range.0..self.table_range.1]
1279    }
1280
1281    /// The section table, in file order.
1282    pub fn entries(&self) -> Vec<Entry> {
1283        self.sections.iter().map(|s| s.entry).collect()
1284    }
1285
1286    /// The parsed header, including the claims `open` verified.
1287    pub fn header(&self) -> &Header {
1288        &self.header
1289    }
1290
1291    /// The content id as hex: what names this object's content, not its provenance.
1292    pub fn content_id(&self) -> String {
1293        self.header.content_id_hex()
1294    }
1295
1296    /// The raw bytes of a section, exactly as written.
1297    pub fn section_bytes(&self, id: u16) -> Option<&[u8]> {
1298        self.sections
1299            .iter()
1300            .find(|s| s.entry.id == id)
1301            .map(|s| &self.bytes[s.offset..s.offset + s.len])
1302    }
1303
1304    /// What a `Validator` is handed: the header, the section table and the raw
1305    /// bytes, after the container and both trie archives have been checked.
1306    pub fn view(&self) -> SnapshotView<'_> {
1307        SnapshotView {
1308            header: &self.header,
1309            sections: &self.sections,
1310            bytes: &self.bytes,
1311            table: &self.bytes[self.table_range.0..self.table_range.1],
1312        }
1313    }
1314
1315    fn validate_archives(&self) -> Result<(), Error>
1316    where
1317        T::Archived:
1318            for<'a> rkyv::bytecheck::CheckBytes<rkyv::api::high::HighValidator<'a, RkyvError>>,
1319    {
1320        for SectionRef {
1321            entry,
1322            offset: off,
1323            len,
1324        } in &self.sections
1325        {
1326            let slice = &self.bytes[*off..*off + *len];
1327            match entry.id {
1328                ID_V4 => {
1329                    rkyv::access::<ArchivedPrefixMap<Ipv4Net, T>, RkyvError>(slice)
1330                        .map_err(|_| Error::BadArchive(ID_V4))?;
1331                }
1332                ID_V6 => {
1333                    rkyv::access::<ArchivedPrefixMap<Ipv6Net, T>, RkyvError>(slice)
1334                        .map_err(|_| Error::BadArchive(ID_V6))?;
1335                }
1336                _ => {}
1337            }
1338        }
1339        Ok(())
1340    }
1341
1342    /// The IPv4 trie, if the object has one.
1343    ///
1344    /// # Safety of the unchecked access
1345    ///
1346    /// The bytes were checked by `validate_archives` during `from_bytes`, and this
1347    /// method is only reachable through a value that construction produced. Doing the
1348    /// checked access here instead would re-validate the whole archive on every
1349    /// lookup.
1350    #[allow(unsafe_code)]
1351    pub fn v4(&self) -> Option<&ArchivedPrefixMap<Ipv4Net, T>> {
1352        // SAFETY: see the doc comment; the archive was byte-checked at open.
1353        self.section_bytes(ID_V4)
1354            .map(|s| unsafe { rkyv::access_unchecked::<ArchivedPrefixMap<Ipv4Net, T>>(s) })
1355    }
1356
1357    /// The IPv6 trie, if the object has one. Same unchecked access as `v4`.
1358    #[allow(unsafe_code)]
1359    pub fn v6(&self) -> Option<&ArchivedPrefixMap<Ipv6Net, T>> {
1360        // SAFETY: see `v4`; the archive was byte-checked at open.
1361        self.section_bytes(ID_V6)
1362            .map(|s| unsafe { rkyv::access_unchecked::<ArchivedPrefixMap<Ipv6Net, T>>(s) })
1363    }
1364
1365    /// How many prefixes the object holds.
1366    pub fn len(&self) -> usize {
1367        self.v4().map(|m| m.len()).unwrap_or(0) + self.v6().map(|m| m.len()).unwrap_or(0)
1368    }
1369
1370    /// Whether the object holds nothing.
1371    pub fn is_empty(&self) -> bool {
1372        self.len() == 0
1373    }
1374
1375    /// Longest-prefix match for a single address.
1376    pub fn search(&self, addr: std::net::IpAddr) -> Option<(IpNet, &T::Archived)> {
1377        match addr {
1378            std::net::IpAddr::V4(a) => {
1379                let p = Ipv4Net::new(a, 32).ok()?;
1380                let map = self.v4()?;
1381                let (lpm, value) = map.get_lpm(&p)?;
1382                Some((IpNet::V4(lpm), value))
1383            }
1384            std::net::IpAddr::V6(a) => {
1385                let p = Ipv6Net::new(a, 128).ok()?;
1386                let map = self.v6()?;
1387                let (lpm, value) = map.get_lpm(&p)?;
1388                Some((IpNet::V6(lpm), value))
1389            }
1390        }
1391    }
1392
1393    /// Longest prefix that covers `prefix`, and its value.
1394    ///
1395    /// `prefix` is a prefix, not an address: for one address use `search`, which
1396    /// builds the `/32` or `/128` for you.
1397    pub fn lpm(&self, prefix: IpNet) -> Option<(IpNet, &T::Archived)> {
1398        match prefix {
1399            IpNet::V4(p) => {
1400                let map = self.v4()?;
1401                let (lpm, value) = map.get_lpm(&p)?;
1402                Some((IpNet::V4(lpm), value))
1403            }
1404            IpNet::V6(p) => {
1405                let map = self.v6()?;
1406                let (lpm, value) = map.get_lpm(&p)?;
1407                Some((IpNet::V6(lpm), value))
1408            }
1409        }
1410    }
1411
1412    // ---- the read side of prefix_trie, with IpNet keys ----
1413    //
1414    // A snapshot holds two tries, one per family. These forward the map's own
1415    // read API so a caller does not have to match on the family and hold two
1416    // code paths for every query.
1417
1418    /// The value stored exactly at `prefix`, with no ancestor fallback.
1419    pub fn get_exact(&self, prefix: IpNet) -> Option<&T::Archived> {
1420        match prefix {
1421            IpNet::V4(p) => self.v4().and_then(|m| m.get(&p)),
1422            IpNet::V6(p) => self.v6().and_then(|m| m.get(&p)),
1423        }
1424    }
1425
1426    /// Whether an entry is stored exactly at `prefix`.
1427    pub fn contains_key(&self, prefix: IpNet) -> bool {
1428        match prefix {
1429            IpNet::V4(p) => self.v4().is_some_and(|m| m.contains_key(&p)),
1430            IpNet::V6(p) => self.v6().is_some_and(|m| m.contains_key(&p)),
1431        }
1432    }
1433
1434    /// The least specific stored entry covering `prefix`.
1435    pub fn spm(&self, prefix: IpNet) -> Option<(IpNet, &T::Archived)> {
1436        match prefix {
1437            IpNet::V4(p) => self
1438                .v4()
1439                .and_then(|m| m.get_spm(&p))
1440                .map(|(k, v)| (IpNet::V4(k), v)),
1441            IpNet::V6(p) => self
1442                .v6()
1443                .and_then(|m| m.get_spm(&p))
1444                .map(|(k, v)| (IpNet::V6(k), v)),
1445        }
1446    }
1447
1448    /// Whether any stored entry covers `prefix`.
1449    pub fn is_covered(&self, prefix: IpNet) -> bool {
1450        match prefix {
1451            IpNet::V4(p) => self.v4().is_some_and(|m| m.is_covered(&p)),
1452            IpNet::V6(p) => self.v6().is_some_and(|m| m.is_covered(&p)),
1453        }
1454    }
1455
1456    /// Whether `prefix` is covered by an aggregate entry, that is a stored
1457    /// prefix carrying its whole subtree.
1458    pub fn is_covered_in_aggregate(&self, prefix: IpNet) -> bool {
1459        match prefix {
1460            IpNet::V4(p) => self.v4().is_some_and(|m| m.is_covered_in_aggregate(&p)),
1461            IpNet::V6(p) => self.v6().is_some_and(|m| m.is_covered_in_aggregate(&p)),
1462        }
1463    }
1464
1465    /// Every entry, IPv4 first then IPv6, in trie order.
1466    pub fn iter(&self) -> Box<dyn Iterator<Item = (IpNet, &T::Archived)> + '_> {
1467        let v4 = self
1468            .v4()
1469            .into_iter()
1470            .flat_map(|m| m.iter())
1471            .map(|(p, v)| (IpNet::V4(p), v));
1472        let v6 = self
1473            .v6()
1474            .into_iter()
1475            .flat_map(|m| m.iter())
1476            .map(|(p, v)| (IpNet::V6(p), v));
1477        Box::new(v4.chain(v6))
1478    }
1479
1480    /// Every key, IPv4 first then IPv6.
1481    pub fn keys(&self) -> Box<dyn Iterator<Item = IpNet> + '_> {
1482        Box::new(self.iter().map(|(p, _)| p))
1483    }
1484
1485    /// Every entry at or after `prefix` in trie order, within `prefix`'s family;
1486    /// an IPv4 start does not continue into the IPv6 trie. Use `iter()` for both.
1487    pub fn iter_from(
1488        &self,
1489        prefix: IpNet,
1490        inclusive: bool,
1491    ) -> Box<dyn Iterator<Item = (IpNet, &T::Archived)> + '_> {
1492        match prefix {
1493            IpNet::V4(p) => {
1494                let it = self
1495                    .v4()
1496                    .into_iter()
1497                    .flat_map(move |m| m.iter_from(&p, inclusive))
1498                    .map(|(k, v)| (IpNet::V4(k), v));
1499                Box::new(it)
1500            }
1501            IpNet::V6(p) => {
1502                let it = self
1503                    .v6()
1504                    .into_iter()
1505                    .flat_map(move |m| m.iter_from(&p, inclusive))
1506                    .map(|(k, v)| (IpNet::V6(k), v));
1507                Box::new(it)
1508            }
1509        }
1510    }
1511
1512    /// Every value, IPv4 first then IPv6.
1513    pub fn values(&self) -> Box<dyn Iterator<Item = &T::Archived> + '_> {
1514        let v4 = self.v4().into_iter().flat_map(|m| m.values());
1515        let v6 = self.v6().into_iter().flat_map(|m| m.values());
1516        Box::new(v4.chain(v6))
1517    }
1518
1519    /// How many addresses the entries cover, per family.
1520    pub fn address_counts(&self) -> AddressCounts {
1521        let count = |m: Option<Option<u128>>| match m {
1522            None => Count::NoEntries,
1523            Some(None) => Count::All,
1524            Some(Some(n)) => Count::Exact(n),
1525        };
1526        AddressCounts {
1527            v4: count(self.v4().map(|m| m.address_count().map(u128::from))),
1528            v6: count(self.v6().map(|m| m.address_count())),
1529        }
1530    }
1531
1532    /// The prefixes that cover `prefix`, each with its value.
1533    pub fn cover(&self, prefix: IpNet) -> Vec<(IpNet, &T::Archived)> {
1534        match prefix {
1535            IpNet::V4(p) => self
1536                .v4()
1537                .map(|m| m.cover(&p).map(|(k, v)| (IpNet::V4(k), v)).collect())
1538                .unwrap_or_default(),
1539            IpNet::V6(p) => self
1540                .v6()
1541                .map(|m| m.cover(&p).map(|(k, v)| (IpNet::V6(k), v)).collect())
1542                .unwrap_or_default(),
1543        }
1544    }
1545
1546    /// The prefix itself when it is stored, plus everything under it, in trie
1547    /// order. A query for a block that is not stored returns only what is under
1548    /// it, never a sibling.
1549    ///
1550    /// The query prefix is read as its network address, and every key returned is a
1551    /// key the object contains: a query for `10.1.2.3/16` answers for `10.1.0.0/16`
1552    /// and returns that key, never the caller's spelling of it.
1553    pub fn children(&self, prefix: IpNet) -> Vec<(IpNet, &T::Archived)> {
1554        let mut out: Vec<(IpNet, &T::Archived)> = Vec::new();
1555        match prefix {
1556            IpNet::V4(p) => {
1557                let p = p.trunc();
1558                let Some(map) = self.v4() else { return out };
1559                if let Some((k, v)) = map.get_key_value(&p) {
1560                    out.push((IpNet::V4(k), v));
1561                }
1562                if let Some(view) = map.view_at(&p) {
1563                    for (k, v) in view.iter() {
1564                        if k != p {
1565                            out.push((IpNet::V4(k), v));
1566                        }
1567                    }
1568                }
1569            }
1570            IpNet::V6(p) => {
1571                let p = p.trunc();
1572                let Some(map) = self.v6() else { return out };
1573                if let Some((k, v)) = map.get_key_value(&p) {
1574                    out.push((IpNet::V6(k), v));
1575                }
1576                if let Some(view) = map.view_at(&p) {
1577                    for (k, v) in view.iter() {
1578                        if k != p {
1579                            out.push((IpNet::V6(k), v));
1580                        }
1581                    }
1582                }
1583            }
1584        }
1585        out
1586    }
1587}