Skip to content

beacon

diapason.mesh.beacon

How a device says « je suis là » to the rest of the fleet.

Until now presence could only be recorded by whoever held this machine's API key — which is to say, by this machine about itself. That made every remote device's presence a fiction, and the whole honest-about-offline machinery had nothing true to stand on: a command could be reported as sent to a device that had been unplugged for a week.

A device announces itself with the same credential it uses to command: an Ed25519 signature over the envelope, verified against the public key recorded when it was paired. No API key is involved, because a joining device never has one.

Replay is stopped by monotonicity rather than by nonces. A heartbeat every fifteen seconds would mint 5 760 nonces per device per day to protect a message whose entire content is "still here"; storing one integer per device and refusing anything not strictly newer costs nothing and refuses the same attack — an attacker replaying a captured beacon cannot make a device that is off look on.

PresenceRejected

Bases: Exception

A beacon that will not be believed, with the reason in French.

announce_to(device, *, address='', app_state='', timeout_s=4.0, post=None)

Tell one peer we are here. False on any failure — never raises.

A beacon that does not arrive is not an error the user should hear about: the peer will simply consider us offline, which is what the honest-presence rules are designed to handle.

announce_to_fleet(*, registry=None, app_state='', post=None)

Announce to every trusted peer whose address we know.

build_beacon(*, owner_id, device_id, app_state='', transport='lan', address='', capabilities=None, app_version='', now=None)

The unsigned envelope, with keys in the order they are signed.

local_address()

The address at which peers can really reach this machine.

A server bound to loopback advertises loopback, even though a LAN address would look more useful: peers off this machine genuinely cannot reach it, and telling them otherwise would send commands into the void and have them reported as delivered.

local_endpoint()

Le socket réellement promis par le processus, sans le deviner.

None avant que la commande serve ait choisi ses sockets. La découverte refuse alors de publier : annoncer un port supposé serait exactement la panne que set_local_endpoint a été créé pour éviter.

set_local_endpoint(host, port)

Record the host and port uvicorn was actually given.

sign_beacon(payload)

Sign with THIS device's private key.

verify_beacon(raw, *, registry, local_owner_id, local_device_id, now=None)

Decide whether to believe raw, and return the accepted device row.

Check order mirrors verify_command: cheap structural checks first, cryptography once the envelope is plausible, and the monotonicity clock advanced LAST — a beacon rejected for another reason must not move the watermark that the legitimate device still needs to clear.