Add TOON format support with new rustapi-toon crate

Introduces the rustapi-toon crate for TOON (Token-Oriented Object Notation) support, enabling LLM-optimized data serialization and extraction. Updates workspace and rustapi-rs to support a new 'toon' feature, adds content negotiation, LLM response wrappers, and OpenAPI integration for TOON. Also includes a new example (toon-api) and benchmarking setup (toon_bench).

Author: Tuntii

Cargo.lock

@@ -7,11 +7,14 @@ members = [
     "crates/rustapi-validate",
     "crates/rustapi-openapi",
     "crates/rustapi-extras",
+    "crates/rustapi-toon",
     "examples/hello-world",
     "examples/sqlx-crud",
     "examples/crud-api",
     "examples/auth-api",
     "examples/proof-of-concept",
+    "examples/toon-api",
+    "benches/toon_bench",
 ]
 
 [workspace.package]
@@ -72,9 +75,16 @@ prometheus = "0.13"
 # OpenAPI
 utoipa = { version = "4.2" }
 
+# TOON format
+toon-format = { version = "0.4", default-features = false }
+
+# Benchmarking
+criterion = { version = "0.5", features = ["html_reports"] }
+
 # Internal crates
 rustapi-core = { path = "crates/rustapi-core", version = "0.1.2", default-features = false }
 rustapi-macros = { path = "crates/rustapi-macros", version = "0.1.2" }
 rustapi-validate = { path = "crates/rustapi-validate", version = "0.1.2" }
 rustapi-openapi = { path = "crates/rustapi-openapi", version = "0.1.2", default-features = false }
 rustapi-extras = { path = "crates/rustapi-extras", version = "0.1.2" }
+rustapi-toon = { path = "crates/rustapi-toon", version = "0.1.2" }

Cargo.toml

@@ -15,6 +15,7 @@ readme = "README.md"
 rustapi-core = { workspace = true, default-features = false }
 rustapi-macros = { workspace = true }
 rustapi-extras = { workspace = true, optional = true }
+rustapi-toon = { workspace = true, optional = true }
 
 # Re-exports for user convenience
 tokio = { workspace = true }
@@ -39,6 +40,9 @@ config = ["dep:rustapi-extras", "rustapi-extras/config"]
 cookies = ["dep:rustapi-extras", "rustapi-extras/cookies", "rustapi-core/cookies"]
 sqlx = ["dep:rustapi-extras", "rustapi-extras/sqlx"]
 
+# TOON format support
+toon = ["dep:rustapi-toon"]
+
 # Meta features
 extras = ["jwt", "cors", "rate-limit"]
-full = ["extras", "config", "cookies", "sqlx"]
+full = ["extras", "config", "cookies", "sqlx", "toon"]

crates/rustapi-rs/Cargo.toml

@@ -93,6 +93,32 @@ pub use rustapi_extras::sqlx;
 #[cfg(feature = "sqlx")]
 pub use rustapi_extras::{convert_sqlx_error, SqlxErrorExt};
 
