as-json.md

as/json

The following is documentation on how to use the as/json implementation to handle encoding and decoding for you

Stability: stable

JSON example

var TChannelJSON = require('tchannel/as/json');
var TChannel = require('tchannel');

var server = TChannel({
    serviceName: 'server'
});
var client = TChannel();
var tchannelJSON = TChannelJSON({
    channel: client
});

var context = {};

tchannelJSON.register(server, 'echo', context, echo);
function echo(context, req, head, body, callback) {
    callback(null, {
        ok: true,
        head: head,
        body: body
    });
}

server.listen(4040, '127.0.0.1', onListening);

function onListening() {
    tchannelJSON.request({
        serviceName: 'server',
        host: '127.0.0.1:4040'
    }).send('echo', {
        head: 'object'
    }, {
        body: 'object'
    }, onResponse);

    function onResponse(err, resp) {
        if (err) {
            console.log('got error', err);
        } else {
            console.log('got resp', resp);
        }

        server.close();
    }
}

var tchannelJSON = TChannelJSON(opts)

TChannelJSON returns a tchannelJSON interface with a .request(), .send() and .register() method used to send call requests and register call request handlers

It can be passed options.

• opts.logParseFailures logParseFailures defaults to true. When it is set to true we will log parse failures to the logger using logger.warn(). If you do not want these log statements you can set the option to false
• opts.channel The channel used to make requests on. This option is required if you want to use the .request() method

tchannelJSON.request(reqOpts).send(endpoint, head, body, cb)

You MUST pass in a channel option to TChannelJSON() to use this method

The .request() method can be used to make an outgoing JSON request.

It returns an object with a .send() method used to send requests

This is just sugar for tchannelJSON.send(...)

tchannelJSON.send(req, endpoint, head, body, callback(err, response))

The .send() method can be used to send to an outgoing request.

First you must use tchannel.request(...) to create an outgoing request to send to.

• endpoint is arg1 as a string for the call request.
• head is an arbitrary value that will be JSON serialized to arg2
• body is an arbitrary value that will be JSON serialized to arg3
• callback takes two args; an error and a response. The response is an object with three fields; ok, head and body.
• response.ok is the ok field from the call response.
• response.head is an arbitrary value that was JSON parsed from arg2
• response.body is an arbitrary value that was JSON parsed from arg3

tchannelJSON.register(tchannel, arg1, ctx, handlerFn)

The .register() method can be used to register a call request handler for a given arg1.

First you must pass in the tchannel you want to register on as well as the arg1, i.e. method name you want to register.

The ctx argument will be passed to your handlerFn and can be used for passing context around without creating closures.

The handlerFn takes five arguments, (ctx, req, head, body, cb(err, response))

• ctx in the handlerFn will be the same ctx you specified in your .register() call. This is useful for passing context around.
• req will be the incoming call request object from tchannel
• head will be an arbitrary object that is JSON parsed from arg2
• body will be an arbitrary object that is JSON parsed from arg3
• cb takes two args; and error and a response. The response is an object with three fields; ok, head, body
• error If you pass an error to the cb we will send a UnexpectedError error frame. This must NOT be used for normal operations. Any error passed to the cb will be considered an unexpected error and will be logged to the logger with logger.error(); i.e. it is a bug.
• response.ok A boolean whether to return a call response that is ok or not.
• response.head An arbitrary value that will be JSON serialized to arg2.
• response.body If response.ok is true then this is an arbitrary value taht will be JSON serialized to arg3. If response.ok is false then this must be an error object that will be serialized to arg3.

If you want to send a not ok call response with arbitrary arg3 response you must turn bossMode on in the TChannelJSON constructor.