Copas
Coroutine Oriented Portable Asynchronous Services for Lua

Overview

Copas is a dispatcher based on coroutines that can be used for asynchroneous networking. For example TCP or UDP based servers. But it also features timers and client support for http(s), ftp and smtp requests.

It uses LuaSocket as the interface with the TCP/IP stack and LuaSec for ssl support.

A server or thread registered with Copas should provide a handler for requests and use Copas socket functions to send the response. Copas loops through requests and invokes the corresponding handlers. For a full implementation of a Copas HTTP server you can refer to Xavante as an example.

Copas is free software and uses the same license as Lua 5.1 to 5.3

Status

Current version is 3.0.0 and was developed for Lua 5.1 to 5.3.

Download

Copas can be downloaded from its Github page, in the "Downloads" tab.

You can also install Copas using LuaRocks:

luarocks install copas

Dependencies

Copas depends on LuaSocket, Coxpcall (only when using Lua 5.1), and (optionally) LuaSec.

History

Copas 3.0.0 [12/Nov/2021]
  • [breaking] Change: copas.addserver() now uses the timeout value as a copas timeout, instead of a luasocket timeout. The client sockets for incoming connections will inherit the timeout from the server socket.
  • Added: support for SNI on TLS connections #81 (@amyspark)
  • Added: copas.settimeout() so Copas can manage its own timeouts instead of spinning forever (Patrick Barrett )
  • Added: timer class, see module "copas.timer"
  • Added: lock class, see module "copas.lock"
  • Added: semaphore class, see module "copas.semaphore"
  • Added: timeout interface copas.timeout()
  • Added: option to override the default errorhandler, and fixes to the handler
  • Added: copas.removethread() added to be able to forcefully remove a previously added thread
  • Added: copas.loop() now takes an optional initialization function
  • Fixed: closing sockets from another thread would make the read/write ops hang #104
  • Fixed: coxpcall dependency in limit.lua #63 (Francois Perrad)
  • Fixed: CI now generates the certificates for testing, on unix make can be used, on Windows generate them manually
  • Fixed: type in wrapped udp:setpeername was actually calling udp:getpeername
  • Fixed: default error handler didn't print the stacktrace
  • Fixed: small memory leak when sleeping until woken
  • Fixed: do not wrap udp:sendto() method, since udp send doesn't block
  • Change: performance improvement in big limit-sets (Francisco Castro)
  • Change: update deprecated tls default to tls 1.2 in (copas.http)
Copas 2.0.2 [2017]
  • Added: copas.running flag
  • Fixed: fix for http request #53 (Peter Melnichenko)
  • Added: extra parameter keep_open for the removeserver() method (Hisham Muhammad)
  • Change: tweaked makefile with a DESTDIR variable (Richard Leitner)
Copas 2.0.1 [2016]
  • Added: support for Lua 5.3 (no code changes, just rockspec update)
  • Fixed: yield across c boundary error (by Peter Melnichenko)
  • Fixed: bug in wrappers for setoption() and shutdown() (reported by Rob Probin)
Copas 2.0.0 [2015]
  • Added: removeserver() function to remove servers from the scheduler (by Paul Kulchenko)
  • Added: client requests for http(s), ftp, and smtp (like LuaSocket/LuaSec, but async)
  • Added: transparent async support (handshake, and send/receive) for ssl using LuaSec
  • Added: handler() as a convenience for full copas and ssl wrapping
  • [breaking] Change: the loop now exits when there is nothing more to do
  • [breaking] Change: dummy first argument to new tasks removed
  • Fixed: completed the socket wrappers, missing functions were added
  • Fixed: connect issue, step() errorring out instead of returning nil + error
  • Fixed: UDP sockets being auto closed
  • Fixed: the receivePartial function for http request support (by Paul Kulchenko)
Copas 1.2.1 [2013]
  • Fixed bad version constant
  • Fixed timer issue
  • updated documentation
Copas 1.2.0 [2013]
  • Support for Lua 5.2
  • UDP support
  • suspending threads
  • other minor updates
Copas 1.1.6 [18/Mar/2010]
  • Now checks to see if socket.http was required before copas
Copas 1.1.5 [07/Apr/2009]
  • Fixed bug reported by Sam Roberts on the Kepler list (found due to Xavante locking up on some POST requests)
Copas 1.1.4 [10/Dec/2008]
  • Fixed bug [#5372] - copas.connect is semi-broken (found by Gary NG)
Copas 1.1.3 [19/May/2008]
  • Using copcall instead of pcall in socket.protect (feature request [#5274] by Gary NG)
Copas 1.1.2 [15/May/2008]
  • Fixed Bug [#4249] - bugs in copas.receive (found by Gary NG)
Copas 1.1.1 [13/Aug/2007]
  • Compatible with Lua 5.1
  • Refactored by Thomas Harning Jr. (for more details check Bug 766)
  • Patch by Gary NG concerning the handling of stopped sockets
Copas 1.1 [20/Sep/2006]
Copas 1.0 [17/May/2005]
Copas 1.0 Beta[17/Feb/2005]
  • First public version

Credits

Copas was designed and implemented by André Carregal and Javier Guerra as part of the Kepler Project which holds its copyright. Copas development had significative contributions from Diego Nehab, Mike Pall, David Burgess, Leonardo Godinho, Thomas Harning Jr. and Gary NG.

Contact us

For more information please contact us. Comments are welcome!

You can also reach other Kepler developers and users on the Kepler Project mailing list.

Valid XHTML 1.0!