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. The MIT License (MIT)
 *                     
 *   3. EUROPEAN UNION PUBLIC LICENCE v. 1.2 EUPL © the European Union 2007, 2016
 */

//! syslog-rs
//! 
//!  <img src="https://cdn.4neko.org/syslog_logo.webp" width="280"/> <img src="https://cdn.4neko.org/source_avail.webp" width="280"/> <img src="https://cdn.4neko.org/mit_mpl_eupl_2.webp" width="280"/>
//! 
//! 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_with_thread_local` enables the lockless syslog client for single threaded or `thread_local` instances.
//! * 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_async_interface" for asynchronious interface only without any realisations.
//! * 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 = "5.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::formatters::DefaultSyslogFormatter;
//! use syslog_rs::{SyslogApi, SyncSyslog};
//! use syslog_rs::{LogFacility, LogStat, Priority, SyslogLocal};
//! 
//! pub static SYSLOG: LazyLock<SyncSyslog> = LazyLock::new(|| 
//!     {
//!         SyncSyslog::openlog(
//!             Some("example"), 
//!             LogStat::LOG_CONS | LogStat::LOG_PID, 
//!             LogFacility::LOG_DAEMON, SyslogLocal::new()
//!         )
//!         .unwrap()
//!     }
//! );
//! 
//! pub static SYSLOG2: LazyLock<SyncSyslog<DefaultSyslogFormatter, SyslogLocal>> = LazyLock::new(|| 
//!     {
//!         SyncSyslog
//!             ::<_, _>
//!             ::openlog_with(
//!             None, 
//!             LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
//!             LogFacility::LOG_DAEMON, SyslogLocal::new()
//!         )
//!         .unwrap()
//!     }
//! );
//! 
//! pub static SYSLOG3: LazyLock<SyncSyslog<DefaultSyslogFormatter, SyslogLocal>> = LazyLock::new(|| 
//!     {
//!         SyncSyslog
//!             ::<_, _>
//!             ::openlog_with(
//!                 None, 
//!                 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)*).into())
//!     )
//! }
//! 
//! macro_rules! logdebug2 
//! {
//!     ($($arg:tt)*) => (
//!         SYSLOG2.syslog(Priority::LOG_DEBUG, format!($($arg)*).into())
//!     )
//! }
//! 
//! pub fn main()
//! {
//!     logdebug2!("test program name!");
//! 
//! 
//!     logdebug!("test message1!");
//! 
//!     SYSLOG.change_identity(Some("example2")).unwrap();
//! 
//!     logdebug!("test message from new ident");
//! 
//!     let new_syslog = 
//!         SyncSyslog
//!             ::<DefaultSyslogFormatter, SyslogLocal>
//!             ::openlog_with(
//!                 None, 
//!                 LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
//!                 LogFacility::LOG_DAEMON, SyslogLocal::new()
//!             )
//!             .unwrap();
//! 
//!     let c_new_syslog = new_syslog.clone();
//!     let thread_hndl = 
//!         std::thread::spawn(move || 
//!             {
//!                 logdebug!("message from thread 1");
//!                 std::thread::sleep(Duration::from_nanos(1000));
//!                 logdebug!("message from thread 2");
//!                 std::thread::sleep(Duration::from_nanos(1000));
//!                 logdebug!("message from thread 3");
//!                 std::thread::sleep(Duration::from_nanos(1000));
//!                 logdebug!("message from thread 4");
//! 
//!                 c_new_syslog.syslog(Priority::LOG_DEBUG, "test".into());
//!             }
//!         );
//! 
//!     let _ = thread_hndl.join();
//! 
//!     logdebug!("joined");
//!     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");

// make sure that the build_async_interface and either async_embedded are not used together.
#[cfg(all(feature = "build_async_interface", feature = "async_embedded"))]
compile_error!("build_async_interface and either tokio/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;

extern crate instance_copy_on_write;

// -- 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")]
extern crate crossbeam_utils;

/// A sync syslog realization including shared and queued syslog client.
#[cfg(feature = "build_sync")]
pub mod sync;

/// An async interface and/or realisations. The main async syslog struct is located there.
#[cfg(feature = "async_enabled")]
pub mod a_sync;

/// A message formatters i.e RFC5424 and other. Also a message formatter interface.
pub mod formatters;

pub mod syslog_provider;

/// A syslog destnation. i.e local, remote, remote TLS, local file. Needed to initialize the 
/// (both sync and async) instances.
pub use syslog_provider::*;

/// A common things for the sockets managment.
pub mod socket;

/// A common code which holds all flags and macroses.
#[macro_use] 
pub mod common;

/// Unified error interface.
#[macro_use] 
pub mod error;


//-- NON EXPORT
/// A portable code which is different for different OSes.
mod portable;

/// Public use of the type of the tap.
pub use socket::TapType;

/// A (prev SyslogShared) single shared (between threads) a sync type of the syslog client.
#[cfg(feature = "build_sync")]
pub use sync::syslog_sync_shared::SyncSyslog;

#[cfg(feature = "build_sync")]
pub use sync::syslog_trait::SyslogApi;

/// A streamable sync instance (both).
#[cfg(feature = "build_sync")]
pub use sync::SyStreamApi;


/// A `sy_async` is a shortcut to the file `syslog_async.rs` in dir `a_sync`.
#[cfg(feature = "async_enabled")]
pub use a_sync::syslog_async as sy_async;

/// A main async syslog instance.
#[cfg(feature = "async_enabled")]
pub use sy_async::AsyncSyslog;

/// A shortcut for the internals of the `async_syslog` and IO for user implementation.
#[cfg(feature = "build_async_interface")]
pub use a_sync::syslog_async_internal::{AsyncSyslogInternal, AsyncSyslogInternalIO};

/// A shortcut to the trait `AsyncMutex` which unifies the mutex realiztion of different 
/// exec environments.
#[cfg(feature = "build_async_interface")]
pub use a_sync::syslog_async_internal::AsyncMutex;

/// Use this trait to access queue interface for async code.
#[cfg(all(feature = "async_enabled", feature = "build_with_queue"))]
pub use a_sync::syslog_trait::AsyncSyslogQueueApi;


/// A shortcut to the file `syslog_sync_queue.rs` in dir `sync`.
#[cfg(feature = "build_with_queue")]
pub use sync::syslog_sync_queue as sy_sync_queue;

/// A (previosuly SyslogQueue) queued sync type of the syslog client. Also async queue.
#[cfg(feature = "build_with_queue")]
pub use sync::syslog_sync_queue::QueuedSyslog;

#[cfg(feature = "build_with_thread_local")]
pub use sync::syslog_threadlocal::SingleSyslog;

/// A shortcut use of all in the `common.rs`.
pub use common::*;