Skip to content

[TENT] Integrate TENT 4 receiver credit on current upstream main - #54

Closed
Connor-Matthew wants to merge 14 commits into
mainfrom
codex/tent4-integration
Closed

Connor-Matthew wants to merge 14 commits into
mainfrom
codex/tent4-integration

Conversation

@Connor-Matthew

@Connor-Matthew Connor-Matthew commented Oct 19, 2026 •

Copy link
Copy Markdown

Superseded by #55 after the source branch was renamed to ub/tent4-integration. This PR was closed without merging.

Description

Migrate only original TENT 4 commit d78e20dd3f9568c8223fbdbb3e98e00f6ed34c67 onto official kvcache-ai/Mooncake main at 1a6d00d0f4dc7f54c573c5fcd4ff5f80bd1f2813, after TENT 3 landed upstream in kvcache-ai#4605.

This adds receiver-credit authority/exchange, runtime dispatch gating, transport session fences, staging propagation, and the native UB validation guide. Conflict resolution preserves current-main cancellation, safe TCP retry, payload limits, registered-memory permissions, copy-error propagation, runtime policy snapshots and submit-stage failover. Required-credit scatter submissions are rejected explicitly because scatter bypasses the credit-owning runtime queue; a regression test covers the rejection before transport handoff. A separate migration compatibility fix validates the receiver session/epoch against the pinned HP TCP metadata before initial or retry handoff, with missing/stale/version/flags rejection and matching-session success coverage. HP TCP was introduced upstream after the original TENT 4 snapshot.

Related design discussions: kvcache-ai#2849 (receiver-advertised credits, closed historical RFC) and kvcache-ai#3093 (native UB/URMA). This is TENT 4 follow-up work, distinct from the existing TENT 3 integration PR #53 and native UB/bonding PR #40. No duplicate TENT 4 PR was open when checked.

Base note: this fork's main is 12 official commits behind the selected official baseline. Those commits are existing upstream history; the new commits on top of official main are the migrated TENT 4 change and the HP TCP compatibility fix. No fork-main synchronization or merge is performed by this PR.

Validation PR: do not merge. Keep draft until CI, human review, and the owner's two-node UB traffic/data-integrity validation finish.

Suggested Merge Priority

  • P0 — Urgent
  • P1 — High
  • P2 — Normal
  • P3 — Low

Module

  • Transfer Engine (mooncake-transfer-engine)
  • Docs

Type of Change

  • New feature
  • Documentation update

How Has This Been Tested?

Test commands:

# macOS standalone builds use clang++ -std=c++20, Homebrew gtest/glog,
# tent/include, and the production status.cpp + relevant runtime source.
/tmp/mooncake-tent4-migration/receiver_credit_test --gtest_brief=1
/tmp/mooncake-tent4-migration/admission_queue_test --gtest_brief=1
/tmp/mooncake-tent4-migration/request_merge_test --gtest_brief=1
# Request merge test links the production merge function extracted unchanged
# from transfer_engine_impl.cpp, avoiding Linux-only engine dependencies.
make -C docs html SPHINXBUILD=/tmp/mooncake-tent4-migration/venv/bin/sphinx-build
pre-commit run --files $(git diff --name-only --diff-filter=ACMR 1a6d00d0f...HEAD)

Test results: 26 receiver-credit + 50 admission-queue + 11 request-merge tests pass (87 total). Before migration, the official baseline passed its 14 receiver-credit + 43 admission-queue tests. Documentation HTML builds successfully and the changed pages/navigation were inspected. All applicable pre-commit hooks pass, including clang-format 20.1.8 on changed lines and codespell.

  • Targeted portable unit tests pass
  • Full Linux/TENT CI passes (pending this PR)
  • New scatter and HP TCP session-fence regressions execute in Linux CI (not runnable with the full Linux engine on this macOS host)
  • Native UB two-node integration and traffic/data-integrity tests pass (owner will run on server)

Checklist

  • Agent self-review performed
  • Code formatted using ./scripts/code_format.sh via the pre-commit hook
  • Pre-commit run on changed files; applicable hooks pass
  • Documentation updated
  • Original feature tests migrated; scatter and HP TCP compatibility regressions added
  • Existing RFC discussions linked above for this >500 LOC change
  • Human submitter has reviewed every changed line and can defend the change end-to-end

