0
# Socket Configuration
1

2
Comprehensive socket configuration options for tuning socket behavior including timeouts, buffer sizes, and protocol-specific options.
3

4
## Capabilities
5

6
### Base Socket Options
7

8
Base configuration options available for all socket types.
9

10
```kotlin { .api }
11
/**
12
 * Socket options builder - base class for all socket configuration
13
 */
14
sealed class SocketOptions {
15
    /**
16
     * ToS value, TypeOfService.UNDEFINED by default, may not work with old JDK (will be silently ignored)
17
     */
18
    var typeOfService: TypeOfService = TypeOfService.UNDEFINED
19

20
    /**
21
     * SO_REUSEADDR option
22
     */
23
    var reuseAddress: Boolean = false
24

25
    /**
26
     * SO_REUSEPORT option, may not work with old JDK (will be silently ignored)
27
     */
28
    var reusePort: Boolean = false
29
}
30
```
31

32
### TCP Server Socket Options
33

34
Configuration options specific to TCP server sockets.
35

36
```kotlin { .api }
37
/**
38
 * TCP server socket options
39
 */
40
class AcceptorOptions : SocketOptions {
41
    /**
42
     * Represents TCP server socket backlog size. When a client attempts to connect,
43
     * the request is added to the backlog until it will be accepted.
44
     * Once accept() is invoked, a client socket is removed from the backlog.
45
     * If the backlog is too small, it may overflow and upcoming requests will be
46
     * rejected by the underlying TCP implementation.
47
     * Default: 511
48
     */
49
    var backlogSize: Int = 511
50
}
51
```
52

53
**Usage Example:**
54

55
```kotlin
56
import io.ktor.network.sockets.*
57
import io.ktor.network.selector.*
58

59
val selectorManager = SelectorManager()
60

61
// Configure TCP server socket
62
val serverSocket = aSocket(selectorManager).tcp().bind("0.0.0.0", 8080) {
63
    backlogSize = 100
64
    reuseAddress = true
65
    reusePort = true
66
    typeOfService = TypeOfService.IPTOS_RELIABILITY
67
}
68

69
println("Server listening on port ${serverSocket.port}")
70
println("Backlog size: ${serverSocket.options.backlogSize}")
71
```
72

73
### Peer Socket Options
74

75
Base configuration options for client sockets and peer connections.
76

77
```kotlin { .api }
78
/**
79
 * Represents TCP client or UDP socket options
80
 */
81
open class PeerSocketOptions : SocketOptions {
82
    /**
83
     * Socket outgoing buffer size (SO_SNDBUF), -1 or 0 to make system decide
84
     * Default: -1
85
     */
86
    var sendBufferSize: Int = -1
87

88
    /**
89
     * Socket incoming buffer size (SO_RCVBUF), -1 or 0 to make system decide
90
     * Default: -1
91
     */
92
    var receiveBufferSize: Int = -1
93
}
94
```
95

96
### TCP Client Socket Options
97

98
Configuration options specific to TCP client sockets.
99

100
```kotlin { .api }
101
/**
102
 * Represents TCP client socket options
103
 */
104
class TCPClientSocketOptions : PeerSocketOptions {
105
    /**
106
     * TCP_NODELAY socket option, useful to disable Nagle algorithm
107
     * Default: true
108
     */
109
    var noDelay: Boolean = true
110

111
    /**
112
     * SO_LINGER option applied at socket close, not recommended to set to 0 however useful for debugging
113
     * Value of -1 is the default and means that it is not set and system-dependent
114
     * Default: -1
115
     */
116
    var lingerSeconds: Int = -1
117

118
    /**
119
     * SO_KEEPALIVE option is to enable/disable TCP keep-alive
120
     * Default: null (system default)
121
     */
122
    var keepAlive: Boolean? = null
123

124
    /**
125
     * Socket timeout (read and write) in milliseconds
126
     * Default: Long.MAX_VALUE (infinite)
127
     */
128
    var socketTimeout: Long = Long.MAX_VALUE
129
}
130
```
131

