Module discovery 

Discovery file management for the single-instance daemon.

The daemon writes a JSON file to ~/.hyperdb/daemon.json containing its PID and the hyperd endpoint. Clients read this file to locate the running daemon, validating liveness via a TCP health check before trusting it.

Structs

DaemonInfo

Information written by the daemon so clients can discover and connect.

PortScan

Port scan configuration: a base port and the number of ports to scan. When span == 1, the port is pinned (no scan). Used by the later port-scanning stage to discover or spawn a daemon across a range.

Enums

ProbeResult

Result of probing a single port: either our daemon, something else, or refused.

ScanOutcome

The outcome of scanning a port range for a running daemon or a free port to spawn on.

Functions

discover

Read the discovery file and validate that the daemon is still alive. Returns None if no daemon is running (file missing, stale, or unreachable).

discovery_file_path

Returns the path to the discovery file.

find_running_daemon

Discover a running daemon via the discovery file, or by scanning the configured port range. Returns None if no daemon is found in either place.

remove_discovery_file

Remove the discovery file (called during graceful shutdown).

resolve_port

Resolve the daemon health port from environment or default. Back-compat wrapper for single-port callers; returns the base port from resolve_port_scan. New code that needs scan-aware logic should call resolve_port_scan directly.

resolve_port_scan

Resolve the daemon health port scan configuration from environment or default. If HYPERDB_DAEMON_PORT is set and valid, returns a pinned scan (span=1) at that exact port. Otherwise, returns the default base port with the full scan span.

scan_for_daemon

Scan the configured port range to find a running daemon or identify a free port. If any port in the range answers identified-PING and returns valid STATUS, we return Found immediately (first wins). Otherwise, we return FreePort with the first refused port encountered, or AllOccupied if everything is in use.

state_dir

Returns the directory used for daemon state files.

write_discovery_file

Write the discovery file atomically (write-to-temp then rename).