fix: setup ExposeHostPorts forward on container start hook

[mdelapenya]

Fixes #2811

Previously ExposedHostPorts would start an SSHD container prior to
starting the testcontainer and inject a PostReadies lifecycle hook into
the testcontainer in order to set up remote port forwarding from the
host to the SSHD container so the testcontainer can talk to the host via
the SSHD container

This would be an issue if the testcontainer depends on accessing the
host port on startup ( e.g., a proxy server ) as the forwarding for the
host access isn't set up until all the WiatFor strategies on the
testcontainer have completed.

The fix is to move the forwarding setup to the PreCreates hook on the
testcontainer. Since remote forwarding doesn't establish a connection to
the host port until a connection is made to the remote port, this should
not be an issue even if the host isn't listening yet and ensures the
remote port is available to the testcontainer immediately.

What does this PR do?

Changes the lifecycle hook for the ExposedHostPorts forwarding to happen on PreCreates of the testcontainer instead of PostReadies. Additionally updates the port forwarding tests to ensure the host ports are accessible on startup and that there's no issues even if the host isn't listening until PostCreates.

Why is it important?

Previously ExposedHostPorts would start an SSHD container prior to starting the testcontainer and inject a PostReadies lifecycle hook into the testcontainer in order to set up remote port forwarding from the host to the SSHD container so the testcontainer can talk to the host via the SSHD container

This would be an issue if the testcontainer depends on accessing the host port on startup ( e.g., a proxy server ) as the forwarding for the host access isn't set up until all the WiatFor strategies on the testcontainer have completed.

Related issues

• Fixes [Bug]: Unable to connect to HostAccessPorts on container startup #2811

How to test this PR

go test port_forwarding_test.go

Additionally, I've provided a minimal example of my use case where I ran into the issue trying to test my Caddy configuration as an API gateway using testcontainers.

package caddy_test

import (
	"bytes"
	"context"
	"fmt"
	"io"
	"net"
	"net/http"
	"net/http/httptest"
	"testing"

	"github.com/stretchr/testify/assert"
	"github.com/stretchr/testify/require"
	"github.com/testcontainers/testcontainers-go"
	"github.com/testcontainers/testcontainers-go/wait"
)

const caddyFileContent = `
listen :80

reverse_proxy /api/* {
	to {$API_SERVER}

	health_uri /health
	health_status 200
	health_interval 10s
}
`

func TestCaddyfile(t *testing.T) {
	ctx := context.Background()

	apiServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "Hello, World!")
	}))
	apiServerPort := apiServer.Listener.Addr().(*net.TCPAddr).Port

	caddyContainer, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
		ContainerRequest: testcontainers.ContainerRequest{
			Image:        "caddy:2.8.4",
			ExposedPorts: []string{"80/tcp"},
			WaitingFor:   wait.ForLog("server running"),
			Env: map[string]string{
				"API_SERVER": fmt.Sprintf("http://%s:%d", testcontainers.HostInternal, apiServerPort),
			},
			Files: []testcontainers.ContainerFile{
				{
					Reader:            bytes.NewReader([]byte(caddyFileContent)),
					ContainerFilePath: "/etc/caddy/Caddyfile",
				},
			},
			HostAccessPorts: []int{apiServerPort},
		},
		Started: true,
	})
	require.NoError(t, err)
	defer caddyContainer.Terminate(ctx)

	caddyURL, err := caddyContainer.PortEndpoint(ctx, "80/tcp", "http")
	require.NoError(t, err)

	resp, err := http.Get(caddyURL + "/api/test")
	require.NoError(t, err)
	defer resp.Body.Close()

	body, err := io.ReadAll(resp.Body)
	require.NoError(t, err)

	assert.Equal(t, http.StatusOK, resp.StatusCode)
	assert.Equal(t, "Hello, World!", string(body))

	lr, err := caddyContainer.Logs(ctx)
	assert.NoError(t, err)
	lb, err := io.ReadAll(lr)
	assert.NoError(t, err)
	fmt.Printf("== Caddy Logs ==\n%s================\n\n", string(lb))
}

[netlify]

✅ Deploy Preview for testcontainers-go ready!

Name	Link
🔨 Latest commit	55b28d1
🔍 Latest deploy log	https://app.netlify.com/projects/testcontainers-go/deploys/69bdcbd24b99310008d957ca
😎 Deploy Preview	https://deploy-preview-3200--testcontainers-go.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.

