Skip to content
This repository has been archived by the owner on Mar 8, 2023. It is now read-only.

Latest commit

 

History

History
231 lines (162 loc) · 8.02 KB

api.markdown

File metadata and controls

231 lines (162 loc) · 8.02 KB

rail API

Table of Contents

Exports

RAIL.plugins

An object holding all built-in plugins.

RAIL.tools

tools.copyHeaders(target, source, defaults)

Copies all properties, headers in this case, from either the source or the defaults to the target.

tools.copy(target, source, defaults, keys)

Copies all properties in keys from either the source or the defaults to the target.

tools.parseURL(url)

Parses an URL into an object with proto, host, port & path.

tools.applyURL(target, url)

Applies proto, host, port & path of an URL to the target.

RAIL.globalClient

A global RAIL object pre-loaded with buffer, json, redirect, cookies, timeout, validate & retry plugin.

RAIL.call(urlOrOptions, responseListener)

A convenience method ala. https.request() using RAIL.globalClient.

See rail.call().

back to top

Class: RAIL

RAIL extends events.EventEmitter.

new RAIL(opt_options)

Creates a new RAIL object.

opt_options

  • {string} proto - One of https, http2 or http, defaults to https
  • {Object} request - holding default request options, see https.request()
  • {Object} * - plugin options
  • {number} maxReplayBuffer The maximum size of a buffered request body, see Class: ReplayBuffer

rail.plugins

An object holding loaded plugins.

rail.proto

The default protocol for all calls.

rail.defaults

The default request options for all calls.

rail.use(name, opt_plugin, opt_options)

Loads a plugin.

  • {string} name The name of the plugin
  • {?function=} opt_plugin A plugin constructor
  • {?Object=} opt_options Optional plugin options

Returns the newly loaded plugin on success, null when the plugin is already loaded and false when no constructor could be located.

rail.use('buffer'/*, opt_options */);        // load built-in plugin
rail.use('my', MyPlugin/*, opt_options */);  // load a custom plugin

rail.call(opt_options, opt_responseListener)

Factory method to create new Call objects, think https.request().

opt_options

When opt_options is a string, it is handled like opt_options.url.

  • {string} proto See new RAIL(opt_options)
  • {string} url When given, the request options are set accordingly
  • {Object} request The request options, see io.js or node.js
  • {Object|boolean} * Any plugin options, configured plugins are auto-loaded
  • {number} maxReplayBuffer The maximum size of a buffered request body, see Class: ReplayBuffer

Notes

  • request options hostname, auth, localAddress & socketPath are not supported
  • request options can also be provided directly besides proto & plugin options

back to top

Class: Call

Call extends stream.Writable.

new Call(rail, opt_options)

Creates a new Call object. Not supposed to be used directly, see rail.call().

call.aborted

A boolean indicating the state of the call.

call.ended

A boolean indicating the state of the writable stream.

call.request

The currently active request stream, if any.

call.response

The currently active response stream, if any.

call.abort()

Immediately abort any request, free the ReplayBuffer and prevent any further requests. Internally request.abort() is called.

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

call.write(chunk, encoding, opt_callback)

See writable.write().

call.end(chunk, encoding, opt_callback)

See writable.end().

Returns this.

Event 'request'

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

function({Object} request)

Event 'abort'

Emitted when a pending connect or active request is aborted.

Event 'response'

Emitted after the response headers have been received.

function({Object} response)

Event 'warn'

function({string} plugin, {string} status, {?string} opt_message)

Event 'error'

back to top

Class: ReplayBuffer

The ReplayBuffer is used to buffer the request body in case of redirects, retries or other use-cases. ReplayBuffer is an EE.

The plugin API offers call.__buffer() to enable this buffer.

new ReplayBuffer(opt_max)

Creates a new ReplayBuffer object.

  • {number} opt_max is the maximum size of all buffered chunks, defaults to 134217728 (128 MiB)

replayBuffer.max

The maximum number of bytes allowed to buffer.

replayBuffer.length

The current number of bytes buffered.

replayBuffer.buffer

A boolean controlling if the buffer is active or in streaming mode.

replayBuffer.ended

A boolean indicating if the buffer accepts more data.

replayBuffer.bailout

A boolean indicating that the buffer size is exceeding the maximum allowed size.

replayBuffer.pipe(writable, opt_callback)

Copy buffered chunks to writable using replayBuffer.replay() and relay all future chunks to writable.

replayBuffer.unpipe(writable)

replayBuffer.push(chunk)

Push a new chunk to the buffer.

Throws an error when the buffer has already ended. Returns false when the buffer size exceeds max, otherwise true.

replayBuffer.replay(writable, callback)

Copy all buffered chunks to writable.

replayBuffer.dump()

Empties the buffer and sets replayBuffer.buffer to false.

replayBuffer.end()

Prevents further addition of chunks and clear the writable stream.

Event: 'end'

Emitted when the buffer is ended. This is the last moment a can modify the request configuration.

back to top