Struct Server 

pub struct Server<T: RequestHandler> { /* private fields */ }

A Futures based implementation of a DNS server

Implementations

impl<T: RequestHandler> Server<T>

pub fn new(handler: T) -> Self

Creates a new ServerFuture with the specified Handler.

pub fn with_access( handler: T, denied_networks: impl IntoIterator<Item = IpNet>, allowed_networks: impl IntoIterator<Item = IpNet>, ) -> Self

Creates a new ServerFuture with the specified Handler and denied/allowed networks

pub fn register_socket(&mut self, socket: UdpSocket)

Register a UDP socket. Should be bound before calling this function.

pub fn register_listener( &mut self, listener: TcpListener, timeout: Duration, response_buffer_size: usize, )

Register a TcpListener to the Server. This should already be bound to either an IPv6 or an IPv4 address.

To make the server more resilient to DOS issues, there is a timeout. Care should be taken to not make this too low depending on use cases.

Arguments

• listener - a bound TCP socket
• timeout - timeout duration of incoming requests, any connection that does not send requests within this time period will be closed. In the future it should be possible to create long-lived queries, but these should be from trusted sources only, this would require some type of whitelisting.
• response_buffer_size - size of the buffer for outgoing responses per connection

pub fn register_tls_listener_with_tls_config( &mut self, listener: TcpListener, handshake_timeout: Duration, tls_config: Arc<ServerConfig>, ) -> Result<()>

Available on crate feature __tls only.

Register a TlsListener to the Server. The TlsListener should already be bound to either an IPv6 or an IPv4 address.

To make the server more resilient to DOS issues, there is a timeout. Care should be taken to not make this too low depending on use cases.

The TLS ServerConfig should be configured with TLS 1.3 support and the DoT ALPN protocol enabled.

Arguments

• listener - a bound TCP (needs to be on a different port from standard TCP connections) socket
• timeout - timeout duration of incoming requests, any connection that does not send requests within this time period will be closed. In the future it should be possible to create long-lived queries, but these should be from trusted sources only, this would require some type of whitelisting.
• tls_config - rustls server config

pub fn register_tls_listener( &mut self, listener: TcpListener, timeout: Duration, server_cert_resolver: Arc<dyn ResolvesServerCert>, ) -> Result<()>

Available on crate feature __tls only.

Register a TlsListener to the Server by providing a rustls ResolvesServerCert. The TlsListener should already be bound to either an IPv6 or an IPv4 address.

To make the server more resilient to DOS issues, there is a timeout. Care should be taken to not make this too low depending on use cases.

Arguments

• listener - a bound TCP (needs to be on a different port from standard TCP connections) socket
• timeout - timeout duration of incoming requests, any connection that does not send requests within this time period will be closed. In the future it should be possible to create long-lived queries, but these should be from trusted sources only, this would require some type of whitelisting.
• server_cert_resolver - resolver for the certificate and key used to announce to clients

pub fn register_https_listener( &mut self, listener: TcpListener, handshake_timeout: Duration, server_cert_resolver: Arc<dyn ResolvesServerCert>, dns_hostname: Option<String>, http_endpoint: String, ) -> Result<()>

Available on crate feature __https only.

Register a TcpListener for HTTPS (h2) to the Server for supporting DoH (DNS-over-HTTPS). The TcpListener should already be bound to either an IPv6 or an IPv4 address.

To make the server more resilient to DOS issues, there is a timeout. Care should be taken to not make this too low depending on use cases.

Arguments

• listener - a bound TCP (needs to be on a different port from standard TCP connections) socket
• handshake_timeout - timeout duration of incoming requests, any connection that does not send requests within this time period will be closed. In the future it should be possible to create long-lived queries, but these should be from trusted sources only, this would require some type of whitelisting.
• server_cert_resolver - resolver for the certificate and key used to announce to clients
• dns_hostname - the DNS hostname of the H2 server.
• http_endpoint - the HTTP endpoint of the H2 server.

pub fn register_https_listener_with_tls_config( &mut self, listener: TcpListener, handshake_timeout: Duration, tls_config: Arc<ServerConfig>, dns_hostname: Option<String>, http_endpoint: String, ) -> Result<()>

Available on crate feature __https only.

Register a TcpListener for HTTPS (h2) for supporting DoH with the given TLS config.

The TcpListener should already be bound to either an IPv6 or an IPv4 address.

The TLS ServerConfig should be configured with TLS 1.3 support and the DoH ALPN protocol enabled.

To make the server more resilient to DOS issues, there is a timeout. Care should be taken to not make this too low depending on use cases.

Arguments

