domain-status 0.2.1

Concurrent URL status checker that captures comprehensive metadata in SQLite.
Documentation
//! Database models and types.
//!
//! This module defines the data structures used for database operations:
//! - `UrlRecord` - Main URL status record
//! - `PersistedUrlRecord` - Complete record with all satellite data (despite the name, records are NOT batched - they're written immediately)
//!
//! All models use `Option<T>` for nullable fields to match `SQLite`'s type system.

use chrono::NaiveDateTime;

use crate::error_handling::ErrorType;

/// Represents a complete URL status record for database insertion.
///
/// Contains all data extracted from a URL check including HTTP response details,
/// HTML metadata, DNS information, TLS certificate data, and security headers.
///
/// # Database Schema
///
/// This struct maps directly to the `url_status` table. The `timestamp` field
/// is stored as milliseconds since Unix epoch. All string fields that can be
/// empty are stored as `TEXT NOT NULL` with empty strings as fallback.
#[derive(Debug)]
pub struct UrlRecord {
    /// The original domain/URL before any redirects
    pub initial_domain: String,
    /// The final domain/URL after following redirects
    pub final_domain: String,
    /// Original request URL (scheme/host/path/query) before redirects
    pub initial_url: Option<String>,
    /// Final URL after redirects (scheme/host/path/query)
    pub final_url: Option<String>,
    /// The resolved IP address of the final domain
    pub ip_address: String,
    /// Reverse DNS lookup result for the IP address
    pub reverse_dns_name: Option<String>,
    /// HTTP status code (e.g., 200, 404, 500)
    pub status: u16,
    /// Human-readable status description
    pub status_desc: String,
    /// Response time in seconds
    pub response_time: f64,
    /// HTML page title
    pub title: String,
    /// HTML meta description
    pub description: Option<String>,
    /// Content of `<meta name="robots">` when present
    pub meta_robots: Option<String>,
    /// TLS version
    pub tls_version: Option<crate::models::TlsVersion>,
    /// SSL certificate subject (e.g., "CN=example.com")
    pub ssl_cert_subject: Option<String>,
    /// SSL certificate issuer
    pub ssl_cert_issuer: Option<String>,
    /// SSL certificate valid from date
    pub ssl_cert_valid_from: Option<NaiveDateTime>,
    /// SSL certificate valid to date
    pub ssl_cert_valid_to: Option<NaiveDateTime>,
    /// Timestamp of the check (milliseconds since Unix epoch)
    pub timestamp: i64,
    /// JSON array of DNS nameservers
    pub nameservers: Option<String>,
    /// JSON array of TXT DNS records
    pub txt_records: Option<String>,
    /// JSON array of MX DNS records
    pub mx_records: Option<String>,
    /// SPF record content
    pub spf_record: Option<String>,
    /// DMARC record content
    pub dmarc_record: Option<String>,
    /// TLS cipher suite used
    pub cipher_suite: Option<String>,
    /// TLS key exchange algorithm
    pub key_algorithm: Option<crate::models::KeyAlgorithm>,
    /// ID of the scan run this record belongs to
    pub run_id: Option<String>,
    /// SHA-256 hash of the response body
    pub body_sha256: Option<String>,
    /// Whether the response body was truncated at the scan size cap
    pub body_truncated: bool,
    /// First-party external `<script src>` candidates when script scanning is on
    pub external_scripts_eligible: u32,
    /// External scripts successfully fetched and scanned for secrets
    pub external_scripts_scanned: u32,
    /// Response body length in bytes
    pub content_length: Option<i64>,
    /// HTTP protocol version (e.g., "HTTP/1.1", "HTTP/2")
    pub http_version: Option<String>,
    /// Content-Type header value
    pub content_type: Option<String>,
    /// Canonical URL from `<link rel="canonical">`
    pub canonical_url: Option<String>,
    /// SHA-256 fingerprint of the leaf TLS certificate DER
    pub cert_fingerprint_sha256: Option<String>,
    /// Certificate serial number
    pub cert_serial_number: Option<String>,
    /// Whether the certificate is self-signed (issuer == subject)
    pub cert_is_self_signed: Option<bool>,
    /// Whether the certificate is a wildcard cert (`*.example.com`)
    pub cert_is_wildcard: Option<bool>,
    /// Whether the cert doesn't match the requested domain
    pub cert_is_mismatched: Option<bool>,
    /// Meta refresh redirect URL from `<meta http-equiv="refresh">`
    pub meta_refresh_url: Option<String>,
    /// Parsed HSTS max-age (seconds), when Strict-Transport-Security present
    pub hsts_max_age: Option<i64>,
    /// HSTS includeSubDomains directive present
    pub hsts_include_subdomains: Option<bool>,
    /// HSTS preload directive present
    pub hsts_preload: Option<bool>,
    /// MTA-STS TXT record (`_mta-sts.<domain>`)
    pub mta_sts_record: Option<String>,
    /// TLS-RPT TXT record (`_smtp._tls.<domain>`)
    pub tls_rpt_record: Option<String>,
    /// BIMI TXT record (`default._bimi.<domain>`)
    pub bimi_record: Option<String>,
    /// Best-effort CDN/edge provider slug from headers/DNS
    pub cdn_provider: Option<String>,
}

