Skip to main content

domain_status/
lib.rs

1#![recursion_limit = "256"]
2// Pedantic clippy: only allow genuinely noise-level lints.
3// items_after_statements: function-scoped `static LazyLock` is idiomatic Rust.
4// struct_field_names: _us/_ms suffixes on timing fields are intentional clarity.
5// similar_names: geoip_cc_b/geoip_cn_b etc are clear in context.
6// needless_continue: used intentionally for clarity in drain loop.
7#![allow(
8    clippy::items_after_statements,
9    clippy::struct_field_names,
10    clippy::similar_names,
11    clippy::needless_continue
12)]
13//! `domain_status` library: core URL scanning functionality
14//!
15//! This library provides high-level APIs for scanning URLs and capturing comprehensive
16//! metadata including HTTP status, TLS certificates, DNS information, technology
17//! fingerprints, and more.
18//!
19//! # Example
20//!
21//! ```no_run
22//! use domain_status::{Config, run_scan};
23//! use tokio;
24//!
25//! # #[tokio::main]
26//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
27//! let config = Config {
28//!     file: std::path::PathBuf::from("urls.txt"),
29//!     max_concurrency: 50,
30//!     rate_limit_rps: 20,
31//!     ..Default::default()
32//! };
33//!
34//! let report = run_scan(config).await?;
35//! println!("Processed {} URLs: {} succeeded, {} failed",
36//!          report.total_urls, report.successful, report.failed);
37//! # Ok(())
38//! # }
39//! ```
40//!
41//! # Requirements
42//!
43//! This library requires a Tokio runtime. Use `#[tokio::main]` in your application
44//! or ensure you're calling library functions within an async context.
45//!
46//! # Stability and API guarantees
47//!
48//! - **Stable:** Exit codes (see project docs), [`Config`] validation rules, and public function signatures and types follow `SemVer`.
49//! - **Primary embed API:** [`Config`] + [`run_scan`] + [`export`] + [`summary`] (+ typed errors / exit codes).
50//! - **Advanced (may narrow further in 0.x):** [`whois`], [`GeoIpService`], [`cli`].
51//! - **Crate-private:** initialization helpers, most config constants/header names, fetch/fingerprint/storage internals.
52//! - **May change:** Exact wording of error messages, the internal error chain and downcasting behavior, and default config values (e.g. timeouts, limits) may change in patch or minor releases to improve safety or diagnostics.
53
54#![deny(
55    clippy::enum_glob_use,
56    missing_debug_implementations,
57    missing_docs,
58    unsafe_code
59)]
60
61mod app;
62mod cache_paths;
63pub mod cli;
64mod clock;
65pub mod config;
66mod const_str;
67mod dns;
68mod domain;
69mod error_handling;
70pub mod exit_codes;
71pub mod export;
72mod fetch;
73mod fingerprint;
74mod geoip;
75pub(crate) mod initialization;
76mod models;
77mod parse;
78mod run;
79mod runtime_metrics;
80mod security;
81mod sql;
82mod status_server;
83mod storage;
84pub mod summary;
85mod tls;
86mod user_agent;
87mod utils;
88pub mod whois;
89
90// Re-export public API
91pub use cli::evaluate_exit_code;
92pub use config::{Config, FailOn, LogFormat, LogLevel, ScanDependencyOverrides};
93pub use error_handling::{
94    log_error_chain, DatabaseError, ErrorExt, FingerprintError, MigrationError, ReqwestErrorExt,
95    RunScanError, StartupError,
96};
97// Reachable from `StartupError::StatusServer(_)` — surface the type so callers
98// matching on that variant can name it.
99pub use exit_codes::{EXIT_NO_URLS_PCT, EXIT_POLICY_FAILURE, EXIT_RUNTIME_ERROR, EXIT_SUCCESS};
100pub use geoip::GeoIpService;
101pub use models::{KeyAlgorithm, TlsVersion};
102pub use run::{run_scan, ScanReport};
103pub use status_server::StatusServerLifecycleError;
104pub use storage::{
105    init_db_pool_with_path, query_run_history, run_migrations, RunSummary, UrlRecord,
106};
107pub use summary::{format_scan_summary, query_scan_summary, ScanSummary, SummaryOptions};
108// Low-level insert helpers used by the crate's own integration tests under
109// `tests/`. These are NOT a stable public API — they expose internals of the
110// SQLite write pipeline, with all the surface that requires (column lists,
111// FK ordering, retry semantics). Gated behind the `test-utils` feature so the
112// default published crate doesn't include them in its semver surface.
113//
114// Enable with `cargo test --features test-utils` (already part of `just test`,
115// `just ci`, and the CI workflow's `--all-features` invocation).
116#[cfg(feature = "test-utils")]
117pub use storage::insert::url::{insert_url_record, UrlRecordInsertParams};
118#[cfg(feature = "test-utils")]
119pub use whois::seed_whois_cache;
120
121pub use utils::print_io_error_hint_if_applicable;
122pub use whois::{lookup_whois, WhoisResult};