Service

Services are pluggable components responsible for I/O orchestration usually in a transparent way. For simplicity, they expose a number of standard properties to unify code working with them.

Service helper

A helper function is defined in scaffold.js file, which takes the following arguments:

• io — io object itself.
• name — a unique service name as a string.
• priority — a priority number, usually between 0 and 100. Services with higher priorities have precedence when inspecting an I/O request.
• callback — a callback function, which defines a service. It is described below in details.

The helper function returns io object.

Its algorithm:

• Create a sub-object for a service using name, if it is not there. For example, when creating a service called test, io.test object is going to be created.
• The newly created or existing service object will be populated:
  • A Boolean property isActive is added. Default: false.
  • Following methods will be added, if not present:
    • attach() — adds the service to io, sets isActive to true.
    • detach() — removes the service from io, sets isActive to false.
    • optIn(options) — returns a Boolean value, if a service can process this request.
    • theDefault — a value, which indicates what to do if a request is not specifically marked for the service.

optIn(options) checks options for a flag named name, e.g., a hypothetical test service will look for options.test. If it is there, it is used as a Boolean value to indicate that a request should be processed or bypassed. Otherwise, theDefault is used.

theDefault

If theDefault is a function, it is called with options object, and its result is interpreted as a Boolean value. Otherwise theDefault is a Boolean value.

By default it is the following function:

function defaultOptIn (options) {
  return !options.transport &&
    (!options.method || options.method.toUpperCase() == 'GET');
}

Which means it accepts only GET requests on the default transport (XHR).

Examples:

• If we want to reject all requests, unless specifically marked, we set theDefault to false.

• If we want to accept all requests, unless specifically marked, we set 'theDefault' to true.

• If we want to process only JSON-P requests, we set it to:

  function (options) { return options.transport === 'jsonp'; }

Service callback

A service callback is a function, which takes three parameters:

• options — an options object described in the main API. It describes an I/O request.
• prep — a helper object made with io.prepareRequest() (see the main API).
• level — an index of a service object in io stack. Used to bypass already processed services. Typical use to call io.request with the same parameters, but decreasing level by one.

It should return a promise if an I/O request is successfully processed, or false value, if skipped. In the latter case, io will continue going over services down to individual transports.

Example

Let's construct a dummy trace service:

define(['heya-io/io', 'heya-io/scaffold'], function (io, scaffold) {
  'use strict';

  function serviceHandler (options, prep, level) {
    if (!io.trace.optIn(options)) {
      return null; // reject a request
    }

    // let's ask somebody else to process this request
    var promise = io.request(options, prep, level - 1);
    promise.then(function (result) {
      console.log('REQUEST:', options, 'RESULT:', result);
    });
    return promise;
  }

  return scaffold(io, 'trace', 10, serviceHandler);
});