testcontainers::Network Class Reference

A RAII handle to a user-defined Docker network. More...

#include <testcontainers/Network.hpp>

Classes
class	Builder
	A copyable builder for a richer user-defined network: driver, internal / attachable / IPv6 flags, IPAM address pools, driver options, and labels. More...

Public Member Functions
	Network (const Network &)=delete
Network &	operator= (const Network &)=delete
	Network (Network &&other) noexcept
Network &	operator= (Network &&other) noexcept
	~Network ()
	Removes the network unless it was already explicitly removed or moved-from.
const std::string &	name () const noexcept
	The network's name (used by containers to join it / resolve peers).
const std::string &	id () const noexcept
	The network's id.
bool	is_persistent () const noexcept
	True when this handle will NOT remove the network on destruction (after keep()).
NetworkInspect	inspect () const
	A structured snapshot of this network (GET /networks/{id}): driver, flags, IPAM pools, options, labels, and the currently attached containers.
std::string	inspect_raw () const
	The RAW inspect JSON body (GET /networks/{id}), so callers can read any field NetworkInspect does not model.
void	keep (bool keep=true) noexcept
	Keep the network alive past this handle: from here on neither destruction nor remove() removes it (is_persistent() reports true afterwards) — removing the network becomes the caller's responsibility (e.g.
void	remove ()
	Explicitly remove the network now.
void	connect (const std::string &container_id, const std::vector< std::string > &aliases={}) const
	Connect an already-running container to this network, optionally giving it DNS aliases on this network.

Static Public Member Functions
static Builder	builder ()
	Start a builder for a richer network (driver, IPAM, options, labels).
static Network	create (std::string name)
	Create a network with the given name.
static Network	create ()
	Create a network with a generated unique name (tc-<random hex>).
static NetworkInspect	inspect (const std::string &id_or_name)
	A structured snapshot of an arbitrary network by name or id, without a Network handle (the daemon accepts both forms).

Detailed Description

A RAII handle to a user-defined Docker network.

Move-only: it owns a real external resource and removes the network on destruction (best-effort, exceptions swallowed). Copying is deleted so the removal happens exactly once; keep() releases removal ownership (the network then outlives the handle). Containers placed on the same network (via GenericImage::with_network) can resolve each other by container name.

Constructor & Destructor Documentation

Network() [1/2]

testcontainers::Network::Network ( const Network & )

delete

Network() [2/2]

testcontainers::Network::Network ( Network && other )

inlinenoexcept

~Network()

testcontainers::Network::~Network ( )

inline

Removes the network unless it was already explicitly removed or moved-from.

Never throws.

Member Function Documentation

builder()

Builder testcontainers::Network::builder ( )

inlinestatic

Start a builder for a richer network (driver, IPAM, options, labels).

operator=() [1/2]

Network & testcontainers::Network::operator= ( const Network & )

delete

operator=() [2/2]

Network & testcontainers::Network::operator= ( Network && other )

inlinenoexcept

create() [1/2]

Network testcontainers::Network::create ( std::string name )

static

Create a network with the given name.

create() [2/2]

Network testcontainers::Network::create ( )

static

Create a network with a generated unique name (tc-<random hex>).

name()

const std::string & testcontainers::Network::name ( ) const

inlinenoexcept

The network's name (used by containers to join it / resolve peers).

id()

const std::string & testcontainers::Network::id ( ) const

inlinenoexcept

The network's id.

is_persistent()

bool testcontainers::Network::is_persistent ( ) const

inlinenoexcept

True when this handle will NOT remove the network on destruction (after keep()).

inspect() [1/2]

NetworkInspect testcontainers::Network::inspect

(

)

const

A structured snapshot of this network (GET /networks/{id}): driver, flags, IPAM pools, options, labels, and the currently attached containers.

Throws DockerError if the network is gone.

inspect_raw()

std::string testcontainers::Network::inspect_raw

(

)

const

The RAW inspect JSON body (GET /networks/{id}), so callers can read any field NetworkInspect does not model.

Throws DockerError if the network is gone.

inspect() [2/2]

NetworkInspect testcontainers::Network::inspect ( const std::string & id_or_name )

static

A structured snapshot of an arbitrary network by name or id, without a Network handle (the daemon accepts both forms).

Connects via DockerClient::from_environment(). Throws DockerError if no such network exists (NotFoundError) or the daemon cannot be reached.

keep()

void testcontainers::Network::keep ( bool keep = true )

inlinenoexcept

Keep the network alive past this handle: from here on neither destruction nor remove() removes it (is_persistent() reports true afterwards) — removing the network becomes the caller's responsibility (e.g.

DockerClient::remove_network or docker network rm). keep(false) re-arms removal — handy for forwarding a "keep my resources" debug flag in one call instead of an if.

Ryuk still applies on Linux engines: a created network carries the session label, so the reaper removes it shortly after the test process exits — keep() only protects it from THIS process's teardown. For a network that must outlive the process, disable the reaper (TESTCONTAINERS_RYUK_DISABLED). (No reaper runs against a Windows-containers engine — a kept network there stays until you remove it.)

remove()

void testcontainers::Network::remove

(

)

Explicitly remove the network now.

Idempotent; after this the destructor does nothing. On a kept handle (after keep()) this releases ownership without removing the network.

connect()

void testcontainers::Network::connect	(	const std::string &	container_id,
		const std::vector< std::string > &	aliases = {} ) const

Connect an already-running container to this network, optionally giving it DNS aliases on this network.

Lets a container join after it was started (e.g. without GenericImage::with_network).