AI Assistance Disclosure

  • No AI tools were used
  • AI tools were used

Codex migrated the original commit, resolved conflicts against current main, added the scatter compatibility guard/regression, and ran the available local checks. Independent Codex agents reviewed migration risks. The human submitter's full review and hardware validation remain pending; this PR must stay unmerged.

yokinoshitayoki and others added 13 commits October 16, 2026 16:17
…4314)

* [Store] Add LastHitOnly lease selection to BatchProbeKey

Select and lease only the last complete request-scoped candidate, returning a selected-only mask. Preserve lease-free default probes and existing existence APIs. Thread the policy through both RPC boundaries and Python, with lease, tenant, shared-group and concurrency coverage.

Batch-probe RPC signatures change; participating components must upgrade together. Implements the Store portion of RFC kvcache-ai#4255.

* [Store] Use string_view for probe validation errors
…e-ai#4729)

kvcache-ai#4314 added the GrantLeasePolicy parameter to MasterService::BatchProbeKey
but missed this call site, which breaks the tent build. Pass the default
{} policy: ProbeLeaseMode::None preserves the lease-free existence probe
the scenario expects.
…e RPC (kvcache-ai#4704)

setupConnectionsByActive() held the endpoint RWSpinlock across the
transfer-metadata handshake RPC. The handshake is reciprocal: the peer's
passive handler must take the same lock on its own endpoint, so a
bilateral active setup (both sides dialing at once) deadlocked.

Serialize active setup with a dedicated mutex that passive handlers never
take, and hold the state lock only while reading local state and while
publishing the reply, so three properties hold:

- Active callers are serialized into one handshake RPC; the state lock is
  released while the RPC is in flight.
- A reply that crosses a disconnect, a nic-path change or endpoint teardown
  is stale: a generation counter, bumped on every disconnect/path change,
  rejects it instead of publishing a connection against dead state.
- A passive handshake that connected the endpoint while the RPC was in
  flight wins: the active caller returns success and discards its own
  reply, even if the RPC failed or the generation moved.

Also qualify efa_context.h includes as
"transport/efa_transport/efa_context.h" so the endpoint header can be
included from tests that shadow the context boundary
(tests/efa_endpoint_handshake_test.cpp compiles the real endpoint source
against a scripted RPC/address-vector fake and runs without an EFA
device).
… page (kvcache-ai#4693)

---------

Co-authored-by: Ke Yang <yangke@approaching.ai>
Co-authored-by: Cursor <cursoragent@cursor.com>
…yout (kvcache-ai#4689)

* Move feature page to store-rs

* Move store-rs build guide to the build file

* Highlight the title of store-rs toubleshooting

* Address review comments

---------

Co-authored-by: Ke Yang <yangke@approaching.ai>
Co-authored-by: Daegyu Han <daegyu13.han@gmail.com>
Co-authored-by: 2xdevv <2xdevv@gmail.com>
)

The leadership lease TTL was hard-coded to DEFAULT_MASTER_VIEW_LEASE_TTL_SEC
(5 s) in the etcd coordinator. An etcd apply stall of about that length
makes the leader miss a keepalive and step down, so clusters with observed
slow applies cannot ride such stalls out.

Add --ha_leader_lease_ttl_sec (default 5, allowed range 2..60, also read
from the JSON config as ha_leader_lease_ttl_sec) and thread it through
MasterConfig, MasterServiceSupervisorConfig and HABackendSpec to the etcd
coordinator's GrantLease call. The effective value is logged at startup.
The floor is 2 s because etcd raises smaller lease TTLs to 2 s with its
default settings. The default keeps the existing behavior; the Redis and
k8s backends do not use the flag. Document the flag in the Mooncake Store
deployment guide.

A longer TTL trades failover latency for stall tolerance: a new leader
still waits one full TTL in warmup before serving (fencing against the
old leader), and after a leader crash the standby waits for the old lease
to expire.
…er (kvcache-ai#4688)

Signed-off-by: Xucheng Zhou <aden1350@outlook.com>
@Connor-Matthew
Connor-Matthew deleted the codex/tent4-integration branch October 19, 2026 08:33
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.