Messaging over HTML5 Server-Sent Events

Queues and topics over plain HTTP. No client library required.

EventPost is a lightweight message server built on Micronaut. Clients publish with a POST and receive a stream of Server-Sent Events, so a Java program needs only the JDK's HttpClient and a web page needs only fetch() and EventSource. Queued messages are kept off the Java heap in NoHeapDB, in memory-mapped files, or in Oracle NoSQL Database.

curl -N http://localhost:8080/eventpost/api/topic/stocks
One EventPost :8080/eventpost/api
queue: orders3 waiting
OrderSubmitterPOST
Alice 0 packed
Bob 0 packed
topic: stockslatest only, never stored
StockTickerPOST every 1 s
to everysubscriber
~12,000messages per second with 16 parallel senders
0client libraries: just HTTP and SSE
3places to keep queued messages
An illustration. Throughput measured with 16 sender threads on one machine, every message delivered.
12,500messages per second at best, 16 parallel senders, every one delivered
8 of 8delivered, in order, after five receivers were killed just before the messages were sent
4HTTP endpoints: publish and receive, for queues and for topics
2functions are all a web page needs: one fetch() and one EventSource

Measured with the project's QueueSender and QueueReceiver programs and the sample apps, on one machine. Your numbers depend on message size, network and hardware.

Why Server-Sent Events

Messaging that every browser and every HTTP client already speaks.

Most message brokers bring their own wire protocol, and with it a client library for every language you use, and often a gateway before a web page can join in.

EventPost uses only HTTP. A client sends an ordinary GET and the server keeps the response open, writing a data: line each time there's a message. Browsers support that with the built-in EventSource, which reconnects on its own. Publishing is a POST of data: lines in the same format.

There's no special port and no binary protocol, so it passes through firewalls and proxies like any web request, and a curl command is a working client. See the Server-Sent Events specification for the format.

JMS or AMQP broker
ActiveMQ, RabbitMQ
WebSocket messaging
STOMP over WebSocket
EventPost
Wire protocolThe broker's ownWebSocket frames plus a subprotocolPlain HTTP and SSE
Java clientA client libraryA client libraryjava.net.http, in the JDK
Browser clientThrough a gatewayA JavaScript libraryfetch and EventSource
Through proxiesUsually a separate portNeeds upgrade supportLike any web request
AcknowledgementsYesDepends on the brokerNot yet
Features

Everything in the box

Two kinds of destination over one small server, with storage you choose when it starts.

Queues

  • Exactly one receiverEach message goes to one connected receiver, and several receivers share the work.
  • Messages waitWith no receiver connected, messages stay in the queue until one arrives.
  • Saved before they're queuedEach body is stored before its ID joins the queue, and deleted once it's sent.
  • Safe when a receiver leavesA closed tab or stopped program loses nothing; a message taken for it goes back to the front.

Topics

  • Every subscriberEach connected subscriber gets each update, whether it's a terminal, a service or a web page.
  • The latest messageA subscriber busy with one message gets only the newest of those that follow.
  • Never storedTopics live in memory, so they cost the storage nothing.
  • Built for live stateSend the full current state in each message, and a late subscriber is up to date with the next one.

Plain HTTP API

  • Four endpointsPOST /queue/publish, GET /queue/{name}, and the same two for topics.
  • Batches in one requestEach data: line in a POST body is a separate message.
  • Names created on first useNo setup step: publish or subscribe to a name and it exists.
  • Clear responses200 when stored, 500 if storing failed, 415 for the wrong content type.

Choice of storage

  • NoHeapDB, in memoryThe default. Message bodies are kept off the Java heap, with no database to run.
  • NoHeapDB, persistedMemory-mapped files in ~/JavaOffHeap, reloaded on restart, with the index rebuilt after a crash.
  • Oracle NoSQL DatabaseFor queued messages that belong on a dedicated database server.
  • Fails fastChosen before the server starts, so a bad setting or unreachable database stops it at once.

Clients in any language

  • BrowsersEventSource receives and reconnects on its own; fetch() publishes.
  • JavaA sample client of about 90 lines, comments included, on java.net.http.HttpClient.
  • Anything elseAny language with an HTTP client, or just curl.
  • Serves your pages tooMicronaut can serve web pages from the same origin, or enable CORS for pages hosted elsewhere.

