xarf/lib.rs
1//! # xarf — XARF v4 parser, validator, and generator
2//!
3//! The [eXtended Abuse Reporting Format](https://xarf.org/) (XARF) is a JSON
4//! schema for describing abuse incidents — spam, DDoS, phishing, compromised
5//! infrastructure, copyright violations, and so on. This crate is a Rust
6//! implementation of the v4 spec.
7//!
8//! ## Quick start
9//!
10//! ```rust,no_run
11//! use xarf::{parse, Contact, ReportBuilder, create_evidence};
12//! use serde_json::json;
13//!
14//! // Parse incoming JSON.
15//! let result = parse(r#"{"xarf_version": "4.2.0", ... }"#).unwrap();
16//! if result.errors.is_empty() {
17//! println!("category = {}", result.report.unwrap().category.as_str());
18//! }
19//!
20//! // Build a new report programmatically.
21//! let evidence = create_evidence("text/plain", b"log line");
22//! let result = ReportBuilder::new("messaging", "spam", "192.0.2.1")
23//! .reporter(Contact::new("Acme", "abuse@acme.example", "acme.example"))
24//! .sender(Contact::new("Acme", "abuse@acme.example", "acme.example"))
25//! .extra("protocol", json!("smtp"))
26//! .extra("smtp_from", json!("spam@bad.example"))
27//! .add_evidence(evidence)
28//! .build()
29//! .unwrap();
30//! ```
31//!
32//! ## Modules
33//!
34//! - [`model`] — the [`Report`], [`Contact`], [`Evidence`], and [`Category`]
35//! types that make up the typed view.
36//! - [`parser`] — [`parse`] and [`parse_value`] for ingesting JSON.
37//! - [`generator`] — [`ReportBuilder`], [`create_report`], [`create_evidence`]
38//! for emitting new reports.
39//! - [`validator`] — schema validation primitives behind the higher-level
40//! entry points.
41//! - [`v3_compat`] — automatic XARF v3 → v4 conversion.
42
43#![doc(html_root_url = "https://docs.rs/xarf-rs/0.1.2")]
44#![warn(missing_debug_implementations)]
45
46pub mod error;
47pub mod generator;
48mod hex;
49pub mod model;
50pub mod parser;
51pub mod schemas;
52pub mod v3_compat;
53pub mod validator;
54
55// ---------------------------------------------------------------------------
56// Public re-exports — the convenience API.
57// ---------------------------------------------------------------------------
58
59pub use error::{Result, ValidationError, ValidationInfo, ValidationWarning, XarfError};
60pub use generator::{
61 CreateReportOptions, EvidenceOptions, HashAlgorithm, ReportBuilder, SPEC_VERSION,
62 create_evidence, create_evidence_with_options, create_report,
63};
64pub use model::{Category, Contact, Evidence, Report};
65pub use parser::{ParseOptions, ParseResult, parse, parse_value, parse_with_options};
66pub use v3_compat::{convert_v3_to_v4, deprecation_warning, is_v3_report};
67pub use validator::{ValidateOptions, ValidationResult, quick_errors, validate};