use std::io::{BufRead, Write};
use serde::{Deserialize, Serialize};
use crate::format::ENGINE_NAME;
#[doc(inline)]
pub use super::JOURNAL_VERSION;
#[non_exhaustive]
#[derive(Debug, thiserror::Error)]
pub enum JournalError {
#[error("no journal header: this is not a file {ENGINE_NAME} wrote, or it is empty")]
NotAJournal,
#[error(
"journal version {found} is newer than this build understands ({understood}); \
resume it with the engine that wrote it"
)]
VersionTooNew {
found: u32,
understood: u32,
},
#[error("journal line {line}: {message}")]
Malformed {
line: u64,
message: String,
},
#[error("journal line {line}: unknown {field} '{value}'")]
UnknownValue {
line: u64,
field: &'static str,
value: String,
},
#[error("journal i/o: {0}")]
Io(#[from] std::io::Error),
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Header {
pub journal_version: u32,
pub engine: String,
pub engine_version: String,
}
impl Header {
pub fn current() -> Self {
Self {
journal_version: JOURNAL_VERSION,
engine: ENGINE_NAME.to_string(),
engine_version: env!("CARGO_PKG_VERSION").to_string(),
}
}
}
#[derive(Debug)]
pub struct Writer<W: Write> {
inner: W,
}
impl<W: Write> Writer<W> {
pub fn create(mut inner: W) -> Result<Self, JournalError> {
writeln!(inner, "{}", serde_json::to_string(&Header::current())?)?;
Ok(Self { inner })
}
pub fn append(inner: W) -> Self {
Self { inner }
}
pub fn write<T: Serialize>(&mut self, record: &T) -> Result<(), JournalError> {
writeln!(self.inner, "{}", serde_json::to_string(record)?)?;
Ok(())
}
pub fn flush(&mut self) -> Result<(), JournalError> {
self.inner.flush()?;
Ok(())
}
}
impl From<serde_json::Error> for JournalError {
fn from(error: serde_json::Error) -> Self {
JournalError::Malformed {
line: 0,
message: error.to_string(),
}
}
}
#[derive(Debug)]
pub struct Reader<R: BufRead> {
inner: R,
line: u64,
truncated: bool,
}
impl<R: BufRead> Reader<R> {
pub fn open(mut inner: R) -> Result<Self, JournalError> {
let mut first = String::new();
let read = inner.read_line(&mut first)?;
if read == 0 {
return Err(JournalError::NotAJournal);
}
let header: Header =
serde_json::from_str(first.trim_end()).map_err(|_| JournalError::NotAJournal)?;
if header.engine != ENGINE_NAME {
return Err(JournalError::NotAJournal);
}
if header.journal_version > JOURNAL_VERSION {
return Err(JournalError::VersionTooNew {
found: header.journal_version,
understood: JOURNAL_VERSION,
});
}
Ok(Self {
inner,
line: 1,
truncated: false,
})
}
pub fn line(&self) -> u64 {
self.line
}
pub fn read<T: for<'de> Deserialize<'de>>(&mut self) -> Result<Option<T>, JournalError> {
loop {
if self.truncated {
return Ok(None);
}
let mut buffer = String::new();
if self.inner.read_line(&mut buffer)? == 0 {
return Ok(None);
}
self.line += 1;
let complete = buffer.ends_with('\n');
self.truncated = !complete;
let text = buffer.trim_end();
if text.is_empty() {
continue;
}
return match serde_json::from_str(text) {
Ok(record) => Ok(Some(record)),
Err(_) if !complete => Ok(None),
Err(error) => Err(JournalError::Malformed {
line: self.line,
message: error.to_string(),
}),
};
}
}
}
pub mod parse {
pub use crate::record::wire::{
host_status, network_role, port_state, protocol, scan_response, status_protocol,
};
}
#[cfg(test)]
mod tests {
use super::*;
use crate::export::schema;
use crate::model::host::{HostStatus, NetworkRole, StatusProtocol};
use crate::model::port::discovery::ScanResponse;
use crate::model::port::{PortState, Protocol};
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
struct Sample {
name: String,
count: u32,
}
fn sample(name: &str) -> Sample {
Sample {
name: name.to_string(),
count: 7,
}
}
fn journal(records: &[Sample]) -> Vec<u8> {
let mut out = Vec::new();
let mut writer = Writer::create(&mut out).expect("header");
for record in records {
writer.write(record).expect("record");
}
out
}
#[test]
fn records_round_trip_through_the_framing() {
let written = vec![sample("first"), sample("second"), sample("third")];
let bytes = journal(&written);
let mut reader = Reader::open(bytes.as_slice()).expect("opens");
let mut read = Vec::new();
while let Some(record) = reader.read::<Sample>().expect("reads") {
read.push(record);
}
assert_eq!(read, written);
}
#[test]
fn an_empty_file_is_not_a_journal() {
assert!(matches!(
Reader::open(&[][..]),
Err(JournalError::NotAJournal)
));
}
#[test]
fn a_file_without_a_header_is_refused() {
let bytes = b"{\"name\":\"first\",\"count\":7}\n";
assert!(matches!(
Reader::open(&bytes[..]),
Err(JournalError::NotAJournal)
));
}
#[test]
fn a_newer_journal_version_is_refused() {
let header = format!(
"{{\"journal_version\":{},\"engine\":\"{ENGINE_NAME}\",\"engine_version\":\"9.9.9\"}}\n",
JOURNAL_VERSION + 1
);
match Reader::open(header.as_bytes()) {
Err(JournalError::VersionTooNew { found, understood }) => {
assert_eq!(found, JOURNAL_VERSION + 1);
assert_eq!(understood, JOURNAL_VERSION);
}
other => panic!("expected a version refusal, got {other:?}"),
}
}
#[test]
fn a_torn_final_line_ends_the_journal_without_an_error() {
let mut bytes = journal(&[sample("first"), sample("second")]);
bytes.extend_from_slice(b"{\"name\":\"third\",\"cou");
let mut reader = Reader::open(bytes.as_slice()).expect("opens");
let mut read = Vec::new();
while let Some(record) = reader.read::<Sample>().expect("reads past the tear") {
read.push(record);
}
assert_eq!(read, vec![sample("first"), sample("second")]);
}
#[test]
fn a_complete_line_that_does_not_parse_is_an_error() {
let mut bytes = journal(&[sample("first")]);
bytes.extend_from_slice(b"{\"name\":\"second\",\"cou\n");
let mut reader = Reader::open(bytes.as_slice()).expect("opens");
assert_eq!(
reader.read::<Sample>().expect("first"),
Some(sample("first"))
);
match reader.read::<Sample>() {
Err(JournalError::Malformed { line, .. }) => assert_eq!(line, 3),
other => panic!("expected a malformed line, got {other:?}"),
}
}
#[test]
fn unknown_fields_are_ignored() {
let mut bytes = journal(&[]);
bytes.extend_from_slice(b"{\"name\":\"first\",\"count\":7,\"arrived\":\"later\"}\n");
let mut reader = Reader::open(bytes.as_slice()).expect("opens");
assert_eq!(
reader.read::<Sample>().expect("reads"),
Some(sample("first"))
);
}
#[test]
fn every_wire_name_parses_back_to_the_value_it_came_from() {
for status in [
HostStatus::Unknown,
HostStatus::Down,
HostStatus::Filtered,
HostStatus::Up,
] {
let name = schema::host_status_name(status);
assert_eq!(parse::host_status(name), Some(status), "{name}");
}
for state in [
PortState::ClosedFiltered,
PortState::Filtered,
PortState::Unfiltered,
PortState::Closed,
PortState::OpenFiltered,
PortState::Open,
] {
let name = schema::port_state_name(state);
assert_eq!(parse::port_state(name), Some(state), "{name}");
}
for protocol in [Protocol::Tcp, Protocol::Udp] {
let name = schema::protocol_name(protocol);
assert_eq!(parse::protocol(name), Some(protocol), "{name}");
}
for role in NetworkRole::ALL {
let name = schema::network_role_name(role);
assert_eq!(parse::network_role(name), Some(role), "{name}");
}
for protocol in [
StatusProtocol::Arp,
StatusProtocol::Ndp,
StatusProtocol::IcmpEcho,
StatusProtocol::IcmpUnreachable,
StatusProtocol::TcpSyn,
StatusProtocol::Tcp,
StatusProtocol::Udp,
StatusProtocol::Custom("a-strategy".into()),
] {
let name = schema::status_protocol_name(&protocol);
assert_eq!(
parse::status_protocol(&name),
Some(protocol.clone()),
"{name}"
);
}
for response in [
ScanResponse::TcpSynAck,
ScanResponse::TcpRst,
ScanResponse::UdpResponse,
ScanResponse::NoResponse,
ScanResponse::IcmpUnreachable,
ScanResponse::IcmpProhibited,
ScanResponse::Custom("a-strategy".to_string()),
] {
let name = schema::scan_response_name(&response);
assert_eq!(
parse::scan_response(&name),
Some(response.clone()),
"{name}"
);
}
}
#[test]
fn an_unknown_name_is_refused_rather_than_guessed() {
assert_eq!(parse::port_state("ajar"), None);
assert_eq!(parse::host_status("perhaps"), None);
assert_eq!(parse::protocol("sctp"), None);
assert_eq!(parse::network_role("gateway"), None);
assert_eq!(parse::status_protocol("igmp"), None);
assert_eq!(parse::scan_response("tcp_fin_ack"), None);
}
#[test]
fn an_empty_custom_name_is_refused() {
assert_eq!(parse::status_protocol("custom:"), None);
assert_eq!(parse::scan_response("custom:"), None);
}
}