0
# URL Handling
1

2
Comprehensive URL manipulation with JVM integration for `java.net.URI` and `java.net.URL` interoperability. Provides immutable URL representation and mutable builder pattern for URL construction.
3

4
## Capabilities
5

6
### Url
7

8
Immutable URL representation with full parsing and component access.
9

10
```kotlin { .api }
11
/**
12
 * Immutable URL representation
13
 */
14
class Url : Serializable {
15
    val protocol: URLProtocol
16
    val host: String
17
    val port: Int
18
    val specifiedPort: Int
19
    val user: String?
20
    val password: String?
21
    val encodedUser: String?
22
    val encodedPassword: String?
23
    val encodedPath: String
24
    val encodedPathAndQuery: String
25
    val encodedQuery: String?
26
    val encodedFragment: String?
27
    val fragment: String?
28
    val pathSegments: List<String>
29
    val parameters: Parameters
30
    val trailingQuery: Boolean
31
    
32
    /**
33
     * Convert to Java URI (JVM-specific)
34
     */
35
    fun toURI(): URI
36
    
37
    companion object {
38
        fun serializer(): KSerializer<Url>
39
    }
40
}
41

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

47
/**
48
 * Get authority part (host:port)
49
 */
50
val Url.authority: String
51

52
/**
53
 * Get full path including query string
54
 */
55
val Url.fullPath: String
56

57
/**
58
 * Get host with port if specified
59
 */
60
val Url.hostWithPort: String
61

62
/**
63
 * Get host with port only if not default
64
 */
65
val Url.hostWithPortIfSpecified: String
66

67
/**
68
 * Check if URL has absolute path
69
 */
70
val Url.isAbsolutePath: Boolean
71

72
/**
73
 * Check if URL has relative path
74
 */
75
val Url.isRelativePath: Boolean
76
```
77

78
### URLBuilder
79

80
Mutable URL builder for constructing URLs step by step.
81

82
```kotlin { .api }
83
/**
84
 * Mutable URL builder
85
 */
86
class URLBuilder {
87
    var protocol: URLProtocol
88
    var protocolOrNull: URLProtocol?
89
    var host: String
90
    var port: Int
91
    var user: String?
92
    var password: String?
93
    var encodedUser: String?
94
    var encodedPassword: String?
95
    var pathSegments: MutableList<String>
96
    var encodedPathSegments: MutableList<String>
97
    var parameters: ParametersBuilder
98
    var encodedParameters: ParametersBuilder
99
    var fragment: String?
100
    var encodedFragment: String?
101
    var trailingQuery: Boolean
102
    
103
    /**
104
     * Build immutable URL
105
     */
106
    fun build(): Url
107
    
108
    /**
109
     * Build URL as string
110
     */
111
    fun buildString(): String
112
    
113
    /**
114
     * Create copy of this builder
115
     */
116
    fun clone(): URLBuilder
117
    
118
    /**
119
     * Take components from URI (JVM-specific)
120
     */
121
    fun takeFrom(uri: URI): URLBuilder
122
    
123
    /**
124
     * Take components from URL (JVM-specific)
125
     */
126
    fun takeFrom(url: URL): URLBuilder
127
    
128
    /**
129
     * Take components from another URLBuilder
130
     */
131
    fun takeFrom(builder: URLBuilder): URLBuilder
132
    
133
    /**
134
     * Take components from Url
135
     */
136
    fun takeFrom(url: Url): URLBuilder
137
    
138
    companion object
139
}
140

141
/**
142
 * Get encoded path string
143
 */
144
val URLBuilder.encodedPath: String
145

146
/**
147
 * Set encoded path from string
148
 */
149
fun URLBuilder.setEncodedPath(path: String)
150

151
/**
152
 * Get authority part
153
 */
154
val URLBuilder.authority: String
155

156
/**
157
 * Check if builder has absolute path
158
 */
159
val URLBuilder.isAbsolutePath: Boolean
160

161
/**
162
 * Check if builder has relative path
163
 */
164
val URLBuilder.isRelativePath: Boolean
165

166
/**
167
 * Append path segments (vararg)
168
 */
169
fun URLBuilder.path(vararg segments: String)
170

171
/**
172
 * Append path segments from list
173
 */
174
fun URLBuilder.pathComponents(segments: List<String>): URLBuilder
175

176
/**
177
 * Append encoded path segments
178
 */
179
fun URLBuilder.appendEncodedPathSegments(segments: List<String>): URLBuilder
180

181
/**
182
 * Append path segments with encoding control
183
 */
184
fun URLBuilder.appendPathSegments(segments: List<String>, encodeSlash: Boolean = true): URLBuilder
185
```
186