[kberezin-nshl]

When is this going to be merged @mdelapenya @stevenh ?

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 459438a3-db9c-4b8f-b447-572ced8c629d

📥 Commits

Reviewing files that changed from the base of the PR and between 092e175 and 55b28d1.

📒 Files selected for processing (2)

• modules/solace/solace.go
• port_forwarding.go

✅ Files skipped from review due to trivial changes (1)

• modules/solace/solace.go

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

• port_forwarding.go

---

Summary by CodeRabbit

• Bug Fixes

  • Extended Solace service readiness check timeouts to improve startup reliability: primary router validation now waits up to 2 minutes, and port listening checks have 30-second timeouts.

• Tests

  • Enhanced port forwarding verification with comprehensive per-port testing to ensure all exposed ports are properly validated.

Walkthrough

SSH tunnel setup for HostAccessPorts moved from container-readiness (PostReadies) to container-creation (PreCreates) phase, enabling host port forwarding before container startup. Callback signature updated to accept ContainerRequest instead of Container. Tests enhanced with per-port forwarding verification. Solace module wait strategy timeouts increased.

Changes

Cohort / File(s)	Summary
SSH Tunnel Hook Migration port_forwarding.go	Relocated SSH tunnel setup hook from PostReadies to PreCreates lifecycle phase; callback signature changed to accept ContainerRequest for direct access to HostAccessPorts configuration.
Port Forwarding Verification port_forwarding_test.go	Added per-port forwarding validation with individual httptest servers for each configured host port; includes per-port wait strategies with wget-based health checks and explicit cleanup.
Wait Strategy Timeouts modules/solace/solace.go	Extended primary Solace readiness startup timeout from 1 to 2 minutes; added explicit 30-second startup timeout to per-port listening wait strategies.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~18 minutes

Poem

🐰 Before the container takes its stand,
The tunnel's built with careful hand,
Host ports now reachable from the start,
Per-port checks verify each part,
Timeouts generous—all systems smart! 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% 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 'fix: setup ExposeHostPorts forward on container start hook' directly and clearly describes the main change: moving the ExposeHostPorts forwarding setup to an earlier container lifecycle hook.
Description check	✅ Passed	The PR description comprehensively explains the issue, the fix, why it matters, includes test instructions, and provides a realistic example demonstrating the use case that required this change.
Linked Issues check	✅ Passed	The code changes fully address issue #2811 by moving ExposeHostPorts forwarding from PostReadies to PreCreates hook, enabling host port access during container startup and wait strategies as required.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the objectives: port_forwarding.go refactors the hook lifecycle, port_forwarding_test.go validates per-port forwarding, and solace.go adjusts timeouts to accommodate earlier hook execution.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

Tip

You can enable review details to help with troubleshooting, context usage and more.

Enable the reviews.review_details setting to include review details such as the model used, the time taken for each step and more in the review comments.

[mdelapenya]

@kberezin-nshl my bad, this PR was piled in the list. Thanks for the ping 🙏

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ec51c67 and 1f48580.

📒 Files selected for processing (2)

• port_forwarding.go (1 hunks)
• port_forwarding_test.go (1 hunks)

🧰 Additional context used

🧠 Learnings (2)

📚 Learning: 2025-09-29T13:57:14.636Z

Learnt from: mdelapenya
Repo: testcontainers/testcontainers-go PR: 3319
File: modules/arangodb/arangodb.go:46-57
Timestamp: 2025-09-29T13:57:14.636Z
Learning: In testcontainers-go ArangoDB module, the wait strategy combines port listening check with HTTP readiness check using wait.ForAll - both strategies are required and complementary, not redundant.

Applied to files:

• port_forwarding_test.go

📚 Learning: 2025-09-29T15:08:18.694Z

Learnt from: mdelapenya
Repo: testcontainers/testcontainers-go PR: 3320
File: modules/artemis/artemis.go:98-103
Timestamp: 2025-09-29T15:08:18.694Z
Learning: In testcontainers-go, nat.Port is a type alias for string, so untyped string constants can be passed directly to functions expecting nat.Port (like wait.ForListeningPort) without explicit type conversion - the Go compiler handles the implicit conversion automatically.

