typed-request-client

Make HTTP requests using TypedRequest and TypedResponse objects.

Example

var TypedRequestClient = require('typed-request-client');
var Statsd = require('lynx');

var statsd = Statsd({
    host: 'localhost',
    port: 6379
});

var request = TypedRequestClient({
    clientName: 'my-client',
    statsd: statsd
});

var typedRequest = {
    url: 'http://localhost:9000/',
    method: 'GET',
    headers: {},
    body: { userId: '42' }
};

request(typedRequest, {
    requestSchema: someJSONSchemaForRequest,
    responseSchema: someJSONSchemaForResponse,
    resource: '.read'
}, function (err, typedResponse) {
    // if an IO err happened then err

    // typedResponse is a plain object with
    //  - statusCode (number)
    //  - httpVersion (string)
    //  - headers (object)
    //  - body (object)
});

Scope

The typed-request-client module will do the following for you:

• Make HTTP client requests using TypedRequest and TypedResponse interfaces.
• Wrap your HTTP client request in a Prober using the airlock module.
• Validate the TypedRequest and TypedResponse as per the supplied requestSchema and responseSchema.
• Add statsd integration to your service, it will write four different keys, increment:request, timing:request-time, increment:statusCode, timing:total-time

Docs

var makeReq = TypedRequestClient(opts)

To create a TypedRequestClient you must pass a number of options.

When you create one it will return a makeReq function you can call.

opts.clientName

You must pass a clientName into the TypedRequestClient. This will be a name used the statsd events being emitted.

This means you should pick a name you want to use for statsd.

opts.statsd

You must pass in a working statsd client. A statsd client is required since the TypedRequestClient must output statsd.

A valid statsd client has at least two methods:

• statsd.increment(listOfKeys)
• statsd.timing(listsOfKeys, numericTimeDelta)

opts.request

You can optionally pass in a different request function. This will default to mikeal/request from npm if you do not pass one in.

opts.now

You can optionally pass in a different now function. This will default to Date.now() from ES5 if you do not pass one in.

makeReq(typedRequest, options, callback)

The function returned from TypedRequestClient allows you to make typed requests to a server.

The makeReq interface is purposefully low level and kept simple. You must supply all information.

typedRequest

The first argument is the typedRequest you want to make.

type TypedRequest : {
    url: String,
    method?: "OPTIONS" | "GET" | "HEAD" | "POST" | "PUT" |
        "DELETE" | "TRACE" | "PATCH",
    query?: Object<String, String>,
    headers?: Object<String, String>,
    body?: Any
}

A TypedRequest is a plain javascript object that looks similar to a HttpRequest from node core, however it is not a stream.

The url property must be a valid full URI including host & port

The method property must be a valid HTTP method. It will default to the "GET" HTTP method.

The query property is an optional object you can pass. It will be serialized to a string using the querystring module and correctly appended to the url you passed.

If you pass a query ensure that there are no querystring parameters on the url.

The headers property is an optional object of headers. If you pass any headers then they will be used as part of the outgoing HTTP request.

The body property is an optional javascript object to send as part of the HTTP request. If set to valid JSON then the makeReq function will send your value as a JSON encoded string as part of the outgoing HTTP request.

options

The second argument is options and it is required.

type HandlerOptions : {
    requestSchema: JSONSchema,
    responseSchema: JSONSchema,
    resource: String
}

You must specifiy a requestSchema which must be a valid JSONSchema object.

This will be used to validate the typedRequest argument.

Feel free to look at integration tests for an example of a valid requestSchema.

You must specify a responseSchema which must be a valid JSONSchema object.

This will be used to validate the typedResponse argument coming out of the callback from the outgoing HTTP request.

You must specify a resource name which must be a string and will be used when emitting stats events.

callback(error, typedResponse)

The callback to makeReq is the third and final argument. It will get called with an Error or a TypedResponse.

If you get an Error then that's either an IO error or a validation error.

If you get a typedResponse then that will look like:

type TypedResponse : {
    httpVersion: String,
    statusCode: Number,
    headers: Object<String, String>
    body?: Any
}

The typedResponse will have a httpVersion field that is the version of HTTP used.

The typedResponse will have a statusCode field that is the statusCode of response to the outgoing HTTP request.

The typedResponse will have a headers field that is an object of heeaders returned by the outgoing HTTP request.

The body will be the HTTP body of the HTTP response.

Extending

The typed request client as exported by typed-request-client uses a default stack of configurable adapters. These can be customized. Each of these layers is exported by various modules under adapters and can be coposed as a pipeline as exported by make-typed-request/adapt.

var adapt = require('make-typed-request/adapt');
function MyTypedRequestClient(options) {
    return adapt()
        .probing(options)
        .statsdMeasure(options, 'requestTime')
        .statsdReportStatusCode(options)
        .validating(options)
        .statsdReportRequestMade(options)
        .statsdMeasure(options, 'totalTime')
        .statsd(options)
        .valueOf();
}

We use the enchain module to create fluent interfaces based on a collection of adapter methods. This layer can be bypassed.

var TypedRequestClient = require('make-typed-request/make-typed-request');
var Validating = require('make-typed-request/adapters/validating');
var MyTypedRequestClient = Validating(TypedRequestClient, {});

Additional client adapters can be made as functions that accept a client as their first argument and return a decorated client. By convention we pass a shared options object through every adapter, but further arguments may be adapter instance specific.

function MyAdapter(client, options, myArgument) {
    return myClient;
    function myClient(request, shared, respond) {
        // Intercept request
        client(request, shared, onResponse);
        function onResponse(error, response) {
            // Observe progress
            if (error) { respond(error); }
            // Intercept response
            respond(null, response);
        }
    }
}

You can then create your own adapter chain vocabulary with enchain. All of the adapters that this package provides are exported as a single object from typed-request-client/adapters, that you may mix into your own chains.

var enchain = require('enchain');
var adapt = enchain({
    validating: require('make-typed-request/adapters').validating,
    // etc
    myAdapter: require('./my-adapter')
});
var TypedRequestClient = require('make-typed-request/make-typed-request');
var options = {
    requestSchema: someJSONSchemaForRequest,
    responseSchema: someJSONSchemaForResponse
};
var MyTypedRequestClient = adapt(TypedRequestClient)
    .myAdapter(options, myArgument)
    .validating(options)
    .valueOf()

Installation

npm install typed-request-client

Tests

npm test

Contributors

• Raynos
• Kris Kowal

MIT Licenced