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.
Rust agent-memoryai-agentsbm25claude-codeclicode-searchcursordatabaseelasticsearchfull-text-searchhybrid-searchjsonllocal-firstmcpmcp-servermodel-context-protocolragrustsearch-enginevector-search
//! Bulk operation handler.
//!
//! Parses ES-compatible NDJSON bulk format and executes operations against
//! the engine with per-item error isolation.
//!
//! Performance: index/create operations are batched per-index and submitted
//! via `index_batch_turbo()` for maximum throughput (50K+ docs/sec).
use std::collections::HashMap;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use crate::engine::Engine;
use crate::index::IndexResponse;
use crate::{EngineError, Result};
#[cfg(test)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum SemanticLifecyclePoint {
Grouped,
Parsed,
Prepared,
EmbeddingInside,
EmbeddingItemInside,
BeforePublication,
PublicationInside,
AfterPublication,
}
#[cfg(test)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum SemanticLifecycleFault {
None,
Embedding,
Publication,
}
#[cfg(test)]
pub(crate) type SemanticLifecycleHook = std::sync::Arc<
dyn Fn(&str, SemanticLifecyclePoint) -> SemanticLifecycleFault + Send + Sync + 'static,
>;
#[cfg(test)]
tokio::task_local! {
static SEMANTIC_LIFECYCLE_HOOK: (String, SemanticLifecycleHook);
static DISABLED_SEMANTIC_COUNTERS: std::sync::Arc<DisabledSemanticCounters>;
}
#[cfg(test)]
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
struct DisabledSemanticInstrumentation {
schema_reads: usize,
guard_vectors: usize,
sizing_walks: usize,
}
#[cfg(test)]
#[derive(Default)]
struct DisabledSemanticCounters {
schema_reads: std::sync::atomic::AtomicUsize,
guard_vectors: std::sync::atomic::AtomicUsize,
sizing_walks: std::sync::atomic::AtomicUsize,
}
#[cfg(test)]
impl DisabledSemanticCounters {
fn snapshot(&self) -> DisabledSemanticInstrumentation {
use std::sync::atomic::Ordering;
DisabledSemanticInstrumentation {
schema_reads: self.schema_reads.load(Ordering::Relaxed),
guard_vectors: self.guard_vectors.load(Ordering::Relaxed),
sizing_walks: self.sizing_walks.load(Ordering::Relaxed),
}
}
}
#[cfg(test)]
fn count_disabled_semantic_access(
select: fn(&DisabledSemanticCounters) -> &std::sync::atomic::AtomicUsize,
) {
use std::sync::atomic::Ordering;
let _ = DISABLED_SEMANTIC_COUNTERS.try_with(|counters| {
select(counters).fetch_add(1, Ordering::Relaxed);
});
}
#[cfg(test)]
pub(crate) fn semantic_lifecycle_hook(
target: &str,
point: SemanticLifecyclePoint,
) -> SemanticLifecycleFault {
SEMANTIC_LIFECYCLE_HOOK
.try_with(|(hook_target, hook)| {
if hook_target == "*" || hook_target == target {
hook(target, point)
} else {
SemanticLifecycleFault::None
}
})
.unwrap_or(SemanticLifecycleFault::None)
}
#[cfg(test)]
pub(crate) async fn with_semantic_lifecycle_hook<F: std::future::Future>(
target: impl Into<String>,
hook: SemanticLifecycleHook,
future: F,
) -> F::Output {
SEMANTIC_LIFECYCLE_HOOK
.scope((target.into(), hook), future)
.await
}
#[cfg(test)]
fn semantic_lifecycle_hook_installed(target: &str) -> bool {
SEMANTIC_LIFECYCLE_HOOK
.try_with(|(hook_target, _)| hook_target == "*" || hook_target == target)
.unwrap_or(false)
}
#[cfg(not(test))]
fn semantic_lifecycle_hook_installed(_target: &str) -> bool {
false
}
#[cfg(test)]
thread_local! {
/// Test-only count of explicit-id batch publications (#2427).
static EXPLICIT_ID_BATCHES: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
}
/// Publish semantically prepared sources as one batch (#2427). A failed
/// preparation fails only its own item; an empty id gets a generated one.
async fn publish_prepared_batch(
idx: &crate::index::Index,
index_name: &str,
prepared: Vec<(usize, String, Result<Value>)>,
items: &mut [Option<BulkItemResult>],
) -> bool {
let mut errors = false;
let mut docs = Vec::with_capacity(prepared.len());
for (item_idx, id, prepared) in prepared {
let failure = match prepared {
Ok(source) => {
let id = if id.is_empty() {
uuid::Uuid::new_v4().to_string()
} else {
id
};
match serde_json::to_vec(&source) {
Ok(bytes) => {
docs.push((item_idx, id, std::sync::Arc::<[u8]>::from(bytes)));
continue;
}
Err(e) => (id, 500, e.to_string()),
}
}
Err(e) => (id, engine_error_http_status(&e), e.to_string()),
};
let (id, status, error) = failure;
items[item_idx] = Some(BulkItemResult {
action: "index".into(),
index: index_name.to_string(),
id,
status,
result: None,
error: Some(error),
get_source: None,
});
errors = true;
}
errors | publish_explicit_id_batch(idx, index_name, docs, items).await
}
/// Publish `index` actions that carry an `_id` as one batch and fill their
/// item slots in request order. Returns whether any item failed (#2427).
async fn publish_explicit_id_batch(
idx: &crate::index::Index,
index_name: &str,
docs: Vec<(usize, String, std::sync::Arc<[u8]>)>,
items: &mut [Option<BulkItemResult>],
) -> bool {
if docs.is_empty() {
return false;
}
#[cfg(test)]
EXPLICIT_ID_BATCHES.with(|count| count.set(count.get() + 1));
let mut errors = false;
let mut slots = Vec::with_capacity(docs.len());
let batch = docs
.into_iter()
.map(|(item_idx, id, bytes)| {
slots.push((item_idx, id.clone()));
(id, bytes)
})
.collect();
match idx.index_batch_explicit_ids_raw(batch).await {
Ok(results) => {
for ((item_idx, id), result) in slots.into_iter().zip(results) {
items[item_idx] = Some(match result {
Ok(resp) => BulkItemResult {
action: "index".into(),
index: index_name.to_string(),
id: resp.id,
// 201 for a new doc, 200 for an overwrite (ES).
status: if resp.result == "updated" { 200 } else { 201 },
result: Some(resp.result),
error: None,
get_source: None,
},
Err(e) => {
errors = true;
BulkItemResult {
action: "index".into(),
index: index_name.to_string(),
id,
status: engine_error_http_status(&e),
result: None,
error: Some(e.to_string()),
get_source: None,
}
}
});
}
}
Err(e) => {
// Whole-batch failure (write block, breaker, back-pressure):
// every item gets the same status, as on the auto-id batch.
let status = engine_error_http_status(&e);
for (item_idx, id) in slots {
items[item_idx] = Some(BulkItemResult {
action: "index".into(),
index: index_name.to_string(),
id,
status,
result: None,
error: Some(e.to_string()),
get_source: None,
});
}
errors = true;
}
}
errors
}
// ── Types ─────────────────────────────────────────────────────────────────────
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BulkResult {
pub took_ms: u64,
pub errors: bool,
pub items: Vec<BulkItemResult>,
}
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct BulkItemResult {
pub action: String,
pub index: String,
pub id: String,
pub status: u16,
pub result: Option<String>,
pub error: Option<String>,
/// Post-execution source to echo under `items[N].<action>.get` in
/// the HTTP response. Populated only when the action metadata
/// carried `_source: true` / `_source: {...}` and the action
/// succeeded. None for all other cases.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub get_source: Option<Value>,
}
fn malformed_document_reason(
document_id: Option<&str>,
item_index: usize,
error: &serde_json::Error,
) -> String {
let document_id = document_id.unwrap_or("<auto-generated>");
format!(
"invalid document JSON for document ID {document_id:?} at bulk item position {}: \
parser error: {error}; parser location: line {}, column {}. \
Fix: replace this source line with exactly one complete UTF-8 JSON object. \
Related help: xerj index --help and https://xerj.org/llms.txt",
item_index + 1,
error.line(),
error.column(),
)
}
/// Per-item 400 reason for a document carrying an unpaired UTF-16 surrogate.
/// Mirrors the shape of [`malformed_document_reason`] so the HTTP response
/// reads the same way, and names the fix the issue reporter already adopted.
fn lone_surrogate_document_reason(
document_id: Option<&str>,
item_index: usize,
detail: &str,
) -> String {
let document_id = document_id.unwrap_or("<auto-generated>");
format!(
"invalid document JSON for document ID {document_id:?} at bulk item position {}: \
parser error: {detail}; a JSON string escape (\\uXXXX) encoded an unpaired UTF-16 \
surrogate — half of an astral code point (e.g. an emoji cut in two by a fixed-width \
chunker). Fix: replace the unpaired surrogate with U+FFFD, or re-encode the field as \
valid UTF-8, before indexing. \
Related help: xerj index --help and https://xerj.org/llms.txt",
item_index + 1,
)
}
/// Scan a structurally-valid JSON document for an unpaired UTF-16 surrogate in
/// a `\uXXXX` string escape, returning a short reason when one is found.
///
/// Why this exists: the `index` turbo path validates each source line with
/// `serde_json::IgnoredAny`, which walks the JSON *without decoding* string
/// contents, so it ACCEPTS an escape such as `"a\ud83db"`. The auto-id docs
/// are then grouped and parsed as one batch into `serde_json::Value`s
/// (`index_batch_turbo_raw` → `parse_validated_raw_batch`), and that parse
/// DOES decode escapes and rejects the unpaired surrogate — but it fails the
/// whole batch with a single error, so one bad chunk sank all 127 of its
/// neighbours (issue #1304). ES reports such a document per-item and indexes
/// the rest; this check restores that contract by catching the one gap
/// between `IgnoredAny` acceptance and `Value` rejection here, per-item,
/// before the document can enter a batch.
///
/// It runs only after `IgnoredAny` has already accepted the bytes, so every
/// string is terminated and every `\u` is followed by four hex digits; the
/// scan therefore only has to check surrogate *pairing*. Equivalence with
/// serde_json's own accept/reject decision is pinned by a unit test. Unpaired
/// surrogates are the sole semantic string check `Value` makes that
/// `IgnoredAny` skips (nesting depth is already capped identically upstream
/// in `validate_raw_json_nesting`), so this closes the gap completely.
fn lone_surrogate_escape_reason(bytes: &[u8]) -> Option<&'static str> {
// Decode four ASCII hex digits at `i` into a u16. The structural pass
// guarantees they are present and valid; `None` here would mean that
// invariant broke, in which case we defer to the downstream parser.
fn hex4(bytes: &[u8], i: usize) -> Option<u16> {
let mut value: u16 = 0;
for offset in 0..4 {
let digit = *bytes.get(i + offset)?;
let nibble = match digit {
b'0'..=b'9' => digit - b'0',
b'a'..=b'f' => digit - b'a' + 10,
b'A'..=b'F' => digit - b'A' + 10,
_ => return None,
};
value = (value << 4) | nibble as u16;
}
Some(value)
}
// Fast path: a `\uXXXX` escape requires a backslash, so a document with
// no backslash at all cannot carry an unpaired surrogate. `contains` is a
// single memchr pass, which keeps the common ingest doc (no escapes) off
// the byte-by-byte state machine below and preserves the turbo win.
if !bytes.contains(&b'\\') {
return None;
}
let mut i = 0;
let mut in_string = false;
while i < bytes.len() {
let byte = bytes[i];
if !in_string {
if byte == b'"' {
in_string = true;
}
i += 1;
continue;
}
match byte {
b'"' => {
in_string = false;
i += 1;
}
b'\\' => {
// The byte after a backslash is the escape kind. An escaped
// backslash (`\\`) consumes both bytes here, so a following
// `u` is a literal `u`, never the start of a `\u` escape.
match bytes.get(i + 1).copied() {
Some(b'u') => {
// `None` can only mean the structural invariant broke;
// fall through to the downstream parser via `?`.
let code_unit = hex4(bytes, i + 2)?;
if (0xDC00..=0xDFFF).contains(&code_unit) {
// A low surrogate with no preceding high surrogate.
return Some("lone trailing surrogate in hex escape");
}
if (0xD800..=0xDBFF).contains(&code_unit) {
// A high surrogate must be followed immediately by
// a `\u` escape encoding a low surrogate.
let paired = bytes.get(i + 6) == Some(&b'\\')
&& bytes.get(i + 7) == Some(&b'u')
&& hex4(bytes, i + 8)
.is_some_and(|low| (0xDC00..=0xDFFF).contains(&low));
if !paired {
return Some("lone leading surrogate in hex escape");
}
// Consume the whole valid pair: `\uXXXX\uYYYY`.
i += 12;
continue;
}
// A well-formed non-surrogate `\uXXXX` escape.
i += 6;
}
Some(_) => i += 2, // `\"`, `\\`, `\n`, `\t`, …
None => i += 1,
}
}
_ => i += 1,
}
}
None
}
/// The one place a bulk item's per-item `status` is derived from an engine
/// error. Every `Err` arm in this module routes through here.
///
/// It defers to `XerjError::http_status()` (409 version conflict, 404 not
/// found, 403 index blocked, 400 bad mapping/query, 429 exhausted …) and only
/// overrides one case: the disk flood-stage block reports itself as
/// `read_only_allow_delete`, which ES answers **429**, not the 403 the other
/// blocks get (`IndexMetadata.INDEX_READ_ONLY_ALLOW_DELETE_BLOCK` carries
/// `RestStatus.TOO_MANY_REQUESTS`; approach only, no ES code reproduced).
///
/// Three call sites used to inline their own `match` instead, and each listed
/// only the errors its author had in mind — so a genuine write block fell
/// through `_ => 500` and a blocked bulk looked like a server fault.
fn engine_error_http_status(error: &EngineError) -> u16 {
match error {
EngineError::Common(xerj_common::XerjError::IndexBlocked { block_type, .. })
if block_type.contains("read_only_allow_delete") =>
{
429
}
EngineError::Common(error) => error.http_status(),
_ => 500,
}
}
// ── Bulk processor ────────────────────────────────────────────────────────────
/// A parsed bulk action before execution.
struct ParsedAction {
action_type: String,
target_index: String,
doc_id: Option<String>,
doc_body: Option<Value>,
/// Original NDJSON bytes for the doc line — forwarded verbatim to
/// the WAL so we never re-serialize the parsed `Value`. Empty for
/// delete actions.
doc_bytes: std::sync::Arc<[u8]>,
/// Original position in the output items vec.
item_index: usize,
/// `require_alias` flag: Some(true) → require target to be an alias;
/// Some(false) → explicitly opt out of URL default;
/// None → inherit URL-level default.
require_alias: Option<bool>,
/// Per-item ingest pipeline name (if set via action metadata).
pipeline: Option<String>,
/// Optimistic concurrency: expected `_seq_no` / `_primary_term`
/// from the action metadata. When set, the engine routes via
/// `index_document_with_version` so a mismatch produces a 409
/// `version_conflict_engine_exception` per-item error.
if_seq_no: Option<u64>,
if_primary_term: Option<u64>,
/// Per-item `_routing` from action metadata — stored on the doc
/// as `_routing` so `exists: _routing` and `fields: [_routing]`
/// resolve.
routing: Option<String>,
/// Per-item `dynamic_templates` spec from the action metadata.
/// ES bulk allows callers to request a specific dynamic template
/// per field: `{"index":{"dynamic_templates":{"foo":"tmpl_name"}}}`.
/// Validation against the index's declared `dynamic_templates`
/// happens in execute_bulk_action — unknown template names
/// produce a per-item 400 `document_parsing_exception`.
dynamic_templates: Option<std::collections::BTreeMap<String, String>>,
/// Per-item `_source` from action metadata (update-only). When
/// set, the response echoes the post-update source under
/// `items[N].update.get._source` (ES `?_source=true` shorthand
/// on bulk updates).
source_req: Option<Value>,
}
/// Process a bulk NDJSON body.
///
/// `default_index` is used when the action line does not specify `_index`.
///
/// All `index` and `create` operations are batched per-index and submitted
/// via `index_batch_turbo()` for 10–20x higher throughput than one-at-a-time.
/// `update` and `delete` operations are still executed individually.
pub async fn process_bulk(engine: &Engine, default_index: Option<&str>, body: &str) -> BulkResult {
process_bulk_with_opts(engine, default_index, body, BulkOpts::default()).await
}
fn release_raw_owner(
owners: &mut std::collections::HashMap<usize, (usize, crate::ingest_memory::Retained<'static>)>,
source: std::sync::Arc<[u8]>,
) {
let owner = std::sync::Arc::as_ptr(&source) as *const () as usize;
// The logical owner must outlive every Arc clone. Dropping the ledger
// token first would publish a false zero while this clone still retains
// the backing allocation.
drop(source);
release_raw_owner_by_id(owners, owner);
}
fn release_raw_owner_by_id(
owners: &mut std::collections::HashMap<usize, (usize, crate::ingest_memory::Retained<'static>)>,
owner: usize,
) {
if let Some((remaining, _)) = owners.get_mut(&owner) {
*remaining -= 1;
if *remaining == 0 {
owners.remove(&owner);
}
}
}
#[derive(Clone, Default)]
pub struct BulkOpts {
pub require_alias: Option<bool>,
/// URL-level default `_source` / `_source_includes` / `_source_excludes`
/// shape (see search body filter). Applied to every update action
/// that doesn't provide its own `_source` in the action meta.
pub default_source_req: Option<Value>,
/// URL-level `?pipeline=` — the ingest pipeline for every `index` /
/// `create` action that does not name one in its own action metadata.
/// `_none` disables the target index's `index.default_pipeline`.
///
/// Issue #204: this used to be dropped on the floor, so
/// `POST /_bulk?pipeline=redact` answered `201` per item and stored the
/// UNREDACTED document, while the single-document form of the same write
/// ran the pipeline. Same for `index.default_pipeline`, which `_bulk` never
/// consulted at all.
pub default_pipeline: Option<String>,
}
/// The action named by the first key of a bulk action line, without parsing
/// the line. Anything unrecognised reads as `index`, the renderer's default.
fn action_line_kind(line: &str) -> &'static str {
let rest = line.trim_start_matches([' ', '\t']);
let Some(rest) = rest.strip_prefix('{') else {
return "index";
};
let rest = rest.trim_start_matches([' ', '\t']);
let Some(rest) = rest.strip_prefix('"') else {
return "index";
};
match rest.split('"').next() {
Some("create") => "create",
Some("update") => "update",
Some("delete") => "delete",
_ => "index",
}
}
/// One refusal item per paired action, in body order (#2427). Used when the
/// whole request is refused before its parse: a single summary item would
/// not match the body's action count, and the autoindex client (like any
/// client re-offering 429 items by position) could not map it back.
fn refuse_every_action(
pairs: &[(usize, &str, Option<&str>, usize)],
default_index: Option<&str>,
error: &EngineError,
) -> Vec<BulkItemResult> {
let status = engine_error_http_status(error);
let reason = error.to_string();
pairs
.iter()
.map(|(_, action_line, _, _)| BulkItemResult {
action: action_line_kind(action_line).to_string(),
index: default_index.unwrap_or("").to_string(),
id: String::new(),
status,
result: None,
error: Some(reason.clone()),
get_source: None,
})
.collect()
}
pub async fn process_bulk_with_opts(
engine: &Engine,
default_index: Option<&str>,
body: &str,
opts: BulkOpts,
) -> BulkResult {
use rayon::prelude::*;
let started = std::time::Instant::now();
// ── F8: bulk DoS protections ──────────────────────────────────────────
//
// 1. Acquire a global bulk-concurrency permit. Caps the number of
// concurrent `_bulk` requests in the parse phase to
// `max_concurrent_bulks` (default 8), preventing N concurrent bulks
// from each materializing ~300 B/action of parse-phase heap before the
// memtable admission check fires.
// 2. Enforce `max_actions_per_bulk` (default 50 000). An unbounded bulk
// body of one-byte lines produces ~50 M lines → ~25 M action pairs ×
// ~300 B ≈ 7.5 GiB of heap per request. The cap rejects oversized
// bulks with a single 413-style error item before allocating the
// parse-phase Vecs.
let _bulk_permit = match crate::governor::global() {
Some(g) => match g.acquire_bulk().await {
Ok(p) => Some(p),
Err(e) => {
return BulkResult {
took_ms: started.elapsed().as_millis() as u64,
errors: true,
items: vec![BulkItemResult {
action: "bulk".to_string(),
index: default_index.unwrap_or("").to_string(),
id: String::new(),
status: 503,
result: None,
error: Some(e.to_string()),
get_source: None,
}],
};
}
},
None => None,
};
let t_lines = std::time::Instant::now();
let lines: Vec<&str> = body.lines().filter(|l| !l.trim().is_empty()).collect();
let lines_ms = t_lines.elapsed().as_millis() as u64;
// Pre-allocate output slots — filled in after execution.
let mut items: Vec<Option<BulkItemResult>> = Vec::new();
let mut errors = false;
// F8: enforce `max_actions_per_bulk`. Each action is an action+doc line
// pair (or a single delete line), so the action count is at most
// `lines.len()`. Reject before building `pairs` / `parse_results` /
// `parsed` (the ~300 B/action amplifiers).
let max_actions = engine.config().limits.max_actions_per_bulk;
if max_actions > 0 && lines.len() > max_actions * 2 {
return BulkResult {
took_ms: started.elapsed().as_millis() as u64,
errors: true,
items: vec![BulkItemResult {
action: "bulk".to_string(),
index: default_index.unwrap_or("").to_string(),
id: String::new(),
status: 413,
result: None,
error: Some(format!(
"bulk request contains {} lines (~{} actions); exceeds max_actions_per_bulk of {}",
lines.len(),
lines.len() / 2,
max_actions,
)),
get_source: None,
}],
};
}
// M5.3 — PARALLEL NDJSON PARSE.
//
// Pre-M5.3 the bulk parser walked lines serially, calling
// `serde_json::from_str::<Value>` on every action + doc line.
// For a 5 000-doc bulk = 10 000 parses × ~5 µs = ~50 ms of
// single-threaded work per batch — the single largest CPU cost
// in the bulk ingest path at single-client saturation.
//
// We pair action+doc lines into tuples (an action line is
// always followed by a doc line for index/create/update; delete
// has no doc line), then rayon-parallel-parse the tuples. The
// parse is a pure function so no cross-pair state is shared —
// rayon shards the work across up to `num_cpus()` cores.
//
// The parse output is a `Vec<Result<ParsedAction, ErrItem>>`
// that preserves the original order, so downstream code that
// matches on item_index remains correct.
// Step 1: pair action + doc lines so we can parse each pair in
// parallel. The delete action has no doc line, so we track the
// optional body-line index.
// A delete action has NO body line; index/create/update each have
// exactly one. The action type is the first key of the action object
// (`{"delete":{...}}`), so we can identify a delete from its action
// line alone — no full parse needed. This loop USED to optimistically
// consume the next line as the body for EVERY action and rely on a
// "push it back" fixup that was never actually implemented (see the
// delete branch below). The result: a delete followed by another
// action (e.g. two consecutive deletes) silently swallowed that next
// action line — ~50% of consecutive deletes were lost. Detect the
// delete up front so its body line is never consumed.
fn action_line_is_delete(line: &str) -> bool {
let b = line.as_bytes();
let mut p = 0usize;
while p < b.len() && (b[p] == b' ' || b[p] == b'\t') {
p += 1;
}
if p >= b.len() || b[p] != b'{' {
return false;
}
p += 1;
while p < b.len() && (b[p] == b' ' || b[p] == b'\t') {
p += 1;
}
if p >= b.len() || b[p] != b'"' {
return false;
}
p += 1;
let start = p;
while p < b.len() && b[p] != b'"' {
p += 1;
}
p < b.len() && &b[start..p] == b"delete"
}
let mut pairs: Vec<(usize, &str, Option<&str>, usize)> = Vec::new();
let mut i = 0;
while i < lines.len() {
let action_line = lines[i];
let item_index = items.len();
items.push(None);
let (doc_line, advance) = if !action_line_is_delete(action_line) && i + 1 < lines.len() {
(Some(lines[i + 1]), 2)
} else {
(None, 1)
};
pairs.push((i, action_line, doc_line, item_index));
i += advance;
}
// #2427: memory admission for the whole request BEFORE the parse.
// The write paths below check the breaker only after the parse has built
// a document copy (and, for update/create, a parsed `Value`) per action,
// so a bulk admitted on a stale sample, or while a latch was engaged,
// allocated all of that first. `lines` and `pairs` borrow the body and
// cost a few words per action. Refuse here with one 429 per action (the
// client re-offers 429 items by position, so the count must match the
// body), or count the body against live RSS until the parse ends.
let parse_reservation = match crate::governor::global() {
Some(g) => match g.admit_bulk_parse(body.len() as u64) {
Ok(reservation) => Some(reservation),
Err(e) => {
// The refusal frees nothing by itself; ask for the drain on
// this 429 like `Index::governor_write_gate` (#2321).
crate::engine::request_memory_pressure_drain();
return BulkResult {
took_ms: started.elapsed().as_millis() as u64,
errors: true,
items: refuse_every_action(&pairs, default_index, &EngineError::Common(e)),
};
}
},
None => None,
};
// Step 2: parallel parse. Each tuple yields either a
// `ParsedAction` or an `ErrItem`. The order of the output
// vector matches the input order so `item_index` still
// addresses the right slot.
enum ParseOutcome {
Ok(ParsedAction),
Err(BulkItemResult, usize),
}
let t_parse = std::time::Instant::now();
// Dedicated ingest pool: keeps bulk-parse bursts off the global rayon
// pool that the search path fans out on (see `crate::ingest_pool`).
let parse_results: Vec<ParseOutcome> = crate::ingest_pool().install(|| {
pairs
.par_iter()
.map(|(_line_idx, action_line, doc_line, item_index)| {
// M5.12 — FAST-PATH manual parse of the action line.
//
// Pre-M5.12 the action line hit `serde_json::from_str::<Value>`
// which allocates a Map<String,Value> for every one of 5000
// action lines per batch = ~5 us × 5000 = 25 ms of pure
// allocation per bulk batch.
//
// We handle the three common shapes inline and fall back to
// full serde_json parse only on a cache miss:
// {"index":{}}
// {"index":{"_id":"..."}}
// {"index":{"_index":"..."}}
// {"index":{"_index":"...","_id":"..."}}
// (same for "create", "update", "delete")
let bytes = action_line.as_bytes();
// Any require_alias mention forces full parse (bool extraction is
// not handled in the fast path); uncommon enough to not matter.
let has_require_alias = bytes.windows(14).any(|w| w == b"require_alias\"");
let has_pipeline = bytes.windows(9).any(|w| w == b"pipeline\"");
let has_if_seq_no = bytes.windows(11).any(|w| w == b"\"if_seq_no\"");
let has_routing = bytes.windows(9).any(|w| w == b"\"routing\"");
let has_source = bytes.windows(9).any(|w| w == b"\"_source\"");
let has_dynamic_templates =
bytes.windows(19).any(|w| w == b"\"dynamic_templates\"");
let mut require_alias_per_item: Option<bool> = None;
let mut pipeline_per_item: Option<String> = None;
let mut if_seq_no_per_item: Option<u64> = None;
let mut if_primary_term_per_item: Option<u64> = None;
let mut routing_per_item: Option<String> = None;
let mut source_req_per_item: Option<Value> = None;
let mut dynamic_templates_per_item: Option<
std::collections::BTreeMap<String, String>,
> = None;
let (action_type, target_index, doc_id) = 'fast: {
if has_require_alias
|| has_pipeline
|| has_if_seq_no
|| has_routing
|| has_source
|| has_dynamic_templates
{
break 'fast (None, None, None);
}
// Parse state: skip whitespace, expect `{`, "action": "index" etc.
let mut p = 0usize;
while p < bytes.len() && (bytes[p] == b' ' || bytes[p] == b'\t') {
p += 1;
}
if p >= bytes.len() || bytes[p] != b'{' {
break 'fast (None, None, None);
}
p += 1;
while p < bytes.len() && (bytes[p] == b' ' || bytes[p] == b'\t') {
p += 1;
}
if p >= bytes.len() || bytes[p] != b'"' {
break 'fast (None, None, None);
}
p += 1;
// Find closing quote of action name.
let key_start = p;
while p < bytes.len() && bytes[p] != b'"' {
p += 1;
}
if p >= bytes.len() {
break 'fast (None, None, None);
}
let key = &bytes[key_start..p];
let action_ty: &'static str = match key {
b"index" => "index",
b"create" => "create",
b"update" => "update",
b"delete" => "delete",
_ => break 'fast (None, None, None),
};
p += 1;
while p < bytes.len() && (bytes[p] == b' ' || bytes[p] == b':') {
p += 1;
}
if p >= bytes.len() || bytes[p] != b'{' {
break 'fast (None, None, None);
}
// Extract optional _index and _id inside the inner object.
// Both are bare-quoted strings with no embedded quotes in
// the canonical bulk format produced by ES clients. The
// inner object itself may contain nested objects (e.g.
// `dynamic_templates:{...}`), so we track brace depth —
// a naive "first `}`" scan would truncate the inner slice
// at the first nested `}` and hide fields like `op_type`.
let inner_end = {
let mut j = p + 1;
let mut depth: i32 = 1;
let mut in_str = false;
while j < bytes.len() {
let c = bytes[j];
if in_str {
if c == b'\\' {
j += 2;
continue;
}
if c == b'"' {
in_str = false;
}
} else {
match c {
b'"' => in_str = true,
b'{' => depth += 1,
b'}' => {
depth -= 1;
if depth == 0 {
break;
}
}
_ => {}
}
}
j += 1;
}
if j >= bytes.len() {
break 'fast (None, None, None);
}
j
};
let inner = &bytes[p + 1..inner_end];
// #954: a backslash inside the action object can only be
// part of a string escape in valid JSON, and find_field
// below scans for the next raw '"' without unescaping —
// `{"_id":"a\"b"}` would yield `a\` and desync the rest of
// the line, collapsing distinct ids. Any escaped content
// (_id, _index, op_type alike) opts out of the fast path;
// the serde_json fallback below parses it correctly.
if inner.contains(&b'\\') {
break 'fast (None, None, None);
}
let find_field = |needle: &[u8]| -> Option<String> {
// Look for `"_key":"value"` (quoted) or `"_key":NUM`
// (numeric, e.g. `_id:1`) inside `inner`. ES bulk
// accepts both shapes — numeric ids are stringified at
// the coordinator. An empty quoted value is preserved
// as `Some(String::new())` so the caller can tell
// "key absent" from "key present, empty".
let mut i = 0;
while i + needle.len() <= inner.len() {
if &inner[i..i + needle.len()] == needle {
let mut j = i + needle.len();
while j < inner.len() && inner[j] != b':' {
j += 1;
}
j += 1;
while j < inner.len() && inner[j] == b' ' {
j += 1;
}
if j >= inner.len() {
return None;
}
if inner[j] == b'"' {
j += 1;
let v_start = j;
while j < inner.len() && inner[j] != b'"' {
j += 1;
}
return Some(
std::str::from_utf8(&inner[v_start..j]).ok()?.to_string(),
);
}
// Unquoted numeric id (e.g. `"_id":1`).
let v_start = j;
while j < inner.len()
&& (inner[j].is_ascii_digit()
|| inner[j] == b'-'
|| inner[j] == b'.')
{
j += 1;
}
if v_start == j {
return None;
}
return Some(
std::str::from_utf8(&inner[v_start..j]).ok()?.to_string(),
);
}
i += 1;
}
None
};
let idx_name = find_field(br#""_index""#);
let id = find_field(br#""_id""#);
// ES allows `{"index": {"op_type": "create", ...}}` as a shorthand
// for a `create` action; promote it so downstream treats it as create.
let op_type = find_field(br#""op_type""#);
let final_ty: &'static str =
if action_ty == "index" && op_type.as_deref() == Some("create") {
"create"
} else {
action_ty
};
(Some(final_ty), idx_name, id)
};
let (action_type, target_index, doc_id) = if let Some(ty) = action_type {
(ty, target_index, doc_id)
} else {
// Fallback: serde_json for non-canonical action lines.
// simd_json would need a mutable buffer (action_line is &str
// borrowed from the request body), forcing a per-action
// to_vec(). For the small action JSONs typical here (a few
// hundred bytes), serde_json's borrow-only path beats
// simd_json + allocation on the wall clock.
let action_val: Value = match serde_json::from_slice(action_line.as_bytes()) {
Ok(v) => v,
Err(e) => {
return ParseOutcome::Err(
BulkItemResult {
action: "unknown".into(),
index: default_index.unwrap_or("_unknown").to_string(),
id: String::new(),
status: 400,
result: None,
error: Some(format!("failed to parse action line: {e}")),
get_source: None,
},
*item_index,
);
}
};
let (a, meta) = if let Some(obj) = action_val.get("index") {
("index", obj)
} else if let Some(obj) = action_val.get("create") {
("create", obj)
} else if let Some(obj) = action_val.get("update") {
("update", obj)
} else if let Some(obj) = action_val.get("delete") {
("delete", obj)
} else {
return ParseOutcome::Err(
BulkItemResult {
action: "unknown".into(),
index: default_index.unwrap_or("_unknown").to_string(),
id: String::new(),
status: 400,
result: None,
error: Some("unknown action type".to_string()),
get_source: None,
},
*item_index,
);
};
let op_type_str = meta.get("op_type").and_then(Value::as_str);
let final_a: &'static str = if a == "index" && op_type_str == Some("create") {
"create"
} else {
a
};
require_alias_per_item = meta.get("require_alias").and_then(Value::as_bool);
pipeline_per_item = meta
.get("pipeline")
.and_then(Value::as_str)
.map(str::to_owned);
// Wire → internal seq translation: ES numbers seq_no
// from 0 on the wire, the internal WAL counter from 1.
// The CAS compare (index_document_with_version) runs on
// internal seqs, so a `_seq_no` captured from any read
// or write response round-trips through bulk CAS.
if_seq_no_per_item = meta
.get("if_seq_no")
.and_then(Value::as_u64)
.map(|s| s.saturating_add(1));
if_primary_term_per_item = meta.get("if_primary_term").and_then(Value::as_u64);
routing_per_item = meta
.get("routing")
.and_then(Value::as_str)
.map(str::to_owned);
source_req_per_item = meta.get("_source").cloned();
dynamic_templates_per_item = meta
.get("dynamic_templates")
.and_then(Value::as_object)
.map(|o| {
o.iter()
.filter_map(|(k, v)| v.as_str().map(|s| (k.clone(), s.to_string())))
.collect()
});
// ES bulk accepts `_id` as either a string or a number;
// numeric ids are stringified at the coordinating node.
let id_from_meta = meta.get("_id").and_then(|v| match v {
Value::String(s) => Some(s.clone()),
Value::Number(n) => Some(n.to_string()),
Value::Bool(b) => Some(b.to_string()),
_ => None,
});
(
final_a,
meta.get("_index")
.and_then(Value::as_str)
.map(str::to_owned),
id_from_meta,
)
};
let target_index = target_index
.or_else(|| default_index.map(str::to_owned))
.unwrap_or_else(|| "_unknown".to_string());
// ES rejects an explicit empty `_id` with an
// illegal_argument_exception per-item error. `_id` missing
// entirely still auto-generates; only the present-but-empty
// case is wrong.
if let Some(s) = doc_id.as_deref() {
if s.is_empty() {
return ParseOutcome::Err(
BulkItemResult {
action: action_type.to_string(),
index: target_index,
id: String::new(),
status: 400,
result: None,
error: Some("if _id is specified it must not be empty".to_string()),
get_source: None,
},
*item_index,
);
}
}
let (doc_body, doc_bytes) = if action_type != "delete" {
let dl = match doc_line {
Some(dl) => dl,
None => {
return ParseOutcome::Err(
BulkItemResult {
action: action_type.to_string(),
index: target_index,
id: doc_id.unwrap_or_default(),
status: 400,
result: None,
error: Some("missing document body".to_string()),
get_source: None,
},
*item_index,
);
}
};
// One document over the fixed ceiling is refused before
// `IgnoredAny`, `Value`, or tokenization. `Token` owns a
// `String` per word, and `panic = "abort"` dies on that
// allocation before the RSS governor samples (#1122).
// 413, not 429:
// the item is settled. Neighbours in the same bulk still
// index. A lone 413 is not the whole-request action-count
// refusal (`is_whole_request_too_large` requires more than
// one sent action).
if xerj_common::document_limit::indexed_document_too_large(dl.len()) {
return ParseOutcome::Err(
BulkItemResult {
action: action_type.to_string(),
index: target_index,
id: doc_id.unwrap_or_default(),
status: 413,
result: None,
error: Some(xerj_common::document_limit::indexed_document_refusal(
dl.len(),
)),
get_source: None,
},
*item_index,
);
}
// M5.11 — SKIP the doc-body JSON parse for `index`
// actions. The turbo-raw ingest path accepts the raw
// NDJSON bytes and defers the parse to drain-for-flush
// on a background thread, taking ~5 µs/doc off the HTTP
// worker's critical path. `update` and `create`
// actions still need the parsed Value because they
// take different code paths below — but `index` is
// the dominant one on ingest benchmarks.
//
// The bytes are still VALIDATED here (syntax + top-level
// object) via `IgnoredAny`, which walks the JSON without
// building a Value tree — no per-key String allocations,
// so the turbo win (skipping the tree build) is kept.
// Without this, a malformed doc line was deferred to the
// background parse whose `.unwrap_or({})` stored the doc
// as EMPTY `{}` while the response said 201/errors:false
// — silent data loss. ES rejects the item with a 400
// `document_parsing_exception` instead; mirror that.
if action_type == "index" {
if let Err(e) =
serde_json::from_slice::<serde::de::IgnoredAny>(dl.as_bytes())
{
return ParseOutcome::Err(
BulkItemResult {
action: action_type.to_string(),
index: target_index,
id: doc_id.clone().unwrap_or_default(),
status: 400,
result: None,
error: Some(malformed_document_reason(
doc_id.as_deref(),
*item_index,
&e,
)),
get_source: None,
},
*item_index,
);
}
// ES requires the doc body to be a JSON object;
// a bare array / scalar is rejected per-item
// (ES 8.13: `not_x_content_exception`; we report
// the same condition as a 400 parse error).
let is_object = dl
.as_bytes()
.iter()
.find(|b| !b" \t\r\n".contains(b))
.map(|b| *b == b'{')
.unwrap_or(false);
if !is_object {
return ParseOutcome::Err(
BulkItemResult {
action: action_type.to_string(),
index: target_index,
id: doc_id.unwrap_or_default(),
status: 400,
result: None,
error: Some(
"failed to parse: invalid document JSON: \
document body must be a JSON object"
.to_string(),
),
get_source: None,
},
*item_index,
);
}
// `IgnoredAny` above does not decode string escapes,
// so an unpaired UTF-16 surrogate (`"a\ud83db"`) slips
// through here but is rejected by the batch `Value`
// parse on the turbo-raw ingest path — failing every
// other document grouped with it (issue #1304). Reject
// it per-item now so ES's bulk contract holds: the one
// bad document errors and its neighbours still index.
if let Some(detail) = lone_surrogate_escape_reason(dl.as_bytes()) {
return ParseOutcome::Err(
BulkItemResult {
action: action_type.to_string(),
index: target_index,
id: doc_id.clone().unwrap_or_default(),
status: 400,
result: None,
error: Some(lone_surrogate_document_reason(
doc_id.as_deref(),
*item_index,
detail,
)),
get_source: None,
},
*item_index,
);
}
let bytes: std::sync::Arc<[u8]> = std::sync::Arc::from(dl.as_bytes());
(None, bytes)
} else {
// See action_line fallback above for why serde_json beats
// simd_json + to_vec() on small bulk doc lines.
match serde_json::from_slice::<Value>(dl.as_bytes()) {
Ok(v) => {
let bytes: std::sync::Arc<[u8]> =
std::sync::Arc::from(dl.as_bytes());
(Some(v), bytes)
}
Err(e) => {
return ParseOutcome::Err(
BulkItemResult {
action: action_type.to_string(),
index: target_index,
id: doc_id.clone().unwrap_or_default(),
status: 400,
result: None,
error: Some(malformed_document_reason(
doc_id.as_deref(),
*item_index,
&e,
)),
get_source: None,
},
*item_index,
);
}
}
}
} else {
// Delete action — we may have optimistically consumed
// a line during pair building that actually belongs to
// the NEXT action. Signal the caller to pop it back
// into the input stream.
let skip_back = if doc_line.is_some() { 1usize } else { 0usize };
let action = ParsedAction {
action_type: action_type.to_string(),
target_index,
doc_id,
doc_body: None,
doc_bytes: std::sync::Arc::from(&[][..]),
item_index: *item_index,
require_alias: require_alias_per_item,
pipeline: pipeline_per_item.clone(),
if_seq_no: if_seq_no_per_item,
if_primary_term: if_primary_term_per_item,
routing: routing_per_item.clone(),
source_req: source_req_per_item.clone(),
dynamic_templates: dynamic_templates_per_item.clone(),
};
if skip_back > 0 {
// We need to signal that the "body" we consumed
// was actually a new action line — but with a
// parallel parse this is hard because lines are
// not in order. For now, fall back to the
// serial path for delete-heavy batches.
// In practice nginx log ingest has ZERO deletes,
// so this branch is cold.
return ParseOutcome::Ok(action);
}
return ParseOutcome::Ok(action);
};
// For update actions, the request may put `_source` on the
// doc body rather than the action meta
// (`{_source: true, doc: {...}}`). Honor that too.
let source_req_final = source_req_per_item.or_else(|| {
if action_type == "update" {
doc_body.as_ref().and_then(|b| b.get("_source").cloned())
} else {
None
}
});
ParseOutcome::Ok(ParsedAction {
action_type: action_type.to_string(),
target_index,
doc_id,
doc_body,
doc_bytes,
item_index: *item_index,
require_alias: require_alias_per_item,
pipeline: pipeline_per_item,
if_seq_no: if_seq_no_per_item,
if_primary_term: if_primary_term_per_item,
routing: routing_per_item,
source_req: source_req_final,
dynamic_templates: dynamic_templates_per_item,
})
})
.collect()
});
let parse_ms = t_parse.elapsed().as_millis() as u64;
// The parse buffers now exist and are visible to the RSS sampler; each
// write path takes its own analyze reservation for the token spike.
drop(parse_reservation);
let t_group = std::time::Instant::now();
let mut parsed: Vec<ParsedAction> = Vec::with_capacity(parse_results.len());
for outcome in parse_results {
match outcome {
ParseOutcome::Ok(a) => parsed.push(a),
ParseOutcome::Err(err_item, item_idx) => {
items[item_idx] = Some(err_item);
errors = true;
}
}
}
// ── Effective ingest pipeline per item ──────────────────────────────────
//
// Elasticsearch resolves the pipeline for a bulk `index`/`create` action in
// this order, and so does xerj now:
//
// 1. the action's own `"pipeline"` metadata key
// 2. the request's `?pipeline=` query parameter
// 3. the target index's `index.default_pipeline` setting
//
// and `_none` at either of the first two levels disables the setting.
//
// Issue #204: only step 1 existed here. `POST /_bulk?pipeline=redact` and
// an index carrying `index.default_pipeline` both answered `201` per item
// and stored the document UNTRANSFORMED — no error, no log line — while
// `PUT /{index}/_doc/{id}?pipeline=redact` ran the pipeline and refused
// when it could not. One instruction, two answers, and the silent one was
// the high-volume path.
//
// Resolving here, before the existence check below and before the
// turbo-path partition (which diverts any action carrying a pipeline),
// means the rest of this function needs no further change: an unknown or
// unrunnable name fails the item exactly as an explicit one always did.
for action in parsed.iter_mut() {
if !matches!(action.action_type.as_str(), "index" | "create") {
// `update` and `delete` never carry a source body through a
// pipeline, in ES or here.
continue;
}
let explicit = action
.pipeline
.as_deref()
.or(opts.default_pipeline.as_deref());
action.pipeline = match explicit {
Some("_none") => None,
Some(p) => Some(p.to_string()),
None => engine.default_pipeline_for(&action.target_index),
};
}
// ── Per-item validation: pipeline existence ─────────────────────────────
//
// The effective pipeline resolved above must name a registered ingest
// pipeline; otherwise ES fails the item with
// `illegal_argument_exception: pipeline with id [...] does not exist`.
parsed.retain(|action| {
if let Some(pid) = action.pipeline.as_deref() {
if !engine.pipelines.contains_key(pid) {
items[action.item_index] = Some(BulkItemResult {
action: action.action_type.clone(),
index: action.target_index.clone(),
id: action.doc_id.clone().unwrap_or_default(),
status: 400,
result: None,
error: Some(format!("pipeline with id [{pid}] does not exist")),
get_source: None,
});
errors = true;
return false;
}
}
true
});
// ── Per-item validation: require_alias + ambiguous-alias write target ─────
//
// ES rejects an item when `require_alias=true` (per-item or URL-default)
// and the target is not a registered alias. It also rejects writes to an
// alias that has more than one backing index unless one is designated as
// the write index via `is_write_index:true` in the alias metadata.
let url_require_alias = opts.require_alias.unwrap_or(false);
let default_source_req = opts.default_source_req.clone();
parsed.retain_mut(|action| {
let eff_require_alias = action.require_alias.unwrap_or(url_require_alias);
let target = action.target_index.clone();
let is_alias = engine.aliases.contains_key(&target);
if eff_require_alias && !is_alias {
items[action.item_index] = Some(BulkItemResult {
action: action.action_type.clone(),
index: target.clone(),
id: action.doc_id.clone().unwrap_or_default(),
status: 404,
result: None,
error: Some(format!(
"no such index [{target}] and [require_alias] request flag is [true] and [{target}] is not an alias"
)),
get_source: None,
});
errors = true;
return false;
}
if is_alias {
// One write-target definition for every write path: a single
// backing index or exactly one `is_write_index:true`. The old code
// only checked that SOME write index existed and then left the
// target as the alias, so `get_or_create_index` wrote to the FIRST
// backing index and ignored the designation.
match engine.write_target(&target) {
Ok(Some(concrete)) => action.target_index = concrete,
Ok(None) => {}
Err(reason) => {
items[action.item_index] = Some(BulkItemResult {
action: action.action_type.clone(),
index: target.clone(),
id: action.doc_id.clone().unwrap_or_default(),
status: 400,
result: None,
error: Some(reason),
get_source: None,
});
errors = true;
return false;
}
}
}
true
});
// ── Turbo path: batch pure `index` ops per index ─────────────────────────
//
// `index` actions always overwrite — safe to batch via index_batch_turbo().
// `create` actions must fail with 409 if the doc already exists, so they
// are executed individually below (along with update/delete).
//
// Group `index`-only ops by target index. **CONSUMES** `parsed` — the
// previous version borrowed and then cloned `action.doc_body` (a full
// `serde_json::Value` deep-clone) into the batch, which on a 60-field
// nginx doc was ~60 allocations per document * 55 k docs/s = 3.3 M
// allocs/s of pure waste. Now we drain `parsed` by value and move the
// Value straight into the batch.
// M5.11 — index actions carry only `(item_index, doc_id, doc_bytes)`.
// The parsed `Value` is never built for index actions on this path.
let mut index_batches: HashMap<String, Vec<(usize, String, std::sync::Arc<[u8]>)>> =
HashMap::new();
// AUTO-ID plain-index actions (no explicit `_id`). These are
// guaranteed new — they can NEVER overwrite — so every one is a
// "created"/201. That makes them safe to push through the single
// `index_batch_turbo_raw` batch call, whose response is hardcoded
// to "created". Explicit-id index actions stay in `index_batches`
// and run the per-doc loop because they may overwrite and so need
// created-vs-updated / 201-vs-200 semantics turbo can't express.
let mut auto_id_batches: HashMap<String, Vec<(usize, String, std::sync::Arc<[u8]>)>> =
HashMap::new();
let mut semantic_index_batches: HashMap<
String,
Vec<(usize, Option<String>, std::sync::Arc<[u8]>)>,
> = HashMap::new();
let mut non_index_actions: Vec<ParsedAction> = Vec::new();
// Precompute which target indices declare any strict-format date
// fields — those need per-doc date-format validation before the
// doc is accepted. Actions targeting those indices go through the
// slow path so the validation loop below can see them.
let mut index_needs_date_validation: HashMap<String, bool> = HashMap::new();
let index_has_strict_date = |target: &str, cache: &mut HashMap<String, bool>| -> bool {
if let Some(b) = cache.get(target) {
return *b;
}
let has = engine
.index_mappings
.get(target)
.map(|m| {
let props = m.get("properties").cloned().or_else(|| {
m.get("mappings")
.and_then(|mm| mm.get("properties"))
.cloned()
});
mapping_has_strict_date(&props.unwrap_or(Value::Null))
})
.unwrap_or(false);
cache.insert(target.to_string(), has);
has
};
// Same gate for dynamic-templates with `copy_to`: the ingest
// loop below materialises the copy into the doc body so the
// stored source reflects it. The turbo path skips doc parsing,
// so route those actions through the slow path.
let mut index_needs_dynamic_copy: HashMap<String, bool> = HashMap::new();
let index_has_dynamic_copy = |target: &str, cache: &mut HashMap<String, bool>| -> bool {
if let Some(b) = cache.get(target) {
return *b;
}
let has = engine
.index_mappings
.get(target)
.map(|m| {
let tmpls = m
.get("mappings")
.and_then(|mm| mm.get("dynamic_templates"))
.or_else(|| m.get("dynamic_templates"));
tmpls
.and_then(Value::as_array)
.map(|arr| {
arr.iter().any(|v| {
v.as_object()
.and_then(|o| o.iter().next())
.map(|(_, body)| {
body.get("mapping")
.and_then(|mm| mm.get("copy_to"))
.is_some()
})
.unwrap_or(false)
})
})
.unwrap_or(false)
})
.unwrap_or(false);
cache.insert(target.to_string(), has);
has
};
// Same gate for `semantic_text` fields: those auto-embed on ingest,
// which only the per-doc path does. The turbo auto-id batch path
// stores raw bytes and never embeds, so auto-id bulk docs into a
// semantic_text index would land unvectorised and `semantic`/`knn`
// search would silently return nothing. Route them through the slow
// path so `apply_semantic_embeddings` runs.
let mut index_needs_embedding: HashMap<String, bool> = HashMap::new();
let index_has_embedding = |target: &str, cache: &mut HashMap<String, bool>| -> bool {
if let Some(b) = cache.get(target) {
return *b;
}
let has = engine
.index_mappings
.get(target)
.map(|m| {
let props = m.get("properties").cloned().or_else(|| {
m.get("mappings")
.and_then(|mm| mm.get("properties"))
.cloned()
});
mapping_has_semantic_text(&props.unwrap_or(Value::Null))
})
.unwrap_or(false)
// The index does not exist yet. A matching template's
// `semantic_text` is applied by the auto-create this batch is
// about to do; classifying from the absent mapping sent the
// first write down the turbo path, which never embeds (#2281).
|| engine.absent_index_template_has_semantic_text(target);
cache.insert(target.to_string(), has);
has
};
// Same gate for numeric / boolean field types (issue #781). Unlike the
// three above this does NOT divert to the slow path — that would cost
// every mapped-numeric index the turbo batch — it coerces the raw doc
// bytes in place right here and lets the action stay on turbo. The gate
// exists so an index with no numeric or boolean field never pays for the
// parse at all.
//
// The cache carries the PROPERTIES MAP, not just the boolean gate:
// `mapping_properties(...).cloned()` deep-copies the whole properties
// blob, and reading it per action would put an O(mapping) copy on the HTTP
// worker for every document in the batch — the cost M5.11 took off this
// path. Behind an `Arc` the per-action price is a refcount bump, and both
// enforcement sites (partition loop and per-item loop) share the one
// cache. `None` means "this index needs no check" — an unmapped index, or
// one whose mapping declares no numeric/boolean field.
type CoerceProps = Option<std::sync::Arc<serde_json::Map<String, Value>>>;
let mut index_type_check_props: HashMap<String, CoerceProps> = HashMap::new();
let typed_numeric_props =
|target: &str, cache: &mut HashMap<String, CoerceProps>| -> CoerceProps {
if let Some(p) = cache.get(target) {
return p.clone();
}
let props: CoerceProps = engine.index_mappings.get(target).and_then(|m| {
if !xerj_common::field_coercion::mapping_has_enforced_types(&m) {
return None;
}
xerj_common::field_coercion::mapping_properties(&m)
.cloned()
.map(std::sync::Arc::new)
});
cache.insert(target.to_string(), props.clone());
props
};
// A bulk body is an ordered log: ES applies its items in request order,
// so `delete 1` followed by `index 1` leaves the doc present, and
// `index 1 {v:1}`, `delete 1`, `index 1 {v:2}` leaves `{v:2}`. The
// partition below runs its groups as phases (semantic, then turbo
// index, then everything else), which reorders items across groups.
// That is harmless while each `(index, _id)` lives in one group, but a
// key that a non-turbo action (delete / update / create / CAS / routed
// index) also touches would see its plain `index` items jump ahead and
// the later delete win — the doc is gone and every item said success.
// Collect those keys up front and keep all of their items on the
// sequential path, which executes in request order.
let sequential_keys: std::collections::HashSet<(String, String)> = parsed
.iter()
.filter(|a| {
a.action_type != "index"
|| a.if_seq_no.is_some()
|| a.if_primary_term.is_some()
|| a.routing.is_some()
|| a.dynamic_templates.is_some()
|| a.pipeline.is_some()
})
.filter_map(|a| {
a.doc_id
.as_ref()
.map(|id| (a.target_index.clone(), id.clone()))
})
.collect();
for mut action in parsed {
// ── Numeric / boolean type enforcement (issue #781) ──────────────
//
// A field mapped `integer` used to keep whatever arrived — `1.9`,
// `9999999999`, `"abc"`, even an object — so `range {gte: 1.5}`
// matched a doc that ES stores as `1` and `term {i: 1}` missed it.
// Values ES coerces are coerced here (`1.9` → `1`, `"5"` → `5`,
// `"true"` → `true`); values ES refuses become a per-item 400
// `document_parsing_exception`, like the date-format check below.
//
// Runs at partition time so it covers the turbo batch path as well
// as the per-item loop. Actions carrying a pipeline are skipped: ES
// runs the pipeline before parsing the document, so those are
// checked after their pipeline in the per-item loop instead.
// `update` merges into a doc that was already validated on write.
if matches!(action.action_type.as_str(), "index" | "create") && action.pipeline.is_none() {
let props = typed_numeric_props(&action.target_index, &mut index_type_check_props);
if let Some(props) = props {
// `index` actions defer the JSON parse to the turbo path, so
// the body may not be built yet — parse it here, and only
// pay the re-serialize when a value actually changed.
let parsed_body = match action.doc_body.take() {
Some(Value::Object(o)) => Some(o),
Some(other) => {
action.doc_body = Some(other);
None
}
None => match serde_json::from_slice::<Value>(&action.doc_bytes) {
Ok(Value::Object(o)) => Some(o),
_ => None,
},
};
if let Some(mut body) = parsed_body {
match xerj_common::field_coercion::coerce_document(&mut body, &props) {
Ok(changed) => {
// Serialize from the map itself, not a clone of
// it — `preserve_order` is on workspace-wide, so
// the caller's `_source` key order survives.
if changed {
if let Ok(bytes) = serde_json::to_vec(&body) {
action.doc_bytes = std::sync::Arc::from(bytes.as_slice());
}
}
action.doc_body = Some(Value::Object(body));
}
Err(bad) => {
items[action.item_index] = Some(BulkItemResult {
action: action.action_type.clone(),
index: action.target_index.clone(),
id: action.doc_id.clone().unwrap_or_default(),
status: 400,
result: None,
error: Some(bad.reason(&action.doc_id.clone().unwrap_or_default())),
get_source: None,
});
errors = true;
continue;
}
}
}
}
}
// `index` with no `if_seq_no` / `routing` goes through the
// turbo batch path. Actions that carry CAS or routing metadata
// must be executed individually so we can honor them — route
// them through the non-index path. Also divert when the index
// has date fields with a strict `format`, so the per-item
// validation loop can reject malformed values like ES does.
let has_strict_date =
index_has_strict_date(&action.target_index, &mut index_needs_date_validation);
let has_dynamic_copy =
index_has_dynamic_copy(&action.target_index, &mut index_needs_dynamic_copy);
let has_embedding = index_has_embedding(&action.target_index, &mut index_needs_embedding);
let has_plain_metadata = action.action_type == "index"
&& action.if_seq_no.is_none()
&& action.if_primary_term.is_none()
&& action.routing.is_none()
&& action.dynamic_templates.is_none()
&& action.pipeline.is_none()
&& !has_strict_date
&& !has_dynamic_copy
&& (sequential_keys.is_empty()
|| !action.doc_id.as_ref().is_some_and(|id| {
sequential_keys.contains(&(action.target_index.clone(), id.clone()))
}));
let is_plain_index = has_plain_metadata && !has_embedding;
if is_plain_index {
match action.doc_id {
None => {
// Auto-id: brand-new doc, always "created"/201. Route the
// whole group through ONE `index_batch_turbo_raw` call.
let id = uuid::Uuid::new_v4().to_string();
auto_id_batches
.entry(action.target_index)
.or_default()
.push((action.item_index, id, action.doc_bytes));
}
Some(id) => {
// Explicit id: may overwrite → keep the per-doc path so
// created/updated + 201/200 is resolved correctly.
index_batches.entry(action.target_index).or_default().push((
action.item_index,
id,
action.doc_bytes,
));
}
}
} else if has_plain_metadata && has_embedding {
semantic_index_batches
.entry(action.target_index)
.or_default()
.push((action.item_index, action.doc_id, action.doc_bytes));
} else {
non_index_actions.push(action);
}
}
let parsed = non_index_actions;
let group_ms = t_group.elapsed().as_millis() as u64;
let t_exec = std::time::Instant::now();
// ── semantic_text index actions: cross-document embedding windows ────
//
// Parse and prepare a target-index group together so the embedder sees
// useful multi-document windows. The normal per-document index method is
// still used after preparation; it observes the supplied companion vector
// and therefore preserves WAL, overwrite status, response ordering, and
// item-level errors.
let mut semantic_raw_memory = crate::ingest_memory::enabled().then(
std::collections::HashMap::<usize, (usize, crate::ingest_memory::Retained<'static>)>::new,
);
if let Some(raw_memory) = semantic_raw_memory.as_mut() {
for batch in semantic_index_batches.values() {
for (_, _, source) in batch {
let owner = std::sync::Arc::as_ptr(source) as *const () as usize;
raw_memory
.entry(owner)
.and_modify(|(remaining, _)| *remaining += 1)
.or_insert_with(|| {
(
1usize,
crate::ingest_memory::Retained::new(
crate::ingest_memory::Category::RawSource,
source.len(),
),
)
});
}
}
}
for (index_name, batch) in semantic_index_batches {
#[cfg(test)]
let _ = semantic_lifecycle_hook(&index_name, SemanticLifecyclePoint::Grouped);
let idx = match engine.get_or_create_index(&index_name) {
Ok(i) => i,
Err(e) => {
for (item_idx, id, source) in batch {
if let Some(raw_memory) = semantic_raw_memory.as_mut() {
release_raw_owner(raw_memory, source);
} else {
drop(source);
}
items[item_idx] = Some(BulkItemResult {
action: "index".into(),
index: index_name.clone(),
id: id.unwrap_or_default(),
status: 500,
result: None,
error: Some(e.to_string()),
get_source: None,
});
errors = true;
}
continue;
}
};
let vector_fields = if crate::ingest_memory::enabled() {
#[cfg(test)]
count_disabled_semantic_access(|counters| &counters.schema_reads);
idx.semantic_vector_fields().await
} else {
std::collections::HashSet::new()
};
let mut valid_meta = Vec::with_capacity(batch.len());
let mut valid_sources = Vec::with_capacity(batch.len());
let mut valid_memory = crate::ingest_memory::enabled().then(|| {
#[cfg(test)]
count_disabled_semantic_access(|counters| &counters.guard_vectors);
Vec::with_capacity(batch.len())
});
for (item_idx, id, bytes) in batch {
let parsed = serde_json::from_slice::<Value>(&bytes);
match parsed {
Ok(source) => {
if let Some(valid_memory) = valid_memory.as_mut() {
#[cfg(test)]
count_disabled_semantic_access(|counters| &counters.sizing_walks);
let parsed_document = crate::ingest_memory::Retained::new(
crate::ingest_memory::Category::ParsedSource,
crate::ingest_memory::estimated_json_heap_excluding(
&source,
&vector_fields,
),
);
let parsed_vector = crate::ingest_memory::Retained::new(
crate::ingest_memory::Category::ParsedVector,
crate::ingest_memory::vector_value_capacity(&source, &vector_fields),
);
valid_memory.push((parsed_document, parsed_vector));
}
if let Some(raw_memory) = semantic_raw_memory.as_mut() {
release_raw_owner(raw_memory, bytes);
} else {
drop(bytes);
}
valid_meta.push((item_idx, id));
valid_sources.push(source);
}
Err(e) => {
if let Some(raw_memory) = semantic_raw_memory.as_mut() {
release_raw_owner(raw_memory, bytes);
} else {
drop(bytes);
}
items[item_idx] = Some(BulkItemResult {
action: "index".into(),
index: index_name.clone(),
id: id.unwrap_or_default(),
status: 400,
result: None,
error: Some(format!("failed to parse: invalid document JSON: {e}")),
get_source: None,
});
errors = true;
}
}
}
#[cfg(test)]
let _ = semantic_lifecycle_hook(&index_name, SemanticLifecyclePoint::Parsed);
// Backend-owned chunk strings, tokenizer tensors, and inference
// scratch are not yet logically attributed. Their effect remains
// visible only as allocator/RSS physical delta; it is not zero.
let prepared = idx.apply_semantic_embeddings_batch(valid_sources).await;
#[cfg(test)]
let _ = semantic_lifecycle_hook(&index_name, SemanticLifecyclePoint::Prepared);
// #2427: without ingest-memory tracing nothing is accounted per
// document, so publish the prepared group as one batch instead of
// one `index_document_prepared` call per document. The tracing mode
// (and its lifecycle tests) keeps the sequential path so each
// prepared document's ownership is still released as it publishes.
if valid_memory.is_none() && !semantic_lifecycle_hook_installed(&index_name) {
let docs = valid_meta
.into_iter()
.zip(prepared)
.map(|((item_idx, id), prepared)| (item_idx, id.unwrap_or_default(), prepared))
.collect();
errors |= publish_prepared_batch(&idx, &index_name, docs, &mut items).await;
continue;
}
let mut valid_memory = valid_memory.map(Vec::into_iter);
for ((item_idx, id), prepared_source) in valid_meta.into_iter().zip(prepared) {
let memory = valid_memory.as_mut().and_then(Iterator::next);
let (source, prepared_memory) = match prepared_source {
Ok(source) => {
let prepared_memory = if let Some((parsed_document, parsed_vector)) = memory {
#[cfg(test)]
count_disabled_semantic_access(|counters| &counters.sizing_walks);
let prepared_document_bytes =
crate::ingest_memory::estimated_json_heap_excluding(
&source,
&vector_fields,
);
let prepared_vector_bytes =
crate::ingest_memory::vector_value_capacity(&source, &vector_fields);
Some(crate::ingest_memory::Retained::replace_pair(
parsed_document,
parsed_vector,
(
crate::ingest_memory::Category::PreparedDocument,
prepared_document_bytes,
),
(
crate::ingest_memory::Category::PreparedVector,
prepared_vector_bytes,
),
))
} else {
None
};
(source, prepared_memory)
}
Err(e) => {
drop(memory);
let status = engine_error_http_status(&e);
items[item_idx] = Some(BulkItemResult {
action: "index".into(),
index: index_name.clone(),
id: id.unwrap_or_default(),
status,
result: None,
error: Some(e.to_string()),
get_source: None,
});
errors = true;
continue;
}
};
let error_id = id.clone().unwrap_or_default();
#[cfg(test)]
let _ = semantic_lifecycle_hook(&index_name, SemanticLifecyclePoint::BeforePublication);
let publication = idx.index_document_prepared(id, source).await;
drop(prepared_memory);
#[cfg(test)]
let _ = semantic_lifecycle_hook(&index_name, SemanticLifecyclePoint::AfterPublication);
match publication {
Ok(resp) => {
let status = if resp.result == "updated" { 200 } else { 201 };
items[item_idx] = Some(BulkItemResult {
action: "index".into(),
index: index_name.clone(),
id: resp.id,
status,
result: Some(resp.result),
error: None,
get_source: None,
});
}
Err(e) => {
let status = engine_error_http_status(&e);
items[item_idx] = Some(BulkItemResult {
action: "index".into(),
index: index_name.clone(),
id: error_id,
status,
result: None,
error: Some(e.to_string()),
get_source: None,
});
errors = true;
}
}
}
}
// ── Auto-id index actions: ONE turbo batch per target index ──────────
//
// `index_batch_turbo_raw` appends the whole group with a single WAL
// batch + one parsed FTS-memtable insert per doc (the now-correct,
// single-representation path). It returns one `IndexResponse` per
// input doc IN ORDER, so we map them straight back onto the item
// slots — all 201/"created" since auto-id docs can't overwrite.
for (index_name, batch) in auto_id_batches {
let idx = match engine.get_or_create_index(&index_name) {
Ok(i) => i,
Err(e) => {
for (item_idx, id, _) in batch {
items[item_idx] = Some(BulkItemResult {
action: "index".into(),
index: index_name.clone(),
id,
status: 500,
result: None,
error: Some(e.to_string()),
get_source: None,
});
errors = true;
}
continue;
}
};
// Keep item indices parallel to the docs we hand to turbo so we
// can re-associate responses (turbo preserves input order).
let item_indices: Vec<usize> = batch.iter().map(|(i, _, _)| *i).collect();
let turbo_docs: Vec<(String, std::sync::Arc<[u8]>)> = batch
.into_iter()
.map(|(_, id, bytes)| (id, bytes))
.collect();
match idx.index_batch_turbo_raw(turbo_docs).await {
Ok(responses) => {
for (k, resp) in responses.into_iter().enumerate() {
let item_idx = item_indices[k];
items[item_idx] = Some(BulkItemResult {
action: "index".into(),
index: index_name.clone(),
id: resp.id,
status: 201,
result: Some("created".into()),
error: None,
get_source: None,
});
}
}
Err(e) => {
// Whole-batch failure (e.g. ResourceExhausted → 429):
// mark every item in the batch with the same status.
let status = engine_error_http_status(&e);
for item_idx in item_indices {
items[item_idx] = Some(BulkItemResult {
action: "index".into(),
index: index_name.clone(),
id: String::new(),
status,
result: None,
error: Some(e.to_string()),
get_source: None,
});
}
errors = true;
}
}
}
// Execute turbo batches (index-only).
for (index_name, batch) in index_batches {
let idx = match engine.get_or_create_index(&index_name) {
Ok(i) => i,
Err(e) => {
for (item_idx, id, _) in batch {
items[item_idx] = Some(BulkItemResult {
action: "index".into(),
index: index_name.clone(),
id,
status: 500,
result: None,
error: Some(e.to_string()),
get_source: None,
});
errors = true;
}
continue;
}
};
// #2427: publish the whole explicit-id group as one batch. The
// per-document `index_document` loop this replaces held the WAL lock,
// copied the source into the storage memtable, and opened a
// publication bracket once per document; eight concurrent bulks
// used about two cores. `index_batch_explicit_ids_raw` keeps the
// per-doc answers (`created`/`updated`, `_version`, date errors).
//
// An index created from a native schema can carry embedding fields
// without a `semantic_text` mapping, so the partition above calls it
// plain. `index_document` embedded those documents itself; prepare
// them here in one shared pass before the batch publication.
if !idx.semantic_vector_fields().await.is_empty() {
let mut meta = Vec::with_capacity(batch.len());
let mut sources = Vec::with_capacity(batch.len());
for (item_idx, doc_id, doc_bytes) in batch {
match serde_json::from_slice::<Value>(&doc_bytes) {
Ok(source) => {
meta.push((item_idx, doc_id));
sources.push(source);
}
Err(e) => {
items[item_idx] = Some(BulkItemResult {
action: "index".into(),
index: index_name.clone(),
id: doc_id,
status: 400,
result: None,
error: Some(format!("failed to parse: invalid document JSON: {e}")),
get_source: None,
});
errors = true;
}
}
}
let prepared = idx.apply_semantic_embeddings_batch(sources).await;
let docs = meta
.into_iter()
.zip(prepared)
.map(|((item_idx, id), prepared)| (item_idx, id, prepared))
.collect();
errors |= publish_prepared_batch(&idx, &index_name, docs, &mut items).await;
continue;
}
let docs = batch
.into_iter()
.map(|(item_idx, doc_id, doc_bytes)| {
let doc_id = if doc_id.is_empty() {
uuid::Uuid::new_v4().to_string()
} else {
doc_id
};
(item_idx, doc_id, doc_bytes)
})
.collect();
errors |= publish_explicit_id_batch(&idx, &index_name, docs, &mut items).await;
}
// Execute non-index ops individually (create, update, delete).
// `create` / `update` / `delete` — executed individually. `parsed` here
// has already been filtered to non-`index` actions by the turbo-batch
// partition above, so the match arms no longer need an `"index" => {}`
// no-op branch. We consume `parsed` by value to avoid per-action
// deep-clones of `doc_id` (String) and `doc_body` (Value tree).
for action in parsed {
let ParsedAction {
action_type,
target_index,
doc_id,
doc_body,
doc_bytes,
item_index: item_idx,
require_alias: _,
pipeline,
if_seq_no,
if_primary_term,
routing,
source_req,
dynamic_templates,
} = action;
let error_id = doc_id.clone().unwrap_or_default();
let target_index_for_get = target_index.clone();
let doc_id_for_get = doc_id.clone();
// Ensure we have the doc body parsed before validating — our
// dynamic-templates check needs `doc_body.contains_key(field)`
// to tell "spec applies to this doc" from "spec references a
// field not even present". The turbo-index partition skipped
// parsing; do it here if needed.
let mut doc_body = doc_body.or_else(|| {
if action_type == "index" && !doc_bytes.is_empty() {
// doc_bytes is Arc<[u8]> — mutating it would invalidate
// sibling clones, so simd_json (which mutates in-place)
// forced a per-doc to_vec(). serde_json takes &[u8]
// immutably and avoids the allocation entirely.
serde_json::from_slice::<Value>(&doc_bytes).ok()
} else {
None
}
});
// ── Ingest pipeline execution ───────────────────────────────────
//
// ES runs the item's ingest pipeline BEFORE field mapping,
// `copy_to`, and date / dynamic-template validation, so we apply
// it here — right after the doc body is parsed. Only `index` /
// `create` carry a source body through a pipeline (`update` /
// `delete` never do). Unknown pipeline names were already rejected
// as per-item 400s in the pre-partition validation pass above, so a
// lookup miss here is defensive only — mirror the same error.
if let Some(pid) = pipeline.as_deref() {
if matches!(action_type.as_str(), "index" | "create") {
let input = doc_body
.clone()
.unwrap_or_else(|| Value::Object(serde_json::Map::new()));
match engine.process_through_pipeline(pid, vec![input]) {
Ok(mut results) if !results.is_empty() => {
let (p_action, transformed) = results.remove(0);
if matches!(p_action, xerj_wasm::pipeline::ProcessAction::Drop) {
// Pipeline dropped the doc: ES reports a
// successful no-op and does not index it.
items[item_idx] = Some(BulkItemResult {
action: action_type.to_string(),
index: target_index.clone(),
id: error_id.clone(),
status: 200,
result: Some("noop".into()),
error: None,
get_source: None,
});
continue;
}
doc_body = Some(transformed);
}
// No output for this document. `process_through_pipeline`
// zips one action per input, so this is an internal
// invariant break — but it must not fall through to
// indexing the ORIGINAL body, which is the silent
// pass-through issue #204 is about. Fail the item.
Ok(_) => {
items[item_idx] = Some(BulkItemResult {
action: action_type.to_string(),
index: target_index.clone(),
id: error_id.clone(),
status: 400,
result: None,
error: Some(format!("pipeline with id [{pid}] returned no document")),
get_source: None,
});
errors = true;
continue;
}
Err(e) => {
// A genuinely absent pipeline keeps ES's exact wording
// (the conformance suite asserts it). A pipeline that
// IS registered but carries a processor this build
// cannot run reports that instead — issue #204: telling
// an operator a pipeline "does not exist" when
// `GET /_ingest/pipeline` plainly returns it sends them
// hunting for the wrong problem.
let reason = match &e {
xerj_wasm::WasmError::PipelineNotRunnable { .. } => e.to_string(),
_ => format!("pipeline with id [{pid}] does not exist"),
};
items[item_idx] = Some(BulkItemResult {
action: action_type.to_string(),
index: target_index.clone(),
id: error_id.clone(),
status: 400,
result: None,
error: Some(reason),
get_source: None,
});
errors = true;
continue;
}
}
}
}
// Apply dynamic-template `copy_to` at ingest. When a doc
// field name matches a dynamic template's `match` pattern
// (or equals the template name) and the template's mapping
// carries `copy_to`, ES silently copies the value into the
// target field. Our search-time `apply_copy_to` only walks
// the declared schema — it doesn't see dynamic templates —
// so we materialise the copy into the doc body before it's
// stored. This fixes the copy_to cluster in
// `20_synthetic_source.yml` without requiring full dynamic
// mapping persistence.
if matches!(action_type.as_str(), "index" | "create") {
if let Some(body) = doc_body.as_mut().and_then(|v| v.as_object_mut()) {
let mapping = engine.index_mappings.get(&target_index).map(|v| v.clone());
apply_dynamic_template_copy_to(body, mapping.as_ref(), dynamic_templates.as_ref());
}
}
// Dynamic-templates validation: if the action specifies any
// per-field `dynamic_templates: {field: tmpl_name}`, the
// referenced template must exist in the target index's
// mapping. Unknown names produce a per-item 400
// `document_parsing_exception` in ES.
if let Some(dt_map) = &dynamic_templates {
if !dt_map.is_empty() {
let mapping = engine.index_mappings.get(&target_index).map(|v| v.clone());
// Collect per-template (name, match_pattern) so we can
// test whether the field name would match ANY declared
// template's pattern. ES accepts a dynamic_templates
// spec on a field when either (a) the named template
// exists, or (b) the field already has a concrete
// mapping, or (c) the field matches some template's
// `match` pattern (ES would silently apply that
// template instead).
let templates: Vec<(String, Option<String>)> = mapping
.as_ref()
.and_then(|m| {
m.get("mappings")
.and_then(|mm| mm.get("dynamic_templates"))
.or_else(|| m.get("dynamic_templates"))
})
.and_then(Value::as_array)
.map(|arr| {
arr.iter()
.filter_map(|v| {
v.as_object().and_then(|o| {
let (name, spec) = o.iter().next()?;
let pattern =
spec.get("match").and_then(Value::as_str).map(String::from);
Some((name.clone(), pattern))
})
})
.collect()
})
.unwrap_or_default();
let declared_names: std::collections::HashSet<String> =
templates.iter().map(|(n, _)| n.clone()).collect();
let declared_fields: std::collections::HashSet<String> = mapping
.as_ref()
.and_then(|m| {
m.get("mappings")
.and_then(|mm| mm.get("properties"))
.or_else(|| m.get("properties"))
})
.and_then(Value::as_object)
.map(|o| o.keys().cloned().collect())
.unwrap_or_default();
let field_matches_any_template = |field: &str| -> bool {
templates.iter().any(|(name, pattern)| {
if let Some(pat) = pattern {
// Simple `*`-glob matching.
let p_bytes = pat.as_bytes();
let f_bytes = field.as_bytes();
simple_glob_matches(p_bytes, f_bytes)
} else {
// No pattern — the template default is a
// name-matching rule: field must equal the
// template's name.
field == name.as_str()
}
})
};
let mut first_bad: Option<(String, String)> = None;
for (field, tmpl) in dt_map {
let present_in_doc = doc_body
.as_ref()
.map(|db| {
db.as_object()
.map(|o| o.contains_key(field))
.unwrap_or(false)
})
.unwrap_or(true);
if declared_fields.contains(field) {
continue;
}
if !present_in_doc {
continue;
}
if declared_names.contains(tmpl) {
continue;
}
// Fall back: the field might be implicitly mapped by
// a pattern-matching template (e.g. `match: "my*"`).
if field_matches_any_template(field) {
continue;
}
first_bad = Some((field.clone(), tmpl.clone()));
break;
}
// Type-compatibility pass: when the caller's
// `dynamic_templates: {foo: string}` maps a scalar
// type (keyword/text/long/…) but the doc carries
// dotted keys `foo.*` that would implicitly make
// `foo` an object, ES rejects with
// `failed to parse field [foo] of type [TYPE]`.
if first_bad.is_none() {
if let Some(body) = doc_body.as_ref().and_then(Value::as_object) {
// Look up each referenced template's mapping
// spec so we can inspect its `type`.
let tmpl_specs: std::collections::HashMap<String, Value> = mapping
.as_ref()
.and_then(|m| {
m.get("mappings")
.and_then(|mm| mm.get("dynamic_templates"))
.or_else(|| m.get("dynamic_templates"))
})
.and_then(Value::as_array)
.map(|arr| {
arr.iter()
.filter_map(|v| {
v.as_object().and_then(|o| {
let (name, spec) = o.iter().next()?;
let mapping_spec =
spec.get("mapping").cloned().unwrap_or(Value::Null);
Some((name.clone(), mapping_spec))
})
})
.collect()
})
.unwrap_or_default();
let mut first_type_clash: Option<(String, String, String)> = None;
for (field, tmpl) in dt_map {
let Some(spec) = tmpl_specs.get(tmpl) else {
continue;
};
let ftype = spec.get("type").and_then(Value::as_str).unwrap_or("");
// Scalar-like types that can't hold an object.
let scalar = matches!(
ftype,
"keyword"
| "text"
| "match_only_text"
| "long"
| "integer"
| "short"
| "byte"
| "double"
| "float"
| "boolean"
| "date"
| "date_nanos"
| "ip"
| "binary"
| "half_float"
| "scaled_float"
| "unsigned_long"
| "geo_point"
);
if !scalar {
continue;
}
let prefix = format!("{}.", field);
let has_dotted = body.keys().any(|k| k.starts_with(&prefix));
if !has_dotted {
continue;
}
// Build a preview of the "object-shaped"
// value ES would render (e.g. `{bar=hello world}`).
let mut parts: Vec<String> = Vec::new();
for (k, v) in body.iter() {
if !k.starts_with(&prefix) {
continue;
}
let sub_key = &k[prefix.len()..];
let rendered = match v {
Value::String(s) => s.clone(),
other => other.to_string(),
};
parts.push(format!("{}={}", sub_key, rendered));
}
let preview = format!("{{{}}}", parts.join(", "));
first_type_clash = Some((field.clone(), ftype.to_string(), preview));
break;
}
if let Some((field, ftype, preview)) = first_type_clash {
let reason = format!(
"failed to parse field [{}] of type [{}] in document with id '{}'. Preview of field's value: '{}'",
field, ftype,
doc_id.clone().unwrap_or_default(),
preview
);
items[item_idx] = Some(BulkItemResult {
action: action_type.to_string(),
index: target_index.clone(),
id: error_id.clone(),
status: 400,
result: None,
error: Some(reason),
get_source: None,
});
errors = true;
continue;
}
}
}
if let Some((field, tmpl)) = first_bad {
let reason = format!(
"Can't find dynamic template for dynamic template name [{}] of field [{}]",
tmpl, field
);
items[item_idx] = Some(BulkItemResult {
action: action_type.to_string(),
index: target_index.clone(),
id: error_id,
status: 400,
result: None,
error: Some(reason),
get_source: None,
});
errors = true;
continue;
}
}
}
// Date-format validation: if any field is declared as
// `type: date` with an explicit `format` (no `ignore_malformed`
// override), values that don't parse against the format are
// rejected at ingest as ES does — `document_parsing_exception`
// at the bulk item level. We only apply this for `index` /
// `create`; updates operate on already-stored docs.
if matches!(action_type.as_str(), "index" | "create") {
if let Some(body) = doc_body.as_ref().and_then(Value::as_object) {
let mapping_props = engine.index_mappings.get(&target_index).and_then(|m| {
m.get("properties")
.or_else(|| m.get("mappings").and_then(|mm| mm.get("properties")))
.cloned()
});
if let Some(props) = mapping_props {
if let Some(bad) = find_bad_date_field(body, &props) {
let reason = format!(
"failed to parse field [{}] of type [date] in document with id '{}'",
bad.0,
doc_id.clone().unwrap_or_default(),
);
items[item_idx] = Some(BulkItemResult {
action: action_type.to_string(),
index: target_index.clone(),
id: error_id.clone(),
status: 400,
result: None,
error: Some(reason),
get_source: None,
});
errors = true;
continue;
}
}
}
}
// Numeric / boolean type enforcement (issue #781). A field mapped
// `integer` used to keep whatever arrived — `1.9`, `9999999999`,
// `"abc"`, even an object — so the same query over the same declared
// -integer field returned different hits than ES. Values ES coerces
// are coerced here (`1.9` → `1`, `"5"` → `5`, `"true"` → `true`) and
// values ES refuses become a per-item 400 `document_parsing_exception`,
// exactly like the date-format check above. `index` / `create` only:
// an `update` merges into a doc that was already validated on write.
//
// The rules live in `xerj_common::field_coercion`, shared with the
// single-document `_doc` / `_create` handlers in `xerj-api`, so the
// two write paths cannot drift apart.
if matches!(action_type.as_str(), "index" | "create") {
let mapping_props = typed_numeric_props(&target_index, &mut index_type_check_props);
if let Some(props) = mapping_props {
if let Some(body) = doc_body.as_mut().and_then(Value::as_object_mut) {
if let Err(bad) = xerj_common::field_coercion::coerce_document(body, &props) {
items[item_idx] = Some(BulkItemResult {
action: action_type.to_string(),
index: target_index.clone(),
id: error_id.clone(),
status: 400,
result: None,
error: Some(bad.reason(&doc_id.clone().unwrap_or_default())),
get_source: None,
});
errors = true;
continue;
}
}
}
}
// doc_body already lazy-parsed above (for dynamic-templates
// validation). Nothing else to do here.
let result = execute_bulk_action(
engine,
&action_type,
&target_index,
doc_id,
doc_body,
if_seq_no,
if_primary_term,
routing,
)
.await;
match result {
Ok(resp) => {
// ES bulk semantics: 201 on first create, 200 on
// overwrite (update). Delete → 200. Engine reports the
// fact via `resp.result` ("created" vs "updated").
let status: u16 = match action_type.as_str() {
"delete" => 200,
_ if resp.result == "updated" || resp.result == "noop" => 200,
_ => 201,
};
// Bulk update supports echoing the post-update source
// via `items[N].update.get._source`. Source spec comes
// from (priority): action metadata → doc-body `_source`
// → URL-level default (?_source=true).
let effective_source_req =
source_req.clone().or_else(|| default_source_req.clone());
let get_source: Option<Value> =
if action_type == "update" && effective_source_req.is_some() {
match doc_id_for_get.as_deref() {
Some(id) => match engine.get_index(&target_index_for_get) {
Ok(idx) => {
let fetched = idx.get_document(id).await.ok().flatten();
fetched.map(|src| {
apply_bulk_source_filter(
&src,
effective_source_req.as_ref().unwrap(),
)
})
}
Err(_) => None,
},
None => None,
}
} else {
None
};
items[item_idx] = Some(BulkItemResult {
action: action_type.clone(),
index: target_index,
id: resp.id,
status,
result: Some(resp.result),
error: None,
get_source,
});
}
Err(e) => {
errors = true;
// Map engine-level errors to the correct HTTP status so
// per-item error objects carry the status ES clients key
// off of. VersionConflict → 409, NotFound → 404.
let status = engine_error_http_status(&e);
items[item_idx] = Some(BulkItemResult {
action: action_type,
index: target_index,
id: error_id,
status,
result: None,
error: Some(e.to_string()),
get_source: None,
});
}
}
}
// Flatten — any slot still None is a parse error that already set its slot.
let final_items: Vec<BulkItemResult> = items.into_iter().flatten().collect();
let exec_ms = t_exec.elapsed().as_millis() as u64;
let took_ms = started.elapsed().as_millis() as u64;
// THROWAWAY prof (XERJ_PROF): whole-request bulk attribution.
if std::env::var_os("XERJ_PROF").is_some() {
eprintln!(
"XERJ_PROF bulk total_ms={} lines_ms={} parse_ms={} group_ms={} exec_ms={} n_lines={}",
took_ms,
lines_ms,
parse_ms,
group_ms,
exec_ms,
lines.len()
);
}
if took_ms >= 50 {
tracing::debug!(
total_ms = took_ms,
lines_ms,
parse_ms,
group_ms,
exec_ms,
n_lines = lines.len(),
"process_bulk timings"
);
}
BulkResult {
took_ms,
errors,
items: final_items,
}
}
/// Apply a bulk-action `_source` request to a fetched document.
///
/// Accepts the same shapes the search body does:
/// - `true` / `false` — include everything / return `Value::Null`
/// - `"field"` — single include
/// - `["f1", "f2"]` — include list
/// - `{"includes": [...], "excludes": [...]}` — full filter
fn apply_bulk_source_filter(src: &Value, spec: &Value) -> Value {
let obj = match src.as_object() {
Some(o) => o.clone(),
None => return src.clone(),
};
let (includes, excludes): (Vec<String>, Vec<String>) = match spec {
Value::Bool(true) => return Value::Object(obj),
Value::Bool(false) => return Value::Null,
Value::String(s) => (vec![s.clone()], Vec::new()),
Value::Array(arr) => (
arr.iter()
.filter_map(|v| v.as_str().map(String::from))
.collect(),
Vec::new(),
),
Value::Object(o) => {
let pull = |k: &str| -> Vec<String> {
match o.get(k) {
Some(Value::Array(a)) => a
.iter()
.filter_map(|x| x.as_str().map(String::from))
.collect(),
Some(Value::String(s)) => vec![s.clone()],
_ => Vec::new(),
}
};
(pull("includes"), pull("excludes"))
}
_ => return Value::Object(obj),
};
let mut out = serde_json::Map::new();
for (k, v) in obj {
let keep = includes.is_empty() || includes.iter().any(|inc| inc == &k);
let drop = excludes.iter().any(|exc| exc == &k);
if keep && !drop {
out.insert(k, v);
}
}
Value::Object(out)
}
/// Apply dynamic-template `copy_to` directives to a doc body at
/// ingest. For each field in the doc that isn't already in the
/// declared mapping, check every dynamic template in order; if the
/// field name matches a template's `match` pattern (or equals the
/// template's name when no pattern is declared) AND the template's
/// mapping specifies `copy_to`, splice the field's value into the
/// target field (supporting dotted target paths and array append
/// semantics). When the per-item action metadata pins a specific
/// template via `dynamic_templates: {field: tmpl_name}`, that
/// template takes priority.
pub fn apply_dynamic_template_copy_to_public(
body: &mut serde_json::Map<String, Value>,
mapping: Option<&Value>,
) {
apply_dynamic_template_copy_to(body, mapping, None);
}
fn apply_dynamic_template_copy_to(
body: &mut serde_json::Map<String, Value>,
mapping: Option<&Value>,
per_item: Option<&std::collections::BTreeMap<String, String>>,
) {
let Some(mapping) = mapping else { return };
let templates_v = mapping
.get("mappings")
.and_then(|m| m.get("dynamic_templates"))
.or_else(|| mapping.get("dynamic_templates"));
let Some(templates_arr) = templates_v.and_then(Value::as_array) else {
return;
};
if templates_arr.is_empty() {
return;
}
let declared_props: std::collections::HashSet<String> = mapping
.get("mappings")
.and_then(|m| m.get("properties"))
.or_else(|| mapping.get("properties"))
.and_then(Value::as_object)
.map(|o| o.keys().cloned().collect())
.unwrap_or_default();
// Pre-extract (name, pattern, copy_to) triples, ordered.
let specs: Vec<(String, Option<String>, Option<String>)> = templates_arr
.iter()
.filter_map(|v| {
let (name, body) = v.as_object().and_then(|o| o.iter().next())?;
let pattern = body.get("match").and_then(Value::as_str).map(String::from);
let copy_to =
body.get("mapping")
.and_then(|m| m.get("copy_to"))
.and_then(|c| match c {
Value::String(s) => Some(s.clone()),
Value::Array(a) => a.first().and_then(Value::as_str).map(String::from),
_ => None,
});
Some((name.clone(), pattern, copy_to))
})
.collect();
let field_names: Vec<String> = body.keys().cloned().collect();
let mut touched_targets: Vec<String> = Vec::new();
let mut pristine: serde_json::Map<String, Value> = serde_json::Map::new();
for field in field_names {
if declared_props.contains(&field) {
continue;
}
// Priority 1: per-item `dynamic_templates: {field: name}`.
let forced = per_item.and_then(|m| m.get(&field).cloned());
let mut chosen: Option<String> = None;
if let Some(name) = forced {
if let Some((_, _, copy_to)) = specs.iter().find(|(n, _, _)| n == &name) {
chosen = copy_to.clone();
}
}
// Priority 2: first matching template in declaration order.
if chosen.is_none() {
for (name, pattern, copy_to) in &specs {
let matches = if let Some(pat) = pattern {
simple_glob_matches(pat.as_bytes(), field.as_bytes())
} else {
field == name.as_str()
};
if matches {
chosen = copy_to.clone();
break;
}
}
}
let Some(target_path) = chosen else { continue };
let Some(val) = body.get(&field).cloned() else {
continue;
};
// Snapshot the target's pristine value before mutation so
// the synthetic-source emit path can restore the explicit-
// only source shape. Matches apply_copy_to's convention.
if !touched_targets.iter().any(|t| t == &target_path) {
let pristine_val = path_get(body, &target_path).cloned().unwrap_or(Value::Null);
pristine.insert(target_path.clone(), pristine_val);
touched_targets.push(target_path.clone());
}
// Append value into target path (splat arrays like
// apply_copy_to does). Keyword-ish target types expect
// strings; the synthetic_source + fields fetch path handles
// stringification downstream, so we preserve the original
// value shape here.
match val {
Value::Array(arr) => {
for v in arr {
append_copy_to_path(body, &target_path, v);
}
}
other => append_copy_to_path(body, &target_path, other),
}
}
if !touched_targets.is_empty() {
// Merge with any existing pristine snapshot (apply_copy_to
// from the declared-schema path may have already written
// one; keep both sets of restore entries).
if let Some(Value::Object(existing)) = body.get("__xy_copy_to_pristine__").cloned() {
for (k, v) in existing {
pristine.entry(k).or_insert(v);
}
}
body.insert(
"__xy_copy_to_pristine__".to_string(),
Value::Object(pristine),
);
}
}
fn path_get<'a>(root: &'a serde_json::Map<String, Value>, path: &str) -> Option<&'a Value> {
let segs: Vec<&str> = path.split('.').collect();
if segs.is_empty() {
return None;
}
let mut cur: &Value = root.get(segs[0])?;
for seg in &segs[1..] {
cur = cur.as_object()?.get(*seg)?;
}
Some(cur)
}
fn append_copy_to_path(target: &mut serde_json::Map<String, Value>, path: &str, val: Value) {
let segs: Vec<&str> = path.split('.').collect();
if segs.is_empty() {
return;
}
let last = segs.len() - 1;
let mut cur: &mut serde_json::Map<String, Value> = target;
for (i, seg) in segs.iter().enumerate() {
if i == last {
let entry = cur.entry((*seg).to_string()).or_insert(Value::Null);
match entry {
Value::Null => {
*entry = val;
return;
}
Value::Array(arr) => {
arr.push(val);
return;
}
existing => {
let prev = existing.clone();
*existing = Value::Array(vec![prev, val]);
return;
}
}
}
let entry = cur
.entry((*seg).to_string())
.or_insert_with(|| Value::Object(serde_json::Map::new()));
if !entry.is_object() {
let old = entry.take();
let mut m = serde_json::Map::new();
m.insert("__xy_scalar__".to_string(), old);
*entry = Value::Object(m);
}
cur = entry.as_object_mut().unwrap();
}
}
/// Does this mapping-properties tree contain at least one
/// `type: date`/`type: date_nanos` field that has an explicit
/// `format` set AND does not opt into `ignore_malformed`? When true,
/// ingest must parse-validate date values on this index.
fn mapping_has_strict_date(props: &Value) -> bool {
let Some(obj) = props.as_object() else {
return false;
};
for (_, spec) in obj {
let ftype = spec.get("type").and_then(Value::as_str).unwrap_or("");
if (ftype == "date" || ftype == "date_nanos")
&& spec.get("format").and_then(Value::as_str).is_some()
&& !spec
.get("ignore_malformed")
.and_then(Value::as_bool)
.unwrap_or(false)
{
return true;
}
if let Some(sub) = spec.get("properties") {
if mapping_has_strict_date(sub) {
return true;
}
}
}
false
}
/// True when any field in the mapping is a `semantic_text` field. Such
/// fields auto-embed their text into a companion `<field>_vector` at
/// ingest, which only happens on the per-doc `index_document` path
/// (`Index::apply_semantic_embeddings`). The turbo auto-id batch path
/// stores the raw NDJSON bytes and never parses/embeds them, so an index
/// with a `semantic_text` field MUST be routed through the per-doc path —
/// otherwise auto-id bulk docs land with an empty vector column and
/// `semantic`/`knn` search silently returns nothing.
fn mapping_has_semantic_text(props: &Value) -> bool {
let Some(obj) = props.as_object() else {
return false;
};
for (_, spec) in obj {
if spec.get("type").and_then(Value::as_str) == Some("semantic_text") {
return true;
}
if let Some(sub) = spec.get("properties") {
if mapping_has_semantic_text(sub) {
return true;
}
}
}
false
}
/// Walk a doc body against the index's mapping properties to find
/// the first field that is declared as `type: date` with a `format`
/// set, `ignore_malformed` off, and a value that doesn't parse
/// against the declared format. Returns `(field_name, bad_value)`
/// or `None` when everything checks out. ES `date_optional_time` and
/// `strict_date_optional_time*` formats cover ISO-8601; `epoch_*`
/// require purely numeric strings / numbers.
fn find_bad_date_field(
doc: &serde_json::Map<String, Value>,
props: &Value,
) -> Option<(String, Value)> {
let props_obj = props.as_object()?;
for (fname, spec) in props_obj {
let Some(val) = doc.get(fname) else { continue };
let ftype = spec.get("type").and_then(Value::as_str).unwrap_or("");
if ftype != "date" && ftype != "date_nanos" {
continue;
}
let fmt = spec.get("format").and_then(Value::as_str).unwrap_or("");
if fmt.is_empty() {
continue;
}
let ignore_mal = spec
.get("ignore_malformed")
.and_then(Value::as_bool)
.unwrap_or(false);
if ignore_mal {
continue;
}
// Pick the single value to validate — arrays recurse over
// each element, using the first failure we find.
let candidates: Vec<&Value> = match val {
Value::Array(arr) => arr.iter().collect(),
other => vec![other],
};
for cand in candidates {
if !date_value_parses(cand, fmt) {
return Some((fname.clone(), cand.clone()));
}
}
}
None
}
/// Does `val` parse against the ES date `fmt`?
///
/// This is the `ignore_malformed: false` path — a `false` here rejects the
/// whole document with `document_parsing_exception`. It delegates to
/// [`xerj_query::dates::date_value_valid_with_format`], which is also what
/// the `ignore_malformed: true` path calls, so the two cannot disagree.
///
/// They used to, and in the wrong direction: this function hand-rolled its
/// own rules and ended with a blanket `true` for "named or custom patterns",
/// so under a declared format like `dd/MM/yyyy` the value `"literally
/// anything"` was accepted here while the *lenient* path dropped it. Setting
/// `ignore_malformed: false` — asking for stricter handling — made the engine
/// accept strictly more. Keep this a delegation.
fn date_value_parses(val: &Value, fmt: &str) -> bool {
xerj_query::dates::date_value_valid_with_format(val, fmt)
}
/// `*`-glob match (single wildcard segment, no `**`, no character
/// classes). Used to test a field name against a dynamic-template
/// `match` pattern.
fn simple_glob_matches(pat: &[u8], txt: &[u8]) -> bool {
let (mut p, mut t) = (0usize, 0usize);
let (mut star, mut star_t) = (None::<usize>, 0usize);
while t < txt.len() {
if p < pat.len() && (pat[p] == b'?' || pat[p] == txt[t]) {
p += 1;
t += 1;
} else if p < pat.len() && pat[p] == b'*' {
star = Some(p);
star_t = t;
p += 1;
} else if let Some(sp) = star {
p = sp + 1;
star_t += 1;
t = star_t;
} else {
return false;
}
}
while p < pat.len() && pat[p] == b'*' {
p += 1;
}
p == pat.len()
}
// Per-item bulk execution needs all 8 pieces of action metadata (target,
// id, body, CAS pair, routing); grouping them into a struct would just
// reshuffle the same fields, so allow the arg count here.
#[allow(clippy::too_many_arguments)]
async fn execute_bulk_action(
engine: &Engine,
action_type: &str,
index: &str,
doc_id: Option<String>,
body: Option<Value>,
if_seq_no: Option<u64>,
if_primary_term: Option<u64>,
routing: Option<String>,
) -> Result<IndexResponse> {
// Inject `_routing` into the source body so `exists: _routing` and
// `fields: [_routing]` resolve through the stored doc.
let inject_routing = |body: Option<Value>| -> Option<Value> {
match routing.as_deref() {
Some(r) => {
let mut v = body.unwrap_or(Value::Object(serde_json::Map::new()));
if let Some(obj) = v.as_object_mut() {
obj.insert("_routing".to_string(), Value::String(r.to_string()));
}
Some(v)
}
None => body,
}
};
match action_type {
"index" => {
// index: create or overwrite. Honors `if_seq_no` for
// optimistic concurrency — a mismatch bubbles up as a
// VersionConflict engine error which the caller maps to a
// 409 per-item error.
let idx = engine.get_or_create_index(index)?;
let source = inject_routing(body).unwrap_or(Value::Object(serde_json::Map::new()));
if if_seq_no.is_some() || if_primary_term.is_some() {
idx.index_document_with_version(doc_id, source, if_seq_no, if_primary_term)
.await
} else {
idx.index_document(doc_id, source).await
}
}
"create" => {
// create: fail with 409 if document already exists.
let idx = engine.get_or_create_index(index)?;
let source = inject_routing(body).unwrap_or(Value::Object(serde_json::Map::new()));
let id = doc_id.unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
idx.create_document(id, source).await
}
"update" => {
// Partial update: merge `doc` fields into the existing document.
let idx = engine.get_or_create_index(index)?;
let id = doc_id.ok_or_else(|| {
crate::EngineError::Common(xerj_common::XerjError::invalid_query(
"update action requires _id",
))
})?;
let body_val = body.unwrap_or(Value::Object(serde_json::Map::new()));
let partial = body_val.get("doc").cloned();
let upsert = body_val.get("upsert").cloned();
let doc_as_upsert = body_val
.get("doc_as_upsert")
.and_then(Value::as_bool)
.unwrap_or(false);
match idx
.update_document_with_upsert(&id, partial, upsert, doc_as_upsert)
.await?
{
Some(resp) => Ok(resp),
None => Err(crate::EngineError::Common(
xerj_common::XerjError::document_not_found(&id, index),
)),
}
}
"delete" => {
let idx = engine.get_index(index)?;
let id = doc_id.ok_or_else(|| {
crate::EngineError::Common(xerj_common::XerjError::invalid_query(
"delete action requires _id",
))
})?;
idx.delete_document(&id).await?;
Ok(IndexResponse {
id,
seq_no: 0,
version: 0,
result: "deleted".to_string(),
})
}
other => Err(crate::EngineError::Common(
xerj_common::XerjError::invalid_query(format!("unknown bulk action: {other}")),
)),
}
}
#[cfg(test)]
mod semantic_lifecycle_tests {
use super::*;
use crate::ingest_memory::{Category, Ledger, Measurement};
use serde_json::json;
use std::sync::{Arc, Mutex};
use tempfile::TempDir;
use xerj_common::config::Config;
use xerj_common::types::{EmbeddingConfig, FieldConfig, FieldType, Schema};
fn semantic_engine(name: &str) -> (TempDir, Engine) {
semantic_engine_with_targets(name, &[("content", "content_vector")])
}
fn semantic_engine_with_targets(name: &str, targets: &[(&str, &str)]) -> (TempDir, Engine) {
let dir = TempDir::new().unwrap();
let mut config = Config::default();
config.server.data_dir = dir.path().to_string_lossy().into_owned();
let engine = Engine::new(config).unwrap();
let mut schema = Schema::empty();
for (field, target) in targets {
let mut config = FieldConfig::new(*field, FieldType::Text);
config.options.dimensions = Some(16);
config.embedding = Some(EmbeddingConfig {
endpoint: None,
model: None,
target_field: Some((*target).into()),
});
schema.fields.push(config);
}
engine.create_index(name, schema).unwrap();
let properties = targets
.iter()
.map(|(field, _)| ((*field).to_string(), json!({"type": "semantic_text"})))
.collect::<serde_json::Map<_, _>>();
engine
.put_index_mapping(name, json!({"properties": properties}))
.unwrap();
(dir, engine)
}
fn current(ledger: &Ledger, category: Category) -> u64 {
ledger.gauge(category, Measurement::Estimated).current
}
fn all_semantic_current(ledger: &Ledger) -> u64 {
[
Category::RawSource,
Category::ParsedSource,
Category::ParsedVector,
Category::PreparedDocument,
Category::PreparedVector,
]
.into_iter()
.map(|category| current(ledger, category))
.sum()
}
#[test]
fn raw_owner_token_outlives_every_arc_occurrence() {
let ledger: &'static Ledger = Box::leak(Box::new(Ledger::new()));
let source: Arc<[u8]> = Arc::from(&b"{\"content\":\"retained\"}"[..]);
let owner = Arc::as_ptr(&source) as *const () as usize;
let mut owners = std::collections::HashMap::from([(
owner,
(
2,
crate::ingest_memory::Retained::for_ledger(
ledger,
Category::RawSource,
source.len(),
),
),
)]);
let second = Arc::clone(&source);
release_raw_owner(&mut owners, second);
assert_eq!(Arc::strong_count(&source), 1);
assert_eq!(owners.get(&owner).map(|entry| entry.0), Some(1));
assert_eq!(current(ledger, Category::RawSource), source.len() as u64);
release_raw_owner(&mut owners, source);
assert!(owners.is_empty());
assert_eq!(current(ledger, Category::RawSource), 0);
}
async fn run_case(
name: &str,
fault: SemanticLifecycleFault,
) -> (
BulkResult,
&'static Ledger,
Vec<(SemanticLifecyclePoint, [u64; 5])>,
) {
let (_dir, engine) = semantic_engine_with_targets(
name,
&[("content", "content_vector"), ("summary", "summary_vector")],
);
let ledger: &'static Ledger = Box::leak(Box::new(Ledger::new()));
// Zero-capacity rendezvous channels make every hook a genuine phase
// barrier: the ingest task cannot advance until the observer has read
// the live gauges and explicitly released it.
let expected = if fault == SemanticLifecycleFault::Embedding {
4
} else {
8
};
let (observation_tx, observation_rx) = std::sync::mpsc::sync_channel(0);
let (resume_tx, resume_rx) = std::sync::mpsc::sync_channel(0);
let resume_rx = Arc::new(Mutex::new(resume_rx));
let observer = std::thread::spawn(move || {
let mut points = Vec::with_capacity(expected);
for _ in 0..expected {
points.push(observation_rx.recv().unwrap());
resume_tx.send(()).unwrap();
}
points
});
let hook: SemanticLifecycleHook = Arc::new(move |_, point| {
observation_tx
.send((
point,
[
current(ledger, Category::RawSource),
current(ledger, Category::ParsedSource),
current(ledger, Category::ParsedVector),
current(ledger, Category::PreparedDocument),
current(ledger, Category::PreparedVector),
],
))
.unwrap();
resume_rx.lock().unwrap().recv().unwrap();
match (fault, point) {
(SemanticLifecycleFault::Embedding, SemanticLifecyclePoint::EmbeddingInside) => {
fault
}
(
SemanticLifecycleFault::Publication,
SemanticLifecyclePoint::PublicationInside,
) => fault,
_ => SemanticLifecycleFault::None,
}
});
let body = format!(
"{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"one\"}}}}\n\
{{\"content\":\"caller supplied vector\",\
\"content_vector\":[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,\
0.9,1.0,1.1,1.2,1.3,1.4,1.5,1.6],\
\"summary\":\"a genuine semantic lifecycle embedding job\"}}\n"
);
let result = crate::ingest_memory::with_test_ledger(
ledger,
with_semantic_lifecycle_hook(name, hook, process_bulk(&engine, None, &body)),
)
.await;
let points = observer.join().unwrap();
(result, ledger, points)
}
#[tokio::test]
async fn semantic_lifecycle_success_balances_isolated_ledger() {
let (result, ledger, points) =
run_case("semantic-lifecycle-success", SemanticLifecycleFault::None).await;
assert!(!result.errors, "{:?}", result.items);
let phase_points: Vec<_> = points.iter().map(|(point, _)| *point).collect();
assert_eq!(
phase_points,
[
SemanticLifecyclePoint::Grouped,
SemanticLifecyclePoint::Parsed,
SemanticLifecyclePoint::EmbeddingInside,
SemanticLifecyclePoint::EmbeddingItemInside,
SemanticLifecyclePoint::Prepared,
SemanticLifecyclePoint::BeforePublication,
SemanticLifecyclePoint::PublicationInside,
SemanticLifecyclePoint::AfterPublication,
]
);
let at = |point| points.iter().find(|(p, _)| *p == point).unwrap().1;
assert!(at(SemanticLifecyclePoint::Grouped)[0] > 0);
assert_eq!(at(SemanticLifecyclePoint::Parsed)[0], 0);
assert!(at(SemanticLifecyclePoint::Parsed)[1] > 0);
assert!(at(SemanticLifecyclePoint::EmbeddingInside)[1] > 0);
assert!(
at(SemanticLifecyclePoint::EmbeddingInside)[2] > 0,
"caller-supplied vector ownership must remain live while embedding is blocked"
);
assert_eq!(at(SemanticLifecyclePoint::BeforePublication)[1], 0);
assert!(at(SemanticLifecyclePoint::BeforePublication)[3] > 0);
assert!(at(SemanticLifecyclePoint::BeforePublication)[4] > 0);
assert_eq!(at(SemanticLifecyclePoint::AfterPublication), [0; 5]);
assert!(current(ledger, Category::RawSource) == 0);
assert!(
ledger
.gauge(Category::RawSource, Measurement::SerializedSize)
.peak
> 0
);
assert!(
ledger
.gauge(Category::ParsedSource, Measurement::Estimated)
.peak
> 0
);
assert!(
ledger
.gauge(Category::PreparedDocument, Measurement::Estimated)
.peak
> 0
);
assert!(
ledger
.gauge(Category::PreparedVector, Measurement::ExactCapacity)
.peak
> 0
);
assert_eq!(all_semantic_current(ledger), 0);
assert_eq!(ledger.accounting_errors(), 0);
assert_eq!(all_semantic_current(&crate::ingest_memory::LEDGER), 0);
}
#[tokio::test]
async fn semantic_lifecycle_embedding_error_releases_parsed_ownership() {
let (result, ledger, points) = run_case(
"semantic-lifecycle-embed-error",
SemanticLifecycleFault::Embedding,
)
.await;
assert!(result.errors);
assert_eq!(result.items[0].status, 400);
let phase_points: Vec<_> = points.iter().map(|(point, _)| *point).collect();
assert_eq!(
phase_points,
[
SemanticLifecyclePoint::Grouped,
SemanticLifecyclePoint::Parsed,
SemanticLifecyclePoint::EmbeddingInside,
SemanticLifecyclePoint::Prepared,
]
);
let inside = points
.iter()
.find(|(point, _)| *point == SemanticLifecyclePoint::EmbeddingInside)
.unwrap()
.1;
assert!(inside[1] > 0);
assert!(
inside[2] > 0,
"caller-supplied vector ownership must remain live while embedding is blocked"
);
assert!(
ledger
.gauge(Category::ParsedSource, Measurement::Estimated)
.peak
> 0
);
assert_eq!(all_semantic_current(ledger), 0);
assert_eq!(ledger.accounting_errors(), 0);
}
#[tokio::test]
async fn semantic_lifecycle_publication_error_releases_prepared_ownership() {
let (result, ledger, points) = run_case(
"semantic-lifecycle-publication-error",
SemanticLifecycleFault::Publication,
)
.await;
assert!(result.errors);
assert_eq!(result.items[0].status, 400);
let phase_points: Vec<_> = points.iter().map(|(point, _)| *point).collect();
assert_eq!(
phase_points,
[
SemanticLifecyclePoint::Grouped,
SemanticLifecyclePoint::Parsed,
SemanticLifecyclePoint::EmbeddingInside,
SemanticLifecyclePoint::EmbeddingItemInside,
SemanticLifecyclePoint::Prepared,
SemanticLifecyclePoint::BeforePublication,
SemanticLifecyclePoint::PublicationInside,
SemanticLifecyclePoint::AfterPublication,
]
);
let inside = points
.iter()
.find(|(point, _)| *point == SemanticLifecyclePoint::PublicationInside)
.unwrap()
.1;
assert!(inside[3] > 0);
assert!(inside[4] > 0);
assert!(
ledger
.gauge(Category::PreparedDocument, Measurement::Estimated)
.peak
> 0
);
assert!(
ledger
.gauge(Category::PreparedVector, Measurement::ExactCapacity)
.peak
> 0
);
assert_eq!(all_semantic_current(ledger), 0);
assert_eq!(ledger.accounting_errors(), 0);
}
#[tokio::test]
async fn semantic_lifecycle_hook_scope_is_panic_safe_and_target_specific() {
let (_dir, engine) = semantic_engine("semantic-lifecycle-panic");
let engine = Arc::new(engine);
let ledger: &'static Ledger = Box::leak(Box::new(Ledger::new()));
let hook: SemanticLifecycleHook = Arc::new(|_, point| {
if point == SemanticLifecyclePoint::Grouped {
panic!("deliberate lifecycle hook panic");
}
SemanticLifecycleFault::None
});
let body = concat!(
"{\"index\":{\"_index\":\"semantic-lifecycle-panic\",\"_id\":\"one\"}}\n",
"{\"content\":\"panic cleanup\"}\n",
);
let panic_engine = Arc::clone(&engine);
let task = tokio::spawn(async move {
crate::ingest_memory::with_test_ledger(
ledger,
with_semantic_lifecycle_hook(
"semantic-lifecycle-panic",
hook,
process_bulk(&panic_engine, None, body),
),
)
.await
});
assert!(task.await.unwrap_err().is_panic());
assert_eq!(all_semantic_current(ledger), 0);
let other_ledger = Box::leak(Box::new(Ledger::new()));
let rejecting_hook: SemanticLifecycleHook =
Arc::new(|_, _| SemanticLifecycleFault::Publication);
let result = crate::ingest_memory::with_test_ledger(
other_ledger,
with_semantic_lifecycle_hook(
"different-target",
rejecting_hook,
process_bulk(&engine, None, body),
),
)
.await;
assert!(
!result.errors,
"target-specific hook leaked onto another target"
);
assert_eq!(all_semantic_current(other_ledger), 0);
assert_eq!(all_semantic_current(&crate::ingest_memory::LEDGER), 0);
}
#[tokio::test]
async fn semantic_lifecycle_declines_after_each_sequential_publication() {
let name = "semantic-lifecycle-sequential";
let (_dir, engine) = semantic_engine(name);
let ledger: &'static Ledger = Box::leak(Box::new(Ledger::new()));
let observations = Arc::new(Mutex::new(Vec::<(SemanticLifecyclePoint, u64, u64)>::new()));
let captured = Arc::clone(&observations);
let embedded = Arc::new(std::sync::atomic::AtomicBool::new(false));
let embedded_hook = Arc::clone(&embedded);
let hook: SemanticLifecycleHook = Arc::new(move |_, point| {
if point == SemanticLifecyclePoint::EmbeddingInside {
embedded_hook.store(true, std::sync::atomic::Ordering::Relaxed);
}
if matches!(
point,
SemanticLifecyclePoint::BeforePublication
| SemanticLifecyclePoint::AfterPublication
) {
captured.lock().unwrap().push((
point,
current(ledger, Category::PreparedDocument),
current(ledger, Category::PreparedVector),
));
}
SemanticLifecycleFault::None
});
let body = (0..3)
.map(|i| {
format!(
"{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"{i}\"}}}}\n\
{{\"content\":\"semantic document number {i}\"}}\n"
)
})
.collect::<String>();
let result = crate::ingest_memory::with_test_ledger(
ledger,
with_semantic_lifecycle_hook(name, hook, process_bulk(&engine, None, &body)),
)
.await;
assert!(!result.errors, "{:?}", result.items);
assert!(embedded.load(std::sync::atomic::Ordering::Relaxed));
let observations = observations.lock().unwrap();
assert_eq!(observations.len(), 6);
for pair in observations.as_chunks::<2>().0 {
assert_eq!(pair[0].0, SemanticLifecyclePoint::BeforePublication);
assert_eq!(pair[1].0, SemanticLifecyclePoint::AfterPublication);
assert!(pair[0].1 > pair[1].1);
assert!(pair[0].2 > pair[1].2);
}
for pair in observations.as_chunks::<2>().0 {
assert!(pair[0].1 > 0);
assert!(pair[0].2 > 0);
assert_eq!(pair[1].1, 0, "published document ownership stayed charged");
assert_eq!(pair[1].2, 0, "published vector ownership stayed charged");
}
assert_eq!(observations.last().unwrap().1, 0);
assert_eq!(observations.last().unwrap().2, 0);
assert_eq!(all_semantic_current(ledger), 0);
assert_eq!(ledger.accounting_errors(), 0);
}
#[tokio::test]
async fn semantic_lifecycle_mixed_publication_outputs_balance_per_item() {
let name = "semantic-lifecycle-mixed";
let (_dir, engine) = semantic_engine(name);
let ledger: &'static Ledger = Box::leak(Box::new(Ledger::new()));
let publication = Arc::new(std::sync::atomic::AtomicUsize::new(0));
let publication_hook = Arc::clone(&publication);
let points = Arc::new(Mutex::new(Vec::new()));
let captured_points = Arc::clone(&points);
let hook: SemanticLifecycleHook = Arc::new(move |_, point| {
captured_points.lock().unwrap().push(point);
if point == SemanticLifecyclePoint::PublicationInside
&& publication_hook.fetch_add(1, std::sync::atomic::Ordering::Relaxed) == 1
{
SemanticLifecycleFault::Publication
} else {
SemanticLifecycleFault::None
}
});
let body = (0..3)
.map(|i| {
format!(
"{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"{i}\"}}}}\n\
{{\"content\":\"mixed output {i}\"}}\n"
)
})
.collect::<String>();
let result = crate::ingest_memory::with_test_ledger(
ledger,
with_semantic_lifecycle_hook(name, hook, process_bulk(&engine, None, &body)),
)
.await;
assert!(result.errors);
assert_eq!(
result
.items
.iter()
.map(|item| item.status)
.collect::<Vec<_>>(),
[201, 400, 201]
);
let points = points.lock().unwrap();
assert!(points.contains(&SemanticLifecyclePoint::EmbeddingInside));
assert_eq!(
points
.iter()
.filter(|point| **point == SemanticLifecyclePoint::PublicationInside)
.count(),
3
);
assert_eq!(all_semantic_current(ledger), 0);
assert_eq!(ledger.accounting_errors(), 0);
}
#[tokio::test]
async fn semantic_lifecycle_mixed_embedding_outputs_balance_per_item() {
let name = "semantic-lifecycle-mixed-embedding";
let (_dir, engine) = semantic_engine(name);
let ledger: &'static Ledger = Box::leak(Box::new(Ledger::new()));
let item = Arc::new(std::sync::atomic::AtomicUsize::new(0));
let item_hook = Arc::clone(&item);
let points = Arc::new(Mutex::new(Vec::new()));
let captured_points = Arc::clone(&points);
let hook: SemanticLifecycleHook = Arc::new(move |_, point| {
captured_points.lock().unwrap().push((
point,
current(ledger, Category::ParsedSource),
current(ledger, Category::ParsedVector),
));
if point == SemanticLifecyclePoint::EmbeddingItemInside
&& item_hook.fetch_add(1, std::sync::atomic::Ordering::Relaxed) == 1
{
SemanticLifecycleFault::Embedding
} else {
SemanticLifecycleFault::None
}
});
let body = (0..3)
.map(|i| {
format!(
"{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"{i}\"}}}}\n\
{{\"content\":\"mixed embedding output {i}\"}}\n"
)
})
.collect::<String>();
let result = crate::ingest_memory::with_test_ledger(
ledger,
with_semantic_lifecycle_hook(name, hook, process_bulk(&engine, None, &body)),
)
.await;
assert!(result.errors);
assert_eq!(
result
.items
.iter()
.map(|item| item.status)
.collect::<Vec<_>>(),
[201, 500, 201]
);
let points = points.lock().unwrap();
assert!(points.iter().any(|(point, parsed, _)| *point
== SemanticLifecyclePoint::EmbeddingInside
&& *parsed > 0));
assert_eq!(
points
.iter()
.filter(|(point, _, _)| *point == SemanticLifecyclePoint::EmbeddingItemInside)
.count(),
3
);
assert_eq!(
points
.iter()
.filter(|(point, _, _)| *point == SemanticLifecyclePoint::PublicationInside)
.count(),
2
);
assert_eq!(all_semantic_current(ledger), 0);
assert_eq!(ledger.accounting_errors(), 0);
}
#[tokio::test]
async fn semantic_lifecycle_covers_malformed_caller_vectors_and_literal_dotted_target() {
let name = "semantic-lifecycle-input-shapes";
let (_dir, engine) =
semantic_engine_with_targets(name, &[("content", "custom.vector"), ("summary", "v2")]);
let ledger: &'static Ledger = Box::leak(Box::new(Ledger::new()));
let points = Arc::new(Mutex::new(Vec::new()));
let captured_points = Arc::clone(&points);
let hook: SemanticLifecycleHook = Arc::new(move |_, point| {
captured_points.lock().unwrap().push(point);
SemanticLifecycleFault::None
});
let body = format!(
"{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"bad\"}}}}\n\
{{\"content\":\n\
{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"supplied\"}}}}\n\
{{\"content\":\"caller vector\",\"custom.vector\":[0.1,0.2,0.3],\
\"summary\":\"second target\",\"v2\":[0.4,0.5]}}\n\
{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"derived\"}}}}\n\
{{\"content\":\"derive literal dotted target\",\"summary\":\"derive second\"}}\n"
);
let result = crate::ingest_memory::with_test_ledger(
ledger,
with_semantic_lifecycle_hook(name, hook, process_bulk(&engine, None, &body)),
)
.await;
assert!(result.errors);
assert_eq!(
result
.items
.iter()
.map(|item| item.status)
.collect::<Vec<_>>(),
[400, 201, 201]
);
assert!(
ledger
.gauge(Category::ParsedVector, Measurement::ExactCapacity)
.peak
> 0
);
let points = points.lock().unwrap();
assert!(points.contains(&SemanticLifecyclePoint::EmbeddingInside));
assert_eq!(
points
.iter()
.filter(|point| **point == SemanticLifecyclePoint::PublicationInside)
.count(),
2
);
assert!(
ledger
.gauge(Category::PreparedVector, Measurement::ExactCapacity)
.peak
> 0
);
assert_eq!(all_semantic_current(ledger), 0);
assert_eq!(ledger.accounting_errors(), 0);
}
#[tokio::test]
async fn semantic_lifecycle_multiple_targets_and_index_creation_failure_balance() {
let ok = "semantic-lifecycle-target-a";
let fails = "semantic-lifecycle-target-b";
let (dir, engine) = semantic_engine(ok);
let mut schema = Schema::empty();
let mut content = FieldConfig::new("content", FieldType::Text);
content.options.dimensions = Some(16);
content.embedding = Some(EmbeddingConfig {
endpoint: None,
model: None,
target_field: Some("content_vector".into()),
});
schema.fields.push(content);
engine.create_index(fails, schema).unwrap();
engine
.put_index_mapping(
fails,
json!({"properties": {"content": {"type": "semantic_text"}}}),
)
.unwrap();
let ledger: &'static Ledger = Box::leak(Box::new(Ledger::new()));
let engine = Arc::new(engine);
let hook_engine = Arc::clone(&engine);
let collision = dir.path().join(fails);
let points = Arc::new(Mutex::new(Vec::new()));
let captured_points = Arc::clone(&points);
let hook: SemanticLifecycleHook = Arc::new(move |target, point| {
captured_points
.lock()
.unwrap()
.push((target.to_string(), point));
if target == fails && point == SemanticLifecyclePoint::Grouped {
let engine = Arc::clone(&hook_engine);
std::thread::spawn(move || {
tokio::runtime::Runtime::new()
.unwrap()
.block_on(engine.delete_index(fails))
.unwrap();
})
.join()
.unwrap();
std::fs::write(&collision, b"blocks index directory creation").unwrap();
}
SemanticLifecycleFault::None
});
let body = format!(
"{{\"index\":{{\"_index\":\"{ok}\",\"_id\":\"ok\"}}}}\n\
{{\"content\":\"first target\"}}\n\
{{\"index\":{{\"_index\":\"{fails}\",\"_id\":\"fail\"}}}}\n\
{{\"content\":\"second target\"}}\n"
);
let result = crate::ingest_memory::with_test_ledger(
ledger,
with_semantic_lifecycle_hook("*", hook, process_bulk(&engine, None, &body)),
)
.await;
assert!(result.errors);
assert_eq!(
result
.items
.iter()
.map(|item| item.status)
.collect::<Vec<_>>(),
[201, 500]
);
let points = points.lock().unwrap();
assert!(points.contains(&(ok.to_string(), SemanticLifecyclePoint::EmbeddingInside)));
assert!(points.contains(&(ok.to_string(), SemanticLifecyclePoint::PublicationInside)));
assert!(points.contains(&(fails.to_string(), SemanticLifecyclePoint::Grouped)));
assert!(!points.contains(&(fails.to_string(), SemanticLifecyclePoint::EmbeddingInside)));
assert_eq!(all_semantic_current(ledger), 0);
assert_eq!(ledger.accounting_errors(), 0);
}
#[tokio::test]
async fn tracing_off_semantic_path_skips_all_instrumentation_structures() {
assert_eq!(
crate::ingest_memory::config().mode,
crate::ingest_memory::TraceMode::Off,
"this structural proof requires tracing to be off; it must not silently skip"
);
let name = "semantic-lifecycle-disabled";
let (_dir, engine) = semantic_engine(name);
let counters = Arc::new(DisabledSemanticCounters::default());
let body = format!(
"{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"one\"}}}}\n\
{{\"content\":\"disabled structural proof\"}}\n"
);
let result = DISABLED_SEMANTIC_COUNTERS
.scope(Arc::clone(&counters), process_bulk(&engine, None, &body))
.await;
assert!(!result.errors, "{:?}", result.items);
assert_eq!(
counters.snapshot(),
DisabledSemanticInstrumentation::default(),
"tracing-off path read schema, allocated its guard vector, or walked JSON for sizing"
);
assert_eq!(all_semantic_current(&crate::ingest_memory::LEDGER), 0);
assert_eq!(crate::ingest_memory::LEDGER.accounting_errors(), 0);
}
}
#[cfg(test)]
mod lone_surrogate_tests {
use super::*;
use tempfile::TempDir;
use xerj_common::config::Config;
use xerj_common::types::Schema;
fn plain_engine(name: &str) -> (TempDir, Engine) {
let dir = TempDir::new().unwrap();
let mut config = Config::default();
config.server.data_dir = dir.path().to_string_lossy().into_owned();
let engine = Engine::new(config).unwrap();
engine.create_index(name, Schema::empty()).unwrap();
(dir, engine)
}
/// The per-item scan must reject exactly the documents serde_json's own
/// `Value` parse rejects for surrogate escapes — no more, no less. If it
/// were stricter it would drop valid documents; if it were laxer the bad
/// document would still reach the batch `Value` parse and sink its
/// neighbours, which is the bug. Every case below first passes
/// `IgnoredAny` (the fast path the scan runs after), so the comparison is
/// apples-to-apples.
#[test]
fn surrogate_scan_matches_serde_value_decision() {
// Build every `\uXXXX` escape from a runtime backslash (code point 92)
// so the test source carries no literal escape sequences that a tool
// or editor might normalise — the bytes under test are exactly these.
let bs = char::from_u32(92).unwrap();
let u = |hex: &str| format!("{bs}u{hex}");
let body = |inner: String| format!(r#"{{"body":"{inner}"}}"#).into_bytes();
let key = |inner: String| format!(r#"{{"{inner}":"v"}}"#).into_bytes();
let cases: Vec<Vec<u8>> = vec![
body("plain ascii".to_string()),
body(format!("emoji {}{} ok", u("d83d"), u("de00"))), // valid pair
body(format!("clef {}{}", u("d834"), u("dd1e"))), // valid astral pair
body(format!("a{}b", u("d83d"))), // lone high (issue #1304)
body(u("d83d")), // lone high at string end
body(format!("{} low", u("dc00"))), // lone low surrogate
body(format!("{}{}", u("d83d"), u("0041"))), // high then a non-low escape
body(format!("{}text", u("d83d"))), // high then plain text
body(format!("{}{}", u("dc00"), u("d83d"))), // low before high (both wrong)
body(format!("escaped {}{}u1234 literal", bs, bs)), // `\\u1234` is not an escape
body(format!("{}t {}n {}{} tame", bs, bs, bs, bs)), // ordinary escapes only
body(format!("bom {} null {}", u("feff"), u("0000"))), // valid non-surrogate escapes
key(format!("{}{}", u("d83d"), u("de00"))), // valid pair in an object key
key(u("d83d")), // lone surrogate in a key
];
for raw in &cases {
let readable = String::from_utf8_lossy(raw);
assert!(
serde_json::from_slice::<serde::de::IgnoredAny>(raw).is_ok(),
"precondition: IgnoredAny should accept {readable:?}",
);
let scan_rejects = lone_surrogate_escape_reason(raw).is_some();
let value_rejects = serde_json::from_slice::<serde_json::Value>(raw).is_err();
assert_eq!(
scan_rejects, value_rejects,
"scan and serde_json::Value disagree on {readable:?}",
);
}
}
/// Issue #1304: a single auto-id document carrying an unpaired UTF-16
/// surrogate must fail per-item while its 127 well-formed neighbours
/// index. Before the fix the whole batch failed with a single
/// `lone leading surrogate in hex escape` and nothing was indexed.
#[tokio::test]
async fn one_lone_surrogate_does_not_sink_its_bulk_batch() {
let name = "issue-1304";
let (_dir, engine) = plain_engine(name);
const TOTAL: usize = 128;
const BAD_POS: usize = 42;
let mut body = String::new();
for i in 0..TOTAL {
// Auto-id: no `_id`, so every doc is grouped into one turbo batch.
body.push_str(&format!("{{\"index\":{{\"_index\":\"{name}\"}}}}\n"));
if i == BAD_POS {
// `"a" + String.fromCharCode(0xd83d) + "b"` -> `"a\ud83db"`.
body.push_str("{\"body\":\"a\\ud83db\"}\n");
} else {
body.push_str(&format!("{{\"body\":\"chunk {i} is well formed\"}}\n"));
}
}
let result = process_bulk(&engine, None, &body).await;
assert!(
result.errors,
"a batch containing one bad document must report errors=true",
);
assert_eq!(result.items.len(), TOTAL);
let failed: Vec<usize> = result
.items
.iter()
.enumerate()
.filter(|(_, item)| item.status != 201)
.map(|(i, _)| i)
.collect();
assert_eq!(
failed,
vec![BAD_POS],
"exactly the one unpaired-surrogate document must fail, not its neighbours",
);
let bad = &result.items[BAD_POS];
assert_eq!(bad.status, 400, "the bad document is a 400, not a 500");
assert!(
bad.error
.as_deref()
.unwrap_or_default()
.contains("surrogate"),
"the per-item error should name the surrogate: {:?}",
bad.error,
);
// The 127 good documents are actually indexed, not merely acked.
let index = engine.get_index(name).unwrap();
index.refresh().await.unwrap();
assert_eq!(
index.live_doc_count(),
(TOTAL - 1) as u64,
"every well-formed document in the batch must be indexed",
);
}
/// Two bad documents in the same batch each fail on their own; the rest
/// still index. Guards against an off-by-one in the per-item routing.
#[tokio::test]
async fn multiple_bad_surrogates_each_fail_individually() {
let name = "issue-1304-multi";
let (_dir, engine) = plain_engine(name);
const TOTAL: usize = 64;
let bad_positions = [7usize, 50];
let mut body = String::new();
for i in 0..TOTAL {
body.push_str(&format!("{{\"index\":{{\"_index\":\"{name}\"}}}}\n"));
if bad_positions.contains(&i) {
body.push_str("{\"body\":\"\\udc00 trailing\"}\n");
} else {
body.push_str(&format!("{{\"body\":\"doc {i}\"}}\n"));
}
}
let result = process_bulk(&engine, None, &body).await;
assert!(result.errors);
let failed: Vec<usize> = result
.items
.iter()
.enumerate()
.filter(|(_, item)| item.status != 201)
.map(|(i, _)| i)
.collect();
assert_eq!(failed, bad_positions.to_vec());
let index = engine.get_index(name).unwrap();
index.refresh().await.unwrap();
assert_eq!(index.live_doc_count(), (TOTAL - bad_positions.len()) as u64);
}
}
#[cfg(test)]
mod parse_admission_tests {
use super::*;
#[test]
fn action_line_kind_reads_the_first_key_without_parsing() {
assert_eq!(action_line_kind(r#"{"index":{"_index":"a"}}"#), "index");
assert_eq!(action_line_kind(r#" { "create":{}}"#), "create");
assert_eq!(action_line_kind(r#"{"update":{"_id":"1"}}"#), "update");
assert_eq!(action_line_kind(r#"{"delete":{"_id":"1"}}"#), "delete");
assert_eq!(action_line_kind("not json"), "index");
}
/// #2427: a request refused before its parse answers one 429 per action,
/// in body order, so a client re-offering 429 items by position can map
/// every item back onto the body it sent.
#[test]
fn a_refused_bulk_answers_one_429_per_action() {
let pairs: Vec<(usize, &str, Option<&str>, usize)> = vec![
(0, r#"{"index":{}}"#, Some(r#"{"a":1}"#), 0),
(2, r#"{"delete":{"_id":"x"}}"#, None, 1),
(3, r#"{"update":{"_id":"y"}}"#, Some(r#"{"doc":{}}"#), 2),
];
let error = EngineError::Common(xerj_common::XerjError::circuit_breaking(
"[parent] real memory circuit breaker tripped",
));
let items = refuse_every_action(&pairs, Some("logs"), &error);
assert_eq!(items.len(), 3);
assert_eq!(
items.iter().map(|i| i.action.as_str()).collect::<Vec<_>>(),
["index", "delete", "update"]
);
for item in &items {
assert_eq!(item.status, 429);
assert_eq!(item.index, "logs");
assert!(item.error.as_deref().unwrap().contains("circuit breaker"));
}
}
}
#[cfg(test)]
mod explicit_id_batch_tests {
use super::*;
use serde_json::json;
use tempfile::TempDir;
use xerj_common::config::Config;
use xerj_common::types::{EmbeddingConfig, FieldConfig, FieldType, Schema};
fn engine_with(name: &str, schema: Schema) -> (TempDir, Engine) {
let dir = TempDir::new().unwrap();
let mut config = Config::default();
config.server.data_dir = dir.path().to_string_lossy().into_owned();
let engine = Engine::new(config).unwrap();
engine.create_index(name, schema).unwrap();
(dir, engine)
}
fn statuses(result: &BulkResult) -> Vec<(u16, Option<String>)> {
result
.items
.iter()
.map(|item| (item.status, item.result.clone()))
.collect()
}
fn created() -> (u16, Option<String>) {
(201, Some("created".into()))
}
fn updated() -> (u16, Option<String>) {
(200, Some("updated".into()))
}
/// #2427: explicit-id `index` actions were published one
/// `index_document` call at a time, each also copying the source into
/// the storage memtable. They now go through one turbo batch, which
/// keeps only the WAL + FTS representation, while `created`/`updated`
/// and `_version` stay exactly what the per-doc path reported.
#[tokio::test]
async fn explicit_id_index_actions_publish_as_one_batch() {
let name = "explicit-id-batch";
let (_dir, engine) = engine_with(name, Schema::empty());
let body = format!(
"{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"a\"}}}}\n{{\"n\":1,\"t\":\"alpha\"}}\n\
{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"b\"}}}}\n{{\"n\":2,\"t\":\"beta\"}}\n\
{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"a\"}}}}\n{{\"n\":3,\"t\":\"alpha again\"}}\n"
);
EXPLICIT_ID_BATCHES.with(|count| count.set(0));
let result = process_bulk(&engine, None, &body).await;
assert!(!result.errors, "{:?}", result.items);
assert_eq!(statuses(&result), vec![created(), created(), updated()]);
assert_eq!(EXPLICIT_ID_BATCHES.with(|count| count.get()), 1);
let idx = engine.get_or_create_index(name).unwrap();
assert_eq!(
idx.resident_memtable_entries(),
0,
"explicit-id bulk documents were copied into the storage memtable one by one"
);
assert_eq!(idx.lookup_version("a"), Some(2));
assert_eq!(idx.lookup_version("b"), Some(1));
let a = idx.get_document("a").await.unwrap().unwrap();
assert_eq!(a["n"], json!(3));
assert_eq!(a["t"], json!("alpha again"));
// A tombstone keeps counting; a re-index after delete is "created".
let body = format!(
"{{\"delete\":{{\"_index\":\"{name}\",\"_id\":\"b\"}}}}\n\
{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"a\"}}}}\n{{\"n\":4}}\n"
);
let result = process_bulk(&engine, None, &body).await;
assert!(!result.errors, "{:?}", result.items);
assert_eq!(idx.lookup_version("a"), Some(3));
assert_eq!(idx.lookup_version("b"), None);
let body = format!("{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"b\"}}}}\n{{\"n\":5}}\n");
let result = process_bulk(&engine, None, &body).await;
assert_eq!(statuses(&result), vec![created()]);
assert_eq!(idx.lookup_version("b"), Some(3));
let b = idx.get_document("b").await.unwrap().unwrap();
assert_eq!(b["n"], json!(5));
}
/// The batch must keep per-document default-format date refusal: one
/// bad date fails only its own item.
#[tokio::test]
async fn explicit_id_batch_keeps_per_item_date_errors() {
let name = "explicit-id-batch-dates";
let mut schema = Schema::empty();
schema.fields.push(FieldConfig::new("ts", FieldType::Date));
let (_dir, engine) = engine_with(name, schema);
let body = format!(
"{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"ok1\"}}}}\n{{\"ts\":\"2024-01-02\"}}\n\
{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"bad\"}}}}\n{{\"ts\":\"not a date\"}}\n\
{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"ok2\"}}}}\n{{\"ts\":\"2024-01-03T04:05:06Z\"}}\n"
);
let result = process_bulk(&engine, None, &body).await;
assert!(result.errors);
assert_eq!(result.items[0].status, 201, "{:?}", result.items);
assert_eq!(result.items[1].status, 400, "{:?}", result.items);
assert_eq!(result.items[1].id, "bad");
assert_eq!(result.items[2].status, 201, "{:?}", result.items);
let idx = engine.get_or_create_index(name).unwrap();
assert!(idx.get_document("bad").await.unwrap().is_none());
assert!(idx.get_document("ok2").await.unwrap().is_some());
}
/// Semantic documents (ingest-memory tracing off) publish their prepared
/// sources as one batch too, vectors included.
#[tokio::test]
async fn semantic_index_actions_publish_as_one_batch() {
let name = "explicit-id-batch-semantic";
let mut schema = Schema::empty();
let mut field = FieldConfig::new("content", FieldType::Text);
field.options.dimensions = Some(16);
field.options.similarity = Some("cosine".to_string());
field.embedding = Some(EmbeddingConfig {
endpoint: None,
model: None,
target_field: Some("content_vector".into()),
});
schema.fields.push(field);
let (_dir, engine) = engine_with(name, schema);
engine
.put_index_mapping(
name,
json!({"properties": {"content": {"type": "semantic_text"}}}),
)
.unwrap();
let body = (0..3)
.map(|i| {
format!(
"{{\"index\":{{\"_index\":\"{name}\",\"_id\":\"{}\"}}}}\n\
{{\"content\":\"semantic document number {i}\"}}\n",
i % 2
)
})
.collect::<String>();
EXPLICIT_ID_BATCHES.with(|count| count.set(0));
let result = process_bulk(&engine, None, &body).await;
assert!(!result.errors, "{:?}", result.items);
assert_eq!(statuses(&result), vec![created(), created(), updated()]);
assert_eq!(EXPLICIT_ID_BATCHES.with(|count| count.get()), 1);
let idx = engine.get_or_create_index(name).unwrap();
assert_eq!(idx.resident_memtable_entries(), 0);
assert_eq!(idx.lookup_version("0"), Some(2));
let doc = idx.get_document("0").await.unwrap().unwrap();
assert_eq!(doc["content"], json!("semantic document number 2"));
assert!(
idx.semantic_vector_fields()
.await
.contains("content_vector"),
"semantic target field missing"
);
}
}