nserver.transport

CachedConnection dataclass

Dataclass for storing information about a TCP connection

Attributes:

Name	Type	Description
connection	socket	the actual socket we are connected to
remote_address	Tuple[str, int]	the socket's peername
last_data_time	float	timestamp when we last received data from this socket
selector_key	SelectorKey	key used by our TCP Transport's selector
cache_key	CacheKey	the key used to store this connection in the cache

MessageContainer

MessageContainer(
    raw_data: bytes,
    transport: TransportBase,
    transport_data: Any,
    remote_client: Union[str, Tuple[str, int]],
)

Class for holding DNS messages and the transport they originated from.

Used to simplify the interface (and allow for threading etc later).

Create new message container

Parameters:

Name	Type	Description	Default
raw_data	bytes	The raw message pulled from the transport. It will parsed as a DNS message.	required
transport	TransportBase	The transport instance that created this message (e.g. self). Messages must only be returned to this transport instance when responding (even if it would be possible for another instance to respond (e.g. with UDP processing)). As such transports should rely on only receiving messages that they created (opposed to assert message.transport is self).	required
transport_data	Any	Data that the transport instance wishes to store with this message for later use. What is stored is up to the transport, and it is up to the transport implementation to correctly handle it.	required
remote_client	Union[str, Tuple[str, int]]	Representation of the remote client that sent this DNS request. This value is primarily to allow logging and debugging of invalid requests. Whilst transport instances must set this value, they should NOT use it for processing.	required

get_response_bytes

get_response_bytes()

Convert response object to bytes

TCPMessageData dataclass

Message.transport_data for TCP transports

Attributes:

Name	Type	Description
socket	socket	the socket this message was received on

TCPv4Transport

TCPv4Transport(settings: Settings)

Bases: TransportBase

Transport class for IPv4 TCP.

References

• https://tools.ietf.org/html/rfc7766#section-8

receive_message

receive_message() -> MessageContainer

As per parent class

send_message_response

send_message_response(message: MessageContainer) -> None

As per parent class

start_server

start_server(timeout: int = 60) -> None

As per parent class

stop_server

stop_server() -> None

As per parent class

TcpState

Bases: IntEnum

State of a TCP connection

TransportBase

TransportBase(settings: Settings)

Base class for all transports

Parameters:

Name	Type	Description	Default
settings	Settings	settings of the server this transport is attached to	required

receive_message

receive_message() -> MessageContainer

Receive a message from the running server

send_message_response

send_message_response(message: MessageContainer) -> None

Respond to a message that was received by the server

start_server

start_server(timeout: int = 60) -> None

Start transport's server

stop_server

stop_server() -> None

Stop transport's server

UDPMessageData dataclass

Message.transport_data for UDP transports

Attributes:

Name	Type	Description
remote_address	Tuple[str, int]	UDP peername that this message was received from

UDPv4Transport

UDPv4Transport(settings: Settings)

Bases: TransportBase

Transport class for IPv4 UDP.

receive_message

receive_message() -> MessageContainer

As per parent class

send_message_response

send_message_response(message: MessageContainer) -> None

As per parent class

start_server

start_server(timeout=60) -> None

As per parent class

stop_server

stop_server() -> None

As per parent class

UDPv6Transport

UDPv6Transport(settings: Settings)

Bases: UDPv4Transport

Transport class for IPv6 UDP.

receive_message

receive_message() -> MessageContainer

As per parent class

send_message_response

send_message_response(message: MessageContainer) -> None

As per parent class

start_server

start_server(timeout=60) -> None

As per parent class

stop_server

stop_server() -> None

As per parent class

get_tcp_info

get_tcp_info(connection: socket.socket) -> Tuple

Get socket.TCP_INFO from socket

Parameters:

Name	Type	Description	Default
connection	socket	the socket to inspect	required

Returns:

Type	Description
Tuple	Tuple of 28 integers. Strictly speaking the data returned is platform dependent as will be whatever is in /usr/include/linux/tcp.h. For our purposes we cap it at the first 28 values.

get_tcp_state

get_tcp_state(connection: socket.socket) -> TcpState

Get the TcpState of a socket

Parameters:

Name	Type	Description	Default
connection	socket	the socket to inspect	required

recv_data

recv_data(
    data_length: int,
    connection: socket.socket,
    existing_data: bytes = b"",
    timeout: int = 10,
) -> bytes

Receive a given amount of data from a socket.

Parameters:

Name	Type	Description	Default
data_length	int	number of bytes to receive	required
connection	socket	the socket to receive data from	required
existing_data	bytes	data that is added to the response before we collect further data	b''
timeout	int	time before giving up in seconds	10

Raises:

Type	Description
TimeoutError	timeout was reached before we finished receiving the data