plugin-api.markdown

rail Plugin API

The RAIL object emits plugin-* events that correspond to different states of a single request inside a call. These events enable plugins to monitor the state of a request, as well as modify the request configuration and when necessary intercept user events on the Call object.

The Call object provides a plugin interface for interception of user events & request management.

All methods for the plugin interface begin with two underscores __.

Table of Contents

• Plugin Events
• Interceptable Events
• Request Management

Example

A class implementing a very simple plugin that emits my event every time a request configuration has been created.

function MyPlugin(rail, options) {
  if (!(this instanceof MyPlugin)) {
    return new MyPlugin(rail, options);
  }
  this._rail = rail;

  this._setup();
}
module.exports = MyPlugin;


MyPlugin.prototype._setup = function() {
  var self = this;
  var rail = this._rail;

  rail.on('plugin-configure', function(call, options) {
    if (options.my) {
      call.emit('my', 'works!');
    }
  });
};

back to top

Plugin Events

These events are emitted on the RAIL object.

Event: 'plugin-call'

Emitted when a new Call object is created.

function({Call} call, {Object} options)

Event: 'plugin-configure'

Emitted after a new configuration has been pushed onto the stack.

function({Call} call, {Object} options)

Event: 'plugin-replay-buffer'

Emitted when a request body buffer has been created. See Class: ReplayBuffer for API of buffer.

function({Call} call, {Object} options, {ReplayBuffer} buffer)

Note: A call to __buffer() is required to enable this event.

Event: 'plugin-request'

Emitted directly after a request object has been created.

function({Call} call, {Object} options, {Request} request)

Event: 'plugin-abort'

Emitted when a pending connect or active request is aborted.

function({Call} call, {Object} options)

Event: 'plugin-response'

Emitted when response headers have been received.

function({Call} call, {Object} options, {Response} response)

back to top

Interceptable Events

Specific events emitted on the Call object can be intercepted. These interceptable events are designed to gain complete control over the request workflow and allow implementing even non-trivial & asynchronous features as a plugin.

As an example for such a non-trivial feature see the redirect plugin.

call.__emit(event, var_args)

Invokes the next pending interceptor or emits the event.

On each call to __emit() only one interceptor is invoked. This way plugins can blackhole responses by not calling __emit(). Creating a new request is obligatory in these cases.

call.__intercept(event, interceptor)

Registers an interceptor for an event.

call.__clear()

Removes all registered interceptors.

Event: 'request'

Emitted after the request object has been created and the ReplayBuffer has been flushed.

function({Call} call, {Object} options, {Object} request)

Event: 'response'

Emitted after the response headers have been received.

function({Call} call, {Object} options, {Object} response)

Event: 'error'

Emitted on an error.

function({Error} err)

back to top

Request Management

All request configurations are stored in call._stack, the current configuration is referenced by call._pointer.

call.__configure(options)

Creates a new request configuration and increments the internal pointer.

The current configuration is always the default, meaning options only needs to contain changes.

Note: Request options are copied, plugin options are referenced when not a primitive.

call.__buffer()

Enable request body buffering.

A plugin-replay-buffer event is emitted when the buffer is created.

Returns the current ReplayBuffer, false otherwise.

call.__request(opt_callback)

Create a request object when no request is pending and a configuration is available. When no configuration is available, a non-interceptable error is emitted.

• {function({?Error} err, {?Object=} request)} opt_callback Called after the request object has been created and the ReplayBuffer has been flushed, a possible connect error is passed to the callback (that error has already been emitted)

Returns true when a request is pending, the newly created request object otherwise.

call.__abort()

Aborts the current request and response, if any.

Note: An interceptable error is very likely to be emitted after a call to __abort().

back to top