Socket

Q: What does connection refused mean?

ECONNREFUSED means your socket reached the target machine, but no program was listening on that port, so the operating system rejected the connection. Check that the server is running and listening on the address and port you expect.

In Turkish: soket

Updated September 30, 20263 min read

In short

A socket is a software endpoint that a program opens to send and receive data over a network, identified by an IP address, a port number, and a protocol.

What is a network socket?

A socket is the programming interface an application uses to communicate over a network. The program asks the operating system for a socket, connects it to a remote address or binds it to a local one, and then reads and writes data through it much as it would with a file. Almost every network program, from browsers and web servers to database drivers, is built on sockets, usually through the Berkeley sockets API, which first appeared in BSD Unix in the early 1980s and is now supported by every major operating system.

A TCP server creates a socket, binds it to a port such as 8080, and calls listen(); each time a client connects, accept() returns a new socket dedicated to that one conversation. The client creates its own socket and calls connect() with the server's address, after which both sides use send() and recv(). Each TCP connection is identified by four values: the source IP address, source port, destination IP address, and destination port. A UDP socket skips connecting and simply sends and receives individual datagrams, and on Unix-like systems every socket is a file descriptor, the same kind of handle used for open files.

If an IP address is a building's street address and a port is an apartment number, a socket is the telephone installed in that apartment: the device a program actually talks and listens through. Most developers use sockets indirectly through HTTP clients, web frameworks, and database libraries, but they show up in errors such as ECONNREFUSED (nothing is listening on that port) and EADDRINUSE (the port is already taken) and in settings like timeouts and connection pools. Unix domain sockets use the same API for fast communication between processes on the same machine, without going through the network stack.

A socket is often confused with a port and with WebSocket. A port is just a number, while a socket is a live object inside a program, and one listening port can have thousands of connected sockets at once, one per client. WebSocket, despite its name, is a specific protocol that gives browsers a long-lived two-way connection to a server; it runs over an ordinary TCP socket but is not the same thing as the low-level sockets API.

Key takeaways

A socket is a program's endpoint for sending and receiving network data.
Servers call bind(), listen(), and accept(); clients call connect(); both then send() and recv().
A TCP connection is identified by source IP, source port, destination IP, and destination port.
On Unix-like systems a socket is a file descriptor, and Unix domain sockets connect processes on one machine.
A port is a number, a socket is a live endpoint, and WebSocket is a separate protocol.

Example

A tiny TCP echo server with Python socketspython

import socket

# Accept connections and send back whatever each client sends
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as server:
    server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
    server.bind(("127.0.0.1", 8080))  # claim an address and port
    server.listen()                   # start accepting connections
    while True:
        conn, addr = server.accept()  # a new socket for each client
        with conn:
            data = conn.recv(1024)
            conn.sendall(data)        # echo the bytes back

# Try it from another terminal: echo hello | nc 127.0.0.1 8080

Readers ask

What is the difference between a socket and a port?

A port is a number that identifies a service on a machine, while a socket is an endpoint a program creates to communicate, tied to an address, a port, and a protocol. A single listening port can have many connected sockets, one for each client.

What is the difference between a socket and a WebSocket?

A socket is the general operating system interface for network communication, used by all kinds of programs. WebSocket is a specific protocol, started with an HTTP upgrade request, that gives web pages a persistent two-way channel to a server, and it runs on top of a TCP socket.

What does connection refused mean?

ECONNREFUSED means your socket reached the target machine, but no program was listening on that port, so the operating system rejected the connection. Check that the server is running and listening on the address and port you expect.