armature-core 0.5.0

//! Small Vector Optimizations
//!
//! This module provides stack-allocated vector types for common use cases
//! in HTTP frameworks. By using `SmallVec`, we avoid heap allocations for
//! typical request sizes while maintaining Vec-like semantics.
//!
//! ## Performance Impact
//!
//! | Use Case | Typical Size | Inline Capacity | Heap Alloc Saved |
//! |----------|--------------|-----------------|------------------|
//! | Query params | 2-5 | 8 | ~99% |
//! | Path params | 1-3 | 4 | ~100% |
//! | Middlewares | 3-8 | 8 | ~95% |
//! | Form fields | 5-12 | 16 | ~90% |
//! | Cookies | 2-6 | 8 | ~98% |
//! | Route segments | 2-5 | 8 | ~99% |
//!
//! ## Usage
//!
//! ```rust,ignore
//! use armature_core::small_vec::{SmallQueryParams, SmallPathParams, SmallVecExt};
//! use std::borrow::Cow;
//!
//! // Stack-allocated for typical sizes
//! let mut params = SmallQueryParams::new();
//! params.push((Cow::Borrowed("page"), Cow::Borrowed("1")));
//! params.push((Cow::Borrowed("limit"), Cow::Borrowed("10")));
//! assert!(params.is_inline()); // No heap allocation
//! ```

use smallvec::SmallVec;
use std::borrow::Cow;
use std::fmt;

// ============================================================================
// Inline Capacities (tuned for HTTP workloads)
// ============================================================================

/// Query parameters: most requests have 0-5 params
pub const QUERY_PARAM_INLINE: usize = 8;

/// Path parameters: most routes have 0-3 params
pub const PATH_PARAM_INLINE: usize = 4;

/// Middleware chain: typical apps have 3-8 middlewares
pub const MIDDLEWARE_INLINE: usize = 8;

/// Form fields: typical forms have 5-15 fields
pub const FORM_FIELD_INLINE: usize = 16;

/// Cookies: typical requests have 2-6 cookies
pub const COOKIE_INLINE: usize = 8;

/// Route segments: typical paths have 2-5 segments
pub const ROUTE_SEGMENT_INLINE: usize = 8;

/// Generic small collection: 8 elements inline
pub const SMALL_INLINE: usize = 8;

/// Tiny collection: 4 elements inline
pub const TINY_INLINE: usize = 4;

// ============================================================================
// Type Aliases for Common Use Cases
// ============================================================================

/// Small vector for query parameters (key-value pairs).
/// Stores up to 8 params inline (~256 bytes on stack).
pub type SmallQueryParams<'a> = SmallVec<[(Cow<'a, str>, Cow<'a, str>); QUERY_PARAM_INLINE]>;

/// Small vector for path parameters (key-value pairs).
/// Stores up to 4 params inline (~128 bytes on stack).
pub type SmallPathParams<'a> = SmallVec<[(Cow<'a, str>, Cow<'a, str>); PATH_PARAM_INLINE]>;

/// Small vector for string pairs (owned).
pub type SmallPairs = SmallVec<[(String, String); SMALL_INLINE]>;

/// Small vector for strings.
pub type SmallStrings = SmallVec<[String; SMALL_INLINE]>;

/// Small vector for bytes.
pub type SmallBytes = SmallVec<[u8; 64]>;

/// Small vector for route segments.
pub type SmallSegments<'a> = SmallVec<[&'a str; ROUTE_SEGMENT_INLINE]>;

/// Small vector for generic items.
pub type Small<T> = SmallVec<[T; SMALL_INLINE]>;

/// Tiny vector for very small collections.
pub type Tiny<T> = SmallVec<[T; TINY_INLINE]>;

// ============================================================================
// Query Parameters
// ============================================================================

/// Optimized query parameter storage.
///
/// Uses SmallVec to store parameters inline for typical request sizes,
/// avoiding heap allocation for most requests.
#[derive(Clone, Default)]
pub struct QueryParams {
    inner: SmallVec<[(String, String); QUERY_PARAM_INLINE]>,
}

impl QueryParams {
    /// Create empty params.
    #[inline]
    pub const fn new() -> Self {
        Self {
            inner: SmallVec::new_const(),
        }
    }

