Stashback

Stashback is a library for stashing and retrieving callbacks in a decoupled request/response workflow. Its primary use case is to enable code within an http request/response sequence to publish a message to an ESB, e.g. RabbitMQ and wait for a reply.

Installation

npm install stashback

Example Usage (Express)

const rabbitmq = require('./my-rabbitmq-client');
const express = require('express');
const { v4: uuid } = require('uuid');
const stashback = require('stashback')({ timeout: 5000 });

var app = express();

app.get('/greet/:id', function (req, res, next) {
  // Generate a unique id for the callback
  var callbackId = uuid();

  // Define the callback
  var callback = (err, user) => {
    if (err) return next(err);
    res.send(`Hello ${user.name}`);
  };

  // Stash the callback for later execution
  stashback.stash(callbackId, callback, (err) => {
    // An error will occur if you've used a duplicate callbackId.
    if (err) return next(err);

    // Publish the message to the ESB, requesting user for the specified id. Using rabbitmq as an example.
    rabbitmq.publish({ callbackId, userId: req.params.id });
  });
});

app.listen(3000);

function onMessage(message) {
  // When we receive the user response unstash the callback using the callbackId specified in the message
  stashback.unstash(message.callbackId, (err, cb) => {
    // Execute the callback passing it the user object (the callback will be a no-op if something went wrong)
    cb(err, message.user);
  });
}

Callback Expiry

In order to prevent a slow memory leak and to abort slow running requests it's a good idea to configure stashback with a timeout. This can be done globally and for each 'stash' operation. See the api for more details.

Duplicates

Attempting to 'stash' multiple callbacks with the same id results in an error. Attempting to 'unstash' a callback twice (or after it has expired) results in both an error and a no-op callback being returned. i.e.

stashback.unstash('never-stashed-or-expired', function (err, callback) {
  assert.equal(err.message, 'Unknown key: never-stashed-or-expired');
  assert.equal(typeof callback, 'function');
});

API

options

Returns a configured stashback object

| Param | Type | Description | | ---------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | options | Object | | | options.timeout | milliseconds | This timeout is applied to the callback being stashed. If the timeout is exceeded the callback is executed with an error object. | | options.onUnknownKey | function | Function to be executed when instructed to unstash an unknown (or expired) key. It will be invoked with the key and next parameters. | | options.onDuplicateKey | function | Function to be executed when instructed to stash a duplicate key. It will be invoked with the key and next parameters. | | options.onExpiry | function | Function to be executed after expiring a key. It will be invoked with the key and callback to be expired. |

stash

Stashes a callback for subsequent retrieval

| Param | Type | Description | | ---------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | key | String | The callback id | | callback | function | The callback to be stashed | | options | Object | | | options.timeout | milliseconds | This timeout is applied to the callback being stashed. If the timeout is exceeded the callback is executed with an error object. | | options.onDuplicateKey | function | Function to be executed when instructed to stash a duplicate key. It will be invoked with the key and next parameters. | | options.onExpiry | function | Function to be executed after expiring a key. It will be invoked with the key and next parameters. | | next | callback | Callback which will be invoked an the error object |

unstash

Unstashes a callback for execution

| Param | Type | Description | | -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | key | String | The callback id | | options | Object | | | options.onUnknownKey | function | Function to be executed when instructed to unstash an unknown (or expired) key. Will be invoked with the key and next parameters. | | next | callback | Callback which will be invoked with the error object and the unstashed callback (or no-op function if the callback was not found or has expired). |

unstashAll

Unstashes all callbacks for execution

| Param | Type | Description | | ------- | --------------------- | ----------------------------------------------------------------------------------------- | | options | Object | | | next | callback | Callback which will be invoked with the error object and an array of unstashed callbacks. |

stats

Provides statistics

Returns: Object - stats An object containing the number of 'stashed' and 'expired' callbacks