fix(config): ship the canonical [historical]/[streaming] section names (#811)

The TOML deserializer binds sections named [historical], [streaming],
[grpc] and [auth], but the shipped config.default.toml, the from_file
rustdoc example, and the configuration article all used the internal
[mdds]/[fpss] names (and a non-existent [retry] section). serde maps
those to no field, so a user copying the sample had every host, port,
tls, flush, and ring override silently discarded with no error, while
[auth] still matched and loaded creds, masking the failure.

Rename the sample, the rustdoc example, and the article to the
canonical names, and document the streaming wait-strategy knobs the
sample was missing. Four config_file tests asserted overrides that the
[mdds]/[fpss] names never applied; they passed only because the suite
does not run under the config-file feature in the default matrix.
Rename their sections so they exercise the real binding, and add a
guard test pinning the canonical section names in the shipped sample
(the existing parse test only checked values equal to the production
defaults, so it could not catch this).

Co-authored-by: Claude <noreply@anthropic.com>

Author: userFRM

crates/thetadatadx/config.default.toml

@@ -6,7 +6,7 @@
 # ── Historical Data (gRPC) ───────────────────────────────────────────────────
 # Historical data is served via gRPC over TLS (not raw TCP).
 
-[mdds]
+[historical]
 host = "mdds-01.thetadata.us"
 port = 443
 tls = true
@@ -21,7 +21,7 @@ max_message_size = 4194304
 # ── Real-Time Streaming (TLS/TCP) ────────────────────────────────────────────
 # The client tries each host in order until one connects.
 
-[fpss]
+[streaming]
 # Production servers (New Jersey datacenter)
 hosts = [
     "nj-a.thetadata.us:20000",
@@ -51,6 +51,27 @@ reconnect_wait_rate_limited = 130000
 # Increase if stream events are being dropped (see `dropped_event_count`).
 ring_size = 131072
 
+# Outgoing write flushing: "batched" (default, coalesces writes) or
+# "immediate" (flush every frame, lowest send latency, more syscalls).
+flush_mode = "batched"
+
+# Consumer wait strategy when the ring is empty. Presets:
+#   "low_latency" (default) — spin, brief yield, then a short park
+#   "balanced"              — shorter spin, low idle CPU
+#   "efficient"             — minimal spin, longest park, lowest idle CPU
+#   "busy_spin"             — pure spin, no park (pins a core while idle)
+wait_strategy = "low_latency"
+
+# Fine-tune the active strategy. These override the preset's spin/yield/
+# park counts; the values below are the "low_latency" defaults.
+wait_spin_iters = 100
+wait_yield_iters = 10
+wait_park_us = 50
+
+# CPU core to pin the streaming consumer thread to. -1 (default) leaves
+# it unpinned; set a core index to reduce scheduler jitter on a busy box.
+consumer_cpu = -1
+
 # ── Credentials ──────────────────────────────────────────────────────────────
 # Path to credentials file (line 1 = email, line 2 = password).
 # Can also be overridden programmatically via Credentials::new().
@@ -61,15 +82,15 @@ creds_file = "creds.txt"
 # ── Alternate Server Regions ─────────────────────────────────────────────────
 # Uncomment to use staging or dev servers. These are NOT stable.
 
-# [fpss]
+# [streaming]
 # hosts = [
 #     "nj-a.thetadata.us:20100",
 #     "test-server.thetadata.us:20100",
 #     "test-server.thetadata.us:20101",
 # ]
 
 # Dev servers (frequent reboots, replays historical data):
-# [fpss]
+# [streaming]
 # hosts = [
 #     "nj-a.thetadata.us:20200",
 #     "test-server.thetadata.us:20200",

crates/thetadatadx/src/config/mod.rs

@@ -822,15 +822,15 @@ mod config_file {
         /// # Example file
         ///
         /// ```toml
-        /// [mdds]
+        /// [historical]
         /// host = "mdds-01.thetadata.us"
         /// port = 443
         /// tls = true
         ///
-        /// [fpss]
+        /// [streaming]
         /// hosts = ["nj-a.thetadata.us:20000", "nj-b.thetadata.us:20000"]
         /// reconnect_wait = 2000
-        /// queue_depth = 1_000_000
+        /// ring_size = 131072
         /// flush_mode = "batched"  # or "immediate"
         ///
         /// [grpc]
@@ -874,8 +874,9 @@ mod config_file {
             let wait_strategy =
                 StreamingWaitStrategy::parse(&cf.streaming.wait_strategy).unwrap_or_default();
 
-            // If [grpc].max_message_size_mb is set, it overrides [mdds].max_message_size.
-            // The grpc section value is in MB; the mdds section value is in bytes.
+            // If [grpc].max_message_size_mb is set, it overrides
+            // [historical].max_message_size. The grpc section value is in
+            // MB; the historical section value is in bytes.
             let max_message_size = if cf.grpc.max_message_size_mb
                 != DirectConfig::production().historical.max_message_size / (1024 * 1024)
             {
@@ -1025,11 +1026,11 @@ mod tests {
         #[test]
         fn partial_toml_overrides_only_specified() {
             let toml = r#"
-                [mdds]
+                [historical]
                 host = "custom.example.com"
                 port = 8443
 
-                [fpss]
+                [streaming]
                 ring_size = 65536
             "#;
             let config = DirectConfig::from_toml_str(toml).unwrap();
@@ -1043,7 +1044,7 @@ mod tests {
         #[test]
         fn streaming_hosts_as_array() {
             let toml = r#"
-                [fpss]
+                [streaming]
                 hosts = ["host-a.example.com:20000", "host-b.example.com:20001"]
             "#;
             let config = DirectConfig::from_toml_str(toml).unwrap();
@@ -1061,7 +1062,7 @@ mod tests {
         #[test]
         fn streaming_hosts_as_csv_string() {
             let toml = r#"
-                [fpss]
+                [streaming]
                 hosts = "host-a.example.com:20000,host-b.example.com:20001"
             "#;
             let config = DirectConfig::from_toml_str(toml).unwrap();
@@ -1072,7 +1073,7 @@ mod tests {
         #[test]
         fn flush_mode_immediate() {
             let toml = r#"
-                [fpss]
+                [streaming]
                 flush_mode = "immediate"
             "#;
             let config = DirectConfig::from_toml_str(toml).unwrap();
@@ -1082,7 +1083,7 @@ mod tests {
         #[test]
         fn flush_mode_batched_by_default() {
             let toml = r#"
-                [fpss]
+                [streaming]
                 flush_mode = "batched"
             "#;
             let config = DirectConfig::from_toml_str(toml).unwrap();
@@ -1163,7 +1164,7 @@ mod tests {
         #[test]
         fn unknown_keys_are_ignored() {
             let toml = r#"
-                [mdds]
+                [historical]
                 host = "mdds-01.thetadata.us"
                 port = 443
                 unknown_key = "should be ignored"
@@ -1186,6 +1187,29 @@ mod tests {
             assert_eq!(config.streaming.hosts.len(), 4);
         }
 
+        #[test]
+        fn config_default_toml_uses_canonical_section_names() {
+            // The deserializer binds `[historical]` / `[streaming]`; the
+            // internal vendor names `[mdds]` / `[fpss]` deserialize to
+            // nothing, so a sample shipping them silently discards every
+            // override. Asserting host==443 above can't catch that (those
+            // equal the production defaults), so pin the section names in
+            // the shipped sample directly.
+            let default_toml = include_str!("../../config.default.toml");
+            assert!(
+                default_toml.contains("[historical]"),
+                "config.default.toml must use the canonical [historical] section"
+            );
+            assert!(
+                default_toml.contains("[streaming]"),
+                "config.default.toml must use the canonical [streaming] section"
+            );
+            assert!(
+                !default_toml.contains("[mdds]") && !default_toml.contains("[fpss]"),
+                "config.default.toml must not ship the dead [mdds]/[fpss] section names"
+            );
+        }
+
         #[test]
         fn invalid_toml_returns_error() {
             let result = DirectConfig::from_toml_str("this is not valid toml [[[");

docs-site/docs/articles/configuration.md

@@ -46,10 +46,11 @@ Every field above is available on all four language surfaces under the naming co
 With the `config-file` feature, Rust loads the same fields from TOML — useful for operating the [server binary](/server/) or any deployment where configuration should live outside code:
 
 ```toml
-[retry]
-max_attempts = 5
+[historical]
+host = "mdds-01.thetadata.us"
+port = 443
 
-[fpss]
+[streaming]
 flush_mode = "immediate"
 hosts = ["host-a.example.com:20000", "host-b.example.com:20000"]
 ```