README.markdown

Name

lua-resty-websocket - Lua WebSocket implementation for the ngx_lua module

Table of Contents

• Name
• Status
• Description
• Synopsis
• Modules
  • resty.websocket.server
    • Methods
      • new
      • set_timeout
      • send_text
      • send_binary
      • send_ping
      • send_pong
      • send_close
      • send_frame
      • recv_frame
  • resty.websocket.client
    • Methods
      • client:new
      • client:connect
      • client:close
      • client:set_keepalive
      • client:set_timeout
      • client:send_text
      • client:send_binary
      • client:send_ping
      • client:send_pong
      • client:send_close
      • client:send_frame
      • client:recv_frame
  • resty.websocket.protocol
    • Methods
      • protocol.recv_frame
      • protocol.build_frame
      • protocol.send_frame
• Automatic Error Logging
• Limitations
• Installation
• TODO
• Community
  • English Mailing List
  • Chinese Mailing List
• Bugs and Patches
• Author
• Copyright and License
• See Also

Status

This library is considered production ready.

Description

This Lua library implements a WebSocket server and client libraries based on the ngx_lua module.

This Lua library takes advantage of ngx_lua's cosocket API, which ensures 100% nonblocking behavior.

Note that only RFC 6455 is supported. Earlier protocol revisions like "hybi-10", "hybi-07", and "hybi-00" are not and will not be considered.

Synopsis

    local server = require "resty.websocket.server"

    local wb, err = server:new{
        timeout = 5000,  -- in milliseconds
        max_payload_len = 65535,
    }
    if not wb then
        ngx.log(ngx.ERR, "failed to new websocket: ", err)
        return ngx.exit(444)
    end

    local data, typ, err = wb:recv_frame()

    if not data then
        if not string.find(err, "timeout", 1, true) then
            ngx.log(ngx.ERR, "failed to receive a frame: ", err)
            return ngx.exit(444)
        end
    end

    if typ == "close" then
        -- for typ "close", err contains the status code
        local code = err

        -- send a close frame back:

        local bytes, err = wb:send_close(1000, "enough, enough!")
        if not bytes then
            ngx.log(ngx.ERR, "failed to send the close frame: ", err)
            return
        end
        ngx.log(ngx.INFO, "closing with status code ", code, " and message ", data)
        return
    end

    if typ == "ping" then
        -- send a pong frame back:

        local bytes, err = wb:send_pong(data)
        if not bytes then
            ngx.log(ngx.ERR, "failed to send frame: ", err)
            return
        end
    elseif typ == "pong" then
        -- just discard the incoming pong frame

    else
        ngx.log(ngx.INFO, "received a frame of type ", typ, " and payload ", data)
    end

    wb:set_timeout(1000)  -- change the network timeout to 1 second

    bytes, err = wb:send_text("Hello world")
    if not bytes then
        ngx.log(ngx.ERR, "failed to send a text frame: ", err)
        return ngx.exit(444)
    end

    bytes, err = wb:send_binary("blah blah blah...")
    if not bytes then
        ngx.log(ngx.ERR, "failed to send a binary frame: ", err)
        return ngx.exit(444)
    end

    local bytes, err = wb:send_close(1000, "enough, enough!")
    if not bytes then
        ngx.log(ngx.ERR, "failed to send the close frame: ", err)
        return
    end

Back to TOC

Modules

Back to TOC

resty.websocket.server

To load this module, just do this

    local server = require "resty.websocket.server"

Back to TOC

Methods

Back to TOC

new

syntax: wb, err = server:new()

syntax: wb, err = server:new(opts)

Performs the websocket handshake process on the server side and returns a WebSocket server object.

In case of error, it returns nil and a string describing the error.

An optional options table can be specified. The following options are as follows:

• max_payload_len

  Specifies the maximal length of payload allowed when sending and receiving WebSocket frames. Defaults to 65535.

• max_recv_len

  Specifies the maximal length of payload allowed when receiving WebSocket frames. Defaults to the value of max_payload_len.

• max_send_len

  Specifies the maximal length of payload allowed when sending WebSocket frames. Defaults to the value of max_payload_len.

• send_masked

  Specifies whether to send out masked WebSocket frames. When it is true, masked frames are always sent. Default to false.

• timeout

  Specifies the network timeout threshold in milliseconds. You can change this setting later via the set_timeout method call. Note that this timeout setting does not affect the HTTP response header sending process for the websocket handshake; you need to configure the send_timeout directive at the same time.

Back to TOC

set_timeout