[PR #1938] [MERGED] Provider API Redesign #2707

New issue

Closed

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

kerem commented

2026-03-16 11:03:50 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/hickory-dns/hickory-dns/pull/1938
Author: @XOR-op
Created: 5/20/2023
Status: ✅ Merged
Merged: 6/6/2023
Merged by: @bluejekyll

Base: main ← Head: provider-api

📝 Commits (9)

e1f142e chore: rename {Abstract} back
b33c8cb feat: new ConnectionProvider API
1133348 feat(WIP): change relevant types
d2743f9 test(WIP): fix integration test
e68b4bd fix(WIP): improper use with features
e07ba0d fix: improper use with features
918ea4e chore: remove unused CreateConnection
182e58f chore: fix clippy
1f44e8c fix: error in rebase

📊 Changes

22 files changed (+437 additions, -344 deletions)

View changed files

📝 crates/async-std-resolver/src/lib.rs (+4 -5)
📝 crates/async-std-resolver/src/runtime.rs (+39 -2)
📝 crates/async-std-resolver/src/tests.rs (+80 -47)
📝 crates/recursor/src/recursor.rs (+6 -4)
📝 crates/recursor/src/recursor_pool.rs (+3 -3)
📝 crates/resolver/examples/custom_provider.rs (+4 -4)
📝 crates/resolver/examples/flush_cache.rs (+3 -4)
📝 crates/resolver/examples/global_resolver.rs (+3 -2)
📝 crates/resolver/examples/multithreaded_runtime.rs (+2 -3)
📝 crates/resolver/src/async_resolver.rs (+81 -75)
📝 crates/resolver/src/https.rs (+2 -2)
📝 crates/resolver/src/lookup.rs (+3 -3)
📝 crates/resolver/src/name_server/connection_provider.rs (+56 -14)
📝 crates/resolver/src/name_server/mod.rs (+7 -5)
📝 crates/resolver/src/name_server/name_server.rs (+42 -64)
📝 crates/resolver/src/name_server/name_server_pool.rs (+54 -54)
📝 crates/resolver/src/resolver.rs (+4 -3)
📝 crates/resolver/src/tls/mod.rs (+2 -2)
📝 crates/server/src/store/forwarder/authority.rs (+3 -3)
📝 crates/server/tests/forwarder.rs (+3 -3)

...and 2 more files

📄 Description

In the later discussion of #1876, @jeff-hiner argues that the current Provider API doesn't offer a convenient way to statefully create DnsHandle. This PR redesigns the Provider API.

This PR replaces the original CreateConnection trait with the new factory trait ConnectionProvider, allowing stateful connection creation. Now we have two layers of customization, ConnectionProvider and RuntimeProvider. The RuntimeProvider is a factory to create TCP or UDP connections, as well as runtime-specific timer. The ConnectionProvider is a factory to create a DnsHandle with the help of RuntimeProvider.

pub trait ConnectionProvider: 'static + Clone + Send + Sync + Unpin {
    /// The handle to the connect for sending DNS requests.
    type Conn: DnsHandle<Error = ResolveError> + Clone + Send + Sync + 'static;
    /// Ths future is responsible for spawning any background tasks as necessary.
    type FutureConn: Future<Output = Result<Self::Conn, ResolveError>> + Send + 'static;
    /// Provider that handles the underlying I/O and timing.
    type RuntimeProvider: RuntimeProvider;

    /// Create a new connection.
    fn new_connection(&self, config: &NameServerConfig, options: &ResolverOpts)
        -> Self::FutureConn;
}

