Merge #29: Make missing package readmes

1801dfd docs: make missing package readmes (Cameron Garnham)

Pull request description:

  closes #28

ACKs for top commit:
  da2ce7:
    ACK 1801dfd

Tree-SHA512: 088beaf26347ede866869cad6ab7254faa94015cca0fc7925505cfa0b0b7a3c909f9224628438c7a836469a9b9aefa3fe2517700c4c32395a20df74c92ca5ed8

Cargo.toml

@@ -31,7 +31,6 @@ homepage = "https://github.com/torrust/bittorrent-infrastructure-project"
 keywords = ["bittorrent"]
 license = "Apache-2.0"
 publish = false # until we decide where to publish.
-readme = "README.md"
 repository = "https://github.com/torrust/bittorrent-infrastructure-project"
 rust-version = "1.71"
 version = "1.0.0-alpha.1"

examples/README.md

@@ -1,5 +1,8 @@
-To see help messages for the examples (and then run them):
-`cd <example> && cargo run --release -- --help`
+# Command Line Example Applications
+These applications are for the demonstration of the bittorrent infrastructure project api:
 
-### Simple Torrent
-Primitive torrent client that can connect to a single peer and upload/download pieces from that peer.
+### [Simple Torrent](./simple_torrent/)
+A primitive torrent client that can connect to a single peer and upload/download pieces from that peer.
+
+### [Get Metadata](./get_metadata/)
+A simple application that downloads a torrent file form a given info-hash.

examples/get_metadata/Cargo.toml

@@ -1,6 +1,7 @@
 [package]
 name = "get_metadata"
 description = "Examples For bip-rs"
+readme = "README.md"
 
 authors.workspace = true
 categories.workspace = true
@@ -9,7 +10,6 @@ edition.workspace = true
 homepage.workspace = true
 license.workspace = true
 publish.workspace = true
-readme.workspace = true
 repository.workspace = true
 version.workspace = true
 

examples/get_metadata/README.md

@@ -0,0 +1,2 @@
+### Get Metadata
+Download torrent file from info hash.

examples/simple_torrent/Cargo.toml

@@ -1,6 +1,7 @@
 [package]
 name = "simple_torrent"
 description = "Examples For bip-rs"
+readme = "README.md"
 
 authors.workspace = true
 categories.workspace = true
@@ -9,7 +10,7 @@ edition.workspace = true
 homepage.workspace = true
 license.workspace = true
 publish.workspace = true
-readme.workspace = true
+
 repository.workspace = true
 version.workspace = true
 

examples/simple_torrent/README.md

@@ -0,0 +1,2 @@
+### Simple Torrent
+Primitive torrent client that can connect to a single peer and upload/download pieces from that peer.

packages/README.md

@@ -0,0 +1,41 @@
+# Packages
+These packages together are the _BitTorrent Infrastructure Project_:
+
+### [Bencode (bencode)](./bencode/)
+A library for parsing and converting bencoded data.
+
+### [Distributed Hash Table (dht)](./dht/)
+A library implementing the Bittorrent Mainline Distributed Hash Table.
+
+### [Disk (disk)](./disk/)
+A library providing the ```FileSystem``` interface, for managing pieces of files.
+
+### [Handshake (handshake)](./handshake/)
+A library providing a trait for custom handshake implementations and it's implementation for the standard bittorrent handshake.
+
+### [Http Tracker (htracker)](./htracker/) (not implemented)
+A library assisting communication with bittorrent HTTP trackers.
+
+### [Local Peer Discovery (lpd)](./lpd/) (not implemented)
+A library providing a implementation of the bittorrent Local Peer/Service Discovery mechanism.
+
+### [Magnet (magnet)](./magnet/)
+A library for parsing and constructing magnet links.
+
+### [Metainfo (metainfo)](./metainfo/)
+A library for Parsing and building of bittorrent metainfo files.
+
+### [Peer (peer)](./peer/)
+A library assisting communication between with bittorrent peers via the peer wire protocol.
+
+### [Select (select)](./select/)
+A library providing the _Bittorrent Infrastructure Project_ piece selection module.
+
+### [Utility (util)](./util/)
+A library providing a set of utilities used by the _Bittorrent Infrastructure Project_.
+
+### [uTorrent Transport Protocol (utp)](./utp/) (not implemented)
+A library implementing the _uTorrent Transport Protocol_.
+
+### [UDP Tracker (utracker)](./utracker/)
+A library for parsing and writing UDP tracker messages.

packages/bencode/Cargo.toml

@@ -2,6 +2,7 @@
 name = "bencode"
 description = "Efficient decoding and encoding for bencode."
 keywords = ["bencode"]
+readme = "README.md"
 
 authors.workspace = true
 categories.workspace = true
@@ -10,7 +11,7 @@ edition.workspace = true
 homepage.workspace = true
 license.workspace = true
 publish.workspace = true
-readme.workspace = true
+
 repository.workspace = true
 version.workspace = true
 

