Tiny SSE

View on Github

A programmable server for Server-Sent Events (SSE)

Features

• Flexible Message Handling – Filter, modify, redirect, and replay messages dynamically.
• Reliable Connections – Track subscribers, support reconnections, and maintain session state.
• Secure Access Control – Enforce authentication, authorization, and event-based restrictions.
• Customizable Behavior – Use hooks to modify messages and manage subscriptions programmatically.

A Whirlwind Tour

Make a Lua script script.lua and run the server

tinysse --script script.lua

-- The `uuid` package is built-in to the Tiny SSE server
local uuid = require "uuid"

-- A message is published
function publish(pub)
  -- Set a unique ID on the publish request.
  -- This can later be referenced in the `message(pub, sub)`
  -- function to correlate the publish request with message
  -- delivery to subscribers
  pub.id = uuid()

  -- We can override the data in the SSE message
  pub.msg.data = "Hello, Universe!"

  -- If the publisher did not set a message ID, then we can set one here.
  -- This will be the `id: <id>` line in the SSE message.
  if not pub.msg.id then
    pub.msg.id = uuid()
  end

  -- We can set a custom event
  pub.msg.event = "custom-event"

  -- Comments too
  pub.msg.comment = {"This is a comment", "Another comment!"}

  -- Return the pub request to the server or it
  -- will be rejected and not delivered to any subscribers
  return pub
end

-- A new subscriber connects
function subscribe(sub)
  -- Set a unique ID on the subscriber.
  sub.id = uuid()

  -- Return the sub request to the server or it
  -- will be rejected and the client will be disconnected immediately
  return sub
end

-- A message is delivered to a subscriber
function message(pub, sub)
  print("Publish ID:", pub.id)
  print("Message ID:", pub.msg.id)
  print("Subscriber ID:", sub.id)

  -- Return the pub request to the server or
  -- the subscriber will not receive the message
  -- (but will still remain connected for subsequent messages)
  return pub
end

-- A subscriber disconnects
function unsubscribe(sub)
  print("Unsubscribed:", sub.id)
end

Refer to the Github repository for more comprehensive examples.