TURN module (rfc5766)

Server

TURN server RFC 5766 / RFC 6062 implementation.

Server

#include <icy/turn/server/server.h>

TURN server RFC 5766 / RFC 6062 implementation. Listens on UDP and/or TCP, authenticates requests via ServerObserver, and manages ServerAllocation objects for each 5-tuple.

Public Methods

Return	Name	Description
	`Server`	#### Parameters
`void`	`start` `virtual`	Binds and listens on the configured address, then starts the maintenance timer.
`void`	`stop` `virtual`	Stops the timer, destroys all allocations, and closes server sockets.
`void`	`handleRequest`	Routes an authenticated request to the appropriate handler based on state. Pending (Authenticating) requests are held until the observer calls back.
`void`	`handleAuthorizedRequest`	Dispatches an already-authorized request to the specific method handler.
`void`	`handleBindingRequest`	Handles a Binding request; responds with XOR-MAPPED-ADDRESS.
`void`	`handleAllocateRequest`	Handles an Allocate request; creates a UDP or TCP ServerAllocation and sends a success response with XOR-RELAYED-ADDRESS and LIFETIME.
`void`	`handleConnectionBindRequest`	Handles a ConnectionBind request by locating the TCPAllocation that owns the given CONNECTION-ID and delegating to it.
`void`	`respond`	Sends a STUN response, signing it with MessageIntegrity if the request had a hash. Routes via UDP or TCP depending on request.transport.
`void`	`respondError`	Constructs and sends an error response with SOFTWARE, REALM, NONCE, and ERROR-CODE.
`std::map< FiveTuple, ServerAllocation * >`	`allocations` `const`	Returns a snapshot copy of the allocation map for safe iteration. Returned raw pointers are valid only while the server holds the allocations.
`void`	`addAllocation`	Transfers ownership of `alloc` to the server and notifies the observer.
`void`	`removeAllocation`	Removes `alloc` from the map and notifies the observer. Called automatically from the ServerAllocation destructor.
`ServerAllocation *`	`getAllocation`	Looks up an allocation by its 5-tuple.
`TCPAllocation *`	`getTCPAllocation`	Finds the TCPAllocation that owns a TCPConnectionPair with the given connection ID.
`net::TCPSocket::Ptr`	`getTCPSocket`	Returns the accepted TCP socket whose peer address matches `remoteAddr`.
`void`	`releaseTCPSocket`	Removes a TCP control socket from the server's socket list and unregisters callbacks. Called when the socket is handed off to a TCPAllocation (ConnectionBind).
`ServerObserver &`	`observer`	#### Returns
`const ServerOptions &`	`options` `const`	#### Returns
`net::UDPSocket &`	`udpSocket`	#### Returns
`net::TCPSocket &`	`tcpSocket`	#### Returns
`Timer &`	`timer`	#### Returns
`void`	`onTCPAcceptConnection`	Accept callback for the TCP listening socket; registers new connections for STUN message processing.
`bool`	`onTCPSocketClosed`	Close callback for accepted TCP sockets; removes the socket from the list.
`bool`	`onSocketRecv`	Receive callback for both UDP and TCP sockets; parses STUN messages and calls handleRequest() for each one.
`void`	`onTimer`	Periodic maintenance callback; expires and removes stale allocations.
`void`	`scheduleDeferredTCPSocketRelease`	Defers accepted TCP socket removal until after the active callback stack unwinds.
`void`	`drainReleasedTCPSockets`

Server

Server(ServerObserver & observer, const ServerOptions & options)

Parameters

observer Observer used for authentication and allocation lifecycle events.
options Server configuration; defaults to 0.0.0.0:3478 with TCP and UDP enabled.

start

virtual

virtual void start()

Binds and listens on the configured address, then starts the maintenance timer.

stop

virtual

virtual void stop()

Stops the timer, destroys all allocations, and closes server sockets.

handleRequest

void handleRequest(Request & request, AuthenticationState state)

Routes an authenticated request to the appropriate handler based on state. Pending (Authenticating) requests are held until the observer calls back.

Parameters

request Incoming STUN request.
state Result of the observer's authenticateRequest() call.

handleAuthorizedRequest

void handleAuthorizedRequest(Request & request)

Dispatches an already-authorized request to the specific method handler.

Parameters

request Authorized STUN request.

handleBindingRequest

void handleBindingRequest(Request & request)

Handles a Binding request; responds with XOR-MAPPED-ADDRESS.

Parameters

request Incoming Binding request.

handleAllocateRequest

void handleAllocateRequest(Request & request)

Handles an Allocate request; creates a UDP or TCP ServerAllocation and sends a success response with XOR-RELAYED-ADDRESS and LIFETIME.

Parameters

request Incoming Allocate request.

handleConnectionBindRequest

void handleConnectionBindRequest(Request & request)

Handles a ConnectionBind request by locating the TCPAllocation that owns the given CONNECTION-ID and delegating to it.

Parameters

request Incoming ConnectionBind request.

respond

