Add network support

Author: Argonus

lib/container.ex

@@ -25,6 +25,8 @@ defmodule Testcontainers.Container do
     container_id: nil,
     check_image: nil,
     network_mode: nil,
+    network: nil,
+    hostname: nil,
     reuse: false,
     force_reuse: false,
     pull_policy: Testcontainers.PullPolicy.always_pull()
@@ -259,6 +261,26 @@ defmodule Testcontainers.Container do
     %__MODULE__{config | network_mode: mode}
   end
 
+  @doc """
+  Sets the Docker network for the container to join.
+
+  Containers on the same network can communicate with each other using their
+  hostnames. Use `with_hostname/2` to set a custom hostname for the container.
+  """
+  def with_network(%__MODULE__{} = config, network_name) when is_binary(network_name) do
+    %__MODULE__{config | network: network_name}
+  end
+
+  @doc """
+  Sets the hostname for the container.
+
+  This is useful when containers need to communicate with each other by hostname
+  on a shared Docker network.
+  """
+  def with_hostname(%__MODULE__{} = config, hostname) when is_binary(hostname) do
+    %__MODULE__{config | hostname: hostname}
+  end
+
   @doc """
   Gets the host port on the container for the given exposed port.
   """

lib/docker/api.ex

@@ -182,6 +182,68 @@ defmodule Testcontainers.Docker.Api do
     end
   end
 
+  @doc """
+  Creates a Docker network.
+  """
+  def create_network(name, conn, opts \\ []) when is_binary(name) do
+    driver = Keyword.get(opts, :driver, "bridge")
+
+    body = %DockerEngineAPI.Model.NetworkCreateRequest{
+      Name: name,
+      Driver: driver,
+      CheckDuplicate: true
+    }
+
+    case Api.Network.network_create(conn, body) do
+      {:ok, %DockerEngineAPI.Model.NetworkCreateResponse{Id: id}} ->
+        {:ok, id}
+
+      {:ok, %DockerEngineAPI.Model.ErrorResponse{message: message}} ->
+        {:error, {:failed_to_create_network, message}}
+
+      {:error, %Tesla.Env{status: 409}} ->
+        {:ok, :already_exists}
+
+      {:error, %Tesla.Env{status: status}} ->
+        {:error, {:http_error, status}}
+
+      {:error, reason} ->
+        {:error, reason}
+    end
+  end
+
+  @doc """
+  Removes a Docker network.
+  """
+  def remove_network(name, conn) when is_binary(name) do
+    case Api.Network.network_delete(conn, name) do
+      {:ok, %Tesla.Env{status: 204}} ->
+        :ok
+
+      {:ok, %Tesla.Env{status: 404}} ->
+        {:error, :network_not_found}
+
+      {:ok, %DockerEngineAPI.Model.ErrorResponse{message: message}} ->
+        {:error, {:failed_to_remove_network, message}}
+
+      {:error, %Tesla.Env{status: status}} ->
+        {:error, {:http_error, status}}
+
+      {:error, reason} ->
+        {:error, reason}
+    end
+  end
+
+  @doc """
+  Checks if a network exists.
+  """
+  def network_exists?(name, conn) when is_binary(name) do
+    case Api.Network.network_inspect(conn, name) do
+      {:ok, %DockerEngineAPI.Model.Network{}} -> true
+      _ -> false
+    end
+  end
+
   def tag_image(image, repo, tag, conn) do
     case Api.Image.image_tag(conn, image, repo: repo, tag: tag) do
       {:ok, %Tesla.Env{status: 201}} ->
@@ -203,21 +265,35 @@ defmodule Testcontainers.Docker.Api do
   end
 
   defp container_create_request(%Container{} = container_config) do
-    %DockerEngineAPI.Model.ContainerCreateRequest{
+    base_request = %DockerEngineAPI.Model.ContainerCreateRequest{
       Image: container_config.image,
       Cmd: container_config.cmd,
       ExposedPorts: map_exposed_ports(container_config),
       Env: map_env(container_config),
       Labels: container_config.labels,
+      Hostname: container_config.hostname,
       HostConfig: %HostConfig{
         AutoRemove: container_config.auto_remove,
         PortBindings: map_port_bindings(container_config),
         Privileged: container_config.privileged,
         Binds: map_binds(container_config),
         Mounts: map_volumes(container_config),
-        NetworkMode: container_config.network_mode
+        NetworkMode: container_config.network_mode || container_config.network
       }
     }
+
+    # Add NetworkingConfig if a network is specified
+    if container_config.network do
+      endpoint_config = %{
+        container_config.network => %DockerEngineAPI.Model.EndpointSettings{}
+      }
+
+      Map.put(base_request, :NetworkingConfig, %DockerEngineAPI.Model.NetworkingConfig{
+        EndpointsConfig: endpoint_config
+      })
+    else
+      base_request
+    end
   end
 
   defp map_exposed_ports(%Container{} = container_config) do
@@ -264,6 +340,38 @@ defmodule Testcontainers.Docker.Api do
     end)
   end
 
