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.4

Status

Current version is 4.7.1 and was developed for Lua 5.1 to 5.4.

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 (or LuaSystem), Coxpcall (only when using Lua 5.1), and (optionally) LuaSec.

History

Copas 4.8.0 unreleased
  • Change: Copas no longer requires LuaSocket, if no sockets are needed, LuaSystem will be enough as a fallback.
  • Feat: added copas.gettime(), which transparently maps to either LuaSockets or LuaSystems implementation, ensuring independence of the availability of either one of those.
  • Feat: Controlled exit of the Copas loop. Adding copas.exit(), copas.exiting(), and copas.waitforexit().
Copas 4.7.1 [9/Mar/2024]
  • Fix: copas.removethread would not remove a sleeping thread immediately (it would not execute, but would prevent the Copas loop from exiting until the timer expired).
  • Fix: queue:finish will return after the last item has been handled, not just popped (if using workers).
Copas 4.7.0 [15/Jan/2023]
  • Fix: windows makefile didn't include all submodules.
  • Fix: creating a new timer with a bad delay setting would throw a bad error message.
  • Refactor: submodules are now part of copas (lazily loaded) and do not need to be required anymore
  • Feat: runtime script added to directly run copas based code
  • Fix: improved socket wrapper for lacking LuaSec methods (setoption, getoption, getpeername, getsockname)
  • Feat: added LuaSec methods to wrapper (getalpn, getsniname)
Copas 4.6.0 [30/Dec/2022]
  • Added: for timeouts in copas, lock, semaphore, and queue, allow math.huge to specify no timeout/wait forever. Using math.huge over long timeouts will reduce pressure on the timer-wheel.
  • Refactor: increase ringsize (timer-wheel) from 1 minute to 1 day to reduce timer-wheel pressure.
Copas 4.5.0 [18/Dec/2022]
  • Added: copas.status got an extra parameter to track more detailed stats.
  • Fix: queue workers would not properly handle falsy items in the queue. The worker would exit instead of handle the item.
  • Fix: a non-reentrant lock should block instead of returning an error when entered again.
  • Fix: finishing a queue would not honour the timeout.
  • Refactor: more manual cleanup instead of relying on weak-tables.
Copas 4.4.0 [23/Oct/2022]
  • Fix: an error in the timer callback would kill the timer.
  • Added: copas.geterrorhandler to retrieve the active errorhandler.
  • Added: option errorhandler for timer objects.
  • Added: copas.pause and copas.pauseforever to replace copas.sleep. The latter method can accidentally sleep-forever if time arithmetic returns a negative result.
  • Added: copas.status which returns an object with number of tasks/timers/sockets.
  • Change: renamed copas.setErrorHandler to copas.seterrorhandler.
  • Change: renamed copas.useSocketTimeoutErrors to copas.usesockettimeouterrors.
Copas 4.3.2 [03/Oct/2022]
  • Fix: error handler for timeouts. Underlying bug is in coxpcall, and hence this only applies to PuC Lua 5.1.
Copas 4.3.1 [21/Sep/2022]
  • Fix: with Lua 5.1 the timeouts would resume the wrapped (by coxpcall) coroutines, instead of the original ones. Causing errors to bubble up one level too many.
Copas 4.3.0 [19/Sep/2022]
  • Fix: when the loop is idle, do an occasional GC to clean out any lingering non-closed sockets. This could prevent the loop from exiting.
  • Fix: in debug mode very large data is now truncated when displayed.
  • Fix: the receive methods could starve other threads on high-throughput.
  • Change: order of copas.addnamedthread args.
  • Fix: copas.receivepartial could return early with no data received if the `prefix` parameter was specified.
  • Change: renamed copas.receivePartial to copas.receivepartial.
  • Added: sock:receivepartial to better process streaming TCP data.
  • fix: copas.receivepartial is now documented.
  • fix: copas.http was missing some error handling.
  • fix: Copas timeouts when receiving/sending would not return partial results, or last bytes sent.
Copas 4.2.0 [06/Sep/2022]
  • Change: pick up datagram size from newer LuaSocket versions.
  • Fix: non-recurring timer can now be armed again from its own handler.
  • Added: calling on the module table now invokes the copas.loop method.
Copas 4.1.0 [25/Aug/2022]
  • Fix: handle errors thrown by the error handlers themselves.
  • Deps: Bump timerwheel to 1.0 (no changes, just a small fix)
  • Added: copas.gettraceback, previously internal to the default error handler, now exposed to make it easier to write proper error handlers
  • Added: http-request now takes a timeout setting, previously it would always use the default value of 30 seconds.
  • Added: the previously internal function for generating a TCP socket in the http-request module, is now exported as http.getcreatefunc(). This allows to capture the socket used by the request. When using streaming responses, for example with server-sent events, this can be used to modify the timeouts, or for closing the stream.
  • Fix: empty queues were not destroyed properly and could prevent Copas from exiting
Copas 4.0.0 [29/Jul/2022]
  • [breaking] Change: removed the "limitset". Its functionality can easily be recreated with the new "queue" class, which is a better abstraction.
  • [breaking] Change: threads added through copas.addthread or copas.addnamedthread will now be "scheduled", instead of immediately started.
  • Fixed: yielding to the Copas scheduler from user-code now throws a proper error and no longer breaks the loop. Breaking the loop could also happen if a thread returned with at least 2 return values.
  • Fixed: wrongly auto-closing sockets. Upon exiting a coroutine, sockets would be automatically closed. This should only be the case for accepted TCP connections on a TCP server socket. This caused issues for sockets shared between threads.
    [breaking]: this changes behavior, auto-close is now determined when accepting the connection, and no longer when terminating the handler thread. This will only affect users that dynamically change copas.autoclose at runtime.
  • Fixed: http requests would not set SNI defaults. Setting fields protocol, options, and verify directly on the http options table is now deprecated. Instead specify sslparams, similar to other SSL/TLS functions.
  • Added: added sempahore:destroy()
  • Added: copas.settimeouts, to set separate timeouts for connect, send, receive
  • Added: queue class, see module "copas.queue"
  • Added: names for sockets and coroutines:
    • copas.addserver() has a 4th argument; name, to name the server socket
    • copas.addnamedthread() is new and identical to copas.addthread(), but also accepts a name
    • copas.setsocketname(), copas.getsocketname(), copas.setthreadname(), copas.getthreadname() added to manage names
    • copas.debug.start() and copas.debug.end() to enable debug logging for the scheduler itself.
    • copas.debug.socket() to enable debug logging for socket methods (experimental).
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!