Applied to files:

• port_forwarding_test.go

🧬 Code graph analysis (2)

port_forwarding.go (2)

lifecycle.go (2)

• ContainerLifecycleHooks (43-55)
• ContainerRequestHook (24-24)

container.go (1)

• ContainerRequest (131-171)

port_forwarding_test.go (3)

wait/wait.go (1)

• Strategy (17-19)

wait/exec.go (1)

• ForExec (72-74)

port_forwarding.go (1)

• HostInternal (28-28)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (20)

• GitHub Check: lint (modules/cassandra) / lint: modules/cassandra
• GitHub Check: lint (modules/artemis) / lint: modules/artemis
• GitHub Check: lint (modules/grafana-lgtm) / lint: modules/grafana-lgtm
• GitHub Check: lint (modules/aerospike) / lint: modules/aerospike
• GitHub Check: lint (modules/solace) / lint: modules/solace
• GitHub Check: lint (modules/mockserver) / lint: modules/mockserver
• GitHub Check: lint / lint:
• GitHub Check: lint (modules/meilisearch) / lint: modules/meilisearch
• GitHub Check: lint (modules/mongodb) / lint: modules/mongodb
• GitHub Check: lint (modules/surrealdb) / lint: modules/surrealdb
• GitHub Check: lint (modules/dynamodb) / lint: modules/dynamodb
• GitHub Check: lint (modules/couchbase) / lint: modules/couchbase
• GitHub Check: lint (modules/azurite) / lint: modules/azurite
• GitHub Check: lint (modules/mssql) / lint: modules/mssql
• GitHub Check: lint (modules/k3s) / lint: modules/k3s
• GitHub Check: lint (modules/elasticsearch) / lint: modules/elasticsearch
• GitHub Check: lint (modules/gcloud) / lint: modules/gcloud
• GitHub Check: lint (modules/postgres) / lint: modules/postgres
• GitHub Check: lint (modules/cockroachdb) / lint: modules/cockroachdb
• GitHub Check: Analyze (go)

🔇 Additional comments (2)

port_forwarding.go (1)

163-173: LGTM! Lifecycle hook change correctly fixes the issue.

Moving SSH tunnel setup from PostReadies to PreCreates ensures host ports are accessible during container startup and wait strategies. The hook signature change from ContainerHook to ContainerRequestHook is correct, and req.HostAccessPorts is available at this lifecycle stage. Since SSH remote port forwarding (line 316) only establishes the listener and doesn't require an active host connection until traffic arrives, this earlier setup aligns with the PR objectives.

port_forwarding_test.go (1)

42-51: Wait strategies are never used—test doesn't verify the fix.

The wait strategies verify that host ports are accessible during container startup (the core behavior this PR fixes), but they are never applied to any container request. Without these wait strategies, the test cannot confirm that ports are reachable before the container becomes ready.

Add the wait strategies to the container request. For example, in testExposeHostPorts or pass them as a parameter and combine them with wait.ForAll:

func testExposeHostPorts(t *testing.T, hostPorts []int, waitStrats []wait.Strategy, hasNetwork, hasHostAccess bool) {
	// ... existing code ...
	
	opts := []testcontainers.ContainerCustomizer{
		testcontainers.WithHostPortAccess(hostAccessPorts...),
		testcontainers.WithCmd("top"),
	}
	
	if hasHostAccess && len(waitStrats) > 0 {
		opts = append(opts, testcontainers.WithWaitStrategy(wait.ForAll(waitStrats...)))
	}
	
	// ... rest of function
}

Then update the test calls to pass the wait strategies, e.g.:

testExposeHostPorts(t, singlePort, waitStrategies[0:1], false, false)

⛔ Skipped due to learnings

Learnt from: mdelapenya
Repo: testcontainers/testcontainers-go PR: 3319
File: modules/arangodb/arangodb.go:46-57
Timestamp: 2025-09-29T13:57:14.636Z
Learning: In testcontainers-go ArangoDB module, the wait strategy combines port listening check with HTTP readiness check using wait.ForAll - both strategies are required and complementary, not redundant.

