From c5b2604a22f1064ffd41c6a72ea24d4f3d4df775 Mon Sep 17 00:00:00 2001 From: Kris Kowal Date: Tue, 21 Mar 2017 11:34:42 -0700 Subject: [PATCH] Revise documentation information architecture --- docs/README.md | 4 +- docs/channel.md | 15 +++-- docs/handlers.md | 43 ++++++++++++ docs/index.md | 30 +-------- docs/requests.md | 155 +++++++++++++++++++++++++++++++++++++++++++ docs/sub-channels.md | 103 ++-------------------------- 6 files changed, 220 insertions(+), 130 deletions(-) create mode 100644 docs/handlers.md mode change 100644 => 120000 docs/index.md create mode 100644 docs/requests.md diff --git a/docs/README.md b/docs/README.md index f281e36c7..9f92d1efa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,8 +12,11 @@ The following documents are core to tchannel - [channel](./channel.md) - [sub-channels](./sub-channels.md) + - [requests](./requests.md) + - [handlers](./handlers.md) - [hyperbahn](./hyperbahn.md) - [as-thrift](./as-thrift.md) + - [as-json](./as-json.md) ## Extra topics @@ -26,4 +29,3 @@ that are available. - [peer-to-peer](./peer-to-peer.md) - [statsd](./statsd.md) - [streaming](./streaming.md) - diff --git a/docs/channel.md b/docs/channel.md index f95295cb7..6e931cbb7 100644 --- a/docs/channel.md +++ b/docs/channel.md @@ -1,11 +1,18 @@ # TChannel -Below we document the interface of tchannel itself; This includes +Below we document the interface of tchannel itself. - - `makeSubChannel` - - `request().send()` - - `register()` + - `TChannel(options)` - `listen()` + - `close()` + + The channel supports additional methods for making subchannels, and off those + sub-channels sending and handling requests. + + - [sub-channels](./sub-channels.md) + - [requests](./requests.md) + - [handlers](./handlers.md) + ## Stability: stable diff --git a/docs/handlers.md b/docs/handlers.md new file mode 100644 index 000000000..59ef8b97a --- /dev/null +++ b/docs/handlers.md @@ -0,0 +1,43 @@ +# TChannel transport handlers + +You can handle TChannel requests by specifying a handler to sub-channel `register()` + + - [sub-channels](./sub-channels.md) + +The TChannel argument schemes wrap handlers, taking responsibility for encoding +and decoding arg2 and arg3. + + - [as-thrift](./as-thrift.md) + - [as-json](./as-json.md) + +### `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](https://github.com/uber/tchannel-node/pull/350) + +You can also pass an arbitrary string `codeMessage` that will +be in the error frame. diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 9bb29687d..000000000 --- a/docs/index.md +++ /dev/null @@ -1,29 +0,0 @@ -# TChannel documentation - -The tchannel documentation is spread out in multiple parts - -## Read the Node GUIDE - -Check out our [GUIDE](./GUIDE/) - -## Core topics - -The following documents are core to tchannel - - - [channel](./channel/) - - [sub-channels](./sub-channels/) - - [hyperbahn](./hyperbahn/) - - [as-thrift](./as-thrift/) - - -## Extra topics - -The following documents give more details for other use cases -that are available. - - - [as-json](./as-json/) - - [errors](./errors/) - - [peer-to-peer](./peer-to-peer/) - - [statsd](./statsd/) - - [streaming](./streaming/) - diff --git a/docs/index.md b/docs/index.md new file mode 120000 index 000000000..42061c01a --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +README.md \ No newline at end of file diff --git a/docs/requests.md b/docs/requests.md new file mode 100644 index 000000000..183bd7ff4 --- /dev/null +++ b/docs/requests.md @@ -0,0 +1,155 @@ +# TChannel transport requests + +You can create and send TChannel requests with TChannel or a sub-channel using +`request` followed by `send`. + +```js +channel +.request(requestOptions) +.send(procedure, headers, body, callback); +``` + + - [sub-channels](./sub-channels.md) + +The TChannel argument schemes call `send` on your behalf, taking responsbility +for the encoding of arg2 and arg3. + + - [as-thrift](./as-thrift.md) + - [as-json](./as-json.md) + +## Stability: stable + +[![stable](http://badges.github.io/stability-badges/dist/stable.svg)](http://github.com/badges/stability-badges) + +### `req.send(arg1, arg2, arg3, cb)` + +Consider using [`as-json`](./as-json.md) or +[`as-thrift`](./as-thrift.md) 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 be `null` or an `Error`. 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 a `Buffer` + - `arg3` is the response body as a `Buffer` + +The following document request options. + +### `options.parent` or `options.hasNoParent` + +The parent request contributes to tracing and clamping the TTL for the outbound +request (minus time spent in process since the parent request was received). +You **must** provide either the parent request or explicitly state that there +is no parent request. + +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` + +### `options.serviceName` (empty) + +The serviceName that you want to send this request to. + + +### `options.headers` + +You can set the transport headers for the outgoing response. There +are multiple headers and they are defined in the +[protocol document](../../docs/protocol.md) + +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.shouldApplicationRetry` (`null`) + +If provided, specifies a function that determines whether TChannel should retry +application errors (as opposed to TChannel transport errors). +Transport errors indicate that the request and response were not completely +sent or received. +Application errors indicate that the request and response were successfully +transported, but the body of the response indicates an application exception. +TChannel does not retry application errors by default. +This function if provided allows TChannel to distinguish retryable requests. +The function receives the exception info and the decoded request and response +body. + +### `options.timeout` (none) + +Specifies the total time a request can spend in-process before timing out. +The deadline/ttl are communicated on the wire to downstream services so they +can shed work for requests that have or are very likely to time out. + +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.timeoutPerAttempt` (none) + +TChannel may retry requests until the timeout. +Each attempt may have a more constrainted timeout, after which it will make +another attempt. + +### `options.retryLimit` + +Determines the maximum number of attempts TChannel may make to fulfill the +request. + +### `options.retryFlags` + +The retry flags is an optional object with three boolean properties: + +- `never` indicates that the request should not be retried under any + circumstance. +- `onConnectionError` indicates that the request should be retried if TChannel + fails to deliver the request due to a connection error. +- `onTimeout` indicates that the request should be retried of the request times + out. + +### `options.streamed` (`false`) + +Indicates that the request and response should be streamed, so all arguments +will be modeled with streams instead of buffers. +Streamed requests will time out only if they fail to receive the *first* frame of +the response before the deadline elapses. +Non-streamed requests time out if they fail to receive the *last* frame of the +response before the deadline elapses. + +### `options.trackPending` + +If specified as false, indicates that the request should not count toward the +pending requests for a peer for purposes of load balancing. + + +### Undocumented request options + +Not yet documented: + +- `options.host` (`''`) +- `options.checksumType` +- `options.forwardTrace` +- `options.trace` +- `options.tracing` +- `options.checksum` +- `options.peer` + diff --git a/docs/sub-channels.md b/docs/sub-channels.md index 9e5fd3b01..6e46414f8 100644 --- a/docs/sub-channels.md +++ b/docs/sub-channels.md @@ -6,6 +6,11 @@ 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. +Read on for details on using a sub channel to send and handle requests. + + - [requests](./requests.md) + - [handlers](./handlers.md) + ## Stability: stable [![stable](http://badges.github.io/stability-badges/dist/stable.svg)](http://github.com/badges/stability-badges) @@ -69,71 +74,7 @@ and make requests based on a hostfile on disk. `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](../../docs/protocol.md) - -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`](./as-json.md) or -[`as-thrift`](./as-thrift.md) 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 be `null` or an `Error`. 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 a `Buffer` - - `arg3` is the response body as a `Buffer` + - [requests](./requests.md) ## `subChannel.register(name, handler)` @@ -145,34 +86,4 @@ 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](../../docs/protocol.md) - -You can also pass an arbitrary string `codeMessage` that will -be in the error frame. + - [requests](./handlers.md)