kvcache-ai/Mooncake

[Feature Request]: Use Builder Pattern for Mooncake Store Client Construction

Open

#978 opened on Oct 29, 2025

View on GitHub
 (4 comments) (0 reactions) (1 assignee)C++ (5,470 stars) (803 forks)auto 404
feature requestgood first issue

Description

Describe your feature request

RFC: Builder Pattern for Mooncake Store Client

Problem

Right now, MooncakeDistributedStore.setup() takes way too many params (like 8+ args), and as we add features or deprecate old configs, it's becoming a maintenance nightmare. Users also find it confusing to remember the order and what each arg does.

# Current API - not great
store.setup(
    local_hostname="host1",
    metadata_server="127.0.0.1:8080",
    global_segment_size=1024*1024*16,
    local_buffer_size=1024*1024*16,
    protocol="tcp",
    rdma_devices="",
    master_server_addr="127.0.0.1:50051",
    engine=None
)

Proposal

Introduce a Builder pattern for both C++ and Python to make config cleaner, more maintainable, and easier to extend.

Python Example

store = (MooncakeDistributedStore.builder()
    .with_local_hostname("host1")
    .with_metadata_server("127.0.0.1:8080")
    .with_global_segment_size(16 * 1024 * 1024)
    .with_local_buffer_size(16 * 1024 * 1024)
    .with_protocol("tcp")
    .with_rdma_devices("")
    .with_master_server_addr("127.0.0.1:50051")
    .with_engine(None)  # optional
    .build())

Or even simpler with defaults:

store = (MooncakeDistributedStore.builder()
    .with_local_hostname("host1")
    .with_metadata_server("127.0.0.1:8080")
    .build())

C++ Example

auto store = MooncakeStoreBuilder()
    .WithLocalHostname("host1")
    .WithMetadataServer("127.0.0.1:8080")
    .WithGlobalSegmentSize(16 * 1024 * 1024)
    .WithProtocol("tcp")
    .Build();

Benefits

  • Readable: Method names are self-documenting
  • Flexible: Easy to add/remove options without breaking existing code
  • Optional params: Only set what you need; rest use defaults
  • Type-safe (in C++): Compiler catches mistakes early
  • Backward compat: Keep old setup() as deprecated wrapper initially

Thoughts? Happy to iterate on naming/API design!

Before submitting a new issue...

  • Make sure you already searched for relevant issues and read the documentation

Contributor guide