Module copas-sse.client
Server-Sent-Events client for Copas.
According to this specification.
For usage see the philips-hue.lua example.
Info:
- Copyright: Copyright (c) 2022-2022 Thijs Schreijer
- License: MIT, see LICENSE.
- Author: Thijs Schreijer
Functions
SSE_Client.new (opts) | Creates a new SSE client. |
SSE_Client:close ([timeout]) | Closes the connection. |
SSE_Client:start () | Starts the connection. |
Fields
SSE_Client.log | The LuaLogging compatible logger in use. |
SSE_Client.state | Current connection state (read-only). |
SSE_Client.states | Constants to match SSE_Client.state (read-only). |
SSE_Client.url | The url providing the stream (read-only). |
Functions
- SSE_Client.new (opts)
-
Creates a new SSE client.
The message objects will be pushed to the returned
Queue
instance. The message contains the following fields:"type"
: one of"event"
(incoming data),"comment"
(incoming comment),"connect"
(connection state changed), or"error"
(connection error happened)."id"
: the event id (only for "event" types)."event"
: event name (only for "event" types)."data"
for "event" type: a string, or an array of strings (if optiondata_as_table
was set)."data"
for "comment" type: the comment (string)."data"
for "connect" type: the new connection state (string)"connecting"
,"open"
, or"close"
."data"
for "error" type: the error message (string).
Parameters:
- opts Options table.
- url string the url to connect to for the event stream.
- headers table table of headers to include in the request. (optional)
- last_event_id string The last event ID to pass to the server when initiating the stream.. (optional)
- timeout number the timeout (seconds) to use for connecting to the stream. (default 30)
- next_event_timeout number the timeout (seconds) between 2 succesive events. (default 300)
- reconnect_delay number delay (seconds) before reconnecting after a lost connection. This is the initial setting, it can be overridden by the server if it sends a new value. (default 3)
- event_timeout number or nil timeout (seconds) since last event, after which the socket is closed and reconnection is started. Default is "nil"; no timeout. (optional)
- data_as_table bool return data as an array of lines. (default false)
Returns:
-
new client object
- SSE_Client:close ([timeout])
-
Closes the connection.
Call this function to exit the event stream. This will destroy the message-queue.
If a timeout is provided then the timeout will be passed to
queue:finish(timeout)
, if omitted the queue will be destroyed by callingqueue:stop()
. See Copas documentation for the difference.Parameters:
- timeout number Timeout in seconds. (optional)
Returns:
-
results from
queue:stop
orqueue:finish
. - SSE_Client:start ()
-
Starts the connection.
Will start the http-request (in the background) and keep looping/retrying to read
events. In case of network failures it will automatically reconnect and use the
last_event_id
to resume events.The returned queue (a
copas.queue
instance), will receive incoming events.Returns:
-
event-queue or
nil + "already started"
Fields
- SSE_Client.log
-
The LuaLogging compatible logger in use. If LuaLogging
was loaded then it will use the
defaultLogger()
, otherwise a stub. The logger can be replaced, to customize the logging. - SSE_Client.state
- Current connection state (read-only). See SSE_Client.states.
- SSE_Client.states
-
Constants to match SSE_Client.state (read-only). Eg.
if client.state == SSE_Client.states.CONNECTING then ...
. Values are;CONNECTING
,OPEN
,CLOSED
. - SSE_Client.url
- The url providing the stream (read-only).