URL Building and Parsing

/**
 * Immutable URL representation
 */
class Url {
    val protocol: URLProtocol
    val host: String
    val port: Int
    val specifiedPort: Int
    val encodedPath: String
    val encodedPathAndQuery: String
    val encodedQuery: String
    val parameters: Parameters
    val fragment: String?
    val encodedFragment: String?
    val user: String?
    val encodedUser: String?
    val password: String?
    val encodedPassword: String?
    val pathSegments: List<String>
    val rawSegments: List<String>
    val segments: List<String>
    val trailingQuery: Boolean
    
    companion object {
        /**
         * Create URL from string
         * @param urlString URL string to parse
         * @return Url instance
         */
        operator fun invoke(urlString: String): Url
        
        fun serializer(): KSerializer<Url>
    }
}

/**
 * Parse URL from string
 * @param urlString URL string to parse  
 * @return Url instance
 */
fun parseUrl(urlString: String): Url

/**
 * Mutable URL builder
 */
class URLBuilder(
    protocol: URLProtocol = URLProtocol.HTTP,
    host: String = "localhost", 
    port: Int = DEFAULT_PORT,
    user: String? = null,
    password: String? = null,
    pathSegments: List<String> = emptyList(),
    parameters: Parameters = Parameters.Empty,
    fragment: String? = null,
    trailingQuery: Boolean = false
) {
    var protocol: URLProtocol
    var host: String
    var port: Int
    var user: String?
    var encodedUser: String?
    var password: String?
    var encodedPassword: String?
    val pathSegments: MutableList<String>
    val encodedPathSegments: MutableList<String>
    val parameters: ParametersBuilder
    val encodedParameters: ParametersBuilder
    var fragment: String?
    var encodedFragment: String?
    var trailingQuery: Boolean
    
    val protocolOrNull: URLProtocol?
    val authority: String
    val encodedPath: String
    
    /**
     * Build immutable URL
     * @return Url instance
     */
    fun build(): Url
    
    /**
     * Build URL as string
     * @return URL string representation
     */
    fun buildString(): String
    
    /**
     * Initialize from URL string
     * @param url URL string to parse
     * @return This URLBuilder for chaining
     */
    fun takeFrom(url: String): URLBuilder
    
    /**
     * Initialize from another URLBuilder
     * @param builder URLBuilder to copy from
     * @return This URLBuilder for chaining
     */
    fun takeFrom(builder: URLBuilder): URLBuilder
    
    /**
     * Initialize from Url instance
     * @param url Url to copy from
     * @return This URLBuilder for chaining
     */
    fun takeFrom(url: Url): URLBuilder
    
    /**
     * Clone this builder
     * @return New URLBuilder with same configuration
     */
    fun clone(): URLBuilder
}

const val DEFAULT_PORT: Int

/**
 * Create URLBuilder from string
 * @param urlString URL string to parse
 * @return URLBuilder instance
 */
fun URLBuilder(urlString: String): URLBuilder

/**
 * Create URLBuilder from Url
 * @param url Url to copy from
 * @return URLBuilder instance
 */
fun URLBuilder(url: Url): URLBuilder

/**
 * Create URLBuilder from another URLBuilder
 * @param builder URLBuilder to copy from
 * @return URLBuilder instance
 */
fun URLBuilder(builder: URLBuilder): URLBuilder

/**
 * Create Url from URLBuilder
 * @param builder URLBuilder to build from
 * @return Url instance
 */
fun Url(builder: URLBuilder): Url

/**
 * Build URL using builder function
 * @param block Function to configure URLBuilder
 * @return Url instance
 */
fun buildUrl(block: URLBuilder.() -> Unit): Url

/**
 * Append path segments to URL builder
 * @param segments Path segments to append
 * @param encodeSlash Whether to encode slash characters
 * @return URLBuilder for chaining
 */
fun URLBuilder.appendPathSegments(segments: List<String>, encodeSlash: Boolean = true): URLBuilder
fun URLBuilder.appendPathSegments(vararg segments: String, encodeSlash: Boolean = true): URLBuilder

/**
 * Append encoded path segments to URL builder
 * @param segments Pre-encoded path segments
 * @return URLBuilder for chaining
 */
fun URLBuilder.appendEncodedPathSegments(segments: List<String>): URLBuilder
fun URLBuilder.appendEncodedPathSegments(vararg segments: String): URLBuilder

/**
 * Set path segments replacing existing ones
 * @param segments Path segments to set
 * @return URLBuilder for chaining
 */
fun URLBuilder.pathComponents(segments: List<String>): URLBuilder
fun URLBuilder.pathComponents(vararg segments: String): URLBuilder

/**
 * Set path segments from string array
 * @param segments Path segments
 */
fun URLBuilder.path(vararg segments: String)

/**
 * Set encoded path directly
 * @param encodedPath Encoded path string
 */
fun URLBuilder.setEncodedPath(encodedPath: String)

/**
 * Get full path including query string
 * @return Full path with query
 */
fun Url.getFullPath(): String

/**
 * Get host with port if non-default
 * @return Host with port
 */
fun Url.getHostWithPort(): String

/**
 * Get host with port if explicitly specified
 * @return Host with port if specified
 */
fun Url.getHostWithPortIfSpecified(): String

/**
 * Check if URL has absolute path
 * @return true if path is absolute
 */
fun Url.isAbsolutePath(): Boolean
fun URLBuilder.isAbsolutePath(): Boolean

/**
 * Check if URL has relative path
 * @return true if path is relative
 */