+  defp from(%DockerEngineAPI.Model.ContainerInspectResponse{
+         Id: container_id,
+         Image: image,
+         NetworkSettings: %{IPAddress: ip_address, Ports: ports, Networks: networks},
+         Config: %{Env: env, Labels: labels}
+       }) do
+    # For custom networks, the IP address is in Networks.<network_name>.IPAddress
+    # The default bridge IPAddress will be empty for custom networks
+    resolved_ip = resolve_ip_address(ip_address, networks)
+
+    %Container{
+      container_id: container_id,
+      image: image,
+      labels: labels,
+      ip_address: resolved_ip,
+      exposed_ports:
+        Enum.reduce(ports || [], [], fn {key, ports}, acc ->
+          acc ++
+            Enum.map(ports || [], fn %{"HostPort" => host_port} ->
+              {key |> String.replace("/tcp", "") |> String.to_integer(),
+               host_port |> String.to_integer()}
+            end)
+        end),
+      environment:
+        Enum.reduce(env || [], %{}, fn env, acc ->
+          tokens = String.split(env, "=")
+          Map.merge(acc, %{"#{List.first(tokens)}": List.last(tokens)})
+        end)
+    }
+  end
+
+  # Also handle when Networks key is missing
   defp from(%DockerEngineAPI.Model.ContainerInspectResponse{
          Id: container_id,
          Image: image,
@@ -291,6 +399,25 @@ defmodule Testcontainers.Docker.Api do
     }
   end
 
+  # Resolve IP address, preferring custom network IPs if default is empty
+  defp resolve_ip_address(nil, networks), do: get_ip_from_networks(networks)
+  defp resolve_ip_address("", networks), do: get_ip_from_networks(networks)
+  defp resolve_ip_address(ip, _networks) when is_binary(ip) and ip != "", do: ip
+
+  defp get_ip_from_networks(nil), do: nil
+
+  defp get_ip_from_networks(networks) when is_map(networks) do
+    # Get the first non-empty IP from any network
+    networks
+    |> Enum.find_value(fn
+      {_name, %{IPAddress: ip}} when is_binary(ip) and ip != "" -> ip
+      {_name, %{"IPAddress" => ip}} when is_binary(ip) and ip != "" -> ip
+      _ -> nil
+    end)
+  end
+
+  defp get_ip_from_networks(_), do: nil
+
   defp create_exec(container_id, command, conn) do
     data = %ExecConfig{Cmd: command}
 

lib/testcontainers.ex

@@ -81,7 +81,8 @@ defmodule Testcontainers do
          conn: conn,
          docker_hostname: docker_hostname,
          session_id: session_id,
-         properties: properties
+         properties: properties,
+         networks: MapSet.new()
        }}
     else
       error ->
@@ -145,6 +146,44 @@ defmodule Testcontainers do
     wait_for_call({:stop_container, container_id}, name)
   end
 
+  @doc """
+  Creates a Docker network.
+
+  Networks allow containers to communicate with each other using hostnames.
+  Use `Container.with_network/2` to attach a container to a network.
+
+  ## Parameters
+
+  - `network_name`: The name of the network to create.
+  - `name`: The name of the Testcontainers GenServer (defaults to `Testcontainers`).
+
+  ## Returns
+
+  - `{:ok, network_id}` if the network is created successfully.
+  - `{:ok, :already_exists}` if the network already exists.
+  - `{:error, reason}` on failure.
+  """
+  def create_network(network_name, name \\ __MODULE__) when is_binary(network_name) do
+    wait_for_call({:create_network, network_name}, name)
+  end
+
+  @doc """
+  Removes a Docker network.
+
+  ## Parameters
+
+  - `network_name`: The name of the network to remove.
+  - `name`: The name of the Testcontainers GenServer (defaults to `Testcontainers`).
+
+  ## Returns
+
+  - `:ok` if the network is removed successfully.
+  - `{:error, reason}` on failure.
+  """
+  def remove_network(network_name, name \\ __MODULE__) when is_binary(network_name) do
+    wait_for_call({:remove_network, network_name}, name)
+  end
+
   @impl true
   def handle_info(_msg, state) do
     {:noreply, state}
@@ -170,6 +209,26 @@ defmodule Testcontainers do
     {:reply, state.docker_hostname, state}
   end
 
+  @impl true
+  def handle_call({:create_network, network_name}, from, state) do
+    Task.async(fn ->
+      result = Api.create_network(network_name, state.conn)
+      GenServer.reply(from, result)
+    end)
+
+    {:noreply, %{state | networks: MapSet.put(state.networks, network_name)}}
+  end
+
+  @impl true
+  def handle_call({:remove_network, network_name}, from, state) do
+    Task.async(fn ->
+      result = Api.remove_network(network_name, state.conn)
+      GenServer.reply(from, result)
+    end)
+
+    {:noreply, %{state | networks: MapSet.delete(state.networks, network_name)}}
+  end
+
   # private functions
 
   defp get_docker_hostname(docker_host_url, conn) do