@articulate/squiss-jobs
v0.2.0
Published
SQS-backed job queue
Downloads
23
Readme
squiss-jobs
SQS-backed job queue.
Module API
squiss.create
:: Object -> Object
Parameters
- Object
{ queueUrl, region, ... }
Options object.queueUrl
is your SQS job queue.region
defaults toeu-west-1
. Other options are listed here.
Returns
- Object
queue
A queue instance. See Instance API.
Creates a job queue instance. Note that squiss-jobs
supplies its own handleMessage
function to sqs-consumer
, so any that you provide will be overridden. Also, I recommend creating this once with your config and exporting it as a singleton.
const squiss = require('@articulate/squiss-jobs')
const queue = squiss.create({
queueUrl: process.env.JOBS_URI,
region: process.env.AWS_REGION
})
module.exports = queue
squiss.domainify
:: ((*, Function) -> *) -> (*, Function) -> *
Parameters
- Function
handler(payload, done)
The job handler to wrap in a domain.
Returns
- Function
wrappedHandler(payload, done)
The wrapped job handler.
Avoids uncaught exceptions in async jobs by wrapping the job handler in a domain. The expected handler signature is the same as expected by queue.handle.
const squiss = require('@articulate/squiss-jobs')
const queue = require('../lib/queue')
const foo = (payload, done) => {
console.log(payload)
done()
}
queue.handle('foo', squiss.domainify(foo))
Instance API
queue.handle
:: (String, (*, Function) -> *) -> Object
Parameters
- String
type
The job type. - Function
handler(payload, done)
The handler for that job type.
Returns
- Object
queue
The queue instance.
Registers a job handler for a specific job type. If you register another handler for the same type, it will overwrite the first.
Please note the expected handler signature. The payload
will have already been deserialized with JSON.parse
. To mark the job as complete, simply call done()
. Call done(err)
with an Error
to fail the job and leave it on the queue.
const squiss = require('@articulate/squiss-jobs')
const queue = require('../lib/queue')
const foo = (payload, done) => {
console.log(payload)
done()
}
queue.handle('foo', squiss.domainify(foo))
You may also call queue.handle
multiple times to register several job types.
const jobs = require('require-dir')()
for (var type in jobs) {
queue.handle(type, squiss.domainify(jobs[type]))
}
queue.handleMany
:: (Object) -> Object
Parameters
- Object
jobs
A map of job types to handlers
Returns
- Object
queue
The queue instance.
Similar to queue.handle, but registers multiple jobs in one shot.
const squiss = require('@articulate/squiss-jobs')
const queue = require('../lib/queue')
const foo = (payload, done) => {
console.log(payload)
done()
}
queue.handleMany('foo', { foo: squiss.domainify(foo) }))
You may also call queue.handleMany
multiple times to register several sets of jobs.
queue.on
:: (String, Function) -> Object
Parameters
- String
type
The event type. - Function
listener
The event listener.
Returns
- Object
queue
The queue instance.
Registers event listeners. This is exactly the eventemitter.on function. Events of interest are listed in the sqs-consumer documentation.
const squiss = require('./squiss')
const queue = squiss.create({ /* your config */ })
queue.on('error', console.error)
queue.on('processing_error', console.error)
queue.send
:: (String, *) -> Promise
Parameters
- String
type
The job type. - Any
payload
The job payload.
Returns
- Promise
Resolves with the message sent through
sqs-producer
.
Sends a job into the SQS queue. The payload
will be serialized with JSON.stringify
, and a random id
will be added to the message before sending into the queue. You can recover from enqueueing errors by calling .catch()
on the returned promise.
const queue = require('../lib/queue')
queue.send('foo', { bar: 'baz' }).catch(console.error)
queue.start
:: () -> Object
Parameters
None.
Returns
- Object
queue
The queue instance.
Starts pulling jobs off the queuing and processing them one-at-a-time.
const squiss = require('@articulate/squiss-jobs')
const queue = require('../lib/queue')
const jobs = require('require-dir')()
for (var type in jobs) {
queue.handle(type, squiss.domainify(jobs[type]))
}
queue.start()
queue.stop
:: () -> Object
Parameters
None.
Returns
- Object
queue
The queue instance.
Stops processing jobs. Because every start
needs a stop
. You can always start again with queue.start()
.
CLI
squiss-jobs
ships with an executable script of the same name to help you create a personal dev job queue in SQS. The queue name will be ${project-dirname}-jobs-${aws-username}
, and will have a RedrivePolicy
pushing to a deadletter queue after 3 job failures.
To run the script, you can either install globally with npm i -g squiss-jobs
, or install normally and include it in your npm
scripts in the package.json
. After creating your queues, it will output the job queue URL for you to include in your ENV.
scotts-air:squiss-jobs scott$ squiss-jobs
Copy the following into your .env file:
JOBS_URI=https://queue.amazonaws.com/689543204258/squiss-jobs-jobs-smccormack
Note: The CLI only supports Mac OSX, and requires brew
. It will brew install
both jq
and awscli
if not present, and then allow you to configure your AWS creds before continuing.