feat: Add connect to network API

[HofmeisterAn]

What does this PR do?

This PR adds a new API to the IContainer interface that lets developers connect a container to existing networks. Some modules configure networks internally without exposing them publicly. This API allows containers to be connected to those networks after they start.

Why is it important?

-

Related issues

• Relates [Enhancement]: Add network connect/disconnect API to IContainer #1614
• Relates [Enhancement]: Add external network support to WebDriverBuilder #1669

Summary by CodeRabbit

• New Features

  • Allow connecting running containers to existing Docker networks.

• Documentation

  • Added guidance for attaching a running container to a pre-existing network and recommended configuration practices.

• Bug Fixes

  • Improved image reference matching reliability.

• Tests

  • Added test coverage verifying runtime container network attachments.

[netlify]

✅ Deploy Preview for testcontainers-dotnet ready!

Name	Link
🔨 Latest commit	45a4274
🔍 Latest deploy log	https://app.netlify.com/projects/testcontainers-dotnet/deploys/69c78ae480f14a00080b3e20
😎 Deploy Preview	https://deploy-preview-1672--testcontainers-dotnet.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 8a011c49-9421-4b9c-8af5-e973f243f9b3

📥 Commits

Reviewing files that changed from the base of the PR and between 066ee8e and 45a4274.

📒 Files selected for processing (1)

• src/Testcontainers/Containers/IContainer.cs

🚧 Files skipped from review as they are similar to previous changes (1)

• src/Testcontainers/Containers/IContainer.cs

---

Walkthrough

Added ConnectAsync overloads to allow attaching an already-running container to an existing Docker network; implemented on interface and DockerContainer class with internal unsafe connect logic and state refresh; docs updated with guidance and a new Linux integration test verifies runtime network attachment.

Changes

Cohort / File(s)	Summary
Network API & Implementation src/Testcontainers/Containers/IContainer.cs, src/Testcontainers/Containers/DockerContainer.cs	Added ConnectAsync(string, CancellationToken) and ConnectAsync(INetwork, CancellationToken) to the interface and DockerContainer; implemented lock-protected calls and UnsafeConnectAsync(string, CancellationToken) which invokes _client.Network.ConnectAsync(...) and refreshes container state.
Documentation docs/api/create_docker_network.md	Added section "Connecting a running container to an existing network" describing usage patterns (container.ConnectAsync(network) and container.ConnectAsync(network.Name)) and recommending WithNetwork(...) for pre-start configuration.
Tests tests/Testcontainers.Platform.Linux.Tests/NetworkConnectTest.cs	Added integration test that creates networks (by name and by reference), starts a long-running container, connects it to both networks at runtime, inspects the container, and asserts both networks are present.
Regex timeout tweak src/Testcontainers/Images/MatchImage.cs	Increased regex timeout in ReferenceRegex constructor from 1s to 5s; no behavioral changes otherwise.

Sequence Diagram(s)

mermaid
sequenceDiagram
participant Caller
participant DockerContainer
participant DockerClient
participant DockerDaemon
Caller->>DockerContainer: ConnectAsync(networkName / INetwork)
DockerContainer->>DockerContainer: Acquire lock
DockerContainer->>DockerClient: Network.ConnectAsync(network, containerId)
DockerClient->>DockerDaemon: API: connect container to network
DockerDaemon-->>DockerClient: 200 OK
DockerClient-->>DockerContainer: Operation complete
DockerContainer->>DockerContainer: Refresh container state (ByIdAsync)
DockerContainer-->>Caller: Task completed

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Suggested labels

breaking change

Poem

🐰 I hopped where networks weave and bend,

Connected containers, one and friend,
A post-start bridge from string to name,
I twitch my nose — the links now game! 🌐

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: Add connect to network API' clearly and concisely summarizes the main change—introducing a new API for connecting containers to networks.
Description check	✅ Passed	The description addresses the mandatory sections with clear explanations of what the PR does and its importance, includes related issues, and follows the template structure.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/add-connect-to-network-api

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

src/Testcontainers/Containers/IContainer.cs (1)

256-270: LGTM!

The new ConnectAsync overloads are well-documented and follow the established interface patterns. Both methods clearly describe their purpose of connecting a running container to an existing network.

For consistency with other async methods like StartAsync and StopAsync, consider adding <exception> documentation tags for OperationCanceledException and TaskCanceledException.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/Testcontainers/Containers/IContainer.cs` around lines 256 - 270, Add
<exception> XML documentation entries to both ConnectAsync overloads to mirror
StartAsync/StopAsync: document that the method may throw
OperationCanceledException and TaskCanceledException when the provided
CancellationToken is canceled; update the summaries for Task ConnectAsync(string
network, CancellationToken ct = default) and Task ConnectAsync(INetwork network,
CancellationToken ct = default) to include these <exception> tags so the
interface's async method docs remain consistent.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@src/Testcontainers/Containers/IContainer.cs`:
- Around line 256-270: Add <exception> XML documentation entries to both
ConnectAsync overloads to mirror StartAsync/StopAsync: document that the method
may throw OperationCanceledException and TaskCanceledException when the provided
CancellationToken is canceled; update the summaries for Task ConnectAsync(string
network, CancellationToken ct = default) and Task ConnectAsync(INetwork network,
CancellationToken ct = default) to include these <exception> tags so the
interface's async method docs remain consistent.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 0216f42f-38ef-44b8-affc-f5be30053477

📥 Commits

Reviewing files that changed from the base of the PR and between 524bade and 066ee8e.

📒 Files selected for processing (5)

• docs/api/create_docker_network.md
• src/Testcontainers/Containers/DockerContainer.cs
• src/Testcontainers/Containers/IContainer.cs
• src/Testcontainers/Images/MatchImage.cs
• tests/Testcontainers.Platform.Linux.Tests/NetworkConnectTest.cs