Cookie Management

/**
 * HTTP cookie representation
 * @param name Cookie name
 * @param value Cookie value
 * @param encoding Value encoding method
 * @param maxAge Maximum age in seconds (null for session cookie)
 * @param expires Expiration date (null for session cookie)
 * @param domain Cookie domain
 * @param path Cookie path
 * @param secure Secure flag (HTTPS only)
 * @param httpOnly HttpOnly flag (not accessible to JavaScript)
 * @param extensions Additional cookie attributes
 */
data class Cookie(
    val name: String,
    val value: String,
    val encoding: CookieEncoding = CookieEncoding.RAW,
    val maxAge: Int? = null,
    val expires: GMTDate? = null,
    val domain: String? = null,
    val path: String? = null,
    val secure: Boolean = false,
    val httpOnly: Boolean = false,
    val extensions: Map<String, String?> = emptyMap()
) : Serializable {
    
    /**
     * Get maxAge as Int (for compatibility)
     */
    val maxAgeInt: Int? get() = maxAge
    
    companion object {
        fun serializer(): KSerializer<Cookie>
    }
}

/**
 * Cookie value encoding methods
 */
enum class CookieEncoding {
    /**
     * No encoding - value used as-is
     */
    RAW,
    
    /**
     * Double-quote encoding - wrap value in quotes
     */
    DQUOTES,
    
    /**
     * URI encoding - percent-encode special characters
     */
    URI_ENCODING,
    
    /**
     * Base64 encoding - encode value as base64
     */
    BASE64_ENCODING
}

/**
 * Parse Set-Cookie header value into Cookie
 * @param value Set-Cookie header value
 * @return Cookie instance
 */
fun parseServerSetCookieHeader(value: String): Cookie

/**
 * Parse Cookie header value into map of name-value pairs
 * @param value Cookie header value
 * @param decodeParametersByEncoding Whether to decode values based on encoding
 * @return Map of cookie names to values
 */
fun parseClientCookiesHeader(
    value: String,
    decodeParametersByEncoding: Boolean = true
): Map<String, String>

/**
 * Render Cookie header value (for client requests)
 * @param cookie Cookie to render
 * @return Cookie header value
 */
fun renderCookieHeader(cookie: Cookie): String

/**
 * Render Set-Cookie header value (for server responses)
 * @param cookie Cookie to render
 * @return Set-Cookie header value
 */
fun renderSetCookieHeader(cookie: Cookie): String

/**
 * Render Set-Cookie header with individual parameters
 * @param name Cookie name
 * @param value Cookie value
 * @param encoding Value encoding
 * @param maxAge Maximum age in seconds
 * @param expires Expiration date
 * @param domain Cookie domain
 * @param path Cookie path
 * @param secure Secure flag
 * @param httpOnly HttpOnly flag
 * @param extensions Additional attributes
 * @param includeEncoding Whether to include encoding attribute
 * @return Set-Cookie header value
 */
fun renderSetCookieHeader(
    name: String,
    value: String,
    encoding: CookieEncoding = CookieEncoding.RAW,
    maxAge: Int? = null,
    expires: GMTDate? = null,
    domain: String? = null,
    path: String? = null,
    secure: Boolean = false,
    httpOnly: Boolean = false,
    extensions: Map<String, String?> = emptyMap(),
    includeEncoding: Boolean = true
): String

/**
 * Encode cookie value using specified encoding
 * @param value Raw cookie value
 * @param encoding Encoding method to use
 * @return Encoded cookie value
 */
fun encodeCookieValue(value: String, encoding: CookieEncoding): String

/**
 * Decode cookie value using specified encoding
 * @param value Encoded cookie value
 * @param encoding Encoding method used
 * @return Decoded cookie value
 */
fun decodeCookieValue(value: String, encoding: CookieEncoding): String

/**
 * Parse cookie date format to GMTDate
 * @param cookieDate Cookie date string
 * @return GMTDate instance
 */
fun fromCookieToGmtDate(cookieDate: String): GMTDate

/**
 * Parse HTTP date format to GMTDate
 * @param httpDate HTTP date string
 * @return GMTDate instance
 */
fun fromHttpToGmtDate(httpDate: String): GMTDate

/**
 * Format GMTDate as HTTP date string
 * @param date GMTDate to format
 * @return HTTP date string
 */
