Skip to content

[Bugfix][TransferEngine] Enable TCP connection pooling by default - #4464

Open
guptaishaan wants to merge 1 commit into
kvcache-ai:mainfrom
guptaishaan:fix-3540
Open

guptaishaan wants to merge 1 commit into
kvcache-ai:mainfrom
guptaishaan:fix-3540

Conversation

@guptaishaan

Copy link
Copy Markdown
Contributor

Description

Fixes #3540.

TCP connection lanes were disabled unless MC_TCP_ENABLE_CONNECTION_POOL was set. Same-IP concurrent workloads therefore opened one connection per transfer and could exhaust the per-destination ephemeral port space.

Enable the existing bounded connection lanes by default. MC_TCP_ENABLE_CONNECTION_POOL=0 remains an explicit opt-out.

Thanks to @absoluteword for reporting the failure.

Module

  • Transfer Engine (mooncake-transfer-engine)
  • Mooncake Store (mooncake-store)
  • Reshard (mooncake-reshard)
  • Mooncake EP (mooncake-ep)
  • Mooncake PG (mooncake-pg)
  • Integration (mooncake-integration)
  • P2P Store (mooncake-p2p-store)
  • Python Wheel (mooncake-wheel)
  • Common (mooncake-common)
  • Mooncake RL (mooncake-rl)
  • CI/CD
  • Docs
  • Other

Type of Change

  • Bug fix
  • New feature
  • Refactor
  • Breaking change
  • Documentation update
  • Performance improvement
  • Other

How Has This Been Tested?

Reproduced connect: Cannot assign requested address by submitting 30,000 outstanding Mooncake TCP writes to the node's non-loopback IP. The permanent regression test fails before the fix with eight accepted sockets and passes after the fix with one reused socket.

Tested on Linux with 8 NVIDIA A40 GPUs present. The Transfer Engine build and tests were CPU-only.

The exact vLLM DP deployment, Docker setup, RTX PRO 6000 Blackwell, and B300 were not available. The legacy tcp_transport_test also requires a metadata service not present in this test build.

Test commands:

cmake --build /tmp/mooncake-3540-te-build-ready --target tcp_write_visibility_test -j 12
/tmp/mooncake-3540-te-build-ready/tests/tcp_write_visibility_test
pre-commit run --files mooncake-transfer-engine/include/transport/tcp_transport/tcp_transport.h mooncake-transfer-engine/tests/tcp_write_visibility_test.cpp

Test results:

  • Unit tests pass
  • Integration tests pass (if applicable)
  • Manual testing done (described above)

Checklist

  • I have performed a self-review of my own code
  • I have formatted my code using ./scripts/code_format.sh
  • I have run pre-commit on the files changed in this PR and all hooks pass
  • I have updated the documentation (not applicable)
  • I have added tests to prove my changes are effective
  • For changes >500 LOC: I have filed an RFC issue (not applicable)

AI Assistance Disclosure

  • No AI tools were used
  • AI tools were used (specify below)

OpenAI Codex reproduced the failure, traced the TCP connection path, implemented the change, and ran the tests. The human submitter must review every changed line and be able to defend the change.

One-shot TCP connections can exhaust the ephemeral port space when several
instances share one node and destination IP. Enable the existing bounded
connection lanes by default while preserving the explicit disable setting.

Add a regression test that verifies requests reuse one connection when the
pool setting is absent.
@absoluteword

absoluteword commented Oct 3, 2026 via email

Copy link
Copy Markdown

@he-yufeng he-yufeng left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The behavioral half of this PR is already on main: 36fdd89 (#3569) flipped enable_connection_pool_ to true, so against current main this diff's tcp_transport.h change is a no-op and the PR will rebase down to the test updates.

Those test updates are worth keeping, though, and I'd suggest reframing the PR around them: OneLaneReusesCleanSocketInFifoOrder currently forces pooling via the env var, which stops being a meaningful exercise of the path users actually get now that pooling is the default. Pointing the test at the default configuration (with ScopedEnvVar gaining the unset support you added) is the right hardening. One nit on the rebase: keep the env override coverage somewhere, since MC_TCP_ENABLE_CONNECTION_POOL=0 is now the only way to get the unpooled behavior and that knob deserves a test that pins it.

@he-yufeng he-yufeng left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for picking up #3540. One heads-up on the base: the default-on flip already shipped in #3569 (merged Aug 24). Current main reads bool enable_connection_pool_ = true;, so the header hunk here rebases to a no-op. The PR looks like it was cut from a pre-flip tree.

The part that still adds value against main is the test hardening:

  • ScopedEnvVar learning to unsetenv on nullptr
  • DefaultConnectionPoolReusesCleanSocket pinning the default-on contract explicitly, so the reuse behavior is exercised even if whoever runs the suite has MC_TCP_ENABLE_CONNECTION_POOL set in their shell

Worth rebasing onto current main and keeping just that part. Related: #4473 updates the docs for the same flip (flag is now an opt-out, 0/false/no).

@alogfans

Copy link
Copy Markdown
Collaborator

Please fix conflicts before merging

@absoluteword

absoluteword commented Oct 23, 2026 via email

Copy link
Copy Markdown

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: Error occurs when Mooncake runs with multiple instances or DP on a single node under the same IP

4 participants