Headers and Parameters

/**
 * HTTP headers container
 */
interface Headers : StringValues {
    
    companion object {
        /**
         * Build headers using DSL
         * @param builder header building function
         * @return Headers instance
         */
        fun build(builder: HeadersBuilder.() -> Unit): Headers
        
        /**
         * Empty headers instance
         */
        val Empty: Headers
    }
}

/**
 * Create headers using DSL
 */
fun headers(builder: HeadersBuilder.() -> Unit): Headers

/**
 * Create empty headers
 */
fun headersOf(): Headers

/**
 * Create headers with single header
 */
fun headersOf(name: String, value: String): Headers

/**
 * Create headers with single header and multiple values
 */
fun headersOf(name: String, values: List<String>): Headers

/**
 * Create headers from pairs
 */
fun headersOf(vararg pairs: Pair<String, String>): Headers

/**
 * Mutable headers builder
 */
class HeadersBuilder : StringValuesBuilderImpl {
    
    /**
     * Build immutable headers
     * @return Headers instance
     */
    fun build(): Headers
}

/**
 * HTTP header name constants and utilities
 */
object HttpHeaders {
    // Request headers
    val Accept: String
    val AcceptCharset: String
    val AcceptEncoding: String
    val AcceptLanguage: String
    val Authorization: String
    val CacheControl: String
    val Connection: String
    val ContentEncoding: String
    val ContentLanguage: String
    val ContentLength: String
    val ContentLocation: String
    val ContentType: String
    val Cookie: String
    val Date: String
    val ETag: String
    val Expect: String
    val Expires: String
    val From: String
    val Host: String
    val IfMatch: String
    val IfModifiedSince: String
    val IfNoneMatch: String
    val IfRange: String
    val IfUnmodifiedSince: String
    val LastModified: String
    val Location: String
    val MaxForwards: String
    val Origin: String
    val Pragma: String
    val ProxyAuthorization: String
    val Range: String
    val Referrer: String
    val RetryAfter: String
    val Server: String
    val TE: String
    val Upgrade: String
    val UserAgent: String
    val Vary: String
    val Via: String
    val Warning: String
    
    // Response headers
    val AcceptRanges: String
    val Age: String
    val Allow: String
    val ContentDisposition: String
    val ContentRange: String
    val ProxyAuthenticate: String
    val SetCookie: String
    val Trailer: String
    val TransferEncoding: String
    val WWWAuthenticate: String
    
    // CORS headers
    val AccessControlAllowCredentials: String
    val AccessControlAllowHeaders: String
    val AccessControlAllowMethods: String
    val AccessControlAllowOrigin: String
    val AccessControlExposeHeaders: String
    val AccessControlMaxAge: String
    val AccessControlRequestHeaders: String
    val AccessControlRequestMethod: String
    
    // WebDAV headers
    val DASL: String
    val DAV: String
    val Depth: String
    val Destination: String
    val If: String
    val LockToken: String
    val Overwrite: String
    val Timeout: String
    
    // Extended headers
    val ALPN: String
    val AuthenticationInfo: String
    val ContentDisposition: String
    val Forwarded: String
    val HTTP2Settings: String
    val Link: String
    val MIMEVersion: String
    val OrderingType: String
    val Position: String
    val Prefer: String
    val PreferenceApplied: String
    val ProxyAuthenticationInfo: String
    val PublicKeyPins: String
    val PublicKeyPinsReportOnly: String
    val ScheduleReply: String
    val ScheduleTag: String
    val SLUG: String
    val StrictTransportSecurity: String
    
    // WebSocket headers
    val SecWebSocketAccept: String
    val SecWebSocketExtensions: String
    val SecWebSocketKey: String
    val SecWebSocketProtocol: String
    val SecWebSocketVersion: String
    
    // Non-standard headers
    val XCorrelationId: String
    val XForwardedFor: String
    val XForwardedHost: String
    val XForwardedPort: String
    val XForwardedProto: String
    val XForwardedServer: String
    val XHttpMethodOverride: String
    val XRequestId: String
    val XTotalCount: String
    
    /**
     * Validate header name
     * @param name header name to check
     * @throws IllegalHeaderNameException if invalid
     */
    fun checkHeaderName(name: String)
    
    /**
     * Validate header value
     * @param value header value to check
     * @throws IllegalHeaderValueException if invalid
     */
    fun checkHeaderValue(value: String)
    
    /**
     * Check if header is considered unsafe
     * @param name header name
     * @return true if unsafe
     */
    fun isUnsafe(name: String): Boolean
    
    /**
     * Array of unsafe header names
     */
    val unsafeHeaders: Array<String>
    
    /**
     * List of unsafe header names
     */
    val unsafeHeadersList: List<String>
}

/**
 * URL parameters container
 */
interface Parameters : StringValues {
    
    companion object {
        /**
         * Build parameters using DSL
         * @param builder parameter building function
         * @return Parameters instance
         */
        fun build(builder: ParametersBuilder.() -> Unit): Parameters
        
        /**
         * Empty parameters instance
         */
        val Empty: Parameters
    }
}

/**
 * Parameters builder interface
 */
interface ParametersBuilder : StringValuesBuilder {
    /**
     * Build immutable parameters
     * @return Parameters instance
     */
    fun build(): Parameters
}

/**
 * Create parameters using DSL
 */
fun parameters(builder: ParametersBuilder.() -> Unit): Parameters