Engine

  • Micronaut 5 on Java 26A single runnable JAR, served by Netty.
  • Paced by the receiverMessages are taken only as fast as each connection asks, so a slow receiver can't drain a queue.
  • Unique, increasing IDsClock-based, never repeated, and seeded from storage on restart.
  • Waiting costs no request threadsDelivery loops run on RxJava's I/O threads.
Quick start

From clone to messages in three steps

EventPost builds with Maven and runs on Java 26. The sample programs need Java 22 or later and nothing else.

  1. Install NoHeapDB

    It isn't on Maven Central, so install it into your local Maven repository first. The build also needs the Oracle NoSQL client JAR; the README shows how.

    git clone https://github.com/ericjbruno/NoHeapDB
    cd NoHeapDB && mvn install -DskipTests
  2. Build and start the server

    It listens on port 8080 and stores queue messages in memory with NoHeapDB, so no database is needed.

    git clone https://github.com/ericjbruno/EventPost
    cd EventPost && mvn package
    java -jar target/EventPost-1.0-SNAPSHOT.jar
  3. Send and receive

    Pick an example on the right: curl, Java, or a web page. Queue and topic names are created on first use.

Terminal
# Terminal 1: receive from the "greetings" queue; the stream stays open
curl -N http://localhost:8080/eventpost/api/queue/greetings

# Terminal 2: send a message. Each data: line is one message
curl -H "Content-Type: text/event-stream" \
     --data-binary $'data: Hello, EventPost!\n\n' \
     "http://localhost:8080/eventpost/api/queue/publish?name=greetings"

# Terminal 1 prints:  data: Hello, EventPost!
# Replace queue with topic in both URLs to try a topic

The full HTTP API, configuration and CORS settings are in the README.

How it works

Store the body, queue the ID, deliver on demand

Queues keep only message IDs in memory. Each body goes to storage, so a queue can hold far more than the heap could, and comes back out only when a receiver takes its ID.

The life of a queue message. On restart, the IDs still in storage are reloaded, so persisted queues pick up where they left off. Topics skip storage entirely and hand the latest message to every subscriber.

  1. Store, then queue

    A message's body is saved before its ID joins the in-memory LinkedBlockingDeque. If it can't be stored, the sender gets an error instead of a 200.

  2. Wait for a live receiver

    Each receiver's handler takes a message only when its connection has asked for one, and checks the Netty channel is still open before taking it and again before sending it.

  3. Send, then delete

    The body is written as an SSE data: event and deleted from storage. A message taken for a receiver that has just gone returns to the front of the queue, keeping its place.

Numbers

Measured, with every message counted

Each run checks that every message sent was received, not just how fast they went.

Queue throughput by sender

Messages per second, one machine. Bars drawn to scale.

One sender, waiting for each response~750
16 parallel senders11,000–12,500

The HTTP round trip, not the storage, sets the pace: NoHeapDB and Oracle NoSQL gave about the same results. Batching several data: lines into one POST also helps, and keeps messages in order.

Delivery when receivers come and go

The tests behind the disconnect fix.

TestDeliveredOrder
Kill 5 receivers, send 8 messages 0.1 s later8 of 8Kept
Close and reload browser tabs, then send 5 shout-outs5 of 5Kept
Two workers share 12 orders6 + 6In turn

Before the fix, each abandoned connection cost one message: the browser test delivered 3 of 5. Persisted NoHeapDB also delivered every message after the server itself was killed with kill -9 mid-run.

Know before you adopt

What EventPost doesn't do yet

No acknowledgements

A queue message is removed once it's written to a receiver's connection. A receiver that disconnects loses nothing, but one that crashes loses the message it was handling and any it hadn't read yet.

No authentication

Any client that can reach the server can publish and receive. Run it on a trusted network, or behind a proxy that handles access control.

Topics aren't durable

Topics deliver the latest message and keep nothing for subscribers who join later. Use a queue when every message must be handled.

Parallel senders don't keep order

Messages from one sender reach a receiver in order, but messages from parallel senders can be stored in any order. Batch from one sender when order matters.