• listener - a bound TCP (needs to be on a different port from standard TCP connections) socket
• handshake_timeout - timeout duration of incoming requests, any connection that does not send requests within this time period will be closed. In the future it should be possible to create long-lived queries, but these should be from trusted sources only, this would require some type of whitelisting.
• tls_config - a customized ServerConfig to use for TLS.
• dns_hostname - the DNS hostname of the H2 server.
• http_endpoint - the HTTP endpoint of the H2 server.

pub fn register_quic_listener( &mut self, socket: UdpSocket, _timeout: Duration, server_cert_resolver: Arc<dyn ResolvesServerCert>, ) -> Result<()>

Available on crate feature __quic only.

Register a UdpSocket to the Server for supporting DoQ (DNS-over-QUIC). The UdpSocket should already be bound to either an IPv6 or an IPv4 address.

To make the server more resilient to DOS issues, there is a timeout. Care should be taken to not make this too low depending on use cases.

Arguments

• socket - a bound UDP socket
• timeout - timeout duration of incoming requests, any connection that does not send requests within this time period will be closed. In the future it should be possible to create long-lived queries, but these should be from trusted sources only, this would require some type of whitelisting.
• server_cert_resolver - resolver for certificate and key used to announce to clients
• dns_hostname - the DNS hostname of the DoQ server.

pub fn register_quic_listener_and_tls_config( &mut self, socket: UdpSocket, _timeout: Duration, tls_config: Arc<ServerConfig>, ) -> Result<(), NetError>

Available on crate feature __quic only.

Register a UdpSocket for supporting DoQ (DNS-over-QUIC) with the provided TLS config.

The UdpSocket should already be bound to either an IPv6 or an IPv4 address.

The TLS ServerConfig should be configured with TLS 1.3 support and the DoQ ALPN protocol enabled.

To make the server more resilient to DOS issues, there is a timeout. Care should be taken to not make this too low depending on use cases.

Arguments

• socket - a bound UDP socket
• timeout - timeout duration of incoming requests, any connection that does not send requests within this time period will be closed. In the future it should be possible to create long-lived queries, but these should be from trusted sources only, this would require some type of whitelisting.
• tls_config - a customized ServerConfig to use for TLS.
• dns_hostname - the DNS hostname of the DoQ server.

pub fn register_h3_listener( &mut self, socket: UdpSocket, _timeout: Duration, server_cert_resolver: Arc<dyn ResolvesServerCert>, dns_hostname: Option<String>, ) -> Result<()>

Available on crate feature __h3 only.

Register a UdpSocket to the Server for supporting DoH3 (DNS-over-HTTP/3). The UdpSocket should already be bound to either an IPv6 or an IPv4 address.

To make the server more resilient to DOS issues, there is a timeout. Care should be taken to not make this too low depending on use cases.

Arguments

• listener - a bound TCP (needs to be on a different port from standard TCP connections) socket
• timeout - timeout duration of incoming requests, any connection that does not send requests within this time period will be closed. In the future it should be possible to create long-lived queries, but these should be from trusted sources only, this would require some type of whitelisting.
• server_cert_resolver - resolver for certificate and key used to announce to clients

pub fn register_h3_listener_with_tls_config( &mut self, socket: UdpSocket, _timeout: Duration, tls_config: Arc<ServerConfig>, dns_hostname: Option<String>, ) -> Result<(), NetError>

Available on crate feature __h3 only.

Register a UdpSocket for supporting DoH3 (DNS-over-HTTP/3) with the specified TLS config.

The UdpSocket should already be bound to either an IPv6 or an IPv4 address.

The TLS ServerConfig should be configured with TLS 1.3 support and the DoH3 ALPN protocol enabled.

To make the server more resilient to DOS issues, there is a timeout. Care should be taken to not make this too low depending on use cases.

Arguments

• listener - a bound TCP (needs to be on a different port from standard TCP connections) socket
• timeout - timeout duration of incoming requests, any connection that does not send requests within this time period will be closed. In the future it should be possible to create long-lived queries, but these should be from trusted sources only, this would require some type of whitelisting.
• tls_config - a customized ServerConfig to use for TLS.

pub async fn shutdown_gracefully(&mut self) -> Result<(), NetError>

Triggers a graceful shutdown the server. All background tasks will stop accepting new connections and the returned future will complete once all tasks have terminated.

pub fn shutdown_token(&self) -> &CancellationToken

Returns a reference to the CancellationToken used to gracefully shut down the server.

Once cancellation is requested, all background tasks will stop accepting new connections, and block_until_done() will complete once all tasks have terminated.

pub async fn block_until_done(&mut self) -> Result<(), NetError>

This will run until all background tasks complete. If one or more tasks return an error, one will be chosen as the returned error for this future.