From b26d34c09ca034e37634c5123445d56822ba7ac5 Mon Sep 17 00:00:00 2001 From: Emmanuel Bosquet Date: Mon, 3 Jul 2023 09:37:40 +0200 Subject: [PATCH 1/2] rename parse_one_command to parse_one_request documenting comments --- bin/src/command/requests.rs | 4 ++-- command/src/config.rs | 2 +- command/src/lib.rs | 3 +++ command/src/parser.rs | 12 +++++++----- command/src/response.rs | 2 ++ command/src/writer.rs | 1 + 6 files changed, 16 insertions(+), 8 deletions(-) diff --git a/bin/src/command/requests.rs b/bin/src/command/requests.rs index 6b6a2821c..1c73d96b4 100644 --- a/bin/src/command/requests.rs +++ b/bin/src/command/requests.rs @@ -16,7 +16,7 @@ use sozu_command_lib::{ buffer::fixed::Buffer, config::Config, logging, - parser::parse_several_commands, + parser::parse_several_requests, proto::command::{ request::RequestType, response_content::ContentType, AggregatedMetrics, AvailableMetrics, CertificatesWithFingerprints, ClusterHashes, ClusterInformations, FrontendFilters, @@ -213,7 +213,7 @@ impl CommandServer { } let mut offset = 0usize; - match parse_several_commands::(buffer.data()) { + match parse_several_requests::(buffer.data()) { Ok((i, requests)) => { if !i.is_empty() { debug!("could not parse {} bytes", i.len()); diff --git a/command/src/config.rs b/command/src/config.rs index eaba55d15..3b80e44f5 100644 --- a/command/src/config.rs +++ b/command/src/config.rs @@ -10,7 +10,7 @@ //! ``` //! //! `config.toml` is parsed to `FileConfig`, a structure that itself contains a lot of substructures -//! whose names end start with `File-`, like `FileHttpFrontendConfig` for instance. +//! whose names start with `File-` and end with `-Config`, like `FileHttpFrontendConfig` for instance. //! //! The instance of `FileConfig` is then passed to a `ConfigBuilder` that populates a final `Config` //! with listeners and clusters. diff --git a/command/src/lib.rs b/command/src/lib.rs index 36daa448a..879cb540a 100644 --- a/command/src/lib.rs +++ b/command/src/lib.rs @@ -14,6 +14,7 @@ pub mod certificate; pub mod channel; /// parse TOML config and generate requests from it pub mod config; +/// parse Requests pub mod parser; /// Contains Rust types generated by [`prost`](https://docs.rs/prost/latest/prost/) /// using the protobuf definition in `command.proto`. @@ -58,6 +59,7 @@ pub mod parser; /// /// A bit cumbersome, but it is the only way to benefit from protobuf in Rust. pub mod proto; +/// File descriptor readiness pub mod ready; /// Helper functions around types received by Sōzu pub mod request; @@ -67,4 +69,5 @@ pub mod response; pub mod scm_socket; /// A representation of Sōzu's state pub mod state; +/// A writer used for logging pub mod writer; diff --git a/command/src/parser.rs b/command/src/parser.rs index 6f67060de..8aa18ea03 100644 --- a/command/src/parser.rs +++ b/command/src/parser.rs @@ -41,7 +41,8 @@ impl nom::error::ParseError<&[u8]> for CustomError { } } -pub fn parse_one_command<'a, T>(input: &'a [u8]) -> IResult<&[u8], T, CustomError> +/// Parse a single Request or WorkerRequest +pub fn parse_one_request<'a, T>(input: &'a [u8]) -> IResult<&[u8], T, CustomError> where T: serde::de::Deserialize<'a>, { @@ -63,11 +64,12 @@ where Ok((next_input, command)) } -pub fn parse_several_commands<'a, T>(input: &'a [u8]) -> IResult<&[u8], Vec, CustomError> +/// Parse a Requests or WorkerRequests using nom +pub fn parse_several_requests<'a, T>(input: &'a [u8]) -> IResult<&[u8], Vec, CustomError> where T: serde::de::Deserialize<'a>, { - many0(parse_one_command)(input) + many0(parse_one_request)(input) } #[cfg(test)] @@ -97,7 +99,7 @@ mod test { let empty_vec: Vec = vec![]; assert_eq!( - parse_one_command(bytes).unwrap(), + parse_one_request(bytes).unwrap(), (&empty_vec[..], worker_request) ) } @@ -128,7 +130,7 @@ mod test { let bytes_to_parse = &serialized_requests.as_bytes(); - let parsed_requests = parse_several_commands(bytes_to_parse).unwrap(); + let parsed_requests = parse_several_requests(bytes_to_parse).unwrap(); println!("parsed commands: {parsed_requests:?}"); diff --git a/command/src/response.rs b/command/src/response.rs index 90b69a497..85b410441 100644 --- a/command/src/response.rs +++ b/command/src/response.rs @@ -160,6 +160,7 @@ impl From for RequestTcpFrontend { } } +/// A backend, as used *within* Sōzu #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct Backend { pub cluster_id: String, @@ -223,6 +224,7 @@ struct StatePath { pub type MessageId = String; +/// A response as sent by a worker #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct WorkerResponse { pub id: MessageId, diff --git a/command/src/writer.rs b/command/src/writer.rs index a786d5730..e3d465575 100644 --- a/command/src/writer.rs +++ b/command/src/writer.rs @@ -1,5 +1,6 @@ use std::io::{self, Error, ErrorKind, Write}; +/// A multiline writer used for logging pub struct MultiLineWriter { inner: Option, buf: Vec, From 39f4170ccb15c8f6dd0e9f9855275362f2880674 Mon Sep 17 00:00:00 2001 From: Emmanuel Bosquet Date: Mon, 3 Jul 2023 10:29:20 +0200 Subject: [PATCH 2/2] comments on logging macros --- command/src/logging.rs | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/command/src/logging.rs b/command/src/logging.rs index 654189b70..ebaece98e 100644 --- a/command/src/logging.rs +++ b/command/src/logging.rs @@ -540,6 +540,7 @@ pub fn target_to_backend(target: &str) -> LoggerBackend { } } +/// write a log with the custom logger (used in other macros, do not use directly) #[macro_export] macro_rules! log { (__inner__ $target:expr, $lvl:expr, $format:expr, $level_tag:expr, @@ -581,6 +582,7 @@ macro_rules! log { }; } +/// log a failure concerning an HTTP or TCP request #[macro_export] macro_rules! log_access { (__inner__ $target:expr, $lvl:expr, $format:expr, $level_tag:expr, @@ -622,6 +624,7 @@ macro_rules! log_access { }; } +/// log an error with Sōzu's custom log stack #[macro_export] macro_rules! error { ($format:expr, $($arg:tt)*) => { @@ -632,6 +635,7 @@ macro_rules! error { }; } +/// log a failure concerning an HTTP or TCP request #[macro_export] macro_rules! error_access { ($format:expr, $($arg:tt)*) => { @@ -642,6 +646,7 @@ macro_rules! error_access { }; } +/// log a warning with Sōzu’s custom log stack #[macro_export] macro_rules! warn { ($format:expr, $($arg:tt)*) => { @@ -653,6 +658,7 @@ macro_rules! warn { } } +/// log an info with Sōzu’s custom log stack #[macro_export] macro_rules! info { ($format:expr, $($arg:tt)*) => { @@ -663,6 +669,7 @@ macro_rules! info { } } +/// log the success of an HTTP or TCP request #[macro_export] macro_rules! info_access { ($format:expr, $($arg:tt)*) => { @@ -673,6 +680,7 @@ macro_rules! info_access { } } +/// log a debug with Sōzu’s custom log stack #[macro_export] macro_rules! debug { ($format:expr, $($arg:tt)*) => { @@ -687,6 +695,7 @@ macro_rules! debug { } } +/// log a trace with Sōzu’s custom log stack #[macro_export] macro_rules! trace { ($format:expr, $($arg:tt)*) => ( @@ -701,6 +710,7 @@ macro_rules! trace { ) } +/// write a log with a "FIXME" prefix on an info level #[macro_export] macro_rules! fixme { () => { @@ -754,6 +764,7 @@ impl log::Log for CompatLogger { fn flush(&self) {} } +/// start a logger used in test environment #[macro_export] macro_rules! setup_test_logger { () => {