[PR #1876] [MERGED] API-breaking change: Deprecate ConnectionProvider with new RuntimeProvider #2669

New issue

Closed

opened 2026-03-16 11:01:40 +03:00 by kerem · 0 comments

kerem commented

2026-03-16 11:01:40 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/hickory-dns/hickory-dns/pull/1876
Author: @XOR-op
Created: 1/9/2023
Status: ✅ Merged
Merged: 3/4/2023
Merged by: @bluejekyll

Base: main ← Head: main

📝 Commits (10+)

27ad963 WIP: many underlying type except mdns
458010d revert mdns
ecb9f15 WIP: narrow UdpSocket down to DnsUdpSocket
01ba4af WIP: udp creator
05d172e WIP: clean generic for NameServer
20dfc17 WIP: logic of NameServer
32a4d06 fix nameserver logic and udp socket creation
823d5bd replace ConnProvider with RuntimeProvider
5b3b68e test: fix compile errors
8e780d2 trait CreateConnection

📊 Changes

45 files changed (+1589 additions, -903 deletions)

View changed files

📝 Cargo.lock (+3 -2)
📝 crates/async-std-resolver/src/lib.rs (+5 -6)
📝 crates/async-std-resolver/src/net.rs (+34 -26)
📝 crates/async-std-resolver/src/runtime.rs (+25 -17)
📝 crates/async-std-resolver/src/tests.rs (+68 -63)
📝 crates/proto/Cargo.toml (+2 -1)
📝 crates/proto/src/https/https_client_stream.rs (+40 -25)
📝 crates/proto/src/native_tls/tls_client_stream.rs (+36 -3)
📝 crates/proto/src/native_tls/tls_stream.rs (+62 -30)
📝 crates/proto/src/openssl/tls_client_stream.rs (+41 -8)
📝 crates/proto/src/openssl/tls_stream.rs (+65 -44)
📝 crates/proto/src/quic/mod.rs (+1 -0)
📝 crates/proto/src/quic/quic_client_stream.rs (+142 -3)
📝 crates/proto/src/rustls/tls_client_stream.rs (+35 -2)
📝 crates/proto/src/rustls/tls_stream.rs (+65 -5)
📝 crates/proto/src/tcp/tcp_client_stream.rs (+26 -4)
📝 crates/proto/src/tcp/tcp_stream.rs (+54 -28)
📝 crates/proto/src/tests/tcp.rs (+4 -8)
📝 crates/proto/src/tests/udp.rs (+2 -2)
📝 crates/proto/src/udp/mod.rs (+1 -1)

...and 25 more files

📄 Description

Why we need new interface?

Current ConnectionProvider interface didn't provide enough ability for end-users to create customized connections, although it looked like. For example, users find it hard to customize underlying TCP or UDP sockets, see #1863, #1870, #1335. Users may also seek for abstract TCP stream instead of real one. Related discussion can be found on #1863.

What is our plan?

We design new RuntimeProvider interface, whose responsibility is to provide TCP-like and UDP-like connections. Currently, the new interface looks like:

pub trait RuntimeProvider: Clone + Send + Sync + Unpin + 'static {
    type Handle: Clone + Send + Spawn + Sync + Unpin;
    type Timer: Time + Send + Unpin;
    type Udp: DnsUdpSocket + Send;
    type Tcp: DnsTcpStream;

    /// Create a runtime handle
    fn create_handle(&self) -> Self::Handle;

    /// Create a TCP connection with custom configuration.
    fn connect_tcp(
        &self, server_addr: SocketAddr,
    ) -> Pin<Box<dyn Send + Future<Output = io::Result<Self::Tcp>>>>;

    /// Create a UDP socket bound to `local_addr`. The returned value should **not** be connected to `server_addr`.
    /// *Notice: the future should be ready once returned at best effort. Otherwise UDP DNS may need much more retries.*
    fn bind_udp(
        &self, local_addr: SocketAddr, server_addr: SocketAddr,
    ) -> Pin<Box<dyn Send + Future<Output = io::Result<Self::Udp>>>>;
}

where we introduce new DnsUdpSocket as the counterpart of DnsTcpSocket ,removing requirements for bind and connect.

Design problems

~~Should we take GenericConnection as our only implementation, or leaving some interface for users to implement their own ones?~~

Progress