132
**Usage Examples:**
133

134
```kotlin
135
import io.ktor.network.sockets.*
136
import io.ktor.network.selector.*
137

138
val selectorManager = SelectorManager()
139

140
// Configure TCP client with performance options
141
val fastSocket = aSocket(selectorManager).tcp().connect("localhost", 8080) {
142
    noDelay = true              // Disable Nagle algorithm for low latency
143
    keepAlive = true            // Enable keep-alive
144
    socketTimeout = 30000       // 30 second timeout
145
    sendBufferSize = 64 * 1024  // 64KB send buffer
146
    receiveBufferSize = 64 * 1024 // 64KB receive buffer
147
}
148

149
// Configure TCP client with reliability options
150
val reliableSocket = aSocket(selectorManager).tcp().connect("remote-server.com", 443) {
151
    noDelay = false             // Enable Nagle for better throughput
152
    keepAlive = true            // Enable keep-alive
153
    lingerSeconds = 5           // Wait up to 5 seconds for data to be sent on close
154
    socketTimeout = 60000       // 60 second timeout
155
    typeOfService = TypeOfService.IPTOS_RELIABILITY
156
}
157

158
// Configure TCP client for debugging
159
val debugSocket = aSocket(selectorManager).tcp().connect("localhost", 8080) {
160
    noDelay = true
161
    lingerSeconds = 0           // Immediate close (useful for debugging)
162
    socketTimeout = 5000        // Short timeout for testing
163
}
164
```
165

166
### UDP Socket Options
167

168
Configuration options specific to UDP sockets.
169

170
```kotlin { .api }
171
/**
172
 * Represents UDP socket options
173
 */
174
class UDPSocketOptions : PeerSocketOptions {
175
    /**
176
     * SO_BROADCAST socket option - enables broadcast datagram transmission
177
     * Default: false
178
     */
179
    var broadcast: Boolean = false
180
}
181
```
182

183
**Usage Examples:**
184

185
```kotlin
186
import io.ktor.network.sockets.*
187
import io.ktor.network.selector.*
188

189
val selectorManager = SelectorManager()
190

191
// Configure UDP socket for broadcast
192
val broadcastSocket = aSocket(selectorManager).udp().bind("0.0.0.0", 8080) {
193
    broadcast = true            // Enable broadcast
194
    reuseAddress = true         // Allow multiple processes to bind
195
    receiveBufferSize = 1024 * 1024 // 1MB receive buffer
196
}
197

198
// Configure UDP socket for unicast with large buffers
199
val unicastSocket = aSocket(selectorManager).udp().connect(
200
    InetSocketAddress("server.example.com", 8080)
201
) {
202
    broadcast = false
203
    sendBufferSize = 512 * 1024     // 512KB send buffer
204
    receiveBufferSize = 512 * 1024  // 512KB receive buffer
205
    typeOfService = TypeOfService.IPTOS_THROUGHPUT
206
}
207
```
208

209
### Type of Service
210

211
Value class for IP Type of Service (ToS) field configuration.
212

213
```kotlin { .api }
214
/**
215
 * An inline class to hold a IP ToS value
216
 * @property value an unsigned byte IP_TOS value
217
 */
218
value class TypeOfService(val value: UByte) {
219
    /**
220
     * Creates ToS by integer value discarding extra high bits
221
     */
222
    constructor(value: Int) : this(value.toUByte())
223

224
    /**
225
     * Integer representation of this ToS
226
     */
227
    val intValue: Int
228

229
    companion object {
230
        val UNDEFINED: TypeOfService = TypeOfService(0u)
231
        val IPTOS_LOWCOST: TypeOfService = TypeOfService(0x02u)
232
        val IPTOS_RELIABILITY: TypeOfService = TypeOfService(0x04u)
233
        val IPTOS_THROUGHPUT: TypeOfService = TypeOfService(0x08u)
234
        val IPTOS_LOWDELAY: TypeOfService = TypeOfService(0x10u)
235
    }
236
}
237
```
238

