0
# Socket Addresses
1

2
Socket address types and utilities for different addressing schemes including Internet addresses and Unix domain sockets.
3

4
## Capabilities
5

6
### Socket Address Base Class
7

8
Base sealed class for all socket address types providing common functionality.
9

10
```kotlin { .api }
11
/**
12
 * Represents a socket address abstraction.
13
 * This sealed class serves as the base type for different kinds of socket addresses,
14
 * such as Internet-specific or other platform-dependent address types.
15
 */
16
sealed class SocketAddress
17

18
/**
19
 * Retrieves the port number associated with this socket address.
20
 * If the SocketAddress instance is of type InetSocketAddress, the associated port is returned.
21
 * Otherwise, an UnsupportedOperationException is thrown.
22
 * @returns the port number of the socket address if available
23
 * @throws UnsupportedOperationException if the socket address type does not support a port
24
 */
25
fun SocketAddress.port(): Int
26
```
27

28
**Usage Example:**
29

30
```kotlin
31
import io.ktor.network.sockets.*
32

33
val inetAddress = InetSocketAddress("localhost", 8080)
34
val unixAddress = UnixSocketAddress("/tmp/socket")
35

36
// Get port from inet address
37
val port = inetAddress.port() // Returns 8080
38

39
// This would throw UnsupportedOperationException
40
try {
41
    val unixPort = unixAddress.port()
42
} catch (e: UnsupportedOperationException) {
43
    println("Unix sockets don't have ports")
44
}
45
```
46

47
### Internet Socket Address
48

49
Socket address for Internet Protocol (IP) based connections supporting both IPv4 and IPv6.
50

51
```kotlin { .api }
52
/**
53
 * Internet socket address for IP-based connections
54
 * @param hostname The hostname or IP address
55
 * @param port The port number
56
 */
57
class InetSocketAddress(
58
    hostname: String,
59
    port: Int
60
) : SocketAddress {
61
    /**
62
     * The hostname of the socket address.
63
     * Note that this may trigger a name service reverse lookup.
64
     */
65
    val hostname: String
66

67
    /**
68
     * The port number of the socket address.
69
     */
70
    val port: Int
71

72
    /**
73
     * Returns the raw IP address bytes of this socket address.
74
     * The returned array is 4-bytes for IPv4 addresses and 16-bytes for IPv6 addresses.
75
     * Returns null if the address cannot be resolved or is not a valid IP address.
76
     * Always returns null for Kotlin/JS and Kotlin/Wasm targets.
77
     */
78
    fun resolveAddress(): ByteArray?
79

80
    /**
81
     * The hostname of the socket address.
82
     * Note that this may trigger a name service reverse lookup.
83
     */
84
    operator fun component1(): String
85

86
    /**
87
     * The port number of the socket address.
88
     */
89
    operator fun component2(): Int
90

91
    /**
92
     * Create a copy of InetSocketAddress.
93
     * Note that this may trigger a name service reverse lookup.
94
     */
95
    fun copy(hostname: String = this.hostname, port: Int = this.port): InetSocketAddress
96
}
97
```
98

99
**Usage Examples:**
100

101
```kotlin
102
import io.ktor.network.sockets.*
103

104
// Create inet socket addresses
105
val localhostAddress = InetSocketAddress("localhost", 8080)
106
val ipAddress = InetSocketAddress("192.168.1.1", 80)
107
val ipv6Address = InetSocketAddress("::1", 8080)
108

109
// Access properties
110
println("Hostname: ${localhostAddress.hostname}")
111
println("Port: ${localhostAddress.port}")
112

113
// Destructuring declaration
114
val (hostname, port) = localhostAddress
115
println("Connecting to $hostname:$port")
116

117
// Copy with modifications
118
val sslAddress = localhostAddress.copy(port = 8443)
119
println("SSL address: $sslAddress")
120

121
// Resolve IP address
122
val ipBytes = localhostAddress.resolveAddress()
123
if (ipBytes != null) {
124
    println("IP bytes: ${ipBytes.joinToString(".")}")
125
} else {
126
    println("Could not resolve address")
127
}
128

129
// Use in socket operations
130
val selectorManager = SelectorManager()
131
val socket = aSocket(selectorManager).tcp().connect(localhostAddress)
132
```
133

134
### Unix Socket Address
135

136
Socket address for Unix domain sockets supporting local inter-process communication.
137

