1 | # torrent-discovery [![travis][travis-image]][travis-url] [![npm][npm-image]][npm-url] [![downloads][downloads-image]][downloads-url] [![javascript style guide][standard-image]][standard-url]
|
2 |
|
3 | [travis-image]: https://img.shields.io/travis/webtorrent/torrent-discovery/master.svg
|
4 | [travis-url]: https://travis-ci.org/webtorrent/torrent-discovery
|
5 | [npm-image]: https://img.shields.io/npm/v/torrent-discovery.svg
|
6 | [npm-url]: https://npmjs.org/package/torrent-discovery
|
7 | [downloads-image]: https://img.shields.io/npm/dm/torrent-discovery.svg
|
8 | [downloads-url]: https://npmjs.org/package/torrent-discovery
|
9 | [standard-image]: https://img.shields.io/badge/code_style-standard-brightgreen.svg
|
10 | [standard-url]: https://standardjs.com
|
11 |
|
12 | ### Discover BitTorrent and WebTorrent peers
|
13 |
|
14 | This module bundles [bittorrent-dht](https://www.npmjs.com/package/bittorrent-dht),
|
15 | [bittorrent-tracker](https://www.npmjs.com/package/bittorrent-tracker), and [bittorrent-lsd](https://www.npmjs.com/package/bittorrent-lsd) clients and exposes a single API for discovering BitTorrent peers via both discovery methods.
|
16 |
|
17 | ## features
|
18 |
|
19 | - simple API
|
20 | - find peers from trackers, DHT, and LSD
|
21 | - automatically announces, so other peers can discover us
|
22 | - can start finding peers with just an info hash, before full metadata is available
|
23 |
|
24 | This module also **works in the browser** with [browserify](http://browserify.org). In
|
25 | that context, it discovers [WebTorrent](http://webtorrent.io) (WebRTC) peers.
|
26 |
|
27 | ## install
|
28 |
|
29 | ```
|
30 | npm install torrent-discovery
|
31 | ```
|
32 |
|
33 | ## api
|
34 |
|
35 | ### `discovery = new Discovery(opts)`
|
36 |
|
37 | Create a new peer discovery instance. Required options are:
|
38 |
|
39 | ```js
|
40 | {
|
41 | infoHash: '', // as hex string or Buffer
|
42 | peerId: '', // as hex string or Buffer
|
43 | port: 0 // torrent client port (only required in node)
|
44 | }
|
45 | ```
|
46 |
|
47 | Optional options are:
|
48 |
|
49 | ```js
|
50 | {
|
51 | announce: [], // force list of announce urls to use (from magnet uri)
|
52 | dht: true, // use dht? optionally, this can be an `opts` object, or a DHT instance to use (can be reused for multiple torrents)
|
53 | dhtPort: 0, // custom listen port for the DHT instance (not used if DHT instance is given via `opts.dht`)
|
54 | userAgent: '', // User-Agent header for http requests
|
55 | tracker: true, // use trackers? optionally, this can be an `opts` object
|
56 | lsd: true // use lsd?
|
57 | }
|
58 | ```
|
59 |
|
60 | See the documentation for [bittorrent-dht](https://www.npmjs.com/package/bittorrent-dht),
|
61 | [bittorrent-tracker](https://www.npmjs.com/package/bittorrent-tracker) and [bittorrant-lsd](https://www.npmjs.com/package/bittorrent-lsd) for information on what options are available via the `opts` object.
|
62 |
|
63 | **This module automatically handles announcing on intervals, for maximum peer discovery.**
|
64 |
|
65 | ### `discovery.updatePort(port)`
|
66 |
|
67 | When the port that the torrent client is listening on changes, call this method to
|
68 | reannounce to the tracker and DHT with the new port.
|
69 |
|
70 | ### `discovery.complete([opts])`
|
71 |
|
72 | Announce that download has completed (and the client is now a seeder). This is only
|
73 | used by trackers, for statistical purposes. If trackers are not in use, then
|
74 | this method is a no-op.
|
75 |
|
76 | Optional `opts` object with the following options:
|
77 |
|
78 | ```
|
79 | {number=} opts.uploaded
|
80 | {number=} opts.downloaded
|
81 | {number=} opts.numwant
|
82 | {number=} opts.left (if not set, calculated automatically)
|
83 | ```
|
84 |
|
85 | ### `discovery.destroy()`
|
86 |
|
87 | Destroy and cleanup the DHT, tracker, and LSD instances.
|
88 |
|
89 | ### events
|
90 |
|
91 | ### `discovery.on('peer', (peer, source) => {})`
|
92 |
|
93 | Emitted whenever a new peer is discovered. Source is either `'tracker'`, `'dht'`, or `'lsd'` based on peer source.
|
94 |
|
95 | **In node**, `peer` is a string in the form `ip:port`, e.g. `12.34.56.78:4000`.
|
96 |
|
97 | **In the browser**, `peer` is an instance of
|
98 | [`simple-peer`](https://www.npmjs.com/package/simple-peer), a small wrapper around a WebRTC
|
99 | peer connection.
|
100 |
|
101 | ### `discovery.on('dhtAnnounce', () => {})`
|
102 |
|
103 | Emitted whenever an `announce` message has been sent to the DHT.
|
104 |
|
105 | ### `discovery.on('warning', err => {})`
|
106 |
|
107 | Emitted when there is a **non-fatal** DHT, tracker, or LSD error. For example, an
|
108 | inaccessible tracker server would be considered a warning. Useful for logging.
|
109 |
|
110 | ### `discovery.on('error', err => {})`
|
111 |
|
112 | Emitted when there is a fatal, DHT, tracker, or LSD error. This is unrecoverable
|
113 | and the `discovery` object will be destroyed if this event is emitted.
|
114 |
|
115 | ## license
|
116 |
|
117 | MIT. Copyright (c) [Feross Aboukhadijeh](https://feross.org) and [WebTorrent, LLC](https://webtorrent.io).
|