If a user wants to override the default networking behavior, he/she can simply implement a new RuntimeProvider, without the need of re-implementing the GenericConnection internal logic. If a user wants to override the upper logic of a DnsHandle, for example add an auth field to the HTTP header, he/she can just implement a new ConnectionProvider and reuse current RuntimeProvider (It's also possible not to use a connection provided by RuntimeProvider, as long as the user insists).

Currently, the default handle is GenericConnection and the default connection provider is GenericProvider.

This PR also clarifies the usage of Provider API. The original comment in 0.22 as well as #1876 is kind of misleading.

_{🔄 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/1938 **Author:** [@XOR-op](https://github.com/XOR-op) **Created:** 5/20/2023 **Status:** ✅ Merged **Merged:** 6/6/2023 **Merged by:** [@bluejekyll](https://github.com/bluejekyll) **Base:** `main` ← **Head:** `provider-api` --- ### 📝 Commits (9) - [`e1f142e`](https://github.com/hickory-dns/hickory-dns/commit/e1f142e19e707a962e43294cf27b7cfe68009cbf) chore: rename {Abstract} back - [`b33c8cb`](https://github.com/hickory-dns/hickory-dns/commit/b33c8cba17915ba448e93092895b573c81c06dc2) feat: new ConnectionProvider API - [`1133348`](https://github.com/hickory-dns/hickory-dns/commit/11333488cbff5de5383eff214a89d0d77ccebf95) feat(WIP): change relevant types - [`d2743f9`](https://github.com/hickory-dns/hickory-dns/commit/d2743f92bbae7f5885d8e2620d1465304985465f) test(WIP): fix integration test - [`e68b4bd`](https://github.com/hickory-dns/hickory-dns/commit/e68b4bda5c667a2eb99340aa1e7f9b4a8105fc56) fix(WIP): improper use with features - [`e07ba0d`](https://github.com/hickory-dns/hickory-dns/commit/e07ba0df64ad3be04adf7e8f892db7ee4c6770f0) fix: improper use with features - [`918ea4e`](https://github.com/hickory-dns/hickory-dns/commit/918ea4e527c1965cd6e0af2f17480d262fa6d0dc) chore: remove unused CreateConnection - [`182e58f`](https://github.com/hickory-dns/hickory-dns/commit/182e58f1bd15e75e858fe1ded68412975bb4f010) chore: fix clippy - [`1f44e8c`](https://github.com/hickory-dns/hickory-dns/commit/1f44e8c718f9e731131b398ce858781af73226ca) fix: error in rebase ### 📊 Changes **22 files changed** (+437 additions, -344 deletions) <details> <summary>View changed files</summary> 📝 `crates/async-std-resolver/src/lib.rs` (+4 -5) 📝 `crates/async-std-resolver/src/runtime.rs` (+39 -2) 📝 `crates/async-std-resolver/src/tests.rs` (+80 -47) 📝 `crates/recursor/src/recursor.rs` (+6 -4) 📝 `crates/recursor/src/recursor_pool.rs` (+3 -3) 📝 `crates/resolver/examples/custom_provider.rs` (+4 -4) 📝 `crates/resolver/examples/flush_cache.rs` (+3 -4) 📝 `crates/resolver/examples/global_resolver.rs` (+3 -2) 📝 `crates/resolver/examples/multithreaded_runtime.rs` (+2 -3) 📝 `crates/resolver/src/async_resolver.rs` (+81 -75) 📝 `crates/resolver/src/https.rs` (+2 -2) 📝 `crates/resolver/src/lookup.rs` (+3 -3) 📝 `crates/resolver/src/name_server/connection_provider.rs` (+56 -14) 📝 `crates/resolver/src/name_server/mod.rs` (+7 -5) 📝 `crates/resolver/src/name_server/name_server.rs` (+42 -64) 📝 `crates/resolver/src/name_server/name_server_pool.rs` (+54 -54) 📝 `crates/resolver/src/resolver.rs` (+4 -3) 📝 `crates/resolver/src/tls/mod.rs` (+2 -2) 📝 `crates/server/src/store/forwarder/authority.rs` (+3 -3) 📝 `crates/server/tests/forwarder.rs` (+3 -3) _...and 2 more files_ </details> ### 📄 Description In the later discussion of #1876, @jeff-hiner argues that the current Provider API doesn't offer a convenient way to statefully create `DnsHandle`. This PR redesigns the Provider API. This PR replaces the original `CreateConnection` trait with the new factory trait `ConnectionProvider`, allowing stateful connection creation. Now we have two layers of customization, `ConnectionProvider` and `RuntimeProvider`. The `RuntimeProvider` is a factory to create TCP or UDP connections, as well as runtime-specific timer. The `ConnectionProvider` is a factory to create a `DnsHandle` with the help of `RuntimeProvider`. ```rust pub trait ConnectionProvider: 'static + Clone + Send + Sync + Unpin { /// The handle to the connect for sending DNS requests. type Conn: DnsHandle<Error = ResolveError> + Clone + Send + Sync + 'static; /// Ths future is responsible for spawning any background tasks as necessary. type FutureConn: Future<Output = Result<Self::Conn, ResolveError>> + Send + 'static; /// Provider that handles the underlying I/O and timing. type RuntimeProvider: RuntimeProvider; /// Create a new connection. fn new_connection(&self, config: &NameServerConfig, options: &ResolverOpts) -> Self::FutureConn; } ``` If a user wants to override the default networking behavior, he/she can simply implement a new `RuntimeProvider`, without the need of re-implementing the `GenericConnection` internal logic. If a user wants to override the upper logic of a `DnsHandle`, for example add an auth field to the HTTP header, he/she can just implement a new `ConnectionProvider` and reuse current `RuntimeProvider` (It's also possible not to use a connection provided by `RuntimeProvider`, as long as the user insists). Currently, the default handle is `GenericConnection` and the default connection provider is `GenericProvider`. This PR also clarifies the usage of Provider API. The original comment in 0.22 as well as #1876 is kind of misleading. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>