Skip to main content

opf_mlx/
lib.rs

1//! Minimal Rust interface to the persistent native MLX Privacy Filter process.
2//!
3//! Text stays in Rust. Only `u32` token IDs cross to C++; only `u8` BIOES
4//! labels come back. This keeps IPC bounded at roughly five bytes per token.
5
6use 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    /// Inclusive UTF-8 byte offset in the original Rust string.
124    pub start: usize,
125    /// Exclusive UTF-8 byte offset in the original Rust string.
126    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    /// Exact exported execution batch, including padded rows in the final batch.
177    pub batch: usize,
178    /// Exact exported padded-token length. Inputs longer than this are rejected.
179    pub tokens: usize,
180}
181
182#[derive(Clone, Debug)]
183pub struct ServerOptions {
184    pub memory_limit_gb: Option<f64>,
185    /// Independent MLX allocator-cache ceiling. The 0.5 GiB default bounds
186    /// retained free buffers on qualified 16 GB Macs; `None` uses MLX's
187    /// own default cache policy.
188    pub cache_limit_gb: Option<f64>,
189    /// Maximum padded tokens in any Metal invocation, including single
190    /// documents. The 32k default is qualified on a 16 GB M4; larger-memory
191    /// Macs can tune upward.
192    pub max_batch_tokens: usize,
193    /// Explicit decoder biases in official calibration-file order. When
194    /// omitted, the client loads `viterbi_calibration.json` beside the model.
195    pub viterbi_biases: Option<[f32; 6]>,
196    /// Optional calibration artifact path. This conflicts with explicit
197    /// `viterbi_biases`; when omitted, the model's sibling artifact is used.
198    pub viterbi_calibration_path: Option<PathBuf>,
199    /// Maximum time for model import and the startup readiness check.
200    pub startup_timeout: Duration,
201    /// Maximum time for each inference protocol request.
202    pub io_timeout: Duration,
203    /// Maximum graceful shutdown wait before the child is killed.
204    pub shutdown_timeout: Duration,
205    /// Compile and execute the configured fixed trace before startup returns.
206    /// This has no effect on dynamic `spawn` and can be disabled when cold
207    /// startup latency matters more than first-request predictability.
208    pub prewarm_fixed_trace: bool,
209    /// Emit per-request active, peak, and cached MLX bytes on server stderr.
210    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    /// Start the helper in single-shape mode so every Metal invocation uses
251    /// the same exported trace, including padded rows in the final batch.
252    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    /// Tokenize and infer a batch. The native server automatically groups
354    /// documents by exported token bucket under `max_batch_tokens` and
355    /// restores the caller's original order.
356    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    /// Preserve full-document semantics, refusing any input that would
375    /// actually require chunking. The current exported model contract cannot
376    /// reproduce full-sequence logits and Viterbi decoding across chunks.
377    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    /// Run overlapping chunks and merge their independently decoded spans.
393    /// This is intentionally explicit because boundary logits and Viterbi
394    /// paths can differ from a full-document inference.
395    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        // Locate tokens covering " Alice Smith" and mark a person span.
1294        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}