[PR #1392] [MERGED] [TE] Add configurable handshake max length via MC_HANDSHAKE_MAX_LENGTH #2215

New issue

Closed

opened 2026-10-29 21:33:44 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 21:33:44 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/Mooncake/pull/1392
Author: @herrluk
Created: 1/16/2026
Status: ✅ Merged
Merged: 1/22/2026
Merged by: @stmatengss

Base: main ← Head: feature/configurable-handshake-max-length

📝 Commits (1)

90d797c [TE] Add configurable handshake max length via MC_HANDSHAKE_MAX_LENGTH

📊 Changes

4 files changed (+63 additions, -2 deletions)

View changed files

📝 docs/source/design/transfer-engine/index.md (+1 -0)
📝 docs/source/zh_archive/transfer-engine.md (+1 -0)
📝 mooncake-transfer-engine/include/common.h (+37 -1)
📝 mooncake-transfer-engine/tests/common_test.cpp (+24 -1)

📄 Description

Summary

Add MC_HANDSHAKE_MAX_LENGTH environment variable to configure the maximum handshake message length in P2P mode.

Problem

When using P2P handshake mode with a single RDMA instance that registers many memory buffers (>10,000), the serialized segment metadata JSON can exceed the hardcoded 1MB limit, causing handshake failures with error:

readString: too large length from socket: <length>

Each registered buffer adds ~96 bytes to the JSON payload:

Buffers	Size	Status
1,000	~94KB	✅ OK
5,000	~469KB	✅ OK
10,000	~938KB	⚠️ Near limit
15,000	~1.37MB	❌ Exceeds limit

Solution

Add getHandshakeMaxLength() function that reads MC_HANDSHAKE_MAX_LENGTH
Add resetHandshakeMaxLength() for testing purposes
Value is in bytes, valid range: 1MB to 128MB
Default remains 1MB (1048576 bytes) for backward compatibility
Logs custom value when set, warns on invalid values

Usage

# Set to 4MB to support ~40,000 buffers
export MC_HANDSHAKE_MAX_LENGTH=4194304

Type of Change

Bug fix
New feature
Breaking change
Documentation update

How Has This Been Tested?

Added unit tests in common_test.cpp:

ReturnsDefaultWhenEnvNotSet - verifies default 1MB value
ReturnsCachedValue - verifies caching behavior
ReadsCustomValueFromEnv - verifies custom value from environment
RejectsValueTooSmall - verifies rejection of values < 1MB
RejectsValueTooLarge - verifies rejection of values > 128MB
AcceptsMinimumValidValue - verifies 1MB boundary
AcceptsMaximumValidValue - verifies 128MB boundary
RejectsInvalidString - verifies handling of non-numeric input

Checklist

I have performed a self-review of my own code.
I have updated the documentation.
I have added tests to prove my changes are effective.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/Mooncake/pull/1392 **Author:** [@herrluk](https://github.com/herrluk) **Created:** 1/16/2026 **Status:** ✅ Merged **Merged:** 1/22/2026 **Merged by:** [@stmatengss](https://github.com/stmatengss) **Base:** `main` ← **Head:** `feature/configurable-handshake-max-length` --- ### 📝 Commits (1) - [`90d797c`](https://github.com/kvcache-ai/Mooncake/commit/90d797c7786c3f50ad2af7f57bf06e7d88abe4a7) [TE] Add configurable handshake max length via MC_HANDSHAKE_MAX_LENGTH ### 📊 Changes **4 files changed** (+63 additions, -2 deletions) <details> <summary>View changed files</summary> 📝 `docs/source/design/transfer-engine/index.md` (+1 -0) 📝 `docs/source/zh_archive/transfer-engine.md` (+1 -0) 📝 `mooncake-transfer-engine/include/common.h` (+37 -1) 📝 `mooncake-transfer-engine/tests/common_test.cpp` (+24 -1) </details> ### 📄 Description ## Summary Add `MC_HANDSHAKE_MAX_LENGTH` environment variable to configure the maximum handshake message length in P2P mode. ## Problem When using P2P handshake mode with a single RDMA instance that registers many memory buffers (>10,000), the serialized segment metadata JSON can exceed the hardcoded 1MB limit, causing handshake failures with error: ``` readString: too large length from socket: <length> ``` Each registered buffer adds ~96 bytes to the JSON payload: | Buffers | Size | Status | |---------|------|--------| | 1,000 | ~94KB | ✅ OK | | 5,000 | ~469KB | ✅ OK | | 10,000 | ~938KB | ⚠️ Near limit | | 15,000 | ~1.37MB | ❌ Exceeds limit | ## Solution - Add `getHandshakeMaxLength()` function that reads `MC_HANDSHAKE_MAX_LENGTH` - Add `resetHandshakeMaxLength()` for testing purposes - Value is in bytes, valid range: 1MB to 128MB - Default remains 1MB (1048576 bytes) for backward compatibility - Logs custom value when set, warns on invalid values ## Usage ```bash # Set to 4MB to support ~40,000 buffers export MC_HANDSHAKE_MAX_LENGTH=4194304 ``` ## Type of Change - [x] Bug fix - [ ] New feature - [ ] Breaking change - [x] Documentation update ## How Has This Been Tested? Added unit tests in `common_test.cpp`: - `ReturnsDefaultWhenEnvNotSet` - verifies default 1MB value - `ReturnsCachedValue` - verifies caching behavior - `ReadsCustomValueFromEnv` - verifies custom value from environment - `RejectsValueTooSmall` - verifies rejection of values < 1MB - `RejectsValueTooLarge` - verifies rejection of values > 128MB - `AcceptsMinimumValidValue` - verifies 1MB boundary - `AcceptsMaximumValidValue` - verifies 128MB boundary - `RejectsInvalidString` - verifies handling of non-numeric input ## Checklist - [x] I have performed a self-review of my own code. - [x] I have updated the documentation. - [x] I have added tests to prove my changes are effective. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 21:33:44 +00:00