netindex 2.0.1

Immutable IP-range and ASN indexes with borrowed payloads
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

#![doc = include_str!("../README.md")]

use std::{collections::TryReserveError, io};

pub use builder::Builder;
pub use coverage::{Coverage, CoverageRouter};
#[cfg(feature = "external-sort")]
pub use external::{ExternalBuildStats, ExternalBuilder, ExternalOptions};
pub use reader::{Match, Reader};
pub use reader_set::ReaderSet;
pub use target::Target;

mod builder;
#[cfg(feature = "codec")]
pub mod codec;
mod coverage;
#[cfg(feature = "external-sort")]
mod external;
mod layout;
#[cfg(feature = "mmdb")]
pub mod mmdb;
mod packed;
mod payload;
mod reader;
mod reader_set;
mod routing;
mod search;
mod target;
#[cfg(feature = "shared-values")]
pub mod values;

/// A validated file-backed reader; requires the mmap feature.
#[cfg(feature = "mmap")]
pub type MappedReader = Reader<memmap2::Mmap>;

/// Failures in index, shared-value, and codec operations.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
    /// A configured resource ceiling was exceeded.
    #[error("resource limit exceeded: {0}")]
    Limit(&'static str),
    /// An input target or encoded field violates the format.
    #[error("invalid {0}")]
    Invalid(&'static str),
    /// A codec field has an invalid position, kind, or supplied value.
    #[cfg(feature = "codec")]
    #[error("invalid codec field {position}: {reason}")]
    CodecField {
        /// Zero-based position in the caller's schema.
        position: usize,
        /// The violated field requirement.
        reason: &'static str,
    },
    /// A typed string pool contains invalid UTF-8.
    #[cfg(feature = "shared-values")]
    #[error("invalid shared string UTF-8")]
    Utf8(#[from] std::str::Utf8Error),
    /// An on-disk version is not supported.
    #[error("unsupported index version {0}")]
    Version(u32),
    /// A memory reservation failed.
    #[error("failed to reserve index memory")]
    Allocation(#[from] TryReserveError),
    /// Reserving an index or shared-value deduplication table failed.
    #[error("failed to reserve deduplication table memory")]
    HashAllocation(#[from] hashbrown::TryReserveError),
    /// Reading file metadata or creating a read-only mapping failed.
    #[cfg(feature = "mmap")]
    #[error("failed to {operation} index file")]
    MappingIo {
        /// Filesystem operation that failed.
        operation: &'static str,
        /// Underlying filesystem cause.
        #[source]
        error: io::Error,
    },
    /// I/O on the caller's encoded artifact failed.
    #[error("artifact I/O failed")]
    Io(#[from] io::Error),
    /// Creating, reading, writing, or cleaning up temporary build files failed.
    #[cfg(feature = "external-sort")]
    #[error("failed to {operation} temporary index data")]
    TemporaryIo {
        /// Temporary-file operation that failed.
        operation: &'static str,
        /// Underlying filesystem cause.
        #[source]
        error: io::Error,
    },
}

/// Resource limits for building and opening an index.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Limits {
    /// Maximum assertions (including duplicates), unique pool values, or codec fields.
    pub records: usize,
    /// Maximum complete artifact bytes, including metadata and payloads.
    pub bytes: usize,
}

impl Default for Limits {
    fn default() -> Self {
        Self {
            records: 1_000_000,
            bytes: 128 * 1024 * 1024,
        }
    }
}