LuaSocket: Network support for the Lua language

What is LuaSocket?

LuaSocket is a Lua extension library that is composed by two parts: a C core that provides support for the TCP and UDP transport layers, and a set of Lua modules that add support for functionality commonly needed by applications that deal with the Internet.

The core support has been implemented so that it is both efficient and simple to use. The core can be used by any Lua application once it has been properly initialized by the interpreter running the Lua application. The code has been tested and runs well on several Windows and Unix platforms.

The most used modules implement the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and downloading files) client protocols. These provide a very natural and generic interface to the e functionality covered by the protocols. In addition, you will find that the MIME (common encodings), URL (anything you could possible want to do with one) and LTN12 (filters, sinks, sources and pumps) modules can be very handy.

The library is available under the same terms and conditions as the Lua language, the MIT license. The idea is that if you can use Lua in a project, you should also be able to use LuaSocket.

Download

LuaSocket version 2.0 beta is now available for download! It is compatible with Lua 5.0 and has been tested on Windows XP, Linux, and Mac OS X.

The library can be downloaded in source code from the following links:

luasocket-2.0-beta.tar.gz
luasocket-2.0-beta.zip

Besides the full C and Lua source code for the library, the distribution contains several examples, this user's manual and the test procedures.

I am also providing PC Win32 binaries for those that want to give LuaSocket a quick try:

luasocket-2.0-beta-win32.zip

The quick and dirty way to use these binaries is to unpack everything into a directory, say c:\luasocket (include all Lua files from the LuaSocket distrbitution in the same directory too!). Then set LUA_INIT to load the lua.lua helper file:

c:\luasocket\> set LUA_INIT=@lua.lua

From that directory, you can then run the interpreter and it should find all files it needs. To download this manual page from the Internet, for example, do the following:

c:\luasocket\> lua
Lua 5.0.2  Copyright (C) 1994-2004 Tecgraf, PUC-Rio
> http = require"http"
> print(http.request"http://www.tecgraf.puc-rio.br/luasocket/")
--> this file

Special thanks

Throughout LuaSocket's history, many people gave suggestions that helped improve it. For that, I thank the Lua community. Special thanks go to David Burgess, who has helped push the library to a new level of quality and from whom I have learned a lot of stuff that doesn't show up in RFCs. Special thanks also to Carlos Cassino, who played a big part in the extensible design seen in the C core of LuaSocket 2.0.

What's New

Everything is new! Many changes for 2.0 happened in the C layer, which has been almost completely rewritten. The code has been ported to Lua 5.0 and greatly improved. There have also been some API changes that made the interface simpler and more consistent. Here are some of the changes that made it into version 2.0:

Major C code rewrite. Code is modular and extensible. Hopefully, other developers will be motivated to provide code for SSL, local domain sockets, file descriptors, pipes (on Unix) and named pipes etc;
Everything that is exported by the library is exported inside namespaces. These should be obtained with calls to the require function;
Functions such as send/receive/timeout/close etc do not exist anymore as stand-alone functions. They are now only available as methods of the appropriate objects;
All functions return a non-nil value as first return value if successful. All functions return nil followed by error message in case of error. This made the library much easier to use;
Greatly reduced the number of times the C select is called during data transfers, by calling only on failure. This might improve a lot the maximum throughput;
TCP has been changed to become more uniform. It's possible to first create a TCP object, then connect or bind if needed, and finally use I/O functions. socket.connect and socket.bind functions are still provided for simplicity;
This allows for setting a timeout value before connecting;
And also allows binding to a local address before connecting;
New socket.dns.gethostname function and shutdown method;
Better error messages and parameter checking;
Should be interrupt safe;
UDP connected sockets can break association with peer by calling setpeername with address '*';
Sets returned by socket.select are associative;
Select checks if sockets have buffered data and returns immediately;
socket.sleep and socket.gettime are now part of the library and are supported. They used to be available only when LUASOCKET_DEBUG was defined, but it turns out they might be useful for applications;
socket.try and socket.protect provide a simple interface to exceptions that proved very in the implementation of high-level modules;
Socket options interface has been improved. TCP objects also support socket options and many new options were added.

Lots of changes in the Lua modules, too!

Every module loads only the modules that it needs. There is no waste of memory. LuaSocket core takes only 20k of memory;
New MIME and LTN12 modules make all other modules much more powerful;
Support for multipart messages in the SMTP module;
The old callback mechanism of FTP and HTTP has been replaced with LTN12 sources and sinks, with advantage;
Common implementation for low-level FTP and SMTP;
FTP, HTTP, and SMTP are implemented in multiple levels in such a way that users will have no problems extending the functionality to satisfy personal needs;
SMTP knows how to perform LOGIN and PLAIN authentication.

Incompatibilities with previous versions

The introduction of namespaces affects all programs that use LuaSocket, specially code that relies on global functions. These are no longer available. Note that even the support modules (http, smtp etc) are independent now and should be "require"d;
FTP, SMTP and HTTP are completely new; I am sure you will agree the new stuff is better;
WARNING: The new send, receive, sendto, setpeername and setsockname, return convention WILL break old code;
To enable local binding before connect, the bind method does not call listen anymore. It is the new listen method that turns a TCP object into a server object;
socket.time changed to socket.gettime for uniformity;
Interface to options has changed.

Old Versions

All previous versions of the LuaSocket library can be downloaded here. Although these versions are no longer supported, they are still available for those that have compatibility issues.