Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

search: index.max_result_window above 10,000 works; limits.max_result_window is the node default

Tom Villanicfe489ea89f5
diff --git a/engine/crates/xerj-api/src/es_compat.rs b/engine/crates/xerj-api/src/es_compat.rs
index 767a40351..6534864e0 100644
--- a/engine/crates/xerj-api/src/es_compat.rs
+++ b/engine/crates/xerj-api/src/es_compat.rs
@@ -22514,8 +22514,10 @@ pub async fn delete_index_template(
/// An index's `index.max_result_window`, in any of the three spellings a
/// settings document can carry it (nested `index.max_result_window`, a flat
-/// dotted key under `index`, or a top-level dotted key), defaulting to ES's
-/// 10,000. Shared by the `ids` clause check and the `rerank.window` check.
+/// dotted key under `index`, or a top-level dotted key), defaulting to the
+/// node's `limits.max_result_window` (10,000 by default, the ES default) like
+/// the engine's own check. Shared by the `ids` clause check and the
+/// `rerank.window` check.
fn index_max_result_window(state: &AppState, ix: &str) -> usize {
state
.engine
@@ -22537,7 +22539,7 @@ fn index_max_result_window(state: &AppState, ix: &str) -> usize {
.or_else(|| s.get("index.max_result_window").and_then(as_int))
})
.map(|v| v as usize)
- .unwrap_or(10_000)
+ .unwrap_or(state.engine.config().limits.max_result_window)
}
#[derive(Debug, Deserialize, Default)]
diff --git a/engine/crates/xerj-common/src/config.rs b/engine/crates/xerj-common/src/config.rs
index 0c58f6e9e..0a4572226 100644
--- a/engine/crates/xerj-common/src/config.rs
+++ b/engine/crates/xerj-common/src/config.rs
@@ -246,6 +246,12 @@ impl Config {
return Err(XerjError::config("vector.max_dimensions must be > 0"));
}
+ if !(1..=i32::MAX as usize).contains(&self.limits.max_result_window) {
+ return Err(XerjError::config(
+ "limits.max_result_window must be in 1..=2147483647",
+ ));
+ }
+
if !(1..=4096).contains(&self.embedding.onnx_scheduling_window) {
return Err(XerjError::config(
"embedding.onnx_scheduling_window must be in 1..=4096",
@@ -1522,10 +1528,11 @@ pub struct LimitsConfig {
pub max_body_bytes: usize,
/// Maximum value of `from + size` in a search request (default: `10_000`).
///
- /// Mirrors Elasticsearch's `index.max_result_window`. Deep pagination past
- /// this should use `search_after` / point-in-time cursors instead. The
- /// limit prevents `size=2_000_000_000` from allocating 2 billion `Hit`
- /// structs from a single HTTP POST.
+ /// The node-wide default for Elasticsearch's `index.max_result_window`:
+ /// an index whose settings carry `index.max_result_window` uses that, any
+ /// other index uses this. Deep pagination past it should use
+ /// `search_after` / point-in-time cursors instead. Must be in
+ /// `1..=2147483647` (the setting's ES range).
pub max_result_window: usize,
/// Maximum number of doc-references in a single `_mget` request body
/// (default: `10_000`). Mirrors `max_result_window`.
@@ -2613,6 +2620,14 @@ mod tests {
assert!(!cfg.tls.enabled);
}
+ #[test]
+ fn max_result_window_must_be_a_positive_es_int() {
+ assert!(Config::from_toml_str("[limits]\nmax_result_window = 0\n").is_err());
+ assert!(Config::from_toml_str("[limits]\nmax_result_window = 2147483648\n").is_err());
+ let cfg = Config::from_toml_str("[limits]\nmax_result_window = 50000\n").unwrap();
+ assert_eq!(cfg.limits.max_result_window, 50_000);
+ }
+
#[test]
fn s3_backend_without_a_bucket_is_rejected() {
// #965 wired `backend = "s3"` as a real index backend, so the old
diff --git a/engine/crates/xerj-engine/src/index.rs b/engine/crates/xerj-engine/src/index.rs
index a61f96e5b..e9f72251d 100644
--- a/engine/crates/xerj-engine/src/index.rs
+++ b/engine/crates/xerj-engine/src/index.rs
@@ -6496,6 +6496,57 @@ mod semantic_deadline_regression_tests {
);
}
+ /// `index.max_result_window` above 10,000 was stored and then overruled by
+ /// the parser's hardcoded 10,000 (measured on rc.89: `from: 20000` on an
+ /// index set to 50,000 answered "from + size must be <= 10000"), and the
+ /// node's `limits.max_result_window` was read by nothing. The index
+ /// setting now governs, the node setting is the fallback, and the check
+ /// still refuses a window past either.
+ #[tokio::test]
+ async fn result_window_comes_from_the_index_setting_then_the_node_limit() {
+ let window = |from: u64, size: u64| {
+ xerj_query::parse_request(&serde_json::json!({ "from": from, "size": size }))
+ .expect("the parser no longer caps the window at 10,000")
+ };
+ let dir = TempDir::new().unwrap();
+ let mut config = xerj_common::config::Config::default();
+ config.server.data_dir = dir.path().to_string_lossy().into_owned();
+ config.limits.max_result_window = 50;
+ let engine_instance = Engine::new(config).expect("engine");
+ engine_instance
+ .create_index("node-limit", Schema::empty())
+ .unwrap();
+ engine_instance
+ .create_index("index-limit", Schema::empty())
+ .unwrap();
+
+ // No index setting: the node limit (50) applies.
+ let node = engine_instance.get_index("node-limit").unwrap();
+ node.search(&window(40, 10))
+ .await
+ .expect("40 + 10 fits a window of 50");
+ let err = node
+ .search(&window(45, 10))
+ .await
+ .expect_err("45 + 10 exceeds the node's window of 50");
+ assert!(err.to_string().contains("max_result_window=50"), "{err}");
+
+ // An index setting wins over the node limit, in both directions, and
+ // above the old hardcoded 10,000.
+ let idx = engine_instance.get_index("index-limit").unwrap();
+ idx.put_settings(serde_json::json!({ "index": { "max_result_window": 50_000 } }))
+ .await
+ .unwrap();
+ idx.search(&window(20_000, 10))
+ .await
+ .expect("a 50,000 index window admits from 20,000");
+ let err = idx
+ .search(&window(49_995, 10))
+ .await
+ .expect_err("49,995 + 10 exceeds the index's window of 50,000");
+ assert!(err.to_string().contains("max_result_window=50000"), "{err}");
+ }
+
/// #312 bug 1: a single dynamic insert whose new top-level field is a nested
/// OBJECT must count the whole subtree against `max_fields_per_index`, not as
/// one field — otherwise one document overshoots the budget by the subtree's
@@ -8890,6 +8941,10 @@ pub struct Index {
/// directly, which previously bypassed the limit.
max_fields_per_index: u32,
+ /// Snapshot of `config.limits.max_result_window`: the `from + size`
+ /// ceiling for an index whose settings carry no `index.max_result_window`.
+ max_result_window: usize,
+
/// Embedding backend for `semantic` / `semantic_text` (v0.7-P2).
/// One of lexical (built-in, default), an external proxy, the built-in
/// Candle neural BERT embedder, or the experimental ONNX Runtime backend
@@ -9584,6 +9639,7 @@ impl Index {
compression_config: config.compression.clone(),
embedding_config: config.embedding.clone(),
max_fields_per_index: config.limits.max_fields_per_index,
+ max_result_window: config.limits.max_result_window,
embedder: Arc::new(RwLock::new(effective_embedder)),
dv_cache: Arc::new(per_index_map()),
sort_shadow_cache: Arc::new(per_index_map()),
@@ -10030,6 +10086,7 @@ impl Index {
compression_config: config.compression.clone(),
embedding_config: config.embedding.clone(),
max_fields_per_index: config.limits.max_fields_per_index,
+ max_result_window: config.limits.max_result_window,
embedder: Arc::new(RwLock::new(effective_embedder)),
dv_cache: Arc::new(per_index_map()),
sort_shadow_cache: Arc::new(per_index_map()),
@@ -19554,6 +19611,57 @@ impl Index {
// ── Search ────────────────────────────────────────────────────────────────
+ /// `from + size` against this index's result window: its
+ /// `index.max_result_window` setting, else the node's
+ /// `limits.max_result_window` (10,000 by default, the ES default).
+ ///
+ /// Called by [`Index::search`] ahead of the per-query memory guard, so an
+ /// oversized window is the 400 `illegal_argument_exception` ES returns
+ /// rather than a 429 from the guard, and again at the top of
+ /// `search_inner`, ahead of the kNN / semantic short-circuits that never
+ /// reach materialisation (hybrid legs re-enter there). The parser used to
+ /// refuse any from + size above a hardcoded 10,000, which also overrode a
+ /// larger per-index setting.
+ ///
+ /// The setting may be stored as a nested object `{index: {max_result_window}}`,
+ /// a literal-dotted key under `index`, or a top-level dotted key, depending
+ /// on the shape the caller provided. (Ids-count validation happens at the
+ /// HTTP layer where index_settings is accessible.)
+ async fn check_result_window(&self, from: usize, size: usize) -> Result<()> {
+ let max_result_window: usize = {
+ let settings = self.settings.read().await;
+ settings
+ .pointer("/index/max_result_window")
+ .and_then(|v| {
+ v.as_u64()
+ .or_else(|| v.as_str().and_then(|s| s.parse().ok()))
+ })
+ .or_else(|| {
+ settings
+ .get("index")
+ .and_then(|i| i.get("index.max_result_window"))
+ .and_then(|v| {
+ v.as_u64()
+ .or_else(|| v.as_str().and_then(|s| s.parse().ok()))
+ })
+ })
+ .or_else(|| {
+ settings.get("index.max_result_window").and_then(|v| {
+ v.as_u64()
+ .or_else(|| v.as_str().and_then(|s| s.parse().ok()))
+ })
+ })
+ .map(|v| v as usize)
+ .unwrap_or(self.max_result_window)
+ };
+ if from.saturating_add(size) > max_result_window {
+ return Err(EngineError::Common(
+ xerj_common::XerjError::result_window_too_large(from, size, max_result_window),
+ ));
+ }
+ Ok(())
+ }
+
/// Execute a search request against this index.
pub async fn search(&self, request: &SearchRequest) -> Result<SearchResult> {
use crate::collection_publication::ReadAdmission;
@@ -19882,6 +19990,8 @@ impl Index {
// window (~10 MiB) is nowhere near the cap, so normal search is
// unaffected; the guard only bites pathological windows or a
// deliberately low operator budget.
+ self.check_result_window(request.from, request.size).await?;
+
if let Some(g) = crate::governor::global() {
if g.query_memory_enabled() {
// Conservative per-hit estimate: stored source + collector
@@ -20181,6 +20291,8 @@ impl Index {
let size = request.size;
let from = request.from;
+ self.check_result_window(from, size).await?;
+
// Resolve field aliases in the query: rewrite any alias field names to their targets.
//
// The unsearchable-field check rides on the same schema guard, and runs
@@ -20553,45 +20665,6 @@ impl Index {
};
let query = pinned_query.as_ref().unwrap_or(query);
- // ── Max result window enforcement ──────────────────────────────────────
- // Default max_result_window is 10,000 (matches ES default).
- // Allow override via index setting `index.max_result_window`.
- // The key may be stored either as nested object `{index: {max_result_window}}`
- // or as a literal-dotted key `{index: {"index.max_result_window"}}` depending
- // on the shape the caller provided at index creation. (Ids-count validation
- // happens at the HTTP layer where index_settings is accessible.)
- let max_result_window: usize = {
- let settings = self.settings.read().await;
- settings
- .pointer("/index/max_result_window")
- .and_then(|v| {
- v.as_u64()
- .or_else(|| v.as_str().and_then(|s| s.parse().ok()))
- })
- .or_else(|| {
- settings
- .get("index")
- .and_then(|i| i.get("index.max_result_window"))
- .and_then(|v| {
- v.as_u64()
- .or_else(|| v.as_str().and_then(|s| s.parse().ok()))
- })
- })
- .or_else(|| {
- settings.get("index.max_result_window").and_then(|v| {
- v.as_u64()
- .or_else(|| v.as_str().and_then(|s| s.parse().ok()))
- })
- })
- .map(|v| v as usize)
- .unwrap_or(10_000)
- };
- if from + size > max_result_window {
- return Err(EngineError::Common(
- xerj_common::XerjError::result_window_too_large(from, size, max_result_window),
- ));
- }
-
// Fetch limit is the per-sub-source materialisation cap. We materialise
// at most (from + size + 100) hits with their sources, and count the
// rest as `total` without buffering them. This keeps query memory
diff --git a/engine/crates/xerj-query/src/parser.rs b/engine/crates/xerj-query/src/parser.rs
index e67d78040..d7d9c736a 100644
--- a/engine/crates/xerj-query/src/parser.rs
+++ b/engine/crates/xerj-query/src/parser.rs
@@ -39,9 +39,14 @@ use crate::sort::{SortField, SortMissing, SortMode, SortOrder};
// workers each get their own counter.
const MAX_QUERY_DEPTH: usize = 64;
-/// Cap on `from + size`. Mirrors ES's `index.max_result_window` default.
-/// Deep pagination beyond this should use `search_after`/PIT instead.
-pub const MAX_RESULT_WINDOW: usize = 10_000;
+/// Parse-time ceiling on `from + size`: the largest value ES's
+/// `index.max_result_window` can take (a Java `int`). The real limit is the
+/// index's `index.max_result_window`, else the node's
+/// `limits.max_result_window` (default 10,000), and the engine enforces it
+/// before anything is materialised. This bound only keeps the arithmetic
+/// sane; it used to be a hardcoded 10,000, which silently overrode a larger
+/// per-index setting. Deep pagination should use `search_after`/PIT.
+pub const MAX_RESULT_WINDOW: usize = i32::MAX as usize;
// ── Boolean clause limit ──────────────────────────────────────────────────────
//
@@ -262,10 +267,9 @@ pub fn parse_request(body: &Value) -> Result<SearchRequest> {
None => 10,
};
- // ES default `index.max_result_window` is 10_000. Without this cap a
- // single request with `size=2_000_000_000` allocates a Vec<Hit> for two
- // billion entries before pagination. Trust the user the same way ES
- // does — i.e., not at all.
+ // The per-index / per-node window is checked by the engine (it needs the
+ // index settings, which the parser does not have), ahead of every
+ // allocation sized by `from + size`; see `MAX_RESULT_WINDOW`.
if from.saturating_add(size) > MAX_RESULT_WINDOW {
return invalid(format!(
"from + size must be <= {MAX_RESULT_WINDOW} (got {})",
@@ -4674,6 +4678,17 @@ mod tests {
parse_query(&j).expect("parse failed")
}
+ /// The window is the engine's to enforce (per-index setting, then the node
+ /// limit); the parser only bounds the arithmetic at the setting's largest
+ /// value. A hardcoded 10,000 here overruled `index.max_result_window`.
+ #[test]
+ fn parser_leaves_the_result_window_to_the_index() {
+ let r = parse_request(&json!({ "from": 20_000, "size": 10 }))
+ .expect("from 20,000 is legal for an index whose window allows it");
+ assert_eq!((r.from, r.size), (20_000, 10));
+ assert!(parse_request(&json!({ "from": i32::MAX as u64, "size": 1 })).is_err());
+ }
+
// ── #846: minimum_should_match negative / combination specs ───────────────
#[test]
diff --git a/landing/docs/config.html b/landing/docs/config.html
index af5b7c2bf..a02fe7c20 100644
--- a/landing/docs/config.html
+++ b/landing/docs/config.html
@@ -224,7 +224,7 @@
<p>Paths for the config are, in precedence order: <code class="inline">--config /path/to/xerj.toml</code> on the command line, then <code class="inline">/etc/xerj/xerj.toml</code>, then <code class="inline">./xerj.toml</code> in the working directory. If none exist, the full default is used.</p>
<h2>Full key table</h2>
- <div class="cfg"><div class="head">KEY</div><div class="head">TYPE</div><div class="head">DEFAULT</div><div class="head">DESCRIPTION</div><div class="group" id="server">[server]</div><div class="cell k">rest_port</div><div class="cell t">u16</div><div class="cell d">8080</div><div class="cell dsc">Native REST API listener port. All native endpoints (/v1/*) live here.</div><div class="cell k">grpc_port</div><div class="cell t">u16</div><div class="cell d">8081</div><div class="cell dsc">Reserved for a future gRPC API. Not wired in v0.1 — leave at default.</div><div class="cell k">es_compat_port</div><div class="cell t">u16</div><div class="cell d">9200</div><div class="cell dsc">Elasticsearch-compatible wire port. Point Kibana, Logstash, or the ES client here. Set to 0 to disable.</div><div class="cell k">bind_address</div><div class="cell t">string</div><div class="cell d">"127.0.0.1"</div><div class="cell dsc">Interface to bind every listener to. Loopback by default, so an unconfigured node is unreachable from the network. Set "0.0.0.0" or a private address to expose it (also --bind / XERJ_BIND_ADDRESS). Must be an IPv4 or IPv6 literal — host names are not resolved, and a node given one refuses to start.</div><div class="cell k">allow_insecure_network_bind</div><div class="cell t">bool</div><div class="cell d">false</div><div class="cell dsc">Permit a non-loopback bind_address while tls.enabled = false. Startup refuses that combination otherwise: every listener would serve plain HTTP, so the API key in every Authorization header crosses the network in cleartext. Set true only when a proxy, sidecar, mesh or container boundary terminates TLS in front of the node. Env: XERJ_ALLOW_INSECURE_NETWORK_BIND.</div><div class="cell k">data_dir</div><div class="cell t">path</div><div class="cell d">"./data"</div><div class="cell dsc">Root for indices, WAL files, and segments. Needs fast I/O and enough free space.</div><div class="group" id="auth">[auth]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">true</div><div class="cell dsc">Require an API key on every request. Set to false only on a trusted network.</div><div class="cell k">admin_api_key</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Static admin key. Left empty, a 256-bit key is generated on first run and written to <data_dir>/admin.key.</div><div class="group" id="tls">[tls]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">false</div><div class="cell dsc">Terminate TLS at the server. Requires cert_path + key_path. If you terminate at a proxy, leave false.</div><div class="cell k">cert_path</div><div class="cell t">path</div><div class="cell d">""</div><div class="cell dsc">PEM X.509 certificate. Use a CA-signed cert in production.</div><div class="cell k">key_path</div><div class="cell t">path</div><div class="cell d">""</div><div class="cell dsc">PEM private key. Permissions should be 0600.</div><div class="group" id="storage">[storage]</div><div class="cell k">wal_sync</div><div class="cell t">enum</div><div class="cell d">"batched"</div><div class="cell dsc">"sync" · "batched" · "async". Durability vs throughput. Batched is the recommended default.</div><div class="cell k">wal_batch_ms</div><div class="cell t">u32</div><div class="cell d">100</div><div class="cell dsc">Fsync cadence when wal_sync="batched" (ms). Range 1–10000. Lower = smaller loss window.</div><div class="cell k">wal_max_size_mb</div><div class="cell t">u32</div><div class="cell d">1024</div><div class="cell dsc">WAL rollover threshold (MiB). Larger means fewer rollovers, longer crash recovery.</div><div class="cell k">flush_size_mb</div><div class="cell t">u32</div><div class="cell d">512</div><div class="cell dsc">Memtable buffer size that triggers a segment flush (MiB).</div><div class="cell k">flush_interval_secs</div><div class="cell t">u32</div><div class="cell d">30</div><div class="cell dsc">Maximum wall-clock interval between flushes even if the buffer is not full.</div><div class="group" id="merge">[merge]</div><div class="cell k">strategy</div><div class="cell t">enum</div><div class="cell d">"size_tiered"</div><div class="cell dsc">Only "size_tiered" is implemented; "log_structured" is refused at startup rather than silently running the other policy.</div><div class="cell k">min_segments</div><div class="cell t">u32</div><div class="cell d">10</div><div class="cell dsc">Accepted and validated (must be ≥ 2) but <strong>not wired</strong>: the merge trigger is per-tier and comes from min_merge_count. Setting it away from the default logs a warning at startup.</div><div class="cell k">max_segment_mb</div><div class="cell t">u32</div><div class="cell d">8192</div><div class="cell dsc">Upper bound on a mergeable segment (MiB). Segments at or above this size are never merged again.</div><div class="cell k">io_rate_mb_per_sec</div><div class="cell t">u32</div><div class="cell d">100</div><div class="cell dsc">Accepted but <strong>not wired</strong>: merge I/O is not throttled in this build — the rate limiter that honours it sits in an unused storage-crate merge executor. Setting it away from the default logs a warning at startup.</div><div class="cell k">max_concurrent</div><div class="cell t">u8</div><div class="cell d">1</div><div class="cell dsc">Accepted but <strong>not wired</strong>: merge parallelism comes from the XERJ_MERGE_PARALLELISM environment variable, which also defaults to 1. Setting it away from the default logs a warning at startup.</div><div class="group" id="compression">[compression]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">true</div><div class="cell dsc">Accepted but <strong>not wired</strong>: every durable artifact is a compressed envelope with no uncompressed write path, so false changes nothing on disk. Setting it away from the default logs a warning at startup.</div><div class="cell k">level</div><div class="cell t">enum</div><div class="cell d">"balanced"</div><div class="cell dsc">"fast" (Zstd L1), "balanced" (Zstd L3, default), "best" (Zstd L6, cold storage). Applied when segments are re-encoded <strong>at merge</strong>; flush always writes L3, because raising the flush level collapses sustained ingest. Force-merge to apply a change to data already on disk.</div><div class="cell k">block_size_docs</div><div class="cell t">u32</div><div class="cell d">128</div><div class="cell dsc">Accepted but <strong>not wired</strong>: the stored codec is columnar over the whole segment section, not blocked by document count. Range 16–4096 is enforced at startup, and a non-default value logs a warning.</div><div class="group" id="fts">[fts]</div><div class="cell k">default_analyzer</div><div class="cell t">enum</div><div class="cell d">"standard"</div><div class="cell dsc">"standard" · "whitespace" · "simple" · "english". Override per-field in the mapping.</div><div class="group" id="vector">[vector]</div><div class="cell k">default_metric</div><div class="cell t">enum</div><div class="cell d">"cosine"</div><div class="cell dsc">"cosine" · "dot_product" · "euclidean". Cosine for text embeddings is the usual choice.</div><div class="cell k">hnsw_m</div><div class="cell t">u32</div><div class="cell d">16</div><div class="cell dsc">Accepted and validated; the built-in HNSW graph currently builds with fixed M=16 — this key is not yet wired to the build.</div><div class="cell k">hnsw_ef_construction</div><div class="cell t">u32</div><div class="cell d">200</div><div class="cell dsc">Accepted; must be ≥ hnsw_m. The graph currently builds with fixed ef_construction=200 — this key is not yet wired to the build.</div><div class="cell k">hnsw_ef_search</div><div class="cell t">u32</div><div class="cell d">100</div><div class="cell dsc">Accepted but not read by the serving path — the ANN beam width comes from the request's num_candidates (floored at 800).</div><div class="cell k">default_quantization</div><div class="cell t">enum</div><div class="cell d">"none"</div><div class="cell dsc">"none" (the default) or "scalar8" = kNN scored from 1-byte-per-dimension codes, 1–2% recall loss. scalar8 buys precision, <strong>not</strong> RAM: the scan reads the full-precision vector from <code class="inline">_source</code> and quantizes it per query, so resident memory is unchanged and the field also gives up HNSW-served kNN (<a href="https://github.com/xerj-org/xerj/issues/392">#392</a>). "binary" has no quantizer behind it and is refused at startup rather than silently stored at full precision; "scalar4" is not a value this key accepts at all (the 4-bit quantizer in the vector crate is unreachable from config or mapping).</div><div class="cell k">max_dimensions</div><div class="cell t">u32</div><div class="cell d">16384</div><div class="cell dsc">Upper bound on vector dimensionality. 4× the Elasticsearch limit of 4096.</div><div class="group" id="logs">[logs]</div><div class="cell k">retention_days</div><div class="cell t">u32</div><div class="cell d">90</div><div class="cell dsc">Auto-delete log docs older than N days. 0 disables.</div><div class="cell k">time_partition</div><div class="cell t">enum</div><div class="cell d">"1h"</div><div class="cell dsc">"1m" · "5m" · "15m" · "1h" · "6h" · "1d". Time-slice granularity for retention pruning.</div><div class="group" id="embedding">[embedding]</div><div class="cell k">default_endpoint</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">OpenAI-compatible embeddings URL. Empty disables auto-embedding on ingest. Example: "https://api.openai.com/v1/embeddings".</div><div class="cell k">default_model</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Model name passed to the endpoint. Example: "text-embedding-3-small" or "nomic-embed-text".</div><div class="cell k">batch_size</div><div class="cell t">u32</div><div class="cell d">64</div><div class="cell dsc">Docs per embedding API call. Range 1–2048. Bigger batches amortise round-trip cost.</div><div class="cell k">timeout_ms</div><div class="cell t">u32</div><div class="cell d">5000</div><div class="cell dsc">HTTP timeout for embedding calls (ms). Ingest fails with a timeout error if exceeded.</div><div class="group" id="limits">[limits]</div><div class="cell k">max_query_memory_mb</div><div class="cell t">u32</div><div class="cell d">512</div><div class="cell dsc">Per-query memory cap (MiB). Queries that exceed it are cancelled.</div><div class="cell k">max_concurrent_searches</div><div class="cell t">u32</div><div class="cell d">64</div><div class="cell dsc">Global in-flight search ceiling. Extras are queued.</div><div class="cell k">max_fields_per_index</div><div class="cell t">u32</div><div class="cell d">500</div><div class="cell dsc">Field-explosion protection. ES default is 1000; 500 is intentionally stricter.</div><div class="group" id="indexing">[indexing]</div><div class="cell k">turbo_batch_size</div><div class="cell t">u32</div><div class="cell d">1000</div><div class="cell dsc">Docs per batch in turbo mode. Range 500–5000. Larger = higher throughput, slightly higher latency.</div><div class="cell k">turbo_parallel</div><div class="cell t">bool</div><div class="cell d">true</div><div class="cell dsc">Parallel tokenisation on Rayon threads. Disable only for debugging.</div><div class="cell k">turbo_fast_analyzer</div><div class="cell t">bool</div><div class="cell d">false</div><div class="cell dsc">Skip stemming and stop-word removal in turbo mode. Trades recall for speed.</div><div class="group" id="cluster">[cluster]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">false</div><div class="cell dsc">Enable multi-node cluster mode. When true, the Raft state machine and cluster transport are started on port.</div><div class="cell k">port</div><div class="cell t">u16</div><div class="cell d">9300</div><div class="cell dsc">TCP port for intra-cluster Raft and search messages. Must be reachable from every peer.</div><div class="cell k">peers</div><div class="cell t">array</div><div class="cell d">[]</div><div class="cell dsc">Peer list in "node_id=host:port" format. The local node identifies itself from the entry matching bind_address:port. Example: ["a=10.0.0.1:9300","b=10.0.0.2:9300","c=10.0.0.3:9300"].</div><div class="cell k">tick_ms</div><div class="cell t">u64</div><div class="cell d">50</div><div class="cell dsc">Raft tick interval (ms). Lower = faster leader election at the cost of CPU.</div><div class="cell k">auth_secret</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Cluster-wide shared secret authenticating every control frame on port (HMAC-SHA256 over a per-connection challenge). Mandatory when enabled = true — with cluster mode on and no secret here or in XERJ_CLUSTER_AUTH_SECRET the node refuses to start. Same value on every node; minimum 16 chars; generate with `openssl rand -hex 32`. Authenticates, does not encrypt.</div><div class="group" id="wal_tap">[wal_tap]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">false</div><div class="cell dsc">Push a filtered subset of indices to an external ES-compatible target (Elasticsearch, OpenSearch, or another XERJ node) in near-real-time. One-directional and single-node — this is not cross-cluster replication. Off by default.</div><div class="cell k">target_url</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Base URL of the target cluster; the tap POSTs to {target_url}/_bulk. Example: "https://central:9200". Empty disables the tap even with enabled = true. Must not carry credentials in the URL (user:pass@host is refused at startup): target_url is echoed by GET /_xerj/wal_tap, by _stats and in the log. Put the credential in target_auth.</div><div class="cell k">target_auth</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Verbatim Authorization header for the target, e.g. "ApiKey abc123". Write-only: GET /_xerj/wal_tap reports whether one is set, never its value.</div><div class="cell k">indices</div><div class="cell t">array</div><div class="cell d">[]</div><div class="cell dsc">Index allowlist, glob patterns. Empty ships nothing; ["edge-*","metrics"] ships those. A wildcard never expands to a hidden index, and XERJ&#39;s own .xerj* system indices are never shipped whatever this says.</div><div class="cell k">poll_interval_ms</div><div class="cell t">u64</div><div class="cell d">500</div><div class="cell dsc">How often each allowlisted index&#39;s WAL is polled (ms). Range 50–60000. This is the floor on end-to-end latency; the tap adds nothing to the write path.</div><div class="cell k">max_batch_docs</div><div class="cell t">usize</div><div class="cell d">1000</div><div class="cell dsc">Maximum WAL entries read and shipped per poll, per index. Must be at least 1.</div><div class="cell k">max_batch_bytes</div><div class="cell t">usize</div><div class="cell d">5242880</div><div class="cell dsc">Maximum _bulk body size (bytes). Bounds one HTTP request against the target&#39;s http.max_content_length — a larger batch is split across requests, never truncated.</div><div class="cell k">request_timeout_secs</div><div class="cell t">u64</div><div class="cell d">30</div><div class="cell dsc">Per-request timeout against the target. A timed-out batch is retried; the cursor does not advance, so nothing is dropped.</div><div class="cell k">max_retry_backoff_secs</div><div class="cell t">u64</div><div class="cell d">60</div><div class="cell dsc">Ceiling on the exponential, jittered retry backoff when the target is down. Range 1&ndash;86400 (one day), enforced at startup as well as by PUT /_xerj/wal_tap.</div><div class="cell k">min_retained_generations</div><div class="cell t">u64</div><div class="cell d">0</div><div class="cell dsc">Rotated WAL generations kept per shard after every entry in them is durable in a segment, so a tap whose target is briefly unreachable still finds them. At the default 0, WAL retention never waits for the target: an outage longer than storage.flush_interval_secs loses entries and reports them as gaps in GET /_xerj/wal_tap/_stats. This is a bounded floor, not a retention lease — the extra cost is at most n × storage.wal_max_size_mb per WAL shard per index, whether or not a tap is running, so a stalled target can never fill this node&#39;s disk. Capped at 64 and range-checked at startup, not only by PUT /_xerj/wal_tap &mdash; the config file must not be a way around the bound.</div><div class="group" id="rerank">[rerank]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">true</div><div class="cell dsc">Allow the <code class="inline">rerank</code> search stage. It is the only search-time feature that sends document text off this node, and it does nothing until a key is set. <strong>false</strong> refuses every rerank request with HTTP 403, whatever the environment holds, and nothing is sent.</div><div class="cell k">api_key</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Rerank provider key. Empty falls back to the TYPESAFE_API_KEY environment variable; a value here wins over the environment. Empty in both places means reranking is not configured and a rerank request gets HTTP 503. Write-only: GET /_xerj/rerank reports whether a key is set and where it came from, never its value. There is no per-request key.</div><div class="cell k">endpoint</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Where judged document text is POSTed. Empty falls back to TYPESAFE_ENDPOINT, then to https://api.typesafe.ai/v1/systemone. Must be an absolute http:// or https:// URL with no credentials in it (user:pass@host is refused at startup, whether it came from this file or from TYPESAFE_ENDPOINT): the endpoint is echoed by GET /_xerj/rerank.</div></div>
+ <div class="cfg"><div class="head">KEY</div><div class="head">TYPE</div><div class="head">DEFAULT</div><div class="head">DESCRIPTION</div><div class="group" id="server">[server]</div><div class="cell k">rest_port</div><div class="cell t">u16</div><div class="cell d">8080</div><div class="cell dsc">Native REST API listener port. All native endpoints (/v1/*) live here.</div><div class="cell k">grpc_port</div><div class="cell t">u16</div><div class="cell d">8081</div><div class="cell dsc">Reserved for a future gRPC API. Not wired in v0.1 — leave at default.</div><div class="cell k">es_compat_port</div><div class="cell t">u16</div><div class="cell d">9200</div><div class="cell dsc">Elasticsearch-compatible wire port. Point Kibana, Logstash, or the ES client here. Set to 0 to disable.</div><div class="cell k">bind_address</div><div class="cell t">string</div><div class="cell d">"127.0.0.1"</div><div class="cell dsc">Interface to bind every listener to. Loopback by default, so an unconfigured node is unreachable from the network. Set "0.0.0.0" or a private address to expose it (also --bind / XERJ_BIND_ADDRESS). Must be an IPv4 or IPv6 literal — host names are not resolved, and a node given one refuses to start.</div><div class="cell k">allow_insecure_network_bind</div><div class="cell t">bool</div><div class="cell d">false</div><div class="cell dsc">Permit a non-loopback bind_address while tls.enabled = false. Startup refuses that combination otherwise: every listener would serve plain HTTP, so the API key in every Authorization header crosses the network in cleartext. Set true only when a proxy, sidecar, mesh or container boundary terminates TLS in front of the node. Env: XERJ_ALLOW_INSECURE_NETWORK_BIND.</div><div class="cell k">data_dir</div><div class="cell t">path</div><div class="cell d">"./data"</div><div class="cell dsc">Root for indices, WAL files, and segments. Needs fast I/O and enough free space.</div><div class="group" id="auth">[auth]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">true</div><div class="cell dsc">Require an API key on every request. Set to false only on a trusted network.</div><div class="cell k">admin_api_key</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Static admin key. Left empty, a 256-bit key is generated on first run and written to <data_dir>/admin.key.</div><div class="group" id="tls">[tls]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">false</div><div class="cell dsc">Terminate TLS at the server. Requires cert_path + key_path. If you terminate at a proxy, leave false.</div><div class="cell k">cert_path</div><div class="cell t">path</div><div class="cell d">""</div><div class="cell dsc">PEM X.509 certificate. Use a CA-signed cert in production.</div><div class="cell k">key_path</div><div class="cell t">path</div><div class="cell d">""</div><div class="cell dsc">PEM private key. Permissions should be 0600.</div><div class="group" id="storage">[storage]</div><div class="cell k">wal_sync</div><div class="cell t">enum</div><div class="cell d">"batched"</div><div class="cell dsc">"sync" · "batched" · "async". Durability vs throughput. Batched is the recommended default.</div><div class="cell k">wal_batch_ms</div><div class="cell t">u32</div><div class="cell d">100</div><div class="cell dsc">Fsync cadence when wal_sync="batched" (ms). Range 1–10000. Lower = smaller loss window.</div><div class="cell k">wal_max_size_mb</div><div class="cell t">u32</div><div class="cell d">1024</div><div class="cell dsc">WAL rollover threshold (MiB). Larger means fewer rollovers, longer crash recovery.</div><div class="cell k">flush_size_mb</div><div class="cell t">u32</div><div class="cell d">512</div><div class="cell dsc">Memtable buffer size that triggers a segment flush (MiB).</div><div class="cell k">flush_interval_secs</div><div class="cell t">u32</div><div class="cell d">30</div><div class="cell dsc">Maximum wall-clock interval between flushes even if the buffer is not full.</div><div class="group" id="merge">[merge]</div><div class="cell k">strategy</div><div class="cell t">enum</div><div class="cell d">"size_tiered"</div><div class="cell dsc">Only "size_tiered" is implemented; "log_structured" is refused at startup rather than silently running the other policy.</div><div class="cell k">min_segments</div><div class="cell t">u32</div><div class="cell d">10</div><div class="cell dsc">Accepted and validated (must be ≥ 2) but <strong>not wired</strong>: the merge trigger is per-tier and comes from min_merge_count. Setting it away from the default logs a warning at startup.</div><div class="cell k">max_segment_mb</div><div class="cell t">u32</div><div class="cell d">8192</div><div class="cell dsc">Upper bound on a mergeable segment (MiB). Segments at or above this size are never merged again.</div><div class="cell k">io_rate_mb_per_sec</div><div class="cell t">u32</div><div class="cell d">100</div><div class="cell dsc">Accepted but <strong>not wired</strong>: merge I/O is not throttled in this build — the rate limiter that honours it sits in an unused storage-crate merge executor. Setting it away from the default logs a warning at startup.</div><div class="cell k">max_concurrent</div><div class="cell t">u8</div><div class="cell d">1</div><div class="cell dsc">Accepted but <strong>not wired</strong>: merge parallelism comes from the XERJ_MERGE_PARALLELISM environment variable, which also defaults to 1. Setting it away from the default logs a warning at startup.</div><div class="group" id="compression">[compression]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">true</div><div class="cell dsc">Accepted but <strong>not wired</strong>: every durable artifact is a compressed envelope with no uncompressed write path, so false changes nothing on disk. Setting it away from the default logs a warning at startup.</div><div class="cell k">level</div><div class="cell t">enum</div><div class="cell d">"balanced"</div><div class="cell dsc">"fast" (Zstd L1), "balanced" (Zstd L3, default), "best" (Zstd L6, cold storage). Applied when segments are re-encoded <strong>at merge</strong>; flush always writes L3, because raising the flush level collapses sustained ingest. Force-merge to apply a change to data already on disk.</div><div class="cell k">block_size_docs</div><div class="cell t">u32</div><div class="cell d">128</div><div class="cell dsc">Accepted but <strong>not wired</strong>: the stored codec is columnar over the whole segment section, not blocked by document count. Range 16–4096 is enforced at startup, and a non-default value logs a warning.</div><div class="group" id="fts">[fts]</div><div class="cell k">default_analyzer</div><div class="cell t">enum</div><div class="cell d">"standard"</div><div class="cell dsc">"standard" · "whitespace" · "simple" · "english". Override per-field in the mapping.</div><div class="group" id="vector">[vector]</div><div class="cell k">default_metric</div><div class="cell t">enum</div><div class="cell d">"cosine"</div><div class="cell dsc">"cosine" · "dot_product" · "euclidean". Cosine for text embeddings is the usual choice.</div><div class="cell k">hnsw_m</div><div class="cell t">u32</div><div class="cell d">16</div><div class="cell dsc">Accepted and validated; the built-in HNSW graph currently builds with fixed M=16 — this key is not yet wired to the build.</div><div class="cell k">hnsw_ef_construction</div><div class="cell t">u32</div><div class="cell d">200</div><div class="cell dsc">Accepted; must be ≥ hnsw_m. The graph currently builds with fixed ef_construction=200 — this key is not yet wired to the build.</div><div class="cell k">hnsw_ef_search</div><div class="cell t">u32</div><div class="cell d">100</div><div class="cell dsc">Accepted but not read by the serving path — the ANN beam width comes from the request's num_candidates (floored at 800).</div><div class="cell k">default_quantization</div><div class="cell t">enum</div><div class="cell d">"none"</div><div class="cell dsc">"none" (the default) or "scalar8" = kNN scored from 1-byte-per-dimension codes, 1–2% recall loss. scalar8 buys precision, <strong>not</strong> RAM: the scan reads the full-precision vector from <code class="inline">_source</code> and quantizes it per query, so resident memory is unchanged and the field also gives up HNSW-served kNN (<a href="https://github.com/xerj-org/xerj/issues/392">#392</a>). "binary" has no quantizer behind it and is refused at startup rather than silently stored at full precision; "scalar4" is not a value this key accepts at all (the 4-bit quantizer in the vector crate is unreachable from config or mapping).</div><div class="cell k">max_dimensions</div><div class="cell t">u32</div><div class="cell d">16384</div><div class="cell dsc">Upper bound on vector dimensionality. 4× the Elasticsearch limit of 4096.</div><div class="group" id="logs">[logs]</div><div class="cell k">retention_days</div><div class="cell t">u32</div><div class="cell d">90</div><div class="cell dsc">Auto-delete log docs older than N days. 0 disables.</div><div class="cell k">time_partition</div><div class="cell t">enum</div><div class="cell d">"1h"</div><div class="cell dsc">"1m" · "5m" · "15m" · "1h" · "6h" · "1d". Time-slice granularity for retention pruning.</div><div class="group" id="embedding">[embedding]</div><div class="cell k">default_endpoint</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">OpenAI-compatible embeddings URL. Empty disables auto-embedding on ingest. Example: "https://api.openai.com/v1/embeddings".</div><div class="cell k">default_model</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Model name passed to the endpoint. Example: "text-embedding-3-small" or "nomic-embed-text".</div><div class="cell k">batch_size</div><div class="cell t">u32</div><div class="cell d">64</div><div class="cell dsc">Docs per embedding API call. Range 1–2048. Bigger batches amortise round-trip cost.</div><div class="cell k">timeout_ms</div><div class="cell t">u32</div><div class="cell d">5000</div><div class="cell dsc">HTTP timeout for embedding calls (ms). Ingest fails with a timeout error if exceeded.</div><div class="group" id="limits">[limits]</div><div class="cell k">max_query_memory_mb</div><div class="cell t">u32</div><div class="cell d">512</div><div class="cell dsc">Per-query memory cap (MiB). Queries that exceed it are cancelled.</div><div class="cell k">max_concurrent_searches</div><div class="cell t">u32</div><div class="cell d">64</div><div class="cell dsc">Global in-flight search ceiling. Extras are queued.</div><div class="cell k">max_fields_per_index</div><div class="cell t">u32</div><div class="cell d">500</div><div class="cell dsc">Field-explosion protection. ES default is 1000; 500 is intentionally stricter.</div><div class="cell k">max_result_window</div><div class="cell t">u64</div><div class="cell d">10000</div><div class="cell dsc">Largest <code class="inline">from + size</code> a search may ask for, for any index whose settings carry no <code class="inline">index.max_result_window</code> (that setting wins when present, above or below this). 1–2147483647. Page past it with <code class="inline">search_after</code> or a point-in-time cursor.</div><div class="group" id="indexing">[indexing]</div><div class="cell k">turbo_batch_size</div><div class="cell t">u32</div><div class="cell d">1000</div><div class="cell dsc">Docs per batch in turbo mode. Range 500–5000. Larger = higher throughput, slightly higher latency.</div><div class="cell k">turbo_parallel</div><div class="cell t">bool</div><div class="cell d">true</div><div class="cell dsc">Parallel tokenisation on Rayon threads. Disable only for debugging.</div><div class="cell k">turbo_fast_analyzer</div><div class="cell t">bool</div><div class="cell d">false</div><div class="cell dsc">Skip stemming and stop-word removal in turbo mode. Trades recall for speed.</div><div class="group" id="cluster">[cluster]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">false</div><div class="cell dsc">Enable multi-node cluster mode. When true, the Raft state machine and cluster transport are started on port.</div><div class="cell k">port</div><div class="cell t">u16</div><div class="cell d">9300</div><div class="cell dsc">TCP port for intra-cluster Raft and search messages. Must be reachable from every peer.</div><div class="cell k">peers</div><div class="cell t">array</div><div class="cell d">[]</div><div class="cell dsc">Peer list in "node_id=host:port" format. The local node identifies itself from the entry matching bind_address:port. Example: ["a=10.0.0.1:9300","b=10.0.0.2:9300","c=10.0.0.3:9300"].</div><div class="cell k">tick_ms</div><div class="cell t">u64</div><div class="cell d">50</div><div class="cell dsc">Raft tick interval (ms). Lower = faster leader election at the cost of CPU.</div><div class="cell k">auth_secret</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Cluster-wide shared secret authenticating every control frame on port (HMAC-SHA256 over a per-connection challenge). Mandatory when enabled = true — with cluster mode on and no secret here or in XERJ_CLUSTER_AUTH_SECRET the node refuses to start. Same value on every node; minimum 16 chars; generate with `openssl rand -hex 32`. Authenticates, does not encrypt.</div><div class="group" id="wal_tap">[wal_tap]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">false</div><div class="cell dsc">Push a filtered subset of indices to an external ES-compatible target (Elasticsearch, OpenSearch, or another XERJ node) in near-real-time. One-directional and single-node — this is not cross-cluster replication. Off by default.</div><div class="cell k">target_url</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Base URL of the target cluster; the tap POSTs to {target_url}/_bulk. Example: "https://central:9200". Empty disables the tap even with enabled = true. Must not carry credentials in the URL (user:pass@host is refused at startup): target_url is echoed by GET /_xerj/wal_tap, by _stats and in the log. Put the credential in target_auth.</div><div class="cell k">target_auth</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Verbatim Authorization header for the target, e.g. "ApiKey abc123". Write-only: GET /_xerj/wal_tap reports whether one is set, never its value.</div><div class="cell k">indices</div><div class="cell t">array</div><div class="cell d">[]</div><div class="cell dsc">Index allowlist, glob patterns. Empty ships nothing; ["edge-*","metrics"] ships those. A wildcard never expands to a hidden index, and XERJ&#39;s own .xerj* system indices are never shipped whatever this says.</div><div class="cell k">poll_interval_ms</div><div class="cell t">u64</div><div class="cell d">500</div><div class="cell dsc">How often each allowlisted index&#39;s WAL is polled (ms). Range 50–60000. This is the floor on end-to-end latency; the tap adds nothing to the write path.</div><div class="cell k">max_batch_docs</div><div class="cell t">usize</div><div class="cell d">1000</div><div class="cell dsc">Maximum WAL entries read and shipped per poll, per index. Must be at least 1.</div><div class="cell k">max_batch_bytes</div><div class="cell t">usize</div><div class="cell d">5242880</div><div class="cell dsc">Maximum _bulk body size (bytes). Bounds one HTTP request against the target&#39;s http.max_content_length — a larger batch is split across requests, never truncated.</div><div class="cell k">request_timeout_secs</div><div class="cell t">u64</div><div class="cell d">30</div><div class="cell dsc">Per-request timeout against the target. A timed-out batch is retried; the cursor does not advance, so nothing is dropped.</div><div class="cell k">max_retry_backoff_secs</div><div class="cell t">u64</div><div class="cell d">60</div><div class="cell dsc">Ceiling on the exponential, jittered retry backoff when the target is down. Range 1&ndash;86400 (one day), enforced at startup as well as by PUT /_xerj/wal_tap.</div><div class="cell k">min_retained_generations</div><div class="cell t">u64</div><div class="cell d">0</div><div class="cell dsc">Rotated WAL generations kept per shard after every entry in them is durable in a segment, so a tap whose target is briefly unreachable still finds them. At the default 0, WAL retention never waits for the target: an outage longer than storage.flush_interval_secs loses entries and reports them as gaps in GET /_xerj/wal_tap/_stats. This is a bounded floor, not a retention lease — the extra cost is at most n × storage.wal_max_size_mb per WAL shard per index, whether or not a tap is running, so a stalled target can never fill this node&#39;s disk. Capped at 64 and range-checked at startup, not only by PUT /_xerj/wal_tap &mdash; the config file must not be a way around the bound.</div><div class="group" id="rerank">[rerank]</div><div class="cell k">enabled</div><div class="cell t">bool</div><div class="cell d">true</div><div class="cell dsc">Allow the <code class="inline">rerank</code> search stage. It is the only search-time feature that sends document text off this node, and it does nothing until a key is set. <strong>false</strong> refuses every rerank request with HTTP 403, whatever the environment holds, and nothing is sent.</div><div class="cell k">api_key</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Rerank provider key. Empty falls back to the TYPESAFE_API_KEY environment variable; a value here wins over the environment. Empty in both places means reranking is not configured and a rerank request gets HTTP 503. Write-only: GET /_xerj/rerank reports whether a key is set and where it came from, never its value. There is no per-request key.</div><div class="cell k">endpoint</div><div class="cell t">string</div><div class="cell d">""</div><div class="cell dsc">Where judged document text is POSTed. Empty falls back to TYPESAFE_ENDPOINT, then to https://api.typesafe.ai/v1/systemone. Must be an absolute http:// or https:// URL with no credentials in it (user:pass@host is refused at startup, whether it came from this file or from TYPESAFE_ENDPOINT): the endpoint is echoed by GET /_xerj/rerank.</div></div>
<h2 id="server-section">[server]</h2>