    /// Create with capacity.
    #[inline]
    pub fn with_capacity(cap: usize) -> Self {
        Self {
            inner: SmallVec::with_capacity(cap),
        }
    }

    /// Check if storage is inline (no heap allocation).
    #[inline]
    pub fn is_inline(&self) -> bool {
        !self.inner.spilled()
    }

    /// Get number of parameters.
    #[inline]
    pub fn len(&self) -> usize {
        self.inner.len()
    }

    /// Check if empty.
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.inner.is_empty()
    }

    /// Add a parameter.
    #[inline]
    pub fn push(&mut self, key: impl Into<String>, value: impl Into<String>) {
        self.inner.push((key.into(), value.into()));
    }

    /// Get first value for a key.
    #[inline]
    pub fn get(&self, key: &str) -> Option<&str> {
        self.inner
            .iter()
            .find(|(k, _)| k == key)
            .map(|(_, v)| v.as_str())
    }

    /// Get all values for a key (for multi-value params like `?tag=a&tag=b`).
    #[inline]
    pub fn get_all<'a>(&'a self, key: &'a str) -> impl Iterator<Item = &'a str> {
        self.inner
            .iter()
            .filter(move |(k, _)| k == key)
            .map(|(_, v)| v.as_str())
    }

    /// Check if key exists.
    #[inline]
    pub fn contains(&self, key: &str) -> bool {
        self.inner.iter().any(|(k, _)| k == key)
    }

    /// Iterate over all params.
    #[inline]
    pub fn iter(&self) -> impl Iterator<Item = (&str, &str)> {
        self.inner.iter().map(|(k, v)| (k.as_str(), v.as_str()))
    }

    /// Parse from query string (e.g., "a=1&b=2").
    pub fn parse(query: &str) -> Self {
        let mut params = Self::new();

        for part in query.split('&') {
            if part.is_empty() {
                continue;
            }

            if let Some((key, value)) = part.split_once('=') {
                // URL decode
                let key = urlencoding::decode(key).unwrap_or(Cow::Borrowed(key));
                let value = urlencoding::decode(value).unwrap_or(Cow::Borrowed(value));
                params.push(key.into_owned(), value.into_owned());
            } else {
                // Key without value
                let key = urlencoding::decode(part).unwrap_or(Cow::Borrowed(part));
                params.push(key.into_owned(), String::new());
            }
        }

        params
    }

    /// Convert to owned Vec (for compatibility).
    #[inline]
    pub fn to_vec(&self) -> Vec<(String, String)> {
        self.inner.to_vec()
    }
}

impl fmt::Debug for QueryParams {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_map()
            .entries(self.inner.iter().map(|(k, v)| (k, v)))
            .finish()
    }
}

impl<'a> IntoIterator for &'a QueryParams {
    type Item = (&'a str, &'a str);
    type IntoIter = std::iter::Map<
        std::slice::Iter<'a, (String, String)>,
        fn(&'a (String, String)) -> (&'a str, &'a str),
    >;

    fn into_iter(self) -> Self::IntoIter {
        self.inner.iter().map(|(k, v)| (k.as_str(), v.as_str()))
    }
}

// ============================================================================
// Path Parameters
// ============================================================================

/// Optimized path parameter storage.
///
/// Most routes have 0-3 path parameters, so we store 4 inline.
#[derive(Clone, Default)]
pub struct PathParams {
    inner: SmallVec<[(String, String); PATH_PARAM_INLINE]>,
}

impl PathParams {
    /// Create empty params.
    #[inline]
    pub const fn new() -> Self {
        Self {
            inner: SmallVec::new_const(),
        }
    }

    /// Check if storage is inline.
    #[inline]
    pub fn is_inline(&self) -> bool {
        !self.inner.spilled()
    }

    /// Get number of parameters.
    #[inline]
    pub fn len(&self) -> usize {
        self.inner.len()
    }

    /// Check if empty.
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.inner.is_empty()
    }

    /// Add a parameter.
    #[inline]
    pub fn push(&mut self, key: impl Into<String>, value: impl Into<String>) {
        self.inner.push((key.into(), value.into()));
    }

    /// Get value by name.
    #[inline]
    pub fn get(&self, name: &str) -> Option<&str> {
        self.inner
            .iter()
            .find(|(k, _)| k == name)
            .map(|(_, v)| v.as_str())
    }

