You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Feb 12, 2024. It is now read-only.
Copy file name to clipboardExpand all lines: examples/circuit-relaying/README.md
+29-29Lines changed: 29 additions & 29 deletions
Original file line number
Diff line number
Diff line change
@@ -24,10 +24,10 @@ Here is a simple diagram depicting how a typical circuit-relay connection might
24
24
25
25
`Node A` tries to connect to `Node B` but, UH-OH! There is a firewall in between that's preventing it from happening. If both `Node A` and `Node B` know about a relay, they can use it to establish the connection.
26
26
27
-
This is how it looks like, in somewhat simplified steps:
27
+
This is what it looks like, in simplified steps:
28
28
29
-
1.`Node A` tries to connect to `Node B` over one of its know addresses
30
-
2. Connection fails because of firewall/nat/incompatible transports/etc...
29
+
1.`Node A` tries to connect to `Node B` over one of its known addresses
30
+
2. Connection fails because of firewall/NAT/incompatible transports/etc...
31
31
3. Both `Node A` and `Node B` know of the same relay - `Relay`
32
32
4.`Node A` falls back to dialing over `Relay` to `Node B` using its `'/p2p-circuit'` address, which involves:
33
33
1.`Node A` sends a `HOP` request to `Relay`
@@ -37,24 +37,24 @@ This is how it looks like, in somewhat simplified steps:
37
37
5.`Relay` proceed to create a circuit over the two nodes
38
38
5.`Node A` and `Node B` are now connected over `Relay`
39
39
40
-
Thats it!
40
+
That's it!
41
41
42
-
#### Whats up with this `HOP` and `STOP` nonsense?
42
+
#### What's up with this `HOP` and `STOP` nonsense?
43
43
44
-
Circuit relay consists of two logical parts - dialer/listener and relay (`HOP`). The listener is also known as the `STOP` node. Each of this - dial, listen and relay happen on a different node. If we use the nodes from the above example, it looks something like this:
44
+
Circuit relay consists of two logical parts — dialer/listener and relay (`HOP`). The listener is also known as the `STOP` node. Each of these — dial, listen, and relay — happen on a different node. If we use the nodes from the above example, it looks something like this:
45
45
46
46
- The `dialer` knows how to dial a `relay` (`HOP`) - `Node A`
47
47
- The `relay` (`HOP`) knows how to contact a destination node (`STOP`) and create a circuit - `Relay` node
48
48
- The `listener` (`STOP`) knows how to process relay requests that come from the relay (`HOP`) node - `Node B`
49
49
50
50
_Fun fact - the `HOP` and `STOP` names are also used internally by circuit to identify the network message types._
51
51
52
-
#### A few caveats (and features).
52
+
#### A few caveats (and features)
53
53
54
-
There are a couple of caveats and features to be aware of
54
+
There are a couple of caveats and features to be aware of:
55
55
56
56
- A `Relay` will only work if it already has a connection to the `STOP` node
57
-
- No `multihop` dialing is supported. Although it's a feature planed for upcoming releases (no date on this one)
57
+
- No `multihop` dialing is supported. It's a feature planed for upcoming releases (no date on this one)
58
58
- Multihop dialing is when several relays are used to establish the connection
59
59
- It is possible to use explicit relay addresses to connect to a node, or even to listen for connections on. See next section to learn how to do this.
60
60
@@ -79,8 +79,8 @@ We can take it a step further and encode the same information for the destinatio
If a node is configured with this address, it will use the specified host (`/ip4/127.0.0.1/tcp/65000/ipfs/QmRelay`) as a relay and it will be reachable over this relay.
82
-
- There could multiple addresses of this sort specified in the config, in which case the node is going to be reachable over all of them.
83
-
- This is useful if for example, the node is behind a firewall but wants to be reachable from the outside over a specific relay.
82
+
- There could multiple addresses of this sort specified in the config, in which case the node will be reachable over all of them.
83
+
- This is useful if, for example, the node is behind a firewall but wants to be reachable from the outside over a specific relay.
84
84
85
85
Other use-cases are also supported by this scheme, e.g. we can have multiple hops (circuit-relay nodes) encoded in the address, something planed for future releases.
86
86
@@ -131,7 +131,7 @@ This will set up your IPFS repo in your home directory.
131
131
132
132
#### Configure and run the js or go ipfs node
133
133
134
-
We can either use a `go-ipfs` or a `js-ipfs` node as a relay, we'll demonstrate how to set them up in this tutorial and we encourage you to try them both out. That said, either js or go should do the trick!
134
+
You can use a `go-ipfs` or a `js-ipfs` node as a relay. We'll demonstrate how to set both up in this tutorial and we encourage you to try both out. That said, either js or go should do the trick!
135
135
136
136
##### Setting up a `go-ipfs` node
137
137
@@ -153,9 +153,9 @@ In order to enable the relay functionality in `go-ipfs` we need to edit it's con
153
153
}
154
154
```
155
155
156
-
The two options we're looking for are `DisableRelay` and `EnableRelayHop`. We want the former (`DisableRelay`) set to `false` and the later (`EnableRelayHop`) to `true`, just like in the example above. That should set our go node as a relay.
156
+
The two options we're looking for are `DisableRelay` and `EnableRelayHop`. We want the former (`DisableRelay`) set to `false` and the latter (`EnableRelayHop`) to `true`, just like in the example above. That should set our go node as a relay.
157
157
158
-
We also need to make sure our go node is able to be dialed from the browser, for that we need to enable a transport that both the browser and the go node can communicate over. We will use the web sockets transport, although there are others that can be used, such as `webrtc-star` and `websocket-star`. To enable the transport and set the interface and port we need to edit the `~/.ipfs/config` one more time. Lets find the `Swarm` array and add our desired address there. I picked `/ip4/0.0.0.0/tcp/4004/ws`as it is a port I know is not being used by anything on my machine, but we can also use port `0` so that the OS chooses a random available port for us - either one should work.
158
+
We also need to make sure our go node can be dialed from the browser. For that, we need to enable a transport that both the browser and the go node can communicate over. We will use the web sockets transport, although there are others that can be used, such as `webrtc-star` and `websocket-star`. To enable the transport and set the interface and port we need to edit the `~/.ipfs/config` one more time. Let's find the `Swarm` array and add our desired address there. I picked `/ip4/0.0.0.0/tcp/4004/ws`because it is a port I know is not being used by anything on my machine, but we can also use port `0` so that the OS chooses a random available port for us — either one should work.
159
159
160
160
```
161
161
"Swarm": [
@@ -169,11 +169,11 @@ The config should look similar to the above snippet after we've edited it.
169
169
170
170
##### Setting up a `js-ipfs` node
171
171
172
-
We need to go through similar steps to enable circuit relay in `jsipfs`, however the config options are slightly different right now - that should change once this feature is not marked as experimental, but for now we have to deal with two different sets of options.
172
+
We need to go through similar steps to enable circuit relay in `jsipfs`. However, the config options are slightly different — that should change once this feature is not marked as experimental, but for now we have to deal with two different sets of options.
173
173
174
-
Just as we did with `go-ipfs`, go ahead and edit `js-ipfs` config file located under `~/.jsipfs/config`. Lets add the following config:
174
+
Just as we did with `go-ipfs`, go ahead and edit `js-ipfs` config file located under `~/.jsipfs/config`. Let's add the following config:
175
175
176
-
(Note that the "EXPERIMENTAL" section might be missing from the config file, in that case, just go ahead and add it)
176
+
(Note that the "EXPERIMENTAL" section might be missing from the config file. In that case, just go ahead and add it)
177
177
178
178
```js
179
179
"EXPERIMENTAL": {
@@ -190,7 +190,7 @@ Note that we don't have to do anything to enable the `websocket` transport as it
190
190
191
191
##### Starting the relay node
192
192
193
-
We can start the relay nodes by either doing`ipfs daemon` or `jsipfs daemon`:
193
+
We can start the relay nodes by either running`ipfs daemon` or `jsipfs daemon`:
194
194
195
195
**go ipfs**
196
196
@@ -210,7 +210,7 @@ Gateway (readonly) server listening on /ip4/127.0.0.1/tcp/8080
210
210
Daemon is ready
211
211
```
212
212
213
-
In the case of go ipfs, the crucial `/ipfs/Qm...` part of the multiaddr might be missing, in that case, you can get it by running the `ipfs id` command.
213
+
In the case of go ipfs, the crucial `/ipfs/Qm...` part of the multiaddr might be missing. In that case, you can get it by running the `ipfs id` command.
214
214
215
215
```
216
216
$ ipfs id
@@ -229,7 +229,7 @@ $ ipfs id
229
229
}
230
230
```
231
231
232
-
We can then grab the resolved multiaddr from the `Addresses` array -`/ip4/127.0.0.1/tcp/4004/ws/ipfs/Qm...`. Lets note it down somewhere and move to the next step.
232
+
We can then grab the resolved multiaddr from the `Addresses` array —`/ip4/127.0.0.1/tcp/4004/ws/ipfs/Qm...`. Let's note it down somewhere and move to the next step.
233
233
234
234
**js ipfs**
235
235
@@ -247,24 +247,24 @@ Gateway (readonly) is listening on: /ip4/127.0.0.1/tcp/9090
247
247
Daemon is ready
248
248
```
249
249
250
-
Look out for an address similar to `/ip4/127.0.0.1/tcp/4003/ws/ipfs/Qm...` note it down somewhere, and lets move on to the next step.
250
+
Look out for an address similar to `/ip4/127.0.0.1/tcp/4003/ws/ipfs/Qm...`. Note it down somewhere, and let's move on to the next step.
251
251
252
252
### 2. Configure and run the bundled example
253
253
254
-
Now that we have ipfs installed and initialized, lets set up the included example. This is a standard npm package, so the usual `npm install` should get us going. Lets`cd` into the `examples/circuit-relaying` directory and run:
254
+
Now that we have ipfs installed and initialized, let's set up the included example. This is a standard npm package, so the usual `npm install` should get us going. Let's`cd` into the `examples/circuit-relaying` directory and run:
255
255
256
256
```
257
257
npm install
258
258
```
259
259
260
-
After it finishes, we should be able to run the project with `npm start` and get a similar output to the bellow one:
260
+
After it finishes, we should be able to run the project with `npm start` and get output similar to:
261
261
262
262
```
263
263
npm run start
264
264
Server running at http://localhost:1234
265
265
```
266
266
267
-
The bundled example is a simple chat app that uses another cool ipfs feature - [pubsub](https://github.com/libp2p/specs/tree/master/pubsub). Lets open up a browser and paste the above url into the address bar. We should see something similar to the following image:
267
+
The bundled example is a simple chat app that uses another cool ipfs feature - [pubsub](https://github.com/libp2p/specs/tree/master/pubsub). Let's open up a browser and paste the above url into the address bar. We should see something similar to the following image:
268
268
269
269

270
270
@@ -282,26 +282,26 @@ After connecting to the IPFS node, we should see the relay peer show up under th
282
282
283
283

284
284
285
-
Lets repeat the same steps with the second tab. Now, both of our browser nodes should be connected to the relay and we can move on to the next step.
285
+
Let's repeat the same steps with the second tab. Now, both of our browser nodes should be connected to the relay and we can move on to the next step.
286
286
287
287
### 4. Dial the two browser nodes using a `/p2p-circuit` address
288
288
289
-
Having both browsers running side by side (as shown in the first screenshot), lets get them connected to each other. Head out to the `Addresses` box in one of the tabs, copy the `/p2p-circuit` address and then paste it into the `Connect to Peer` box in the other tab. Repeat these steps on the second tab.
289
+
Now that both browsers are running side by side (as shown in the first screenshot), let's get them connected to each other. Head out to the `Addresses` box in one of the tabs, copy the `/p2p-circuit` address and then paste it into the `Connect to Peer` box in the other tab. Repeat these steps on the second tab.
290
290
291
291

292
292
293
-
Lets hit the `Connect` button on each of the tabs and we should get the two browsers connected and join the chat room.
293
+
Let's hit the `Connect` button on each of the tabs and we should get the two browsers connected and join the chat room.
294
294
295
295

296
296
297
297
### 5. Send data browser to browser.
298
298
299
-
Now that we have the two browsers connected, lets try the app out. Type a few words in one of the browser windows and you should see them appear in the other as well!
299
+
Now that we have the two browsers connected, let's try the app out. Type a few words in one of the browser windows and you should see them appear in the other as well!
300
300
301
301

302
302
303
303
Thats it!
304
304
305
305
### Conclusion
306
306
307
-
Lets recap what we accomplished in this tutorial. We were able to install a js and go ipfs node and configure them as circuit relays, we connected our browsers to the relay and were able to use the bundled chat app to send messages browser to browser.
307
+
Let's recap what we accomplished in this tutorial. We were able to install a js and go ipfs node and configure them as circuit relays, we connected our browsers to the relay, and were able to use the bundled chat app to send messages browser to browser.
0 commit comments