yeti_types/

content_type.rs

//! Content type enum and format resolution.
//!
//! Defines the unified content type for all interfaces. Lives in yeti-types (L0)
//! so Context can reference it directly. Serialization implementations that need
//! heavy deps (ciborium, rmp-serde, serde_yaml) live in yeti-sdk (L2).
//!
//! Resolution priority:
//! 1. Transport headers (Upgrade, Accept: text/event-stream, Content-Type: application/grpc)
//! 2. URL extension (.json, .yaml, .sse, .proto, etc.)
//! 3. ?format= query parameter
//! 4. ?stream=sse query parameter
//! 5. Accept header (standard content negotiation)
//! 6. Default: JSON

/// Supported content types, transports, and discovery formats.
///
/// Copy, stack-allocated, zero-cost to pass around.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub enum ContentType {
    // ── Data formats (serialization) ──
    /// JSON (application/json) — default
    #[default]
    Json,
    /// YAML (application/yaml)
    Yaml,
    /// CBOR (application/cbor) — binary
    Cbor,
    /// `MessagePack` (application/msgpack) — binary
    MsgPack,
    /// CSV (text/csv) — tabular
    Csv,
    /// Protobuf (application/proto) — binary, also Connect/gRPC
    Proto,
    /// Form URL-encoded (application/x-www-form-urlencoded) — request deserialization
    FormUrlEncoded,
    /// Multipart form data (multipart/form-data) — request deserialization
    MultipartForm,

    // ── Streaming transports ──
    /// Server-Sent Events (text/event-stream)
    Sse,
    /// WebSocket (Upgrade: websocket)
    WebSocket,
    /// gRPC-Web / Connect server-streaming (application/grpc-web+json).
    /// Length-prefixed envelope frames `[flag:u8][len:u32 BE][payload]`
    /// over a held-open HTTP/2 response — the browser-reachable member of
    /// the gRPC family (raw gRPC needs HTTP/2 trailers the fetch API
    /// can't read). Shares the subscribe path with [`Self::Sse`]; only
    /// the frame encoding differs.
    GrpcWeb,

    // ── Discovery formats ──
    /// `OpenAPI` 3.1 spec
    OpenApi,
    /// MCP tools/list response
    Mcp,
    /// Human-readable Markdown
    Markdown,
}

impl ContentType {
    /// Parse from URL file extension.
    #[must_use]
    pub fn from_extension(ext: &str) -> Option<Self> {
        match ext {
            "json" => Some(Self::Json),
            "yaml" | "yml" => Some(Self::Yaml),
            "cbor" => Some(Self::Cbor),
            "msgpk" | "msgpack" => Some(Self::MsgPack),
            "csv" => Some(Self::Csv),
            "proto" => Some(Self::Proto),
            "sse" => Some(Self::Sse),
            "ws" => Some(Self::WebSocket),
            "openapi" => Some(Self::OpenApi),
            "mcp" => Some(Self::Mcp),
            "md" => Some(Self::Markdown),
            _ => None,
        }
    }

    /// Parse from Content-Type request header for transport/format detection.
    ///
    /// Returns `None` for standard types that don't need special routing.
    #[must_use]
    pub fn from_content_type_header(header: &str) -> Option<Self> {
        let media_type = header.split(';').next().unwrap_or("").trim();
        match media_type {
            // gRPC-Web server-streaming → the streaming subscribe path.
            // Unambiguous (distinct from unary application/grpc+proto and
            // application/connect+proto), so it can't misroute unary RPC.
            "application/grpc-web" | "application/grpc-web+proto" | "application/grpc-web+json" => {
                Some(Self::GrpcWeb)
            },
            "application/grpc" | "application/grpc+proto" => Some(Self::Proto),
            "application/proto" | "application/protobuf" => Some(Self::Proto),
            "application/connect+proto" => Some(Self::Proto),
            "application/x-www-form-urlencoded" => Some(Self::FormUrlEncoded),
            "multipart/form-data" => Some(Self::MultipartForm),
            _ => None,
        }
    }

