kvcache-ai/Mooncake
View on GitHub[Feature Request]: Use Builder Pattern for Mooncake Store Client Construction
Open
#978 opened on Oct 29, 2025
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