|
| 1 | +# TOML Configuration Support — Design Doc |
| 2 | + |
| 3 | +**Issue:** #247 — Add proper TOML configuration file support |
| 4 | +**Date:** 2026-05-27 |
| 5 | +**Status:** Approved |
| 6 | + |
| 7 | +## Problem |
| 8 | + |
| 9 | +Current config system uses a hand-rolled Redis-style parser (`parse_redis_config`) that: |
| 10 | +- Only handles `key = value` and `key value` format |
| 11 | +- Cannot parse TOML sections (`[raft]`), arrays, or nested structures |
| 12 | +- All values are parsed as strings, then manually converted |
| 13 | +- The existing `config.example.toml` uses TOML format that the parser cannot read |
| 14 | + |
| 15 | +## Solution |
| 16 | + |
| 17 | +Replace the manual parser with the `toml` crate + serde `Deserialize`: |
| 18 | + |
| 19 | +### TOML Structure |
| 20 | + |
| 21 | +```toml |
| 22 | +# Basic |
| 23 | +binding = "127.0.0.1" |
| 24 | +port = 7379 |
| 25 | +timeout = 300 |
| 26 | +memory = "1GB" |
| 27 | +log-dir = "./logs" |
| 28 | +db-dir = "./db" |
| 29 | +db-path = "" |
| 30 | +db-instance-num = 3 |
| 31 | +redis-compatible-mode = true |
| 32 | +# requirepass = "secret" |
| 33 | + |
| 34 | +# Compaction |
| 35 | +small-compaction-threshold = 10 |
| 36 | +small-compaction-duration-threshold = 180 |
| 37 | + |
| 38 | +# RocksDB |
| 39 | +rocksdb-max-subcompactions = 1 |
| 40 | +rocksdb-max-background-jobs = 2 |
| 41 | +rocksdb-max-write-buffer-number = 2 |
| 42 | +rocksdb-min-write-buffer-number-to-merge = 1 |
| 43 | +rocksdb-write-buffer-size = 67108864 |
| 44 | +rocksdb-level0-file-num-compaction-trigger = 4 |
| 45 | +rocksdb-num-levels = 7 |
| 46 | +rocksdb-enable-pipelined-write = false |
| 47 | +rocksdb-level0-slowdown-writes-trigger = 20 |
| 48 | +rocksdb-level0-stop-writes-trigger = 36 |
| 49 | +rocksdb-ttl-second = 0 |
| 50 | +rocksdb-periodic-second = 0 |
| 51 | +rocksdb-level-compaction-dynamic-level-bytes = false |
| 52 | +rocksdb-max-open-files = 10000 |
| 53 | +rocksdb-target-file-size-base = 67108864 |
| 54 | +rocksdb-compression-type = "lz4" |
| 55 | + |
| 56 | +# Raft (optional section) |
| 57 | +[raft] |
| 58 | +node-id = 1 |
| 59 | +raft-addr = "127.0.0.1:9220" |
| 60 | +resp-addr = "127.0.0.1:7379" |
| 61 | +data-dir = "./raft-data" |
| 62 | +# heartbeat-interval-ms = 500 |
| 63 | +# election-timeout-min-ms = 1500 |
| 64 | +# election-timeout-max-ms = 3000 |
| 65 | +use-memory-log-store = false |
| 66 | +``` |
| 67 | + |
| 68 | +### Key Design Decisions |
| 69 | + |
| 70 | +1. **Flat top-level keys** — RocksDB settings stay flat (not nested under `[rocksdb]`) to minimize migration friction |
| 71 | +2. **`[raft]` section** — Uses TOML table syntax, maps to `Option<RaftClusterConfig>` |
| 72 | +3. **`memory` field** — Keep string format ("1GB") with custom serde deserializer (`deserialize_memory`) |
| 73 | +4. **Backward compat** — Drop Redis-style format entirely (it was never a real parser) |
| 74 | +5. **Error messages** — `toml` crate gives line/column numbers in errors |
| 75 | + |
| 76 | +### Files to Modify |
| 77 | + |
| 78 | +| File | Change | |
| 79 | +|------|--------| |
| 80 | +| `src/conf/Cargo.toml` | Add `toml = "0.8"` | |
| 81 | +| `src/conf/src/config.rs` | Add `Deserialize` derive + serde attrs, rewrite `Config::load()` | |
| 82 | +| `src/conf/src/de_func.rs` | Keep `deserialize_memory`/`deserialize_bool_from_yes_no`, remove `parse_redis_config`/`parse_config_line`/`redis_config_to_ini` | |
| 83 | +| `src/conf/src/lib.rs` | Update tests to use TOML format | |
0 commit comments