chore: add docs and fix typos

Author: achingbrain

Diff for: .travis.yml

@@ -177,7 +177,7 @@ jobs:
   - stage: test
     name: js-ipfs interface tests - ipfs-client - chrome webworker
     script:
-      - npm run test:interface:coclientre -- $RUN_SINCE -- -- --bail -t webworker --timeout 60000
+      - npm run test:interface:client -- $RUN_SINCE -- -- --bail -t webworker --timeout 60000
 
   - stage: test
     name: js-ipfs interface tests - ipfs-client - firefox

Diff for: packages/interface-ipfs-core/src/add-all.js

@@ -15,7 +15,6 @@ const { isNode } = require('ipfs-utils/src/env')
 const { getDescribe, getIt, expect } = require('./utils/mocha')
 const testTimeout = require('./utils/test-timeout')
 const uint8ArrayFromString = require('uint8arrays/from-string')
-const delay = require('delay')
 
 /** @typedef { import("ipfsd-ctl/src/factory") } Factory */
 /**
@@ -437,6 +436,9 @@ module.exports = (common, options) => {
 
         await new Promise((resolve) => {
           const interval = setInterval(() => {
+            // we've received a progress result, that means we've received some
+            // data from the server before we're done sending data to the server
+            // so the streaming is bidirectional and we can finish up
             if (progressInvoked) {
               clearInterval(interval)
               resolve()
@@ -468,7 +470,7 @@ module.exports = (common, options) => {
 
       await expect(drain(ipfs.addAll(source(), {
         fileImportConcurrency: 1,
-        chunker: 'rabin-2048--50' // invalid chunker parameters
+        chunker: 'rabin-2048--50' // invalid chunker parameters, validated after the stream starts moving
       }))).to.eventually.be.rejectedWith(/Chunker parameter avg must be an integer/)
     })
   })

Diff for: packages/ipfs-client/README.md

@@ -0,0 +1,55 @@
+# ipfs-client
+
+> A client for [ipfs][] daemons
+
+This module combines the [ipfs-grpc-client][] and [ipfs-http-client][] modules to give you a client that is capable of bidirectional streaming in the browser as well as node.
+
+## Install
+
+```console
+$ npm install ipfs-client
+```
+
+## API
+
+The client object created by the `createClient` function supports the [IPFS Core API](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api), see the docs for more.
+
+### `createClient([options])`
+
+### Parameters
+
+None
+
+### Options
+
+An optional object which may have the following keys:
+
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| grpc | `Multiaddr` or `string` or `URL` | `undefined` | The address of a [ipfs-grpc-server][] to connect to |
+| http | `Multiaddr` or `string` or `URL` | `undefined` | The address of a [ipfs-http-server][] to connect to |
+
+### Returns
+
+| Type | Description |
+| -------- | -------- |
+| `object` | An instance of the client |
+
+### Example
+
+```js
+const createClient = require('ipfs-client')
+
+const client = createClient({
+  grpc: '/ipv4/127.0.0.1/tcp/5003/ws',
+  http: '/ipv4/127.0.0.1/tcp/5002/http'
+})
+
+const id = await client.id()
+```
+
+[ipfs]: https://www.npmjs.com/package/ipfs
+[ipfs-grpc-client]: https://www.npmjs.com/package/ipfs-grpc-client
+[ipfs-http-client]: https://www.npmjs.com/package/ipfs-http-client
+[ipfs-grpc-server]: https://www.npmjs.com/package/ipfs-grpc-server
+[ipfs-http-server]: https://www.npmjs.com/package/ipfs-http-server

Diff for: packages/ipfs-grpc-client/README.md

@@ -0,0 +1,57 @@
+# ipfs-grpc-client
+
+> A client for the [ipfs-grpc-server][] module
+
+This module implements part of the [IPFS Core API](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) using      gRPC over websockets to achieve the bidirectional streaming necessary to have full duplex streams running in the browser.
+
+It's not recommended you use this directly, instead use the [ipfs-client](https://www.npmjs.com/package/ipfs-client) to combine this with the [ipfs-http-client](https://www.npmjs.com/package/ipfs-http-client) in order to have HTTP fallback for the missing parts of the API.
+
+## Why?
+
+The [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) and [XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) APIs do not allow for full-duplex streaming, that is, allowing the client to receive bytes from the response while also adding more bytes to the outgoing request.
+
+This limits what we can do in browsers in terms of the API, for example streaming arbitrarily sized payloads or exposing libp2p duplex streams.
+
+gPRC over websockets has no such limitations so allows us to harness the full power of a remote IPFS node in the browser without the need to work around browser behaviour.
+
+## Install
+
+```console
+$ npm install ipfs-grpc-client
+```
+
+## API
+
+### `createClient([options])`
+
+### Parameters
+
+None
+
+### Options
+
+An optional object which may have the following keys:
+
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| url | `Multiaddr` or `string` or `URL` | `undefined` | The address of a [ipfs-grpc-server][] to connect to |
+
+### Returns
+
+| Type | Description |
+| -------- | -------- |
+| `object` | An instance of the client |
+
+### Example
+
+```js
+const createClient = require('ipfs-gprc-client')
+
+const client = createClient({
+  url: '/ipv4/127.0.0.1/tcp/1234/ws'
+})
+
+const id = await client.id()
+```
+
+[ipfs-grpc-server]: https://www.npmjs.com/package/ipfs-grpc-server

Diff for: packages/ipfs-grpc-client/src/core-api/add-all.js

@@ -99,7 +99,7 @@ module.exports = function grpcAddAll (grpc, opts = {}) {
 
     const client = grpc.client(Root.addAll, {
       host: opts.url,
-      debug: true
+      debug: Boolean(process.env.DEBUG)
     })
 
     setTimeout(() => {

Diff for: packages/ipfs-grpc-server/README.md

@@ -2,6 +2,16 @@
 
 > A gRPC server that runs over a websocket
 
+## Why?
+
+[gRPC-web](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md) allows us to form HTTP requests out of gRPC invocations, but the [official implementation](https://github.com/grpc/grpc-web) supports only unary calls and server streaming, which in terms of functionality doesn't give us much over the existing [ipfs-http-client](https://www.npmjs.com/package/ipfs-http-client).
+
+In order to support streaming file uploads with errors, pubsub, etc, bi-directional streaming is required.  We can either use Websockets for this, or use two connections, one for upload and one for download though this involves two requests for every operation and some orchestration on the server side to match one up with the other.
+
+Websockets are a cheaper and simpler way of accomplishing the same thing though sadly the official gRPC implementation has [no plans](https://github.com/grpc/grpc-web/blob/master/doc/streaming-roadmap.md#issues-with-websockets) to implement full-duplex streaming in this way.
+
+This module implements a Websocket proxy for a gRPC-web server.  It's largely a js port of the [grpcwebproxy](https://github.com/improbable-eng/grpc-web/tree/master/go/grpcwebproxy) project from [improbable-eng/grpc-web](https://github.com/improbable-eng/grpc-web).
+
 ## Protocol
 
 Every message sent to or received from the server will have the following format:
@@ -43,3 +53,97 @@ A five-byte field that contains one byte signifying if it's a Header or a Traile
 |--------------|---|
 | 0            | 0: This is a header, 128: This is a footer |
 | 1-4          | A big-endian 32-bit integer that specifies the length of the trailer |
+
+## Handlers
+
+Method handlers come in four flavours - unary, server streaming, client streaming, bidirectional streaming and accept metadata as an argument.
+
+### Metadata
+
+All methods accept metadata which are sent as the equivalent of HTTP headers as part of every request.  These are accepted by the client as options to a given method.
+
+E.g.:
+
+```js
+ipfs.addAll(source, options)
+// `source` will be turned into a message stream
+// `options` will be sent as metadata
+```
+
+### Unary
+
+The simplest case, one request message and one response message.
+
+```javascript
+module.exports = function grpcFunction (ipfs, options = {}) {
+  async function handler (request, metadata) {
+    const response = {
+      //... some fields here
+    }
+
+    return response
+  }
+
+  return handler
+}
+```
+
+### Server streaming
+
+Where the server sends repeated messages.  `sink` is an [it-pushable][].
+
+```javascript
+module.exports = function grpcFunction (ipfs, options = {}) {
+  async function serverStreamingHandler (request, sink, metadata) {
+    sink.push(..)
+    sink.push(..)
+
+    sink.end()
+  }
+
+  return clientStreamingHandler
+}
+```
+
+### Client streaming
+
+Where the client sends repeated messages.  `source` is an [AsyncIterator][].
+
+```javascript
+module.exports = function grpcFunction (ipfs, options = {}) {
+  async function clientStreamingHandler (source, metadata) {
+    const response = {
+      //... some fields here
+    }
+
+    for await (const thing of source) {
+      // do something with `thing`
+    }
+
+    return response
+  }
+
+  return handler
+}
+```
+
+### Bidirectional streaming
+
+The simplest case, one request message and one response message.  `source` is an [AsyncIterator][] and `sink` is an [it-pushable][].
+
+```javascript
+module.exports = function grpcFunction (ipfs, options = {}) {
+  async function bidirectionalHandler (source, sink, metadata) {
+    for await (const thing of source) {
+      sink.push(sink)
+    }
+
+    sink.end()
+  }
+
+  return bidirectionalHandler
+}
+```
+
+[it-pushable]: https://www.npmjs.com/package/it-pushable
+[AsyncIterator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator