feat: allow ingress to share a single port with pull_api (#183)

[7schmiede]

Summary

Lets the ingress listener share a single port with pull_api (and, transitively, admin_api) via path-prefix muxing — the same mechanism that already backs the pull_api == admin_api shared listener. Previously ingress.listen sharing an address with pull/admin was a hard compile error, forcing multi-port deployments even when a single published port would be simpler (reverse-proxy path-routing, single-published-port orchestrators).

When ingress.listen equals pull_api.listen (and/or admin_api.listen), the components are served on one net.Listener:

• ingress serves its bare route paths (/webhooks/...) as the default handler;
• pull/admin serve under their existing prefix values (/pull, /admin);
• dispatch is by path prefix, ingress being the fallback.

Strictly opt-in (inferred from equal listen addresses); the multi-port topology remains the default and recommended posture. No new DSL keyword.

Related Issues

Closes #183

Scope

• DSL / config behavior
• Runtime behavior
• MCP behavior
• Documentation only

What changed

Config (internal/config/compile.go)

• Removed the unconditional ingress.listen must not share … guard.
• New validateSharedListeners generalizes shared-listener validation across ingress/pull/admin grouped by address. For every shared address it enforces:
  • co-listening API servers have non-empty, distinct, non-overlapping prefix values (reuses hasPathPrefix);
  • no ingress route path collides with (shadows or is shadowed by) a co-listening API prefix — the new check ingress introduces, since ingress paths are user-defined;
  • identical TLS across everything on the shared address.
• pull_api.grpc_listen and observability.metrics.listen keep their existing dedicated-listener guards.
• New Compiled.IngressShared flag; surfaced as ingress_shared in the MCP config_compile summary + runtime-control status; added to the restart-required reload set.

Runtime (internal/app/run.go)

• HTTP components (ingress / pull / admin) are grouped by listen address; each group becomes one http.Server. Multi-member groups are muxed by a generalized prefixMux (replaces sharedPrefixMux) with ingress as the default handler. Per-component tracing/access-log wrapping preserved.

Validation

• go test ./... passed locally (Go 1.26.4)
• Added tests for behavioral changes
• Updated docs for user-visible changes
• Updated CHANGELOG.md
• Updated BACKLOG.md / STATUS.md

Tests added:

• internal/config: valid single-port config compiles and sets the flag; all-three-shared; ingress-route-path/prefix collision rejected; empty prefix rejected; TLS mismatch rejected. Repurposed the obsolete IngressMustNotShareListener test into IngressShareWithoutPrefixRejected.
• internal/e2e: TestBinaryE2E_SinglePortIngressPull — POST to /webhooks/... and dequeue/ack via the Pull API on the same port.

Manual check against a real binary:

config validate (ingress :8080 + pull_api :8080 prefix /pull)  -> config ok            (exit 0)
config validate (ingress route /pull/... vs pull_api.prefix /pull)
  -> config invalid: shared listener: ingress route path "/pull/github"
     collides with pull_api.prefix "/pull" …                    (exit 1)

Security and Operations

• No secrets or credentials committed
• Auth/policy implications reviewed — Pull/Admin auth and TLS semantics unchanged; TLS must be identical across a shared address (enforced at compile time).
• Backward compatibility considered — default topology and existing pull_api == admin_api shared listener behavior are unchanged; the feature only activates on explicitly equal listen addresses.

Notes for Reviewers

• The runtime server construction was refactored from the branchy SharedListener/else into address-based grouping. It reproduces the previous topology for the default and pull_api == admin_api cases (verified by the existing e2e/unit suites) and adds the ingress-sharing cases.
• Toggling the shared-listener mode remains restart-required (documented; also enforced via IngressShared in the reload gate).

🤖 Generated with Claude Code