    /// Get value by index (for positional params).
    #[inline]
    pub fn get_index(&self, index: usize) -> Option<&str> {
        self.inner.get(index).map(|(_, v)| v.as_str())
    }

    /// Iterate over params.
    #[inline]
    pub fn iter(&self) -> impl Iterator<Item = (&str, &str)> {
        self.inner.iter().map(|(k, v)| (k.as_str(), v.as_str()))
    }
}

impl fmt::Debug for PathParams {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_map()
            .entries(self.inner.iter().map(|(k, v)| (k, v)))
            .finish()
    }
}

// ============================================================================
// Form Fields
// ============================================================================

/// Optimized form field storage.
///
/// Typical forms have 5-15 fields, so we store 16 inline.
#[derive(Clone, Default)]
pub struct FormFields {
    inner: SmallVec<[(String, String); FORM_FIELD_INLINE]>,
}

impl FormFields {
    /// Create empty fields.
    #[inline]
    pub const fn new() -> Self {
        Self {
            inner: SmallVec::new_const(),
        }
    }

    /// Check if storage is inline.
    #[inline]
    pub fn is_inline(&self) -> bool {
        !self.inner.spilled()
    }

    /// Get number of fields.
    #[inline]
    pub fn len(&self) -> usize {
        self.inner.len()
    }

    /// Check if empty.
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.inner.is_empty()
    }

    /// Add a field.
    #[inline]
    pub fn push(&mut self, name: impl Into<String>, value: impl Into<String>) {
        self.inner.push((name.into(), value.into()));
    }

    /// Get field value.
    #[inline]
    pub fn get(&self, name: &str) -> Option<&str> {
        self.inner
            .iter()
            .find(|(k, _)| k == name)
            .map(|(_, v)| v.as_str())
    }

    /// Check if field exists.
    #[inline]
    pub fn contains(&self, name: &str) -> bool {
        self.inner.iter().any(|(k, _)| k == name)
    }

    /// Iterate over fields.
    #[inline]
    pub fn iter(&self) -> impl Iterator<Item = (&str, &str)> {
        self.inner.iter().map(|(k, v)| (k.as_str(), v.as_str()))
    }

    /// Parse from URL-encoded body.
    pub fn parse(body: &str) -> Self {
        let mut fields = Self::new();

        for part in body.split('&') {
            if part.is_empty() {
                continue;
            }

            if let Some((key, value)) = part.split_once('=') {
                let key = urlencoding::decode(key).unwrap_or(Cow::Borrowed(key));
                let value = urlencoding::decode(value).unwrap_or(Cow::Borrowed(value));
                fields.push(key.into_owned(), value.into_owned());
            }
        }

        fields
    }
}

impl fmt::Debug for FormFields {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_map()
            .entries(self.inner.iter().map(|(k, v)| (k, v)))
            .finish()
    }
}

// ============================================================================
// Cookies
// ============================================================================

/// Optimized cookie storage.
///
/// Most requests have 2-6 cookies, so we store 8 inline.
#[derive(Clone, Default)]
pub struct Cookies {
    inner: SmallVec<[(String, String); COOKIE_INLINE]>,
}

impl Cookies {
    /// Create empty cookies.
    #[inline]
    pub const fn new() -> Self {
        Self {
            inner: SmallVec::new_const(),
        }
    }

    /// Check if storage is inline.
    #[inline]
    pub fn is_inline(&self) -> bool {
        !self.inner.spilled()
    }

    /// Get number of cookies.
    #[inline]
    pub fn len(&self) -> usize {
        self.inner.len()
    }

    /// Check if empty.
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.inner.is_empty()
    }

    /// Add a cookie.
    #[inline]
    pub fn push(&mut self, name: impl Into<String>, value: impl Into<String>) {
        self.inner.push((name.into(), value.into()));
    }

    /// Get cookie value.
    #[inline]
    pub fn get(&self, name: &str) -> Option<&str> {
        self.inner
            .iter()
            .find(|(k, _)| k == name)
            .map(|(_, v)| v.as_str())
    }

    /// Check if cookie exists.
    #[inline]
    pub fn contains(&self, name: &str) -> bool {
        self.inner.iter().any(|(k, _)| k == name)
    }

    /// Iterate over cookies.
    #[inline]
    pub fn iter(&self) -> impl Iterator<Item = (&str, &str)> {
        self.inner.iter().map(|(k, v)| (k.as_str(), v.as_str()))
    }

    /// Parse from Cookie header value.
    pub fn parse(cookie_header: &str) -> Self {
        let mut cookies = Self::new();

        for cookie in cookie_header.split(';') {
            let cookie = cookie.trim();
            if cookie.is_empty() {
                continue;
            }

            if let Some((name, value)) = cookie.split_once('=') {
                cookies.push(name.trim().to_string(), value.trim().to_string());
            }
        }

        cookies
    }
}

