syslog_rs/

lib.rs

/*-
 * syslog-rs - a syslog client translated from libc to rust
 * 
 * Copyright 2025 Aleksandr Morozov
 * 
 * The syslog-rs crate can be redistributed and/or modified
 * under the terms of either of the following licenses:
 *
 *   1. the Mozilla Public License Version 2.0 (the “MPL”) OR
 *                     
 *   2. EUROPEAN UNION PUBLIC LICENCE v. 1.2 EUPL © the European Union 2007, 2016
 */

//! syslog-rs
//! 
//! 
//! An implementation of the syslog from glibc/libc like it was designed in
//! in both system libraries. The API is almost compatible with what is in
//! libc/glibc.
//! 
//! ## Supports
//! 
//! * GNU/Linux RFC3164 (UTF-8 by default)
//! * *BSD and OSX RFC5424 (BOM UTF-8 by default)
//! 
//! Directories:
//! * a_sync - all async code
//! * formatters - syslog message formatter.
//! * sync - all sync code
//! * src - all common code for both sync and async.
//! 
//! Features: 
//! * feature = "build_sync"  a base feature which enables all SYNC code. Just enabling the `use_sync`
//!      would enable only basic SharedSyslog.
//! * feature = "build_async_tokio" a Tokio based async IO. Includes the tokio and tokio-rustls deps.
//! * feature = "build_async_smol" for synchronious with async processing (use syslog_rs::sy_async_queue::{Syslog};)
//! * feature = "build_with_queue" a Smol based async IO. Includes the smol and futures-rustls dep.
//!     moves the syslog client to separate thread and by default uses 
//!     crossbeam-channel to receive messages.
//!     Depending on which async procvider is selected, the channel realization 
//!     will be switched suring compilation. In this case, an async code can be 
//!     attached to the sync queue which allows to write to the same syslog
//!     connection with the same setup.
//! * feature = "build_ext_net" adds the networking support! (TCP, UDP)
//! * feature = "build_ext_tls" adds the TLS support over network (TCP).
//! * feature = "build_ext_file" writing directly to file.
//! 
//! --
//! * feature = "udp_truncate_1024_bytes" - Forces truncation of the (whole) syslog message to 1024
//! * feature = udp_truncate_1440_bytes - Forces truncation of the (whole) syslog message to 1440
//! * feature = tcp_truncate_1024_bytes - Forces truncation of the (whole) syslog message to 1024
//! * feature = tcp_truncate_2048_bytes - Forces truncation of the (whole) syslog message to 2048 
//! * feature = tcp_truncate_4096_bytes - Forces truncation of the (whole) syslog message to 4096
//! * feature = tcp_truncate_max_bytes - Forces truncation of the (whole) syslog message to 8192 (max)
//! * feature = dgram_sysctl_failure_panic - BSD only! By default, if crate fails to obtain a sysctl net.local.dgram.maxdgram, 
//!     it returns a default value 2048. If this feature is enabled, then it will panic.
//! 
//! `build_async_tokio` and `build_async_smol` cannot be used together.
//! 
//! `build_with_queue` behaves differently if enabled ine of the async providers.
//! 
//! # Usage
//! 
//! syslog-rs = {version = "2.0", default-features = false, features = ["build_sync", "build_ext_net", "udp_truncate_1440_bytes"]}
//! 
//! By default, the following features are enabled: `build_sync`, `truncate_default`
//! 
//! ```ignore
//! use std::{sync::LazyLock, thread};
//! use std::time::Duration;
//! 
//! use syslog_rs::sy_sync::Syslog;
//! 
//! use syslog_rs::{LogFacility, LogStat, Priority, SyslogLocal};
//! 
//! pub static SYSLOG: LazyLock<Syslog> = LazyLock::new(|| 
//!    {
//!        Syslog::openlog(
//!            Some("example"), 
//!            LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
//!            LogFacility::LOG_DAEMON, SyslogLocal::new()
//!        )
//!        .unwrap()
//!    }
//! );
//! 
//! 
//! macro_rules! logdebug 
//! {
//!     ($($arg:tt)*) => (
//!         SYSLOG.syslog(Priority::LOG_DEBUG, format!($($arg)*))
//!     )
//! }
//! 
//! pub fn main()
//! {
//!     logdebug!("test message1!");
//! 
//!     SYSLOG.change_identity("example2").unwrap();
//! 
//!     logdebug!("test message from new ident");
//! 
//!     thread::sleep(Duration::from_micros(10));
//! 
//!     return;
//! }
//! ```
//! 
//! ```ignore
//! use syslog_rs::sy_async::AsyncSyslog;
//! use tokio::sync::OnceCell;
//! use tokio::time::{Duration, sleep};
//! 
//! use syslog_rs::{LogFacility, LogStat, Priority, SyslogLocal};
//! 
//! 
//! pub static SYSLOG: OnceCell<AsyncSyslog> = OnceCell::const_new();
//! 
//! 
//! 
//! 
//! macro_rules! logdebug 
//! {
//!     ($($arg:tt)*) => (
//!         SYSLOG.get().unwrap().syslog(Priority::LOG_DEBUG, format!($($arg)*)).await
//!     )
//! }
//! 
//! #[tokio::main]
//! async fn main()
//! {
//!     let syslog =
//!         AsyncSyslog::openlog(
//!                 Some("example"), 
//!                 LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
//!                 LogFacility::LOG_DAEMON,
//!                 SyslogLocal::new()
//!             )
//!             .await
//!             .unwrap();
//! 
//! 
//!     SYSLOG.get_or_init(|| async { syslog }).await;
//! 
//! 
//!     logdebug!("test message async start!");
//!     
//!     SYSLOG.get().unwrap().vsyslog(Priority::LOG_DEBUG, "test 2").await;
//! 
//!     sleep(Duration::from_micros(10)).await;
//! 
//!     SYSLOG.get().unwrap().change_identity("new_identity").await.unwrap();
//! 
//!     logdebug!("test message new identity!");
//! 
//!     sleep(Duration::from_micros(10)).await;
//! 
//!     logdebug!("test 123!");
//!     logdebug!("test 123123! end ");
//!     return;
//! }
//! 
//! ```

