Add example for connecting over HTTP/2 (#2088)

Co-authored-by: marcbrevoort-cyberhive <69469731+marcbrevoort-cyberhive@users.noreply.github.com>

.github/workflows/test.yml

@@ -89,6 +89,7 @@ jobs:
             dns-over-native-tls,
             dnssec-openssl,
             dnssec-ring,
+            doc,
           ]
     steps:
       - uses: actions/checkout@v4

Cargo.lock

@@ -812,6 +812,7 @@ dependencies = [
  "tokio",
  "tracing",
  "tracing-subscriber",
+ "webpki-roots",
 ]
 
 [[package]]

crates/client/Cargo.toml

@@ -107,6 +107,7 @@ tracing-subscriber = { workspace = true, features = [
     "fmt",
     "env-filter",
 ] }
+webpki-roots = { workspace = true }
 
 [package.metadata.docs.rs]
 all-features = true

crates/client/src/h2_client_connection.rs

@@ -29,6 +29,61 @@ pub struct HttpsClientConnection<T> {
     marker: PhantomData<T>,
 }
 
+/// ## Querying DNS over HTTPS (DoH)
+///
+/// The example code below demonstrates how to use the Client to
+/// issue DNS queries over HTTPS.
+///
+/// ```rust
+/// use hickory_client::client::SyncClient;
+/// use hickory_client::client::Client;
+/// use hickory_client::h2::HttpsClientConnection;
+/// use hickory_client::rr::{DNSClass, Name, RecordType};
+/// use hickory_proto::iocompat::AsyncIoTokioAsStd;
+/// use rustls::{ClientConfig, OwnedTrustAnchor, RootCertStore};
+/// use std::net::{IpAddr, Ipv4Addr, SocketAddr};
+/// use webpki_roots;
+///
+/// let name_server = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(8, 8, 8, 8)), 443);
+/// let host_to_lookup = "example.com".to_string();
+///
+/// let mut root_store = RootCertStore::empty();
+/// root_store.add_trust_anchors(webpki_roots::TLS_SERVER_ROOTS.iter().map(|ta| {
+///     OwnedTrustAnchor::from_subject_spki_name_constraints(
+///         ta.subject,
+///         ta.spki,
+///         ta.name_constraints,
+///     )
+/// }));
+///
+/// let client_config = ClientConfig::builder()
+///     .with_safe_default_cipher_suites()
+///     .with_safe_default_kx_groups()
+///     .with_safe_default_protocol_versions()
+///     .unwrap()
+///     .with_root_certificates(root_store)
+///     .with_no_client_auth();
+///
+/// let shared_client_config = std::sync::Arc::new(client_config);
+/// let conn: HttpsClientConnection<AsyncIoTokioAsStd<tokio::net::TcpStream>> =
+///     HttpsClientConnection::new(name_server, "dns.google".to_string(), shared_client_config);
+///
+/// let client = SyncClient::new(conn);
+/// let name = Name::from_ascii(host_to_lookup).unwrap();
+/// let dns_class = DNSClass::IN;
+/// let record_type = RecordType::A;
+///
+/// let response = client.query(&name, dns_class, record_type);
+/// match response {
+///     Ok(answer) => {
+///         println!("ok={:?}", answer);
+///     }
+///     Err(e) => {
+///         println!("err Resp={:?}", e);
+///     }
+/// }
+/// ```
+
 impl<T> HttpsClientConnection<T> {
     /// Creates a new client connection.
     ///

justfile

@@ -60,7 +60,10 @@ build feature='' ignore='':
 # Run tests on all projects in the workspace
 test feature='' ignore='':
     cargo ws exec {{ignore}} cargo {{MSRV}} test --all-targets --benches --examples --bins --tests {{feature}}
-   
+
+doc feature='':
+    cargo ws exec --ignore=hickory-dns cargo {{MSRV}} test --doc {{feature}}
+
 # This tests compatibility with BIND9, TODO: support other feature sets besides openssl for tests
 compatibility: init-bind9
     cargo test --manifest-path tests/compatibility-tests/Cargo.toml --all-targets --benches --examples --bins --tests --no-default-features --features=none;