README
Pulse Publisher
A collection of utilities for interacting with Mozilla's Pulse.
Requirements
This is tested on and should run on any of node {7, 8, 10}.
Usage
The source-code contains additional comments for each method.
// Exchanges are typically declared in a file like exchanges.js
let Exchanges = require('pulse-publisher');
// Create a new set of exchanges
let exchanges = new Exchanges({
name: 'myservice', // should match serviceName
version: 'v1',
title: 'Title for Exchanges Docs',
description: [
'Description in **markdown**.',
'This will available in reference JSON',
].join(''),
});
// Declare an exchange
exchanges.declare({
exchange: 'test-exchange', // Name-suffix for exchange on RabbitMQ
name: 'testExchange', // Name of exchange in reference JSON (used client libraries)
title: 'Title for Exchange Docs',
description: [
'Description in **markdown**.',
'This will available in reference JSON',
].join(''),
schema: 'name-of-my-schema.yml', // Schema for payload, a file in `schemas/<version>`
messageBuilder: (message) => message, // Build message from arguments given to publisher.testExchange(...)
routingKey: [
// Declaration of elements that makes up the routing key
{
// First element should always be constant 'primary' to be able to identify
// primary routingkey from CC'ed routing keys.
name: 'routingKeyKind', // Identifier used in client libraries
summary: 'Routing key kind hardcoded to primary in primary routing-key',
constant: 'primary',
required: true,
}, {
name: 'someId', // See routingKeyBuilder
summary: 'Brief docs',
required: true || false, // If false, the default value is '_'
maxSize: 22, // Max size is validated when sending
multipleWords: true || false, // If true, the value can contain dots '.'
}, {
// Last element should always be multiple words (and labeled reserved)
// The only way to match it is with a #, hence, we ensure that clients are
// compatible with future routing-keys if add addtional entries in the future.
name: 'reserved',
summary: 'Space reserved for future use.',
multipleWords: true,
maxSize: 1,
}
],
routingKeyBuilder: (message) => {
// Build routingKey from arguments given to publisher.testExchange(...)
// This can return either a string or an object with a key for each
// required property specified in 'routingKey' above.
return {
someId: message.someIdentifier,
};
},
CCBuilder: (message) => {
// Construct CC'ed routingkeys as strings from arguments given to publisher.testExchanges(...)
// By convention they should all be prefixed 'route.', so they don't interfer with the primary
// routing key.
return message.routes.map(r => 'route.' + r);
},
});
// Note you can declare multiple exchanges, by calling exchanges.declare again.
// Nothing happens on AMQP before exchanges.connect() is called. This just declares
// the code in JS.
// Some where in your app, instantiate a publisher
let publisher = await exchanges.connect({
rootUrl: ...,
credentials: {
hostname: ..,
username: ..,
password: ..,
vhost: ..,
},
namespace: '...', // namespace for the pulse exchanges (e.g., `taskcluster-glurble`)
expires: '1 day', // lifetime of the namespace
validator: await schemaset.validator(rootUrl),
monitor: undefined, // optional instance of taskcluster-lib-monitor
});
// Send a message to the declared testExchange
await publisher.testExchange({someIdentifier: '...', routes: [], ...});
Note that all four values for credentials must be included.
Alternately, if using
taskcluster-lib-loader,
create a loader component that calls setup, which will also publish the exchange reference:
publisher: {
requires: ['cfg', 'schemaset', 'monitor'],
setup: ({cfg, validator, monitor}) => exchanges.setup({
rootUrl: cfg.taskcluster.rootUrl,
credentials: cfg.pulse,
namespace: cfg.pulse.namespace,
expires: cfg.pulse.expires,
validator: await schemaset.validator(cft.taskcluster.rootUrl),
publish: cfg.app.publishMetaData,
aws: cfg.aws,
monitor: monitor.prefix('publisher'),
}),
},
Docs can also be generated with exchange.reference(). See the source code docs for details.
Test Support
For testing, it is useful to be able to verify that messages were sent without requiring a real AMQP server.
Pass credentials: {fake: true} to connect or setup to get this behavior.
No AMQP connection will be made, but each call to a message-publishing method
will result in a "fakePublish" message emitted from the publisher with content
{exchange, routingKey, payload, CCs}.
Testing
You'll need to fill a file called user-config.yml with valid keys. There is a user-config-example.yml you can copy over to see which keys are needed. Then it is just a matter of yarn install and yarn test.