239
**Usage Example:**
240

241
```kotlin
242
import io.ktor.network.sockets.*
243
import io.ktor.network.selector.*
244

245
val selectorManager = SelectorManager()
246

247
// Configure sockets with different ToS values for different use cases
248
val gameSocket = aSocket(selectorManager).tcp().connect("game-server.com", 7777) {
249
    typeOfService = TypeOfService.IPTOS_LOWDELAY  // Gaming requires low latency
250
    noDelay = true
251
    socketTimeout = 10000
252
}
253

254
val fileTransferSocket = aSocket(selectorManager).tcp().connect("file-server.com", 21) {
255
    typeOfService = TypeOfService.IPTOS_THROUGHPUT  // File transfer needs high throughput
256
    noDelay = false  // Allow Nagle for better bulk transfer
257
}
258

259
val backupSocket = aSocket(selectorManager).tcp().connect("backup-server.com", 22) {
260
    typeOfService = TypeOfService.IPTOS_RELIABILITY  // Backup needs reliability
261
    keepAlive = true
262
    socketTimeout = 300000  // 5 minute timeout
263
}
264

265
val costOptimizedSocket = aSocket(selectorManager).tcp().connect("service.com", 80) {
266
    typeOfService = TypeOfService.IPTOS_LOWCOST  // Cost-sensitive traffic
267
}
268

269
// Custom ToS value
270
val customSocket = aSocket(selectorManager).tcp().connect("custom-server.com", 8080) {
271
    typeOfService = TypeOfService(0x20)  // Custom ToS value
272
}
273

274
println("Game socket ToS: ${gameSocket.options.typeOfService.intValue}")
275
```
276

277
### Configuration Patterns
278

279
Common configuration patterns for different use cases.
280

281
**Complete Configuration Examples:**
282

283
```kotlin
284
import io.ktor.network.sockets.*
285
import io.ktor.network.selector.*
286

287
val selectorManager = SelectorManager()
288

289
// High-performance TCP server
290
val highPerfServer = aSocket(selectorManager).tcp().bind("0.0.0.0", 8080) {
291
    backlogSize = 1000
292
    reuseAddress = true
293
    reusePort = true
294
    typeOfService = TypeOfService.IPTOS_THROUGHPUT
295
}
296

297
// Robust TCP client with timeouts
298
val robustClient = aSocket(selectorManager).tcp().connect("api.example.com", 443) {
299
    noDelay = true
300
    keepAlive = true
301
    socketTimeout = 30000
302
    lingerSeconds = 5
303
    sendBufferSize = 128 * 1024
304
    receiveBufferSize = 128 * 1024
305
    typeOfService = TypeOfService.IPTOS_RELIABILITY
306
}
307

308
// UDP multicast sender
309
val multicastSender = aSocket(selectorManager).udp().bind() {
310
    broadcast = true
311
    reuseAddress = true
312
    sendBufferSize = 256 * 1024
313
    typeOfService = TypeOfService.IPTOS_THROUGHPUT
314
}
315

316
// Debug-friendly configuration
317
val debugSocket = aSocket(selectorManager).tcp().connect("localhost", 8080) {
318
    noDelay = true
319
    lingerSeconds = 0     // Immediate close
320
    socketTimeout = 5000  // Short timeout
321
    keepAlive = false
322
}
323

324
// Memory-constrained configuration
325
val lightweightSocket = aSocket(selectorManager).tcp().connect("service.com", 80) {
326
    sendBufferSize = 8 * 1024    // Small buffers
327
    receiveBufferSize = 8 * 1024
328
    socketTimeout = 15000        // Shorter timeout
329
    typeOfService = TypeOfService.IPTOS_LOWCOST
330
}
331
```