Skip to main content

ramvamp_server/
request.rs

1//! `POST /v1/chat/completions` request shapes.
2//!
3//! Deserialization is deliberately permissive about *fields* and strict about
4//! *meaning*: unknown keys are ignored so a client sending `logprobs`,
5//! `presence_penalty` or next year's parameter is served rather than refused,
6//! but anything this server cannot honour honestly ([`n` > 1][ServerError::MultipleChoices],
7//! a non-text content part) is a typed error rather than a silent
8//! approximation.
9//!
10//! # The `content` trap
11//!
12//! Clients send message content in two forms — a bare string, and an array of
13//! typed parts:
14//!
15//! ```json
16//! {"role":"user","content":"hello"}
17//! {"role":"user","content":[{"type":"text","text":"hello"}]}
18//! ```
19//!
20//! Both are ordinary traffic; OpenCode and the OpenAI SDKs emit the array form
21//! routinely. The pinned ChatML template coerces non-string content to `""`
22//! (see `ramvamp_core::tokenizer::chat`), so a server that models `content` as
23//! `String` and shrugs at the array form does not fail — it prefills an empty
24//! user turn and the model answers a question it never received. That is the
25//! worst failure shape available: confident, fluent, and about nothing.
26//!
27//! Hence [`Content`]: an enum over both forms, flattened by
28//! [`Message::text`], with every non-text part a typed rejection. Dropping an
29//! `image_url` part would be the same bug wearing a smaller hat.
30
31use serde::{Deserialize, Serialize};
32use serde_json::Value;
33
34use crate::error::ServerError;
35
36/// The charset a tool name has to match, as a regex, for error messages.
37///
38/// OpenAI's own constraint, reproduced rather than invented so a client that
39/// already satisfies the upstream API satisfies this one. Checked by
40/// [`is_valid_tool_name`], which spells it out in code because this crate does
41/// not take a regex dependency for one character class.
42pub const TOOL_NAME_PATTERN: &str = "^[A-Za-z0-9_-]{1,64}$";
43
44/// Whether `name` is a tool name this server will render.
45///
46/// Names are *validated*, never sanitized. Every other untrusted string in a
47/// request goes through the tokenizer's sanitizer, which breaks added-token
48/// literals with a zero-width marker; doing that to a name would be silent
49/// corruption, because the model echoes the name back and the client matches
50/// the call against the name it sent. An invisible marker inside it makes the
51/// call unmatchable and the log unreadable. So a bad name is a 400.
52///
53/// Byte length is character length here: every accepted character is ASCII, so
54/// a name with a multi-byte character fails the charset test first.
55pub fn is_valid_tool_name(name: &str) -> bool {
56    !name.is_empty()
57        && name.len() <= 64
58        && name
59            .bytes()
60            .all(|b| b.is_ascii_alphanumeric() || b == b'_' || b == b'-')
61}
62
63/// Check one tool name, naming the request field it came from.
64fn check_tool_name(name: &str, param: &'static str) -> Result<(), ServerError> {
65    if is_valid_tool_name(name) {
66        return Ok(());
67    }
68    Err(ServerError::InvalidToolName {
69        name: name.to_owned(),
70        param,
71    })
72}
73
74/// Check a tool name that arrived as untyped JSON.
75///
76/// A definition whose `name` is absent or not a string goes down the same
77/// path, with the offending JSON (`null`, `123`) quoted back: a nameless
78/// definition can never produce a call the client is able to match.
79fn check_json_tool_name(name: &Value, param: &'static str) -> Result<(), ServerError> {
80    match name.as_str() {
81        Some(name) => check_tool_name(name, param),
82        None => Err(ServerError::InvalidToolName {
83            name: name.to_string(),
84            param,
85        }),
86    }
87}
88
89/// The `name` of one tool definition.
90///
91/// Accepts both shapes the renderer accepts: the OpenAI wrapper
92/// (`{"type":"function","function":{"name":…}}`) and the bare
93/// `{"name":…}`, mirroring the template's own `if tool_call.function`
94/// flattening. Indexing a [`Value`] with a missing key yields `Null`, which
95/// [`check_json_tool_name`] refuses.
96fn definition_name(tool: &Value) -> &Value {
97    match tool.get("function") {
98        Some(function) => &function["name"],
99        None => &tool["name"],
100    }
101}
102
103/// Who is speaking.
104#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
105#[serde(rename_all = "lowercase")]
106pub enum MessageRole {
107    /// Instructions to the model.
108    System,
109    /// A human turn.
110    User,
111    /// A model turn.
112    Assistant,
113    /// The result of a tool call. Rendered as a `<tool_response>` block
114    /// inside a `user` turn; see [`crate::prompt`].
115    Tool,
116}
117
118impl MessageRole {
119    /// The lowercase wire string.
120    pub fn as_str(self) -> &'static str {
121        match self {
122            MessageRole::System => "system",
123            MessageRole::User => "user",
124            MessageRole::Assistant => "assistant",
125            MessageRole::Tool => "tool",
126        }
127    }
128}
129
130/// One part of an array-form `content`.
131///
132/// Modelled as an open struct rather than a closed `#[serde(tag = "type")]`
133/// enum on purpose: an unknown variant would surface as a serde parse failure
134/// ("unknown variant `image_url`"), which is a 400 that reads like malformed
135/// JSON. Keeping `kind` a string lets any part type parse and then be refused
136/// with a message that names it.
137#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
138pub struct ContentPart {
139    /// The part's `type`, e.g. `text` or `image_url`.
140    #[serde(rename = "type")]
141    pub kind: String,
142    /// The text, present on `text` parts.
143    #[serde(default, skip_serializing_if = "Option::is_none")]
144    pub text: Option<String>,
145}
146
147impl ContentPart {
148    /// The `type` value of a text part.
149    pub const TEXT: &'static str = "text";
150
151    /// A text part.
152    pub fn text(text: impl Into<String>) -> Self {
153        ContentPart {
154            kind: ContentPart::TEXT.to_owned(),
155            text: Some(text.into()),
156        }
157    }
158
159    /// The text this part contributes, or why it cannot contribute any.
160    pub fn as_text(&self) -> Result<&str, ServerError> {
161        if self.kind != ContentPart::TEXT {
162            return Err(ServerError::UnsupportedContentPart {
163                kind: self.kind.clone(),
164            });
165        }
166        self.text.as_deref().ok_or(ServerError::MissingPartText)
167    }
168}
169
170/// Message content in either of the two forms clients send.
171#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
172#[serde(untagged)]
173pub enum Content {
174    /// The bare-string form.
175    Text(String),
176    /// The array-of-parts form.
177    Parts(Vec<ContentPart>),
178}
179
180impl Content {
181    /// The text this content contributes.
182    ///
183    /// Parts are joined with no separator: the split is a transport detail, so
184    /// a client that sent `["hello ", "world"]` meant `hello world`, and
185    /// inserting a separator would fabricate whitespace the user never typed.
186    pub fn text(&self) -> Result<String, ServerError> {
187        match self {
188            Content::Text(text) => Ok(text.clone()),
189            Content::Parts(parts) => {
190                let mut out = String::new();
191                for part in parts {
192                    out.push_str(part.as_text()?);
193                }
194                Ok(out)
195            }
196        }
197    }
198}
199
200/// A function call the model asked for, echoed back by the client on the next
201/// turn.
202///
203/// Preserved verbatim through parsing and re-rendered into the prompt as the
204/// `<tool_call>` block the model originally emitted, so the conversation the
205/// model sees on turn *n+1* contains the call it made on turn *n*.
206#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
207pub struct ToolCall {
208    /// Call id, matched by a `tool` message's `tool_call_id`.
209    pub id: String,
210    /// Always `function` today.
211    #[serde(rename = "type")]
212    pub kind: String,
213    /// The call itself.
214    pub function: FunctionCall,
215}
216
217/// The function half of a [`ToolCall`].
218#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
219pub struct FunctionCall {
220    /// Function name.
221    pub name: String,
222    /// Arguments as a JSON *string*, exactly as OpenAI sends them. Kept a
223    /// string rather than parsed: models emit invalid JSON here often enough
224    /// that parsing would turn a recoverable turn into a 400, and re-encoding
225    /// valid JSON would not round-trip byte for byte.
226    pub arguments: String,
227}
228
229/// One chat turn as the client sent it.
230#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
231pub struct Message {
232    /// Who is speaking.
233    pub role: MessageRole,
234    /// The content. `None` for an assistant turn that is only `tool_calls`,
235    /// which clients send as an explicit `"content": null`.
236    #[serde(default, skip_serializing_if = "Option::is_none")]
237    pub content: Option<Content>,
238    /// Optional participant name.
239    #[serde(default, skip_serializing_if = "Option::is_none")]
240    pub name: Option<String>,
241    /// Calls an assistant turn requested.
242    #[serde(default, skip_serializing_if = "Option::is_none")]
243    pub tool_calls: Option<Vec<ToolCall>>,
244    /// Which call a `tool` turn answers.
245    #[serde(default, skip_serializing_if = "Option::is_none")]
246    pub tool_call_id: Option<String>,
247}
248
249impl Message {
250    /// A message with plain string content.
251    pub fn new(role: MessageRole, content: impl Into<String>) -> Self {
252        Message {
253            role,
254            content: Some(Content::Text(content.into())),
255            name: None,
256            tool_calls: None,
257            tool_call_id: None,
258        }
259    }
260
261    /// The text of this message, flattened from whichever content form
262    /// arrived. Absent content is the empty string, which is what an assistant
263    /// turn carrying only `tool_calls` contributes.
264    pub fn text(&self) -> Result<String, ServerError> {
265        match &self.content {
266            Some(content) => content.text(),
267            None => Ok(String::new()),
268        }
269    }
270
271    /// The calls this turn carries, empty when it carries none.
272    pub fn calls(&self) -> &[ToolCall] {
273        self.tool_calls.as_deref().unwrap_or(&[])
274    }
275
276    /// Refuse a call whose name is outside [`TOOL_NAME_PATTERN`].
277    ///
278    /// A name echoed back on an assistant turn gets the same check as a
279    /// definition: it is rendered into the prompt the same way, and the next
280    /// `tool` turn is matched against it by the client.
281    pub fn check_tool_calls(&self) -> Result<(), ServerError> {
282        for call in self.calls() {
283            check_tool_name(&call.function.name, "messages")?;
284        }
285        Ok(())
286    }
287}
288
289/// A `stop` value: OpenAI accepts a single string or an array of them.
290#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
291#[serde(untagged)]
292pub enum StringOrArray {
293    /// One sequence.
294    One(String),
295    /// Up to four sequences.
296    Many(Vec<String>),
297}
298
299impl StringOrArray {
300    /// The sequences, in order.
301    pub fn as_slice(&self) -> &[String] {
302        match self {
303            StringOrArray::One(one) => std::slice::from_ref(one),
304            StringOrArray::Many(many) => many.as_slice(),
305        }
306    }
307}
308
309/// `stream_options`, the only sub-object that changes the chunk sequence.
310#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
311pub struct StreamOptions {
312    /// Emit a final usage-only chunk before the sentinel.
313    #[serde(default, skip_serializing_if = "Option::is_none")]
314    pub include_usage: Option<bool>,
315}
316
317/// A `POST /v1/chat/completions` body.
318///
319/// Unknown fields are ignored rather than rejected — a client that sends a
320/// parameter this build does not implement gets an answer, not a 400 — so the
321/// fields listed here are the ones that change behaviour, not the ones that
322/// are legal.
323#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
324pub struct ChatCompletionRequest {
325    /// Whatever the client called the model. Echoed back unexamined: this
326    /// server serves exactly one install, so validating the name could only
327    /// refuse requests it is able to answer.
328    pub model: String,
329    /// The conversation. Must be non-empty.
330    #[serde(default)]
331    pub messages: Vec<Message>,
332    /// Stream the reply as SSE.
333    #[serde(default, skip_serializing_if = "Option::is_none")]
334    pub stream: Option<bool>,
335    /// Streaming extras.
336    #[serde(default, skip_serializing_if = "Option::is_none")]
337    pub stream_options: Option<StreamOptions>,
338    /// Softmax temperature.
339    #[serde(default, skip_serializing_if = "Option::is_none")]
340    pub temperature: Option<f32>,
341    /// Nucleus-sampling mass.
342    #[serde(default, skip_serializing_if = "Option::is_none")]
343    pub top_p: Option<f32>,
344    /// Top-k cutoff. Not an OpenAI field; accepted because llama.cpp accepts
345    /// it and local tooling sends it.
346    #[serde(default, skip_serializing_if = "Option::is_none")]
347    pub top_k: Option<u32>,
348    /// PRNG seed.
349    #[serde(default, skip_serializing_if = "Option::is_none")]
350    pub seed: Option<u64>,
351    /// Reply length cap, the older spelling.
352    #[serde(default, skip_serializing_if = "Option::is_none")]
353    pub max_tokens: Option<u32>,
354    /// Reply length cap, the current spelling. Wins when both appear.
355    #[serde(default, skip_serializing_if = "Option::is_none")]
356    pub max_completion_tokens: Option<u32>,
357    /// Stop sequences.
358    #[serde(default, skip_serializing_if = "Option::is_none")]
359    pub stop: Option<StringOrArray>,
360    /// How many completions to return. Anything above 1 is refused.
361    #[serde(default, skip_serializing_if = "Option::is_none")]
362    pub n: Option<u32>,
363    /// Tool definitions, preserved verbatim.
364    ///
365    /// Held as raw JSON rather than a typed schema because the renderer takes
366    /// them that way: each definition is serialized into the `# Tools` system
367    /// block exactly as it arrived, so a Rust shape here could only lose
368    /// fields (`strict`, vendor extensions) that the reference template keeps.
369    #[serde(default, skip_serializing_if = "Option::is_none")]
370    pub tools: Option<Vec<Value>>,
371    /// Tool selection policy. Only `auto` and `none` are honourable here; see
372    /// [`ChatCompletionRequest::check_tool_choice`].
373    #[serde(default, skip_serializing_if = "Option::is_none")]
374    pub tool_choice: Option<Value>,
375}
376
377impl ChatCompletionRequest {
378    /// Parse a request body.
379    ///
380    /// Every byte here is untrusted, so serde's failure is captured as a
381    /// message rather than propagated as a panic or an opaque 500.
382    pub fn from_json(body: &str) -> Result<Self, ServerError> {
383        serde_json::from_str(body).map_err(|e| ServerError::MalformedJson(e.to_string()))
384    }
385
386    /// Check everything that can be checked without a tokenizer.
387    ///
388    /// Called before any work is scheduled, so a request that cannot be served
389    /// never reaches the decode loop and never occupies the single session.
390    pub fn validate(&self) -> Result<(), ServerError> {
391        if self.messages.is_empty() {
392            return Err(ServerError::EmptyMessages);
393        }
394        if let Some(n) = self.n
395            && n > 1
396        {
397            return Err(ServerError::MultipleChoices { n });
398        }
399        // A stop sequence has no consumer: `GenerateParams` carries no stop
400        // strings and the generate entry points stop on the tokenizer's own
401        // stop tokens. Accepting one would let generation run past where the
402        // caller asked it to end, with nothing in the response to say so.
403        if !self.stop_sequences().is_empty() {
404            return Err(ServerError::StopUnsupported);
405        }
406        self.check_tool_choice()?;
407        self.check_tools()?;
408        for message in &self.messages {
409            // Flattening is the check: it is the only thing that inspects
410            // every part, and doing it here means a bad part is refused before
411            // the session is claimed rather than mid-prefill.
412            message.text()?;
413            message.check_tool_calls()?;
414        }
415        Ok(())
416    }
417
418    /// The tool definitions, empty when none were sent.
419    pub fn tools(&self) -> &[Value] {
420        self.tools.as_deref().unwrap_or(&[])
421    }
422
423    /// Refuse a tool definition whose name the model could not call back.
424    ///
425    /// Separate from [`validate`](Self::validate) so [`crate::prompt::build`],
426    /// which is the thing that actually renders these, enforces it too rather
427    /// than trusting that validation ran.
428    pub fn check_tools(&self) -> Result<(), ServerError> {
429        for tool in self.tools() {
430            check_json_tool_name(definition_name(tool), "tools")?;
431        }
432        Ok(())
433    }
434
435    /// Refuse a `tool_choice` this build cannot honour.
436    ///
437    /// `auto`, `none` and absent are accepted and all render the same prompt,
438    /// because that is what the template does: it branches on `tools` alone
439    /// and has no way to say "you must call something". `required` and a named
440    /// function therefore cannot be expressed at all, and serving them by
441    /// letting the model choose freely would drop the one constraint the
442    /// request was about.
443    pub fn check_tool_choice(&self) -> Result<(), ServerError> {
444        let Some(choice) = &self.tool_choice else {
445            return Ok(());
446        };
447        if matches!(choice.as_str(), Some("auto" | "none")) {
448            return Ok(());
449        }
450        Err(ServerError::UnsupportedToolChoice {
451            choice: choice.to_string(),
452        })
453    }
454
455    /// Whether to stream. Absent means false.
456    pub fn stream(&self) -> bool {
457        self.stream.unwrap_or(false)
458    }
459
460    /// Whether to emit the usage-only chunk. Absent means false.
461    pub fn include_usage(&self) -> bool {
462        self.stream_options
463            .and_then(|options| options.include_usage)
464            .unwrap_or(false)
465    }
466
467    /// The reply length cap.
468    ///
469    /// `max_completion_tokens` is the current spelling and `max_tokens` the
470    /// deprecated alias; when both arrive the newer one wins, because a client
471    /// that sends both is an SDK filling in a compatibility field behind a
472    /// caller who set the modern one.
473    pub fn max_new_tokens(&self) -> Option<u32> {
474        self.max_completion_tokens.or(self.max_tokens)
475    }
476
477    /// The stop sequences, empty when none were sent.
478    ///
479    /// Read by [`validate`](Self::validate) only, to refuse a non-empty one.
480    /// When the runtime grows stop strings this becomes the accessor that
481    /// feeds them; until then it exists so the refusal has one definition of
482    /// "sent a stop sequence" across both `stop` spellings.
483    pub fn stop_sequences(&self) -> &[String] {
484        self.stop.as_ref().map_or(&[], StringOrArray::as_slice)
485    }
486}
487
488#[cfg(test)]
489mod tests {
490    use super::*;
491
492    fn parse(body: &str) -> Result<ChatCompletionRequest, ServerError> {
493        ChatCompletionRequest::from_json(body)
494    }
495
496    #[test]
497    fn string_content_parses() {
498        let request = parse(r#"{"model":"m","messages":[{"role":"user","content":"hello"}]}"#)
499            .expect("valid body");
500        assert_eq!(request.messages[0].text().expect("text"), "hello");
501        assert_eq!(request.messages[0].role, MessageRole::User);
502    }
503
504    /// The trap this module exists for: the array form must reach the model,
505    /// not be coerced to `""`.
506    #[test]
507    fn array_form_content_is_flattened() {
508        let request = parse(
509            r#"{"model":"m","messages":[
510                {"role":"user","content":[{"type":"text","text":"hello"}]}
511            ]}"#,
512        )
513        .expect("valid body");
514        assert_eq!(request.messages[0].text().expect("text"), "hello");
515    }
516
517    #[test]
518    fn multiple_text_parts_concatenate_without_a_separator() {
519        let request = parse(
520            r#"{"model":"m","messages":[
521                {"role":"user","content":[
522                    {"type":"text","text":"hello "},
523                    {"type":"text","text":"world"}
524                ]}
525            ]}"#,
526        )
527        .expect("valid body");
528        assert_eq!(request.messages[0].text().expect("text"), "hello world");
529    }
530
531    #[test]
532    fn empty_parts_array_flattens_to_empty_text() {
533        let request =
534            parse(r#"{"model":"m","messages":[{"role":"user","content":[]}]}"#).expect("valid");
535        assert_eq!(request.messages[0].text().expect("text"), "");
536    }
537
538    #[test]
539    fn non_text_content_part_is_rejected_not_dropped() {
540        let request = parse(
541            r#"{"model":"m","messages":[
542                {"role":"user","content":[
543                    {"type":"text","text":"what is this"},
544                    {"type":"image_url","image_url":{"url":"data:image/png;base64,AA"}}
545                ]}
546            ]}"#,
547        )
548        .expect("valid body");
549        let error = request.validate().expect_err("image parts are refused");
550        assert!(
551            matches!(&error, ServerError::UnsupportedContentPart { kind } if kind == "image_url"),
552            "{error:?}"
553        );
554        assert!(error.to_string().contains("image_url"));
555    }
556
557    #[test]
558    fn text_part_without_text_is_rejected() {
559        let request =
560            parse(r#"{"model":"m","messages":[{"role":"user","content":[{"type":"text"}]}]}"#)
561                .expect("valid body");
562        assert!(matches!(
563            request.validate().expect_err("text is required"),
564            ServerError::MissingPartText
565        ));
566    }
567
568    #[test]
569    fn null_content_flattens_to_empty_text() {
570        let request = parse(
571            r#"{"model":"m","messages":[{"role":"assistant","content":null,"tool_calls":[]}]}"#,
572        )
573        .expect("valid body");
574        assert_eq!(request.messages[0].text().expect("text"), "");
575    }
576
577    #[test]
578    fn empty_messages_is_rejected() {
579        let request = parse(r#"{"model":"m","messages":[]}"#).expect("valid body");
580        assert!(matches!(
581            request.validate().expect_err("must be non-empty"),
582            ServerError::EmptyMessages
583        ));
584        // Absent entirely, too.
585        let request = parse(r#"{"model":"m"}"#).expect("valid body");
586        assert!(matches!(
587            request.validate().expect_err("must be non-empty"),
588            ServerError::EmptyMessages
589        ));
590    }
591
592    /// The refusal this replaced answered 400 to every tools request; the
593    /// renderer can carry them now, so a well-formed one is served.
594    #[test]
595    fn a_request_carrying_tools_is_accepted() {
596        let body = r#"{"model":"m","messages":[{"role":"user","content":"hi"}],
597            "tools":[{"type":"function","function":{"name":"read_file","parameters":{}}}]}"#;
598        let req = ChatCompletionRequest::from_json(body).expect("parses");
599        req.validate().expect("the renderer has a tools branch");
600        assert_eq!(req.tools().len(), 1);
601    }
602
603    #[test]
604    fn an_empty_tools_array_is_not_a_refusal() {
605        let body = r#"{"model":"m","messages":[{"role":"user","content":"hi"}],"tools":[]}"#;
606        let req = ChatCompletionRequest::from_json(body).expect("parses");
607        req.validate().expect("an empty list asks for nothing");
608        assert!(req.tools().is_empty());
609    }
610
611    #[test]
612    fn the_tool_name_charset_is_openais() {
613        for good in ["f", "get_weather", "read-file", "a1", &"n".repeat(64)] {
614            assert!(is_valid_tool_name(good), "{good}");
615        }
616        for bad in [
617            "",
618            "get weather",
619            "say\"hi",
620            "read<file>",
621            "a.b",
622            "naïve",
623            "a\u{200b}b",
624            &"n".repeat(65),
625        ] {
626            assert!(!is_valid_tool_name(bad), "{bad}");
627        }
628    }
629
630    /// A name is refused rather than repaired: the model echoes it back and
631    /// the client matches on it, so a sanitizer marker inside one would make
632    /// the call unmatchable and the difference invisible.
633    #[test]
634    fn a_tool_definition_name_outside_the_charset_is_refused_with_the_name() {
635        let body = r#"{"model":"m","messages":[{"role":"user","content":"hi"}],
636            "tools":[{"type":"function","function":{"name":"read<file>"}}]}"#;
637        let error = ChatCompletionRequest::from_json(body)
638            .expect("parses")
639            .validate()
640            .expect_err("hostile name");
641        assert!(
642            matches!(&error, ServerError::InvalidToolName { name, param }
643                if name == "read<file>" && *param == "tools"),
644            "{error:?}"
645        );
646        assert_eq!(error.status(), 400);
647        assert!(error.to_string().contains("read<file>"));
648    }
649
650    #[test]
651    fn a_definition_with_no_usable_name_is_refused_too() {
652        for tools in [
653            r#"[{"type":"function","function":{"parameters":{}}}]"#,
654            r#"[{"type":"function","function":{"name":42}}]"#,
655            r#"[{"type":"function"}]"#,
656            r#"[{}]"#,
657        ] {
658            let body = format!(
659                r#"{{"model":"m","messages":[{{"role":"user","content":"hi"}}],"tools":{tools}}}"#
660            );
661            let error = parse(&body)
662                .expect("parses")
663                .validate()
664                .expect_err("a nameless tool cannot be called back");
665            assert!(
666                matches!(error, ServerError::InvalidToolName { .. }),
667                "{tools}: {error:?}"
668            );
669        }
670    }
671
672    /// The bare shape the renderer also accepts, so the check has to see it.
673    #[test]
674    fn a_bare_tool_definition_is_named_by_its_own_name_field() {
675        let ok = r#"{"model":"m","messages":[{"role":"user","content":"hi"}],
676            "tools":[{"name":"read_file","parameters":{}}]}"#;
677        parse(ok).expect("parses").validate().expect("valid name");
678
679        let bad = r#"{"model":"m","messages":[{"role":"user","content":"hi"}],
680            "tools":[{"name":"read file","parameters":{}}]}"#;
681        assert!(matches!(
682            parse(bad).expect("parses").validate().expect_err("refused"),
683            ServerError::InvalidToolName { .. }
684        ));
685    }
686
687    #[test]
688    fn a_tool_name_echoed_back_on_an_assistant_turn_is_checked_against_messages() {
689        let body = r#"{"model":"m","messages":[
690            {"role":"user","content":"hi"},
691            {"role":"assistant","content":null,"tool_calls":[
692                {"id":"call_1","type":"function",
693                 "function":{"name":"say\"hi","arguments":"{}"}}
694            ]}
695        ]}"#;
696        let error = parse(body)
697            .expect("parses")
698            .validate()
699            .expect_err("hostile name");
700        assert!(
701            matches!(&error, ServerError::InvalidToolName { name, param }
702                if name == "say\"hi" && *param == "messages"),
703            "{error:?}"
704        );
705    }
706
707    #[test]
708    fn tool_choice_accepts_only_what_the_template_can_express() {
709        let base = r#""model":"m","messages":[{"role":"user","content":"hi"}]"#;
710        for accepted in ["\"auto\"", "\"none\""] {
711            parse(&format!("{{{base},\"tool_choice\":{accepted}}}"))
712                .expect("parses")
713                .validate()
714                .unwrap_or_else(|e| panic!("{accepted} is renderable: {e}"));
715        }
716        parse(&format!("{{{base}}}"))
717            .expect("parses")
718            .validate()
719            .expect("absent is auto");
720
721        for refused in [
722            "\"required\"",
723            r#"{"type":"function","function":{"name":"read_file"}}"#,
724            "\"banana\"",
725        ] {
726            let error = parse(&format!("{{{base},\"tool_choice\":{refused}}}"))
727                .expect("parses")
728                .validate()
729                .expect_err("cannot be forced");
730            assert!(
731                matches!(error, ServerError::UnsupportedToolChoice { .. }),
732                "{refused}: {error:?}"
733            );
734            assert_eq!(error.param(), Some("tool_choice"));
735            assert!(error.to_string().contains("auto"), "{refused}");
736        }
737    }
738
739    /// Nothing in the runtime applies a stop string, so accepting one lets
740    /// generation run past where the caller asked it to end with nothing in
741    /// the response to say so.
742    #[test]
743    fn a_non_empty_stop_is_refused_rather_than_dropped() {
744        let base = r#""model":"m","messages":[{"role":"user","content":"hi"}]"#;
745        for sent in ["\"<end>\"", r#"["a","b"]"#] {
746            let error = parse(&format!("{{{base},\"stop\":{sent}}}"))
747                .expect("parses")
748                .validate()
749                .expect_err("no consumer for stop strings");
750            assert!(
751                matches!(error, ServerError::StopUnsupported),
752                "{sent}: {error:?}"
753            );
754            assert_eq!(error.status(), 400);
755            assert_eq!(error.param(), Some("stop"));
756        }
757        // Absent and empty ask for nothing, so they are served.
758        parse(&format!("{{{base}}}"))
759            .expect("parses")
760            .validate()
761            .expect("absent asks for nothing");
762        parse(&format!("{{{base},\"stop\":[]}}"))
763            .expect("parses")
764            .validate()
765            .expect("an empty list asks for nothing");
766        parse(&format!("{{{base},\"stop\":null}}"))
767            .expect("parses")
768            .validate()
769            .expect("null is absent");
770    }
771
772    #[test]
773    fn n_above_one_is_rejected() {
774        let body = r#"{"model":"m","messages":[{"role":"user","content":"hi"}],"n":2}"#;
775        let request = parse(body).expect("valid body");
776        assert!(matches!(
777            request.validate().expect_err("n > 1 cannot be honoured"),
778            ServerError::MultipleChoices { n: 2 }
779        ));
780    }
781
782    #[test]
783    fn n_of_at_most_one_is_accepted() {
784        for body in [
785            r#"{"model":"m","messages":[{"role":"user","content":"hi"}],"n":1}"#,
786            r#"{"model":"m","messages":[{"role":"user","content":"hi"}]}"#,
787            r#"{"model":"m","messages":[{"role":"user","content":"hi"}],"n":0}"#,
788        ] {
789            parse(body).expect("valid body").validate().expect("ok");
790        }
791    }
792
793    #[test]
794    fn both_max_token_spellings_are_read_and_the_newer_one_wins() {
795        let base = r#""model":"m","messages":[{"role":"user","content":"hi"}]"#;
796        let only_old = parse(&format!("{{{base},\"max_tokens\":16}}")).expect("valid");
797        assert_eq!(only_old.max_new_tokens(), Some(16));
798
799        let only_new = parse(&format!("{{{base},\"max_completion_tokens\":32}}")).expect("valid");
800        assert_eq!(only_new.max_new_tokens(), Some(32));
801
802        let both = parse(&format!(
803            "{{{base},\"max_tokens\":16,\"max_completion_tokens\":32}}"
804        ))
805        .expect("valid");
806        assert_eq!(both.max_new_tokens(), Some(32));
807
808        let neither = parse(&format!("{{{base}}}")).expect("valid");
809        assert_eq!(neither.max_new_tokens(), None);
810    }
811
812    #[test]
813    fn unknown_fields_are_ignored() {
814        let request = parse(
815            r#"{"model":"m","messages":[{"role":"user","content":"hi"}],
816                "presence_penalty":0.5,"logprobs":true,"future_knob":{"a":[1]}}"#,
817        )
818        .expect("unknown fields must not fail the request");
819        request.validate().expect("still valid");
820    }
821
822    #[test]
823    fn malformed_json_is_a_typed_error() {
824        let error = parse("{not json").expect_err("malformed");
825        assert!(matches!(error, ServerError::MalformedJson(_)));
826        assert_eq!(error.status(), 400);
827    }
828
829    #[test]
830    fn stop_accepts_a_string_or_an_array() {
831        let base = r#""model":"m","messages":[{"role":"user","content":"hi"}]"#;
832        let one = parse(&format!("{{{base},\"stop\":\"<end>\"}}")).expect("valid");
833        assert_eq!(one.stop_sequences(), ["<end>"]);
834
835        let many = parse(&format!("{{{base},\"stop\":[\"a\",\"b\"]}}")).expect("valid");
836        assert_eq!(many.stop_sequences(), ["a", "b"]);
837
838        let none = parse(&format!("{{{base}}}")).expect("valid");
839        assert!(none.stop_sequences().is_empty());
840    }
841
842    #[test]
843    fn stream_and_include_usage_default_to_false() {
844        let base = r#""model":"m","messages":[{"role":"user","content":"hi"}]"#;
845        let plain = parse(&format!("{{{base}}}")).expect("valid");
846        assert!(!plain.stream());
847        assert!(!plain.include_usage());
848
849        let streaming = parse(&format!(
850            "{{{base},\"stream\":true,\"stream_options\":{{\"include_usage\":true}}}}"
851        ))
852        .expect("valid");
853        assert!(streaming.stream());
854        assert!(streaming.include_usage());
855
856        // Streaming without the option must not opt in to the usage chunk.
857        let bare_stream = parse(&format!("{{{base},\"stream\":true}}")).expect("valid");
858        assert!(bare_stream.stream());
859        assert!(!bare_stream.include_usage());
860    }
861
862    /// A later wave pairs tool results with their calls by id, so both halves
863    /// have to survive parsing untouched.
864    #[test]
865    fn tool_calls_and_tool_call_id_round_trip_without_loss() {
866        let body = r#"{
867            "model":"m",
868            "messages":[
869                {"role":"user","content":"weather?"},
870                {"role":"assistant","content":null,"tool_calls":[
871                    {"id":"call_abc","type":"function",
872                     "function":{"name":"get_weather","arguments":"{\"city\":\"Cairo\"}"}}
873                ]},
874                {"role":"tool","tool_call_id":"call_abc","content":"31C","name":"get_weather"}
875            ],
876            "tools":[{"type":"function","function":{"name":"get_weather","strict":true}}],
877            "tool_choice":"auto"
878        }"#;
879        let request = ChatCompletionRequest::from_json(body).expect("valid body");
880
881        let calls = request.messages[1]
882            .tool_calls
883            .as_ref()
884            .expect("tool_calls preserved");
885        assert_eq!(calls[0].id, "call_abc");
886        assert_eq!(calls[0].kind, "function");
887        assert_eq!(calls[0].function.name, "get_weather");
888        // Arguments stay the model's exact string, not a re-encoding of it.
889        assert_eq!(calls[0].function.arguments, r#"{"city":"Cairo"}"#);
890
891        assert_eq!(request.messages[2].role, MessageRole::Tool);
892        assert_eq!(
893            request.messages[2].tool_call_id.as_deref(),
894            Some("call_abc")
895        );
896        assert_eq!(request.messages[2].name.as_deref(), Some("get_weather"));
897        assert_eq!(request.messages[2].text().expect("text"), "31C");
898
899        // `tools` keeps fields no typed schema here would know about.
900        let tools = request.tools.as_ref().expect("tools preserved");
901        assert_eq!(tools[0]["function"]["strict"], true);
902        assert_eq!(request.tool_choice, Some(serde_json::json!("auto")));
903
904        // And the whole thing survives a serialize/parse cycle.
905        let round_tripped: ChatCompletionRequest =
906            serde_json::from_str(&serde_json::to_string(&request).expect("serializes"))
907                .expect("re-parses");
908        assert_eq!(round_tripped, request);
909    }
910
911    #[test]
912    fn every_role_parses() {
913        for (wire, role) in [
914            ("system", MessageRole::System),
915            ("user", MessageRole::User),
916            ("assistant", MessageRole::Assistant),
917            ("tool", MessageRole::Tool),
918        ] {
919            let body = format!(r#"{{"model":"m","messages":[{{"role":"{wire}","content":"x"}}]}}"#);
920            let request = parse(&body).expect("valid role");
921            assert_eq!(request.messages[0].role, role);
922            assert_eq!(role.as_str(), wire);
923        }
924        assert!(matches!(
925            parse(r#"{"model":"m","messages":[{"role":"wizard","content":"x"}]}"#)
926                .expect_err("unknown role"),
927            ServerError::MalformedJson(_)
928        ));
929    }
930}