Klomp is a simple Stomp messaging client that keeps your sanity intact.
The purpose of Klomp is to be the simplest possible Stomp client. No in-memory buffering of outgoing messages, no fanout subscriptions in-process, no transactions, no complicated messaging patterns. Code simple enough so that when something goes wrong, the problem is obvious.
The API surface area is minimal.
Klomp#subscribe are your
klomp = Klomp.new(["127.0.0.1:61613"], "login" => "mylogin", "passcode" => "mypassword") klomp.publish("/queue/klomp", "sanity") # subscribe with a block that gets invoked for each message klomp.subscribe("/queue/klomp") do |msg| puts msg.body # => sanity end # subscribe with an object that gets #call'd class Klompen def call(msg) puts msg.body end end # replaces previous subscribe block above klomp.subscribe("/queue/klomp", Klompen.new) klomp.unsubscribe("/queue/klomp") # subscribe with custom headers klomp.subscribe("/queue/klomp", Klompen.new, :persistent => :true) klomp.subscribe("/queue/klomp", :persistent => :true) do ... end klomp.disconnect
Connections are established when a
Klomp object is constructed. Connections
can be established in several ways.
# Pass a single string containing host:port klomp = Klomp.new "localhost:61613" # Authentication with 'login' and 'passcode' klomp = Klomp.new "localhost:61613", "login" => "bob", "passcode" => "farmville" # With a stomp:// URL klomp = Klomp.new "stomp://bob:farmville@localhost:61613"
Klomp can be used to load-balance and maintain connections to multiple broker hosts, such that if one broker goes down, the remaining broker(s) will be used. Each broker is expected to provide an identical list of queues. To ensure delivery, all Stomp clients should be connected to all brokers in the load-balancing scenario.
Publish semantics are slightly different than those for subscribe:
- Publish: Klomp will publish each message on a randomly-selected broker.
- Subscribe: each Klomp object subscribes to the provided queues on all hosts.
Load-balanced connections are achieved with an array of servers.
klomp = Klomp.new ["broker-001:61613", "broker-002:61613"] klomp = Klomp.new ["broker-001:61613", "broker-002:61613"], "login" => "bob", "passcode" => "farmville" klomp = Klomp.new ["stomp://bob:farmville@broker-001:61613", "stomp://bob:farmville@broker-002:61613"]
Klomp can use the Stomp 1.1 "virtual host" feature in several ways.
# additional name in colon-separated triple klomp = Klomp.new "virtual-host:localhost:61613" # host option in constructor klomp = Klomp.new "localhost:61613", "host" => "virtual-host" # host query parameter in stomp:// url klomp = Klomp.new "stomp://bob:farmville@localhost:61613?host=virtual-host"
If a Klomp connection experiences errors reading from or writing to its socket, the connection will go into an "offline" state. A sentinel thread will be started that attempts to reconnect periodically at Fibonacci back-off intervals.
Klomp accepts a
Logger object in the constructor options hash.
klomp = Klomp.new "localhost:61613", "logger" => Logger.new($stdout)
Background exceptions that occur in the subscriber thread as well as offline and
reconnect events will be logged at the
warn level, while individual sent and
received message frames will be logged at the
REQUIREMENTS / LIMITATIONS:
- Only supports Stomp 1.1
- Only one subscription per queue per Klomp
- Only one handler object/block per queue. If you want to multi-dispatch a message, write your own dispatcher.
- Only supports the following frames:
- CONNECT/CONNECTED (initial handshake)
- Not supported:
- ack/receipt headers
The MIT License
Copyright (C) 2012 LivingSocial
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.