An Elixir client for Lightstreamer servers, speaking TLCP 2.5.0 over WebSocket.

Unofficial and vendor-agnostic: this library implements the published TLCP protocol and nothing else. Adapter sets, item naming, field semantics and credential formats are defined by the server you connect to. "Lightstreamer" is a trademark of Lightstreamer Srl; this project is not affiliated with them.

Quick start

Stream live stock quotes from Lightstreamer's public demo server — paste this into iex -S mix:

{:ok, session} =
  Lightstreamer.connect("https://push.lightstreamer.com", adapter_set: "DEMO")

{:ok, sub} =
  Lightstreamer.subscribe(session,
    data_adapter: "QUOTE_ADAPTER",
    items: ["item1", "item2", "item3"],
    fields: ["stock_name", "last_price", "time"]
  )

for _ <- 1..10 do
  receive do
    {:lightstreamer, ^sub, {:update, %Lightstreamer.Update{} = update}} ->
      IO.inspect(update.values, label: update.item)
  end
end

Lightstreamer.close(session)

The first three updates are the snapshot (one full state per item); the rest are live changes as the simulated market moves.

A real consumer is usually a GenServer that owns its subscription and handles the same messages in GenServer.handle_info/2 — updates are plain messages, so there is no callback API to integrate with.

Delivery contract

Each subscription has an owner pid (default: the subscribe/2 caller), which receives:

• {:lightstreamer, sub, {:update, %Lightstreamer.Update{}}} — merged current field state plus the set of fields changed by this event
• {:lightstreamer, sub, {:end_of_snapshot, item}}
• {:lightstreamer, sub, {:overflow, item, lost_count}} — the server dropped lost_count updates for the item (buffer limits)
• {:lightstreamer, sub, {:unsubscribed, reason}} — the subscription is gone; reason is :requested after unsubscribe/2, {:closed, reason} when the session ends, {:unsupported_diff, tag} if the server sent a diff format this library refuses (see below), or {:resubscribe_failed, %Lightstreamer.Error{}} when re-issuing after a reconnect was rejected

Session-level events go to the connect/2 caller (or the :events_to pid):

• {:lightstreamer, session, {:disconnected, reason}}
• {:lightstreamer, session, {:reconnected, session_id}}
• {:lightstreamer, session, {:closed, reason}}

Field values are strings (or nil for wire-null), exactly as delivered — typing and parsing are the consumer's job.

Connection resilience

By default (reconnect: :automatic) a session heals itself: server-driven rebinds are transparent, and on connection loss it rebinds — or re-creates the session and re-issues every subscription — with capped exponential backoff. After a re-create, each item delivers a fresh snapshot (snapshot?: true) before live updates resume, and a gap in updates is possible across the reconnect. Watch the session-level events above if you need to react to that. Bad credentials are never retried.

Architecture

A pure protocol codec (Lightstreamer.Protocol, Lightstreamer.Protocol.Frame, Lightstreamer.Protocol.Update) with no processes or sockets, driven by a Lightstreamer.Session state machine that owns one WebSocket via the Lightstreamer.Transport behaviour (Lightstreamer.Transport.MintWs in production). See the Internals module group.

The library starts no processes of its own and reads no application config — every session is created by your code with per-call options, and can sit in your supervision tree via child_spec/1:

children = [
  {Lightstreamer, url: "https://push.lightstreamer.com", adapter_set: "DEMO"}
]