hick 0.1.0

Batteries-included, runtime-agnostic mDNS / DNS-SD for Rust — a Sans-I/O protocol core with pluggable async drivers.

Introduction

hick is the high-level entry point to the hick mDNS family. It wires the Sans-I/O protocol core (mdns-proto) to a ready-to-use async driver (hick-reactor) so you can publish and discover services on the local network in a few lines, with tokio out of the box.

mDNS (Multicast DNS, RFC 6762) and DNS-SD (RFC 6763) let peers discover one another on a local link with no central DNS server — the basis of "zeroconf" service discovery. Note that many cloud and shared-infrastructure networks restrict multicast, so mDNS is best suited to office, home, or private networks.

Highlights

• Sans-I/O core. All protocol logic lives in mdns-proto as pure state machines — no sockets, threads, or clocks — making it deterministic and exhaustively unit-tested. The drivers only shuttle bytes and time in and out.
• Runtime-agnostic. Drive it from tokio, smol, or compio (thread-per-core) with no change to protocol behavior.
• no_std and bare-metal. The core runs on alloc — or heapless, with no allocator at all — and hick-smoltcp / hick-embassy bring full mDNS to embedded targets over smoltcp.
• RFC 6762 / 6763 conformant. Probing and announcing, name-conflict detection with automatic renaming, known-answer and duplicate-question suppression, TTL-accurate caching, and TTL=0 goodbyes on withdrawal.
• unsafe-minimal. The protocol core is #![forbid(unsafe_code)]; unsafe is confined to the platform socket and control-message plumbing.
• Observable, à la carte. Opt into tracing spans, metrics counters, pollable stats, or defmt on embedded — each behind a feature flag and compiled out when unused.

The family

The crates split protocol logic from I/O, mirroring the quinn layering:

Installation

[dependencies]
hick = "0.1" # tokio runtime by default

For smol instead of tokio:

[dependencies]
hick = { version = "0.1", default-features = false, features = ["smol"] }

For the compio (completion-based, thread-per-core) runtime:

[dependencies]
hick = { version = "0.1", default-features = false, features = ["compio"] }

For bare-metal (no_std) targets, enable smoltcp (the runtime-agnostic engine) or embassy (the embassy-net async driver) — neither pulls in std:

[dependencies]
hick = { version = "0.1", default-features = false, features = ["embassy"] }

Each driver is also published as a standalone crate (hick-compio, hick-smoltcp, hick-embassy) if you would rather depend on it directly.

The minimum supported Rust version (MSRV) is 1.91.0 (edition 2024).

Example

Common, runtime-agnostic types (Name, QuerySpec, ServiceSpec, …) live at the crate root; the runtime-pinned entry point and driver handles live in the per-runtime module (hick::tokio, hick::smol).

use hick::{Name, QuerySpec, ServiceRecords, ServiceSpec, wire::ResourceType};
use hick::tokio::{server, QueryEvent, ServerOptions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Start the driver, pinned to the tokio runtime.
    let endpoint = server(ServerOptions::default()).await?;

    // Advertise a service. Keep the returned handle alive to keep advertising;
    // dropping it withdraws the service (TTL=0 goodbye) and unregisters it.
    let mut records = ServiceRecords::new(
        Name::try_from_str("_http._tcp.local.")?,            // service type
        Name::try_from_str("My Device._http._tcp.local.")?,  // instance
        Name::try_from_str("my-device.local.")?,             // host
        80,                                                  // port
        120,                                                 // TTL (seconds)
    );
    records.add_a([192, 168, 1, 10].into());
    let _service = endpoint.register_service(ServiceSpec::new(records)).await?;

    // Discover services of a type on the local link.
    let mut query = endpoint
        .start_query(QuerySpec::new(
            Name::try_from_str("_ipp._tcp.local.")?,
            ResourceType::Ptr,
        ))
        .await?;
    while let Some(event) = query.next().await {
        match event {
            QueryEvent::Answer(answer) => println!("{answer:?}"),
            QueryEvent::Terminal(_) => break,
        }
    }
    Ok(())
}

Feature flags

• tokio (default) — drive the tokio runtime via hick-reactor.
• smol — drive the smol runtime.
• compio — drive the compio (thread-per-core) runtime via hick-compio.
• smoltcp — expose the bare-metal hick-smoltcp engine (no_std + alloc).
• embassy — expose the hick-embassy async driver (no_std + alloc).
• tracing — forward structured tracing spans/events from every enabled driver and the proto core.
• stats — enable no_std-safe atomic counters; read a snapshot via endpoint.stats().
• metrics — bridge counters to the metrics facade (Prometheus/StatsD exporters). Implies stats.
• defmt — forward defmt log events to the bare-metal drivers (hick-smoltcp / hick-embassy). Has no effect when only std drivers are enabled.

Observability

tracing — structured events and spans

Add features = ["tracing"] and install a subscriber in main:

fn main() {
    tracing_subscriber::fmt().init();
    // … start your endpoint …
}

The driver task and mdns-proto emit tracing events at DEBUG / INFO / WARN level during probing, service registration, conflict resolution, cache updates, and query completion.

metrics — Prometheus / StatsD counters

Add features = ["metrics"] and install a recorder before starting the endpoint:

// Example using the prometheus exporter from the `metrics-exporter-prometheus` crate:
metrics_exporter_prometheus::PrometheusBuilder::new().install().unwrap();

All mDNS counters (packets, bytes, cache hits, queries, …) are forwarded automatically under mdns_* metric names.

stats — polling counters without a recorder

When you only need periodic read-outs without a full metrics exporter, enable stats and call endpoint.stats():

use hick::tokio::{server, ServerOptions};

let endpoint = server(ServerOptions::default()).await?;
// … run for a while …
let snap = endpoint.stats();
println!("rx={} tx={} cache_size={}", snap.packets_rx, snap.packets_tx, snap.cache_size);

stats() returns a hick_trace::stats::StatsSnapshot — a plain Copy struct of u64 fields covering packets, bytes, cache, queries, services, probes, conflicts, and more. See the hick-trace crate for the full list.

defmt — bare-metal embedded logging

For no_std targets using hick-smoltcp or hick-embassy, enable defmt instead of (or alongside) stats. Log events are forwarded through the defmt framework. On std drivers this feature is a no-op.

Per-crate observability details: hick-trace (shim) · mdns-proto · hick-reactor · hick-compio · hick-smoltcp · hick-embassy · hick-udp.

License

hick is under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE, LICENSE-MIT for details.

Copyright (c) 2025 Al Liu.