void respond(Request & request, stun::Message & response)

Sends a STUN response, signing it with MessageIntegrity if the request had a hash. Routes via UDP or TCP depending on request.transport.

Parameters

request The original request (provides transport and remote address).
response The response message to send.

respondError

void respondError(Request & request, int errorCode, const char * errorDesc)

Constructs and sends an error response with SOFTWARE, REALM, NONCE, and ERROR-CODE.

Parameters

request The original request.
errorCode STUN error code (e.g. 400, 401, 437).
errorDesc Human-readable error description string.

allocations

const

std::map< FiveTuple, ServerAllocation * > allocations() const

Returns a snapshot copy of the allocation map for safe iteration. Returned raw pointers are valid only while the server holds the allocations.

Returns

Map from FiveTuple to raw ServerAllocation pointers.

addAllocation

void addAllocation(std::unique_ptr< ServerAllocation > alloc)

Transfers ownership of alloc to the server and notifies the observer.

Parameters

alloc Newly constructed allocation to register.

removeAllocation

void removeAllocation(ServerAllocation * alloc)

Removes alloc from the map and notifies the observer. Called automatically from the ServerAllocation destructor.

Parameters

alloc Allocation being destroyed.

getAllocation

ServerAllocation * getAllocation(const FiveTuple & tuple)

Looks up an allocation by its 5-tuple.

Parameters

tuple The 5-tuple to search for.

Returns

Pointer to the matching allocation, or nullptr if not found.

getTCPAllocation

TCPAllocation * getTCPAllocation(const uint32_t & connectionID)

Finds the TCPAllocation that owns a TCPConnectionPair with the given connection ID.

Parameters

connectionID TURN CONNECTION-ID to search for.

Returns

Pointer to the owning TCPAllocation, or nullptr if not found.

getTCPSocket

net::TCPSocket::Ptr getTCPSocket(const net::Address & remoteAddr)

Returns the accepted TCP socket whose peer address matches remoteAddr.

Parameters

remoteAddr Peer address to search for.

Returns

Shared pointer to the socket, or empty if not found.

releaseTCPSocket

void releaseTCPSocket(const net::Socket & socket)

Removes a TCP control socket from the server's socket list and unregisters callbacks. Called when the socket is handed off to a TCPAllocation (ConnectionBind).

Parameters

socket The socket to release.

observer

ServerObserver & observer()

Returns

Reference to the observer provided at construction.

options

const

const ServerOptions & options() const

Returns

Reference to the immutable options struct.

udpSocket

net::UDPSocket & udpSocket()

Returns

Reference to the UDP server socket.

tcpSocket

net::TCPSocket & tcpSocket()

Returns

Reference to the TCP server listening socket.

timer

Timer & timer()

Returns

Reference to the maintenance timer.

onTCPAcceptConnection

void onTCPAcceptConnection(const net::TCPSocket::Ptr & sock)

Accept callback for the TCP listening socket; registers new connections for STUN message processing.

Parameters

sock Newly accepted TCP socket.

onTCPSocketClosed

bool onTCPSocketClosed(net::Socket & socket)

Close callback for accepted TCP sockets; removes the socket from the list.

Parameters

socket The closed socket.

onSocketRecv

bool onSocketRecv(net::Socket & socket, const MutableBuffer & buffer, const net::Address & peerAddress)

Receive callback for both UDP and TCP sockets; parses STUN messages and calls handleRequest() for each one.

Parameters

socket The receiving socket.
buffer Received data buffer.
peerAddress Source address of the data.

onTimer

void onTimer()

Periodic maintenance callback; expires and removes stale allocations.

scheduleDeferredTCPSocketRelease

void scheduleDeferredTCPSocketRelease()

Defers accepted TCP socket removal until after the active callback stack unwinds.

drainReleasedTCPSockets

void drainReleasedTCPSockets()

Private Attributes

Return	Name	Description
`std::mutex`	`_mutex`
`ServerObserver &`	`_observer`
`ServerOptions`	`_options`
`net::SocketEmitter`	`_udpSocket`
`net::SocketEmitter`	`_tcpSocket`
`std::vector< net::SocketEmitter >`	`_tcpSockets`
`std::unordered_set< const net::Socket * >`	`_pendingReleasedTCPSockets`
`bool`	`_tcpSocketReleaseScheduled`
`ServerAllocationMap`	`_allocations`
`Timer`	`_timer`

_mutex

std::mutex _mutex

_observer

ServerObserver & _observer

_options

ServerOptions _options

_udpSocket

net::SocketEmitter _udpSocket

_tcpSocket

net::SocketEmitter _tcpSocket

_tcpSockets

std::vector< net::SocketEmitter > _tcpSockets

_pendingReleasedTCPSockets

std::unordered_set< const net::Socket * > _pendingReleasedTCPSockets

_tcpSocketReleaseScheduled

bool _tcpSocketReleaseScheduled {false}

_allocations

ServerAllocationMap _allocations

_timer

Timer _timer

Built with