webstomp-client
This library provides a stomp client for Web browsers and nodejs through Web Sockets.Project Status
This is a fork of the original stomp-websocket re-written in ES6 and incorporate pending pull requests. All credits goes to the original authors: Jeff Mesnil & Jeff Lindsay.Browsers support
Only ES5 compatible modern browsers are supported. If you need a websocket polyfill you can use sockjsnodejs support
As nodejs does not have a WebSocket object like browsers have, you must choose a websocket client and use webstomp.over instead ofwebstomp.client
. Choosing a good client is maybe the most difficult part:Example
npm run example
will open examples in browser and try to connect to RabbitMQ Web-Stomp default Web Sockets url.
node run example/broadcast-node.js
will run a dead simple nodejs example.Use
npm install webstomp-client
Web browser old fashion style
<script type="text/javascript" src="node_modules/webstomp-client/dist/webstomp.min.js"></script>
webstomp
will be a global variable.CommonJS
var webstomp = require('webstomp-client');
ES6 modules
import webstomp from 'webstomp-client';
By default it will load
dist/webstomp.js
, but the npm package.json es6 entry point to the es6 src file if you prefer loading this version.API
Jeff Mesnil stomp-websocket documentation is still a must read even if the API evolved a littlewebstomp
client(url, options)
Uses globalWebSocket
object for you to return a webstomp Client
object.url
Web Sockets endpoint urloptions
- protocols: default to
['v10.stomp', 'v11.stomp', 'v12.stomp']
- binary: default to
false
. See binary section. - heartbeat: default to
{incoming: 10000, outgoing: 10000}
. You can providefalse
to cut it (recommended when the server is a SockJS server) or a definition object. - debug: default to
true
. Will log frame usingconsole.log
over(ws, options)
Takes aWebSocket
alike object instance to return a webstomp Client
object. Allows you to use another WebSocket
object than the default one. 2 cases for this:- you do not want
webstomp.client
to create a default instance for you. - you are in an old browser or nodejs and do not have a global
WebSocket
object thatwebstomp.client
can use.
ws
WebSocket
object instanceoptions
- binary: default to
false
. See binary section. - heartbeat: default to
{incoming: 10000, outgoing: 10000}
. You can providefalse
to cut it (recommended when the server is a SockJS server) or a definition object. - debug: default to
true
. Will log frame usingconsole.log
VERSIONS
supportedVersions()
List all STOMP specifications supported.supportedProtocols()
List all websocket STOMP protocols supported. Useful when creating your ownWebSocket
instance, although optional, protocols is often the second parameter.Client
A client instance can and should be created throughwebstomp.client
or webstomp.over
connect
connect(headers, connectCallback)
connect(headers, connectCallback, errorCallback)
connect(login, passcode, connectCallback)
connect(login, passcode, connectCallback, errorCallback)
connect(login, passcode, connectCallback, errorCallback, host)
disconnect(disconnectCallback, headers={})
send(destination, body='', headers={})
subscribe(destination, callback, headers={})
unsubscribe(id, header={})
It is preferable to unsubscribe from a subscription by callingunsubscribe()
directly on the object returned by client.subscribe()
var subscription = client.subscribe(destination, onmessage);
...
subscription.unsubscribe(headers);
headers
are optionalsonreceive(frame)
If defined on the client instance this function will be called whenever a message is received and in the absence of an explicitsubscribe()
. Some brokers (at least RabbitMQ) will setup an internal routing topology for RPC patterns when a message is sent with certain headers. In RabbitMQ it's called Direct Reply-To
On the client
let onreceive(frame)=>{
console.log('Message received',frame)
}
client.onreceive=onreceive
let headers = {
'reply-to' :'/temp-queue/webstomp',
}
client.send('/topic/public.echo.hi.mom','a message')
On the server (using Amqplib for example)
ch.publish('',raw_message.properties.replyTo,Buffer.from('a reply'))
begin(transaction)
If no transaction ID is passed, one will be created automaticallycommit(transaction)
It is preferable to commit a transaction by callingcommit()
directly on the object returned by client.begin()
:var tx = client.begin(txid);
...
tx.commit();
abort(transaction)
It is preferable to abort a transaction by callingabort()
directly on the object returned by client.begin()
:var tx = client.begin(txid);
...
tx.abort();
ack(messageID, subscription, headers={})
It is preferable to acknowledge a message by callingack()
directly on the message handled by a subscription callback:client.subscribe(destination, (message) => {
// process the message
// acknowledge it
message.ack();
}, {'ack': 'client'}
);
nack(messageID, subscription, headers={})
It is preferable to nack a message by callingnack()
directly on the message handled by a subscription callback:client.subscribe(destination, (message) => {
// process the message
// acknowledge it
message.nack();
}, {'ack': 'client'}
);
debug
Will useconsole.log
by default. Override it to update its behavior.Binary
It is possible to use binary frame instead of string frame over Web Sockets.- client side: set the binary option to true.
- server side: use a compatible websocket server, like with RabbitMQ Web-Stomp since 3.6