Crate mdns_sd

Expand description

A small and safe library for Multicast DNS-SD (Service Discovery).

This library creates one new thread to run a mDNS daemon, and exposes its API that interacts with the daemon via a flume channel. The channel supports both recv() and recv_async().

For example, a client querying (browsing) a service behaves like this:

  Client       <channel>       mDNS daemon thread
    |                             | starts its run-loop.
    |       --- Browse -->        |
    |                             | detects services
    |                             | finds service instance A
    |       <-- Found A --        |
    |           ...               | resolves service A
    |       <-- Resolved A --     |
    |           ...               |

All commands in the public API are sent to the daemon using the unblocking try_send() so that the caller can use it with both sync and async code, with no dependency on any particular async runtimes.

§Usage

The user starts with creating a daemon by calling ServiceDaemon::new(). Then as a mDNS querier, the user would call browse to search for services, and/or as a mDNS responder, call register to publish (i.e. announce) its own service. And, the daemon type can be cloned and passed around between threads.

The user can also call resolve_hostname to resolve a hostname to IP addresses using mDNS, regardless if the host publishes a service name.

§Example: a client querying for a service type.

use mdns_sd::{ServiceDaemon, ServiceEvent};

// Create a daemon
let mdns = ServiceDaemon::new().expect("Failed to create daemon");

// Browse for a service type.
let service_type = "_mdns-sd-my-test._udp.local.";
let receiver = mdns.browse(service_type).expect("Failed to browse");

// Receive the browse events in sync or async. Here is
// an example of using a thread. Users can call `receiver.recv_async().await`
// if running in async environment.
std::thread::spawn(move || {
    while let Ok(event) = receiver.recv() {
        match event {
            ServiceEvent::ServiceResolved(info) => {
                println!("Resolved a new service: {}", info.get_fullname());
            }
            other_event => {
                println!("Received other event: {:?}", &other_event);
            }
        }
    }
});

// Gracefully shutdown the daemon.
std::thread::sleep(std::time::Duration::from_secs(1));
mdns.shutdown().unwrap();

§Example: a server publishs a service and responds to queries.

use mdns_sd::{ServiceDaemon, ServiceInfo};
use std::collections::HashMap;

// Create a daemon
let mdns = ServiceDaemon::new().expect("Failed to create daemon");

// Create a service info.
let service_type = "_mdns-sd-my-test._udp.local.";
let instance_name = "my_instance";
let ip = "192.168.1.12";
let host_name = "192.168.1.12.local.";
let port = 5200;
let properties = [("property_1", "test"), ("property_2", "1234")];

let my_service = ServiceInfo::new(
    service_type,
    instance_name,
    host_name,
    ip,
    port,
    &properties[..],
).unwrap();

// Register with the daemon, which publishes the service.
mdns.register(my_service).expect("Failed to register our service");

// Gracefully shutdown the daemon
std::thread::sleep(std::time::Duration::from_secs(1));
mdns.shutdown().unwrap();

§Limitations

This implementation is based on the following RFCs:

mDNS: RFC 6762
DNS-SD: RFC 6763
DNS: RFC 1035

We focus on the common use cases at first, and currently have the following limitations:

Only support multicast, not unicast send/recv.
Only support 32-bit or bigger platforms, not 16-bit platforms.

§Use logging in tests and examples

Often times it is helpful to enable logging running tests or examples to examine the details. For tests and examples, we use env_logger as the logger and use test-log to enable logging for tests. For instance you can show all test logs using:

RUST_LOG=debug cargo test integration_success -- --nocapture

We also enabled the logging for the examples. For instance you can do:

RUST_LOG=debug cargo run --example query _printer._tcp

Structs§

DnsNameChange: Represents a name change due to a name conflict resolution. See RFC 6762 section 9
Receiver: A handler to receive messages from ServiceDaemon. Re-export from flume crate. The receiving end of a channel.
ResolvedService: Represents a resolved service as a plain data struct. This is from a client (i.e. querier) point of view.
ServiceDaemon: A daemon thread for mDNS
ServiceInfo: Complete info about a Service Instance.
TxtProperties: Represents properties in a TXT record.
TxtProperty: Represents a property in a TXT record.

Enums§

DaemonEvent: Some notable events from the daemon besides ServiceEvent. These events are expected to happen infrequently.
DaemonStatus: Status code for the service daemon.
Error: A basic error type from this library.
HostnameResolutionEvent: All possible events sent to the client from the daemon regarding host resolution.
IfKind: Specify kinds of interfaces. It is used to enable or to disable interfaces in the daemon.
RRType: DNS resource record types, stored as u16. Can do as u16 when needed.
ServiceEvent: All possible events sent to the client from the daemon regarding service discovery.
UnregisterStatus: Response status code for the service unregister call.

Constants§

IP_CHECK_INTERVAL_IN_SECS_DEFAULT: The default interval for checking IP changes automatically.
SERVICE_NAME_LEN_MAX_DEFAULT: The default max length of the service name without domain, not including the leading underscore (_). It is set to 15 per RFC 6763 section 7.2.
VERIFY_TIMEOUT_DEFAULT: The default time out for ServiceDaemon::verify is 10 seconds, per RFC 6762 section 10.4

Traits§

AsIpAddrs: This trait allows for parsing an input into a set of one or multiple Ipv4Addr.
IntoTxtProperties: This trait allows for converting inputs into TxtProperties.

Type Aliases§

Metrics: The metrics is a HashMap of (name_key, i64_value). The main purpose is to help monitoring the mDNS packet traffic.
Result: One and only Result type from this library crate.

Crate mdns_sdCopy item path