Edge Registration

Purpose

Describe how an edge node joins the platform and maintains its connection.

Overview

Each edge runs a node agent and an edge-bound call engine. The node agent registers over node-authenticated HTTP, heartbeats, reconciles desired state, and runs media/recording sync. The call engine consumes the tenant’s originate subject over NATS and drives FreeSWITCH via ESL.

Register: POST /api/v1/nodes/register (with retry/backoff). The response carries an API key, persisted to node.key and presented as a Bearer token on all later calls.
Heartbeat: POST /api/v1/nodes/heartbeat every 30s.
Desired state: GET /api/v1/edge/desired-state?node_id=&since= (304 when unchanged), which the agent materializes into config (carrier gateways, outbound dialplan, TLS certs).

Configuration

NODE_ID=edge-01                    # must match the pacer's originate target
TENANT_ID=<customer edge tenant>   # the single tenant this edge serves
NATS_URL=nats://edge_<TENANT_UUID>:<pw>@nats-host:4222
ESL_PASSWORD=...                   # FreeSWITCH ESL (must match across edge services)
EDGE_MEDIA_ROOT=/var/lib/get2dial/media
AGENT_RECONCILE_INTERVAL_SECONDS=30

Examples

On boot the node agent registers and begins heartbeating; the call engine subscribes to t.<tenant>.node.<NODE_ID>.call.originate and is ready to place calls. The agent also serves ACME HTTP-01 challenges and applies fanned-out TLS chains for the OpenSIPS WSS listener.

Notes

Exactly one call engine should consume a tenant’s originate subject — duplicates compete and double-dial. A NODE_ID mismatch silently dials zero.
Per-tenant NATS/Redis credentials are minted centrally (provision-edge); rotation requires the edge .env to be redeployed.
/nodes/register and /nodes/heartbeat are network-gated (unauthenticated by design in the current posture); data endpoints require the node API key.