packages/bencode/README.md

@@ -0,0 +1,4 @@
+# Bencode
+This library allows for the creation and parsing of bencode encodings.
+
+Bencode is the binary encoding used throughout bittorrent technologies from metainfo files to DHT messages. Bencode types include integers, byte arrays, lists, and dictionaries, of which the last two can hold any bencode type (they could be recursively constructed).

packages/dht/Cargo.toml

@@ -2,6 +2,7 @@
 name = "dht"
 description = "Implementation of the bittorrent mainline DHT"
 keywords = ["dht", "distributed", "hash", "mainline", "bittorrent"]
+readme = "README.md"
 
 authors.workspace = true
 categories.workspace = true
@@ -10,7 +11,7 @@ edition.workspace = true
 homepage.workspace = true
 license.workspace = true
 publish.workspace = true
-readme.workspace = true
+
 repository.workspace = true
 version.workspace = true
 

packages/disk/Cargo.toml

@@ -2,6 +2,7 @@
 name = "disk"
 description = "Bittorrent Infrastructure Project Disk Module"
 keywords = ["filesystem", "fs", "disk"]
+readme = "README.md"
 
 authors.workspace = true
 categories.workspace = true
@@ -10,7 +11,7 @@ edition.workspace = true
 homepage.workspace = true
 license.workspace = true
 publish.workspace = true
-readme.workspace = true
+
 repository.workspace = true
 version.workspace = true
 

packages/disk/README.md

@@ -0,0 +1,6 @@
+# Disk
+This disk management library is all about storing/loading pieces to/from any object implementing the ```FileSystem``` interface.
+
+Allowing torrent storage could to be transparently sent to disk, stored in memory, pushed to a distributed file system, or even uploaded to the cloud as pieces come in.
+
+In addition, notifications are sent when good or bad pieces are detected as soon as enough blocks are sent to the disk manager that make up a full piece.

packages/handshake/Cargo.toml

@@ -1,8 +1,8 @@
 [package]
 name = "handshake"
-
 description = "Common handshaking interface as well as a default handshake implementation"
 keywords = ["handshake", "bittorrent"]
+readme = "README.md"
 
 authors.workspace = true
 categories.workspace = true
@@ -11,7 +11,7 @@ edition.workspace = true
 homepage.workspace = true
 license.workspace = true
 publish.workspace = true
-readme.workspace = true
+
 repository.workspace = true
 version.workspace = true
 

packages/handshake/README.md

@@ -0,0 +1,8 @@
+# Handshake
+This library provides an implementation for handshaking between peers.
+
+Handshaking is the process of connecting to a peer and exchanging information related to how a peer will be communicating with you and vice versa.
+
+In our case, there are many bittorrent technologies that could generally be considered peer discovery mechanisms (local peer discovery, dht, trackers, peer exchange) where once a peer is discovered, a client may want to immediately attempt to establish a connection via a handshake.
+
+This module provides a trait for custom handshake implementations, as well as the standard bittorrent handshake, so that clients can specify a handshaking mechanism for peer discovery services to forward contact information along to.

packages/htracker/Cargo.toml

@@ -1,8 +1,8 @@
 [package]
 name = "htracker"
-
 description = "Communication with bittorrent HTTP trackers"
 keywords = ["tracker", "bittorrent", "http"]
+readme = "README.md"
 
 authors.workspace = true
 categories.workspace = true
@@ -11,6 +11,6 @@ edition.workspace = true
 homepage.workspace = true
 license.workspace = true
 publish.workspace = true
-readme.workspace = true
+
 repository.workspace = true
 version.workspace = true

packages/htracker/README.md

@@ -0,0 +1,2 @@
+# Http Tracker (htracker)
+Not Implemented. Please consider: [UDP Tracker (utracker)](../utracker/).

packages/lpd/Cargo.toml

@@ -2,6 +2,7 @@
 name = "lpd"
 description = "Implementation of the bittorrent Local Peer/Service Discovery mechanism"
 keywords = ["peer", "discovery", "local", "service"]
+readme = "README.md"
 
 authors.workspace = true
 categories.workspace = true
@@ -10,6 +11,6 @@ edition.workspace = true
 homepage.workspace = true
 license.workspace = true
 publish.workspace = true
-readme.workspace = true
+
 repository.workspace = true
 version.workspace = true

packages/lpd/README.md

@@ -0,0 +1,2 @@
+# Local Peer Discovery (lpd)
+Not Implemented.

packages/magnet/Cargo.toml

@@ -2,6 +2,7 @@
 name = "magnet"
 description = "Magnet link parsing and construction"
 keywords = ["magnet", "bittorrent"]
+readme = "README.md"
 
 authors.workspace = true
 categories.workspace = true
@@ -10,7 +11,7 @@ edition.workspace = true
 homepage.workspace = true
 license.workspace = true
 publish.workspace = true
-readme.workspace = true
+
 repository.workspace = true
 version.workspace = true
 

