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/stocksfetch() and one EventSourceMeasured with the project's QueueSender and QueueReceiver programs and the sample apps, on one machine. Your numbers depend on message size, network and hardware.
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 protocol | The broker's own | WebSocket frames plus a subprotocol | Plain HTTP and SSE |
| Java client | A client library | A client library | java.net.http, in the JDK |
| Browser client | Through a gateway | A JavaScript library | fetch and EventSource |
| Through proxies | Usually a separate port | Needs upgrade support | Like any web request |
| Acknowledgements | Yes | Depends on the broker | Not yet |
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 endpoints
POST /queue/publish,GET /queue/{name}, and the same two for topics. - Batches in one requestEach
data:line in aPOSTbody is a separate message. - Names created on first useNo setup step: publish or subscribe to a name and it exists.
- Clear responses
200when stored,500if storing failed,415for 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
- Browsers
EventSourcereceives 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.
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.
-
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 -
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 -
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 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
EventPostClient client = new EventPostClient();
// OrderSubmitter: each order is one line of JSON on the "orders" queue
client.publish(EventPostClient.Type.QUEUE, "orders",
"{\"orderId\":\"A-1001\",\"customer\":\"Ada\",\"product\":\"Monitor\",\"quantity\":2}");
// OrderWorker: each order goes to exactly one running worker.
// subscribe() blocks, calling the handler for each message
client.subscribe(EventPostClient.Type.QUEUE, "orders",
order -> System.out.println("Packing " + order));
// Run them with no build step (Java 22 or later):
// java OrderWorker.java Alice
// java OrderWorker.java Bob
// java OrderSubmitter.java 12
HttpClient http = HttpClient.newHttpClient();
// Publish: POST one data: line with the text/event-stream content type
HttpRequest post = HttpRequest.newBuilder()
.uri(URI.create(serverUrl + "/queue/publish?name=orders"))
.header("Content-Type", "text/event-stream")
.POST(HttpRequest.BodyPublishers.ofString("data: " + message + "\n\n"))
.build();
http.send(post, HttpResponse.BodyHandlers.ofString());
// Receive: GET the stream and read it line by line
HttpRequest get = HttpRequest.newBuilder()
.uri(URI.create(serverUrl + "/queue/orders"))
.header("Accept", "text/event-stream")
.build();
HttpResponse<Stream<String>> response = http.send(get, HttpResponse.BodyHandlers.ofLines());
try (Stream<String> lines = response.body()) {
lines.filter(line -> line.startsWith("data:"))
.map(line -> line.substring("data:".length()).trim())
.forEach(handler);
}
const API = `${location.origin}/eventpost/api`;
// Publish one message (a single line of text) to a queue or topic
async function publish(kind, name, message) {
const response = await fetch(`${API}/${kind}/publish?name=${encodeURIComponent(name)}`, {
method: "POST",
headers: { "Content-Type": "text/event-stream" },
body: `data: ${message}\n\n`,
});
if (!response.ok) throw new Error(`Publish failed: HTTP ${response.status}`);
}
// Receive from a queue or topic. EventSource reconnects on its own
function subscribe(kind, name, onMessage) {
const source = new EventSource(`${API}/${kind}/${encodeURIComponent(name)}`);
source.onmessage = (event) => onMessage(JSON.parse(event.data));
return source;
}
// Scorekeeper publishes the match; every Scoreboard shows it
await publish("topic", "match", JSON.stringify(state));
subscribe("topic", "match", showMatch);
# Default: NoHeapDB, in memory. Off-heap, nothing to install
java -jar target/EventPost-1.0-SNAPSHOT.jar
# NoHeapDB, persisted: files in ~/JavaOffHeap, reloaded on restart
java -Deventpost.noheapdb.storage=persisted \
-jar target/EventPost-1.0-SNAPSHOT.jar
# Oracle NoSQL Database: a KV store at 127.0.0.1:5001 named kvstore
java -Deventpost.persistence=oraclekv \
-jar target/EventPost-1.0-SNAPSHOT.jar
# Or use environment variables
export EVENTPOST_PERSISTENCE=noheapdb
export EVENTPOST_NOHEAPDB_STORAGE=persisted
# Serve the browser samples at http://localhost:8080/samples/
java -Dmicronaut.router.static-resources.samples.paths=file:sample-apps \
'-Dmicronaut.router.static-resources.samples.mapping=/samples/**' \
-jar target/EventPost-1.0-SNAPSHOT.jar
The full HTTP API, configuration and CORS settings are in the README.
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.
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 a200.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.
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.
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.
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.
| Test | Delivered | Order |
|---|---|---|
| Kill 5 receivers, send 8 messages 0.1 s later | 8 of 8 | Kept |
| Close and reload browser tabs, then send 5 shout-outs | 5 of 5 | Kept |
| Two workers share 12 orders | 6 + 6 | In 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.
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.
See it running
Start with the repository, then run the samples. Each Java sample is a single source file you run with java File.java; the browser samples are plain HTML and JavaScript.
ericjbruno/EventPost
The server, the sample applications in sample-apps, the article and its figures.
Match Center
A live match scoreboard in plain JavaScript. The Scorekeeper publishes the match to a topic, every Scoreboard shows it, and fans send shout-outs to a queue. MatchFeed.java follows along from Java.
Order processing
A store places orders on a queue and warehouse workers pack them. Each order goes to one worker, and orders wait while no worker is running.
sample-apps / OrderSubmitter.java · OrderWorker.java Java and browser · topicLive stock prices
A ticker publishes every price once a second. A terminal watcher and a web dashboard with sparklines both receive every update.
sample-apps / StockTicker.java · stock-dashboard.html Storage engineNoHeapDB
The off-heap key-value store that keeps EventPost's queued messages out of the Java heap, in memory or in memory-mapped files. Download ZIP.
github.com/ericjbruno/NoHeapDB