use serde::{Deserialize, Serialize};
use serde_json::Value;
use crate::error::ServerError;
pub const TOOL_NAME_PATTERN: &str = "^[A-Za-z0-9_-]{1,64}$";
pub fn is_valid_tool_name(name: &str) -> bool {
!name.is_empty()
&& name.len() <= 64
&& name
.bytes()
.all(|b| b.is_ascii_alphanumeric() || b == b'_' || b == b'-')
}
fn check_tool_name(name: &str, param: &'static str) -> Result<(), ServerError> {
if is_valid_tool_name(name) {
return Ok(());
}
Err(ServerError::InvalidToolName {
name: name.to_owned(),
param,
})
}
fn check_json_tool_name(name: &Value, param: &'static str) -> Result<(), ServerError> {
match name.as_str() {
Some(name) => check_tool_name(name, param),
None => Err(ServerError::InvalidToolName {
name: name.to_string(),
param,
}),
}
}
fn definition_name(tool: &Value) -> &Value {
match tool.get("function") {
Some(function) => &function["name"],
None => &tool["name"],
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum MessageRole {
System,
User,
Assistant,
Tool,
}
impl MessageRole {
pub fn as_str(self) -> &'static str {
match self {
MessageRole::System => "system",
MessageRole::User => "user",
MessageRole::Assistant => "assistant",
MessageRole::Tool => "tool",
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ContentPart {
#[serde(rename = "type")]
pub kind: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub text: Option<String>,
}
impl ContentPart {
pub const TEXT: &'static str = "text";
pub fn text(text: impl Into<String>) -> Self {
ContentPart {
kind: ContentPart::TEXT.to_owned(),
text: Some(text.into()),
}
}
pub fn as_text(&self) -> Result<&str, ServerError> {
if self.kind != ContentPart::TEXT {
return Err(ServerError::UnsupportedContentPart {
kind: self.kind.clone(),
});
}
self.text.as_deref().ok_or(ServerError::MissingPartText)
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(untagged)]
pub enum Content {
Text(String),
Parts(Vec<ContentPart>),
}
impl Content {
pub fn text(&self) -> Result<String, ServerError> {
match self {
Content::Text(text) => Ok(text.clone()),
Content::Parts(parts) => {
let mut out = String::new();
for part in parts {
out.push_str(part.as_text()?);
}
Ok(out)
}
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ToolCall {
pub id: String,
#[serde(rename = "type")]
pub kind: String,
pub function: FunctionCall,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FunctionCall {
pub name: String,
pub arguments: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Message {
pub role: MessageRole,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub content: Option<Content>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub name: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub tool_calls: Option<Vec<ToolCall>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub tool_call_id: Option<String>,
}
impl Message {
pub fn new(role: MessageRole, content: impl Into<String>) -> Self {
Message {
role,
content: Some(Content::Text(content.into())),
name: None,
tool_calls: None,
tool_call_id: None,
}
}
pub fn text(&self) -> Result<String, ServerError> {
match &self.content {
Some(content) => content.text(),
None => Ok(String::new()),
}
}
pub fn calls(&self) -> &[ToolCall] {
self.tool_calls.as_deref().unwrap_or(&[])
}
pub fn check_tool_calls(&self) -> Result<(), ServerError> {
for call in self.calls() {
check_tool_name(&call.function.name, "messages")?;
}
Ok(())
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(untagged)]
pub enum StringOrArray {
One(String),
Many(Vec<String>),
}
impl StringOrArray {
pub fn as_slice(&self) -> &[String] {
match self {
StringOrArray::One(one) => std::slice::from_ref(one),
StringOrArray::Many(many) => many.as_slice(),
}
}
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct StreamOptions {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub include_usage: Option<bool>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ChatCompletionRequest {
pub model: String,
#[serde(default)]
pub messages: Vec<Message>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub stream: Option<bool>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub stream_options: Option<StreamOptions>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub temperature: Option<f32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub top_p: Option<f32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub top_k: Option<u32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub seed: Option<u64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub max_tokens: Option<u32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub max_completion_tokens: Option<u32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub stop: Option<StringOrArray>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub n: Option<u32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub tools: Option<Vec<Value>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub tool_choice: Option<Value>,
}
impl ChatCompletionRequest {
pub fn from_json(body: &str) -> Result<Self, ServerError> {
serde_json::from_str(body).map_err(|e| ServerError::MalformedJson(e.to_string()))
}
pub fn validate(&self) -> Result<(), ServerError> {
if self.messages.is_empty() {
return Err(ServerError::EmptyMessages);
}
if let Some(n) = self.n
&& n > 1
{
return Err(ServerError::MultipleChoices { n });
}
if !self.stop_sequences().is_empty() {
return Err(ServerError::StopUnsupported);
}
self.check_tool_choice()?;
self.check_tools()?;
for message in &self.messages {
message.text()?;
message.check_tool_calls()?;
}
Ok(())
}
pub fn tools(&self) -> &[Value] {
self.tools.as_deref().unwrap_or(&[])
}
pub fn check_tools(&self) -> Result<(), ServerError> {
for tool in self.tools() {
check_json_tool_name(definition_name(tool), "tools")?;
}
Ok(())
}
pub fn check_tool_choice(&self) -> Result<(), ServerError> {
let Some(choice) = &self.tool_choice else {
return Ok(());
};
if matches!(choice.as_str(), Some("auto" | "none")) {
return Ok(());
}
Err(ServerError::UnsupportedToolChoice {
choice: choice.to_string(),
})
}
pub fn stream(&self) -> bool {
self.stream.unwrap_or(false)
}
pub fn include_usage(&self) -> bool {
self.stream_options
.and_then(|options| options.include_usage)
.unwrap_or(false)
}
pub fn max_new_tokens(&self) -> Option<u32> {
self.max_completion_tokens.or(self.max_tokens)
}
pub fn stop_sequences(&self) -> &[String] {
self.stop.as_ref().map_or(&[], StringOrArray::as_slice)
}
}
#[cfg(test)]
mod tests {
use super::*;
fn parse(body: &str) -> Result<ChatCompletionRequest, ServerError> {
ChatCompletionRequest::from_json(body)
}
#[test]
fn string_content_parses() {
let request = parse(r#"{"model":"m","messages":[{"role":"user","content":"hello"}]}"#)
.expect("valid body");
assert_eq!(request.messages[0].text().expect("text"), "hello");
assert_eq!(request.messages[0].role, MessageRole::User);
}
#[test]
fn array_form_content_is_flattened() {
let request = parse(
r#"{"model":"m","messages":[
{"role":"user","content":[{"type":"text","text":"hello"}]}
]}"#,
)
.expect("valid body");
assert_eq!(request.messages[0].text().expect("text"), "hello");
}
#[test]
fn multiple_text_parts_concatenate_without_a_separator() {
let request = parse(
r#"{"model":"m","messages":[
{"role":"user","content":[
{"type":"text","text":"hello "},
{"type":"text","text":"world"}
]}
]}"#,
)
.expect("valid body");
assert_eq!(request.messages[0].text().expect("text"), "hello world");
}
#[test]
fn empty_parts_array_flattens_to_empty_text() {
let request =
parse(r#"{"model":"m","messages":[{"role":"user","content":[]}]}"#).expect("valid");
assert_eq!(request.messages[0].text().expect("text"), "");
}
#[test]
fn non_text_content_part_is_rejected_not_dropped() {
let request = parse(
r#"{"model":"m","messages":[
{"role":"user","content":[
{"type":"text","text":"what is this"},
{"type":"image_url","image_url":{"url":"data:image/png;base64,AA"}}
]}
]}"#,
)
.expect("valid body");
let error = request.validate().expect_err("image parts are refused");
assert!(
matches!(&error, ServerError::UnsupportedContentPart { kind } if kind == "image_url"),
"{error:?}"
);
assert!(error.to_string().contains("image_url"));
}
#[test]
fn text_part_without_text_is_rejected() {
let request =
parse(r#"{"model":"m","messages":[{"role":"user","content":[{"type":"text"}]}]}"#)
.expect("valid body");
assert!(matches!(
request.validate().expect_err("text is required"),
ServerError::MissingPartText
));
}
#[test]
fn null_content_flattens_to_empty_text() {
let request = parse(
r#"{"model":"m","messages":[{"role":"assistant","content":null,"tool_calls":[]}]}"#,
)
.expect("valid body");
assert_eq!(request.messages[0].text().expect("text"), "");
}
#[test]
fn empty_messages_is_rejected() {
let request = parse(r#"{"model":"m","messages":[]}"#).expect("valid body");
assert!(matches!(
request.validate().expect_err("must be non-empty"),
ServerError::EmptyMessages
));
let request = parse(r#"{"model":"m"}"#).expect("valid body");
assert!(matches!(
request.validate().expect_err("must be non-empty"),
ServerError::EmptyMessages
));
}
#[test]
fn a_request_carrying_tools_is_accepted() {
let body = r#"{"model":"m","messages":[{"role":"user","content":"hi"}],
"tools":[{"type":"function","function":{"name":"read_file","parameters":{}}}]}"#;
let req = ChatCompletionRequest::from_json(body).expect("parses");
req.validate().expect("the renderer has a tools branch");
assert_eq!(req.tools().len(), 1);
}
#[test]
fn an_empty_tools_array_is_not_a_refusal() {
let body = r#"{"model":"m","messages":[{"role":"user","content":"hi"}],"tools":[]}"#;
let req = ChatCompletionRequest::from_json(body).expect("parses");
req.validate().expect("an empty list asks for nothing");
assert!(req.tools().is_empty());
}
#[test]
fn the_tool_name_charset_is_openais() {
for good in ["f", "get_weather", "read-file", "a1", &"n".repeat(64)] {
assert!(is_valid_tool_name(good), "{good}");
}
for bad in [
"",
"get weather",
"say\"hi",
"read<file>",
"a.b",
"naïve",
"a\u{200b}b",
&"n".repeat(65),
] {
assert!(!is_valid_tool_name(bad), "{bad}");
}
}
#[test]
fn a_tool_definition_name_outside_the_charset_is_refused_with_the_name() {
let body = r#"{"model":"m","messages":[{"role":"user","content":"hi"}],
"tools":[{"type":"function","function":{"name":"read<file>"}}]}"#;
let error = ChatCompletionRequest::from_json(body)
.expect("parses")
.validate()
.expect_err("hostile name");
assert!(
matches!(&error, ServerError::InvalidToolName { name, param }
if name == "read<file>" && *param == "tools"),
"{error:?}"
);
assert_eq!(error.status(), 400);
assert!(error.to_string().contains("read<file>"));
}
#[test]
fn a_definition_with_no_usable_name_is_refused_too() {
for tools in [
r#"[{"type":"function","function":{"parameters":{}}}]"#,
r#"[{"type":"function","function":{"name":42}}]"#,
r#"[{"type":"function"}]"#,
r#"[{}]"#,
] {
let body = format!(
r#"{{"model":"m","messages":[{{"role":"user","content":"hi"}}],"tools":{tools}}}"#
);
let error = parse(&body)
.expect("parses")
.validate()
.expect_err("a nameless tool cannot be called back");
assert!(
matches!(error, ServerError::InvalidToolName { .. }),
"{tools}: {error:?}"
);
}
}
#[test]
fn a_bare_tool_definition_is_named_by_its_own_name_field() {
let ok = r#"{"model":"m","messages":[{"role":"user","content":"hi"}],
"tools":[{"name":"read_file","parameters":{}}]}"#;
parse(ok).expect("parses").validate().expect("valid name");
let bad = r#"{"model":"m","messages":[{"role":"user","content":"hi"}],
"tools":[{"name":"read file","parameters":{}}]}"#;
assert!(matches!(
parse(bad).expect("parses").validate().expect_err("refused"),
ServerError::InvalidToolName { .. }
));
}
#[test]
fn a_tool_name_echoed_back_on_an_assistant_turn_is_checked_against_messages() {
let body = r#"{"model":"m","messages":[
{"role":"user","content":"hi"},
{"role":"assistant","content":null,"tool_calls":[
{"id":"call_1","type":"function",
"function":{"name":"say\"hi","arguments":"{}"}}
]}
]}"#;
let error = parse(body)
.expect("parses")
.validate()
.expect_err("hostile name");
assert!(
matches!(&error, ServerError::InvalidToolName { name, param }
if name == "say\"hi" && *param == "messages"),
"{error:?}"
);
}
#[test]
fn tool_choice_accepts_only_what_the_template_can_express() {
let base = r#""model":"m","messages":[{"role":"user","content":"hi"}]"#;
for accepted in ["\"auto\"", "\"none\""] {
parse(&format!("{{{base},\"tool_choice\":{accepted}}}"))
.expect("parses")
.validate()
.unwrap_or_else(|e| panic!("{accepted} is renderable: {e}"));
}
parse(&format!("{{{base}}}"))
.expect("parses")
.validate()
.expect("absent is auto");
for refused in [
"\"required\"",
r#"{"type":"function","function":{"name":"read_file"}}"#,
"\"banana\"",
] {
let error = parse(&format!("{{{base},\"tool_choice\":{refused}}}"))
.expect("parses")
.validate()
.expect_err("cannot be forced");
assert!(
matches!(error, ServerError::UnsupportedToolChoice { .. }),
"{refused}: {error:?}"
);
assert_eq!(error.param(), Some("tool_choice"));
assert!(error.to_string().contains("auto"), "{refused}");
}
}
#[test]
fn a_non_empty_stop_is_refused_rather_than_dropped() {
let base = r#""model":"m","messages":[{"role":"user","content":"hi"}]"#;
for sent in ["\"<end>\"", r#"["a","b"]"#] {
let error = parse(&format!("{{{base},\"stop\":{sent}}}"))
.expect("parses")
.validate()
.expect_err("no consumer for stop strings");
assert!(
matches!(error, ServerError::StopUnsupported),
"{sent}: {error:?}"
);
assert_eq!(error.status(), 400);
assert_eq!(error.param(), Some("stop"));
}
parse(&format!("{{{base}}}"))
.expect("parses")
.validate()
.expect("absent asks for nothing");
parse(&format!("{{{base},\"stop\":[]}}"))
.expect("parses")
.validate()
.expect("an empty list asks for nothing");
parse(&format!("{{{base},\"stop\":null}}"))
.expect("parses")
.validate()
.expect("null is absent");
}
#[test]
fn n_above_one_is_rejected() {
let body = r#"{"model":"m","messages":[{"role":"user","content":"hi"}],"n":2}"#;
let request = parse(body).expect("valid body");
assert!(matches!(
request.validate().expect_err("n > 1 cannot be honoured"),
ServerError::MultipleChoices { n: 2 }
));
}
#[test]
fn n_of_at_most_one_is_accepted() {
for body in [
r#"{"model":"m","messages":[{"role":"user","content":"hi"}],"n":1}"#,
r#"{"model":"m","messages":[{"role":"user","content":"hi"}]}"#,
r#"{"model":"m","messages":[{"role":"user","content":"hi"}],"n":0}"#,
] {
parse(body).expect("valid body").validate().expect("ok");
}
}
#[test]
fn both_max_token_spellings_are_read_and_the_newer_one_wins() {
let base = r#""model":"m","messages":[{"role":"user","content":"hi"}]"#;
let only_old = parse(&format!("{{{base},\"max_tokens\":16}}")).expect("valid");
assert_eq!(only_old.max_new_tokens(), Some(16));
let only_new = parse(&format!("{{{base},\"max_completion_tokens\":32}}")).expect("valid");
assert_eq!(only_new.max_new_tokens(), Some(32));
let both = parse(&format!(
"{{{base},\"max_tokens\":16,\"max_completion_tokens\":32}}"
))
.expect("valid");
assert_eq!(both.max_new_tokens(), Some(32));
let neither = parse(&format!("{{{base}}}")).expect("valid");
assert_eq!(neither.max_new_tokens(), None);
}
#[test]
fn unknown_fields_are_ignored() {
let request = parse(
r#"{"model":"m","messages":[{"role":"user","content":"hi"}],
"presence_penalty":0.5,"logprobs":true,"future_knob":{"a":[1]}}"#,
)
.expect("unknown fields must not fail the request");
request.validate().expect("still valid");
}
#[test]
fn malformed_json_is_a_typed_error() {
let error = parse("{not json").expect_err("malformed");
assert!(matches!(error, ServerError::MalformedJson(_)));
assert_eq!(error.status(), 400);
}
#[test]
fn stop_accepts_a_string_or_an_array() {
let base = r#""model":"m","messages":[{"role":"user","content":"hi"}]"#;
let one = parse(&format!("{{{base},\"stop\":\"<end>\"}}")).expect("valid");
assert_eq!(one.stop_sequences(), ["<end>"]);
let many = parse(&format!("{{{base},\"stop\":[\"a\",\"b\"]}}")).expect("valid");
assert_eq!(many.stop_sequences(), ["a", "b"]);
let none = parse(&format!("{{{base}}}")).expect("valid");
assert!(none.stop_sequences().is_empty());
}
#[test]
fn stream_and_include_usage_default_to_false() {
let base = r#""model":"m","messages":[{"role":"user","content":"hi"}]"#;
let plain = parse(&format!("{{{base}}}")).expect("valid");
assert!(!plain.stream());
assert!(!plain.include_usage());
let streaming = parse(&format!(
"{{{base},\"stream\":true,\"stream_options\":{{\"include_usage\":true}}}}"
))
.expect("valid");
assert!(streaming.stream());
assert!(streaming.include_usage());
let bare_stream = parse(&format!("{{{base},\"stream\":true}}")).expect("valid");
assert!(bare_stream.stream());
assert!(!bare_stream.include_usage());
}
#[test]
fn tool_calls_and_tool_call_id_round_trip_without_loss() {
let body = r#"{
"model":"m",
"messages":[
{"role":"user","content":"weather?"},
{"role":"assistant","content":null,"tool_calls":[
{"id":"call_abc","type":"function",
"function":{"name":"get_weather","arguments":"{\"city\":\"Cairo\"}"}}
]},
{"role":"tool","tool_call_id":"call_abc","content":"31C","name":"get_weather"}
],
"tools":[{"type":"function","function":{"name":"get_weather","strict":true}}],
"tool_choice":"auto"
}"#;
let request = ChatCompletionRequest::from_json(body).expect("valid body");
let calls = request.messages[1]
.tool_calls
.as_ref()
.expect("tool_calls preserved");
assert_eq!(calls[0].id, "call_abc");
assert_eq!(calls[0].kind, "function");
assert_eq!(calls[0].function.name, "get_weather");
assert_eq!(calls[0].function.arguments, r#"{"city":"Cairo"}"#);
assert_eq!(request.messages[2].role, MessageRole::Tool);
assert_eq!(
request.messages[2].tool_call_id.as_deref(),
Some("call_abc")
);
assert_eq!(request.messages[2].name.as_deref(), Some("get_weather"));
assert_eq!(request.messages[2].text().expect("text"), "31C");
let tools = request.tools.as_ref().expect("tools preserved");
assert_eq!(tools[0]["function"]["strict"], true);
assert_eq!(request.tool_choice, Some(serde_json::json!("auto")));
let round_tripped: ChatCompletionRequest =
serde_json::from_str(&serde_json::to_string(&request).expect("serializes"))
.expect("re-parses");
assert_eq!(round_tripped, request);
}
#[test]
fn every_role_parses() {
for (wire, role) in [
("system", MessageRole::System),
("user", MessageRole::User),
("assistant", MessageRole::Assistant),
("tool", MessageRole::Tool),
] {
let body = format!(r#"{{"model":"m","messages":[{{"role":"{wire}","content":"x"}}]}}"#);
let request = parse(&body).expect("valid role");
assert_eq!(request.messages[0].role, role);
assert_eq!(role.as_str(), wire);
}
assert!(matches!(
parse(r#"{"model":"m","messages":[{"role":"wizard","content":"x"}]}"#)
.expect_err("unknown role"),
ServerError::MalformedJson(_)
));
}
}