Add readme

Author: bcomnes

README.md

@@ -8,6 +8,56 @@ npm install random-access-http
 
 [![Build Status](https://travis-ci.org/bcomnes/random-access-http.svg?branch=master)](https://travis-ci.org/bcomnes/random-access-http)
 
+## Why?
+
+Peers in a distributed system tend to come and go over a short period of time in many common p2p scenarios, especially when you are giving away a file without incentivizing the swarm to seed the file for a long time.  There are also an abundance of free cloud hosts that let you host large files over http.
+
+This module provides you random access to a file hosted over http so that it can be used by a client in a distributed system (such as hypercore or hyperdrive) to acquire parts of the file for itself and the other peers in the swarm.
+
+## Usage
+
+```js
+var randomAccessHttp = require('random-access-http')
+
+var file = randomAccessHttp('http://example.com/somefile.mp4')
+
+// Read 10 bytes at an offset of 5
+file.read(5, 10, function(err, buffer) {
+  console.log(buffer)
+  file.close(function() {
+    console.log('http keepalive agents and sockets destroyed')
+  })
+})
+```
+
+file will use a keepalive agent to reduce the number http requests needed for the session.  When you are done you should call `file.close()` to destroy the agent.
+
+## API
+
+#### `var file = randomAccessFile(url)`
+
+Create a new 'file' that reads from the provided `url`.  The `url` can be either `http` or `https`.
+
+#### `file.write(offset, buffer, [callback])`
+
+Not implemented!  Please let me know if you have opinions on how to implement this.
+
+#### `file.read(offset, length, callback)`
+
+Read a buffer at a specific offset. Callback is called with the buffer read.  Currently this will fail if the server returns byte ranges different than what is requested.  PRs welcome to expand the flexibility of this method to allow for servers that return fat ranges.
+
+#### `file.close([callback])`
+
+Close outstanding http keepalive agent sockets.
+
+#### `file.on('open')`
+
+Emitted when the url has been checked to support range requests and the keep-alive agent has been created.
+
+#### `file.on('close')`
+
+Emitted after the keepalive agent and its associated sockets have been destroyed.
+
 ## See Also
 
 - [bittorrent.org/beps/bep_0019 WebSeed - HTTP/FTP Seeding (GetRight style)](http://www.bittorrent.org/beps/bep_0019.html)

index.js

@@ -99,8 +99,9 @@ RandomAccessHTTP.prototype.read = function (offset, length, cb) {
     if (res.statusCode !== 206) return cb(new Error('Bad response: ' + res.statusCode))
     var expectedRange = `bytes ${range}/${self.length}`
     if (res.headers['content-range'] !== expectedRange) return cb(new Error('Server returned unexpected range: ' + res.headers['content-range']))
+    if (offset + length > self.length) return cb(new Error('Could not satisfy length'))
     var concatStream = concat(onBuf)
-    var limiter = limitStream(length + 1)
+    var limiter = limitStream(length + 1) // blow up if we get more data back than needed
 
     pump(res, limiter, concatStream, function (err) {
       if (err) return cb(new Error(`problem while reading stream: ${err}`))