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_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 = "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");

// 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;

// -- 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;

/// 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 single shared (between threads) a sync type of the syslog client.
#[cfg(feature = "build_sync")]
pub use sync::syslog_sync_shared::SyslogShared;

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

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

/// 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 queued sync type of the syslog client. Also async queue.
#[cfg(feature = "build_with_queue")]
pub use sync::syslog_sync_queue::SyslogQueue;

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