1use std::fs;
7use std::io::{Read, Write};
8use std::os::fd::AsFd;
9use std::path::{Path, PathBuf};
10use std::process::{Child, ChildStdin, ChildStdout, Command, Stdio};
11use std::thread;
12use std::time::{Duration, Instant};
13
14use nix::fcntl::{FcntlArg, OFlag, fcntl};
15use nix::poll::{PollFd, PollFlags, PollTimeout, poll};
16use serde::Deserialize;
17use thiserror::Error;
18use tiktoken::CoreBpe;
19
20const REQUEST_MAGIC: &[u8; 4] = b"OPF1";
21const RESPONSE_MAGIC: &[u8; 4] = b"OPR1";
22const OP_INFER: u8 = 1;
23const OP_PING: u8 = 2;
24const OP_SHUTDOWN: u8 = 3;
25const MAX_SEQUENCES: usize = 128;
26const MAX_SEQUENCE_TOKENS: usize = 131_072;
27const MAX_SEQUENCE_BYTES: usize = 16 * 1024 * 1024;
28const MAX_TOKENS_PER_REQUEST: usize = MAX_SEQUENCES * MAX_SEQUENCE_TOKENS;
29const MAX_ERROR_BYTES: usize = 64 * 1024;
30const PIPE_WRITE_CHUNK: usize = 4 * 1024;
31
32pub const CLIENT_VERSION: &str = env!("CARGO_PKG_VERSION");
33
34#[derive(Debug, Error)]
35pub enum Error {
36 #[error("failed to start or communicate with the MLX server: {0}")]
37 Io(#[from] std::io::Error),
38 #[error("invalid protocol response: {0}")]
39 Protocol(String),
40 #[error("MLX server error: {0}")]
41 Server(String),
42 #[error("tokenizer error: {0}")]
43 Tokenizer(String),
44 #[error("failed to read Viterbi calibration")]
45 CalibrationIo(#[source] std::io::Error),
46 #[error("invalid Viterbi calibration")]
47 CalibrationJson(#[source] serde_json::Error),
48 #[error("invalid MLX server configuration: {0}")]
49 Configuration(&'static str),
50 #[error(
51 "lossless chunking is unavailable for a {required_tokens}-token input with a {chunk_tokens}-token trace; use detect_chunked_batch_approximate only when boundary-dependent output is acceptable"
52 )]
53 LosslessChunkingUnavailable {
54 required_tokens: usize,
55 chunk_tokens: usize,
56 },
57 #[error("MLX server {operation} timed out after {timeout:?}")]
58 Timeout {
59 operation: &'static str,
60 timeout: Duration,
61 },
62 #[error("MLX server is no longer available after an earlier failure")]
63 Unavailable,
64}
65
66#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
67pub enum Label {
68 AccountNumber,
69 PrivateAddress,
70 PrivateDate,
71 PrivateEmail,
72 PrivatePerson,
73 PrivatePhone,
74 PrivateUrl,
75 Secret,
76}
77
78impl Label {
79 pub fn as_str(self) -> &'static str {
80 match self {
81 Self::AccountNumber => "account_number",
82 Self::PrivateAddress => "private_address",
83 Self::PrivateDate => "private_date",
84 Self::PrivateEmail => "private_email",
85 Self::PrivatePerson => "private_person",
86 Self::PrivatePhone => "private_phone",
87 Self::PrivateUrl => "private_url",
88 Self::Secret => "secret",
89 }
90 }
91
92 pub fn placeholder(self) -> &'static str {
93 match self {
94 Self::AccountNumber => "<ACCOUNT_NUMBER>",
95 Self::PrivateAddress => "<PRIVATE_ADDRESS>",
96 Self::PrivateDate => "<PRIVATE_DATE>",
97 Self::PrivateEmail => "<PRIVATE_EMAIL>",
98 Self::PrivatePerson => "<PRIVATE_PERSON>",
99 Self::PrivatePhone => "<PRIVATE_PHONE>",
100 Self::PrivateUrl => "<PRIVATE_URL>",
101 Self::Secret => "<SECRET>",
102 }
103 }
104
105 fn from_index(index: u8) -> Option<Self> {
106 Some(match index {
107 0 => Self::AccountNumber,
108 1 => Self::PrivateAddress,
109 2 => Self::PrivateDate,
110 3 => Self::PrivateEmail,
111 4 => Self::PrivatePerson,
112 5 => Self::PrivatePhone,
113 6 => Self::PrivateUrl,
114 7 => Self::Secret,
115 _ => return None,
116 })
117 }
118}
119
120#[derive(Clone, Debug, Eq, PartialEq)]
121pub struct Span {
122 pub label: Label,
123 pub start: usize,
125 pub end: usize,
127}
128
129#[derive(Clone, Debug, Eq, PartialEq)]
130pub struct Detection {
131 pub spans: Vec<Span>,
132}
133
134impl Detection {
135 pub fn redact(&self, text: &str) -> String {
136 let mut spans = self
137 .spans
138 .iter()
139 .filter(|span| {
140 span.end <= text.len()
141 && span.end > span.start
142 && text.is_char_boundary(span.start)
143 && text.is_char_boundary(span.end)
144 })
145 .cloned()
146 .collect::<Vec<_>>();
147 spans.sort_by_key(|span| (span.start, span.end, span.label));
148 let mut merged: Vec<Span> = Vec::with_capacity(spans.len());
149 for span in spans {
150 if let Some(previous) = merged.last_mut()
151 && span.start < previous.end
152 {
153 previous.end = previous.end.max(span.end);
154 if span.label == Label::Secret {
155 previous.label = Label::Secret;
156 }
157 continue;
158 }
159 merged.push(span);
160 }
161
162 let mut output = String::with_capacity(text.len());
163 let mut cursor = 0;
164 for span in merged {
165 output.push_str(&text[cursor..span.start]);
166 output.push_str(span.label.placeholder());
167 cursor = span.end;
168 }
169 output.push_str(&text[cursor..]);
170 output
171 }
172}
173
174#[derive(Clone, Copy, Debug, Eq, PartialEq)]
175pub struct FixedTraceShape {
176 pub batch: usize,
178 pub tokens: usize,
180}
181
182#[derive(Clone, Debug)]
183pub struct ServerOptions {
184 pub memory_limit_gb: Option<f64>,
185 pub cache_limit_gb: Option<f64>,
189 pub max_batch_tokens: usize,
193 pub viterbi_biases: Option<[f32; 6]>,
196 pub viterbi_calibration_path: Option<PathBuf>,
199 pub startup_timeout: Duration,
201 pub io_timeout: Duration,
203 pub shutdown_timeout: Duration,
205 pub prewarm_fixed_trace: bool,
209 pub log_memory_stats: bool,
211}
212
213impl Default for ServerOptions {
214 fn default() -> Self {
215 Self {
216 memory_limit_gb: None,
217 cache_limit_gb: Some(0.5),
218 max_batch_tokens: 32_768,
219 viterbi_biases: None,
220 viterbi_calibration_path: None,
221 startup_timeout: Duration::from_secs(60),
222 io_timeout: Duration::from_secs(5 * 60),
223 shutdown_timeout: Duration::from_secs(2),
224 prewarm_fixed_trace: true,
225 log_memory_stats: false,
226 }
227 }
228}
229
230pub struct PrivacyFilter {
231 child: Child,
232 input: ChildStdin,
233 output: ChildStdout,
234 tokenizer: &'static CoreBpe,
235 fixed_trace_tokens: Option<usize>,
236 io_timeout: Duration,
237 shutdown_timeout: Duration,
238 available: bool,
239}
240
241impl PrivacyFilter {
242 pub fn spawn(
243 server_executable: impl AsRef<Path>,
244 model: impl AsRef<Path>,
245 options: ServerOptions,
246 ) -> Result<Self, Error> {
247 Self::spawn_inner(server_executable.as_ref(), model.as_ref(), options, None)
248 }
249
250 pub fn spawn_fixed(
253 server_executable: impl AsRef<Path>,
254 model: impl AsRef<Path>,
255 options: ServerOptions,
256 fixed_trace: FixedTraceShape,
257 ) -> Result<Self, Error> {
258 Self::spawn_inner(
259 server_executable.as_ref(),
260 model.as_ref(),
261 options,
262 Some(fixed_trace),
263 )
264 }
265
266 fn spawn_inner(
267 server_executable: &Path,
268 model: &Path,
269 options: ServerOptions,
270 fixed_trace: Option<FixedTraceShape>,
271 ) -> Result<Self, Error> {
272 validate_memory_limit(options.memory_limit_gb)?;
273 validate_cache_limit(options.cache_limit_gb)?;
274 validate_fixed_trace(fixed_trace, options.max_batch_tokens)?;
275 let viterbi_biases = resolve_viterbi_biases(model, &options)?;
276 let mut command = Command::new(server_executable);
277 command.arg("--model").arg(model);
278 if let Some(limit) = options.memory_limit_gb {
279 command.arg("--memory-limit-gb").arg(limit.to_string());
280 }
281 command.arg("--cache-limit-gb").arg(
282 options
283 .cache_limit_gb
284 .map_or_else(|| "0".to_owned(), |limit| limit.to_string()),
285 );
286 command
287 .arg("--max-batch-tokens")
288 .arg(options.max_batch_tokens.to_string());
289 if let Some(shape) = fixed_trace {
290 command
291 .arg("--fixed-trace-batch")
292 .arg(shape.batch.to_string())
293 .arg("--fixed-trace-tokens")
294 .arg(shape.tokens.to_string());
295 if options.prewarm_fixed_trace {
296 command.arg("--prewarm-fixed-trace");
297 }
298 }
299 if options.log_memory_stats {
300 command.arg("--log-memory-stats");
301 }
302 let bias_names = [
303 "--bias-background-stay",
304 "--bias-background-to-start",
305 "--bias-inside-to-continue",
306 "--bias-inside-to-end",
307 "--bias-end-to-background",
308 "--bias-end-to-start",
309 ];
310 for (name, value) in bias_names.into_iter().zip(viterbi_biases) {
311 if value != 0.0 {
312 command.arg(name).arg(value.to_string());
313 }
314 }
315 let mut child = command
316 .stdin(Stdio::piped())
317 .stdout(Stdio::piped())
318 .stderr(Stdio::inherit())
319 .spawn()?;
320 let input = child
321 .stdin
322 .take()
323 .ok_or_else(|| Error::Protocol("missing child stdin".into()))?;
324 let output = child
325 .stdout
326 .take()
327 .ok_or_else(|| Error::Protocol("missing child stdout".into()))?;
328 let tokenizer = tiktoken::get_encoding("o200k_base")
329 .ok_or_else(|| Error::Tokenizer("o200k_base is unavailable".into()))?;
330 let mut filter = Self {
331 child,
332 input,
333 output,
334 tokenizer,
335 fixed_trace_tokens: fixed_trace.map(|shape| shape.tokens),
336 io_timeout: options.io_timeout,
337 shutdown_timeout: options.shutdown_timeout,
338 available: true,
339 };
340 if let Err(error) =
341 set_nonblocking(&filter.input).and_then(|()| set_nonblocking(&filter.output))
342 {
343 filter.terminate();
344 return Err(Error::Io(error));
345 }
346 if let Err(error) = filter.ping(options.startup_timeout) {
347 filter.terminate();
348 return Err(error);
349 }
350 Ok(filter)
351 }
352
353 pub fn detect_batch(&mut self, texts: &[&str]) -> Result<Vec<Detection>, Error> {
357 if !self.available {
358 return Err(Error::Unavailable);
359 }
360 let mut output = Vec::with_capacity(texts.len());
361 for chunk in texts.chunks(MAX_SEQUENCES) {
362 let prepared = prepare_request(self.tokenizer, chunk)?;
363 match self.exchange_batch(chunk, &prepared.encoded, prepared.total, &prepared.bytes) {
364 Ok(detections) => output.extend(detections),
365 Err(error) => {
366 self.terminate();
367 return Err(error);
368 }
369 }
370 }
371 Ok(output)
372 }
373
374 pub fn detect_chunked_batch(
378 &mut self,
379 texts: &[&str],
380 chunk_tokens: usize,
381 overlap_tokens: usize,
382 ) -> Result<Vec<Detection>, Error> {
383 if !self.available {
384 return Err(Error::Unavailable);
385 }
386 validate_chunk_configuration(chunk_tokens, overlap_tokens)?;
387 let trace_tokens = lossless_trace_tokens(chunk_tokens, self.fixed_trace_tokens);
388 validate_lossless_chunk_request(self.tokenizer, texts, trace_tokens)?;
389 self.detect_batch(texts)
390 }
391
392 pub fn detect_chunked_batch_approximate(
396 &mut self,
397 texts: &[&str],
398 chunk_tokens: usize,
399 overlap_tokens: usize,
400 ) -> Result<Vec<Detection>, Error> {
401 if !self.available {
402 return Err(Error::Unavailable);
403 }
404 validate_chunk_configuration(chunk_tokens, overlap_tokens)?;
405 validate_approximate_trace_tokens(chunk_tokens, self.fixed_trace_tokens)?;
406 let mut combined = vec![Vec::new(); texts.len()];
407 let mut pending = Vec::with_capacity(MAX_SEQUENCES);
408 let mut pending_tokens = 0usize;
409
410 for (source_index, text) in texts.iter().enumerate() {
411 let encoded = Encoded::new(self.tokenizer, text)?;
412 for chunk in encoded.overlapping_chunks(chunk_tokens, overlap_tokens)? {
413 let tokens = chunk.tokens.len();
414 if !pending.is_empty()
415 && (pending.len() == MAX_SEQUENCES
416 || pending_tokens.saturating_add(tokens) > MAX_TOKENS_PER_REQUEST)
417 {
418 self.exchange_chunk_batch(&mut pending, &mut combined)?;
419 pending_tokens = 0;
420 }
421 pending_tokens = pending_tokens
422 .checked_add(tokens)
423 .ok_or_else(|| Error::Protocol("chunked batch token count overflow".into()))?;
424 pending.push(EncodedChunk {
425 source_index,
426 text,
427 encoded: chunk,
428 });
429 }
430 }
431 self.exchange_chunk_batch(&mut pending, &mut combined)?;
432
433 Ok(combined
434 .into_iter()
435 .map(|mut spans| {
436 spans.sort_by_key(|span| (span.start, span.end, span.label));
437 spans.dedup();
438 Detection { spans }
439 })
440 .collect())
441 }
442
443 fn exchange_chunk_batch(
444 &mut self,
445 pending: &mut Vec<EncodedChunk<'_>>,
446 combined: &mut [Vec<Span>],
447 ) -> Result<(), Error> {
448 if pending.is_empty() {
449 return Ok(());
450 }
451 let mut source_indices = Vec::with_capacity(pending.len());
452 let mut texts = Vec::with_capacity(pending.len());
453 let mut encoded = Vec::with_capacity(pending.len());
454 for chunk in pending.drain(..) {
455 source_indices.push(chunk.source_index);
456 texts.push(chunk.text);
457 encoded.push(chunk.encoded);
458 }
459 let prepared = prepare_encoded_request(encoded)?;
460 let detections =
461 match self.exchange_batch(&texts, &prepared.encoded, prepared.total, &prepared.bytes) {
462 Ok(detections) => detections,
463 Err(error) => {
464 self.terminate();
465 return Err(error);
466 }
467 };
468 for (source_index, detection) in source_indices.into_iter().zip(detections) {
469 combined[source_index].extend(detection.spans);
470 }
471 Ok(())
472 }
473
474 fn exchange_batch(
475 &mut self,
476 texts: &[&str],
477 encoded: &[Encoded],
478 total: usize,
479 request: &[u8],
480 ) -> Result<Vec<Detection>, Error> {
481 let deadline = deadline_after(self.io_timeout);
482 write_all_before(
483 &mut self.input,
484 request,
485 deadline,
486 self.io_timeout,
487 "request write",
488 )?;
489 let (status, count, declared_labels) =
490 read_response_header_before(&mut self.output, deadline, self.io_timeout)?;
491 if status != 0 {
492 if declared_labels as usize > MAX_ERROR_BYTES {
493 return Err(Error::Protocol("server error message is too large".into()));
494 }
495 let mut message = vec![0; declared_labels as usize];
496 read_exact_before(
497 &mut self.output,
498 &mut message,
499 deadline,
500 self.io_timeout,
501 "error response read",
502 )?;
503 return Err(Error::Server(
504 String::from_utf8_lossy(&message).into_owned(),
505 ));
506 }
507 if count as usize != encoded.len() || declared_labels as usize != total {
508 return Err(Error::Protocol(
509 "response dimensions do not match request".into(),
510 ));
511 }
512 let mut lengths = Vec::with_capacity(count as usize);
513 for expected in 0..count {
514 let id = read_u64_before(&mut self.output, deadline, self.io_timeout)?;
515 let length = read_u32_before(&mut self.output, deadline, self.io_timeout)?;
516 let _reserved = read_u32_before(&mut self.output, deadline, self.io_timeout)?;
517 if id != expected as u64 || length as usize != encoded[expected as usize].tokens.len() {
518 return Err(Error::Protocol(
519 "response sequence metadata mismatch".into(),
520 ));
521 }
522 lengths.push(length as usize);
523 }
524 let mut detections = Vec::with_capacity(encoded.len());
525 for ((text, item), length) in texts.iter().zip(encoded).zip(lengths) {
526 let mut labels = vec![0u8; length];
527 read_exact_before(
528 &mut self.output,
529 &mut labels,
530 deadline,
531 self.io_timeout,
532 "inference response read",
533 )?;
534 detections.push(Detection {
535 spans: decode_spans(text, item, &labels)?,
536 });
537 }
538 Ok(detections)
539 }
540
541 pub fn detect(&mut self, text: &str) -> Result<Detection, Error> {
542 self.detect_batch(&[text])?
543 .pop()
544 .ok_or_else(|| Error::Protocol("empty response".into()))
545 }
546
547 fn ping(&mut self, timeout: Duration) -> Result<(), Error> {
548 let request = control_request(OP_PING);
549 let deadline = deadline_after(timeout);
550 write_all_before(
551 &mut self.input,
552 &request,
553 deadline,
554 timeout,
555 "startup ping write",
556 )?;
557 let (status, count, labels) =
558 read_response_header_before(&mut self.output, deadline, timeout)?;
559 if status != 0 || count != 0 || labels != 0 {
560 return Err(Error::Protocol("invalid startup ping response".into()));
561 }
562 Ok(())
563 }
564
565 fn terminate(&mut self) {
566 self.available = false;
567 let _ = self.child.kill();
568 let _ = self.child.wait();
569 }
570}
571
572impl Drop for PrivacyFilter {
573 fn drop(&mut self) {
574 if !self.available {
575 return;
576 }
577 let request = control_request(OP_SHUTDOWN);
578 let deadline = deadline_after(self.shutdown_timeout);
579 let _ = write_all_before(
580 &mut self.input,
581 &request,
582 deadline,
583 self.shutdown_timeout,
584 "shutdown write",
585 );
586 loop {
587 match self.child.try_wait() {
588 Ok(Some(_)) => return,
589 Ok(None) if Instant::now() < deadline => {
590 thread::sleep(Duration::from_millis(10));
591 }
592 Ok(None) | Err(_) => break,
593 }
594 }
595 self.terminate();
596 }
597}
598
599struct Encoded {
600 tokens: Vec<u32>,
601 token_starts: Vec<usize>,
602 token_ends: Vec<usize>,
603}
604
605struct PreparedRequest {
606 encoded: Vec<Encoded>,
607 total: usize,
608 bytes: Vec<u8>,
609}
610
611struct EncodedChunk<'a> {
612 source_index: usize,
613 text: &'a str,
614 encoded: Encoded,
615}
616
617#[derive(Deserialize)]
618#[serde(deny_unknown_fields)]
619struct CalibrationArtifact {
620 operating_points: CalibrationOperatingPoints,
621}
622
623#[derive(Deserialize)]
624#[serde(deny_unknown_fields)]
625struct CalibrationOperatingPoints {
626 default: CalibrationPoint,
627}
628
629#[derive(Deserialize)]
630#[serde(deny_unknown_fields)]
631struct CalibrationPoint {
632 biases: CalibrationBiases,
633}
634
635#[derive(Deserialize)]
636#[serde(deny_unknown_fields)]
637struct CalibrationBiases {
638 transition_bias_background_stay: f32,
639 transition_bias_background_to_start: f32,
640 transition_bias_inside_to_continue: f32,
641 transition_bias_inside_to_end: f32,
642 transition_bias_end_to_background: f32,
643 transition_bias_end_to_start: f32,
644}
645
646impl Encoded {
647 fn new(tokenizer: &CoreBpe, text: &str) -> Result<Self, Error> {
648 if text.len() > MAX_SEQUENCE_BYTES {
649 return Err(Error::Protocol(format!(
650 "sequence exceeds {MAX_SEQUENCE_BYTES} bytes"
651 )));
652 }
653 if text.len() > MAX_SEQUENCE_TOKENS
654 && tokenizer.count_with_special_tokens(text) > MAX_SEQUENCE_TOKENS
655 {
656 return Err(Error::Protocol(format!(
657 "sequence exceeds {MAX_SEQUENCE_TOKENS} tokens"
658 )));
659 }
660 let tokens = tokenizer.encode_with_special_tokens(text);
661 if tokens.len() > MAX_SEQUENCE_TOKENS {
662 return Err(Error::Protocol(format!(
663 "sequence exceeds {MAX_SEQUENCE_TOKENS} tokens"
664 )));
665 }
666 let mut token_starts = Vec::with_capacity(tokens.len());
667 let mut token_ends = Vec::with_capacity(tokens.len());
668 let mut decoded = Vec::with_capacity(text.len());
669 for &token in &tokens {
670 token_starts.push(decoded.len());
671 decoded.extend(tokenizer.decode(&[token]));
672 token_ends.push(decoded.len());
673 }
674 if decoded != text.as_bytes() {
675 return Err(Error::Tokenizer(
676 "token bytes do not reconstruct the source text".into(),
677 ));
678 }
679 Ok(Self {
680 tokens,
681 token_starts,
682 token_ends,
683 })
684 }
685
686 fn overlapping_chunks(
687 &self,
688 chunk_tokens: usize,
689 overlap_tokens: usize,
690 ) -> Result<Vec<Self>, Error> {
691 validate_chunk_configuration(chunk_tokens, overlap_tokens)?;
692 if self.tokens.is_empty() {
693 return Ok(vec![Self {
694 tokens: Vec::new(),
695 token_starts: Vec::new(),
696 token_ends: Vec::new(),
697 }]);
698 }
699 let stride = chunk_tokens - overlap_tokens;
700 let mut chunks = Vec::with_capacity(self.tokens.len().div_ceil(stride));
701 let mut start = 0;
702 loop {
703 let end = (start + chunk_tokens).min(self.tokens.len());
704 chunks.push(Self {
705 tokens: self.tokens[start..end].to_vec(),
706 token_starts: self.token_starts[start..end].to_vec(),
707 token_ends: self.token_ends[start..end].to_vec(),
708 });
709 if end == self.tokens.len() {
710 break;
711 }
712 start += stride;
713 }
714 Ok(chunks)
715 }
716}
717
718fn prepare_request(tokenizer: &CoreBpe, texts: &[&str]) -> Result<PreparedRequest, Error> {
719 let mut encoded = Vec::with_capacity(texts.len());
720 for text in texts {
721 encoded.push(Encoded::new(tokenizer, text)?);
722 }
723 prepare_encoded_request(encoded)
724}
725
726fn prepare_encoded_request(encoded: Vec<Encoded>) -> Result<PreparedRequest, Error> {
727 let total = encoded.iter().try_fold(0usize, |total, item| {
728 total
729 .checked_add(item.tokens.len())
730 .filter(|&count| count <= MAX_TOKENS_PER_REQUEST)
731 .ok_or_else(|| Error::Protocol("batch is too large".into()))
732 })?;
733 let mut bytes = Vec::with_capacity(16 + encoded.len() * 16 + total * 4);
734 bytes.extend_from_slice(REQUEST_MAGIC);
735 bytes.extend_from_slice(&[OP_INFER, 0, 0, 0]);
736 bytes.extend_from_slice(&(encoded.len() as u32).to_le_bytes());
737 bytes.extend_from_slice(&(total as u32).to_le_bytes());
738 for (index, item) in encoded.iter().enumerate() {
739 bytes.extend_from_slice(&(index as u64).to_le_bytes());
740 bytes.extend_from_slice(&(item.tokens.len() as u32).to_le_bytes());
741 bytes.extend_from_slice(&0u32.to_le_bytes());
742 }
743 for item in &encoded {
744 for &token in &item.tokens {
745 bytes.extend_from_slice(&token.to_le_bytes());
746 }
747 }
748
749 Ok(PreparedRequest {
750 encoded,
751 total,
752 bytes,
753 })
754}
755
756fn validate_chunk_configuration(chunk_tokens: usize, overlap_tokens: usize) -> Result<(), Error> {
757 if chunk_tokens == 0 || chunk_tokens > MAX_SEQUENCE_TOKENS || overlap_tokens > chunk_tokens / 2
758 {
759 return Err(Error::Configuration(
760 "chunk_tokens must be within the model context and at least twice overlap_tokens",
761 ));
762 }
763 Ok(())
764}
765
766fn lossless_trace_tokens(
767 requested_chunk_tokens: usize,
768 fixed_trace_tokens: Option<usize>,
769) -> usize {
770 fixed_trace_tokens.map_or(requested_chunk_tokens, |fixed_trace_tokens| {
771 requested_chunk_tokens.min(fixed_trace_tokens)
772 })
773}
774
775fn validate_approximate_trace_tokens(
776 chunk_tokens: usize,
777 fixed_trace_tokens: Option<usize>,
778) -> Result<(), Error> {
779 if let Some(fixed_trace_tokens) = fixed_trace_tokens
780 && chunk_tokens > fixed_trace_tokens
781 {
782 return Err(Error::Configuration(
783 "chunk_tokens must not exceed the configured fixed trace token length",
784 ));
785 }
786 Ok(())
787}
788
789fn validate_lossless_chunk_request(
790 tokenizer: &CoreBpe,
791 texts: &[&str],
792 chunk_tokens: usize,
793) -> Result<(), Error> {
794 for text in texts {
795 if text.len() > MAX_SEQUENCE_BYTES {
796 return Err(Error::Protocol(format!(
797 "sequence exceeds {MAX_SEQUENCE_BYTES} bytes"
798 )));
799 }
800 let tokens = tokenizer.count_with_special_tokens(text);
801 if tokens > MAX_SEQUENCE_TOKENS {
802 return Err(Error::Protocol(format!(
803 "sequence exceeds {MAX_SEQUENCE_TOKENS} tokens"
804 )));
805 }
806 if tokens > chunk_tokens {
807 return Err(Error::LosslessChunkingUnavailable {
808 required_tokens: tokens,
809 chunk_tokens,
810 });
811 }
812 }
813 Ok(())
814}
815
816fn resolve_viterbi_biases(model: &Path, options: &ServerOptions) -> Result<[f32; 6], Error> {
817 if options.viterbi_biases.is_some() && options.viterbi_calibration_path.is_some() {
818 return Err(Error::Configuration(
819 "viterbi_biases and viterbi_calibration_path are mutually exclusive",
820 ));
821 }
822 let biases = match options.viterbi_biases {
823 Some(biases) => biases,
824 None => {
825 let default_path = model
826 .parent()
827 .unwrap_or_else(|| Path::new("."))
828 .join("viterbi_calibration.json");
829 let path = options
830 .viterbi_calibration_path
831 .as_deref()
832 .unwrap_or(&default_path);
833 load_viterbi_biases(path)?
834 }
835 };
836 if biases.iter().any(|value| !value.is_finite()) {
837 return Err(Error::Configuration(
838 "Viterbi calibration biases must be finite",
839 ));
840 }
841 Ok(biases)
842}
843
844fn load_viterbi_biases(path: &Path) -> Result<[f32; 6], Error> {
845 let bytes = fs::read(path).map_err(Error::CalibrationIo)?;
846 let artifact: CalibrationArtifact =
847 serde_json::from_slice(&bytes).map_err(Error::CalibrationJson)?;
848 let biases = artifact.operating_points.default.biases;
849 Ok([
850 biases.transition_bias_background_stay,
851 biases.transition_bias_background_to_start,
852 biases.transition_bias_inside_to_continue,
853 biases.transition_bias_inside_to_end,
854 biases.transition_bias_end_to_background,
855 biases.transition_bias_end_to_start,
856 ])
857}
858
859fn decode_spans(text: &str, encoded: &Encoded, labels: &[u8]) -> Result<Vec<Span>, Error> {
860 if labels.len() != encoded.tokens.len() {
861 return Err(Error::Protocol(
862 "label count differs from token count".into(),
863 ));
864 }
865 let mut token_spans = Vec::<(Label, usize, usize)>::new();
866 let mut open: Option<(Label, usize)> = None;
867 for (index, &class) in labels.iter().enumerate() {
868 if class == 0 {
869 if let Some((label, start)) = open.take() {
870 token_spans.push((label, start, index));
871 }
872 continue;
873 }
874 if class > 32 {
875 return Err(Error::Protocol(format!("invalid label class {class}")));
876 }
877 let label = Label::from_index((class - 1) / 4).unwrap();
878 match (class - 1) % 4 {
879 0 => {
880 if let Some((prior, start)) = open.replace((label, index)) {
881 token_spans.push((prior, start, index));
882 }
883 }
884 1 => {
885 if open.map(|x| x.0) != Some(label)
886 && let Some((prior, start)) = open.replace((label, index))
887 {
888 token_spans.push((prior, start, index));
889 }
890 }
891 2 => {
892 let start = match open.take() {
893 Some((open_label, start)) if open_label == label => start,
894 Some((prior, start)) => {
895 token_spans.push((prior, start, index));
896 index
897 }
898 None => index,
899 };
900 token_spans.push((label, start, index + 1));
901 }
902 3 => {
903 if let Some((prior, start)) = open.take() {
904 token_spans.push((prior, start, index));
905 }
906 token_spans.push((label, index, index + 1));
907 }
908 _ => unreachable!(),
909 }
910 }
911 if let Some((label, start)) = open {
912 token_spans.push((label, start, labels.len()));
913 }
914
915 let mut spans = Vec::with_capacity(token_spans.len());
916 for (label, token_start, token_end) in token_spans {
917 if token_start >= token_end {
918 continue;
919 }
920 let mut start = encoded.token_starts[token_start];
921 let mut end = encoded.token_ends[token_end - 1];
922 while start > 0 && !text.is_char_boundary(start) {
923 start -= 1;
924 }
925 while end < text.len() && !text.is_char_boundary(end) {
926 end += 1;
927 }
928 while start < end {
929 let ch = text[start..end].chars().next().unwrap();
930 if !ch.is_whitespace() {
931 break;
932 }
933 start += ch.len_utf8();
934 }
935 while end > start {
936 let ch = text[start..end].chars().next_back().unwrap();
937 if !ch.is_whitespace() {
938 break;
939 }
940 end -= ch.len_utf8();
941 }
942 if start < end {
943 spans.push(Span { label, start, end });
944 }
945 }
946 spans.sort_by_key(|span| {
947 (
948 span.start,
949 std::cmp::Reverse(span.end - span.start),
950 span.label,
951 )
952 });
953 spans.dedup();
954 Ok(spans)
955}
956
957fn control_request(opcode: u8) -> [u8; 16] {
958 let mut request = [0u8; 16];
959 request[..4].copy_from_slice(REQUEST_MAGIC);
960 request[4] = opcode;
961 request
962}
963
964fn deadline_after(timeout: Duration) -> Instant {
965 Instant::now()
966 .checked_add(timeout)
967 .unwrap_or_else(Instant::now)
968}
969
970fn validate_memory_limit(memory_limit_gb: Option<f64>) -> Result<(), Error> {
971 let Some(memory_limit_gb) = memory_limit_gb else {
972 return Ok(());
973 };
974 const BYTES_PER_GIB: f64 = 1_073_741_824.0;
975 let bytes = memory_limit_gb * BYTES_PER_GIB;
976 if !memory_limit_gb.is_finite()
977 || memory_limit_gb <= 0.0
978 || !bytes.is_finite()
979 || bytes < 1.0
980 || bytes >= usize::MAX as f64
981 {
982 return Err(Error::Configuration(
983 "memory_limit_gb must be finite, positive, at least one byte, and fit in size_t",
984 ));
985 }
986 Ok(())
987}
988
989fn validate_cache_limit(cache_limit_gb: Option<f64>) -> Result<(), Error> {
990 let Some(cache_limit_gb) = cache_limit_gb else {
991 return Ok(());
992 };
993 const BYTES_PER_GIB: f64 = 1_073_741_824.0;
994 let bytes = cache_limit_gb * BYTES_PER_GIB;
995 if !cache_limit_gb.is_finite()
996 || cache_limit_gb <= 0.0
997 || !bytes.is_finite()
998 || bytes < 1.0
999 || bytes >= usize::MAX as f64
1000 {
1001 return Err(Error::Configuration(
1002 "cache_limit_gb must be finite, positive, at least one byte, and fit in size_t",
1003 ));
1004 }
1005 Ok(())
1006}
1007
1008fn validate_fixed_trace(
1009 fixed_trace: Option<FixedTraceShape>,
1010 max_batch_tokens: usize,
1011) -> Result<(), Error> {
1012 if max_batch_tokens == 0 {
1013 return Err(Error::Configuration(
1014 "max_batch_tokens must be greater than zero",
1015 ));
1016 }
1017 let Some(shape) = fixed_trace else {
1018 return Ok(());
1019 };
1020 let Some(padded_tokens) = shape.batch.checked_mul(shape.tokens) else {
1021 return Err(Error::Configuration(
1022 "fixed trace padded-token count overflows usize",
1023 ));
1024 };
1025 if shape.batch == 0 || shape.tokens == 0 || padded_tokens > max_batch_tokens {
1026 return Err(Error::Configuration(
1027 "fixed trace dimensions must be positive and fit max_batch_tokens",
1028 ));
1029 }
1030 Ok(())
1031}
1032
1033fn wait_for_io(
1034 fd: &impl AsFd,
1035 events: PollFlags,
1036 deadline: Instant,
1037 configured_timeout: Duration,
1038 operation: &'static str,
1039) -> Result<(), Error> {
1040 loop {
1041 let remaining = deadline.saturating_duration_since(Instant::now());
1042 if remaining.is_zero() {
1043 return Err(Error::Timeout {
1044 operation,
1045 timeout: configured_timeout,
1046 });
1047 }
1048 let timeout = PollTimeout::try_from(remaining).unwrap_or(PollTimeout::MAX);
1049 let mut descriptors = [PollFd::new(fd.as_fd(), events)];
1050 match poll(&mut descriptors, timeout) {
1051 Ok(0) => {
1052 return Err(Error::Timeout {
1053 operation,
1054 timeout: configured_timeout,
1055 });
1056 }
1057 Ok(_) => return Ok(()),
1058 Err(nix::errno::Errno::EINTR) => continue,
1059 Err(errno) => {
1060 return Err(Error::Io(std::io::Error::from_raw_os_error(errno as i32)));
1061 }
1062 }
1063 }
1064}
1065
1066fn set_nonblocking(fd: &impl AsFd) -> std::io::Result<()> {
1067 let flags = fcntl(fd, FcntlArg::F_GETFL)
1068 .map(OFlag::from_bits_truncate)
1069 .map_err(|errno| std::io::Error::from_raw_os_error(errno as i32))?;
1070 fcntl(fd, FcntlArg::F_SETFL(flags | OFlag::O_NONBLOCK))
1071 .map(|_| ())
1072 .map_err(|errno| std::io::Error::from_raw_os_error(errno as i32))
1073}
1074
1075fn write_all_before(
1076 writer: &mut (impl Write + AsFd),
1077 mut bytes: &[u8],
1078 deadline: Instant,
1079 configured_timeout: Duration,
1080 operation: &'static str,
1081) -> Result<(), Error> {
1082 while !bytes.is_empty() {
1083 wait_for_io(
1084 writer,
1085 PollFlags::POLLOUT,
1086 deadline,
1087 configured_timeout,
1088 operation,
1089 )?;
1090 let chunk_len = bytes.len().min(PIPE_WRITE_CHUNK);
1091 match writer.write(&bytes[..chunk_len]) {
1092 Ok(0) => return Err(Error::Io(std::io::ErrorKind::WriteZero.into())),
1093 Ok(written) => bytes = &bytes[written..],
1094 Err(error) if error.kind() == std::io::ErrorKind::Interrupted => continue,
1095 Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => continue,
1096 Err(error) => return Err(Error::Io(error)),
1097 }
1098 }
1099 Ok(())
1100}
1101
1102fn read_exact_before(
1103 reader: &mut ChildStdout,
1104 mut bytes: &mut [u8],
1105 deadline: Instant,
1106 configured_timeout: Duration,
1107 operation: &'static str,
1108) -> Result<(), Error> {
1109 while !bytes.is_empty() {
1110 wait_for_io(
1111 reader,
1112 PollFlags::POLLIN,
1113 deadline,
1114 configured_timeout,
1115 operation,
1116 )?;
1117 match reader.read(bytes) {
1118 Ok(0) => return Err(Error::Io(std::io::ErrorKind::UnexpectedEof.into())),
1119 Ok(read) => bytes = &mut bytes[read..],
1120 Err(error) if error.kind() == std::io::ErrorKind::Interrupted => continue,
1121 Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => continue,
1122 Err(error) => return Err(Error::Io(error)),
1123 }
1124 }
1125 Ok(())
1126}
1127
1128fn read_u32_before(
1129 reader: &mut ChildStdout,
1130 deadline: Instant,
1131 timeout: Duration,
1132) -> Result<u32, Error> {
1133 let mut bytes = [0u8; 4];
1134 read_exact_before(reader, &mut bytes, deadline, timeout, "response read")?;
1135 Ok(u32::from_le_bytes(bytes))
1136}
1137
1138fn read_u64_before(
1139 reader: &mut ChildStdout,
1140 deadline: Instant,
1141 timeout: Duration,
1142) -> Result<u64, Error> {
1143 let mut bytes = [0u8; 8];
1144 read_exact_before(reader, &mut bytes, deadline, timeout, "response read")?;
1145 Ok(u64::from_le_bytes(bytes))
1146}
1147
1148fn read_response_header_before(
1149 reader: &mut ChildStdout,
1150 deadline: Instant,
1151 timeout: Duration,
1152) -> Result<(u8, u32, u32), Error> {
1153 let mut header = [0u8; 16];
1154 read_exact_before(
1155 reader,
1156 &mut header,
1157 deadline,
1158 timeout,
1159 "response header read",
1160 )?;
1161 if &header[..4] != RESPONSE_MAGIC {
1162 return Err(Error::Protocol("bad response magic".into()));
1163 }
1164 Ok(parse_response_header(header))
1165}
1166
1167fn parse_response_header(header: [u8; 16]) -> (u8, u32, u32) {
1168 let count = u32::from_le_bytes([header[8], header[9], header[10], header[11]]);
1169 let labels = u32::from_le_bytes([header[12], header[13], header[14], header[15]]);
1170 (header[4], count, labels)
1171}
1172
1173#[cfg(test)]
1174mod tests {
1175 use super::*;
1176 use std::fs;
1177 use std::fs::File;
1178 use std::os::unix::fs::PermissionsExt;
1179
1180 #[test]
1181 fn tokenizer_round_trips_and_tracks_split_unicode() {
1182 let tokenizer = tiktoken::get_encoding("o200k_base").unwrap();
1183 let text = "Jordan お誕生日 jordan@example.com";
1184 let encoded = Encoded::new(tokenizer, text).unwrap();
1185 assert_eq!(encoded.token_starts.len(), encoded.tokens.len());
1186 assert_eq!(encoded.token_ends.last().copied(), Some(text.len()));
1187 }
1188
1189 #[test]
1190 fn tokenizer_preserves_official_o200k_special_tokens() {
1191 let tokenizer = tiktoken::get_encoding("o200k_base").unwrap();
1192 let text = "before<|endoftext|>alice@example.com";
1193 let encoded = Encoded::new(tokenizer, text).unwrap();
1194 let special_index = encoded
1195 .tokens
1196 .iter()
1197 .position(|&token| token == 199_999)
1198 .expect("o200k endoftext token should be preserved");
1199
1200 assert_eq!(encoded.tokens, tokenizer.encode_with_special_tokens(text));
1201 assert_ne!(encoded.tokens, tokenizer.encode(text));
1202 assert_eq!(
1203 &text[encoded.token_starts[special_index]..encoded.token_ends[special_index]],
1204 "<|endoftext|>"
1205 );
1206 }
1207
1208 #[test]
1209 fn token_chunks_preserve_global_offsets_and_exact_overlap() {
1210 let tokenizer = tiktoken::get_encoding("o200k_base").unwrap();
1211 let text = format!("{}終わり", "word ".repeat(200));
1212 let encoded = Encoded::new(tokenizer, &text).unwrap();
1213 let chunks = encoded.overlapping_chunks(32, 8).unwrap();
1214
1215 assert!(chunks.len() > 1);
1216 assert_eq!(chunks[0].token_starts[0], 0);
1217 assert_eq!(
1218 chunks.last().and_then(|chunk| chunk.token_ends.last()),
1219 Some(&text.len())
1220 );
1221 for chunk in &chunks {
1222 assert!(chunk.tokens.len() <= 32);
1223 assert_eq!(chunk.tokens.len(), chunk.token_starts.len());
1224 assert_eq!(chunk.tokens.len(), chunk.token_ends.len());
1225 }
1226 for pair in chunks.windows(2) {
1227 assert_eq!(
1228 &pair[0].tokens[pair[0].tokens.len() - 8..],
1229 &pair[1].tokens[..8]
1230 );
1231 }
1232 }
1233
1234 #[test]
1235 fn token_chunk_configuration_is_bounded() {
1236 let tokenizer = tiktoken::get_encoding("o200k_base").unwrap();
1237 let encoded = Encoded::new(tokenizer, "hello").unwrap();
1238 for (tokens, overlap) in [(0, 0), (8, 5), (8, 8), (8, 9)] {
1239 assert!(matches!(
1240 encoded.overlapping_chunks(tokens, overlap),
1241 Err(Error::Configuration(_))
1242 ));
1243 }
1244 }
1245
1246 #[test]
1247 fn lossless_chunking_rejects_an_input_that_requires_splitting() {
1248 let tokenizer = tiktoken::get_encoding("o200k_base").unwrap();
1249 let text = "word ".repeat(200);
1250 let required_tokens = tokenizer.count_with_special_tokens(&text);
1251
1252 assert!(validate_lossless_chunk_request(tokenizer, &["short"], 32).is_ok());
1253 assert!(matches!(
1254 validate_lossless_chunk_request(tokenizer, &[&text], 32),
1255 Err(Error::LosslessChunkingUnavailable {
1256 required_tokens: actual,
1257 chunk_tokens: 32,
1258 }) if actual == required_tokens
1259 ));
1260 }
1261
1262 #[test]
1263 fn chunking_validation_uses_the_actual_fixed_trace_length() {
1264 let tokenizer = tiktoken::get_encoding("o200k_base").unwrap();
1265 let text = "word ".repeat(200);
1266 let required_tokens = tokenizer.count_with_special_tokens(&text);
1267 assert!(required_tokens > 128);
1268
1269 let trace_tokens = lossless_trace_tokens(4_096, Some(128));
1270 assert_eq!(trace_tokens, 128);
1271 assert!(matches!(
1272 validate_lossless_chunk_request(tokenizer, &[&text], trace_tokens),
1273 Err(Error::LosslessChunkingUnavailable {
1274 required_tokens: actual,
1275 chunk_tokens: 128,
1276 }) if actual == required_tokens
1277 ));
1278
1279 assert!(matches!(
1280 validate_approximate_trace_tokens(4_096, Some(128)),
1281 Err(Error::Configuration(_))
1282 ));
1283 assert!(validate_approximate_trace_tokens(128, Some(128)).is_ok());
1284 assert!(validate_approximate_trace_tokens(4_096, None).is_ok());
1285 }
1286
1287 #[test]
1288 fn bioes_to_unicode_safe_redaction() {
1289 let tokenizer = tiktoken::get_encoding("o200k_base").unwrap();
1290 let text = "Call Alice Smith today";
1291 let encoded = Encoded::new(tokenizer, text).unwrap();
1292 let mut labels = vec![0; encoded.tokens.len()];
1293 let first = encoded
1295 .token_starts
1296 .iter()
1297 .zip(&encoded.token_ends)
1298 .position(|(&start, &end)| start <= 4 && end > 4)
1299 .unwrap();
1300 let last = encoded.token_ends.iter().position(|&x| x >= 16).unwrap();
1301 if first == last {
1302 labels[first] = 20;
1303 } else {
1304 labels[first] = 17;
1305 labels[last] = 19;
1306 for item in &mut labels[first + 1..last] {
1307 *item = 18;
1308 }
1309 }
1310 let detection = Detection {
1311 spans: decode_spans(text, &encoded, &labels).unwrap(),
1312 };
1313 assert_eq!(detection.redact(text), "Call <PRIVATE_PERSON> today");
1314 }
1315
1316 #[test]
1317 fn unicode_boundary_expansion_preserves_overlapping_labels() {
1318 let text = "éx";
1319 let encoded = Encoded {
1320 tokens: vec![1, 2, 3],
1321 token_starts: vec![0, 1, 2],
1322 token_ends: vec![1, 2, 3],
1323 };
1324
1325 let spans = decode_spans(text, &encoded, &[20, 13, 15]).unwrap();
1326
1327 assert_eq!(spans.len(), 2);
1328 assert!(spans.contains(&Span {
1329 label: Label::PrivatePerson,
1330 start: 0,
1331 end: 2,
1332 }));
1333 assert!(spans.contains(&Span {
1334 label: Label::PrivateEmail,
1335 start: 0,
1336 end: 3,
1337 }));
1338 }
1339
1340 #[test]
1341 fn redaction_skips_spans_that_split_utf8_characters() {
1342 let text = "café";
1343 let detection = Detection {
1344 spans: vec![Span {
1345 label: Label::PrivatePerson,
1346 start: 3,
1347 end: 4,
1348 }],
1349 };
1350 assert_eq!(detection.redact(text), text);
1351 }
1352
1353 #[test]
1354 fn redaction_unions_overlapping_spans_without_leaking_the_suffix() {
1355 let text = "abcdefghij";
1356 let detection = Detection {
1357 spans: vec![
1358 Span {
1359 label: Label::PrivateEmail,
1360 start: 0,
1361 end: 5,
1362 },
1363 Span {
1364 label: Label::PrivatePerson,
1365 start: 4,
1366 end: 10,
1367 },
1368 ],
1369 };
1370
1371 assert_eq!(detection.redact(text), "<PRIVATE_EMAIL>");
1372 }
1373
1374 #[test]
1375 fn oversized_input_is_rejected_during_local_request_preparation() {
1376 let tokenizer = tiktoken::get_encoding("o200k_base").unwrap();
1377 let text = "x ".repeat(MAX_SEQUENCE_TOKENS + 1);
1378 let error = prepare_request(tokenizer, &[&text])
1379 .err()
1380 .expect("oversized input should be rejected");
1381 assert!(matches!(error, Error::Protocol(_)));
1382 }
1383
1384 #[test]
1385 fn byte_limit_rejects_input_before_token_vector_allocation() {
1386 let tokenizer = tiktoken::get_encoding("o200k_base").unwrap();
1387 let text = "x".repeat(MAX_SEQUENCE_BYTES + 1);
1388 let error = Encoded::new(tokenizer, &text)
1389 .err()
1390 .expect("oversized byte input should be rejected");
1391 assert!(matches!(error, Error::Protocol(_)));
1392 }
1393
1394 #[test]
1395 fn memory_limit_must_convert_to_a_positive_size_t() {
1396 for limit in [0.0, -1.0, f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
1397 assert!(matches!(
1398 validate_memory_limit(Some(limit)),
1399 Err(Error::Configuration(_))
1400 ));
1401 }
1402 let size_t_overflow = (usize::MAX as f64) / 1_073_741_824.0;
1403 assert!(matches!(
1404 validate_memory_limit(Some(size_t_overflow)),
1405 Err(Error::Configuration(_))
1406 ));
1407 assert!(validate_memory_limit(None).is_ok());
1408 assert!(validate_memory_limit(Some(0.5)).is_ok());
1409 }
1410
1411 #[test]
1412 fn cache_limit_is_independent_and_defaults_to_half_a_gibibyte() {
1413 assert_eq!(ServerOptions::default().cache_limit_gb, Some(0.5));
1414 assert!(validate_cache_limit(None).is_ok());
1415 assert!(validate_cache_limit(Some(0.5)).is_ok());
1416 for limit in [0.0, -1.0, f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
1417 assert!(matches!(
1418 validate_cache_limit(Some(limit)),
1419 Err(Error::Configuration(_))
1420 ));
1421 }
1422 }
1423
1424 #[test]
1425 fn fixed_trace_must_be_positive_and_fit_the_padded_token_budget() {
1426 assert!(ServerOptions::default().prewarm_fixed_trace);
1427 assert!(validate_fixed_trace(None, 32_768).is_ok());
1428 for shape in [
1429 FixedTraceShape {
1430 batch: 0,
1431 tokens: 1024,
1432 },
1433 FixedTraceShape {
1434 batch: 8,
1435 tokens: 0,
1436 },
1437 FixedTraceShape {
1438 batch: 8,
1439 tokens: 1024,
1440 },
1441 ] {
1442 assert!(matches!(
1443 validate_fixed_trace(Some(shape), 4096),
1444 Err(Error::Configuration(_))
1445 ));
1446 }
1447 assert!(
1448 validate_fixed_trace(
1449 Some(FixedTraceShape {
1450 batch: 4,
1451 tokens: 1024,
1452 }),
1453 4096
1454 )
1455 .is_ok()
1456 );
1457 }
1458
1459 #[test]
1460 fn default_options_load_sibling_calibration_in_official_bias_order() {
1461 let directory = tempfile::tempdir().unwrap();
1462 let calibration = directory.path().join("viterbi_calibration.json");
1463 fs::write(
1464 &calibration,
1465 r#"{
1466 "operating_points": {
1467 "default": {
1468 "biases": {
1469 "transition_bias_background_stay": 1.0,
1470 "transition_bias_background_to_start": 2.0,
1471 "transition_bias_inside_to_continue": 3.0,
1472 "transition_bias_inside_to_end": 4.0,
1473 "transition_bias_end_to_background": 5.0,
1474 "transition_bias_end_to_start": 6.0
1475 }
1476 }
1477 }
1478 }"#,
1479 )
1480 .unwrap();
1481 let options = ServerOptions::default();
1482 let model = directory.path().join("model.mlxfn");
1483 assert_eq!(
1484 resolve_viterbi_biases(&model, &options).unwrap(),
1485 [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]
1486 );
1487 }
1488
1489 #[test]
1490 fn nonblocking_write_honors_timeout_when_pipe_is_full() {
1491 let (_reader, writer) = nix::unistd::pipe().unwrap();
1492 let mut writer = File::from(writer);
1493 set_nonblocking(&writer).unwrap();
1494 let payload = vec![0u8; 4 * 1024 * 1024];
1495 let started = Instant::now();
1496 let timeout = Duration::from_millis(50);
1497 let error = write_all_before(
1498 &mut writer,
1499 &payload,
1500 deadline_after(timeout),
1501 timeout,
1502 "test write",
1503 )
1504 .unwrap_err();
1505 assert!(matches!(error, Error::Timeout { .. }));
1506 assert!(started.elapsed() < Duration::from_secs(2));
1507 }
1508
1509 #[test]
1510 fn parses_bounded_response_header_fields() {
1511 let mut header = [0u8; 16];
1512 header[..4].copy_from_slice(RESPONSE_MAGIC);
1513 header[4] = 1;
1514 header[8..12].copy_from_slice(&7u32.to_le_bytes());
1515 header[12..16].copy_from_slice(&11u32.to_le_bytes());
1516 assert_eq!(parse_response_header(header), (1, 7, 11));
1517 }
1518
1519 #[test]
1520 fn spawn_times_out_when_server_never_becomes_ready() {
1521 let directory = tempfile::tempdir().unwrap();
1522 let server = directory.path().join("unresponsive-server");
1523 fs::write(&server, "#!/bin/sh\nexec sleep 10\n").unwrap();
1524 let mut permissions = fs::metadata(&server).unwrap().permissions();
1525 permissions.set_mode(0o700);
1526 fs::set_permissions(&server, permissions).unwrap();
1527
1528 let options = ServerOptions {
1529 viterbi_biases: Some([0.0; 6]),
1530 startup_timeout: Duration::from_millis(50),
1531 shutdown_timeout: Duration::from_millis(50),
1532 ..ServerOptions::default()
1533 };
1534 let started = Instant::now();
1535 let error = PrivacyFilter::spawn(&server, "unused-model", options)
1536 .err()
1537 .expect("unresponsive process should fail startup");
1538 assert!(matches!(error, Error::Timeout { .. }));
1539 assert!(started.elapsed() < Duration::from_secs(2));
1540 }
1541}