refactor!: NonBlocking becomes an internal concept (#123)

Signed-off-by: tison <[email protected]>

Author: tisonkun

CHANGELOG.md

@@ -9,6 +9,72 @@ All notable changes to this project will be documented in this file.
 * `Diagnostic` is now a trait. `Visitor`'s method signature is simplified.
 * `Append::flush` is now fallible.
 * `Diagnostic`'s and `Visitor`'s `visit` methods are fallible.
+* `NonBlocking` related types and the feature flag are now private.
+* Constructing `RollingFile` and `Syslog` appender is heavily simplified.
+
+Before:
+
+```rust
+fn construct_rolling_file() {
+    let rolling_writer = RollingFileWriter::builder()
+        .rotation(Rotation::Daily)
+        .filename_prefix("app_log")
+        .build("logs")
+        .unwrap();
+
+    let (non_blocking, _guard) = rolling_file::non_blocking(rolling_writer).finish();
+
+    logforth::builder()
+        .dispatch(|d| {
+            d.filter(log::LevelFilter::Trace)
+                .append(RollingFile::new(non_blocking).with_layout(JsonLayout::default()))
+        })
+        .apply();
+}
+
+fn construct_syslog() {
+    let syslog_writer = SyslogWriter::tcp_well_known().unwrap();
+    let (non_blocking, _guard) = syslog::non_blocking(syslog_writer).finish();
+
+    logforth::builder()
+        .dispatch(|d| {
+            d.filter(log::LevelFilter::Trace)
+                .append(Syslog::new(non_blocking))
+        })
+        .apply();
+}
+```
+
+After:
+
+```rust
+fn construct_rolling_file() {
+    let (rolling_writer, _guard) = RollingFileBuilder::new("logs")
+        .layout(JsonLayout::default())
+        .rotation(Rotation::Daily)
+        .filename_prefix("app_log")
+        .build()
+        .unwrap();
+
+    logforth::builder()
+        .dispatch(|d| d.filter(log::LevelFilter::Trace).append(rolling_writer))
+        .apply();
+}
+
+fn construct_syslog() {
+    let (append, _guard) = SyslogBuilder::tcp_well_known().unwrap().build();
+
+    logforth::builder()
+        .dispatch(|d| d.filter(log::LevelFilter::Trace).append(append))
+        .apply();
+}
+```
+
+
+### New features
+
+* Add `LogfmtLayout` to support logfmt format.
+* Add `GoogleStructuredLogLayout` to support Google structured log format.
 
 ## [0.23.1] 2025-03-23
 

Cargo.toml

@@ -40,16 +40,16 @@ google_structured_log = ["internal-serde", "dep:serde_json"]
 journald = ["dep:libc"]
 json = ["internal-serde", "dep:serde_json"]
 native-tls = ["dep:native-tls", "fasyslog?/native-tls"]
-non-blocking = ["dep:crossbeam-channel"]
 opentelemetry = [
   "dep:opentelemetry",
   "dep:opentelemetry-otlp",
   "dep:opentelemetry_sdk",
 ]
-rolling-file = ["non-blocking"]
-syslog = ["non-blocking", "dep:fasyslog"]
+rolling-file = ["internal-non-blocking"]
+syslog = ["internal-non-blocking", "dep:fasyslog"]
 
 # Internal features - not intended for directly public use
+internal-non-blocking = ["dep:crossbeam-channel"]
 internal-serde = ["dep:serde", "log/kv_serde", "jiff/serde"]
 
 [dependencies]

examples/rolling_file.rs

@@ -12,26 +12,20 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use logforth::append::rolling_file;
-use logforth::append::rolling_file::RollingFile;
-use logforth::append::rolling_file::RollingFileWriter;
+use logforth::append::rolling_file::RollingFileBuilder;
 use logforth::append::rolling_file::Rotation;
 use logforth::layout::JsonLayout;
 
 fn main() {
-    let rolling_writer = RollingFileWriter::builder()
+    let (rolling_writer, _guard) = RollingFileBuilder::new("logs")
+        .layout(JsonLayout::default())
         .rotation(Rotation::Daily)
         .filename_prefix("app_log")
-        .build("logs")
+        .build()
         .unwrap();
 
-    let (non_blocking, _guard) = rolling_file::non_blocking(rolling_writer).finish();
-
     logforth::builder()
-        .dispatch(|d| {
-            d.filter(log::LevelFilter::Trace)
-                .append(RollingFile::new(non_blocking).with_layout(JsonLayout::default()))
-        })
+        .dispatch(|d| d.filter(log::LevelFilter::Trace).append(rolling_writer))
         .apply();
 
     let repeat = 1;

examples/syslog.rs

@@ -12,19 +12,13 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use logforth::append::syslog;
-use logforth::append::syslog::Syslog;
-use logforth::append::syslog::SyslogWriter;
+use logforth::append::syslog::SyslogBuilder;
 
 fn main() {
-    let syslog_writer = SyslogWriter::tcp_well_known().unwrap();
-    let (non_blocking, _guard) = syslog::non_blocking(syslog_writer).finish();
+    let (append, _guard) = SyslogBuilder::tcp_well_known().unwrap().build();
 
     logforth::builder()
-        .dispatch(|d| {
-            d.filter(log::LevelFilter::Trace)
-                .append(Syslog::new(non_blocking))
-        })
+        .dispatch(|d| d.filter(log::LevelFilter::Trace).append(append))
         .apply();
 
     let repeat = 1;

src/append/opentelemetry.rs

@@ -50,6 +50,7 @@ pub enum OpentelemetryWireProtocol {
 }
 
 /// A builder to configure and create an [`OpentelemetryLog`] appender.
+#[derive(Debug)]
 pub struct OpentelemetryLogBuilder {
     name: String,
     endpoint: String,

src/append/rolling_file/append.rs

@@ -12,38 +12,146 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+use std::path::PathBuf;
+use std::time::Duration;
+
 use log::Record;
 
-use crate::append::rolling_file::RollingFileWriter;
+use crate::append::rolling_file::rolling::RollingFileWriter;
+use crate::append::rolling_file::rolling::RollingFileWriterBuilder;
+use crate::append::rolling_file::Rotation;
 use crate::append::Append;
 use crate::layout::TextLayout;
 use crate::non_blocking::NonBlocking;
+use crate::non_blocking::NonBlockingBuilder;
 use crate::Diagnostic;
+use crate::DropGuard;
 use crate::Layout;
 
-/// An appender that writes log records to rolling files.
+/// A builder to configure and create an [`RollingFile`] appender.
 #[derive(Debug)]
-pub struct RollingFile {
+pub struct RollingFileBuilder {
+    builder: RollingFileWriterBuilder,
     layout: Box<dyn Layout>,
-    writer: NonBlocking<RollingFileWriter>,
+
+    // non-blocking options
+    thread_name: String,
+    buffered_lines_limit: Option<usize>,
+    shutdown_timeout: Option<Duration>,
 }
 
-impl RollingFile {
-    /// Creates a new [`RollingFile`] appender.
-    ///
-    /// This appender by default uses [`TextLayout`] to format log records.
-    pub fn new(writer: NonBlocking<RollingFileWriter>) -> Self {
+impl RollingFileBuilder {
+    /// Create a new builder.
+    pub fn new(basedir: impl Into<PathBuf>) -> Self {
         Self {
+            builder: RollingFileWriterBuilder::new(basedir),
             layout: Box::new(TextLayout::default().no_color()),
-            writer,
+
+            thread_name: "logforth-rolling-file".to_string(),
+            buffered_lines_limit: None,
+            shutdown_timeout: None,
         }
     }
 
-    /// Sets the layout used to format log records.
-    pub fn with_layout(mut self, layout: impl Into<Box<dyn Layout>>) -> Self {
+    /// Build the [`RollingFile`] appender.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the log directory cannot be created.
+    pub fn build(self) -> anyhow::Result<(RollingFile, DropGuard)> {
+        let RollingFileBuilder {
+            builder,
+            layout,
+            thread_name,
+            buffered_lines_limit,
+            shutdown_timeout,
+        } = self;
+        let writer = builder.build()?;
+        let (non_blocking, guard) = NonBlockingBuilder::new(thread_name, writer)
+            .buffered_lines_limit(buffered_lines_limit)
+            .shutdown_timeout(shutdown_timeout)
+            .build();
+        Ok((RollingFile::new(non_blocking, layout), Box::new(guard)))
+    }
+
+    /// Sets the layout for the logs.
+    ///
+    /// Default to [`TextLayout`].
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use logforth::append::rolling_file::RollingFileBuilder;
+    /// use logforth::layout::JsonLayout;
+    ///
+    /// let builder = RollingFileBuilder::new("my_service");
+    /// builder.layout(JsonLayout::default());
+    /// ```
+    pub fn layout(mut self, layout: impl Into<Box<dyn Layout>>) -> Self {
         self.layout = layout.into();
         self
     }
+
+    /// Sets the buffer size of pending messages.
+    pub fn buffered_lines_limit(mut self, buffered_lines_limit: Option<usize>) -> Self {
+        self.buffered_lines_limit = buffered_lines_limit;
+        self
+    }
+
+    /// Sets the shutdown timeout before the worker guard dropped.
+    pub fn shutdown_timeout(mut self, shutdown_timeout: Option<Duration>) -> Self {
+        self.shutdown_timeout = shutdown_timeout;
+        self
+    }
+
+    /// Sets the thread name for the background sender thread.
+    pub fn thread_name(mut self, thread_name: impl Into<String>) -> Self {
+        self.thread_name = thread_name.into();
+        self
+    }
+
+    /// Sets the rotation policy.
+    pub fn rotation(mut self, rotation: Rotation) -> Self {
+        self.builder = self.builder.rotation(rotation);
+        self
+    }
+
+    /// Sets the filename prefix.
+    pub fn filename_prefix(mut self, prefix: impl Into<String>) -> Self {
+        self.builder = self.builder.filename_prefix(prefix);
+        self
+    }
+
+    /// Sets the filename suffix.
+    pub fn filename_suffix(mut self, suffix: impl Into<String>) -> Self {
+        self.builder = self.builder.filename_suffix(suffix);
+        self
+    }
+
+    /// Sets the maximum number of log files to keep.
+    pub fn max_log_files(mut self, n: usize) -> Self {
+        self.builder = self.builder.max_log_files(n);
+        self
+    }
+
+    /// Sets the maximum size of a log file in bytes.
+    pub fn max_file_size(mut self, n: usize) -> Self {
+        self.builder = self.builder.max_file_size(n);
+        self
+    }
+}
+
+/// An appender that writes log records to rolling files.
+#[derive(Debug)]
+pub struct RollingFile {
+    layout: Box<dyn Layout>,
+    writer: NonBlocking<RollingFileWriter>,
+}
+
+impl RollingFile {
+    fn new(writer: NonBlocking<RollingFileWriter>, layout: Box<dyn Layout>) -> Self {
+        Self { layout, writer }
+    }
 }
 
 impl Append for RollingFile {

src/append/rolling_file/mod.rs

@@ -19,41 +19,29 @@
 //!```
 //! use logforth::append::rolling_file;
 //! use logforth::append::rolling_file::RollingFile;
-//! use logforth::append::rolling_file::RollingFileWriter;
+//! use logforth::append::rolling_file::RollingFileBuilder;
 //! use logforth::append::rolling_file::Rotation;
 //! use logforth::layout::JsonLayout;
 //!
-//! let rolling_writer = RollingFileWriter::builder()
+//! let (rolling_writer, _guard) = RollingFileBuilder::new("logs")
+//!     .layout(JsonLayout::default())
 //!     .rotation(Rotation::Daily)
 //!     .filename_prefix("app_log")
-//!     .build("logs")
+//!     .build()
 //!     .unwrap();
 //!
-//! let (non_blocking, _guard) = rolling_file::non_blocking(rolling_writer).finish();
-//!
 //! logforth::builder()
-//!     .dispatch(|d| {
-//!         d.filter(log::LevelFilter::Trace)
-//!             .append(RollingFile::new(non_blocking).with_layout(JsonLayout::default()))
-//!     })
+//!     .dispatch(|d| d.filter(log::LevelFilter::Trace).append(rolling_writer))
 //!     .apply();
 //!
 //! log::info!("This log will be written to a rolling file.");
 //! ```
 
 pub use append::RollingFile;
-pub use rolling::RollingFileWriter;
-pub use rolling::RollingFileWriterBuilder;
+pub use append::RollingFileBuilder;
 pub use rotation::Rotation;
 
-use crate::non_blocking::NonBlockingBuilder;
-
 mod append;
 mod clock;
 mod rolling;
 mod rotation;
-
-/// Create a non-blocking builder for rolling file writers.
-pub fn non_blocking(writer: RollingFileWriter) -> NonBlockingBuilder<RollingFileWriter> {
-    NonBlockingBuilder::new("logforth-rolling-file", writer)
-}