BREAKING: Many fixes; all leaks fixed

CHANGELOG.md

@@ -0,0 +1,63 @@
+# WebTorrent Version History
+
+## UNRELEASED
+
+### Added
+
+- `client.listening` property to signal whether TCP server is listening for incoming
+  connections.
+
+- `client.dhtPort` property reflects the actual DHT port when user doesn't specify one
+  (this is parallel to `client.torrentPort` for the TCP torrent listening server)
+
+### Changed
+
+- Merged `Swarm` class into `Torrent` object. Properties on `torrent.swarm` (like
+  `torrent.swarm.wires`) now exist on `torrent` (e.g. `torrent.wires`).
+
+- `torrent.addPeer` can no longer be called before the `infoHash` event has been
+  emitted.
+
+- Remove `torrent.on('listening')` event. Use `client.on('listening')` instead.
+
+- Remove support from `TCPPool` for listening on multiple ports. This was not used by
+  WebTorrent and just added complexity. There is now a single `TCPPool` instance for the
+  whole WebTorrent client.
+
+- Deprecate: Do not use `client.download()` anymore. Use `client.add()` instead.
+
+- Deprecate: Do not use `torrent.swarm` anymore. Use `torrent` instead.
+
+- Only pass `torrent.infoHash` to the Chunk Store constructor, instead of the `Torrent`
+  instance itself, to prevent accidental memory leaks of the `Torrent` object by the
+  store. (Open an issue if you were using other properties. They can be re-added.)
+
+- Non-fatal errors with a single torrent will be emitted at `torrent.on('error')`. You
+  should listen to this event. Previously, all torrent errors were also emitted on
+  `client.on('error')` and handling `torrent.on('error')` was optional. This design is
+  better since now it is possible to distinguish between fatal client errors
+  (`client.on('error')`) when the whole client becomes unusable versus recoverable errors
+  where only a single torrent fails (`torrent.on('error')`) but the client can continue to
+  be used. However, if there is no `torrent.on('error')` event, then the error will be
+  forwarded to `client.on('error')`. This prevents crashing the client when the user
+  only has a listener on the client, but it makes it impossible for them to determine
+  a client error versus a torrent error.
+
+### Fixed
+
+- If `client.get` is passed a `Torrent` instance, it now only returns it if it is present
+  in the client.
+
+- Errors creating a torrent with `client.seed` are now emitted on the returned `torrent`
+  object instead of the client (unless there is no event listeners on
+  `torrent.on('error')` as previously discussed). The torrent object is now also destroyed
+  automatically for the user, as was probably expected.
+
+- Do not return existing torrent object when duplicate torrent is added. Fire an
+  `'error'` event instead.
+
+- Memory leaks of `Torrent` object caused by many internal subclasses of WebTorrent,
+  including `RarityMap`, `TCPPool`, `WebConn`, `Server`, `File`.
+
+- `client.ratio` and `torrent.ratio` are now calculated as `uploaded / received` instead
+  of `uploaded / downloaded`.

docs/api.md

@@ -63,7 +63,7 @@ If `opts` is specified, then the default options (shown below) will be overridde
 
 ## `client.add(torrentId, [opts], [function ontorrent (torrent) {}])`
 
-Start downloading a new torrent. Aliased as `client.download`.
+Start downloading a new torrent.
 
 `torrentId` can be one of:
 
@@ -201,6 +201,10 @@ Magnet URI of the torrent (string).
 Array of all files in the torrent. See documentation for `File` below to learn what
 methods/properties files have.
 
+## `torrent.timeRemaining`
+
+Time remaining for download to complete (in milliseconds).
+
 ## `torrent.received`
 
 Total bytes received from peers (*including* invalid data).
@@ -213,10 +217,6 @@ Total *verified* bytes received from peers.
 
 Total bytes uploaded to peers.
 
-## `torrent.timeRemaining`
-
-Time remaining for download to complete (in milliseconds).
-
 ## `torrent.downloadSpeed`
 
 Torrent download speed, in bytes/sec.
