minimost.stun

minimost.stun

A minimal, dependency-free STUN server (RFC 5389) used purely so that WebRTC peers on the LAN gather a server-reflexive ICE candidate carrying their real LAN IP address.

Why this exists

Browsers hide a machine’s real LAN IP behind a random <uuid>.local mDNS host candidate by default. On a LAN without a working mDNS responder (avahi/Bonjour) the remote peer cannot resolve that name, every candidate pair is unusable, and the connection fails with ICE failed (a black screen for screen shares).

Pointing the browser at a STUN server makes it additionally gather a server-reflexive candidate — and unlike host candidates, srflx candidates are not mDNS-obfuscated: they contain the real address the STUN server observed. Because MiniMost is LAN-only there is no NAT between peers, so the reflexed address is directly reachable and the connection succeeds with zero extra configuration — no avahi, no browser flags, no public STUN server (so it works even air-gapped).

This server answers only Binding Requests with a Binding Success Response carrying an XOR-MAPPED-ADDRESS attribute, which is all browsers need for candidate gathering. It does not implement authentication or the full connectivity-check machinery (those happen peer-to-peer, not against this server).

Module-level attributes

DEFAULT_STUN_PORTint

The default UDP port (3478, the IANA-assigned STUN port).

minimost.stun.build_binding_response(data: bytes, addr: tuple) → bytes | None[source]

Build a Binding Success Response for a STUN Binding Request.

Parameters:

  • data (bytes) – The raw datagram received from the client.

  • addr (tuple) – The (ip, port) the datagram was received from.

Returns:

The response datagram, or None if data is not a valid Binding Request this server should answer.

Return type:

bytes or None

minimost.stun._serve_forever(host: str, port: int) → None[source]

Bind a UDP socket and answer STUN Binding Requests forever.

minimost.stun.start_stun_server(port: int = 3478, host: str = '0.0.0.0') → None[source]

Start the STUN server in a daemon thread (idempotent within a process).

Safe to call from minimost.create_app(). The thread is a daemon, so it exits automatically when the process shuts down. Binding 0.0.0.0 is intentional: the server must be reachable by every peer on the LAN.

Parameters:

  • port – UDP port to listen on. Defaults to DEFAULT_STUN_PORT.

  • host – Interface to bind. Defaults to all interfaces.