Sub channels
TChannel supports the notion of sub channels. Whenever you want to implement a serviceName you create a subchannel for it.
Whenever you want to talk to a downstream service; you create a subchannel for it.
Stability: stable
channel.makeSubChannel(options)
Note: Favor using hyperbahnClient.getClientChannel()
for
any creating sub channels if your making requests to hyperbahn
See the hyperbahn documentation on how to create sub channels with hyperbahn
To create a sub channel you call makeSubChannel
on the root
channel.
var channel = TChannel()
var myChannel = channel.makeSubChannel({
serviceName: 'my-service'
});
options.serviceName
The serviceName
for this channel. If this is a serviceName
that you are implementing then you will probably call register()
on the sub channel.
If this is a serviceName
that you want to talk to then you'll
probably call request()
on the sub channel.
options.peers
If this sub channel is used to talk to other services then you
want to pre-populate a peers
list.
In the hyperbahn use case you will use
hyperbahnClient.getClientChannel()
and it will prepopulate the
correct hyperbahn peers.
In the peer to peer use case you will want to specify an array
of host:port
strings for all the other instances you want to
talk to.
If you do not specify a peers
array you must pass a host
option for every outgoing request.
var req = subChannel.request(options)
request()
is used to initiate an outgoing request to another channel.
options.serviceName
The serviceName that you want to send this request to.
options.timeout
You should specify a timeout for this operation. This will default to 100.
This will call your callback with a timeout error if no response was received within the timeout.
options.headers
You can set the transport headers for the outgoing response. There are multiple headers and they are defined in the protocol document
There are two required headers, "cn" the caller name and "as" the arg scheme.
When using the hyperbahn
client and as-thrift
library these
headers will be set for you.
options.parent
When making outgoing requests you must set the parent; the parent is the incoming requests that triggered this outgoing request.
This is mandatory for tracing to work.
options.hasNoParent
Sometimes you do not have a parent
; This is only the case if
you are writing tests or if you are truly the edge HTTP service
that made the first tchannel request.
In these cases you can set hasNoParent
to true
req.send(arg1, arg2, arg3, cb)
Consider using as-json
or
as-thrift
to make send data down
outgoing requests that use json or thrift encoding.
Calling send()
directly is for when you want to deal with
binary buffers.
arg1
is the name of the endpoint you want to call as a string.
arg2
is generally application headers as a Buffer
arg3
is the body of the outgoing request as a Buffer
The cb
gets called with cb(err, res, arg2, arg3)
The callback will either get called with cb(err)
or with
cb(null, resp, arg2, arg3)
err
will either benull
or anError
. This can be an error like a timeout, IO or tchannel error frame.resp
is the incoming response, this can be an OK response or an error from the remote server.resp.ok
will be a boolean, dependening on whether this is an OK response or an application error.arg2
are the application headers as aBuffer
arg3
is the response body as aBuffer
subChannel.register(name, handler)
Consider using as-json
or
as-thrift
to register endpoints
that use json or thrift encoding. Calling register()
directly
is for when you want to deal with binary buffers.
You can call register
to register an named endpoint with
handler
handler(req, res, arg2, arg3)
Your handler will get called with an IncomingRequest
and an
OutgoingResponse
.
You will also receive arg2
and arg3
as buffers.
res.sendOk(arg2, arg3)
To send an ok response you can call sendOk()
on the outgoing
response with two buffers for arg2
and arg3
res.sendNotOk(arg2, arg3)
To send an application error response you can call sendNotOk()
on the outgoing response with two buffers for arg2
and arg3
res.sendError(codeString, codeMessage)
To send an error frame instead of a call response you can call
res.sendError()
.
Valid codeString
values are: Timeout
, Cancelled
, Busy
,
Declined
, UnexpectedError
, BadRequest
, NetworkError
,
UnHealthy
, ProtocolError
For the samentics of the code string please read the protocol document
You can also pass an arbitrary string codeMessage
that will
be in the error frame.