feat: support tls sender

Cargo.toml

@@ -30,9 +30,15 @@ all-features = true
 cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
 rustdoc-args = ["--cfg", "docsrs"]
 
+[features]
+native-tls = ["dep:native-tls"]
+
 [dependencies]
 jiff = { version = "0.1.14" }
 
+# Optional dependencies
+native-tls = { version = "0.2.12", optional = true }
+
 [target.'cfg(unix)'.dependencies]
 cfg-if = { version = "1.0.0" }
 nix = { version = "0.29.0", features = ["hostname"] }
@@ -48,6 +54,12 @@ doc-scrape-examples = true
 name = "tcp_sender"
 path = "examples/tcp_sender.rs"
 
+[[example]]
+doc-scrape-examples = true
+name = "tls_sender"
+path = "examples/tls_sender.rs"
+required-features = ["native-tls"]
+
 [[example]]
 doc-scrape-examples = true
 name = "udp_sender"

README.md

@@ -94,6 +94,12 @@ This crate is built against the latest stable release, and its minimum supported
 
 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.
 
+## When to release a 1.0 version
+
+I'm fine with the current API design and ready for a 1.0 release. Just leave a few months for feedback on the crate's usability. If you have any suggestions or feedback, please open an issue.
+
+I'm going to release a 1.0 version as early as 2025-01.
+
 ## License
 
 This project is licensed under [Apache License, Version 2.0](LICENSE).

examples/tls_sender.rs

@@ -0,0 +1,28 @@
+// Copyright 2024 FastLabs Developers
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use fasyslog::Severity;
+
+fn main() {
+    let mut sender = fasyslog::sender::tls_well_known("127.0.0.1").unwrap();
+    let mut generator = names::Generator::default();
+    for _ in 0..100 {
+        let name = generator.next().unwrap();
+        let message = format!("Hello, {name}!");
+        sender
+            .send_rfc5424(Severity::ERROR, None::<String>, Vec::new(), message)
+            .unwrap();
+    }
+    sender.flush().unwrap();
+}

src/sender/internal.rs

@@ -20,7 +20,7 @@ macro_rules! impl_syslog_sender_common {
                 &mut self,
                 severity: $crate::Severity,
                 message: M,
-            ) -> io::Result<()> {
+            ) -> std::io::Result<()> {
                 let message = self.context.format_rfc3164(severity, Some(message));
                 self.send_formatted(message.to_string().as_bytes())
             }
