STOMPSERVER(1)

💖 STOMPSERVER 💖

okay bestie, gather round, because we're talking about stompserver, which lives in section 1 of the manual (User Commands, if you're keeping score) 💅

---

✨ NAME ✨

stompserver — Stomp protocol messaging server 🦋

---

✨ SYNOPSIS ✨

stompserver [options]

---

✨ DESCRIPTION ✨

It's a Stomp messaging server, no cap. It does FIFO queues backed by file, dbm, memory, or activerecord storage, plus queue monitoring and basic authentication. The way it just… does all of that. Iconic behavior fr fr 🌸

---

✨ OPTIONS ✨

• -C, --config=CONFIGFILE — points at the Configuration File (default: stompserver.conf) 💜
• -p, --port=PORT — change the port (default: 61613) 🎀
• -b, --host=ADDR — change the host (default: localhost) 🌈
• -q, --queuetype=QUEUETYPE — queue type, one of memory|dbm|activerecord|file (default: memory) ✨
• -w, --working_dir=DIR — change the working directory (default: current directory) 🦋
• -s, --storage=DIR — change the storage directory (default: .stompserver, relative to working_dir) 🍓
• -d, --debug — turn on debug messages, we love a chatty server 💀
• -a, --auth — require client authorization 🔐
• -c, --checkpoint=SECONDS — time between checkpointing the queues, in seconds (default: 0) ⏱️
• -h, --help — show this message 🫶

---

✨ QUEUES ✨

ok so stompserver handles basic message queue processing with memory, file, or dbm based queues. Messages are sent and consumed in FIFO order — unless a client error happens, and that should get corrected in the future (their words, not mine, bestie 😭).

Topics? memory-only storage, periodt. You can select activerecord, file or dbm storage and the queues will use that, but topics will only ever be stored in memory. That's just the vibe.

• memory queues are of course the fastest ones, but ngl you shouldn't use them if you want to ensure all messages are delivered 👀
• dbm queues will use berkeleydb if it's available, otherwise dbm or gdbm depending on the platform. Lowkey important: sdbm does not work well with marshalled data. Also note these queues have not been tested in this release 💀
• file based storage: each frame is stored in a single file. The first 8 bytes contain the header length, the next 8 bytes contain the body length, then the headers are stored as a marshalled object followed by the body stored as a string. This storage is currently inefficient because queues are stored separately from messages, which forces a double write for data safety reasons on each message stored. The way that's two writes 😭
• activerecord based storage expects to find a database.yml file in the configuration directory. It should be the most robust backend, but the slowest one. The database must have an ar_messages table, which you can create with the following code — and yes, you are responsible to do so 🫡

ActiveRecord::Schema.define do
  create_table 'ar_messages' do |t|
    t.column 'stomp_id', :string, :null => false
    t.column 'frame', :text, :null => false
  end
end

You can read the frames with this model:

class ArMessage < ActiveRecord::Base
  serialize :frame
end

The ar_message implementation will certainly change in the future, jsyk. It's meant to be easily readable by a Rails application (which could handle the ar_messages table creation with a migration). main character Rails energy tbh 💅

---

✨ ACCESS CONTROL ✨

Basic client authorization is also supported, bestie 🔐 If the -a flag is passed to stompserver on startup, and a .passwd file exists in the run directory, then clients will be required to provide a valid login and passcode. See passwd.example for the password file format 📄✨

---

✨ MONITORING ✨

Queues can be monitored via the monitor queue — this will probably not be supported this way in the future, to avoid polluting the queue namespace (sad, but fair 🥲). If you subscribe to /queue/monitor, you will receive a status message every 5 seconds that displays each queue, it's size, frames enqueued, and frames dequeued. Stats are sent in the same format of stomp headers, so they are easy to parse 🎀 Following is an example of a status message containing stats for 2 queues:

Queue: /queue/client2 size: 0 dequeued: 400 enqueued: 400

Queue: /queue/test size: 50 dequeued: 250 enqueued: 300

---

✨ AUTHOR ✨

stompserver was written by Patrick Hurley <phurley@gmail.com> and Lionel Bouton 👑

This manual page was compiled from the included documentation by Bryan McLellan <btm@loftninjas.org> for the Debian project (and may be used by others). The existing documentation is distributed under the MIT license 🌈

---

ok that's the whole thing, you're so welcome 💖 this page is stompserver, version vibes from July 2009, sitting pretty in section 1 of the manual. go forth and queue, bestie 🦋✨