    /// Parse from Accept header value. Falls back to Json.
    #[must_use]
    pub fn from_accept_header(accept: Option<&str>) -> Self {
        let Some(accept) = accept else {
            return Self::Json;
        };
        for part in accept.split(',') {
            let media_type = part.split(';').next().unwrap_or("").trim();
            match media_type {
                "application/json" | "*/*" => return Self::Json,
                "application/yaml" | "application/x-yaml" | "text/yaml" => return Self::Yaml,
                "application/cbor" => return Self::Cbor,
                "application/msgpack" | "application/x-msgpack" => return Self::MsgPack,
                "text/csv" => return Self::Csv,
                "application/grpc-web"
                | "application/grpc-web+proto"
                | "application/grpc-web+json" => return Self::GrpcWeb,
                "application/proto" | "application/protobuf" | "application/grpc" => {
                    return Self::Proto;
                },
                "text/event-stream" => return Self::Sse,
                _ => {},
            }
        }
        Self::Json
    }

    /// Parse from `?format=` query parameter.
    #[must_use]
    pub fn from_query_param(query: &str) -> Option<Self> {
        for pair in query.split('&') {
            let mut kv = pair.splitn(2, '=');
            if let (Some("format"), Some(value)) = (kv.next(), kv.next()) {
                return match value {
                    "json" => Some(Self::Json),
                    "yaml" | "yml" => Some(Self::Yaml),
                    "cbor" => Some(Self::Cbor),
                    "msgpack" | "messagepack" => Some(Self::MsgPack),
                    "csv" => Some(Self::Csv),
                    "proto" | "protobuf" => Some(Self::Proto),
                    _ => None,
                };
            }
        }
        None
    }

    /// Content-Type header value for the response.
    #[must_use]
    pub const fn header_value(self) -> &'static str {
        match self {
            Self::Json | Self::OpenApi | Self::Mcp => "application/json",
            Self::Yaml => "application/yaml",
            Self::Cbor => "application/cbor",
            Self::MsgPack => "application/msgpack",
            Self::Csv => "text/csv",
            Self::Proto => "application/proto",
            Self::FormUrlEncoded => "application/x-www-form-urlencoded",
            Self::MultipartForm => "multipart/form-data",
            Self::Sse => "text/event-stream",
            Self::WebSocket => "text/plain",
            Self::GrpcWeb => "application/grpc-web+json",
            Self::Markdown => "text/markdown",
        }
    }

    /// Whether this is a streaming transport (SSE, WebSocket, gRPC-Web).
    #[must_use]
    pub const fn is_streaming(self) -> bool {
        matches!(self, Self::Sse | Self::WebSocket | Self::GrpcWeb)
    }

    /// Whether this is a server-to-client streaming-subscribe transport
    /// (SSE or gRPC-Web) — the formats the subscribe handler serves over
    /// a held-open response. Excludes WebSocket (handled by an upgrade in
    /// the host layer before dispatch).
    #[must_use]
    pub const fn is_streaming_subscribe(self) -> bool {
        matches!(self, Self::Sse | Self::GrpcWeb)
    }

    /// Whether this is a data serialization format.
    #[must_use]
    pub const fn is_data_format(self) -> bool {
        matches!(
            self,
            Self::Json | Self::Yaml | Self::Cbor | Self::MsgPack | Self::Csv | Self::Proto
        )
    }
}

