Conduit.Node

Conduit.Node — multi-node cluster registration and leader election.

Each Conduit process that calls Conduit.Node.start registers itself in the conduit_workers DB table and maintains its registration via three background tasks:

heartbeat task  — updates `last_seen_at` every `heartbeat_interval_ms`.
stale task      — reclaims jobs from dead workers and purges stale node rows.
leader task     — tries to acquire a Postgres advisory lock (id 8473625);
                  the holder is the cluster leader.

Leader state is stored in Vault (in-process) so is_leader() and leader_node_id() are O(1) reads with no DB round-trip.

Hostname detection ───────────────── pbuild_node_info reads the HOSTNAME environment variable (set automatically in most container environments). If unset, it falls back to "localhost". Override via CONDUIT_HOSTNAME for bare-metal deployments that use a non-standard env variable.

Functions

fnis_leaderis_leader() : Bool#

Return true if this node is the current cluster leader.

Fast in-process Vault read — no DB round-trip.  Updated by the leader task
on every heartbeat cycle.

fnleader_node_idleader_node_id() : Option(String)#

Return the node_id of the last known cluster leader, or None.

Updated by the leader task each time it wins (or confirms) the advisory lock.
May lag by up to one heartbeat interval when the leader changes.

fnstartstart(storage : s, config : Conduit.Config) : List(Task(()))#

Inserts a NodeInfo row into `conduit_workers`, then spawns:
  • A heartbeat task that pings the DB every `heartbeat_interval_ms`.
  • A stale-detection task that reclaims orphaned jobs and prunes dead nodes.
  • A leader-election task that competes for the advisory lock each heartbeat.

Must be called once at application startup (from `Conduit.API.start`).
Returns the list of task handles; keep them alive for the lifetime of the node.

fnstopstop(storage : s, node_id : String) : ()#

Deregister this node on graceful shutdown.

Removes the node row from `conduit_workers` and releases the advisory leader
lock if this node currently holds it.  Call during application shutdown before
the process exits.