Underlying support
- support for providing customized TCP stream
- support for providing customized UDP socket for quic
- support for providing customized UDP socket for udp
change interface
fix dependent code
fix tests
pass tests

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/hickory-dns/hickory-dns/pull/1876 **Author:** [@XOR-op](https://github.com/XOR-op) **Created:** 1/9/2023 **Status:** ✅ Merged **Merged:** 3/4/2023 **Merged by:** [@bluejekyll](https://github.com/bluejekyll) **Base:** `main` ← **Head:** `main` --- ### 📝 Commits (10+) - [`27ad963`](https://github.com/hickory-dns/hickory-dns/commit/27ad96394d831a170b349ee98d1598f6eb30d1c8) WIP: many underlying type except mdns - [`458010d`](https://github.com/hickory-dns/hickory-dns/commit/458010d7a1478422b8d98405f729602bef936fc3) revert mdns - [`ecb9f15`](https://github.com/hickory-dns/hickory-dns/commit/ecb9f152f4b6389f2211fff97481804b071ca22d) WIP: narrow UdpSocket down to DnsUdpSocket - [`01ba4af`](https://github.com/hickory-dns/hickory-dns/commit/01ba4af4f67f221b3c3230e704ac3a4a38879a4f) WIP: udp creator - [`05d172e`](https://github.com/hickory-dns/hickory-dns/commit/05d172eef9f301b512b7ddf6d126c9c961248222) WIP: clean generic for NameServer - [`20dfc17`](https://github.com/hickory-dns/hickory-dns/commit/20dfc17d6a748e99fe99fe067405340c916a5ca8) WIP: logic of NameServer - [`32a4d06`](https://github.com/hickory-dns/hickory-dns/commit/32a4d0640f2bab9345a1786bc41e73ca01eac470) fix nameserver logic and udp socket creation - [`823d5bd`](https://github.com/hickory-dns/hickory-dns/commit/823d5bdd5af3eab45a42a870c555879f2f47ec0f) replace ConnProvider with RuntimeProvider - [`5b3b68e`](https://github.com/hickory-dns/hickory-dns/commit/5b3b68e9f02cdaaafe48e1196a8124ca2f4dc2f2) test: fix compile errors - [`8e780d2`](https://github.com/hickory-dns/hickory-dns/commit/8e780d2e92034ba363d27bb5b38248ab2d7ead58) trait CreateConnection ### 📊 Changes **45 files changed** (+1589 additions, -903 deletions) <details> <summary>View changed files</summary> 📝 `Cargo.lock` (+3 -2) 📝 `crates/async-std-resolver/src/lib.rs` (+5 -6) 📝 `crates/async-std-resolver/src/net.rs` (+34 -26) 📝 `crates/async-std-resolver/src/runtime.rs` (+25 -17) 📝 `crates/async-std-resolver/src/tests.rs` (+68 -63) 📝 `crates/proto/Cargo.toml` (+2 -1) 📝 `crates/proto/src/https/https_client_stream.rs` (+40 -25) 📝 `crates/proto/src/native_tls/tls_client_stream.rs` (+36 -3) 📝 `crates/proto/src/native_tls/tls_stream.rs` (+62 -30) 📝 `crates/proto/src/openssl/tls_client_stream.rs` (+41 -8) 📝 `crates/proto/src/openssl/tls_stream.rs` (+65 -44) 📝 `crates/proto/src/quic/mod.rs` (+1 -0) 📝 `crates/proto/src/quic/quic_client_stream.rs` (+142 -3) 📝 `crates/proto/src/rustls/tls_client_stream.rs` (+35 -2) 📝 `crates/proto/src/rustls/tls_stream.rs` (+65 -5) 📝 `crates/proto/src/tcp/tcp_client_stream.rs` (+26 -4) 📝 `crates/proto/src/tcp/tcp_stream.rs` (+54 -28) 📝 `crates/proto/src/tests/tcp.rs` (+4 -8) 📝 `crates/proto/src/tests/udp.rs` (+2 -2) 📝 `crates/proto/src/udp/mod.rs` (+1 -1) _...and 25 more files_ </details> ### 📄 Description # Why we need new interface? Current `ConnectionProvider` interface didn't provide enough ability for end-users to create customized connections, although it looked like. For example, users find it hard to customize underlying TCP or UDP sockets, see #1863, #1870, #1335. Users may also seek for abstract TCP stream instead of real one. Related discussion can be found on #1863. # What is our plan? We design new `RuntimeProvider` interface, whose responsibility is to provide TCP-like and UDP-like connections. Currently, the new interface looks like: ```rust pub trait RuntimeProvider: Clone + Send + Sync + Unpin + 'static { type Handle: Clone + Send + Spawn + Sync + Unpin; type Timer: Time + Send + Unpin; type Udp: DnsUdpSocket + Send; type Tcp: DnsTcpStream; /// Create a runtime handle fn create_handle(&self) -> Self::Handle; /// Create a TCP connection with custom configuration. fn connect_tcp( &self, server_addr: SocketAddr, ) -> Pin<Box<dyn Send + Future<Output = io::Result<Self::Tcp>>>>; /// Create a UDP socket bound to `local_addr`. The returned value should **not** be connected to `server_addr`. /// *Notice: the future should be ready once returned at best effort. Otherwise UDP DNS may need much more retries.* fn bind_udp( &self, local_addr: SocketAddr, server_addr: SocketAddr, ) -> Pin<Box<dyn Send + Future<Output = io::Result<Self::Udp>>>>; } ``` where we introduce new `DnsUdpSocket` as the counterpart of `DnsTcpSocket` ,removing requirements for bind and connect. # Design problems - <del>Should we take `GenericConnection` as our only implementation, or leaving some interface for users to implement their own ones? </del> # Progress - Underlying support - [x] support for providing customized TCP stream - [x] support for providing customized UDP socket for quic - [x] support for providing customized UDP socket for udp - [x] change interface - [x] fix dependent code - [x] fix tests - [x] pass tests --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>