/// Resolve content type from all sources. Zero allocations.
///
/// Priority: transport headers > extension > ?format= > ?stream=sse > Accept > JSON default.
pub fn resolve_format(
    headers: &http::HeaderMap,
    extension: Option<&str>,
    query: &str,
) -> ContentType {
    // 1. Transport headers (highest priority)
    if headers
        .get("upgrade")
        .and_then(|v| v.to_str().ok())
        .is_some_and(|v| v.eq_ignore_ascii_case("websocket"))
    {
        return ContentType::WebSocket;
    }
    if headers
        .get("accept")
        .and_then(|v| v.to_str().ok())
        .is_some_and(|v| v.contains("text/event-stream"))
    {
        return ContentType::Sse;
    }
    if let Some(ct) = headers
        .get("content-type")
        .and_then(|v| v.to_str().ok())
        .and_then(ContentType::from_content_type_header)
    {
        return ct;
    }

    // 2. URL extension
    if let Some(ext) = extension
        && let Some(ct) = ContentType::from_extension(ext)
    {
        return ct;
    }

    // 3. ?format= query param
    if let Some(ct) = ContentType::from_query_param(query) {
        return ct;
    }

    // 4. ?stream=sse / ?stream=grpcweb opt-in for streaming subscribe
    for pair in query.split('&') {
        let mut kv = pair.splitn(2, '=');
        match (kv.next(), kv.next()) {
            (Some("stream"), Some("sse")) => return ContentType::Sse,
            (Some("stream"), Some("grpcweb" | "grpc-web")) => return ContentType::GrpcWeb,
            _ => {},
        }
    }

    // 5. Accept header
    let accept = headers.get("accept").and_then(|v| v.to_str().ok());
    ContentType::from_accept_header(accept)
}

/// Strip a known file extension from a path segment.
///
/// Only strips extensions that map to known `ContentType` variants.
/// Returns (`stripped_segment`, `optional_extension`).
///
/// Zero allocations — returns slices into the input.
#[must_use]
pub fn strip_extension(segment: &str) -> (&str, Option<&str>) {
    if let Some(dot) = segment.rfind('.') {
        let ext = &segment[dot + 1..];
        if ContentType::from_extension(ext).is_some() {
            return (&segment[..dot], Some(ext));
        }
    }
    (segment, None)
}