impl UrlRecord {
    /// Minimal `UrlRecord` for unit/integration tests.
    ///
    /// Callers override fields they care about (`initial_domain`, `run_id`, etc.)
    /// instead of re-listing every schema column when columns are added.
    #[must_use]
    pub fn test_default() -> Self {
        Self {
            initial_domain: "example.com".to_string(),
            final_domain: "example.com".to_string(),
            initial_url: Some("https://example.com/".to_string()),
            final_url: Some("https://example.com/".to_string()),
            ip_address: "93.184.216.34".to_string(),
            reverse_dns_name: None,
            status: 200,
            status_desc: "OK".to_string(),
            response_time: 0.1,
            title: "Example".to_string(),
            description: None,
            meta_robots: None,
            tls_version: None,
            ssl_cert_subject: None,
            ssl_cert_issuer: None,
            ssl_cert_valid_from: None,
            ssl_cert_valid_to: None,
            timestamp: 1_700_000_000_000,
            nameservers: None,
            txt_records: None,
            mx_records: None,
            spf_record: None,
            dmarc_record: None,
            cipher_suite: None,
            key_algorithm: None,
            run_id: None,
            body_sha256: None,
            body_truncated: false,
            external_scripts_eligible: 0,
            external_scripts_scanned: 0,
            content_length: None,
            http_version: None,
            content_type: Some("text/html".to_string()),
            canonical_url: None,
            cert_fingerprint_sha256: None,
            cert_serial_number: None,
            cert_is_self_signed: None,
            cert_is_wildcard: None,
            cert_is_mismatched: None,
            meta_refresh_url: None,
            hsts_max_age: None,
            hsts_include_subdomains: None,
            hsts_preload: None,
            mta_sts_record: None,
            tls_rpt_record: None,
            bimi_record: None,
            cdn_provider: None,
        }
    }
}

/// Represents a failed URL processing attempt for database insertion.
///
/// Contains information about why a URL processing failed, including error type,
/// error message, and any context that was available before the failure
/// (e.g., redirect chain, response headers).
///
/// # Database Schema
///
/// This struct maps to the `url_failures` table. The `timestamp` field
/// is stored as milliseconds since Unix epoch.
pub struct UrlFailureRecord {
    pub url: String,
    pub final_url: Option<String>,    // URL after redirects (if any)
    pub domain: String,               // Initial domain extracted from original URL
    pub final_domain: Option<String>, // Final domain after redirects (if any)
    pub error_type: ErrorType,        // Categorized error type
    pub error_message: String,        // Full error message
    pub http_status: Option<u16>,     // HTTP status code if available (e.g., 403, 500)
    pub retry_count: u32,             // Number of retry attempts made
    pub elapsed_time_seconds: Option<f64>, // Time spent before failure
    pub timestamp: i64,               // When the failure occurred
    pub run_id: Option<String>,       // Foreign key to runs.run_id
    pub redirect_chain: Vec<String>,  // Redirect chain before failure (if any)
    pub response_headers: Vec<(String, String)>, // Response headers received (if any)
}

/// Represents a partial failure (DNS/TLS error that didn't prevent URL processing).
///
/// These are errors that occurred during supplementary data collection (DNS, TLS)
/// but didn't prevent the URL from being successfully processed. The URL was
/// processed, but some optional data is missing.
///
/// # Database Schema
///
/// This struct maps to the `url_partial_failures` table. The `timestamp` field
/// is stored as milliseconds since Unix epoch.
#[derive(Debug, Clone)]
pub struct UrlPartialFailureRecord {
    pub url_status_id: i64,     // Foreign key to url_status.id
    pub error_type: ErrorType,  // Categorized error type (DNS/TLS errors)
    pub error_message: String,  // Full error message
    pub timestamp: i64,         // When the failure occurred
    pub run_id: Option<String>, // Foreign key to runs.run_id
}