Crate ebus_discovery 

eBus DNS-SD contract.

The service types an eBus entity advertises and browses (framework.md, “Detail: mDNS Discovery”), the broker transports with the specification’s preference order, the broker modes, and address scopes. With alloc: TXT record decoding, checks and building; the advertisement model; merging the sightings an mDNS backend reports into instances; and broker ranking and selection, including the BrokerSearch state machine.

The crate performs no I/O and reads no clock: backends in a runtime crate feed it sightings and the time as an Instant. Where the specification leaves a choice open it follows python-service-discovery.

A search for a plain MQTT broker, fed one sighting by hand where a backend would report it:

use ebus_discovery::{
    BrokerConfig, BrokerSearch, Instant, InstanceKey, ScopedAddr, Sighting, Slot, TxtRecord,
};

let mut search = BrokerSearch::new(Instant(0), BrokerConfig::default())?;
search.handle(
    Instant(0),
    Sighting::Seen {
        key: InstanceKey {
            service_type: "_mqtt._tcp".into(),
            name: "site-broker".into(),
        },
        slot: Slot::Whole,
        server: "broker.local.".into(),
        port: 1883,
        txt: TxtRecord::new(),
        addrs: vec![ScopedAddr::new([192, 168, 1, 10].into())],
    },
);
while let Some(at) = search.poll_timeout() {
    search.handle_timeout(at);
    if search.result().is_some() {
        break;
    }
}
let broker = search.result().expect("a broker");
assert_eq!((broker.host.as_str(), broker.port), ("broker.local", 1883));

Features

• std (default): links std; implies alloc.
• alloc: everything that allocates: TXT records, the advertisement model, instances, broker ranking and BrokerSearch.
• log: diagnostics through the log crate.

Structs

Advertisementalloc

Everything a host advertises, all under one instance name.

BrokerConfigalloc

How a host finds its broker, from its defaults overridden by its REST “MQTT broker configuration” (framework.md:93, 607).

BrokerEndpointalloc

A broker to connect to, discovered or configured.

BrokerSearchalloc

One broker search, with no I/O: the backend’s sightings and the time go in; requeries and, once, the result come out.

BrokerServicealloc

A broker this host runs (ebus.py:494-546; framework.md:299-326).

EbusTxtalloc

A parsed _ebus._tcp TXT record (ebus.py:178-216).

HttpServicealloc

A REST API advertised as _http._tcp or _https._tcp (ebus.py:445-477).

Identityalloc

An entity’s _ebus._tcp and _device-info._tcp content (ebus.py:330-438).

Instancealloc

A service instance as the table holds it.

InstanceKeyalloc

A service instance’s identity: its type and instance name.

InstanceTablealloc

The instances a backend currently reports, keyed by (service type, instance name), with no I/O.

Instant

Milliseconds on the caller’s monotonic clock.

ParseModeError

A broker mode string that names no mode.

ScopedAddr

An address an mDNS backend reported, with the interface it was seen on.

ServiceRecordalloc

One service an advertisement registers.

TxtRecordalloc

A DNS-SD TXT record: ordered keys, each with a value or none.

TxtReportalloc

What check_txt found near the limits; nothing here stops a record.

Enums

AddrScope

The reachability class of an address, declared in candidate preference order (record.py:51-61): routable addresses before link-local ones.

BrokerConfigErroralloc

A broker configuration a search cannot run with.

BrokerMode

How an entity finds its broker (framework.md:102, 614-622).

BrokerType

A broker transport, declared in the specification’s preference order (framework.md:330-335), so Ord ranks the most preferred first. That order is the default; a client sets its own with BrokerConfig::accept.

Sightingalloc

One report from a backend.

Slotalloc

Where a backend resolved an instance.

TxtErroralloc

A TXT record mDNS cannot carry, or an advertisement that cannot be built.

UrlErroralloc

A configured broker URL that cannot be used.

Wantedalloc

The particular broker a host wants among those discovered.

Constants

BROKER_TYPES

Every broker type, in the specification’s preference order.

DEVICE_INFO_SERVICE

The _device-info._tcp service every eBus entity advertises (framework.md:77).

EBUS_SERVICE

The _ebus._tcp service every eBus entity advertises (framework.md:77).

EBUS_VERSION

The framework.md version this crate implements, the default ebus_version TXT value: the framework value in .ebus-spec.json.

HTTPS_SERVICE

An HTTPS REST API (framework.md:79).

HTTP_SERVICE

A plain HTTP REST API (framework.md:79).

MAX_DEFAULT_INSTANCE_OCTETSalloc

Longest device id used as the default instance name: one 63-octet DNS label less the -99 suffix.

MAX_RENAME_SUFFIXalloc

Instance-name suffixes tried on a collision: -2 through -99.

ROLE_BROKER_HOST

The broker-host role (framework.md:106, 248).

ROLE_CONTROLLER

The controller role (framework.md:248).

ROLE_DEVICE

The device role (framework.md:248).

TCP_BROKER_TYPES

The broker types an MQTT-over-TCP client can use; the accepted types when no TLS is configured (ebus.py:54).

TXTVERS

The txtvers value of every record this crate builds.

TXT_STRING_MAXalloc

Longest single TXT string (key=value): one length byte.

TXT_STRING_WARNalloc

A TXT string longer than this is reported by check_txt.

TXT_TOTAL_WARNalloc

A TXT record longer than this on the wire is reported by check_txt (RFC 6763 section 6.2).

Functions

candidate_addressesalloc

The addresses worth trying, most preferred first: ScopedAddr::is_candidate ones, ordered by AddrScope::preference, then by address, without duplicates.

check_txtalloc

Check that mDNS can carry txt (ebus.py:282-311): every key non-empty, without = and printable ASCII, and every string at most TXT_STRING_MAX bytes. Strings and records near the limits are listed in the report and logged as warnings.

is_local_name

True for a name in the .local mDNS domain, ignoring ASCII case and a trailing dot.

match_configuredalloc

The discovered broker that is the configured one (ebus.py:712-742).

parse_ebus_txtalloc

Parse an _ebus._tcp record: roles, device_id and auth_methods are comma-separated lists, and a missing key parses as empty.

rank_brokersalloc

One endpoint per distinct broker, ranked in the client’s preference order (ebus.py:675-702).

same_host

True when two host names are equal ignoring case and one trailing dot each (ebus.py:661-662).

select_brokeralloc

Choose the broker to connect to (ebus.py:745-795).

strip_dot

name without one trailing dot (instance.py:18-20).