138
```kotlin { .api }
139
/**
140
 * Unix domain socket address for local IPC
141
 * @param path The filesystem path for the socket
142
 */
143
class UnixSocketAddress(
144
    path: String
145
) : SocketAddress {
146
    /**
147
     * The path of the socket address.
148
     */
149
    val path: String
150

151
    /**
152
     * The path of the socket address.
153
     */
154
    operator fun component1(): String
155

156
    /**
157
     * Create a copy of UnixSocketAddress.
158
     */
159
    fun copy(path: String = this.path): UnixSocketAddress
160

161
    companion object {
162
        /**
163
         * Checks if Unix domain sockets are supported on the current platform.
164
         * @returns true if Unix domain sockets are supported, false otherwise
165
         */
166
        fun isSupported(): Boolean
167
    }
168
}
169
```
170

171
**Usage Examples:**
172

173
```kotlin
174
import io.ktor.network.sockets.*
175

176
// Check platform support
177
if (UnixSocketAddress.isSupported()) {
178
    // Create Unix socket addresses
179
    val unixAddress = UnixSocketAddress("/tmp/my-socket")
180
    val userSocket = UnixSocketAddress("/home/user/.app/socket")
181
    
182
    // Access properties
183
    println("Socket path: ${unixAddress.path}")
184
    
185
    // Destructuring declaration
186
    val (path) = unixAddress
187
    println("Socket at: $path")
188
    
189
    // Copy with modifications
190
    val backupSocket = unixAddress.copy(path = "/tmp/my-socket.backup")
191
    
192
    // Use in socket operations (if supported by platform)
193
    val selectorManager = SelectorManager()
194
    try {
195
        val socket = aSocket(selectorManager).tcp().connect(unixAddress)
196
        // Use socket for local IPC
197
    } catch (e: Exception) {
198
        println("Unix sockets not supported or connection failed: ${e.message}")
199
    }
200
} else {
201
    println("Unix domain sockets are not supported on this platform")
202
}
203
```
204

205
### Address Utility Functions
206

207
Utility functions for working with socket addresses.
208

209
```kotlin { .api }
210
/**
211
 * Extension function to get port from any SocketAddress
212
 * @returns port number for InetSocketAddress
213
 * @throws UnsupportedOperationException for address types that don't support ports
214
 */
215
fun SocketAddress.port(): Int
216
```
217

218
**Complete Example:**
219

220
```kotlin
221
import io.ktor.network.sockets.*
222
import io.ktor.network.selector.*
223

224
suspend fun addressExamples() {
225
    val selectorManager = SelectorManager()
226
    
227
    // Different address types
228
    val addresses = listOf(
229
        InetSocketAddress("localhost", 8080),
230
        InetSocketAddress("127.0.0.1", 8080),
231
        InetSocketAddress("::1", 8080), // IPv6 localhost
232
        InetSocketAddress("google.com", 80)
233
    )
234
    
235
    for (address in addresses) {
236
        println("Address: $address")
237
        println("Hostname: ${address.hostname}")
238
        println("Port: ${address.port}")
239
        
240
        // Try to resolve IP
241
        val ipBytes = address.resolveAddress()
242
        if (ipBytes != null) {
243
            if (ipBytes.size == 4) {
244
                println("IPv4: ${ipBytes.joinToString(".")}")
245
            } else if (ipBytes.size == 16) {
246
                println("IPv6: ${ipBytes.joinToString(":") { "%02x".format(it) }}")
247
            }
248
        }
249
        
250
        // Use address for connection
251
        try {
252
            val socket = aSocket(selectorManager).tcp().connect(address)
253
            println("Connected successfully to $address")
254
            socket.close()
255
        } catch (e: Exception) {
256
            println("Connection failed: ${e.message}")
257
        }
258
        
259
        println("---")
260
    }
261
    
262
    // Unix socket example (if supported)
263
    if (UnixSocketAddress.isSupported()) {
264
        val unixAddr = UnixSocketAddress("/tmp/test-socket")
265
        println("Unix socket: ${unixAddr.path}")
266
        
267
        // Note: Unix sockets don't have ports
268
        try {
269
            unixAddr.port()
270
        } catch (e: UnsupportedOperationException) {
271
            println("Unix sockets don't support port(): ${e.message}")
272
        }
273
    }
274
    
275
    selectorManager.close()
276
}
277
```