feat: Ignore port-forwarding extra host in reuse hash

[HofmeisterAn]

What does this PR do?

The PR ignores the port-forwarding extra host value in the reuse hash. That value is set as soon as the port-forwarding container runs.

Why is it important?

TBH, I'm not sure this change is ideal. I wouldn't expect reuse + port-forwarding to work reliably anyway, because the port-forwarding container is currently a singleton and gets recreated for every test session (process). As a result, it ends up with different IP addresses, which leads to different container configurations and therefore different reuse hashes.

I believe ignoring it for now enables more use cases. Once we can reuse the port-forwarding container itself, this likely won't be necessary anymore.

Related issues

• Closes [Enhancement]: PortForwardingContainer breaks reuse hash #1673

Summary by CodeRabbit

• New Features

  • Runtime-dependent host entries are now filtered from container extra hosts configuration during serialization.

• Documentation

  • Added clarification on container label handling for configuration reuse.

[netlify]

✅ Deploy Preview for testcontainers-dotnet ready!

Name	Link
🔨 Latest commit	0c4367f
🔍 Latest deploy log	https://app.netlify.com/projects/testcontainers-dotnet/deploys/69feefd3c6e7df000889c9fa
😎 Deploy Preview	https://deploy-preview-1689--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]

Walkthrough

This PR adds a JSON converter (JsonIgnoreRuntimeExtraHosts) to filter runtime-dependent extra hosts from container configuration serialization, preventing PortForwardingContainer-added host entries from affecting the container reuse hash across test sessions.

Changes

Runtime ExtraHosts Serialization Filtering

Layer / File(s)	Summary
JSON Converter Implementation src/Testcontainers/Configurations/Commons/JsonIgnoreRuntimeExtraHosts.cs	New internal converter filters entries matching host.testcontainers.internal: (case-insensitive) during serialization, sorts remaining host strings, and delegates deserialization to the default deserializer.
Property Integration src/Testcontainers/Configurations/Containers/ContainerConfiguration.cs	[JsonConverter(typeof(JsonIgnoreRuntimeExtraHosts))] attribute applied to the ExtraHosts property to activate filtering during configuration serialization.
Documentation src/Testcontainers/Configurations/Commons/JsonIgnoreRuntimeResourceLabels.cs	XML documentation added explaining that JsonIgnoreRuntimeResourceLabels excludes session-specific labels from the reuse hash for stable container reuse across test sessions.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• testcontainers/testcontainers-dotnet#1555: Adjusts how ExtraHosts are handled in serializer configuration; both PRs address reuse hashing with runtime-added extra hosts.

Poem

A rabbit hops through the code so clean,
Filtering hosts that shouldn't be seen—
Runtime whispers fade from the hash,
Containers reuse without a clash! 🐰✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title accurately describes the main change: ignoring port-forwarding extra host entries in the reuse hash calculation.
Description check	✅ Passed	The PR description covers what the change does and why, with a reference to the related issue, meeting template requirements.
Linked Issues check	✅ Passed	The PR implements the core requirement from issue #1673 by filtering out runtime-dependent port-forwarding extra hosts from reuse hash calculations.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing the port-forwarding extra host filtering mechanism required by the linked issue.

_{✏️ 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/ignore-port-forwarding-extra-host-in-reuse-hash

---

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]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/Testcontainers/Configurations/Commons/JsonIgnoreRuntimeExtraHosts.cs`:
- Around line 18-21: The Read override in JsonIgnoreRuntimeExtraHosts calls
JsonSerializer.Deserialize<IEnumerable<string>>(ref reader) which can return
null for JSON null; update the Read method to capture the result in a local
variable, check for null and return Enumerable.Empty<string>() instead of
propagating null (ensure System.Linq is available), so the method always returns
a non-null IEnumerable<string>.
- Around line 23-27: The Write method in JsonIgnoreRuntimeExtraHosts currently
calls value.Where(...) which will throw if value is null; update
Write(Utf8JsonWriter writer, IEnumerable<string> value, JsonSerializerOptions
options) to guard for null by treating a null value as an empty sequence (e.g.,
use value ?? Enumerable.Empty<string>()), filter out any null elements and then
apply the StartsWith filter and OrderBy before serializing; reference the Write
method and PortForwardingHostEntry constant when making the change.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 28d6ecf0-fbb0-4431-97be-ec6fcb19573e

📥 Commits

Reviewing files that changed from the base of the PR and between 444958d and 0c4367f.

📒 Files selected for processing (3)

• src/Testcontainers/Configurations/Commons/JsonIgnoreRuntimeExtraHosts.cs
• src/Testcontainers/Configurations/Commons/JsonIgnoreRuntimeResourceLabels.cs
• src/Testcontainers/Configurations/Containers/ContainerConfiguration.cs