use serde_json::{Map, Value};
#[derive(Debug, Clone, Default)]
pub struct Surface {
pub filter: Vec<String>,
pub select: Vec<String>,
pub limit: Option<usize>,
pub sort: Option<String>,
pub dedupe_by: Option<String>,
pub count_only: bool,
pub truncate_content: Option<usize>,
pub max_output_bytes: Option<usize>,
}
impl Surface {
pub fn active(&self) -> bool {
!self.filter.is_empty()
|| !self.select.is_empty()
|| self.limit.is_some()
|| self.sort.is_some()
|| self.dedupe_by.is_some()
|| self.count_only
|| self.truncate_content.is_some()
|| self.max_output_bytes.is_some()
}
pub fn apply(&self, mut value: Value) -> Result<Value, crate::error::Error> {
if is_failure(&value) || is_summary(&value) {
return Ok(value);
}
for expr in &self.filter {
let _ = parse_filter(expr)?;
}
if let Some(arr) = find_array_mut(&mut value) {
let mut rows = match arr.take() {
Value::Array(rows) => rows,
_ => Vec::new(),
};
rows = apply_filters(rows, &self.filter)?;
if let Some(key) = &self.sort {
rows.sort_by(|a, b| cmp_key(a, b, key));
}
if let Some(key) = &self.dedupe_by {
rows = dedupe(rows, key);
}
if let Some(n) = self.limit {
rows.truncate(n);
}
if !self.select.is_empty() {
rows = rows
.into_iter()
.map(|row| project(row, &self.select))
.collect();
}
if self.count_only {
return Ok(counted(&value, rows.len()));
}
*arr = Value::Array(rows);
} else if !self.filter.is_empty() || self.limit == Some(0) {
let keep = self.limit != Some(0)
&& apply_filters(vec![value.clone()], &self.filter)?.len() == 1;
if !keep {
if self.count_only {
return Ok(counted(&value, 0));
}
let mut empty = serde_json::json!({});
carry_envelope_identity(&value, &mut empty);
return Ok(empty);
}
if self.count_only {
return Ok(counted(&value, 1));
}
} else if self.count_only {
return Ok(counted(&value, 1));
} else if !self.select.is_empty() {
value = project(value, &self.select);
}
if let Some(n) = self.truncate_content {
if truncate_strings(&mut value, n) {
if let Some(obj) = value.as_object_mut() {
obj.insert("content_truncated".to_string(), Value::Bool(true));
}
}
}
if let Some(max) = self.max_output_bytes {
value = cap_bytes(value, max);
}
Ok(value)
}
}
const ENVELOPE_IDENTITY: &[&str] = &["schema_version", "correlation_id"];
fn counted(source: &Value, n: usize) -> Value {
let mut out = serde_json::json!({ "count": n });
carry_envelope_identity(source, &mut out);
out
}
fn carry_envelope_identity(source: &Value, target: &mut Value) {
let (Some(from), Some(to)) = (source.as_object(), target.as_object_mut()) else {
return;
};
for key in ENVELOPE_IDENTITY {
if let Some(v) = from.get(*key) {
to.entry((*key).to_string()).or_insert_with(|| v.clone());
}
}
}
fn is_summary(value: &Value) -> bool {
value.get("summary").and_then(Value::as_bool) == Some(true)
}
fn is_failure(value: &Value) -> bool {
value.get("error").and_then(Value::as_bool) == Some(true)
|| value.get("ok").and_then(Value::as_bool) == Some(false)
}
const PREFERRED_ROW_KEYS: &[&str] = &[
"models", "checks", "keys", "licenses", "commands", "schemas", "segments",
];
fn find_array_mut(value: &mut Value) -> Option<&mut Value> {
let obj = value.as_object_mut()?;
let arrays: Vec<String> = obj
.iter()
.filter(|(_, v)| v.is_array())
.map(|(k, _)| k.clone())
.collect();
let chosen = match arrays.as_slice() {
[] => return None,
[only] => only.clone(),
many => PREFERRED_ROW_KEYS
.iter()
.find(|k| many.iter().any(|a| a == *k))
.map(|k| (*k).to_string())?,
};
obj.get_mut(&chosen)
}
fn apply_filters(rows: Vec<Value>, filters: &[String]) -> Result<Vec<Value>, crate::error::Error> {
let mut out = rows;
for expr in filters {
let pred = parse_filter(expr)?;
out.retain(|row| pred(row));
}
Ok(out)
}
type RowPredicate = Box<dyn Fn(&Value) -> bool>;
fn parse_filter(expr: &str) -> Result<RowPredicate, crate::error::Error> {
if let Some((k, v)) = expr.split_once("~") {
let k = k.to_string();
let v = v.to_string();
return Ok(Box::new(move |row| {
dotted(row, &k).map(|s| s.contains(&v)).unwrap_or(false)
}));
}
if let Some((k, v)) = expr.split_once("!=") {
let k = k.to_string();
let v = v.to_string();
return Ok(Box::new(move |row| {
dotted(row, &k).map(|s| s != v).unwrap_or(true)
}));
}
if let Some((k, v)) = expr.split_once("==").or_else(|| expr.split_once('=')) {
let k = k.to_string();
let v = v.to_string();
return Ok(Box::new(move |row| {
dotted(row, &k).map(|s| s == v).unwrap_or(false)
}));
}
Err(crate::error::Error::Usage(format!(
"malformed filter: {expr}"
)))
}
fn dotted(row: &Value, key: &str) -> Option<String> {
let mut cur = row;
for part in key.split('.') {
cur = cur.get(part)?;
}
match cur {
Value::String(s) => Some(s.clone()),
Value::Number(n) => Some(n.to_string()),
Value::Bool(b) => Some(b.to_string()),
_ => Some(cur.to_string()),
}
}
fn cmp_key(a: &Value, b: &Value, key: &str) -> std::cmp::Ordering {
use std::cmp::Ordering;
match (dotted(a, key), dotted(b, key)) {
(Some(x), Some(y)) => match (x.parse::<f64>(), y.parse::<f64>()) {
(Ok(xn), Ok(yn)) => xn.partial_cmp(&yn).unwrap_or(Ordering::Equal),
_ => x.cmp(&y),
},
(Some(_), None) => Ordering::Less,
(None, Some(_)) => Ordering::Greater,
(None, None) => Ordering::Equal,
}
}
fn dedupe(rows: Vec<Value>, key: &str) -> Vec<Value> {
let mut seen = std::collections::BTreeSet::new();
let mut out = Vec::new();
for row in rows {
match dotted(&row, key) {
Some(v) if !seen.insert(v.clone()) => {}
_ => out.push(row),
}
}
out
}
fn project(row: Value, keys: &[String]) -> Value {
let mut map = Map::new();
for key in keys {
if let Some(v) = dotted_value(&row, key) {
insert_dotted(&mut map, key, v);
}
}
Value::Object(map)
}
fn dotted_value(row: &Value, key: &str) -> Option<Value> {
let mut cur = row;
for part in key.split('.') {
cur = cur.get(part)?;
}
Some(cur.clone())
}
fn insert_dotted(map: &mut Map<String, Value>, key: &str, value: Value) {
let Some((head, rest)) = key.split_once('.') else {
map.insert(key.to_string(), value);
return;
};
let entry = map
.entry(head.to_string())
.or_insert_with(|| Value::Object(Map::new()));
if let Some(child) = entry.as_object_mut() {
insert_dotted(child, rest, value);
}
}
const TRUNCATION_MARKER: char = '…';
#[allow(clippy::unnecessary_fold)]
pub const CONTENT_KEYS: &[&str] = &["text"];
static ACTIVE_CONTENT_KEYS: std::sync::OnceLock<Vec<String>> = std::sync::OnceLock::new();
pub fn publish_content_keys(keys: Vec<String>) {
let _ = ACTIVE_CONTENT_KEYS.set(keys);
}
fn is_content_key(key: &str) -> bool {
ACTIVE_CONTENT_KEYS.get().map_or_else(
|| CONTENT_KEYS.contains(&key),
|keys| keys.iter().any(|k| k == key),
)
}
fn truncate_scalar(value: &mut Value, max_chars: usize) -> bool {
let Value::String(s) = value else {
return false;
};
if s.chars().count() <= max_chars {
return false;
}
let chars: Vec<char> = s.chars().collect();
let mut keep = max_chars.saturating_sub(1);
while keep > 0
&& chars
.get(keep)
.is_some_and(|c| unicode_normalization::char::is_combining_mark(*c))
{
keep -= 1;
}
let mut out: String = chars.iter().take(keep).collect();
if max_chars > 0 {
out.push(TRUNCATION_MARKER);
}
*s = out;
true
}
fn truncate_strings(value: &mut Value, max_chars: usize) -> bool {
match value {
Value::String(_) => false,
Value::Array(items) => {
let mut cut = false;
for v in items.iter_mut() {
cut |= truncate_strings(v, max_chars);
}
cut
}
Value::Object(map) => map.iter_mut().fold(false, |acc, (key, v)| {
if is_content_key(key.as_str()) && holds_prose(v) {
return truncate_all_strings(v, max_chars) || acc;
}
truncate_strings(v, max_chars) || acc
}),
_ => false,
}
}
fn holds_prose(value: &Value) -> bool {
match value {
Value::String(_) => true,
Value::Array(items) => items.iter().all(|v| matches!(v, Value::String(_))),
_ => false,
}
}
fn truncate_all_strings(value: &mut Value, max_chars: usize) -> bool {
match value {
Value::String(_) => {
let mut scalar = value.take();
let cut = truncate_scalar(&mut scalar, max_chars);
*value = scalar;
cut
}
Value::Array(items) => {
let mut cut = false;
for v in items.iter_mut() {
cut |= truncate_all_strings(v, max_chars);
}
cut
}
Value::Object(map) => {
let mut cut = false;
for (_, v) in map.iter_mut() {
cut |= truncate_all_strings(v, max_chars);
}
cut
}
_ => false,
}
}
fn cap_bytes(value: Value, max: usize) -> Value {
if encoded_len(&value) <= max {
return value;
}
let original = value.clone();
let mut value = value;
if find_array_mut(&mut value).is_some() {
let mut rows = find_array_mut(&mut value)
.and_then(|a| a.as_array().cloned())
.unwrap_or_default();
while !rows.is_empty() {
rows.pop();
let mut clone = value.clone();
if let Some(target) = find_array_mut(&mut clone) {
*target = Value::Array(rows.clone());
}
if let Some(fitted) = fits(&original, &clone, max) {
return fitted;
}
}
if let Some(target) = find_array_mut(&mut value) {
*target = Value::Array(Vec::new());
}
if let Some(fitted) = fits(&original, &value, max) {
return fitted;
}
}
let mut limit = longest_content_len(&value);
while limit > 0 {
limit /= 2;
let mut clone = value.clone();
if truncate_strings(&mut clone, limit) {
if let Some(obj) = clone.as_object_mut() {
obj.insert("content_truncated".to_string(), Value::Bool(true));
}
}
if let Some(fitted) = fits(&original, &clone, max) {
return fitted;
}
}
truncate_strings(&mut value, 0);
announce_if_changed(&original, value)
}
fn fits(original: &Value, candidate: &Value, max: usize) -> Option<Value> {
let marked = announce_if_changed(original, candidate.clone());
(encoded_len(&marked) <= max).then_some(marked)
}
fn announce_if_changed(original: &Value, shaped: Value) -> Value {
if &shaped == original {
return shaped;
}
mark_output_truncated(shaped)
}
fn longest_content_len(value: &Value) -> usize {
match value {
Value::Object(map) => map
.iter()
.map(|(k, v)| {
if is_content_key(k.as_str()) {
longest_string(v)
} else {
longest_content_len(v)
}
})
.max()
.unwrap_or(0),
Value::Array(items) => items.iter().map(longest_content_len).max().unwrap_or(0),
_ => 0,
}
}
fn longest_string(value: &Value) -> usize {
match value {
Value::String(s) => s.chars().count(),
Value::Object(map) => map.values().map(longest_string).max().unwrap_or(0),
Value::Array(items) => items.iter().map(longest_string).max().unwrap_or(0),
_ => 0,
}
}
fn encoded_len(value: &Value) -> usize {
serde_json::to_vec(value).map(|b| b.len()).unwrap_or(0)
}
fn mark_output_truncated(mut value: Value) -> Value {
if let Some(obj) = value.as_object_mut() {
obj.insert("output_truncated".to_string(), Value::Bool(true));
}
value
}
#[cfg(test)]
mod tests {
#[test]
fn cap_holds_when_content_is_not_the_bulk() {
let rows: Vec<serde_json::Value> = (0..400)
.map(|i| serde_json::json!({"start": i as f64, "end": i as f64 + 1.0}))
.collect();
let doc = serde_json::json!({
"schema_version": "0.1.0",
"correlation_id": "cid",
"segments": rows,
});
let shaped = super::cap_bytes(doc, 800);
let len = serde_json::to_vec(&shaped).expect("encode").len();
assert!(len <= 800, "the cap did not hold: {len} bytes");
}
use super::*;
#[test]
fn select_text_only() {
let s = Surface {
select: vec!["text".into()],
..Surface::default()
};
let v = serde_json::json!({"results":[{"text":"hi","file":"a.wav"}]});
let out = s.apply(v).unwrap();
assert_eq!(out["results"][0]["text"], "hi");
assert!(out["results"][0].get("file").is_none());
}
#[test]
fn filter_does_not_hide_error() {
let s = Surface {
filter: vec!["text=nope".into()],
..Surface::default()
};
let v = serde_json::json!({"error":true,"ok":false,"message":"x"});
let out = s.apply(v).unwrap();
assert_eq!(out["error"], true);
}
#[test]
fn summary_survives_select() {
let s = Surface {
select: vec!["text".into()],
..Surface::default()
};
let v = serde_json::json!({"summary":true,"ok":2,"failed":1,"total":3});
let out = s.apply(v).unwrap();
assert_eq!(out["summary"], true);
assert_eq!(out["ok"], 2);
assert_eq!(out["failed"], 1);
assert_eq!(out["total"], 3);
}
#[test]
fn truncate_marks_and_flags() {
let s = Surface {
truncate_content: Some(10),
..Surface::default()
};
let v = serde_json::json!({"results":[{"text":"abcdefghijklmnop"}]});
let out = s.apply(v).unwrap();
let text = out["results"][0]["text"].as_str().unwrap();
assert!(text.ends_with('…'));
assert_eq!(text.chars().count(), 10);
assert_eq!(out["content_truncated"], true);
}
#[test]
fn truncate_does_not_split_utf8() {
let long = "configuração ambígua ".repeat(20);
let s = Surface {
truncate_content: Some(11),
..Surface::default()
};
let v = serde_json::json!({"results":[{"text":long}]});
let out = s.apply(v).unwrap();
let text = out["results"][0]["text"].as_str().unwrap();
assert!(text.chars().count() <= 11);
assert_eq!(text, "configuraç…");
assert_eq!(out["content_truncated"], true);
}
#[test]
fn truncation_never_touches_the_fields_that_identify_the_response() {
let s = Surface {
truncate_content: Some(8),
..Surface::default()
};
let v = serde_json::json!({
"schema_version": "0.1.0",
"correlation_id": "0198c0de-dead-beef-cafe-000000000000",
"file": "/very/long/path/to/some/recording.wav",
"model": "large-v3",
"language_source": "detection",
"results": [{"text": "a transcript long enough to be shortened"}],
});
let out = s.apply(v).unwrap();
assert_eq!(
out["correlation_id"],
"0198c0de-dead-beef-cafe-000000000000"
);
assert_eq!(out["schema_version"], "0.1.0");
assert_eq!(out["file"], "/very/long/path/to/some/recording.wav");
assert_eq!(out["model"], "large-v3");
assert_eq!(out["language_source"], "detection");
let text = out["results"][0]["text"].as_str().unwrap();
assert!(text.chars().count() <= 8, "content is still truncated");
assert_eq!(out["content_truncated"], true);
}
#[test]
fn truncation_never_shortens_a_digest_an_origin_or_a_filename() {
let s = Surface {
truncate_content: Some(4),
..Surface::default()
};
let listing = serde_json::json!({
"models": [{
"name": "tiny",
"filename": "ggml-tiny.bin",
"sha1": "bd577a113a864445d4c299885e0cb97d4ba92b5f",
"url": "https://example.test/ggml-tiny.bin",
}],
});
let out = s.apply(listing).unwrap();
let row = &out["models"][0];
assert_eq!(row["sha1"], "bd577a113a864445d4c299885e0cb97d4ba92b5f");
assert_eq!(row["url"], "https://example.test/ggml-tiny.bin");
assert_eq!(row["filename"], "ggml-tiny.bin");
assert_eq!(row["name"], "tiny");
}
#[test]
fn truncation_still_shortens_the_transcription_text() {
let s = Surface {
truncate_content: Some(4),
..Surface::default()
};
let result = serde_json::json!({
"file": "/long/path/to/recording.wav",
"model": "small",
"text": "a spoken passage long enough to need shortening",
"segments": [
{"start": 0.0, "end": 1.0, "text": "another long spoken passage"},
],
});
let out = s.apply(result).unwrap();
assert!(
out["text"].as_str().expect("text").chars().count() <= 4,
"the one field FR-028 exists to shorten was left whole: {out}"
);
assert!(
out["segments"][0]["text"]
.as_str()
.expect("segment text")
.chars()
.count()
<= 4,
"a segment's text is transcription too: {out}"
);
assert_eq!(
out["content_truncated"], true,
"a cut must be announced: {out}"
);
assert_eq!(out["file"], "/long/path/to/recording.wav");
assert_eq!(out["model"], "small");
assert_eq!(out["segments"][0]["start"], 0.0);
}
#[test]
fn truncation_leaves_the_version_verb_byte_identical() {
let s = Surface {
truncate_content: Some(4),
..Surface::default()
};
let identity = serde_json::json!({
"schema_version": "0.1.0",
"correlation_id": "0198c0de-dead-beef-cafe-000000000000",
"name": "whisper-nvidia-cli",
"version": "0.1.0",
"contract_version": "0.1.0",
"engine": "stub",
});
let out = s.apply(identity.clone()).unwrap();
assert_eq!(out, identity, "version must survive any output shaping");
}
#[test]
fn truncate_absent_when_nothing_cut() {
let s = Surface {
truncate_content: Some(64),
..Surface::default()
};
let v = serde_json::json!({"results":[{"text":"curto"}]});
let out = s.apply(v).unwrap();
assert_eq!(out["results"][0]["text"], "curto");
assert!(out.get("content_truncated").is_none());
}
#[test]
fn malformed_filter_is_usage() {
let s = Surface {
filter: vec!["no-operator".into()],
..Surface::default()
};
let v = serde_json::json!({"results":[{"a":1}]});
assert!(s.apply(v).is_err());
}
}
#[cfg(test)]
mod grapheme_truncation_tests {
use super::*;
use serde_json::json;
#[test]
fn truncation_does_not_strip_an_accent_from_its_letter() {
let decomposed = "cafe\u{301}x";
assert_eq!(decomposed.chars().count(), 6, "six code points");
let mut value = json!(decomposed);
assert!(
truncate_scalar(&mut value, 5),
"six chars under a five cap cuts"
);
let out = value.as_str().expect("string");
assert!(
!out.contains('e') || out.contains('\u{301}'),
"the accent was dropped and the letter silently changed: {out:?}"
);
assert_eq!(
out, "caf\u{2026}",
"the whole cluster leaves, not half of it"
);
}
#[test]
fn precomposed_letters_are_kept_as_normal_characters() {
let mut value = json!("caf\u{e9}xy");
assert!(
truncate_scalar(&mut value, 5),
"five code points under a five cap"
);
assert_eq!(
value.as_str().expect("string"),
"caf\u{e9}\u{2026}",
"a precomposed letter is one character and must be kept"
);
}
#[test]
fn a_string_of_bare_marks_terminates() {
let mut value = json!("\u{301}\u{301}\u{301}\u{301}");
assert!(
truncate_scalar(&mut value, 2),
"four chars under a two cap cuts"
);
assert_eq!(
value.as_str().expect("string"),
"\u{2026}",
"nothing to keep"
);
}
}