Pdf-bot – Fast implementation of micro services to generate PDF files

• Node.js v6 or later

pdf-bot comes packaged with sensible defaults. At the very minimum you must have a config file in the same folder from which you are executing pdf-bot with a storagePath given. However, in reality what you probably want to do is use the pdf-bot install command to generate a configuration file and then use an alias ALIAS pdf-bot = “pdf-bot -c /home/pdf-bot.config.js”

pdf-bot.config.js

var htmlPdf = require('html-pdf-chrome')

module.exports = {
  api: {
    token: 'crazy-secret'
  },
  generator: {
    completionTrigger: new htmlPdf.CompletionTrigger.Timer(1000) // 1 sec timeout
  },
  storagePath: 'storage'
}Copy the code

$ pdf-bot -c ./pdf-bot.config.js push https://esbenp.github.ioCopy the code

See a full list of the available configuration options.

pdf-bot is meant to be a microservice that runs a server to generate PDFs for you. That usually means you will send requests from your application server to the PDF server to request an url to be generated as a PDF. pdf-bot will manage a queue and retry failed generations. Once a job is successfully generated a path to it will be sent back to your application server.

Let us check out the flow for an app that generates PDF invoices.

1. (App server): An invoice is created ----> Send URL to invoice to pdf-bot server
2. (pdf-bot server): Put the URL in the queue
3. (pdf-bot server): PDF is generated using headless Chrome
4. (pdf-bot server): (if failed try again using 1 min, 3 min, 10 min, 30 min, 60 min delay)
5. (pdf-bot server): Upload PDF to storage (e.g. Amazon S3)
6. (pdf-bot server): Send S3 location of PDF back to the app server
7. (App server): Receive S3 location of PDF -> Check signature sum matches for security
8. (App server): Handle PDF however you see fit (move it, download it, save it etc.)
Copy the code

You can send meta data to the pdf-bot server that will be sent back to the application. This can help you identify what PDF you are receiving.

pdf-bot.config.js

module.exports = {
  api: {
    port: 3000,
    token: 'api-token'
  },
  storage: {
    's3': createS3Config({
      bucket: '',
      accessKeyId: '',
      region: '',
      secretAccessKey: ''
    })
  },
  webhook: {
    secret: '1234',
    url: 'http://localhost:3000/webhooks/pdf'
  }
}Copy the code

As a minimum you should configure an access token for your API. This will be used to authenticate jobs sent to your pdf-bot server. You also need to add a webhook configuration to have pdf notifications sent back to your application server. You should add a secret that will be used to generate a signature used to check that the request has not been tampered with during transfer.

Start your API using

pdf-bot -c ./pdf-bot.config.js api

This will start an express server that listens for new jobs on port 3000.

You can install chrome on Ubuntu using

sudo apt-get update && apt-get install chromium-browser
Copy the code

If you are testing things on OSX or similar, chrome-launcher should be able to find and automatically startup Chrome for you.

api.post('/hook', function (req, res) { var signature = req.get('X-PDF-Signature', 'sha1=') var bodyCrypted = require('crypto') .createHmac('sha1', '12345') .update(JSON.stringify(req.body)) .digest('hex') if (bodyCrypted ! == signature) { res.status(401).send() return } console.log('PDF webhook received', JSON.stringify(req.body)) res.status(204).send() })Copy the code

Let us assume I want to generate a PDF for https://esbenp.github.io. I can add the job using the pdf-bot CLI.

$ pdf-bot -c ./pdf-bot.config.js push https://esbenp.github.io --meta '{"id":1}'Copy the code

Next, if my crontab is not setup to run it automatically I can run it using the shift command

$ pdf-bot -c ./pdf-bot.config.js shiftCopy the code

This will look for the oldest uncompleted job and run it.

Currently pdf-bot comes bundled with build-in support for storing PDFs on Amazon S3.

Feel free to contribute a PR if you want to see other storage plugins in pdf-bot!

var decaySchedule = [ 1000 * 60, // 1 minute 1000 * 60 * 3, // 3 minutes 1000 * 60 * 10, // 10 minutes 1000 * 60 * 30, // 30 minutes 1000 * 60 * 60 // 1 hour ]; module.exports = { // The settings of the API api: { // The port your express.js instance listens to requests from. (default: 3000) port: 3000, // The token used to validate requests to your API. Not required, but 100% recommended. token: 'api-token' }, // html-pdf-chrome generator: { // Triggers that specify when the PDF should be generated completionTrigger: new htmlPdf.CompletionTrigger.Timer(1000), // waits for 1 sec // The port to listen for Chrome (default: 9222) port: 9222 }, queue: { // How frequent should pdf-bot retry failed generations? // (default: 1 min, 3 min, 10 min, 30 min, 60 min) generationRetryStrategy: function(job, retries) { return decaySchedule[retries - 1] ? decaySchedule[retries - 1] : 0 }, // How many times should pdf-bot try to generate a PDF? // (default: 5) generationMaxTries: 5, // How frequent should pdf-bot retry failed webhook pings? // (default: 1 min, 3 min, 10 min, 30 min, 60 min) webhookRetryStrategy: function(job, retries) { return decaySchedule[retries - 1] ? decaySchedule[retries - 1] : 0 }, // How many times should pdf-bot try to ping a webhook? // (default: 5) webhookMaxTries: 5, // In what path should the database be stored? path: 'storage/db/db.json', // pdf-bot uses lowdb. You can pass options to it here. lowDbOptions: { } }, storage: { 's3': createS3Config({ bucket: '', accessKeyId: '', region: '', secretAccessKey: '' }) }, webhook: { // The prefix to add to all pdf-bot headers on the webhook response. // I.e. X-PDF-Transaction and X-PDF-Signature. (default: X-PDF-) headerNamespace: 'X-PDF-', // Extra request options to add to the Webhook ping. requestOptions: { }, // The secret used to generate the hmac-sha1 signature hash. // ! Not required, but should definitely be included! secret: '1234', // The endpoint to send PDF messages to. url: 'http://localhost:3000/webhooks/pdf' } }Copy the code

pdf-bot uses debug for debug messages. You can turn on debugging by setting the environment variable DEBUG=pdf:* like so

DEBUG=pdf:* pdf-bot jobsCopy the code

Please report issues to the issue tracker