@@ -32,7 +32,7 @@ macro_rules! impl_syslog_sender_common {
                 msgid: Option<S>,
                 elements: Vec<$crate::SDElement>,
                 message: M,
-            ) -> io::Result<()> {
+            ) -> std::io::Result<()> {
                 let message = self
                     .context
                     .format_rfc5424(severity, msgid, elements, Some(message));
@@ -43,3 +43,25 @@ macro_rules! impl_syslog_sender_common {
 }
 
 pub(crate) use impl_syslog_sender_common;
+
+macro_rules! impl_syslog_stream_send_formatted {
+    ($sender:ident) => {
+        impl $sender {
+            /// Send a formatted message to the stream.
+            pub fn send_formatted(&mut self, message: &[u8]) -> std::io::Result<()> {
+                use std::io::Write;
+                self.writer.write_all(message)?;
+                self.writer.write_all(self.postfix.as_bytes())?;
+                Ok(())
+            }
+
+            /// Flush the stream.
+            pub fn flush(&mut self) -> std::io::Result<()> {
+                use std::io::Write;
+                self.writer.flush()
+            }
+        }
+    };
+}
+
+pub(crate) use impl_syslog_stream_send_formatted;

src/sender/mod.rs

@@ -25,6 +25,11 @@ mod unix;
 #[cfg(unix)]
 pub use unix::*;
 
+#[cfg(feature = "native-tls")]
+mod native_tls;
+#[cfg(feature = "native-tls")]
+pub use native_tls::*;
+
 mod tcp;
 pub use tcp::*;
 
@@ -38,6 +43,8 @@ pub(crate) mod internal;
 pub enum SyslogSender {
     Tcp(TcpSender),
     Udp(UdpSender),
+    #[cfg(feature = "native-tls")]
+    Tls(TlsSender),
     #[cfg(unix)]
     UnixDatagram(UnixDatagramSender),
     #[cfg(unix)]
@@ -54,6 +61,8 @@ impl SyslogSender {
         match self {
             SyslogSender::Tcp(sender) => sender.send_rfc3164(severity, message),
             SyslogSender::Udp(sender) => sender.send_rfc3164(severity, message),
+            #[cfg(feature = "native-tls")]
+            SyslogSender::Tls(sender) => sender.send_rfc3164(severity, message),
             #[cfg(unix)]
             SyslogSender::UnixDatagram(sender) => sender.send_rfc3164(severity, message),
             #[cfg(unix)]
@@ -72,6 +81,8 @@ impl SyslogSender {
         match self {
             SyslogSender::Tcp(sender) => sender.send_rfc5424(severity, msgid, elements, message),
             SyslogSender::Udp(sender) => sender.send_rfc5424(severity, msgid, elements, message),
+            #[cfg(feature = "native-tls")]
+            SyslogSender::Tls(sender) => sender.send_rfc5424(severity, msgid, elements, message),
             #[cfg(unix)]
             SyslogSender::UnixDatagram(sender) => {
                 sender.send_rfc5424(severity, msgid, elements, message)
@@ -88,6 +99,8 @@ impl SyslogSender {
         match self {
             SyslogSender::Tcp(sender) => sender.send_formatted(formatted),
             SyslogSender::Udp(sender) => sender.send_formatted(formatted),
+            #[cfg(feature = "native-tls")]
+            SyslogSender::Tls(sender) => sender.send_formatted(formatted),
             #[cfg(unix)]
             SyslogSender::UnixDatagram(sender) => sender.send_formatted(formatted),
             #[cfg(unix)]
@@ -108,6 +121,8 @@ impl SyslogSender {
         match self {
             SyslogSender::Tcp(sender) => sender.flush(),
             SyslogSender::Udp(_) => Ok(()),
+            #[cfg(feature = "native-tls")]
+            SyslogSender::Tls(sender) => sender.flush(),
             #[cfg(unix)]
             SyslogSender::UnixDatagram(_) => Ok(()),
             #[cfg(unix)]

src/sender/native_tls.rs

@@ -0,0 +1,102 @@
+// Copyright 2024 FastLabs Developers
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use std::borrow::Cow;
+use std::io;
+use std::io::BufWriter;
+use std::net::TcpStream;
+use std::net::ToSocketAddrs;
+
+use native_tls::TlsConnector;
+use native_tls::TlsConnectorBuilder;
+use native_tls::TlsStream;
+
+use crate::format::SyslogContext;
+use crate::sender::internal::impl_syslog_sender_common;
+use crate::sender::internal::impl_syslog_stream_send_formatted;
+
+/// Create a TLS sender that sends messages to the well-known port (6514).
+///
+/// See also [RFC-5425] §4.1 Port Assignment.
+///
+/// [RFC-5425]: https://datatracker.ietf.org/doc/html/rfc5425#section-4.1
+pub fn tls_well_known<S: AsRef<str>>(domain: S) -> io::Result<TlsSender> {
+    let domain = domain.as_ref();
+    tls(format!("{domain}:6514"), domain)
+}
+
+/// Create a TLS sender that sends messages to the given address.
+pub fn tls<A: ToSocketAddrs, S: AsRef<str>>(addr: A, domain: S) -> io::Result<TlsSender> {
+    tls_with(addr, domain, TlsConnector::builder())
+}
+
+/// Create a TLS sender that sends messages to the given address with certificate builder.
+pub fn tls_with<A: ToSocketAddrs, S: AsRef<str>>(
+    addr: A,
+    domain: S,
+    builder: TlsConnectorBuilder,
+) -> io::Result<TlsSender> {
+    TlsSender::connect(addr, domain, builder)
+}
+
+/// A syslog sender that sends messages to a TCP socket over TLS.
+#[derive(Debug)]
+pub struct TlsSender {
+    writer: BufWriter<TlsStream<TcpStream>>,
+    context: SyslogContext,
+    postfix: Cow<'static, str>,
+}
+
+impl TlsSender {
+    /// Connect to a TCP socket over TLS at the given address.
+    pub fn connect<A: ToSocketAddrs, S: AsRef<str>>(
+        addr: A,
+        domain: S,
+        builder: TlsConnectorBuilder,
+    ) -> io::Result<Self> {
+        let domain = domain.as_ref();
+        let stream = TcpStream::connect(addr)?;
+        let connector = builder.build().map_err(io::Error::other)?;
+        let stream = connector
+            .connect(domain, stream)
+            .map_err(io::Error::other)?;
+        Ok(Self {
+            writer: BufWriter::new(stream),
+            context: SyslogContext::default(),
+            postfix: Cow::Borrowed("\r\n"),
+        })
+    }
+
+    /// Set the postfix when formatting Syslog message.
+    ///
+    /// This is generally '\r\n' as defined in [RFC-6587] §3.4.2.
+    ///
+    /// [RFC-6587]: https://datatracker.ietf.org/doc/html/rfc6587
+    pub fn set_postfix(&mut self, postfix: impl Into<Cow<'static, str>>) {
+        self.postfix = postfix.into();
+    }
+
+    /// Set the context when formatting Syslog message.
+    pub fn set_context(mut self, context: SyslogContext) {
+        self.context = context;
+    }
+
+    /// Mutate the context when formatting Syslog message.
+    pub fn mut_context(&mut self) -> &mut SyslogContext {
+        &mut self.context
+    }
+}
+
+impl_syslog_sender_common!(TlsSender);
+impl_syslog_stream_send_formatted!(TlsSender);

src/sender/tcp.rs

@@ -15,12 +15,12 @@
 use std::borrow::Cow;
 use std::io;
 use std::io::BufWriter;
-use std::io::Write;
 use std::net::TcpStream;
 use std::net::ToSocketAddrs;
 
 use crate::format::SyslogContext;
 use crate::sender::internal::impl_syslog_sender_common;
+use crate::sender::internal::impl_syslog_stream_send_formatted;
 
 /// Create a TCP sender that sends messages to the well-known port (601).
 ///
@@ -73,19 +73,7 @@ impl TcpSender {
     pub fn mut_context(&mut self) -> &mut SyslogContext {
         &mut self.context
     }
-
-    /// Send a pre-formatted message.
-    pub fn send_formatted(&mut self, formatted: &[u8]) -> io::Result<()> {
-        self.writer.write_all(formatted)?;
-        self.writer.write_all(self.postfix.as_bytes())?;
-        Ok(())
-    }
-
-    /// Flush the writer.
-    pub fn flush(&mut self) -> io::Result<()> {
-        use std::io::Write;
-        self.writer.flush()
-    }
 }
 
 impl_syslog_sender_common!(TcpSender);
+impl_syslog_stream_send_formatted!(TcpSender);

src/sender/unix.rs

@@ -15,13 +15,13 @@
 use std::borrow::Cow;
 use std::io;
 use std::io::BufWriter;
-use std::io::Write;
 use std::os::unix::net::UnixDatagram;
 use std::os::unix::net::UnixStream;
 use std::path::Path;
 
 use crate::format::SyslogContext;
 use crate::sender::internal::impl_syslog_sender_common;
+use crate::sender::internal::impl_syslog_stream_send_formatted;
 use crate::sender::SyslogSender;
 
 /// Create a Unix datagram sender that sends messages to the given path.
@@ -141,19 +141,7 @@ impl UnixStreamSender {
     pub fn mut_context(&mut self) -> &mut SyslogContext {
         &mut self.context
     }
-
-    /// Send a pre-formatted message.
-    pub fn send_formatted(&mut self, formatted: &[u8]) -> io::Result<()> {
-        self.writer.write_all(formatted)?;
-        self.writer.write_all(self.postfix.as_bytes())?;
-        Ok(())
-    }
-
-    /// Flush the writer.
-    pub fn flush(&mut self) -> io::Result<()> {
-        use std::io::Write;
-        self.writer.flush()
-    }
 }
 
 impl_syslog_sender_common!(UnixStreamSender);
+impl_syslog_stream_send_formatted!(UnixStreamSender);