packages/magnet/README.md

@@ -0,0 +1,2 @@
+# Magnet
+This library provides functions to parse and construct magnet links.

packages/metainfo/Cargo.toml

@@ -2,6 +2,7 @@
 name = "metainfo"
 description = "Parsing and building of bittorrent metainfo files"
 keywords = ["metainfo", "torrent", "file", "bittorrent"]
+readme = "README.md"
 
 authors.workspace = true
 categories.workspace = true
@@ -10,7 +11,7 @@ edition.workspace = true
 homepage.workspace = true
 license.workspace = true
 publish.workspace = true
-readme.workspace = true
+
 repository.workspace = true
 version.workspace = true
 

packages/metainfo/README.md

@@ -0,0 +1,9 @@
+# Magnet
+This library provides an api for parsing and building of bittorrent metainfo files.
+
+
+Metainfo files serve the purpose of providing a list of checksums for clients interested in specific files, how long each hashed piece should be, and the directory structure for the files.
+
+This allows clients to verify the integrity of received files, as well as the ability to recreate exactly the directory structure for the files.
+
+Aside from that, there is a plethora of optional information that can be included in this file such as nodes to be contacted in the DHT, trackers to contact, as well as comments, date created, who created the metainfo file, etc.

packages/peer/Cargo.toml

@@ -2,6 +2,7 @@
 name = "peer"
 description = "Communication with bittorrent peers via peer wire protocol"
 keywords = ["peer", "wire", "protocol", "pwp", "bittorrent"]
+readme = "README.md"
 
 authors.workspace = true
 categories.workspace = true
@@ -10,7 +11,7 @@ edition.workspace = true
 homepage.workspace = true
 license.workspace = true
 publish.workspace = true
-readme.workspace = true
+
 repository.workspace = true
 version.workspace = true
 

packages/peer/README.md

@@ -0,0 +1,12 @@
+# Peer
+This library assists communication between with bittorrent peers via the peer wire protocol.
+
+Peer communication with bittorrent involves:
+- Choking (telling someone we won't respond to them now).
+- Expressing interest (telling someone, if we were unchoked, we would be interested in some data they hold).
+
+As well as downloading and uploading the actual blocks to peers.
+
+This package defines some common bittorrent messages, including those as part of the `ExtensionBits` in `bip_handshake`, as well as those included in the [extension protocol (BEP-10)](http://www.bittorrent.org/beps/bep_0010.html).
+
+We also provide a `PeerManager` for heartbeating peers and multiplexing messages sent to/from peers so that clients have an easier time communicating asynchronously with many peers.

packages/select/Cargo.toml

@@ -2,6 +2,7 @@
 name = "select"
 description = "Bittorrent Infrastructure Project Piece Selection Module"
 keywords = ["piece", "selection"]
+readme = "README.md"
 
 authors.workspace = true
 categories.workspace = true
@@ -10,7 +11,7 @@ edition.workspace = true
 homepage.workspace = true
 license.workspace = true
 publish.workspace = true
-readme.workspace = true
+
 repository.workspace = true
 version.workspace = true
 

packages/select/README.md

@@ -0,0 +1,9 @@
+# Select
+This library provides the _Bittorrent Infrastructure Project_ piece selection algorithm.
+
+Selection is broken up in to three classes of algorithms:
+1. __Piece Revelation__: Determining which pieces we should reveal (even if we don't have the piece...) and to whom.
+2. __Piece Selection__: Determining what pieces we should download/upload next.
+3. __Piece Queueing__: Calculating, given a piece we want to download, which peers should we send such a request to.
+
+We can mix and match different algorithms to create a swarm that may have different characteristics than other swarms.

packages/util/Cargo.toml

@@ -2,6 +2,7 @@
 name = "util"
 description = "Utilities for the Bittorrent Infrastructure Project"
 keywords = ["utility"]
+readme = "README.md"
 
 authors.workspace = true
 categories.workspace = true
@@ -10,7 +11,7 @@ edition.workspace = true
 homepage.workspace = true
 license.workspace = true
 publish.workspace = true
-readme.workspace = true
+
 repository.workspace = true
 version.workspace = true
 

packages/util/README.md

@@ -0,0 +1,2 @@
+# Utility (util)
+This library provides utilities used by the _Bittorrent Infrastructure Project_.

packages/utp/Cargo.toml

@@ -2,6 +2,7 @@
 name = "utp"
 description = "uTorrent Transport Protocol"
 keywords = ["utp", "bittorrent", "transport"]
+readme = "README.md"
 
 authors.workspace = true
 categories.workspace = true
@@ -10,6 +11,6 @@ edition.workspace = true
 homepage.workspace = true
 license.workspace = true
 publish.workspace = true
-readme.workspace = true
+
 repository.workspace = true
 version.workspace = true

packages/utp/README.md

@@ -0,0 +1,2 @@
+# uTorrent Transport Protocol (utp)
+Not Implemented. Please consider our [Peer](../peer/) package.