fun Url.isRelativePath(): Boolean
fun URLBuilder.isRelativePath(): Boolean

/**
 * Get authority part (user:password@host:port)
 * @return Authority string
 */
fun Url.getAuthority(): String

/**
 * Get protocol with authority (https://example.com)
 * @return Protocol with authority
 */
fun Url.getProtocolWithAuthority(): String

/**
 * Append URL path with parameters to Appendable
 * @param path Path to append
 * @param parameters Parameters to append  
 * @param includeQuery Whether to include query separator
 */
fun appendUrlFullPath(
    out: Appendable,
    path: String,
    parameters: ParametersBuilder,
    includeQuery: Boolean
)

/**
 * URL protocol/scheme
 * @param name Protocol name (e.g., "https")
 * @param defaultPort Default port for protocol
 */
data class URLProtocol(val name: String, val defaultPort: Int) {
    companion object {
        val HTTP: URLProtocol
        val HTTPS: URLProtocol
        val WS: URLProtocol
        val WSS: URLProtocol
        val SOCKS: URLProtocol
        
        val byName: Map<String, URLProtocol>
        
        /**
         * Get existing protocol or create new one
         * @param name Protocol name
         * @return URLProtocol instance
         */
        fun createOrDefault(name: String): URLProtocol
    }
}

/**
 * Check if protocol is secure (HTTPS, WSS)
 * @return true if secure protocol
 */
fun URLProtocol.isSecure(): Boolean

/**
 * Check if protocol is WebSocket (WS, WSS)
 * @return true if WebSocket protocol
 */
fun URLProtocol.isWebsocket(): Boolean

/**
 * Encode URL path component
 * @param path Path to encode
 * @param encodeSlash Whether to encode slash characters
 * @param encodePercent Whether to encode percent characters
 * @return Encoded path
 */
fun encodeURLPath(path: String, encodeSlash: Boolean = false, encodePercent: Boolean = true): String

/**
 * Encode URL path part
 * @param part Path part to encode
 * @return Encoded path part
 */
fun encodeURLPathPart(part: String): String

/**
 * Encode URL parameter
 * @param value Parameter value to encode
 * @param spaceToPlus Whether to encode spaces as plus signs
 * @return Encoded parameter value
 */
fun encodeURLParameter(value: String, spaceToPlus: Boolean = false): String

/**
 * Encode URL query component
 * @param component Query component to encode
 * @param spaceToPlus Whether to encode spaces as plus signs
 * @param encodeFull Whether to encode all special characters
 * @param charset Character encoding to use
 * @return Encoded query component
 */
fun encodeURLQueryComponent(
    component: String,
    spaceToPlus: Boolean = true,
    encodeFull: Boolean = false,
    charset: Charset = Charsets.UTF_8
): String

/**
 * Decode URL part
 * @param encoded Encoded URL part
 * @param start Start index
 * @param end End index
 * @param charset Character encoding to use
 * @return Decoded string
 */
fun decodeURLPart(
    encoded: String,
    start: Int = 0,
    end: Int = encoded.length,
    charset: Charset = Charsets.UTF_8
): String

/**
 * Decode URL query component
 * @param encoded Encoded query component
 * @param start Start index
 * @param end End index
 * @param plusToSpace Whether to decode plus signs as spaces
 * @param charset Character encoding to use
 * @return Decoded string
 */
fun decodeURLQueryComponent(
    encoded: String,
    start: Int = 0,
    end: Int = encoded.length,
    plusToSpace: Boolean = true,
    charset: Charset = Charsets.UTF_8
): String

/**
 * OAuth-specific URL encoding
 * @param value Value to encode
 * @return OAuth-encoded value
 */
fun encodeOAuth(value: String): String

/**
 * Exception thrown when URL decoding fails
 */
class URLDecodeException(message: String) : Exception(message)

/**
 * Exception thrown when URL parsing fails
 */
class URLParserException(message: String, cause: Throwable? = null) : IllegalStateException(message, cause)

import io.ktor.http.*

// Create URLs
val url1 = Url("https://api.example.com/users?page=1")
val url2 = parseUrl("https://example.com/path")

// Build URLs
val builtUrl = buildUrl {
    protocol = URLProtocol.HTTPS
    host = "api.example.com"
    port = 8080
    path("v1", "users", "123")
    parameters.append("format", "json")
    parameters.append("include", "profile")
    fragment = "section1"
}

// Use URLBuilder
val builder = URLBuilder("https://example.com")
builder.appendPathSegments("api", "v1", "users")
builder.parameters.append("q", "search term")
val finalUrl = builder.build()

// Access URL components
val protocol = url1.protocol // URLProtocol.HTTPS
val host = url1.host // "api.example.com"
val path = url1.encodedPath // "/users"
val params = url1.parameters // Parameters with "page" -> "1"
val query = url1.encodedQuery // "page=1"

// URL utilities
val fullPath = url1.getFullPath() // "/users?page=1"
val hostWithPort = url1.getHostWithPort() // "api.example.com" or "api.example.com:8080"
val isAbsolute = url1.isAbsolutePath() // true

// Encoding/decoding
val encoded = encodeURLPath("/api/v1/users")
val encodedParam = encodeURLParameter("hello world")
val decoded = decodeURLQueryComponent("hello%20world")

// Protocol utilities
val isSecure = URLProtocol.HTTPS.isSecure() // true
val isWebSocket = URLProtocol.WS.isWebsocket() // true

// Clone and modify
val newBuilder = URLBuilder(url1)
newBuilder.host = "different.example.com"
val modifiedUrl = newBuilder.build()