@spec add_remote_candidate(peer_ref(), candidate() | XMediaLib.SDP.Candidate.t()) ::
  :ok | {:error, term()}

Adds a remote ICE candidate (Trickle ICE, RFC 8838).

Accepts %Candidate{} or a map with :candidate (line or struct), optional :mid, :mline_index, and :end_of_candidates.

@spec apply_descriptions(peer_ref(), sdp(), sdp(), keyword()) ::
  :ok | {:error, term()}

Applies negotiated remote offer and local answer (produced upstream by XSDP).

Initializes ICE-lite credentials and transport config from %XMediaLib.SDP{} or SDP binaries. Validates local fingerprint against the listener certificate when a listener is attached.

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec close(peer_ref()) :: :ok | {:error, term()}

Tears down ICE/DTLS and stops the peer process.

@spec connect_dtls(
  peer_ref(),
  XGW.SRTPSession.keys(),
  {:inet.ip_address(), :inet.port_number()} | nil
) ::
  :ok

Test helper: install SRTP keys and enter media phase (skips live DTLS).

@spec connect_ice(peer_ref(), {:inet.ip_address(), :inet.port_number()} | nil) :: :ok

Test helper: force ICE connected with optional selected from endpoint.

@spec deliver(peer_ref(), packet_kind(), binary(), map()) :: :ok

Delivers a demuxed packet from the Listener (STUN, DTLS, RTP, RTCP, ChannelData).

Fills :arrival_us on meta when missing. The Listener stamps this at demux time; this fallback covers tests and any inject path that skips the Listener.

@spec ice_phase(peer_ref()) :: XGW.ICE.ice_phase()

Returns the ICE agent phase.

Lite peers report :completed (binding-only path). Full peers report the ICE state machine phase from XGW.ICE.Full (for example :gathering).

@spec ice_restart(peer_ref(), sdp()) :: :ok | {:error, term()}

Signals ICE restart with a new remote offer (RFC 8445 section 9.1.1.1).

Full ufrag/pwd rotation and checklist reset: Full.ice_restart/1 resets state; remote credentials come from the restart offer. Local ufrag/pwd unchanged in v1.

@spec local_candidates(peer_ref()) :: [XMediaLib.SDP.Candidate.t()]

Returns local ICE candidates stored in the full ICE agent.

Lite peers return []; use XGW.Listener.host_candidate/1 for lite host lines.

@spec open_datachannel(peer_ref(), binary(), keyword()) ::
  {:ok, map()} | {:error, term()}

Opens a local data channel (DCEP) after the SCTP association is connected.

Synthesizes {:xgw, :datachannel, peer, info} to the handler so Session / Backend register the label the same way as a remote open. Returns {:error, :not_connected} when SCTP is missing or not connected.

@spec outbound_handle(peer_ref()) ::
  {:ok, XGW.Peer.SendHandle.t()} | {:error, :not_ready | :use_genserver}

Returns a hot-path send handle when UDP media is published in ETS.

Prefer XGW.Peer.SendHandle.send_rtp/3 for Echo/SFU forwarding. Returns {:error, :not_ready} before media, or {:error, :use_genserver} for ICE-TCP.

@spec phase(peer_ref()) :: phase()

Returns the Peer's media phase (:ice_wait, :dtls_wait, :media, :closed).

@spec prefetch_relay_candidates(peer_ref()) ::
  {:ok, [String.t()]} | {:error, :no_relay_candidates | term()}

Allocates TURN relay candidates once and keeps the allocations on the peer.

Used by relay-only answer builders so apply_descriptions/3 can seed those relay locals without a second Allocate on the same 5-tuple.

@spec send_datachannel(peer_ref(), reference(), binary(), :string | :binary) ::
  :ok | {:error, term()}

Sends a DataChannel user message after SCTP is up.

Routes to XGW.Peer.Datachannel when that child is published; otherwise the Peer GenServer (tests / pre-attach). type is :string (PPI 51, default) or :binary (PPI 53).

@spec send_datachannel_async(peer_ref(), reference(), binary(), :string | :binary) ::
  :ok

Queues a DataChannel user message without waiting for SCTP/DTLS flush.

Prefer XGW.Peer.SendHandle.send_datachannel/3 when a :dc_passthrough row is published (benches). Production Forwarder fallback casts the per-Peer XGW.Peer.Datachannel process (batched drain) when published; otherwise the Peer GenServer. type defaults to :string (PPI 51).

@spec send_rtcp(peer_ref(), binary() | XMediaLib.Rtcp.t()) :: :ok | {:error, term()}

Sends plaintext RTCP toward the peer (SRTCP-encrypted on the wire).

Same phase and error semantics as send_rtp/3.

@spec send_rtp(peer_ref(), non_neg_integer(), binary() | XMediaLib.Rtp.t()) ::
  :ok | {:error, term()}

Sends plaintext RTP toward the peer (SRTP-encrypted on the wire).

Requires :media phase. On UDP, uses the same ETS encrypt path as SendHandle.send_rtp/3. Returns {:error, :not_connected}, {:error, :no_selected_pair}, {:error, :invalid_packet}, or an SRTP/UDP error.

@spec send_rtp_async(peer_ref(), non_neg_integer(), binary() | XMediaLib.Rtp.t()) ::
  :ok

Queues plaintext RTP toward the peer without waiting for encrypt/send.

Prefer outbound_handle/1 + SendHandle.send_rtp/3 when a handle is available; this cast remains a fallback (ICE-TCP, missing handle).

@spec set_handler(peer_ref(), pid()) :: :ok | {:error, term()}

Replaces the process that receives Peer notifications (:rtp, lifecycle, ...).

Used when a Session installs a media forwarder as handler: after start, or when tests retarget delivery. handler must be a live pid.

@spec start_link(keyword()) :: {:ok, peer_ref()} | {:error, term()}

Starts a peer under XGW.PeerSupervisor.

Required: :handler (pid). Optional: :listener, :ice_lite (default true; false selects XGW.ICE.Full), :consent_interval_ms (default 5000), :consent_timeout_ms (default 30000), :cert_dir (unused here; listener owns certs).

@spec start_supervised(keyword()) :: {:ok, peer_ref()} | {:error, term()}

Starts a peer as a child of XGW.PeerSupervisor.