Immutable URL representation and mutable builders for URL construction with protocol handling, parameter management, and comprehensive URL manipulation utilities.
Immutable URL representation with comprehensive property access and encoding support.
/**
* Immutable URL representation
*/
class Url {
/** URL protocol (HTTP, HTTPS, WS, WSS, etc.) */
val protocol: URLProtocol
/** Host name without port */
val host: String
/** Port number (specified or protocol default) */
val port: Int
/** Explicitly specified port (-1 if not specified) */
val specifiedPort: Int
/** List of path segments */
val pathSegments: List<String>
/** Query parameters */
val parameters: Parameters
/** URL fragment (part after #) */
val fragment: String
/** Username for authentication */
val user: String?
/** Password for authentication */
val password: String?
/** Whether to keep trailing query mark */
val trailingQuery: Boolean
/** Encoded path string */
val encodedPath: String
/** Encoded query string */
val encodedQuery: String
/** Encoded path and query combined */
val encodedPathAndQuery: String
/** Encoded username */
val encodedUser: String?
/** Encoded password */
val encodedPassword: String?
/** Encoded fragment */
val encodedFragment: String
/** URL authority (user:pass@host:port) */
val authority: String
/** Protocol and authority combined */
val protocolWithAuthority: String
}Mutable URL builder for constructing URLs with fluent API and parameter manipulation.
/**
* Mutable URL builder for URL construction
*/
class URLBuilder {
/** URL protocol */
var protocol: URLProtocol
/** Host name */
var host: String
/** Port number */
var port: Int
/** Username for authentication */
var user: String?
/** Password for authentication */
var password: String?
/** List of path segments */
var pathSegments: List<String>
/** Query parameters builder */
val parameters: ParametersBuilder
/** URL fragment */
var fragment: String
/** Whether to keep trailing query mark */
var trailingQuery: Boolean
/** Encoded username */
var encodedUser: String?
/** Encoded password */
var encodedPassword: String?
/** Encoded fragment */
var encodedFragment: String
/** List of encoded path segments */
var encodedPathSegments: List<String>
/** Encoded parameters builder */
val encodedParameters: ParametersBuilder
/** Encoded path string */
var encodedPath: String
/** URL authority */
val authority: String
/**
* Build URL as string
* @return complete URL string
*/
fun buildString(): String
/**
* Build immutable URL
* @return Url instance
*/
fun build(): Url
/**
* Create copy of this builder
* @return new URLBuilder with same values
*/
fun clone(): URLBuilder
/**
* Append path segments to URL
* @param segments list of path segments to append
* @param encodeSlash whether to encode slash characters
* @return this builder for chaining
*/
fun appendPathSegments(
segments: List<String>,
encodeSlash: Boolean = false
): URLBuilder
/**
* Append path segments to URL
* @param components vararg path segments to append
* @param encodeSlash whether to encode slash characters
* @return this builder for chaining
*/
fun appendPathSegments(
vararg components: String,
encodeSlash: Boolean = false
): URLBuilder
/**
* Set path components (replaces existing path)
* @param path vararg path components
*/
fun path(vararg path: String)
/**
* Append encoded path segments
* @param segments list of pre-encoded path segments
* @return this builder for chaining
*/
fun appendEncodedPathSegments(segments: List<String>): URLBuilder
/**
* Append encoded path segments
* @param components vararg pre-encoded path segments
* @return this builder for chaining
*/
fun appendEncodedPathSegments(vararg components: String): URLBuilder
/**
* Set multiple URL components at once
* @param scheme protocol scheme
* @param host host name
* @param port port number
* @param path path string
* @param block additional configuration block
*/
fun set(
scheme: String? = null,
host: String? = null,
port: Int? = null,
path: String? = null,
block: URLBuilder.() -> Unit = {}
)
companion object {
/** Default port placeholder */
const val DEFAULT_PORT: Int = 0
/** Current origin hostname (platform-specific) */
val origin: String
}
}Protocol definitions with default ports and utility functions.
/**
* URL protocol representation
* @param name protocol name/scheme
* @param defaultPort default port for protocol (-1 if unknown)
*/
data class URLProtocol(val name: String, val defaultPort: Int) {
companion object {
/** HTTP protocol (port 80) */
val HTTP: URLProtocol
/** HTTPS protocol (port 443) */
val HTTPS: URLProtocol
/** WebSocket over HTTP (port 80) */
val WS: URLProtocol
/** WebSocket over HTTPS (port 443) */
val WSS: URLProtocol
/** SOCKS proxy protocol (port 1080) */
val SOCKS: URLProtocol
/** Map of protocol names to instances */
val byName: Map<String, URLProtocol>
/**
* Create protocol or get existing one
* @param name protocol name
* @return URLProtocol instance
*/
fun createOrDefault(name: String): URLProtocol
}
}
/**
* Check if protocol is WebSocket (WS or WSS)
* @return true if WebSocket protocol
*/
fun URLProtocol.isWebsocket(): Boolean
/**
* Check if protocol is secure (HTTPS, WSS, etc.)
* @return true if secure protocol
*/
fun URLProtocol.isSecure(): BooleanUsage Examples:
import io.ktor.http.*
// Create URL from string
val url = URLBuilder("https://api.example.com/v1/users")
.appendPathSegments("123")
.apply {
parameters.append("format", "json")
parameters.append("include", "profile")
}
.build()
// Access URL properties
println(url.protocol) // HTTPS
println(url.host) // api.example.com
println(url.port) // 443 (default for HTTPS)
println(url.pathSegments) // [v1, users, 123]
println(url.parameters["format"]) // json
// Build URL step by step
val builder = URLBuilder().apply {
protocol = URLProtocol.HTTPS
host = "example.com"
port = 8443
pathSegments = listOf("api", "v2", "data")
parameters.append("query", "test")
fragment = "section1"
}
val complexUrl = builder.build()
println(complexUrl.buildString())
// https://example.com:8443/api/v2/data?query=test#section1
// Clone and modify builder
val modifiedBuilder = builder.clone().apply {
pathSegments = pathSegments + listOf("more", "path")
parameters.append("additional", "param")
}
// Work with protocols
val httpProtocol = URLProtocol.HTTP
val customProtocol = URLProtocol.createOrDefault("ftp")
println(URLProtocol.HTTPS.isSecure()) // true
println(URLProtocol.WS.isWebsocket()) // true
// Handle authentication in URLs
val authUrl = URLBuilder("https://example.com").apply {
user = "username"
password = "password"
pathSegments = listOf("secure", "area")
}.build()
// Work with encoded components
val encodedBuilder = URLBuilder().apply {
protocol = URLProtocol.HTTPS
host = "example.com"
encodedPathSegments = listOf("path%20with%20spaces", "special%2Fchars")
encodedFragment = "encoded%20fragment"
}
// Parameter manipulation
val urlWithParams = URLBuilder("https://api.example.com").apply {
parameters.append("q", "search term")
parameters.append("limit", "10")
parameters.append("offset", "20")
parameters.appendAll("tags", listOf("kotlin", "http", "api"))
}.build()
// Access parameter values
val searchQuery = urlWithParams.parameters["q"]
val tags = urlWithParams.parameters.getAll("tags")// URLProtocol and related types are defined above in the capabilities section
// No additional types needed - URL and URLBuilder are self-contained