187
### URLProtocol
188

189
URL protocols with default ports and security information.
190

191
```kotlin { .api }
192
/**
193
 * URL protocol representation
194
 * @param name protocol name
195
 * @param defaultPort default port for protocol
196
 */
197
data class URLProtocol(val name: String, val defaultPort: Int) : Serializable {
198
    
199
    companion object {
200
        val HTTP: URLProtocol
201
        val HTTPS: URLProtocol
202
        val WS: URLProtocol
203
        val WSS: URLProtocol
204
        val SOCKS: URLProtocol
205
        
206
        /**
207
         * Create protocol or get existing one
208
         * @param name protocol name
209
         * @return URLProtocol instance
210
         */
211
        fun createOrDefault(name: String): URLProtocol
212
        
213
        /**
214
         * Map of protocol names to instances
215
         */
216
        val byName: Map<String, URLProtocol>
217
    }
218
}
219

220
/**
221
 * Check if protocol is secure (HTTPS, WSS)
222
 */
223
val URLProtocol.isSecure: Boolean
224

225
/**
226
 * Check if protocol is WebSocket (WS, WSS)
227
 */
228
val URLProtocol.isWebsocket: Boolean
229
```
230

231
### URL Construction Functions
232

233
Convenience functions for creating URLs and builders.
234

235
```kotlin { .api }
236
/**
237
 * Create URL from string
238
 */
239
fun Url(urlString: String): Url
240

241
/**
242
 * Create URL from URI (JVM-specific)
243
 */
244
fun Url(uri: URI): Url
245

246
/**
247
 * Create URL from builder
248
 */
249
fun Url(builder: URLBuilder): Url
250

251
/**
252
 * Create URLBuilder from string
253
 */
254
fun URLBuilder(urlString: String): URLBuilder
255

256
/**
257
 * Create URLBuilder from URL
258
 */
259
fun URLBuilder(url: Url): URLBuilder
260

261
/**
262
 * Create URLBuilder from another builder (copy)
263
 */
264
fun URLBuilder(builder: URLBuilder): URLBuilder
265

266
/**
267
 * Build URL using DSL
268
 */
269
fun buildUrl(block: URLBuilder.() -> Unit): Url
270

271
/**
272
 * Parse URL from string
273
 */
274
fun parseUrl(urlString: String): Url
275

276
/**
277
 * Take URL components from string
278
 */
279
fun URLBuilder.takeFrom(urlString: String): URLBuilder
280

281
/**
282
 * Set multiple URL components at once
283
 */
284
fun URLBuilder.set(
285
    protocol: String? = null,
286
    host: String? = null,
287
    port: Int? = null,
288
    path: String? = null,
289
    block: (URLBuilder.() -> Unit)? = null
290
)
291

292
/**
293
 * Append URL path including query parameters
294
 */
295
fun Appendable.appendUrlFullPath(
296
    encodedPath: String,
297
    parameters: ParametersBuilder,
298
    trailingQuery: Boolean
299
)
300
```
301

302
### JVM-specific URL Extensions
303

304
JVM-specific extensions for Java interoperability.
305

306
```kotlin { .api }
307
/**
308
 * Get origin URL for current context (JVM-specific)
309
 */
310
val URLBuilder.Companion.origin: String
311
```
312

313
**Usage Examples:**
314

315
```kotlin
316
import io.ktor.http.*
317
import java.net.URI
318
import java.net.URL
319

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

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

332
// Build with DSL
333
val url4 = buildUrl {
334
    protocol = URLProtocol.HTTPS
335
    host = "example.com"
336
    path("api", "v1", "users")
337
    parameters {
338
        append("page", "1")
339
        append("limit", "10") 
340
    }
341
}
342

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

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

351
// URL components
352
println(url1.protocol) // HTTPS
353
println(url1.host) // api.example.com
354
println(url1.pathSegments) // [users, 123]
355
println(url1.parameters["include"]) // profile
356
println(url1.fullPath) // /users/123?include=profile
357

358
// Modify existing URL
359
val modified = URLBuilder(url1).apply {
360
    pathSegments.add("posts")
361
    parameters.append("sort", "date")
362
}.build()
363
```
364

365
## Types
366

367
All types are defined above in their respective capability sections.
368

369
## Exceptions
370

371
```kotlin { .api }
372
/**
373
 * Thrown when URL decoding fails
374
 */
375
class URLDecodeException(message: String) : Exception
376

377
/**
378
 * Thrown when URL parsing fails
379
 */
380
class URLParserException(message: String, cause: Throwable?) : IllegalStateException
381
```