+// Re-export TOON (feature-gated)
+#[cfg(feature = "toon")]
+pub mod toon {
+    //! TOON (Token-Oriented Object Notation) support
+    //!
+    //! TOON is a compact format for LLM communication that reduces token usage by 20-40%.
+    //!
+    //! # Example
+    //!
+    //! ```rust,ignore
+    //! use rustapi_rs::toon::{Toon, Negotiate, AcceptHeader};
+    //!
+    //! // As extractor
+    //! async fn handler(Toon(data): Toon<MyType>) -> impl IntoResponse { ... }
+    //!
+    //! // As response
+    //! async fn handler() -> Toon<MyType> { Toon(my_data) }
+    //!
+    //! // Content negotiation (returns JSON or TOON based on Accept header)
+    //! async fn handler(accept: AcceptHeader) -> Negotiate<MyType> {
+    //!     Negotiate::new(my_data, accept.preferred)
+    //! }
+    //! ```
+    pub use rustapi_toon::*;
+}
+
 /// Prelude module - import everything you need with `use rustapi_rs::prelude::*`
 pub mod prelude {
     // Core types
@@ -188,6 +214,10 @@ pub mod prelude {
     // SQLx types (feature-gated)
     #[cfg(feature = "sqlx")]
     pub use rustapi_extras::{convert_sqlx_error, SqlxErrorExt};
+
+    // TOON types (feature-gated)
+    #[cfg(feature = "toon")]
+    pub use rustapi_toon::{AcceptHeader, LlmResponse, Negotiate, OutputFormat, Toon};
 }
 
 #[cfg(test)]

crates/rustapi-rs/src/lib.rs

@@ -0,0 +1,42 @@
+[package]
+name = "rustapi-toon"
+description = "TOON (Token-Oriented Object Notation) support for RustAPI - LLM-optimized data format"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+license.workspace = true
+repository.workspace = true
+keywords = ["web", "framework", "api", "toon", "llm"]
+categories = ["web-programming::http-server"]
+rust-version.workspace = true
+readme = "README.md"
+
+[dependencies]
+# Core dependencies
+rustapi-core = { workspace = true }
+rustapi-openapi = { workspace = true }
+
+# TOON format
+toon-format = { workspace = true }
+
+# Serialization
+serde = { workspace = true }
+serde_json = { workspace = true }
+
+# HTTP types
+bytes = { workspace = true }
+http = { workspace = true }
+http-body-util = { workspace = true }
+
+# Async
+futures-util = { workspace = true }
+
+# Logging
+tracing = { workspace = true }
+
+# Error handling
+thiserror = { workspace = true }
+
+[dev-dependencies]
+tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
+serde_json = { workspace = true }

crates/rustapi-toon/Cargo.toml

@@ -0,0 +1,86 @@
+# rustapi-toon
+
+TOON (Token-Oriented Object Notation) support for RustAPI framework.
+
+## What is TOON?
+
+TOON is a compact, human-readable format designed for passing structured data to Large Language Models (LLMs) with significantly reduced token usage (typically 20-40% savings).
+
+## Quick Example
+
+**JSON (16 tokens, 40 bytes):**
+```json
+{
+  "users": [
+    { "id": 1, "name": "Alice" },
+    { "id": 2, "name": "Bob" }
+  ]
+}
+```
+
+**TOON (13 tokens, 28 bytes) - 18.75% token savings:**
+```
+users[2]{id,name}:
+  1,Alice
+  2,Bob
+```
+
+## Usage
+
+Add to your `Cargo.toml`:
+
+```toml
+[dependencies]
+rustapi-rs = { version = "0.1", features = ["toon"] }
+```
+
+### Toon Extractor
+
+Parse TOON request bodies:
+
+```rust
+use rustapi_rs::prelude::*;
+use rustapi_rs::toon::Toon;
+
+#[derive(Deserialize)]
+struct CreateUser {
+    name: String,
+    email: String,
+}
+
+async fn create_user(Toon(user): Toon<CreateUser>) -> impl IntoResponse {
+    // user is parsed from TOON format
+    Json(user)
+}
+```
+
+### Toon Response
+
+Return TOON formatted responses:
+
+```rust
+use rustapi_rs::prelude::*;
+use rustapi_rs::toon::Toon;
+
+#[derive(Serialize)]
+struct User {
+    id: u64,
+    name: String,
+}
+
+async fn get_user() -> Toon<User> {
+    Toon(User {
+        id: 1,
+        name: "Alice".to_string(),
+    })
+}
+```
+
+## Content Types
+
+- Request: `application/toon` or `text/toon`
+- Response: `application/toon`
+
+## License
+
+MIT OR Apache-2.0

crates/rustapi-toon/README.md

@@ -0,0 +1,48 @@
+//! TOON Error types and conversions
+
+use rustapi_core::ApiError;
+use thiserror::Error;
+
+/// Error type for TOON operations
+#[derive(Error, Debug)]
+pub enum ToonError {
+    /// Error during TOON encoding (serialization)
+    #[error("TOON encoding error: {0}")]
+    Encode(String),
+
+    /// Error during TOON decoding (parsing/deserialization)
+    #[error("TOON decoding error: {0}")]
+    Decode(String),
+
+    /// Invalid content type for TOON request
+    #[error("Invalid content type: expected application/toon or text/toon")]
+    InvalidContentType,
+
+    /// Empty body provided
+    #[error("Empty request body")]
+    EmptyBody,
+}
+
+impl From<toon_format::ToonError> for ToonError {
+    fn from(err: toon_format::ToonError) -> Self {
+        match &err {
+            toon_format::ToonError::SerializationError(_) => ToonError::Encode(err.to_string()),
+            _ => ToonError::Decode(err.to_string()),
+        }
+    }
+}
+
+impl From<ToonError> for ApiError {
+    fn from(err: ToonError) -> Self {
+        match err {
+            ToonError::Encode(msg) => {
+                ApiError::internal(format!("Failed to encode TOON: {}", msg))
+            }
+            ToonError::Decode(msg) => ApiError::bad_request(format!("Invalid TOON: {}", msg)),
+            ToonError::InvalidContentType => ApiError::bad_request(
+                "Invalid content type: expected application/toon or text/toon",
+            ),
+            ToonError::EmptyBody => ApiError::bad_request("Empty request body"),
+        }
+    }
+}