/// Strip a known file extension from the last segment of a URL path.
///
/// Returns (`clean_path_slice`, `optional_extension`). Zero allocations —
/// both return values are slices into the input.
///
/// Examples:
/// - "/Users/user-123.json" → ("/Users/user-123", Some("json"))
/// - "/Users.sse" → ("/Users", Some("sse"))
/// - "/Users/user-123" → ("/Users/user-123", None)
#[must_use]
pub fn strip_extension_from_path(path: &str) -> (&str, Option<&str>) {
    // Find the last '/' to isolate the final segment
    let last_slash = path.rfind('/').unwrap_or(0);
    let last_segment = &path[last_slash..];

    // Check for known extension in the last segment
    if let Some(dot) = last_segment.rfind('.') {
        let ext = &last_segment[dot + 1..];
        if ContentType::from_extension(ext).is_some() {
            let clean_end = last_slash + dot;
            return (&path[..clean_end], Some(ext));
        }
    }
    (path, None)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn from_extension() {
        assert_eq!(ContentType::from_extension("json"), Some(ContentType::Json));
        assert_eq!(ContentType::from_extension("yaml"), Some(ContentType::Yaml));
        assert_eq!(ContentType::from_extension("cbor"), Some(ContentType::Cbor));
        assert_eq!(
            ContentType::from_extension("msgpk"),
            Some(ContentType::MsgPack)
        );
        assert_eq!(ContentType::from_extension("csv"), Some(ContentType::Csv));
        assert_eq!(
            ContentType::from_extension("proto"),
            Some(ContentType::Proto)
        );
        assert_eq!(ContentType::from_extension("sse"), Some(ContentType::Sse));
        assert_eq!(
            ContentType::from_extension("ws"),
            Some(ContentType::WebSocket)
        );
        assert_eq!(
            ContentType::from_extension("openapi"),
            Some(ContentType::OpenApi)
        );
        assert_eq!(ContentType::from_extension("mcp"), Some(ContentType::Mcp));
        assert_eq!(
            ContentType::from_extension("md"),
            Some(ContentType::Markdown)
        );
        assert_eq!(ContentType::from_extension("xml"), None);
    }

    #[test]
    fn from_content_type_header() {
        assert_eq!(
            ContentType::from_content_type_header("application/grpc"),
            Some(ContentType::Proto)
        );
        assert_eq!(
            ContentType::from_content_type_header("application/proto"),
            Some(ContentType::Proto)
        );
        assert_eq!(
            ContentType::from_content_type_header("multipart/form-data; boundary=abc"),
            Some(ContentType::MultipartForm)
        );
        assert_eq!(
            ContentType::from_content_type_header("application/x-www-form-urlencoded"),
            Some(ContentType::FormUrlEncoded)
        );
        assert_eq!(
            ContentType::from_content_type_header("application/json"),
            None
        );
    }

    #[test]
    fn from_accept_header() {
        assert_eq!(ContentType::from_accept_header(None), ContentType::Json);
        assert_eq!(
            ContentType::from_accept_header(Some("application/json")),
            ContentType::Json
        );
        assert_eq!(
            ContentType::from_accept_header(Some("application/yaml")),
            ContentType::Yaml
        );
        assert_eq!(
            ContentType::from_accept_header(Some("text/csv")),
            ContentType::Csv
        );
        assert_eq!(
            ContentType::from_accept_header(Some("application/proto")),
            ContentType::Proto
        );
        assert_eq!(
            ContentType::from_accept_header(Some("text/event-stream")),
            ContentType::Sse
        );
        assert_eq!(
            ContentType::from_accept_header(Some("text/html")),
            ContentType::Json
        );
    }

    #[test]
    fn from_query_param() {
        assert_eq!(ContentType::from_query_param(""), None);
        assert_eq!(
            ContentType::from_query_param("format=json"),
            Some(ContentType::Json)
        );
        assert_eq!(
            ContentType::from_query_param("format=csv"),
            Some(ContentType::Csv)
        );
        assert_eq!(
            ContentType::from_query_param("format=proto"),
            Some(ContentType::Proto)
        );
        assert_eq!(
            ContentType::from_query_param("limit=10&format=yaml&offset=0"),
            Some(ContentType::Yaml)
        );
        assert_eq!(ContentType::from_query_param("format=xml"), None);
    }

    #[test]
    fn test_strip_extension() {
        assert_eq!(strip_extension("user-123.json"), ("user-123", Some("json")));
        assert_eq!(strip_extension("Users.sse"), ("Users", Some("sse")));
        assert_eq!(strip_extension("user-123"), ("user-123", None));
        assert_eq!(
            strip_extension("file.name.json"),
            ("file.name", Some("json"))
        );
        assert_eq!(strip_extension("file.unknown"), ("file.unknown", None));
        assert_eq!(
            strip_extension("_discovery.openapi"),
            ("_discovery", Some("openapi"))
        );
    }

    #[test]
    fn resolve_format_transport_headers_win() {
        let mut headers = http::HeaderMap::new();
        headers.insert("upgrade", "websocket".parse().unwrap());
        assert_eq!(
            resolve_format(&headers, Some("json"), "format=yaml"),
            ContentType::WebSocket
        );

        let mut headers = http::HeaderMap::new();
        headers.insert("accept", "text/event-stream".parse().unwrap());
        assert_eq!(resolve_format(&headers, None, ""), ContentType::Sse);

        let mut headers = http::HeaderMap::new();
        headers.insert("content-type", "application/grpc".parse().unwrap());
        assert_eq!(resolve_format(&headers, None, ""), ContentType::Proto);
    }

    #[test]
    fn resolve_format_extension_over_query() {
        let headers = http::HeaderMap::new();
        assert_eq!(
            resolve_format(&headers, Some("cbor"), "format=json"),
            ContentType::Cbor
        );
    }

    #[test]
    fn resolve_format_stream_sse_query_param() {
        let headers = http::HeaderMap::new();
        assert_eq!(
            resolve_format(&headers, None, "stream=sse"),
            ContentType::Sse
        );
    }

    #[test]
    fn resolve_format_default_json() {
        let headers = http::HeaderMap::new();
        assert_eq!(resolve_format(&headers, None, ""), ContentType::Json);
    }
}