net.d.ts (38709B)
1 /** 2 * > Stability: 2 - Stable 3 * 4 * The `net` module provides an asynchronous network API for creating stream-based 5 * TCP or `IPC` servers ({@link createServer}) and clients 6 * ({@link createConnection}). 7 * 8 * It can be accessed using: 9 * 10 * ```js 11 * import net from 'node:net'; 12 * ``` 13 * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/net.js) 14 */ 15 declare module "net" { 16 import * as stream from "node:stream"; 17 import { Abortable, EventEmitter } from "node:events"; 18 import * as dns from "node:dns"; 19 type LookupFunction = ( 20 hostname: string, 21 options: dns.LookupOneOptions, 22 callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void, 23 ) => void; 24 interface AddressInfo { 25 address: string; 26 family: string; 27 port: number; 28 } 29 interface SocketConstructorOpts { 30 fd?: number | undefined; 31 allowHalfOpen?: boolean | undefined; 32 readable?: boolean | undefined; 33 writable?: boolean | undefined; 34 signal?: AbortSignal; 35 } 36 interface OnReadOpts { 37 buffer: Uint8Array | (() => Uint8Array); 38 /** 39 * This function is called for every chunk of incoming data. 40 * Two arguments are passed to it: the number of bytes written to buffer and a reference to buffer. 41 * Return false from this function to implicitly pause() the socket. 42 */ 43 callback(bytesWritten: number, buf: Uint8Array): boolean; 44 } 45 interface ConnectOpts { 46 /** 47 * If specified, incoming data is stored in a single buffer and passed to the supplied callback when data arrives on the socket. 48 * Note: this will cause the streaming functionality to not provide any data, however events like 'error', 'end', and 'close' will 49 * still be emitted as normal and methods like pause() and resume() will also behave as expected. 50 */ 51 onread?: OnReadOpts | undefined; 52 } 53 interface TcpSocketConnectOpts extends ConnectOpts { 54 port: number; 55 host?: string | undefined; 56 localAddress?: string | undefined; 57 localPort?: number | undefined; 58 hints?: number | undefined; 59 family?: number | undefined; 60 lookup?: LookupFunction | undefined; 61 noDelay?: boolean | undefined; 62 keepAlive?: boolean | undefined; 63 keepAliveInitialDelay?: number | undefined; 64 } 65 interface IpcSocketConnectOpts extends ConnectOpts { 66 path: string; 67 } 68 type SocketConnectOpts = TcpSocketConnectOpts | IpcSocketConnectOpts; 69 type SocketReadyState = "opening" | "open" | "readOnly" | "writeOnly" | "closed"; 70 /** 71 * This class is an abstraction of a TCP socket or a streaming `IPC` endpoint 72 * (uses named pipes on Windows, and Unix domain sockets otherwise). It is also 73 * an `EventEmitter`. 74 * 75 * A `net.Socket` can be created by the user and used directly to interact with 76 * a server. For example, it is returned by {@link createConnection}, 77 * so the user can use it to talk to the server. 78 * 79 * It can also be created by Node.js and passed to the user when a connection 80 * is received. For example, it is passed to the listeners of a `'connection'` event emitted on a {@link Server}, so the user can use 81 * it to interact with the client. 82 * @since v0.3.4 83 */ 84 class Socket extends stream.Duplex { 85 constructor(options?: SocketConstructorOpts); 86 /** 87 * Destroys the socket after all data is written. If the `finish` event was already emitted the socket is destroyed immediately. 88 * If the socket is still writable it implicitly calls `socket.end()`. 89 * @since v0.3.4 90 */ 91 destroySoon(): void; 92 /** 93 * Sends data on the socket. The second parameter specifies the encoding in the 94 * case of a string. It defaults to UTF8 encoding. 95 * 96 * Returns `true` if the entire data was flushed successfully to the kernel 97 * buffer. Returns `false` if all or part of the data was queued in user memory.`'drain'` will be emitted when the buffer is again free. 98 * 99 * The optional `callback` parameter will be executed when the data is finally 100 * written out, which may not be immediately. 101 * 102 * See `Writable` stream `write()` method for more 103 * information. 104 * @since v0.1.90 105 * @param [encoding='utf8'] Only used when data is `string`. 106 */ 107 write(buffer: Uint8Array | string, cb?: (err?: Error) => void): boolean; 108 write(str: Uint8Array | string, encoding?: BufferEncoding, cb?: (err?: Error) => void): boolean; 109 /** 110 * Initiate a connection on a given socket. 111 * 112 * Possible signatures: 113 * 114 * * `socket.connect(options[, connectListener])` 115 * * `socket.connect(path[, connectListener])` for `IPC` connections. 116 * * `socket.connect(port[, host][, connectListener])` for TCP connections. 117 * * Returns: `net.Socket` The socket itself. 118 * 119 * This function is asynchronous. When the connection is established, the `'connect'` event will be emitted. If there is a problem connecting, 120 * instead of a `'connect'` event, an `'error'` event will be emitted with 121 * the error passed to the `'error'` listener. 122 * The last parameter `connectListener`, if supplied, will be added as a listener 123 * for the `'connect'` event **once**. 124 * 125 * This function should only be used for reconnecting a socket after`'close'` has been emitted or otherwise it may lead to undefined 126 * behavior. 127 */ 128 connect(options: SocketConnectOpts, connectionListener?: () => void): this; 129 connect(port: number, host: string, connectionListener?: () => void): this; 130 connect(port: number, connectionListener?: () => void): this; 131 connect(path: string, connectionListener?: () => void): this; 132 /** 133 * Set the encoding for the socket as a `Readable Stream`. See `readable.setEncoding()` for more information. 134 * @since v0.1.90 135 * @return The socket itself. 136 */ 137 setEncoding(encoding?: BufferEncoding): this; 138 /** 139 * Pauses the reading of data. That is, `'data'` events will not be emitted. 140 * Useful to throttle back an upload. 141 * @return The socket itself. 142 */ 143 pause(): this; 144 /** 145 * Resumes reading after a call to `socket.pause()`. 146 * @return The socket itself. 147 */ 148 resume(): this; 149 /** 150 * Sets the socket to timeout after `timeout` milliseconds of inactivity on 151 * the socket. By default `net.Socket` do not have a timeout. 152 * 153 * When an idle timeout is triggered the socket will receive a `'timeout'` event but the connection will not be severed. The user must manually call `socket.end()` or `socket.destroy()` to 154 * end the connection. 155 * 156 * ```js 157 * socket.setTimeout(3000); 158 * socket.on('timeout', () => { 159 * console.log('socket timeout'); 160 * socket.end(); 161 * }); 162 * ``` 163 * 164 * If `timeout` is 0, then the existing idle timeout is disabled. 165 * 166 * The optional `callback` parameter will be added as a one-time listener for the `'timeout'` event. 167 * @since v0.1.90 168 * @return The socket itself. 169 */ 170 setTimeout(timeout: number, callback?: () => void): this; 171 /** 172 * Enable/disable the use of Nagle's algorithm. 173 * 174 * When a TCP connection is created, it will have Nagle's algorithm enabled. 175 * 176 * Nagle's algorithm delays data before it is sent via the network. It attempts 177 * to optimize throughput at the expense of latency. 178 * 179 * Passing `true` for `noDelay` or not passing an argument will disable Nagle's 180 * algorithm for the socket. Passing `false` for `noDelay` will enable Nagle's 181 * algorithm. 182 * @since v0.1.90 183 * @param [noDelay=true] 184 * @return The socket itself. 185 */ 186 setNoDelay(noDelay?: boolean): this; 187 /** 188 * Enable/disable keep-alive functionality, and optionally set the initial 189 * delay before the first keepalive probe is sent on an idle socket. 190 * 191 * Set `initialDelay` (in milliseconds) to set the delay between the last 192 * data packet received and the first keepalive probe. Setting `0` for`initialDelay` will leave the value unchanged from the default 193 * (or previous) setting. 194 * 195 * Enabling the keep-alive functionality will set the following socket options: 196 * 197 * * `SO_KEEPALIVE=1` 198 * * `TCP_KEEPIDLE=initialDelay` 199 * * `TCP_KEEPCNT=10` 200 * * `TCP_KEEPINTVL=1` 201 * @since v0.1.92 202 * @param [enable=false] 203 * @param [initialDelay=0] 204 * @return The socket itself. 205 */ 206 setKeepAlive(enable?: boolean, initialDelay?: number): this; 207 /** 208 * Returns the bound `address`, the address `family` name and `port` of the 209 * socket as reported by the operating system:`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }` 210 * @since v0.1.90 211 */ 212 address(): AddressInfo | {}; 213 /** 214 * Calling `unref()` on a socket will allow the program to exit if this is the only 215 * active socket in the event system. If the socket is already `unref`ed calling`unref()` again will have no effect. 216 * @since v0.9.1 217 * @return The socket itself. 218 */ 219 unref(): this; 220 /** 221 * Opposite of `unref()`, calling `ref()` on a previously `unref`ed socket will_not_ let the program exit if it's the only socket left (the default behavior). 222 * If the socket is `ref`ed calling `ref` again will have no effect. 223 * @since v0.9.1 224 * @return The socket itself. 225 */ 226 ref(): this; 227 /** 228 * This property shows the number of characters buffered for writing. The buffer 229 * may contain strings whose length after encoding is not yet known. So this number 230 * is only an approximation of the number of bytes in the buffer. 231 * 232 * `net.Socket` has the property that `socket.write()` always works. This is to 233 * help users get up and running quickly. The computer cannot always keep up 234 * with the amount of data that is written to a socket. The network connection 235 * simply might be too slow. Node.js will internally queue up the data written to a 236 * socket and send it out over the wire when it is possible. 237 * 238 * The consequence of this internal buffering is that memory may grow. 239 * Users who experience large or growing `bufferSize` should attempt to 240 * "throttle" the data flows in their program with `socket.pause()` and `socket.resume()`. 241 * @since v0.3.8 242 * @deprecated Since v14.6.0 - Use `writableLength` instead. 243 */ 244 readonly bufferSize: number; 245 /** 246 * The amount of received bytes. 247 * @since v0.5.3 248 */ 249 readonly bytesRead: number; 250 /** 251 * The amount of bytes sent. 252 * @since v0.5.3 253 */ 254 readonly bytesWritten: number; 255 /** 256 * If `true`, `socket.connect(options[, connectListener])` was 257 * called and has not yet finished. It will stay `true` until the socket becomes 258 * connected, then it is set to `false` and the `'connect'` event is emitted. Note 259 * that the `socket.connect(options[, connectListener])` callback is a listener for the `'connect'` event. 260 * @since v6.1.0 261 */ 262 readonly connecting: boolean; 263 /** 264 * See `writable.destroyed` for further details. 265 */ 266 readonly destroyed: boolean; 267 /** 268 * The string representation of the local IP address the remote client is 269 * connecting on. For example, in a server listening on `'0.0.0.0'`, if a client 270 * connects on `'192.168.1.1'`, the value of `socket.localAddress` would be`'192.168.1.1'`. 271 * @since v0.9.6 272 */ 273 readonly localAddress?: string; 274 /** 275 * The numeric representation of the local port. For example, `80` or `21`. 276 * @since v0.9.6 277 */ 278 readonly localPort?: number; 279 /** 280 * The string representation of the local IP family. `'IPv4'` or `'IPv6'`. 281 * @since v18.8.0, v16.18.0 282 */ 283 readonly localFamily?: string; 284 /** 285 * This is `true` if the socket is not connected yet, either because `.connect()` 286 * has not yet been called or because it is still in the process of connecting (see `socket.connecting`). 287 * @since v10.16.0 288 */ 289 readonly pending: boolean; 290 /** 291 * This property represents the state of the connection as a string. 292 * @see {https://nodejs.org/api/net.html#socketreadystate} 293 * @since v0.5.0 294 */ 295 readonly readyState: SocketReadyState; 296 /** 297 * The string representation of the remote IP address. For example,`'74.125.127.100'` or `'2001:4860:a005::68'`. Value may be `undefined` if 298 * the socket is destroyed (for example, if the client disconnected). 299 * @since v0.5.10 300 */ 301 readonly remoteAddress?: string | undefined; 302 /** 303 * The string representation of the remote IP family. `'IPv4'` or `'IPv6'`. 304 * @since v0.11.14 305 */ 306 readonly remoteFamily?: string | undefined; 307 /** 308 * The numeric representation of the remote port. For example, `80` or `21`. 309 * @since v0.5.10 310 */ 311 readonly remotePort?: number | undefined; 312 /** 313 * The socket timeout in milliseconds as set by socket.setTimeout(). It is undefined if a timeout has not been set. 314 * @since v10.7.0 315 */ 316 readonly timeout?: number | undefined; 317 /** 318 * Half-closes the socket. i.e., it sends a FIN packet. It is possible the 319 * server will still send some data. 320 * 321 * See `writable.end()` for further details. 322 * @since v0.1.90 323 * @param [encoding='utf8'] Only used when data is `string`. 324 * @param callback Optional callback for when the socket is finished. 325 * @return The socket itself. 326 */ 327 end(callback?: () => void): this; 328 end(buffer: Uint8Array | string, callback?: () => void): this; 329 end(str: Uint8Array | string, encoding?: BufferEncoding, callback?: () => void): this; 330 /** 331 * events.EventEmitter 332 * 1. close 333 * 2. connect 334 * 3. data 335 * 4. drain 336 * 5. end 337 * 6. error 338 * 7. lookup 339 * 8. timeout 340 */ 341 addListener(event: string, listener: (...args: any[]) => void): this; 342 addListener(event: "close", listener: (hadError: boolean) => void): this; 343 addListener(event: "connect", listener: () => void): this; 344 addListener(event: "data", listener: (data: Buffer) => void): this; 345 addListener(event: "drain", listener: () => void): this; 346 addListener(event: "end", listener: () => void): this; 347 addListener(event: "error", listener: (err: Error) => void): this; 348 addListener( 349 event: "lookup", 350 listener: (err: Error, address: string, family: string | number, host: string) => void, 351 ): this; 352 addListener(event: "ready", listener: () => void): this; 353 addListener(event: "timeout", listener: () => void): this; 354 emit(event: string | symbol, ...args: any[]): boolean; 355 emit(event: "close", hadError: boolean): boolean; 356 emit(event: "connect"): boolean; 357 emit(event: "data", data: Buffer): boolean; 358 emit(event: "drain"): boolean; 359 emit(event: "end"): boolean; 360 emit(event: "error", err: Error): boolean; 361 emit(event: "lookup", err: Error, address: string, family: string | number, host: string): boolean; 362 emit(event: "ready"): boolean; 363 emit(event: "timeout"): boolean; 364 on(event: string, listener: (...args: any[]) => void): this; 365 on(event: "close", listener: (hadError: boolean) => void): this; 366 on(event: "connect", listener: () => void): this; 367 on(event: "data", listener: (data: Buffer) => void): this; 368 on(event: "drain", listener: () => void): this; 369 on(event: "end", listener: () => void): this; 370 on(event: "error", listener: (err: Error) => void): this; 371 on( 372 event: "lookup", 373 listener: (err: Error, address: string, family: string | number, host: string) => void, 374 ): this; 375 on(event: "ready", listener: () => void): this; 376 on(event: "timeout", listener: () => void): this; 377 once(event: string, listener: (...args: any[]) => void): this; 378 once(event: "close", listener: (hadError: boolean) => void): this; 379 once(event: "connect", listener: () => void): this; 380 once(event: "data", listener: (data: Buffer) => void): this; 381 once(event: "drain", listener: () => void): this; 382 once(event: "end", listener: () => void): this; 383 once(event: "error", listener: (err: Error) => void): this; 384 once( 385 event: "lookup", 386 listener: (err: Error, address: string, family: string | number, host: string) => void, 387 ): this; 388 once(event: "ready", listener: () => void): this; 389 once(event: "timeout", listener: () => void): this; 390 prependListener(event: string, listener: (...args: any[]) => void): this; 391 prependListener(event: "close", listener: (hadError: boolean) => void): this; 392 prependListener(event: "connect", listener: () => void): this; 393 prependListener(event: "data", listener: (data: Buffer) => void): this; 394 prependListener(event: "drain", listener: () => void): this; 395 prependListener(event: "end", listener: () => void): this; 396 prependListener(event: "error", listener: (err: Error) => void): this; 397 prependListener( 398 event: "lookup", 399 listener: (err: Error, address: string, family: string | number, host: string) => void, 400 ): this; 401 prependListener(event: "ready", listener: () => void): this; 402 prependListener(event: "timeout", listener: () => void): this; 403 prependOnceListener(event: string, listener: (...args: any[]) => void): this; 404 prependOnceListener(event: "close", listener: (hadError: boolean) => void): this; 405 prependOnceListener(event: "connect", listener: () => void): this; 406 prependOnceListener(event: "data", listener: (data: Buffer) => void): this; 407 prependOnceListener(event: "drain", listener: () => void): this; 408 prependOnceListener(event: "end", listener: () => void): this; 409 prependOnceListener(event: "error", listener: (err: Error) => void): this; 410 prependOnceListener( 411 event: "lookup", 412 listener: (err: Error, address: string, family: string | number, host: string) => void, 413 ): this; 414 prependOnceListener(event: "ready", listener: () => void): this; 415 prependOnceListener(event: "timeout", listener: () => void): this; 416 } 417 interface ListenOptions extends Abortable { 418 port?: number | undefined; 419 host?: string | undefined; 420 backlog?: number | undefined; 421 path?: string | undefined; 422 exclusive?: boolean | undefined; 423 readableAll?: boolean | undefined; 424 writableAll?: boolean | undefined; 425 /** 426 * @default false 427 */ 428 ipv6Only?: boolean | undefined; 429 } 430 interface ServerOpts { 431 /** 432 * Indicates whether half-opened TCP connections are allowed. 433 * @default false 434 */ 435 allowHalfOpen?: boolean | undefined; 436 /** 437 * Indicates whether the socket should be paused on incoming connections. 438 * @default false 439 */ 440 pauseOnConnect?: boolean | undefined; 441 /** 442 * If set to `true`, it disables the use of Nagle's algorithm immediately after a new incoming connection is received. 443 * @default false 444 * @since v16.5.0 445 */ 446 noDelay?: boolean | undefined; 447 /** 448 * If set to `true`, it enables keep-alive functionality on the socket immediately after a new incoming connection is received, 449 * similarly on what is done in `socket.setKeepAlive([enable][, initialDelay])`. 450 * @default false 451 * @since v16.5.0 452 */ 453 keepAlive?: boolean | undefined; 454 /** 455 * If set to a positive number, it sets the initial delay before the first keepalive probe is sent on an idle socket. 456 * @default 0 457 * @since v16.5.0 458 */ 459 keepAliveInitialDelay?: number | undefined; 460 } 461 /** 462 * This class is used to create a TCP or `IPC` server. 463 * @since v0.1.90 464 */ 465 class Server extends EventEmitter { 466 constructor(connectionListener?: (socket: Socket) => void); 467 constructor(options?: ServerOpts, connectionListener?: (socket: Socket) => void); 468 /** 469 * Start a server listening for connections. A `net.Server` can be a TCP or 470 * an `IPC` server depending on what it listens to. 471 * 472 * Possible signatures: 473 * 474 * * `server.listen(handle[, backlog][, callback])` 475 * * `server.listen(options[, callback])` 476 * * `server.listen(path[, backlog][, callback])` for `IPC` servers 477 * * `server.listen([port[, host[, backlog]]][, callback])` for TCP servers 478 * 479 * This function is asynchronous. When the server starts listening, the `'listening'` event will be emitted. The last parameter `callback`will be added as a listener for the `'listening'` 480 * event. 481 * 482 * All `listen()` methods can take a `backlog` parameter to specify the maximum 483 * length of the queue of pending connections. The actual length will be determined 484 * by the OS through sysctl settings such as `tcp_max_syn_backlog` and `somaxconn` on Linux. The default value of this parameter is 511 (not 512). 485 * 486 * All {@link Socket} are set to `SO_REUSEADDR` (see [`socket(7)`](https://man7.org/linux/man-pages/man7/socket.7.html) for 487 * details). 488 * 489 * The `server.listen()` method can be called again if and only if there was an 490 * error during the first `server.listen()` call or `server.close()` has been 491 * called. Otherwise, an `ERR_SERVER_ALREADY_LISTEN` error will be thrown. 492 * 493 * One of the most common errors raised when listening is `EADDRINUSE`. 494 * This happens when another server is already listening on the requested`port`/`path`/`handle`. One way to handle this would be to retry 495 * after a certain amount of time: 496 * 497 * ```js 498 * server.on('error', (e) => { 499 * if (e.code === 'EADDRINUSE') { 500 * console.log('Address in use, retrying...'); 501 * setTimeout(() => { 502 * server.close(); 503 * server.listen(PORT, HOST); 504 * }, 1000); 505 * } 506 * }); 507 * ``` 508 */ 509 listen(port?: number, hostname?: string, backlog?: number, listeningListener?: () => void): this; 510 listen(port?: number, hostname?: string, listeningListener?: () => void): this; 511 listen(port?: number, backlog?: number, listeningListener?: () => void): this; 512 listen(port?: number, listeningListener?: () => void): this; 513 listen(path: string, backlog?: number, listeningListener?: () => void): this; 514 listen(path: string, listeningListener?: () => void): this; 515 listen(options: ListenOptions, listeningListener?: () => void): this; 516 listen(handle: any, backlog?: number, listeningListener?: () => void): this; 517 listen(handle: any, listeningListener?: () => void): this; 518 /** 519 * Stops the server from accepting new connections and keeps existing 520 * connections. This function is asynchronous, the server is finally closed 521 * when all connections are ended and the server emits a `'close'` event. 522 * The optional `callback` will be called once the `'close'` event occurs. Unlike 523 * that event, it will be called with an `Error` as its only argument if the server 524 * was not open when it was closed. 525 * @since v0.1.90 526 * @param callback Called when the server is closed. 527 */ 528 close(callback?: (err?: Error) => void): this; 529 /** 530 * Returns the bound `address`, the address `family` name, and `port` of the server 531 * as reported by the operating system if listening on an IP socket 532 * (useful to find which port was assigned when getting an OS-assigned address):`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }`. 533 * 534 * For a server listening on a pipe or Unix domain socket, the name is returned 535 * as a string. 536 * 537 * ```js 538 * const server = net.createServer((socket) => { 539 * socket.end('goodbye\n'); 540 * }).on('error', (err) => { 541 * // Handle errors here. 542 * throw err; 543 * }); 544 * 545 * // Grab an arbitrary unused port. 546 * server.listen(() => { 547 * console.log('opened server on', server.address()); 548 * }); 549 * ``` 550 * 551 * `server.address()` returns `null` before the `'listening'` event has been 552 * emitted or after calling `server.close()`. 553 * @since v0.1.90 554 */ 555 address(): AddressInfo | string | null; 556 /** 557 * Asynchronously get the number of concurrent connections on the server. Works 558 * when sockets were sent to forks. 559 * 560 * Callback should take two arguments `err` and `count`. 561 * @since v0.9.7 562 */ 563 getConnections(cb: (error: Error | null, count: number) => void): void; 564 /** 565 * Opposite of `unref()`, calling `ref()` on a previously `unref`ed server will_not_ let the program exit if it's the only server left (the default behavior). 566 * If the server is `ref`ed calling `ref()` again will have no effect. 567 * @since v0.9.1 568 */ 569 ref(): this; 570 /** 571 * Calling `unref()` on a server will allow the program to exit if this is the only 572 * active server in the event system. If the server is already `unref`ed calling`unref()` again will have no effect. 573 * @since v0.9.1 574 */ 575 unref(): this; 576 /** 577 * Set this property to reject connections when the server's connection count gets 578 * high. 579 * 580 * It is not recommended to use this option once a socket has been sent to a child 581 * with `child_process.fork()`. 582 * @since v0.2.0 583 */ 584 maxConnections: number; 585 connections: number; 586 /** 587 * Indicates whether or not the server is listening for connections. 588 * @since v5.7.0 589 */ 590 listening: boolean; 591 /** 592 * events.EventEmitter 593 * 1. close 594 * 2. connection 595 * 3. error 596 * 4. listening 597 */ 598 addListener(event: string, listener: (...args: any[]) => void): this; 599 addListener(event: "close", listener: () => void): this; 600 addListener(event: "connection", listener: (socket: Socket) => void): this; 601 addListener(event: "error", listener: (err: Error) => void): this; 602 addListener(event: "listening", listener: () => void): this; 603 emit(event: string | symbol, ...args: any[]): boolean; 604 emit(event: "close"): boolean; 605 emit(event: "connection", socket: Socket): boolean; 606 emit(event: "error", err: Error): boolean; 607 emit(event: "listening"): boolean; 608 on(event: string, listener: (...args: any[]) => void): this; 609 on(event: "close", listener: () => void): this; 610 on(event: "connection", listener: (socket: Socket) => void): this; 611 on(event: "error", listener: (err: Error) => void): this; 612 on(event: "listening", listener: () => void): this; 613 once(event: string, listener: (...args: any[]) => void): this; 614 once(event: "close", listener: () => void): this; 615 once(event: "connection", listener: (socket: Socket) => void): this; 616 once(event: "error", listener: (err: Error) => void): this; 617 once(event: "listening", listener: () => void): this; 618 prependListener(event: string, listener: (...args: any[]) => void): this; 619 prependListener(event: "close", listener: () => void): this; 620 prependListener(event: "connection", listener: (socket: Socket) => void): this; 621 prependListener(event: "error", listener: (err: Error) => void): this; 622 prependListener(event: "listening", listener: () => void): this; 623 prependOnceListener(event: string, listener: (...args: any[]) => void): this; 624 prependOnceListener(event: "close", listener: () => void): this; 625 prependOnceListener(event: "connection", listener: (socket: Socket) => void): this; 626 prependOnceListener(event: "error", listener: (err: Error) => void): this; 627 prependOnceListener(event: "listening", listener: () => void): this; 628 } 629 type IPVersion = "ipv4" | "ipv6"; 630 /** 631 * The `BlockList` object can be used with some network APIs to specify rules for 632 * disabling inbound or outbound access to specific IP addresses, IP ranges, or 633 * IP subnets. 634 * @since v15.0.0 635 */ 636 class BlockList { 637 /** 638 * Adds a rule to block the given IP address. 639 * @since v15.0.0 640 * @param address An IPv4 or IPv6 address. 641 * @param [type='ipv4'] Either `'ipv4'` or `'ipv6'`. 642 */ 643 addAddress(address: string, type?: IPVersion): void; 644 addAddress(address: SocketAddress): void; 645 /** 646 * Adds a rule to block a range of IP addresses from `start` (inclusive) to`end` (inclusive). 647 * @since v15.0.0 648 * @param start The starting IPv4 or IPv6 address in the range. 649 * @param end The ending IPv4 or IPv6 address in the range. 650 * @param [type='ipv4'] Either `'ipv4'` or `'ipv6'`. 651 */ 652 addRange(start: string, end: string, type?: IPVersion): void; 653 addRange(start: SocketAddress, end: SocketAddress): void; 654 /** 655 * Adds a rule to block a range of IP addresses specified as a subnet mask. 656 * @since v15.0.0 657 * @param net The network IPv4 or IPv6 address. 658 * @param prefix The number of CIDR prefix bits. For IPv4, this must be a value between `0` and `32`. For IPv6, this must be between `0` and `128`. 659 * @param [type='ipv4'] Either `'ipv4'` or `'ipv6'`. 660 */ 661 addSubnet(net: SocketAddress, prefix: number): void; 662 addSubnet(net: string, prefix: number, type?: IPVersion): void; 663 /** 664 * Returns `true` if the given IP address matches any of the rules added to the`BlockList`. 665 * 666 * ```js 667 * const blockList = new net.BlockList(); 668 * blockList.addAddress('123.123.123.123'); 669 * blockList.addRange('10.0.0.1', '10.0.0.10'); 670 * blockList.addSubnet('8592:757c:efae:4e45::', 64, 'ipv6'); 671 * 672 * console.log(blockList.check('123.123.123.123')); // Prints: true 673 * console.log(blockList.check('10.0.0.3')); // Prints: true 674 * console.log(blockList.check('222.111.111.222')); // Prints: false 675 * 676 * // IPv6 notation for IPv4 addresses works: 677 * console.log(blockList.check('::ffff:7b7b:7b7b', 'ipv6')); // Prints: true 678 * console.log(blockList.check('::ffff:123.123.123.123', 'ipv6')); // Prints: true 679 * ``` 680 * @since v15.0.0 681 * @param address The IP address to check 682 * @param [type='ipv4'] Either `'ipv4'` or `'ipv6'`. 683 */ 684 check(address: SocketAddress): boolean; 685 check(address: string, type?: IPVersion): boolean; 686 /** 687 * The list of rules added to the blocklist. 688 * @since v15.0.0, v14.18.0 689 */ 690 rules: readonly string[]; 691 } 692 interface TcpNetConnectOpts extends TcpSocketConnectOpts, SocketConstructorOpts { 693 timeout?: number | undefined; 694 } 695 interface IpcNetConnectOpts extends IpcSocketConnectOpts, SocketConstructorOpts { 696 timeout?: number | undefined; 697 } 698 type NetConnectOpts = TcpNetConnectOpts | IpcNetConnectOpts; 699 /** 700 * Creates a new TCP or `IPC` server. 701 * 702 * If `allowHalfOpen` is set to `true`, when the other end of the socket 703 * signals the end of transmission, the server will only send back the end of 704 * transmission when `socket.end()` is explicitly called. For example, in the 705 * context of TCP, when a FIN packed is received, a FIN packed is sent 706 * back only when `socket.end()` is explicitly called. Until then the 707 * connection is half-closed (non-readable but still writable). See `'end'` event and [RFC 1122](https://tools.ietf.org/html/rfc1122) (section 4.2.2.13) for more information. 708 * 709 * If `pauseOnConnect` is set to `true`, then the socket associated with each 710 * incoming connection will be paused, and no data will be read from its handle. 711 * This allows connections to be passed between processes without any data being 712 * read by the original process. To begin reading data from a paused socket, call `socket.resume()`. 713 * 714 * The server can be a TCP server or an `IPC` server, depending on what it `listen()` to. 715 * 716 * Here is an example of an TCP echo server which listens for connections 717 * on port 8124: 718 * 719 * ```js 720 * import net from 'node:net'; 721 * const server = net.createServer((c) => { 722 * // 'connection' listener. 723 * console.log('client connected'); 724 * c.on('end', () => { 725 * console.log('client disconnected'); 726 * }); 727 * c.write('hello\r\n'); 728 * c.pipe(c); 729 * }); 730 * server.on('error', (err) => { 731 * throw err; 732 * }); 733 * server.listen(8124, () => { 734 * console.log('server bound'); 735 * }); 736 * ``` 737 * 738 * Test this by using `telnet`: 739 * 740 * ```console 741 * $ telnet localhost 8124 742 * ``` 743 * 744 * To listen on the socket `/tmp/echo.sock`: 745 * 746 * ```js 747 * server.listen('/tmp/echo.sock', () => { 748 * console.log('server bound'); 749 * }); 750 * ``` 751 * 752 * Use `nc` to connect to a Unix domain socket server: 753 * 754 * ```console 755 * $ nc -U /tmp/echo.sock 756 * ``` 757 * @since v0.5.0 758 * @param connectionListener Automatically set as a listener for the {@link 'connection'} event. 759 */ 760 function createServer(connectionListener?: (socket: Socket) => void): Server; 761 function createServer(options?: ServerOpts, connectionListener?: (socket: Socket) => void): Server; 762 /** 763 * Aliases to {@link createConnection}. 764 * 765 * Possible signatures: 766 * 767 * * {@link connect} 768 * * {@link connect} for `IPC` connections. 769 * * {@link connect} for TCP connections. 770 */ 771 function connect(options: NetConnectOpts, connectionListener?: () => void): Socket; 772 function connect(port: number, host?: string, connectionListener?: () => void): Socket; 773 function connect(path: string, connectionListener?: () => void): Socket; 774 /** 775 * A factory function, which creates a new {@link Socket}, 776 * immediately initiates connection with `socket.connect()`, 777 * then returns the `net.Socket` that starts the connection. 778 * 779 * When the connection is established, a `'connect'` event will be emitted 780 * on the returned socket. The last parameter `connectListener`, if supplied, 781 * will be added as a listener for the `'connect'` event **once**. 782 * 783 * Possible signatures: 784 * 785 * * {@link createConnection} 786 * * {@link createConnection} for `IPC` connections. 787 * * {@link createConnection} for TCP connections. 788 * 789 * The {@link connect} function is an alias to this function. 790 */ 791 function createConnection(options: NetConnectOpts, connectionListener?: () => void): Socket; 792 function createConnection(port: number, host?: string, connectionListener?: () => void): Socket; 793 function createConnection(path: string, connectionListener?: () => void): Socket; 794 /** 795 * Tests if input is an IP address. Returns `0` for invalid strings, 796 * returns `4` for IP version 4 addresses, and returns `6` for IP version 6 797 * addresses. 798 * @since v0.3.0 799 */ 800 function isIP(input: string): number; 801 /** 802 * Returns `true` if input is a version 4 IP address, otherwise returns `false`. 803 * @since v0.3.0 804 */ 805 function isIPv4(input: string): boolean; 806 /** 807 * Returns `true` if input is a version 6 IP address, otherwise returns `false`. 808 * @since v0.3.0 809 */ 810 function isIPv6(input: string): boolean; 811 interface SocketAddressInitOptions { 812 /** 813 * The network address as either an IPv4 or IPv6 string. 814 * @default 127.0.0.1 815 */ 816 address?: string | undefined; 817 /** 818 * @default `'ipv4'` 819 */ 820 family?: IPVersion | undefined; 821 /** 822 * An IPv6 flow-label used only if `family` is `'ipv6'`. 823 * @default 0 824 */ 825 flowlabel?: number | undefined; 826 /** 827 * An IP port. 828 * @default 0 829 */ 830 port?: number | undefined; 831 } 832 /** 833 * @since v15.14.0 834 */ 835 class SocketAddress { 836 constructor(options: SocketAddressInitOptions); 837 /** 838 * @since v15.14.0 839 */ 840 readonly address: string; 841 /** 842 * Either \`'ipv4'\` or \`'ipv6'\`. 843 * @since v15.14.0 844 */ 845 readonly family: IPVersion; 846 /** 847 * @since v15.14.0 848 */ 849 readonly port: number; 850 /** 851 * @since v15.14.0 852 */ 853 readonly flowlabel: number; 854 } 855 } 856 declare module "node:net" { 857 export * from "net"; 858 }