URL Handling

/**
 * Immutable URL representation
 */
class Url : Serializable {
    val protocol: URLProtocol
    val host: String
    val port: Int
    val specifiedPort: Int
    val user: String?
    val password: String?
    val encodedUser: String?
    val encodedPassword: String?
    val encodedPath: String
    val encodedPathAndQuery: String
    val encodedQuery: String?
    val encodedFragment: String?
    val fragment: String?
    val pathSegments: List<String>
    val parameters: Parameters
    val trailingQuery: Boolean
    
    /**
     * Convert to Java URI (JVM-specific)
     */
    fun toURI(): URI
    
    companion object {
        fun serializer(): KSerializer<Url>
    }
}

/**
 * Get protocol with authority (e.g., "https://example.com")
 */
val Url.protocolWithAuthority: String

/**
 * Get authority part (host:port)
 */
val Url.authority: String

/**
 * Get full path including query string
 */
val Url.fullPath: String

/**
 * Get host with port if specified
 */
val Url.hostWithPort: String

/**
 * Get host with port only if not default
 */
val Url.hostWithPortIfSpecified: String

/**
 * Check if URL has absolute path
 */
val Url.isAbsolutePath: Boolean

/**
 * Check if URL has relative path
 */
val Url.isRelativePath: Boolean

/**
 * Mutable URL builder
 */
class URLBuilder {
    var protocol: URLProtocol
    var protocolOrNull: URLProtocol?
    var host: String
    var port: Int
    var user: String?
    var password: String?
    var encodedUser: String?
    var encodedPassword: String?
    var pathSegments: MutableList<String>
    var encodedPathSegments: MutableList<String>
    var parameters: ParametersBuilder
    var encodedParameters: ParametersBuilder
    var fragment: String?
    var encodedFragment: String?
    var trailingQuery: Boolean
    
    /**
     * Build immutable URL
     */
    fun build(): Url
    
    /**
     * Build URL as string
     */
    fun buildString(): String
    
    /**
     * Create copy of this builder
     */
    fun clone(): URLBuilder
    
    /**
     * Take components from URI (JVM-specific)
     */
    fun takeFrom(uri: URI): URLBuilder
    
    /**
     * Take components from URL (JVM-specific)
     */
    fun takeFrom(url: URL): URLBuilder
    
    /**
     * Take components from another URLBuilder
     */
    fun takeFrom(builder: URLBuilder): URLBuilder
    
    /**
     * Take components from Url
     */
    fun takeFrom(url: Url): URLBuilder
    
    companion object
}

/**
 * Get encoded path string
 */
val URLBuilder.encodedPath: String

/**
 * Set encoded path from string
 */
fun URLBuilder.setEncodedPath(path: String)

/**
 * Get authority part
 */
val URLBuilder.authority: String

/**
 * Check if builder has absolute path
 */
val URLBuilder.isAbsolutePath: Boolean

/**
 * Check if builder has relative path
 */
val URLBuilder.isRelativePath: Boolean

/**
 * Append path segments (vararg)
 */
fun URLBuilder.path(vararg segments: String)

/**
 * Append path segments from list
 */
fun URLBuilder.pathComponents(segments: List<String>): URLBuilder

/**
 * Append encoded path segments
 */
fun URLBuilder.appendEncodedPathSegments(segments: List<String>): URLBuilder

/**
 * Append path segments with encoding control
 */
fun URLBuilder.appendPathSegments(segments: List<String>, encodeSlash: Boolean = true): URLBuilder

/**
 * URL protocol representation
 * @param name protocol name
 * @param defaultPort default port for protocol
 */
data class URLProtocol(val name: String, val defaultPort: Int) : Serializable {
    
    companion object {
        val HTTP: URLProtocol
        val HTTPS: URLProtocol
        val WS: URLProtocol
        val WSS: URLProtocol
        val SOCKS: URLProtocol
        
        /**
         * Create protocol or get existing one
         * @param name protocol name
         * @return URLProtocol instance
         */
        fun createOrDefault(name: String): URLProtocol
        
        /**
         * Map of protocol names to instances
         */
        val byName: Map<String, URLProtocol>
    }
}

/**
 * Check if protocol is secure (HTTPS, WSS)
 */
val URLProtocol.isSecure: Boolean

/**
 * Check if protocol is WebSocket (WS, WSS)
 */
val URLProtocol.isWebsocket: Boolean

/**
 * Create URL from string
 */
fun Url(urlString: String): Url

/**
 * Create URL from URI (JVM-specific)
 */
fun Url(uri: URI): Url

/**
 * Create URL from builder
 */
fun Url(builder: URLBuilder): Url

/**
 * Create URLBuilder from string
 */
fun URLBuilder(urlString: String): URLBuilder

/**
 * Create URLBuilder from URL
 */
fun URLBuilder(url: Url): URLBuilder

/**
 * Create URLBuilder from another builder (copy)
 */
fun URLBuilder(builder: URLBuilder): URLBuilder

/**
 * Build URL using DSL
 */
fun buildUrl(block: URLBuilder.() -> Unit): Url

/**
 * Parse URL from string
 */
fun parseUrl(urlString: String): Url

/**
 * Take URL components from string
 */
fun URLBuilder.takeFrom(urlString: String): URLBuilder

/**
 * Set multiple URL components at once
 */
fun URLBuilder.set(
    protocol: String? = null,
    host: String? = null,
    port: Int? = null,
    path: String? = null,
    block: (URLBuilder.() -> Unit)? = null
)

/**
 * Append URL path including query parameters
 */
fun Appendable.appendUrlFullPath(
    encodedPath: String,
    parameters: ParametersBuilder,
    trailingQuery: Boolean
)

/**
 * Get origin URL for current context (JVM-specific)
 */
val URLBuilder.Companion.origin: String

import io.ktor.http.*
import java.net.URI
import java.net.URL

// Create URLs from strings
val url1 = Url("https://api.example.com/users/123?include=profile")
val url2 = parseUrl("https://example.com")

// Build URLs step by step
val url3 = URLBuilder().apply {
    protocol = URLProtocol.HTTPS
    host = "api.example.com"
    pathSegments = mutableListOf("users", "123")
    parameters.append("include", "profile")
}.build()

// Build with DSL
val url4 = buildUrl {
    protocol = URLProtocol.HTTPS
    host = "example.com"
    path("api", "v1", "users")
    parameters {
        append("page", "1")
        append("limit", "10") 
    }
}

// JVM interoperability
val javaUri = URI("https://example.com/path")
val ktorUrl = Url(javaUri)
val backToJavaUri = ktorUrl.toURI()

val javaUrl = URL("https://example.com")
val builder = URLBuilder().takeFrom(javaUrl)

// URL components
println(url1.protocol) // HTTPS
println(url1.host) // api.example.com
println(url1.pathSegments) // [users, 123]
println(url1.parameters["include"]) // profile
println(url1.fullPath) // /users/123?include=profile

// Modify existing URL
val modified = URLBuilder(url1).apply {
    pathSegments.add("posts")
    parameters.append("sort", "date")
}.build()

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

/**
 * Thrown when URL parsing fails
 */
class URLParserException(message: String, cause: Throwable?) : IllegalStateException