Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns
The Node.js net.Server class
Reference for net.Server in Node.js: listen options, address(), close(), getConnections(), maxConnections and the listening, connection, close and error events.
net.Server is the object returned by net.createServer(). It listens on a TCP port or an IPC path and emits a 'connection' event with a net.Socket for every client. It is an EventEmitter, and the HTTP, HTTPS and TLS servers are all built on top of it.
A server has a simple life cycle: created, listening, closed. listen() binds the port and starts the 'listening' event; close() stops accepting new connections and emits 'close' once the last existing connection has ended.
import net from 'node:net'; const server = net.createServer(); server.on('connection', (socket) => socket.end('bye\n')); server.listen({ port: 0, host: '127.0.0.1' });
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
class net.Server extends EventEmitter server.listen(port?: number, host?: string, backlog?: number, callback?: () => void): net.Server server.listen(options: { port, host, path, backlog, exclusive, ipv6Only, signal, reusePort }, callback?): net.Server server.listen(path: string, callback?): net.Server server.close(callback?: (error?: Error) => void): net.Server server.address(): { address: string, family: string, port: number } | string | null server.getConnections(callback: (error: Error | null, count: number) => void): net.Server
| Member | Description |
|---|---|
listen(...) |
Starts listening. Port 0 picks a free port. Without host, binds :: when IPv6 is available, otherwise 0.0.0.0. Calling it on an already listening server throws ERR_SERVER_ALREADY_LISTEN. |
close(callback) |
Stops accepting connections. The callback runs after 'close', and receives an error if the server was not open (ERR_SERVER_NOT_RUNNING). |
address() |
An object for TCP, a string for pipes, null if not listening. |
getConnections(cb) |
Asynchronously counts open connections. |
maxConnections |
Connections beyond this limit are dropped and 'drop' is emitted. |
listening |
true while the server is listening. |
ref(), unref() |
Whether the server keeps the process alive. |
[Symbol.asyncDispose]() |
Closes the server with await using. |
Events: 'listening', 'connection' (socket), 'close', 'error', 'drop' (data about a connection refused because of maxConnections).
Errors and edge cases: common listen errors are EADDRINUSE (port taken), EACCES (privileged port), EADDRNOTAVAIL (address not on this machine). They are emitted as 'error', not thrown.
Usage notes
- Wait for
'listening'.listen()returns immediately; readaddress()only after the event (or in the callback). close()waits. A keep-alive client holds the server open. Track sockets anddestroy()them if shutdown must be quick.address()afterclose()isnull. Save the port first if you need it later.- Pipes return strings. For IPC servers
address()returns the path, not an object. exclusiveand clusters. In a cluster worker,listen()shares the handle with the primary unlessexclusive: true.- Port 0 for tests. It avoids clashes between parallel test runs.
- Use
unref()for helper servers that should not keep a process alive on their own.