fun toHttpDate(date: GMTDate): String

import io.ktor.http.*
import io.ktor.util.date.*

// Create basic cookies
val sessionCookie = Cookie("session", "abc123")
val userCookie = Cookie("user", "john_doe", path = "/", httpOnly = true)

// Create cookie with expiration
val tomorrow = GMTDate(System.currentTimeMillis() + 86400000) // +1 day
val persistentCookie = Cookie(
    name = "remember_me",
    value = "true",
    expires = tomorrow,
    maxAge = 86400, // 1 day in seconds
    domain = ".example.com",
    path = "/",
    secure = true,
    httpOnly = true
)

// Cookie with encoding
val encodedCookie = Cookie(
    name = "data",
    value = "special chars: &=;",
    encoding = CookieEncoding.URI_ENCODING
)

val base64Cookie = Cookie(
    name = "payload",
    value = "sensitive data",
    encoding = CookieEncoding.BASE64_ENCODING
)

// Render cookies for headers
val cookieHeader = renderCookieHeader(sessionCookie) // "session=abc123"
val setCookieHeader = renderSetCookieHeader(persistentCookie)
// "remember_me=true; Max-Age=86400; Expires=Wed, 21 Oct 2024 07:28:00 GMT; Domain=.example.com; Path=/; Secure; HttpOnly"

// Parse cookies from headers
val parsedCookie = parseServerSetCookieHeader("session=abc123; Path=/; HttpOnly")
val cookieMap = parseClientCookiesHeader("session=abc123; user=john_doe")
// Map: {"session" -> "abc123", "user" -> "john_doe"}

// Work with cookie encoding
val encoded = encodeCookieValue("hello world", CookieEncoding.URI_ENCODING) // "hello%20world"
val decoded = decodeCookieValue("hello%20world", CookieEncoding.URI_ENCODING) // "hello world"

val base64Encoded = encodeCookieValue("secret", CookieEncoding.BASE64_ENCODING) // "c2VjcmV0"
val base64Decoded = decodeCookieValue("c2VjcmV0", CookieEncoding.BASE64_ENCODING) // "secret"

// Cookie with custom extensions
val cookieWithExtensions = Cookie(
    name = "custom",
    value = "data",
    extensions = mapOf(
        "SameSite" to "Strict",
        "Priority" to "High"
    )
)

// Date handling
val cookieDate = "Wed, 21 Oct 2024 07:28:00 GMT"
val gmtDate = fromCookieToGmtDate(cookieDate)
val httpDate = toHttpDate(gmtDate)

// Practical cookie builder
fun createSecureCookie(name: String, value: String, domain: String): Cookie {
    return Cookie(
        name = name,
        value = value,
        domain = domain,
        path = "/",
        secure = true,
        httpOnly = true,
        maxAge = 86400, // 1 day
        encoding = CookieEncoding.URI_ENCODING
    )
}

// Session management example
fun createSessionCookie(sessionId: String): String {
    val cookie = Cookie(
        name = "JSESSIONID",
        value = sessionId,
        path = "/",
        httpOnly = true,
        secure = true,
        maxAge = 1800 // 30 minutes
    )
    return renderSetCookieHeader(cookie)
}

// Authentication cookie example  
fun createAuthCookie(token: String, rememberMe: Boolean): String {
    val maxAge = if (rememberMe) 86400 * 30 else null // 30 days or session
    val cookie = Cookie(
        name = "auth_token",
        value = token,
        path = "/",
        httpOnly = true,
        secure = true,
        maxAge = maxAge,
        encoding = CookieEncoding.BASE64_ENCODING
    )
    return renderSetCookieHeader(cookie)
}

// Cookie deletion (set expired date)
fun createDeleteCookie(name: String): String {
    val pastDate = GMTDate(0) // Unix epoch
    val cookie = Cookie(
        name = name,
        value = "",
        expires = pastDate,
        maxAge = 0,
        path = "/"
    )
    return renderSetCookieHeader(cookie)
}

// Comprehensive cookie parsing
fun parseCookieString(cookieHeader: String): List<Pair<String, String>> {
    val cookieMap = parseClientCookiesHeader(cookieHeader)
    return cookieMap.map { (name, value) -> name to value }
}