Document request options

docs/index.md

@@ -12,6 +12,7 @@ The following documents are core to tchannel
 
  - [channel](./channel/)
  - [sub-channels](./sub-channels/)
+ - [requests](./requests/)
  - [hyperbahn](./hyperbahn/)
  - [as-thrift](./as-thrift/)
 

docs/requests.md

@@ -0,0 +1,93 @@
+
+# TChannel 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);
+```
+
+The following documents request options.
+
+### `options.parent` or `options.hasNoParent`
+
+The parent request contributes to tracing and clamping the TTL for the outbound
+request (less 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.
+
+### `options.serviceName` (empty)
+
+Indicates the callee service name.
+
+
+### `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.
+
+### `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.
+
+### Other
+
+Not yet documented:
+
+- `options.host` (`''`)
+- `options.checksumType`
+- `options.forwardTrace`
+- `options.trace`
+- `options.tracing`
+- `options.checksum`
+- `options.peer`
+- `options.headers`