impl fmt::Debug for Cookies {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_map()
            .entries(self.inner.iter().map(|(k, v)| (k, v)))
            .finish()
    }
}

// ============================================================================
// Helper Traits
// ============================================================================

/// Extension trait for SmallVec operations.
pub trait SmallVecExt<T> {
    /// Check if the SmallVec is still inline (not spilled to heap).
    fn is_inline(&self) -> bool;

    /// Get stack usage in bytes.
    fn stack_size() -> usize;
}

impl<T, const N: usize> SmallVecExt<T> for SmallVec<[T; N]> {
    #[inline]
    fn is_inline(&self) -> bool {
        !self.spilled()
    }

    #[inline]
    fn stack_size() -> usize {
        std::mem::size_of::<SmallVec<[T; N]>>()
    }
}

// ============================================================================
// Conversion Utilities
// ============================================================================

/// Convert a Vec to SmallVec, trying to stay inline if possible.
#[inline]
pub fn vec_to_small<T, const N: usize>(vec: Vec<T>) -> SmallVec<[T; N]> {
    SmallVec::from_vec(vec)
}

/// Create SmallVec from iterator with capacity hint.
#[inline]
pub fn collect_small<T, I, const N: usize>(iter: I) -> SmallVec<[T; N]>
where
    I: IntoIterator<Item = T>,
{
    iter.into_iter().collect()
}

// ============================================================================
// Tests
// ============================================================================

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

    #[test]
    fn test_query_params_inline() {
        let mut params = QueryParams::new();

        // Add typical number of params
        for i in 0..QUERY_PARAM_INLINE {
            params.push(format!("key{}", i), format!("value{}", i));
        }

        assert!(params.is_inline());
        assert_eq!(params.len(), QUERY_PARAM_INLINE);

        // One more should spill
        params.push("extra", "value");
        assert!(!params.is_inline());
    }

    #[test]
    fn test_query_params_parse() {
        let params = QueryParams::parse("name=Alice&age=30&city=NYC");

        assert_eq!(params.get("name"), Some("Alice"));
        assert_eq!(params.get("age"), Some("30"));
        assert_eq!(params.get("city"), Some("NYC"));
        assert!(params.is_inline());
    }

    #[test]
    fn test_query_params_url_decode() {
        let params = QueryParams::parse("name=Hello%20World&emoji=%F0%9F%98%80");

        assert_eq!(params.get("name"), Some("Hello World"));
        assert_eq!(params.get("emoji"), Some("😀"));
    }

    #[test]
    fn test_path_params_inline() {
        let mut params = PathParams::new();
        params.push("id", "123");
        params.push("name", "test");

        assert!(params.is_inline());
        assert_eq!(params.get("id"), Some("123"));
        assert_eq!(params.get_index(0), Some("123"));
    }

    #[test]
    fn test_form_fields_inline() {
        let mut fields = FormFields::new();

        // Add typical form fields
        for i in 0..FORM_FIELD_INLINE {
            fields.push(format!("field{}", i), format!("value{}", i));
        }

        assert!(fields.is_inline());
    }

    #[test]
    fn test_cookies_parse() {
        let cookies = Cookies::parse("session=abc123; user=alice; theme=dark");

        assert_eq!(cookies.get("session"), Some("abc123"));
        assert_eq!(cookies.get("user"), Some("alice"));
        assert_eq!(cookies.get("theme"), Some("dark"));
        assert!(cookies.is_inline());
    }

    #[test]
    fn test_small_vec_stack_size() {
        // Verify reasonable stack sizes
        assert!(SmallVec::<[(String, String); QUERY_PARAM_INLINE]>::stack_size() < 512);
        assert!(SmallVec::<[(String, String); PATH_PARAM_INLINE]>::stack_size() < 256);
    }
}