// make sure that the smol and tokio are not used together.
#[cfg(all(feature = "build_async_tokio", feature = "build_async_smol"))]
compile_error!("use_async_tokio and use_async_smol can not be used at the same time");


//-- REEXPORT --
#[macro_use] 
extern crate bitflags;
pub extern crate chrono;
pub extern crate nix;
extern crate socket2;

// -- TLS --

#[cfg(all(feature = "build_sync", feature = "build_ext_tls"))]
extern crate rustls;

#[cfg(all(feature = "build_async_tokio", feature = "build_ext_tls"))]
extern crate tokio_rustls;

#[cfg(all(feature = "build_async_smol", feature = "build_ext_tls"))]
extern crate futures_rustls;

// -- ASYNC --

#[cfg(feature = "build_async_tokio")]
extern crate tokio;

#[cfg(feature = "build_async_smol")]
extern crate smol;

// -- SYNC --
#[cfg(feature = "build_with_queue")]
extern crate crossbeam_channel;

#[cfg(feature = "build_sync")]
pub mod sync;

#[cfg(feature = "async_enabled")]
pub mod a_sync;

pub mod formatters;

pub mod syslog_provider;
pub use syslog_provider::*;


//-- NON EXPORT
mod portable;

pub mod socket;

//-- PUBLIC 

#[macro_use] 
pub mod common;
#[macro_use] 
pub mod error;

pub use socket::TapType;

pub use syslog_provider::*;

#[cfg(feature = "build_sync")]
pub use sync::syslog as sy_sync;
#[cfg(feature = "build_sync")]
pub use sync::syslog::Syslog;
#[cfg(feature = "build_sync")]
pub use sync::syslog_sync_shared::SyslogShared;

#[cfg(feature = "async_enabled")]
pub use a_sync::syslog_async as sy_async;
#[cfg(feature = "async_enabled")]
pub use a_sync::syslog_async::AsyncSyslog;
#[cfg(feature = "async_enabled")]
pub use a_sync::syslog_async_shared::AsyncSyslogShared;
#[cfg(all(feature = "async_enabled", feature = "build_with_queue"))]
pub use a_sync::syslog_async_queue::AsyncSyslogQueue;

#[cfg(feature = "build_with_queue")]
pub use sync::syslog_sync_queue as sy_sync_queue;
#[cfg(feature = "build_with_queue")]
pub use sync::syslog_sync_queue::SyslogQueue;

pub use common::*;