├── LICENSE
└── README.md


/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2019 comntr
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | ```
  2 |                +------------------+
  3 |                | Chrome Extension |
  4 |                +------------------+
  5 |                          |
  6 |                        1.|
  7 |                          |
  8 |                          v
  9 |       +-----+   2   +--------+  5  +------+ 
 10 |    +->| DHT |<------| client |---->| IPFS |
 11 |    |  +-----+       +--------+     +------+
 12 |  6.|                 |     |
 13 |    |               3.|   4.|
 14 |    |  +----------+   |     |
 15 |    |  | server 1 |<--+     |
 16 |    |  +----------+         |
 17 |    |       ^               |
 18 |    |     7.|               |
 19 |    |       |               |        
 20 |    |  +----------+         |
 21 |    +--| server 2 |<--------+
 22 |       +----------+
 23 | ```
 24 | 
 25 | - `client` is a JS-only site that runs a IPFS node, talks to
 26 |   the `servers` and displays the comments. This site can be
 27 |   hosted on `github.io` since it doesn't have any server-side
 28 |   code.
 29 | - `server` is a VPS with a static IP address that runs a IPFS
 30 |   node and stores comments posted by the `clients`. The `server`
 31 |   publishes its IP address and port to the DHT using the
 32 |   hardcoded `network-id` DHT key.
 33 | - `network-id` is a random 192/256-bit value used as the DHT key
 34 |   to make `servers` discoverable by `clients` and other `servers`.
 35 | 
 36 | 1. The extension grabs the tab URL and gives its hash to the client:
 37 |     ```
 38 |     client5.github.io/#<url-hash>
 39 |     ```
 40 | 2. The client uses the DHT (WebTorrent DHT or IPFS DHT) to find
 41 |    servers in the network. It uses the hardcoded network id as the
 42 |    DHT key:
 43 |     ```bash
 44 |     for prov in $(ipfs dht findprovs $networkid); do
 45 |       timeout 3 ipfs dht findpeer $prov;
 46 |     done
 47 |     ```
 48 |    The DHT finds 2 servers and returns their IP addresses and ports:
 49 |     ```
 50 |     [server 1] 11.22.33.44:12345
 51 |     [server 2] 22.33.44.55:54321
 52 |     ```
 53 | 3. The client sends a `GET /<url-hash>` to server 1 to get comments
 54 |    for this URL. The server uses `ipfs add` to publish the folder
 55 |    with comments to IPFS and returns the `<folder-id>`.
 56 | 4. The client sends a `POST /<url-hash>` to add a comment for the URL.
 57 | 5. The client gets files for `<folder-id>` from IPFS.
 58 | 6. Server 2 uses the DHT to find other servers.
 59 | 7. Server 2 sends a `GET /` to server 1 to get a IPFS folder id for
 60 |    all the comments for all the URLs it knows.
 61 | 
 62 | 
 63 | ```
 64 |   +--------+
 65 |   | client |           Web
 66 |   +--------+
 67 |       |
 68 | --- 1.| -------------------
 69 |       v
 70 | +-------------+
 71 | | http server |        VPS
 72 | +-------------+
 73 |       |    |
 74 |     2.|    +--------+
 75 |       |           4.|
 76 |       v             v
 77 | +----------+ +-----------+
 78 | | HTTP GET | | HTTP POST |
 79 | +----------+ +-----------+
 80 |       |
 81 |       |      +---------+
 82 |     3.|      | watcher |
 83 |       |      +---------+
 84 |       v
 85 | +-------------+  +------+
 86 | | ipfs daemon |  | sync |
 87 | +-------------+  +------+
 88 |       ^              |
 89 |       |      5.      |
 90 |       +--------------+
 91 | ```
 92 | 
 93 | The `server` or VPS consists of a few processes:
 94 | 
 95 | - The `http server` process listens on a certain port and accepts
 96 |   the `GET` and `POST` requests from the `clients`. It doesn't do
 97 |   the work, but rather forwards requests to the designated handlers.
 98 | - The `HTTP GET` handler is a process that works on the `GET`
 99 |   requests. It runs the `ipfs add` command that can be slow sometimes.
100 | - The `HTTP POST` handler is a process that works on the `POST`
101 |   requests. It creates files with new comments and doesn't need to
102 |   use IPFS commands.
103 | - `ipfs daemon` runs in its own process.
104 | - The `watcher` process keeps an eye on all the other processes and
105 |   restarts them if needed. This especially applies to the IPFS
106 |   daemon that tends to leak memory.
107 | - `sync` is the process that connects to other `servers` and pulls
108 |   comments from them. It uses the DHT to discover other `servers`
109 |   and uses IPFS to get comments.
110 | 
111 | 1. The `client` sends a `GET` request to fetch comments for a URL.
112 | 2. The `http server` forwards the `GET` to the `HTTP GET` handler.
113 | 3. The `HTTP GET` handler runs `ipfs add` to generate a IPFS folder
114 |    id for the comments.
115 | 4. If the `client` sends a `POST` request to add a comment, the
116 |    request is processed by the `HTTP POST` handler that creates a
117 |    file with this comment. It doesn't need access to the IPFS daemon.
118 | 5. The `sync` process uses the DHT to find other `servers`, sends
119 |    `GET /` to them and uses IPFS to download comments.
120 | 


--------------------------------------------------------------------------------