feat(provider): publish-endpoint deploys a network relay for provider services

[ndeloof]

A provider's resource lives outside the compose network: consumers could only reach it through injected variables carrying a host-published address. This adds the transparent path:

• publish-endpoint provider message: {"type": "publish-endpoint", "message": "80=localhost:49152"} — container port consumers know on the left, real location on the right. Providers express that location naturally from the host's perspective; compose owns the translation to the relay's vantage point, rewriting host-relative addresses (localhost, any loopback IP, unspecified or empty host) to host.docker.internal — provisioned through ExtraHosts (host-gateway) so it also works on a plain Linux engine. LAN IPs and DNS names pass verbatim.
• Relay container: when endpoints are published, compose deploys docker/compose-relay (new relay/ directory: static Go TCP forwarder, FROM scratch, bake target relay-image, COMPOSE_RELAY_IMAGE override for internal registries) in place of the service — canonical <project>-<service>-1 name, service alias on the networks of the depending services. Consumers use http://<service>:<port>, no injected variables involved.
• First-class project container, full lifecycle: standard compose labels incl. config-hash, so label-driven commands run without the compose file (ps, logs, stop, down) keep seeing the service — plus com.docker.compose.relay (value: identity hash of image+routes) declaring its role:
  • up idempotent: relay kept when routes unchanged, recreated otherwise (reconciler already leaves provider services' containers alone);
  • down treats the relay as part of the provider service's deprovisioning: its containers are removed before the plugin removes the provider's resource — mirroring up, which provisions the resource before deploying the relay — so down -v releases the project network instead of failing on "resource is still in use";
  • exec/cp refuse a relay (no service process to act on);
  • the attached-up monitor excludes relays from the containers whose termination ends the command — they are long-lived infrastructure.

This benefits every provider: the example provider demonstrates the flow (detached HTTP helper + publish-endpoint), covered by an e2e scenario asserting http://db works from a consumer, exec db is refused, and down -v leaves no relay behind, plus unit tests (message parsing, upstream rewriting, route identity, network selection, relay guard, image override). A provider message compose cannot decode is now reported as an "invalid message" rather than an "invalid response" — providers push messages, they don't answer requests.

Standalone — no dependency on #14175 (the two protocol additions are orthogonal).

Publishing note for maintainers: the CI wiring is included — merge.yml publishes docker/compose-relay through the same github-builder pipeline as docker/compose-bin (edge from main; the v1 tag consumers pull moves only on compose release tags, since v1 is the image contract major, not a compose version), and PRs validate the cross build (relay-image-test). The one remaining step is org-side: create the docker/compose-relay Docker Hub repository and allow the existing registry identity to push to it.

🤖 Generated with Claude Code

[docker-agent]

Assessment: 🟢 APPROVE

This PR introduces a well-structured relay mechanism for provider services — the core logic in relay.go, plugins.go, and relay/main.go is sound. One low-severity issue was found in the example/demo code only.

[codecov]

Codecov Report

❌ Patch coverage is 61.23348% with 88 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
pkg/compose/relay.go	55.74%	67 Missing and 10 partials ⚠️
pkg/compose/plugins.go	82.14%	4 Missing and 1 partial ⚠️
pkg/compose/cp.go	20.00%	2 Missing and 2 partials ⚠️
pkg/compose/stop.go	33.33%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[ndeloof]

/review

[github-actions]

👋 Heads up: The /review command is deprecated. Please re-request a review from docker-agent in the PR sidebar instead.

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

Two findings in the new relay code introduced by this PR.

[ndeloof]

/review

[github-actions]

👋 Heads up: The /review command is deprecated. Please re-request a review from docker-agent in the PR sidebar instead.

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

Two medium-severity correctness/reliability issues and two low-severity issues were found in the new relay code.

Findings summary:

• relay/main.go: wg.Wait() does not drain active forward() connections on shutdown (medium, 🟢 strong 100/100)
• pkg/compose/relay.go: paused relay with matching identity is force-removed instead of unpaused (medium, 🟢 strong 97/100)
• pkg/compose/relay.go: missing existence check before project.Networks[key].Name (low, 🟡 moderate 57/100)
• docs/examples/provider.go: bufio.ReadString has no timeout when reading serve-demo address (low, 🟢 strong 100/100)

[ndeloof]

/review

[github-actions]

👋 Heads up: The /review command is deprecated. Please re-request a review from docker-agent in the PR sidebar instead.

[docker-agent]

Assessment: 🔴 CRITICAL

1 critical finding (high-severity CONFIRMED bug) and 1 minor finding (low-severity CONFIRMED).

---

Summary: The PR introduces a solid relay mechanism for provider services. The main correctness issue is an orphan container left behind when network attachment partially fails; the Dockerfile has a dead ARG that should be wired up.

[ndeloof]

/review

[github-actions]

👋 Heads up: The /review command is deprecated. Please re-request a review from docker-agent in the PR sidebar instead.

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

Two medium-confidence findings in the new relay code introduced by this PR.

[ndeloof]

/review

[github-actions]

👋 Heads up: The /review command is deprecated. Please re-request a review from docker-agent in the PR sidebar instead.

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

One medium-severity finding: the relay guard introduced by this PR is incomplete in pkg/compose/cp.go — the default branch (common cp usage without --index) skips the checkRelayTarget check that was correctly added to the options.Index > 0 branch.

[ndeloof]

/review

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

One medium-severity and one low-severity finding in the new relay code.

[docker-agent]

Assessment: 🟢 APPROVE

This PR adds transparent relay infrastructure for provider services that publish endpoints — a clean design that correctly handles the relay lifecycle (up idempotency, down ordering, exec/cp guards, monitor exclusion). The implementation is solid overall.

Two minor correctness issues found in the new relay binary:

[docker-agent]

[low] Backoff cap overshoots intended 1s maximum — actual max sleep is 1280ms

The condition if backoff < time.Second { backoff *= 2 } fires the cap check after computing the new value, not before. Walking the doubling sequence from 5ms: 5→10→20→40→80→160→320→640→1280ms (because 640 < 1000, so it doubles to 1280; then 1280 >= 1000, so it stops). The maximum sleep is 1280ms, 28% above the apparent 1s intent.

Suggested change

	time.Sleep(backoff)
	if backoff < 500*time.Millisecond {
	backoff *= 2
	}

This caps at 1s exactly (640ms doubles to 1280ms → blocked; 320ms doubles to 640ms → allowed). Alternatively, use backoff = min(backoff*2, time.Second) (Go 1.21+, available since this module declares go 1.23).

Confidence	Score
🟢 strong	100/100

[docker-agent]

[low] hostIsContainerLocal uses case-sensitive "localhost" comparison while the compose-side relayUpstream uses strings.EqualFold

relay/main.go normalizes loopback addresses in parseRoutes using hostIsContainerLocal, which checks host == "localhost" (case-sensitive). The compose side in pkg/compose/relay.go:relayUpstream uses strings.EqualFold(host, "localhost"), so it correctly handles "LOCALHOST" or "Localhost".

In the normal flow this gap is unexposed — compose always pre-rewrites upstreams before setting RELAY_ROUTES, so the relay binary never receives an unnormalized "LOCALHOST". However, a user (or a future provider) who sets RELAY_ROUTES manually, or tests the relay image directly, may encounter unexpected behaviour: RELAY_ROUTES=80=LOCALHOST:5432 would silently pass through without rewriting to host.docker.internal, causing dial failures inside the container.

Suggested change

	func hostIsContainerLocal(host string) bool {
	func hostIsContainerLocal(host string) bool {
	if strings.EqualFold(host, "localhost") {
	return true
	}
	ip := net.ParseIP(host)
	return ip != nil && (ip.IsLoopback() || ip.IsUnspecified())
	}

Confidence	Score
🟡 moderate	57/100

[docker-agent]

This review covers only the commits pushed since 1a53da7 (the previous review checkpoint). Earlier commits were already reviewed.

Assessment: 🟢 APPROVE

The incremental diff adds a single docker-bake.hcl change: the existing relay-image target (which previously combined tags and platforms into one definition) is split into two:

• relay-image — local/dev build, tag docker/compose-relay:v1, uses host platform by default (no explicit platforms list). This is the correct pattern for local development builds.
• relay-image-cross — CI publication target, inherits from meta-helper (for workflow-supplied tags/labels), covers all seven Linux platforms that the compose binary itself ships for (amd64, arm/v6, arm/v7, arm64, ppc64le, riscv64, s390x). The omission of darwin/windows is correct and documented in the comment (the relay runs as a container on the engine).

The output = ["type=image"] line in relay-image-cross is correct: the reusable docker/github-builder bake workflow receives push: true in merge.yml and push: false in ci.yml (PR builds), and manages push externally — Docker Buildx's --push flag overrides/supplements the bake target's output field. This is consistent with how image-cross and other cross-compilation targets are handled in this repository.

No issues introduced by this change.

[docker-agent]

This review covers only the commits since 32f8767abdf6.

Assessment: 🟢 APPROVE

This incremental diff is documentation-only: it reorganises the publish-endpoint description in docs/extension.md into a dedicated section ("Compose-native addressing with publish-endpoint") with a Mermaid sequence diagram, and updates the inline listing to link to that section. The new prose is accurate, the anchor link matches the section heading, the sequence diagram correctly depicts the provider→Compose message flow and the relay deployment, and all relay behaviour details (loopback→host.docker.internal translation, host-gateway, container labels, exec/cp refusal, recreation on endpoint change) are faithfully described in the new section.

[glours]

Worth checking:

compose stop on a provider service short-circuits straight into runPlugin(ctx, project, serv, "stop") (pkg/compose/stop.go:55-59) without ever calling stopContainers, this file isn't touched by this PR.

Since this PR gives a provider service a real, persistent relay container (RestartPolicyUnlessStopped), compose stop now leaves that relay running and still Up in compose ps, contradicting docs/extension.md's claim that stop treats the relay like the service.

down.go's new downService got the relay-aware fix (stop/remove containers before invoking the plugin); stop.go needs the same treatment but wasn't updated in this PR.

[ndeloof]

Good catch — fixed in af10501: stop.go now stops the service's containers (relay included) unconditionally before invoking the plugin's own stop hook, mirroring downService's existing pattern. start/restart needed no change, neither special-cases providers so they already operate on whatever containers match the service filter. Extended TestProviderPublishEndpoint with stop/start/restart coverage of the relay container; verified locally that reverting just this change makes the new step fail.

[docker-agent]

This review covers only the commits pushed since 5f875dd.

Assessment: 🟢 APPROVE

The single-file change in this incremental diff correctly reorders stopContainers before runPlugin for provider services in pkg/compose/stop.go, mirroring the established pattern in down.go. Error propagation is correct: stopContainers errors return immediately, and runPlugin errors are returned via the explicit return s.runPlugin(...) call. No logic errors, resource leaks, nil-dereferences, or other issues found.

[glours]

Fixes for potential follow up PRs

1. Relay never reconnects to new networks when routes are unchanged (pkg/compose/relay.go:93-96 relayIdentity, :140-197 ensureServiceRelay) — identity hashes only image+routes, not network topology. When an already-running relay's identity still matches, ensureServiceRelay returns early without checking whether networkKeys includes a network the relay isn't attached to yet. A dependent service added on a new network after the relay is already up can never reach the provider through it, silently.

2. Stale relay is never cleaned up if the provider stops publishing endpoints (pkg/compose/plugins.go:101,126-134, pkg/compose/reconcile.go:638-654), deployRelay is only evaluated when endpoints are non-empty; if a later up reports zero endpoints, nothing removes or revalidates the existing relay. The generic reconciler doesn't catch it either: it returns immediately for any service.Provider != nil before reaching the observed-state/recreate logic that would otherwise clean it up.

3. start/restart don't guard against acting on the relay container (pkg/compose/service_containers.go:619-641, pkg/compose/restart.go:109-131) — unlike exec.go/cp.go, which call checkRelayTarget to refuse a relay, startServiceContainer/restartContainer unconditionally inject secrets/configs and run PostStart/PreStop hooks against any container matching isService(name), relay included. Compose-spec schema doesn't forbid secrets/configs/hooks on a provider: service, so this is reachable.

4. No goroutine-leak test coverage for the new relay code (relay/main_test.go) — the module spawns several goroutines (accept loop, per-connection forward pairs, idle-reap) but has no goleak check, despite goleak being an established convention elsewhere in the repo (e.g. pkg/compose/pre_start_test.go).

5. The relay/ Go module isn't wired into CI lint or test — it's a separate module (relay/go.mod), so golangci-lint run ./... and go test ./... from the repo root never touch it; CI only does go build inside relay/Dockerfile. Practically, relay/main_test.go's two regression tests locking the idle-reap/half-close fix never run in CI, and running golangci-lint manually against relay/ surfaces 8 real issues (5 unchecked Close() errors, one %v→%w, one exitAfterDefer, one staticcheck hit).