Copas - Coroutine Oriented Portable Asynchronous Services for Lua

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. For concurrent programming Copas provides timers, locks, semaphores, queues, and futures.

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

## Status

Current version is 4.12.0 and was developed for Lua 5.1 to 5.5.

## 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.12.0 [15/Aug/2026]
  - Fix: a 0-byte `receive(0)` on a TCP/SSL socket was treated like a normal read and queued the caller on `select`, blocking until more data arrived even though nothing was needed. Per POSIX, a 0-byte read on a stream socket is a no-op; it now returns `""` immediately (#223).
  - Fix: `copas.http` included the URL fragment in the request line sent to the origin server (and, in proxy mode, to the proxy). Fragments are client-side only and must never be transmitted on the wire; a fragment containing sensitive data (e.g. an OAuth callback token) was disclosed to the server and to proxy infrastructure/logs (#220).
  - Fix: `sock:dohandshake()` returned `nil + err` on a handshake timeout instead of throwing like every other failure path. A timed-out handshake could leave a connection running without the intended TLS configuration instead of aborting it; it now throws consistently on a failure (#189).
  - Fix: `copas.http` reused the SNI server name from the first request of a redirect chain for every subsequent hop, so a redirect to a different host still sent the original host's name in the TLS handshake instead of the new target's. This also applied to an explicitly caller-supplied SNI name, which is now cleared on redirect so it no longer follows the chain to unrelated hosts.
  - Fix: `copas.http` sent a redirect target's literal IP address as the TLS SNI name when no hostname was available. IP literals are not valid SNI names per RFC 6066; the SNI extension is now omitted entirely for such requests instead of sending a bogus name.
  - Fix: a recurring timer that cancelled and immediately re-armed itself from within its own callback leaked the old (cancelled) coroutine into the sleeping heap. The old coroutine would sit there for its full delay (#213).
  - Fix: TLS `sslparams` tables that didn't contain the current `wrap`/`sni` keys (e.g. an empty table, or one with misspelled keys) were misidentified and silently ended up disabling TLS, producing a plaintext connection with no error. Such tables are now passed through to LuaSec, which validates and errors on them (#211).
  - Fix: a socket read/write/connect timeout left a stale entry in that socket's wait queue. If the socket was reused afterwards (e.g. returned to a pool), a later real waiter could queue up behind the stale entry and never get woken. Only a single waiter per direction is now allowed; a conflicting second waiter gets an immediate "already in progress" error instead of being silently abandoned (#209).
  - Fix: `timer:cancel()` could abandon an already in-flight callback instead of letting it complete (#207).
  - Fix: several accounting bugs in `copas.semaphore`: `take()` and `give()` didn't validate their amount, so negative, NaN, or infinite values could corrupt or unbound the internal count; `destroy()` only released up to `max` queued waiters instead of all of them; and `get_wait()` counted waiters that had already been cancelled (#205).
  - Added `semaphore:release_all()` to release every waiter past `max` (#205).
  - Fix: `copas.future` completion was capped at 9999 waiters; the cap has been removed (#204).
  - Fix: `copas.lock:get()` with a zero timeout that failed to acquire immediately still queued the caller, which then waited forever with nothing left to time it out (#202).
  - Fix: `copas.lock` and `copas.semaphore` could deadlock or leak resources when a queued waiter was cancelled externally (e.g. via `copas.removethread()` or `future:cancel()`) before being resumed -- `lock:release()` could hand ownership to a coroutine that would never run, and `semaphore:give()` could deduct resources for a waiter that would never consume them. `copas.wakeup()` now reports whether it actually woke a coroutine, so callers can skip stale entries instead (#200).
  - Fix: `copas.http` silently fell back to plain HTTP when given a URL with an unknown/unrecognized scheme, instead of erroring (#195).
Copas 4.11.0 [11/Jun/2026]
  - Feat: added `copas.cancelall()`. It cancels pending work to force-exit the loop. Intended use is for testing, to force a loop exit, even if a test fails.
  - Fix: when a socket timeout occurs, the registers weren't properly cleaned. This caused a memory leak. Fix by @haoxianhan in #186.
Copas 4.10.0 [27/Mar/2026]
  - Feat: added `copas.future` class. Wraps a thread in a future, allowing other threads to wait for its result via `future:get()` or poll with `future:try()`. Errors in the task are propagated to callers. Pending tasks can be cancelled with `future:cancel()`.
  - Deps: bump LuaSocket to 3.x release.
Copas 4.9.0 [11/Mar/2026]
  - Feat: `copas.pause()` and `copas.pauseforever()` now return the actual time slept, in case they got woken up early, and to return a truthy success value.
  - Fix: the `lock` and `semaphore` classes now use the proper coxpcall version of `coroutine.running` in case of Lua 5.1, which could cause rare race-conditions.
Copas 4.8.0 [13/Mar/2025]
  - 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.addthread() added
Copas 1.0 [17/May/2005]
  - copas.step() added
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!