andrewdavidmackenzie / simpdiscover

Simple UDP Discovery rust crate

Simpdiscover

Simpdiscover is a simple rust crate to facilitate discovery of services within the Local Area network (LAN) using UDP Broadcast datagrams or "beacons".

The 'announcer' of a service could be a process on another machines, or another threads or process on the same machine.

Goals

• LAN wide detection of named services and what IP they are at
• Simple to understand and use
• Small, few dependencies on the library and small memory and cpu footprint
• Simple beacon format that is easy to use and that doesn't introduce specific file format support into the library

Non-Goals

• Discovery of services across LANs, WANs, the Web or in the cloud.

Implemented so far

• BeaconSender struct that can be setup to send beacons:
  • with a specific beacon content String
  • on a specific port
  • with methods to:
    • send forever in a loop at a given time period
    • send just one beacon
• Simple BeaconListener struct that can be setup to receive beacons:
  • matching a specific message contents
  • with a method that blocks sender and waits until a message is received
    • with an optional timeout value to wait for or None to wait indefinitely
• Simple 'announce' and 'listen' binaries that use the library as examples
• A some Doc tests to keep the API docs correct
• Github Action to build then clippy check then test all

'announce' binary

Run this binary from the repo using cargo run --bin announce or just announce if you have installed the crate with cargo.

It takes an optional command line parameter to specify the String for the beacon message to announce: cargo run --bin announce -- Hello

'listen' binary

Run this binary from the repo using cargo run --bin listen or just listen if you have installed the crate with cargo.

It takes an optional command line parameter to specify the String for the beacon message to wait for before exiting: cargo run --bin listen -- Hello

Future work

I have taken most of my notes on future work and converted them into GitHub issues.

Some are just questions about things I don't understand and would love experts on UDP and rust to explain them to me.

Please comment or start any you are interested in being implemented.

PRs are obviously welcome, if accompanied by some doc comments, doc tests or tests.

Developers

• Clone/Fork the repo and download:
• cd into the directory
• Add changes, add doc comments and/or doc tests and tests.
• cargo build
• cargo test
• cargo clippy -- -D warnings
• Create a PR
• Github actions will run the same steps as above
• I will review and merge

simpdiscover's Issues

Question: What is the correct IP and port for binding to for sending broadcast messages?

This works currently, but I'm not sure it's correct.

    // Setting the port to non-zero (or at least the same port used in listener) causes
    // this to fail. I am not sure of the correct value to use. Docs on UDP says '0' is
    // permitted, if you do not expect a response from the UDP Datagram sent.
    let bind_address = "0.0.0.0:0";

Start sender in background

Maybe do with async code and allow it to have multiple timers and beacons sending, avoiding a thread per beacon/timing

Add port and protocol fields to beacon

so that we can announce a service on a different port from the datagram being sent on, and to know more about how to connect to it: IP (done), port and protocol (http etc etc).

Supply closure to run on beacon detection

Call to wait for a beacon and then run a supplied closure when it is found?

Service meta-data

• include an arbitrary Byte sequence to also send as meta-data
  client must serialize so we don't need to include a serialization lib or format

regex to match beacon received

• supply an optional regex to match the beacon name
  https://crates.io/crates/regex
  to filter responses.
  Make that feature and the crate inclusion behind a feature to keep the
  project as small as possible.

Question: Why doesn't other broadcast address work?

One works, the other doesn't any idea why?

//const BROADCAST_ADDRESS : &str = "192.168.2.255";
const BROADCAST_ADDRESS : &str = "255.255.255.255";