TCP Basics

LuaSocket is the de-facto networking library for Lua. It exposes raw TCP and UDP sockets plus higher-level helpers for HTTP, SMTP and FTP.

It is an external C module, so it is not part of stock Lua. You install it via LuaRocks and load it with require.

None of the snippets in this course run on a plain playground because they touch the network.

The core object is the TCP master socket, created with socket.tcp(). A fresh master is unconnected and unbound.

From a master you can either connect (turning it into a client object) or bind+listen (turning it into a server object).

Most calls return either a value or nil plus an error string, so always capture both.

TCP works over IPv4 or IPv6. socket.tcp() picks the family lazily, while socket.tcp4() and socket.tcp6() force one.

Use socket.dns.toip(host) to resolve a hostname to a numeric address before connecting if you need explicit control.

conn:connect(host, port) performs the TCP three-way handshake. On success it returns 1; on failure it returns nil and an error message such as "connection refused" or "timeout".

The convenience function socket.connect(host, port) creates a socket and connects in one call.

conn:send(data) writes bytes to the socket. It returns the index of the last byte sent. With a blocking socket this is usually the full length of data.

TCP is a byte stream, not a message protocol, so a single send may be split or merged across the wire. You must frame your own messages.

conn:receive(pattern) reads from the stream. The default pattern "*l" reads one line without the newline. "*a" reads until the connection closes.

You can also pass a number to read exactly that many bytes. On error it returns nil, an error string, and any partial data received.

Always call conn:close() when finished to release the file descriptor and send a TCP FIN.

You can half-close with conn:shutdown("send") to signal end-of-stream while still reading the peer's response. This is handy for request/response protocols using "*a".

By default sockets block forever. conn:settimeout(seconds) bounds how long a call waits. A value of 0 makes the socket non-blocking.

When a timeout fires, the call returns nil and the string "timeout". Always set a timeout in production to avoid hung connections.

TCP is connection-oriented, ordered, and reliable: bytes arrive once and in order, at the cost of handshakes and retransmits.

UDP (socket.udp()) is connectionless and unreliable but lightweight, good for telemetry or games. This course focuses on TCP because it underpins HTTP.

On non-blocking sockets, send may transmit only part of your buffer. It returns nil, "timeout", and the index of the last byte written so far.

A robust sender loops, resuming from the byte after the last one sent until the whole buffer is flushed.

conn:getpeername() returns the remote IP and port, while conn:getsockname() returns the local end. These help with logging and debugging.

conn:setoption("keepalive", true) and conn:setoption("tcp-nodelay", true) tune the underlying socket behaviour.

Test your understanding of TCP receive semantics.

You met LuaSocket's TCP master object, learned to create, connect, send, receive, and close sockets, and saw how timeouts and half-close shape behaviour.

Remember TCP is a byte stream, every call may return nil, err, and a production socket always sets a timeout. Next you will assemble these pieces into a working client.