feat: refine APIs and docs (#1)

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

Cargo.toml

@@ -24,6 +24,10 @@ license = "Apache-2.0"
 repository = "https://github.com/fast/fasyslog"
 rust-version = "1.75.0"
 
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
+
 [dependencies]
 jiff = { version = "0.1.14" }
 

README.md

@@ -1,3 +1,60 @@
-# Fasyslog
+# Fasyslog: A fast syslog client written in Rust
 
-A fast syslog client written in Rust.
+[![Crates.io][crates-badge]][crates-url]
+[![Documentation][docs-badge]][docs-url]
+[![MSRV 1.75][msrv-badge]](https://www.whatrustisit.com)
+[![Apache 2.0 licensed][license-badge]][license-url]
+[![Build Status][actions-badge]][actions-url]
+
+[crates-badge]: https://img.shields.io/crates/v/fasyslog.svg
+
+[crates-url]: https://crates.io/crates/fasyslog
+
+[docs-badge]: https://docs.rs/fasyslog/badge.svg
+
+[msrv-badge]: https://img.shields.io/badge/MSRV-1.75-green?logo=rust
+
+[docs-url]: https://docs.rs/fasyslog
+
+[license-badge]: https://img.shields.io/crates/l/fasyslog
+
+[license-url]: LICENSE
+
+[actions-badge]: https://github.com/fast/fasyslog/workflows/CI/badge.svg
+
+[actions-url]:https://github.com/fast/fasyslog/actions?query=workflow%3ACI
+
+## Description
+
+Client library written in Rust to send messages to a Syslog server. Support implementations:
+
+* RFC-3164 Formatter: [The BSD syslog Protocol](http://tools.ietf.org/html/rfc3164)
+* RFC-5424 Formatter: [The Syslog Protocol](http://tools.ietf.org/html/rfc5424)
+* `UdpSender`: [RFC 5426 - Transmission of Syslog Messages over UDP](http://tools.ietf.org/html/rfc5426)
+* `TcpSender`: [RFC 6587 - Transmission of Syslog Messages over TCP](http://tools.ietf.org/html/rfc6587)
+
+## Getting Started
+
+Add `fasyslog` to your `Cargo.toml`:
+
+```shell
+cargo add fasyslog
+```
+
+## Example
+
+Check the [examples](examples) directory for more examples.
+
+## Documentation
+
+Read the online documents at https://docs.rs/logforth.
+
+## Minimum Supported Rust Version (MSRV)
+
+This crate is built against the latest stable release, and its minimum supported rustc version is 1.75.0.
+
+The policy is that the minimum Rust version required to use this crate can be increased in minor version updates. For example, if Fasyslog 1.0 requires Rust 1.20.0, then Fasyslog 1.0.z for all values of z will also require Rust 1.20.0 or newer. However, Fasyslog 1.y for y > 0 may require a newer minimum version of Rust.
+
+## License
+
+This project is licensed under [Apache License, Version 2.0](LICENSE).

examples/tcp_sender.rs

@@ -12,9 +12,19 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-mod shared;
+use fasyslog::Severity;
 
 fn main() {
-    let sender = fasyslog::sender::tcp_well_known().unwrap();
-    shared::send_syslog_message(sender);
+    let mut sender = fasyslog::sender::tcp_well_known().unwrap();
+    let mut generator = names::Generator::default();
+    for _ in 0..100 {
+        let name = generator.next().unwrap();
+        let message = format!("Hello, {name}!");
+        let mut element = fasyslog::SDElement::new("exampleSDID@32473").unwrap();
+        element.add_param("iut", "3").unwrap();
+        sender
+            .send_rfc5424(Severity::ERROR, Some("TCPIN"), vec![element], message)
+            .unwrap();
+    }
+    sender.flush().unwrap();
 }

examples/udp_sender.rs

@@ -12,9 +12,18 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-mod shared;
+use fasyslog::Severity;
 
 fn main() {
-    let sender = fasyslog::sender::udp_well_known().unwrap();
-    shared::send_syslog_message(sender);
+    let mut sender = fasyslog::sender::udp_well_known().unwrap();
+    let mut generator = names::Generator::default();
+    for _ in 0..100 {
+        let name = generator.next().unwrap();
+        let message = format!("Hello, {name}!");
+        let mut element = fasyslog::SDElement::new("exampleSDID@16253").unwrap();
+        element.add_param("jno", "sul").unwrap();
+        sender
+            .send_rfc5424(Severity::ERROR, Some("UDPIN"), vec![element], message)
+            .unwrap();
+    }
 }

examples/unix_sender.rs

@@ -12,12 +12,18 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-mod shared;
+use fasyslog::Severity;
 
 #[cfg(unix)]
 fn main() {
-    let sender = fasyslog::sender::unix_well_known().unwrap();
-    shared::send_syslog_message(sender);
+    let mut sender = fasyslog::sender::unix_well_known().unwrap();
+    let mut generator = names::Generator::default();
+    for _ in 0..100 {
+        let name = generator.next().unwrap();
+        let message = format!("Hello, {name}!");
+        sender.send_rfc3164(Severity::ERROR, message).unwrap();
+    }
+    sender.flush().unwrap();
 }
 
 #[cfg(not(unix))]

src/format.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Format Syslog messages according to the referred standards.
+
 use std::fmt;
 use std::fmt::Formatter;
 
@@ -123,28 +125,6 @@ impl SyslogContext {
             message,
         }
     }
-
-    /// Format the Syslog message with the given severity as defined in RFC-5425.
-    pub fn format_rfc5425<S, M>(
-        &self,
-        severity: Severity,
-        msgid: Option<S>,
-        elements: Vec<SDElement>,
-        message: Option<M>,
-    ) -> RFC5425Formatter<M>
-    where
-        S: Into<String>,
-        M: fmt::Display,
-    {
-        let msgid = msgid.map(|s| s.into());
-        RFC5425Formatter {
-            context: self,
-            severity,
-            msgid,
-            elements,
-            message,
-        }
-    }
 }
 
 /// Shared format logic for nullable value.
@@ -188,6 +168,9 @@ where
     }
 }
 
+/// Format the Syslog message as [RFC 5424] (The Syslog Protocol)
+///
+/// [RFC 5424]: https://tools.ietf.org/html/rfc5424
 #[derive(Debug)]
 pub struct RFC5424Formatter<'a, M> {
     context: &'a SyslogContext,
@@ -232,35 +215,3 @@ where
         Ok(())
     }
 }
