Revise documentation information architecture (#350)

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)
-

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
 

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.

docs/index.md

@@ -0,0 +1 @@
+README.md

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`
+

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)