refactor!: return PortNotExposed error from `ContainerState::host_p…

…ort_*` (#644)

That's much easier for users to use `?` in `exec_after_start` instead of
mapping manually to appropriate error.

testcontainers/src/core/containers/async_container.rs

@@ -234,10 +234,8 @@ where
     /// Starts the container.
     pub async fn start(&self) -> Result<()> {
         self.docker_client.start(&self.id).await?;
-        for cmd in self
-            .image
-            .exec_after_start(ContainerState::new(self.ports().await?))?
-        {
+        let state = ContainerState::new(self.id(), self.ports().await?);
+        for cmd in self.image.exec_after_start(state)? {
             self.exec(cmd).await?;
         }
         Ok(())

testcontainers/src/core/image.rs

@@ -112,20 +112,40 @@ where
 
 #[derive(Debug)]
 pub struct ContainerState {
+    id: String,
     ports: Ports,
 }
 
 impl ContainerState {
-    pub fn new(ports: Ports) -> Self {
-        Self { ports }
+    pub fn new(id: impl Into<String>, ports: Ports) -> Self {
+        Self {
+            id: id.into(),
+            ports,
+        }
     }
 
-    pub fn host_port_ipv4(&self, internal_port: u16) -> Option<u16> {
-        self.ports.map_to_host_port_ipv4(internal_port)
+    /// Returns the host port for the given internal port (`IPv4`).
+    ///
+    /// Results in an error ([`TestcontainersError::PortNotExposed`]) if the port is not exposed.
+    pub fn host_port_ipv4(&self, internal_port: u16) -> Result<u16, TestcontainersError> {
+        self.ports
+            .map_to_host_port_ipv4(internal_port)
+            .ok_or_else(|| TestcontainersError::PortNotExposed {
+                id: self.id.clone(),
+                port: internal_port,
+            })
     }
 
-    pub fn host_port_ipv6(&self, internal_port: u16) -> Option<u16> {
-        self.ports.map_to_host_port_ipv6(internal_port)
+    /// Returns the host port for the given internal port (`IPv6`).
+    ///
+    /// Results in an error ([`TestcontainersError::PortNotExposed`]) if the port is not exposed.
+    pub fn host_port_ipv6(&self, internal_port: u16) -> Result<u16, TestcontainersError> {
+        self.ports
+            .map_to_host_port_ipv6(internal_port)
+            .ok_or_else(|| TestcontainersError::PortNotExposed {
+                id: self.id.clone(),
+                port: internal_port,
+            })
     }
 }
 

testcontainers/src/runners/async_runner.rs

@@ -218,10 +218,8 @@ where
             let container =
                 ContainerAsync::new(container_id, client.clone(), runnable_image, network).await?;
 
-            for cmd in container
-                .image()
-                .exec_after_start(ContainerState::new(container.ports().await?))?
-            {
+            let state = ContainerState::new(container.id(), container.ports().await?);
+            for cmd in container.image().exec_after_start(state)? {
                 container.exec(cmd).await?;
             }