copas-sse

Contents

• Functions
• Fields

Modules

• copas-sse.client

Topics

• CHANGELOG
• LICENSE

Examples

• philips-hue.lua

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 option data_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 calling queue:stop(). See Copas documentation for the difference.

Parameters:

• timeout number Timeout in seconds. (optional)

Returns:

results from queue:stop or queue: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).