Add register_with_ttl documentation, de-duplicate implementation.

Author: willstott101

src/lib.rs

@@ -29,7 +29,8 @@ use crate::address_family::{Inet, Inet6};
 use crate::fsm::{Command, FSM};
 use crate::services::{ServiceData, Services, ServicesInner};
 
-const DEFAULT_TTL: u32 = 60;
+/// The default TTL for announced mDNS Services.
+pub const DEFAULT_TTL: u32 = 60;
 const MDNS_PORT: u16 = 5353;
 
 pub struct Responder {
@@ -262,7 +263,7 @@ impl Responder {
 }
 
 impl Responder {
-    /// Register a service to be advertised by the `Responder`. The service is unregistered on
+    /// Register a service to be advertised by the Responder with the [`DEFAULT_TTL`]. The service is unregistered on
     /// drop.
     ///
     /// # Example
@@ -289,6 +290,50 @@ impl Responder {
     /// If the TXT records are longer than 255 bytes, this will panic.
     #[must_use]
     pub fn register(&self, svc_type: &str, svc_name: &str, port: u16, txt: &[&str]) -> Service {
+        self.register_with_ttl(svc_type, svc_name, port, txt, DEFAULT_TTL)
+    }
+
+    /// Register a service to be advertised by the Responder. With a custom TTL in seconds. The service is unregistered on
+    /// drop.
+    ///
+    /// You may prefer to use this over [`Responder::register`] if you know your service will be short-lived and want clients to respond
+    /// to it dissapearing more quickly (lower TTL), or if you find your service is very infrequently down and want to reduce
+    /// network traffic (higher TTL).
+    ///
+    /// This becomes more important whilst waiting for <https://github.com/librespot-org/libmdns/issues/27> to be resolved.
+    ///
+    /// # example
+    ///
+    /// ```no_run
+    /// use libmdns::Responder;
+    ///
+    /// # use std::io;
+    /// # fn main() -> io::Result<()> {
+    /// let responder = Responder::new()?;
+    /// // bind service
+    /// let _http_svc = responder.register_with_ttl(
+    ///          "_http._tcp".into(),
+    ///          "my really unreliable and short-lived http server".into(),
+    ///          80,
+    ///          &["path=/"],
+    ///          10 // mDNS clients are requested to re-check every 10 seconds for this HTTP server
+    ///      );
+    /// # Ok(())
+    /// # }
+    /// ```
+    ///
+    /// # Panics
+    ///
+    /// If the TXT records are longer than 255 bytes, this will panic.
+    #[must_use]
+    pub fn register_with_ttl(
+        &self,
+        svc_type: &str,
+        svc_name: &str,
+        port: u16,
+        txt: &[&str],
+        ttl: u32,
+    ) -> Service {
         let txt = if txt.is_empty() {
             vec![0]
         } else {
@@ -313,51 +358,14 @@ impl Responder {
             txt,
         };
 
-        self.commands
-            .borrow_mut()
-            .send_unsolicited(svc.clone(), DEFAULT_TTL, true);
-
-        let id = self.services.write().unwrap().register(svc);
-
-        Service {
-            id,
-            commands: self.commands.borrow().clone(),
-            services: self.services.clone(),
-            _shutdown: self.shutdown.clone(),
-        }
-    }
-
-    #[must_use]
-    pub fn register_with_ttl(&self, svc_type: String, svc_name: String, port: u16, txt: &[&str], ttl: u32) -> Service {
-        let txt = if txt.is_empty() {
-            vec![0]
-        } else {
-            txt.iter()
-                .flat_map(|entry| {
-                    let entry = entry.as_bytes();
-                    if entry.len() > 255 {
-                        panic!("{:?} is too long for a TXT record", entry);
-                    }
-                    std::iter::once(entry.len() as u8).chain(entry.iter().cloned())
-                })
-                .collect()
-        };
-
-        let svc = ServiceData {
-            typ: Name::from_str(format!("{}.local", svc_type)).unwrap(),
-            name: Name::from_str(format!("{}.{}.local", svc_name, svc_type)).unwrap(),
-            port: port,
-            txt: txt,
-        };
-
         self.commands
             .borrow_mut()
             .send_unsolicited(svc.clone(), ttl, true);
 
         let id = self.services.write().unwrap().register(svc);
 
         Service {
-            id: id,
+            id,
             commands: self.commands.borrow().clone(),
             services: self.services.clone(),
             _shutdown: self.shutdown.clone(),