@@ -241,15 +241,19 @@ Number of peers in the torrent swarm.
 
 Torrent download location.
 
-## `torrent.destroy()`
+## `torrent.destroy([callback])`
 
-Alias for `client.remove(torrent)`.
+Alias for `client.remove(torrent)`. If `callback` is provided, it will be called when
+the torrent is fully destroyed, i.e. all open sockets are closed, and the storage is
+closed.
 
 ## `torrent.addPeer(peer)`
 
-Adds a peer to the torrent swarm. Normally, you don't need to call `torrent.addPeer()`.
-WebTorrent will automatically find peers using the tracker servers or DHT. This is just
-for manually adding a peer to the client.
+Add a peer to the torrent swarm. This is advanced functionality. Normally, you should not
+need to call `torrent.addPeer()` manually. WebTorrent will automatically find peers using
+the tracker servers or DHT. This is just for manually adding a peer to the client.
+
+This method should not be called until the `infoHash` event has been emitted.
 
 Returns `true` if peer was added, `false` if peer was blocked by the loaded blocklist.
 
@@ -259,19 +263,28 @@ instance (for WebRTC peers).
 
 ## `torrent.addWebSeed(url)`
 
-Adds a web seed to the torrent swarm. For more information on BitTorrent web seeds, see
+Add a web seed to the torrent swarm. For more information on BitTorrent web seeds, see
 [BEP19](http://www.bittorrent.org/beps/bep_0019.html).
 
 In the browser, web seed servers must have proper CORS (Cross-origin resource sharing)
 headers so that data can be fetched across domain.
 
 The `url` argument is the web seed URL.
 
+## `torrent.removePeer(peer)`
+
+Remove a peer from the torrent swarm. This is advanced functionality. Normally, you should
+not need to call `torrent.removePeer()` manually. WebTorrent will automatically remove
+peers from the torrent swarm when they're slow or don't have pieces that are needed.
+
+The `peer` argument should be an address (i.e. "ip:port" string), a peer id (hex string),
+or `simple-peer` instance.
+
 ## `torrent.select(start, end, [priority], [notify])`
 
-Selects a range of pieces to prioritize starting with `start` and ending with `end` (both inclusive)
-at the given `priority`. `notify` is an optional callback to be called when the selection is updated
-with new data.
+Selects a range of pieces to prioritize starting with `start` and ending with `end` (both
+inclusive) at the given `priority`. `notify` is an optional callback to be called when the
+selection is updated with new data.
 
 ## `torrent.deselect(start, end, priority)`
 
@@ -452,7 +465,7 @@ called once the file is ready. `callback` must be specified, and will be called
 ```js
 file.getBuffer(function (err, buffer) {
   if (err) throw err
-  console.log(buffer) // <Buffer 00 98 00 01 01 00 00 00 50 ae 07 04 01 00 00 00 0a 00 00 00 00 00 00 00 78 ae 07 04 01 00 00 00 05 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ...>
+  console.log(buffer) // <Buffer 00 98 00 01 ...>
 })
 ```
 
@@ -463,9 +476,10 @@ that handles many file types like video (.mp4, .webm, .m4v, etc.), audio (.m4a,
 .wav, etc.), images (.jpg, .gif, .png, etc.), and other file formats (.pdf, .md, .txt,
 etc.).
 
-The file will be fetched from the network with highest priority and streamed into the
-page (if it's video or audio). In some cases, video or audio files will not be streamable
-because they're not in a format that the browser can stream so the file will be fully downloaded before being played. For other non-streamable file types like images and PDFs,
+The file will be fetched from the network with highest priority and streamed into the page
+(if it's video or audio). In some cases, video or audio files will not be streamable
+because they're not in a format that the browser can stream so the file will be fully
+downloaded before being played. For other non-streamable file types like images and PDFs,
 the file will be downloaded then displayed.
 
 `rootElem` is a container element (CSS selector or reference to DOM node) that the content