ladle

A Node.js implementation of RabbitMQ's shovel client.

What it is

RabbitMQ comes with a programmable AMQP client (the Shovel plugin) that picks up messages from one or more source brokers and drops them off in one or more destination brokers. Ladle provides the same functionality as RabbitMQ's shovel plugin, but as a standalone Node.js implementation.

What it does

Ladle acts as a bridge between two or more AMQP brokers. It picks up messages from one or more source brokers and drops off them off at one or more destination brokers.

Features

• [x] Basic message pumping.
• [ ] SSL.
• [ ] Pre-startup declarations.
• [ ] JSON-based configuration.
• [ ] Standalone systemd service.
• [ ] Use it as part of your program.

How to use

As a dependency

If you want to use ladle as part of your own program, you can use npm to install it and automatically add to your list of dependencies:

npm install --save ladle

Then you can copy and paste this example into your code and adjust the configuration as appropriate:

var ladle = require("ladle");
var myLadle = ladle.create({
    ladleName: "test",
    sources: {
        brokers: [ "amqp://user1:user1@host1" ],
        declarations: []
    },
    destinations: {
        brokers: [ "amqp://user2:user2@host2" ],
        declarations: []
    },
    queue: "myWorkQueue",
    publishFields: {
        exchange: "my_direct",
        routingKey: "from_ladle"
    }
});
myLadle.setRunning(true);

This will create and start a ladle named test that will

1. Connect to the AMQP broker running on host1 using the username user1 and password user1 as the credentials.
2. Connect to the AMQP broker running on host2 using the username user2 and password user2 as the credentials.
3. Consume messages from the queue named myWorkQueue on host1.
4. Re-publish messages in the exchange named my_direct with the rouing key from_ladle.

As a standalone application

If you want to use ladle as a standalone application, you can use npm to install it globally instead:

npm install -g ladle

Then you have to create a configuration file at /etc/ladle/ladle.conf. You can use one of the provided example configurations for simpler setup. The file is a JSON document mirroring the configuration you saw above in the usage example. The ladle configuration lets you create one or more ladles at a time.

[ { ladleName: "test",
    sources: {
        brokers: [ "amqp://user1:user1@host1" ],
        declarations: []
    },
    destinations: {
        brokers: [ "amqp://user2:user2@host2" ],
        declarations: []
    },
    queue: "myWorkQueue",
    publishFields: {
        exchange: "my_direct",
        routingKey: "from_ladle"
    } } ]

This creates a ladle just as above.

Ladle configuration

• ladleName the name of the ladle. (required)
• sources the source brokers, ie. where messages are consumed. (required)
  • brokers an array of AMQP URIs in string form. (required)
  • declarations an array of AMQP methods to be run on each broker after the ladle has established a connection to the source brokers. Defaults to none. (optional)
• destinations the destination brokers, ie. where messages are re-published. (required)
  • brokers an array of AMQP URIs in string form. (required)
  • declarations an array of AMQP methods to be run on each broker after the ladle has established a connection to the destination brokers. (optional)
• queue: the name of the message queue to consume messages from. (required)
• prefetchCount: number of messages to prefetch and keep in-flight between brokers. Defaults to 1000. (optional)
• ackMode: How consumed messages are acknowledged. Defaults to onConfirm. (optional)
• publishProperties: Properties set on the basic.properties on each re-published message. (optional)
• addForwardHeaders: If true, an x-ladled header is appended or added to the message. Defaults to false. (Optional)
• publishFields: Fields set on the basic.publish method. By default, messages are re-published using the original exchange name and routing key. (Optional)
• reconnectDelay: the number of seconds to wait before reconnecting. Defaults to 1.5s. (Optional)

How to contribute

Code style

Ladle source code largely follows the Crockford style guide with the following exceptions:

• Line length is extended to 120 characters.
• Semicolon insertion might as well not exist.
• Variables are defined when they're needed, not at the top of a function.

Contributions

Please read the following before you're contributing:

By contributing to this project, you, the contributor, assign the copyright of your contribution, including but not restricted to source code and documentation, to me, Chris Eineke. In return, I grant you a world-wide, non-exclusive, royalty-free and perpetual right to use, copy, modify, communicate and make available to the public (including without limitation via the Internet) and distribute, in each case in an original or modified form, the contribution as you wish. If that hasn't scared you off, fork this repo and create a pull request. If you are contributing code, you must provide a passing unit test or must make appropriate changes to existing unit tests. Don't forget to add yourself to the contributors in package.json.