/**
 * Create empty parameters
 */
fun parametersOf(): Parameters

/**
 * Create parameters with single parameter
 */
fun parametersOf(name: String, value: String): Parameters

/**
 * Create parameters with single parameter and multiple values
 */
fun parametersOf(name: String, values: List<String>): Parameters

/**
 * Create parameters from map
 */
fun parametersOf(map: Map<String, List<String>>): Parameters

/**
 * Create parameters from pairs
 */
fun parametersOf(vararg pairs: Pair<String, String>): Parameters

/**
 * Create parameters builder
 */
fun ParametersBuilder(initialCapacity: Int = 8): ParametersBuilder

/**
 * Combine two parameters instances
 */
operator fun Parameters.plus(other: Parameters): Parameters

/**
 * Parse header value into structured components
 * @param text header value text
 * @return List of HeaderValue instances
 */
fun parseHeaderValue(text: String): List<HeaderValue>

/**
 * Parse header value with parameter control
 * @param text header value text
 * @param parametersOnly parse only parameters
 * @return List of HeaderValue instances
 */
fun parseHeaderValue(text: String, parametersOnly: Boolean): List<HeaderValue>

/**
 * Parse and sort header values by quality
 * @param text header value text
 * @return List of HeaderValue instances sorted by quality
 */
fun parseAndSortHeader(text: String): List<HeaderValue>

/**
 * Parse and sort Content-Type header values
 * @param text Content-Type header text
 * @return List of HeaderValue instances
 */
fun parseAndSortContentTypeHeader(text: String): List<HeaderValue>

/**
 * Convert parameters to header parameter list
 * @param parameters parameters to convert
 * @return List of HeaderValueParam
 */
fun Iterable<Pair<String, String>>.toHeaderParamsList(): List<HeaderValueParam>

/**
 * Parsed header value with quality and parameters
 */
data class HeaderValue(
    val value: String,
    val params: List<HeaderValueParam> = emptyList()
) {
    /**
     * Quality value from q parameter
     */
    val quality: Double
}

/**
 * Header parameter with name and value
 */
data class HeaderValueParam(
    val name: String,
    val value: String,
    val escapeValue: Boolean = false
)

/**
 * Base class for header values with parameters
 */
abstract class HeaderValueWithParameters(
    protected val content: String,
    val parameters: List<HeaderValueParam> = emptyList()
) {
    /**
     * Get parameter value by name
     * @param name parameter name
     * @return parameter value or null
     */
    fun parameter(name: String): String?
    
    companion object {
        /**
         * Parse header value with custom factory
         */
        fun <T> parse(value: String, factory: (String, List<HeaderValueParam>) -> T): T
    }
}

/**
 * Append header value with parameters to builder
 */
fun StringValuesBuilder.append(name: String, value: HeaderValueWithParameters)

/**
 * Escape string if needed for header value
 */
fun escapeIfNeeded(value: String): String

/**
 * Quote string for header value
 */
fun quote(value: String): String

import io.ktor.http.*

// Create headers
val headers = headers {
    append(HttpHeaders.ContentType, "application/json")
    append(HttpHeaders.Authorization, "Bearer token123")
    append(HttpHeaders.Accept, "application/json, text/plain")
}

// Access header values
val contentType = headers[HttpHeaders.ContentType]
val acceptValues = headers.getAll(HttpHeaders.Accept)

// Check for headers
if (headers.contains(HttpHeaders.Authorization)) {
    // Handle authenticated request
}

// Build headers step by step
val builder = HeadersBuilder()
builder.append(HttpHeaders.UserAgent, "MyApp/1.0")
builder.append(HttpHeaders.AcceptEncoding, "gzip, deflate")
val builtHeaders = builder.build()

// Create from predefined values
val simpleHeaders = headersOf(
    HttpHeaders.ContentType to "text/html",
    HttpHeaders.CacheControl to "no-cache"
)

// Work with parameters
val params = parameters {
    append("page", "1")
    append("limit", "10")
    append("sort", listOf("name", "date"))
}

// Access parameter values
val page = params["page"] // "1"
val sortValues = params.getAll("sort") // ["name", "date"]

// Create from map
val paramMap = mapOf(
    "filter" to listOf("active", "verified"),
    "include" to listOf("profile")
)
val paramsFromMap = parametersOf(paramMap)

// Combine parameters
val combined = params + parametersOf("extra", "value")

// Parse complex header values
val acceptHeader = "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
val parsed = parseAndSortHeader(acceptHeader)
// Sorted by quality value (q parameter)

// Header validation
try {
    HttpHeaders.checkHeaderName("Valid-Header")
    HttpHeaders.checkHeaderValue("valid value")
} catch (e: IllegalHeaderNameException) {
    // Handle invalid header name
} catch (e: IllegalHeaderValueException) {
    // Handle invalid header value
}

// Check unsafe headers
if (HttpHeaders.isUnsafe("Cookie")) {
    // Handle unsafe header
}

/**
 * Exception thrown for illegal header names
 */
class IllegalHeaderNameException(
    val headerName: String, 
    val position: Int
) : IllegalArgumentException

/**
 * Exception thrown for illegal header values
 */
class IllegalHeaderValueException(
    val headerValue: String, 
    val position: Int
) : IllegalArgumentException

/**
 * Exception thrown for unsafe header usage
 */
class UnsafeHeaderException(headerName: String) : IllegalArgumentException