slact/lua-resty-sse

lua-resty-sse

Lua Server Side Events client cosocket driver for OpenResty / ngx_lua.

Status

This library is still under active development and is considered production ready.

Synopsis

lua_package_path "/path/to/lua-resty-sse/lib/?.lua;;";

server {

  location /simpleinterface {
    resolver 8.8.8.8;  # Google open DNS server for an example

    content_by_lua_block {

      local SSE = require "resty.sse"

      local headers = {
        ["X-Some-Header-Field"] = "foobar"
      }
      local sse = SSE.new("http://some-pub-sub-server.com/subscriber", headers) --header table is optional
      --never fails, always returns new sse 'object'

      --explicitly calling :connect() is optional. SSE will connect as needed
      local ok, err = sse:connect()
      if not ok then 
        ngx.say("SSE failed: ", err)
        return
      end

      --message processing loop 
      for evt in sse:events() do
        ngx.say("SSE id:", evt.id or "")
        ngx.say("SSE event-type:", evt.type)
        ngx.say("SSE data:", evt.data)
      end
      
      --why did we exit the message processing loop?
      if sse.error then
        ngx.say("SSE error:", sse.error)
      end
  }
}

API

SSE.new(url, headers)

  local SSE = require "resty.sse"
  local sse_client = SSE.new("http://sse_server.example/sse_url")

return new sse object, ready to connect to url with optional headers table

sse:connect()

  local res, err = sse_client:connect()

attempt to connect to SSE server. return true on success, nil, error on failure.

It is not necessary to call this function explicitly, the sse client will attempt to connect() as needed.

sse:close()

close the connection

sse.error

last error string from running the sse client, or nil when running without errors

sse:events()

for-loop iterator to receive SSE events:

for evt in sse:events() do
  --handle evt
end

--why did we exit the loop?
if sse.error then
  --handle error stuff
end

sse.connect_timeout

max time to connect to SSE server, in milliseconds. Default is 5000

sse.readline_timeout

max time to wait until retrying to read a line from the sse socket, in milliseconds. Should be really large for best efficiency.

Default is 10 days.