Learnt from: mdelapenya
Repo: testcontainers/testcontainers-go PR: 3320
File: modules/artemis/artemis.go:98-103
Timestamp: 2025-09-29T15:08:18.694Z
Learning: In testcontainers-go, nat.Port is a type alias for string, so untyped string constants can be passed directly to functions expecting nat.Port (like wait.ForListeningPort) without explicit type conversion - the Go compiler handles the implicit conversion automatically.

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1f48580 and 5f56647.

📒 Files selected for processing (1)

• port_forwarding_test.go (1 hunks)

🧰 Additional context used

🧠 Learnings (2)

📚 Learning: 2025-09-29T15:08:18.694Z

Learnt from: mdelapenya
Repo: testcontainers/testcontainers-go PR: 3320
File: modules/artemis/artemis.go:98-103
Timestamp: 2025-09-29T15:08:18.694Z
Learning: In testcontainers-go, nat.Port is a type alias for string, so untyped string constants can be passed directly to functions expecting nat.Port (like wait.ForListeningPort) without explicit type conversion - the Go compiler handles the implicit conversion automatically.

Applied to files:

• port_forwarding_test.go

📚 Learning: 2025-09-29T13:57:14.636Z

Learnt from: mdelapenya
Repo: testcontainers/testcontainers-go PR: 3319
File: modules/arangodb/arangodb.go:46-57
Timestamp: 2025-09-29T13:57:14.636Z
Learning: In testcontainers-go ArangoDB module, the wait strategy combines port listening check with HTTP readiness check using wait.ForAll - both strategies are required and complementary, not redundant.

Applied to files:

• port_forwarding_test.go

🧬 Code graph analysis (1)

port_forwarding_test.go (3)

wait/wait.go (1)

• Strategy (17-19)

wait/exec.go (1)

• ForExec (72-74)

port_forwarding.go (1)

• HostInternal (28-28)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (14)

• GitHub Check: Redirect rules - testcontainers-go
• GitHub Check: Header rules - testcontainers-go
• GitHub Check: Pages changed - testcontainers-go
• GitHub Check: lint (modules/registry) / lint: modules/registry
• GitHub Check: lint (modules/meilisearch) / lint: modules/meilisearch
• GitHub Check: lint (modules/dockermodelrunner) / lint: modules/dockermodelrunner
• GitHub Check: lint (modules/azurite) / lint: modules/azurite
• GitHub Check: lint (modules/dynamodb) / lint: modules/dynamodb
• GitHub Check: lint (modules/qdrant) / lint: modules/qdrant
• GitHub Check: lint (modules/mssql) / lint: modules/mssql
• GitHub Check: lint (modules/nats) / lint: modules/nats
• GitHub Check: lint (modules/mongodb) / lint: modules/mongodb
• GitHub Check: lint (modules/postgres) / lint: modules/postgres
• GitHub Check: Analyze (go)

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

New waitStrategies are never used; clarify intent or remove to avoid dead code

The waitStrategies slice is fully populated with wait.ForExec(...).WithExitCodeMatcher(...).WithResponseMatcher(...), but it’s never read or passed into testExposeHostPorts / container options. As written, the new wait logic has no effect, and the tests still only validate host access via the explicit containerHasHostAccess / containerHasNoHostAccess calls after the container is started.

Similarly, the servers slice is only written to and never read, so it’s functionally redundant right now.

Depending on your intent:

• If these strategies are meant to assert that host ports are reachable during container startup (per the PR description), you likely want to plumb them into the container’s waiting strategy (e.g., via a WaitingFor / wait customization) and possibly thread them into testExposeHostPorts.
• If they’re not required, consider removing waitStrategies (and the wait import) and possibly the unused servers slice to keep the test simple and avoid confusion.

Also applies to: 37-49

🤖 Prompt for AI Agents

In port_forwarding_test.go around lines 18 to 31 (and similarly 37 to 49), the
slices waitStrategies and servers are built but never used; either wire them
into the container waiting logic or remove them — to fix quickly, delete the
wait import, the waitStrategies and servers declarations and all code that
populates them (including the per-port wait.ForExec(...) setup), and remove any
related unused variables so the test only keeps hostPorts and the actual
assertions; if you prefer to use them instead, pass the corresponding
wait.Strategy into the container creation (e.g., via
WaitingFor/WithStartupTimeout or by extending testExposeHostPorts to accept and
apply a per-port wait strategy) and ensure servers is read where its
httptest.Servers are needed.

[kberezin-nshl]

Any updates here? 🙏