-
-#[derive(Debug)]
-pub struct RFC5425Formatter<'a, M> {
-    context: &'a SyslogContext,
-    severity: Severity,
-    msgid: Option<String>,
-    elements: Vec<SDElement>,
-    message: Option<M>,
-}
-
-impl<M> fmt::Display for RFC5425Formatter<'_, M>
-where
-    M: fmt::Display,
-{
-    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
-        // The RFC-5425 format is defined as 'MSG-LEN SP SYSLOG-MSG',
-        // where SYSLOG-MSG is defined as in RFC-5424.
-        // https://datatracker.ietf.org/doc/html/rfc5425#section-4.3
-        let rfc5424_payload = format!(
-            "{}",
-            RFC5424Formatter {
-                context: self.context,
-                severity: self.severity,
-                msgid: self.msgid.clone(),
-                elements: self.elements.clone(),
-                message: self.message.as_ref()
-            }
-        );
-        let msg_len = rfc5424_payload.len();
-        write!(f, "{msg_len} {rfc5424_payload}")
-    }
-}

src/internal.rs

@@ -32,11 +32,6 @@ pub(crate) fn hostname() -> Option<OsString> {
         // not the name of the cluster virtual server.
         pub const COMPUTER_NAME_PHYSICAL_DNS_HOSTNAME: i32 = 5;
 
-        // The DNS host name of the local computer. If the local computer is a node
-        // in a cluster, lpBuffer receives the DNS host name of the local computer,
-        // not the name of the cluster virtual server.
-        pub const COMPUTER_NAME_PHYSICAL_DNS_HOSTNAME: i32 = 5;
-
         // https://learn.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getcomputernameexw
         ::windows_targets::link!("kernel32.dll" "system" fn GetComputerNameExW(nametype: i32, lpbuffer: *mut u16, nsize: *mut u32) -> i32);
 

src/lib.rs

@@ -12,18 +12,59 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-mod facility;
-pub use facility::*;
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
-mod format;
-pub use format::*;
+//! `fasyslog` is a fast syslog client written in Rust.
+//!
+//! # Overview
+//!
+//! This crate provides facilities to send log messages via syslog. Support implementations:
+//!
+//! * [RFC-3164 Formatter]: [The BSD syslog Protocol](http://tools.ietf.org/html/rfc3164)
+//! * [RFC-5424 Formatter]: [The Syslog Protocol](http://tools.ietf.org/html/rfc5424)
+//! * [`UdpSender`]: [RFC 5426 - Transmission of Syslog Messages over UDP](http://tools.ietf.org/html/rfc5426)
+//! * [`TcpSender`]: [RFC 6587 - Transmission of Syslog Messages over TCP](http://tools.ietf.org/html/rfc6587)
+//! * (unix only) Unix domain socket sender (datagram or stream)
+//!
+//! [RFC-3164 Formatter]: format::RFC3164Formatter
+//! [RFC-5424 Formatter]: format::RFC5424Formatter
+//! [`UdpSender`]: sender::UdpSender
+//! [`TcpSender`]: sender::TcpSender
+//!
+//! # Example
+//!
+//! Send a message to a remote syslog server:
+//!
+//! ```rust, no_run
+//! let mut sender = fasyslog::sender::tcp_well_known().unwrap();
+//! sender
+//!     .send_rfc3164(fasyslog::Severity::INFORMATIONAL, "Hello, syslog!")
+//!     .unwrap();
+//! sender.flush().unwrap();
+//!
+//! let mut element = fasyslog::SDElement::new("exampleSDID@32473").unwrap();
+//! element.add_param("iut", "3").unwrap();
+//! sender
+//!     .send_rfc5424(
+//!         fasyslog::Severity::NOTICE,
+//!         Some("TCPIN"),
+//!         vec![element],
+//!         "Hello, syslog!",
+//!     )
+//!     .unwrap();
+//! sender.flush().unwrap();
+//! ```
 
-pub mod sender;
+mod facility;
+pub use facility::*;
 
 mod severity;
 pub use severity::*;
 
 mod structured_data;
 pub use structured_data::*;
 
+pub mod format;
+pub mod sender;
+
 mod internal;