add docs for p2p http proxy
License: MIT Signed-off-by: Ian Preston <ianopolous@protonmail.com>
Dr Ian Preston committed
Oct 10, 2018 at 22:07 UTC
9e79c5e3c96fb9d7068eef1d4330a0bc33d4ac1f
1 file changed
+80
docs/experimental-features.md
+80
@@ -21,6 +21,7 @@ the above issue.
21
- [BadgerDB datastore](#badger-datastore)
22
- [Private Networks](#private-networks)
23
- [ipfs p2p](#ipfs-p2p)
24
+- [p2p http proxy](#p2p-http-proxy)
25
- [Circuit Relay](#circuit-relay)
26
- [Plugins](#plugins)
27
- [Directory Sharding / HAMT](#directory-sharding-hamt)
@@ -382,6 +383,85 @@ with `ssh [user]@127.0.0.1 -p 2222`.
383
384
---
385
386
+## p2p http proxy
387
+
388
+Allows proxying of HTTP requests over p2p streams. This allows serving any standard http app over p2p streams.
389
+
390
+### State
391
+
392
+Experimental
393
+
394
+### In Version
395
+
396
+master, 0.4.18
397
+
398
+### How to enable
399
+
400
+The `p2p` command needs to be enabled in config:
401
+
402
+```sh
403
+> ipfs config --json Experimental.Libp2pStreamMounting true
404
+```
405
+
406
+On the client, the p2p http proxy needs to be enabled in the config:
407
+
408
+```sh
409
+> ipfs config --json Experimental.P2pHttpProxy true
410
+```
411
+
412
+### How to use
413
+
414
+**Netcat example:**
415
+
416
+First, pick a protocol name for your application. Think of the protocol name as
417
+a port number, just significantly more user-friendly. In this example, we're
418
+going to use `test`.
419
+
420
+***Setup:***
421
+
422
+1. A "server" node with peer ID `$SERVER_ID`
423
+2. A "client" node.
424
+
425
+***On the "server" node:***
426
+
427
+First, start your application and have it listen for TCP connections on
428
+port `$APP_PORT`.
429
+
430
+Then, configure the p2p listener by running:
431
+
432
+```sh
433
+> ipfs p2p listen --allow-custom-protocol test /ip4/127.0.0.1/tcp/$APP_PORT
434
+```
435
+
436
+This will configure IPFS to forward all incoming `test` streams to
437
+`127.0.0.1:$APP_PORT` (opening a new connection to `127.0.0.1:$APP_PORT` per incoming stream.
438
+
439
+***On the "client" node:***
440
+
441
+Next, have your application make a http request to `127.0.0.1:5001/proxy/http/$SERVER_ID/$PROTOCOL/$FORWARDED_PATH`. This
442
+connection will be forwarded to the service running on `127.0.0.1:$APP_PORT` on
443
+the remote machine (which needs to be a http server!) with path `$FORWARDED_PATH`. You can test it with netcat:
444
+
445
+***On "server" node:***
446
+```sh
447
+> echo -e "HTTP/1.1 200\nContent-length: 11\n\nIPFS rocks!" | nc -l -p $APP_PORT
448
+```
449
+
450
+***On "client" node:***
451
+```sh
452
+> curl http://localhost:5001/proxy/http/$SERVER_ID/test/
453
+```
454
+
455
+You should now see the resulting http response: IPFS rocks!
456
+
457
+
458
+### Road to being a real feature
459
+- [ ] Needs p2p streams to graduate from experiments
460
+- [ ] Needs more people to use and report on how well it works / fits use cases
461
+- [ ] More documentation
462
+
463
+---
464
+
465
## Circuit Relay
466
467
Allows peers to connect through an intermediate relay node when there