About

This project provides Lua modules for Websocket Version 13 conformant clients and servers.

The minified version is only ~10k bytes in size.

Clients are available in three different flavours:

synchronous
coroutine based (copas)
asynchronous (lua-ev)

Servers are available as two different flavours:

coroutine based (copas)
asynchronous (lua-ev)

A webserver is NOT part of lua-websockets. If you are looking for a feature rich webserver framework, have a look at orbit or others. It is no problem to work with a "normal" webserver and lua-websockets side by side (two processes, different ports), since websockets are not subject of the 'Same origin policy'.

Usage

copas echo server

This implements a basic echo server via Websockets protocol. Once you are connected with the server, all messages you send will be returned ('echoed') by the server immediately.

local copas = require'copas'

-- create a copas webserver and start listening
local server = require'websocket'.server.copas.listen
{
  -- listen on port 8080
  port = 8080,
  -- the protocols field holds
  --   key: protocol name
  --   value: callback on new connection
  protocols = {
    -- this callback is called, whenever a new client connects.
    -- ws is a new websocket instance
    echo = function(ws)
      while true do
        local message = ws:receive()
        if message then
           ws:send(message)
        else
           ws:close()
           return
        end
      end
    end
  }
}

-- use the copas loop
copas.loop()

lua-ev echo server

This implements a basic echo server via Websockets protocol. Once you are connected with the server, all messages you send will be returned ('echoed') by the server immediately.

local ev = require'ev'

-- create a copas webserver and start listening
local server = require'websocket'.server.ev.listen
{
  -- listen on port 8080
  port = 8080,
  -- the protocols field holds
  --   key: protocol name
  --   value: callback on new connection
  protocols = {
    -- this callback is called, whenever a new client connects.
    -- ws is a new websocket instance
    echo = function(ws)
      ws:on_message(function(ws,message)
          ws:send(message)
        end)

      -- this is optional
      ws:on_close(function()
          ws:close()
        end)
    end
  }
}

-- use the lua-ev loop
ev.Loop.default:loop()

Running test-server examples

The folder test-server contains two re-implementations of the libwebsocket test-server.c example.

cd test-server
lua test-server-ev.lua

cd test-server
lua test-server-copas.lua

Connect to the from Javascript (e.g. chrome's debugging console) like this:

var echoWs = new WebSocket('ws://127.0.0.1:8002','echo');

Dependencies

The client and server modules depend on:

luasocket
luabitop (if not using Lua 5.2 nor luajit)
luasec
copas (optionally)
lua-ev (optionally)

Install

$ git clone git://github.com/lipp/lua-websockets.git
$ cd lua-websockets
$ luarocks make rockspecs/lua-websockets-scm-1.rockspec

Minify

A squishy file for squish is provided. Creating the minified version (~10k) can be created with:

$ squish --gzip

The minifed version has be to be installed manually though.

Tests

Running tests requires:

docker build .

The first run will take A WHILE.

sharpobject/lua-websockets