Do not use heapless on public API.

It's better to not use heapless on the public API.

- It can get major bumps from time to time (for example v0.8 was just relased), and upgrading it is a breaking change of embedded-nal-async, which we should try to avoid.
- It allows users to use any version of heapless, or something else entirely.

Author: Dirbaio

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 - Bump MSRV to 1.60.0 (required for Edition 2021)
 - Switch to Edition 2021
+- [breaking] `Dns::get_host_by_address` now uses `&mut [u8]` instead of `heapless::String`.
 
 ## [0.7.0] - 2023-06-21
 

Cargo.toml

@@ -23,5 +23,4 @@ ip_in_core = []
 
 [dependencies]
 nb = "1"
-no-std-net = { version = "0.6", optional = true }
-heapless = "^0.7"
+no-std-net = { version = "0.6", optional = true }

embedded-nal-async/CHANGELOG.md

@@ -7,7 +7,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
-No unreleased changes yet.
+- [breaking] `Dns::get_host_by_address` now uses `&mut [u8]` instead of `heapless::String`.
 
 ## [0.6.0] - 2023-10-03
 

embedded-nal-async/Cargo.toml

@@ -16,6 +16,5 @@ ip_in_core = []
 
 [dependencies]
 no-std-net = "0.6"
-heapless = "^0.7"
 embedded-nal = { version = "0.7.0", path = "../" }
 embedded-io-async = { version = "0.6.0" }

embedded-nal-async/src/dns.rs

@@ -1,6 +1,5 @@
 use crate::IpAddr;
 use embedded_nal::AddrType;
-use heapless::String;
 
 /// This trait is an extension trait for [`TcpStack`] and [`UdpStack`] for dns
 /// resolutions. It does not handle every DNS record type, but is meant as an
@@ -24,13 +23,22 @@ pub trait Dns {
 		addr_type: AddrType,
 	) -> Result<IpAddr, Self::Error>;
 
-	/// Resolve the hostname of a host, given its ip address
+	/// Resolve the hostname of a host, given its ip address.
+	///
+	/// The hostname is stored at the beginning of `result`, the length is returned.
+	///
+	/// If the buffer is too small to hold the domain name, an error should be returned.
 	///
 	/// **Note**: A fully qualified domain name (FQDN), has a maximum length of
-	/// 255 bytes [`rfc1035`]
+	/// 255 bytes according to [`rfc1035`]. Therefore, you can pass a 255-byte long
+	/// buffer to guarantee it'll always be large enough.
 	///
 	/// [`rfc1035`]: https://tools.ietf.org/html/rfc1035
-	async fn get_host_by_address(&self, addr: IpAddr) -> Result<String<256>, Self::Error>;
+	async fn get_host_by_address(
+		&self,
+		addr: IpAddr,
+		result: &mut [u8],
+	) -> Result<usize, Self::Error>;
 }
 
 impl<T: Dns> Dns for &T {
@@ -44,7 +52,11 @@ impl<T: Dns> Dns for &T {
 		T::get_host_by_name(self, host, addr_type).await
 	}
 
-	async fn get_host_by_address(&self, addr: IpAddr) -> Result<String<256>, Self::Error> {
-		T::get_host_by_address(self, addr).await
+	async fn get_host_by_address(
+		&self,
+		addr: IpAddr,
+		result: &mut [u8],
+	) -> Result<usize, Self::Error> {
+		T::get_host_by_address(self, addr, result).await
 	}
 }

embedded-nal-async/src/lib.rs

@@ -9,9 +9,6 @@
 
 mod dns;
 mod stack;
-// Needed by embedded-nal trait implementers who build get_host_by_address results, or by trait
-// users who pass the results on.
-pub use heapless;
 
 #[cfg(feature = "ip_in_core")]
 pub use core::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, SocketAddrV4, SocketAddrV6};

src/dns.rs

@@ -1,5 +1,4 @@
 use crate::IpAddr;
-use heapless::String;
 
 /// This is the host address type to be returned by `gethostbyname`.
 ///
@@ -37,13 +36,18 @@ pub trait Dns {
 		addr_type: AddrType,
 	) -> nb::Result<IpAddr, Self::Error>;
 
-	/// Resolve the hostname of a host, given its ip address
+	/// Resolve the hostname of a host, given its ip address.
+	///
+	/// The hostname is stored at the beginning of `result`, the length is returned.
+	///
+	/// If the buffer is too small to hold the domain name, an error should be returned.
 	///
 	/// **Note**: A fully qualified domain name (FQDN), has a maximum length of
-	/// 255 bytes [`rfc1035`]
+	/// 255 bytes according to [`rfc1035`]. Therefore, you can pass a 255-byte long
+	/// buffer to guarantee it'll always be large enough.
 	///
 	/// [`rfc1035`]: https://tools.ietf.org/html/rfc1035
-	fn get_host_by_address(&mut self, addr: IpAddr) -> nb::Result<String<256>, Self::Error>;
+	fn get_host_by_address(&self, addr: IpAddr, result: &mut [u8]) -> Result<usize, Self::Error>;
 }
 
 impl<T: Dns> Dns for &mut T {
@@ -57,7 +61,7 @@ impl<T: Dns> Dns for &mut T {
 		T::get_host_by_name(self, hostname, addr_type)
 	}
 
-	fn get_host_by_address(&mut self, addr: IpAddr) -> nb::Result<String<256>, Self::Error> {
-		T::get_host_by_address(self, addr)
+	fn get_host_by_address(&self, addr: IpAddr, result: &mut [u8]) -> Result<usize, Self::Error> {
+		T::get_host_by_address(self, addr, result)
 	}
 }

src/lib.rs

@@ -8,9 +8,6 @@ mod dns;
 mod stack;
 
 pub use nb;
-// Needed by embedded-nal trait implementers who build get_host_by_address results, or by trait
-// users who pass the results on.
-pub use heapless;
 
 #[cfg(not(any(feature = "ip_in_core", feature = "no-std-net")))]
 compile_error!("You must select the ip_in_core feature or the no-std-net feature");