Ratchet Library :: HTTP Protocol Implementation
API  ·  Manual

ratchet.http.client API Reference
ratchet.http.server API Reference

These implementations were written without extensive knowledge or experience in the protocol. Feedback (or patches!) is encouraged!


The HTTP client can be used to send arbitrary commands to an HTTP server, for example to query a REST API or download a file. Once a connection has been established, create a ratchet.http.client object to get started.

-- Initialize "socket"...

local client = ratchet.http.client.new(socket)

Once the object has been created, no more than one query can be performed with it. This is due to a limitation in HTTP/1.0, but allows for greater simplicity. The only required parameter to a command is a URI, but all commands support the passing of additional headers and some also support passing in arbitrary data.

To pass in headers, create a table similar to the following:

local headers = {
    ["X-Fancy-Header"] = {"value1", "value2"},
    ["Content-Length"] = {252},

Here are a few examples of HTTP command queries:

local code, message, headers, data = client:query("GET", "/index.html")
assert(code == "200")
browser:render(headers, data)

local data = "arbitrary data!"
local headers = {
    ["Content-Length"] = {#data},
local code = client:query("PUT", "/api/container/entry", headers, data)
assert(code == "201")


The HTTP server can be used to handle commands from clients. It requires a table be provided whose methods represent the commands supported by the server. Any command received from a client that does not have a corresponding method in the table will be rejected with a 501 code. The ratchet.http.server object does not manage the listening socket or accepting of connections; one object should be instantiated per client connection accepted.

-- Retrieve "socket" from accept() call...

local server = ratchet.http.server.new(socket, handlers)

Once the object has been created, no more than one command can be handled by it. This is due to a limitation in HTTP/1.0, but allows for greater simplicity. All client commands must provide a URI, any command may provide additional headers, and some commands may also provide arbitrary data. Headers will be received and parsed into a table like this one.

Handler Tables

A handler table defines what commands are supported by a server and the logic behind them. The keys of the handler table should be the upper-case of the different commands, with the values being methods (functions whose first parameter is the handler table). Commands are simply arbitrary strings, there is no innate "GET" command unless one is defined by a handler table.

The HTTP response to the client's command is defined by the return values of the command method. Consider a handler method like this:

function handlers:GET(uri, headers, data)
    if uri ~= "/important_stuff.txt" then
        return {
            code = 404,
            message = "Not Found.",
        return {
            code = 200,
            message = "Ok",
            headers = {
                ["Content-Type"] = {"text/plain"},
                ["Content-Length"] = {8},
            data = "secrets!"

The response to the client would be given as "404 Not Found." unless they queried the /important_stuff.txt URI. The response can also include headers (given in table form) and arbitrary data. Passing arbitrary data should follow the standard rules of also providing a "Content-Length" header.

Last modified:  Sun, 17 Aug 2014 09:32:32 -0400
Author:  ian.good