feat: update experimental documentations for 0.5.0 release
Mostly: 1. Remove old experiments. 2. Update reasons for features being experimental. 3. Comment on experiments that will be enabled in the near future.
Steven Allen committed
Apr 27, 2020 at 16:01 UTC
4c663bcf242b76ee090b3138c0ae94da1740d284
1 file changed
+41
-173
docs/experimental-features.md
+41
-173
@@ -38,7 +38,7 @@ the above issue.
38
39
### State
40
41
-experimental, default-disabled.
41
+Candidate, disabled by default but will be enabled by default in 0.6.0.
42
43
### In Version
44
@@ -79,75 +79,40 @@ signed) by running:
79
- [ ] Needs authenticating modes to be implemented
80
- [ ] needs performance analyses to be done
81
82
----
83
-
84
-## Client mode DHT routing
82
+## Raw Leaves for unixfs files
83
86
-Allows the dht to be run in a mode that doesn't serve requests to the network,
87
-saving bandwidth.
84
+Allows files to be added with no formatting in the leaf nodes of the graph.
85
86
### State
90
-stable
87
92
-### In Version
93
-
94
-0.5.0
95
-
96
-### How to enable
97
-
98
-run your daemon with the `--routing=dhtclient` flag.
99
-
100
----
101
-
102
-## go-multiplex stream muxer
103
-Adds support for using the go-multiplex stream muxer alongside (or instead of)
104
-yamux and spdy. This multiplexer is far simpler, and uses less memory and
105
-bandwidth than the others, but is lacking on congestion control and backpressure
106
-logic. It is available to try out and experiment with.
107
-
108
-### State
109
-Stable
88
+Stable but not used by default.
89
90
### In Version
91
+
92
0.4.5
93
94
### How to enable
95
116
-To make it the default stream muxer, set the environment variable
117
-`LIBP2P_MUX_PREFS` as follows:
118
-```
119
-export LIBP2P_MUX_PREFS="/mplex/6.7.0 /yamux/1.0.0 /spdy/3.1.0"
120
-```
121
-
122
----
123
-
124
-## Raw Leaves for unixfs files
125
-Allows files to be added with no formatting in the leaf nodes of the graph.
126
-
127
-### State
128
-experimental.
129
-
130
-### In Version
131
-master, 0.4.5
132
-
133
-### How to enable
134
-Use `--raw-leaves` flag when calling `ipfs add`.
96
+Use `--raw-leaves` flag when calling `ipfs add`. This will save some space when adding files.
97
98
### Road to being a real feature
137
-- [ ] Needs more people to use and report on how well it works.
99
139
----
100
+Enabling this feature _by default_ will change the CIDs (hashes) of all newly imported files and will prevent newly imported files from deduplicating against previously imported files. While we do intend on enabling this by default, we plan on doing so once we have a large batch of "hash-changing" features we can enable all at once.
101
102
## ipfs filestore
103
+
104
Allows files to be added without duplicating the space they take up on disk.
105
106
### State
145
-experimental.
107
+
108
+Experimental.
109
110
### In Version
148
-master, 0.4.7
111
+
112
+0.4.7
113
114
### How to enable
115
+
116
Modify your ipfs config:
117
```
118
ipfs config --json Experimental.FilestoreEnabled true
@@ -159,23 +124,26 @@ Finally, when adding files with ipfs add, pass the --nocopy flag to use the
124
filestore instead of copying the files into your local IPFS repo.
125
126
### Road to being a real feature
127
+
128
- [ ] Needs more people to use and report on how well it works.
129
- [ ] Need to address error states and failure conditions
130
- [ ] Need to write docs on usage, advantages, disadvantages
131
- [ ] Need to merge utility commands to aid in maintenance and repair of filestore
132
167
----
168
-
133
## ipfs urlstore
134
+
135
Allows ipfs to retrieve blocks contents via a URL instead of storing it in the datastore
136
137
### State
173
-experimental.
138
+
139
+Experimental.
140
141
### In Version
176
-master, v0.4.17
142
+
143
+v0.4.17
144
145
### How to enable
146
+
147
Modify your ipfs config:
148
```
149
ipfs config --json Experimental.UrlstoreEnabled true
@@ -190,19 +158,20 @@ And then add a file at a specific URL using `ipfs urlstore add <url>`
158
- [ ] Need to implement caching
159
- [ ] Need to add metrics to monitor performance
160
193
----
194
-
161
## Private Networks
162
163
It allows ipfs to only connect to other peers who have a shared secret key.
164
165
### State
200
-Experimental
166
+
167
+Stable but not quite ready for prime-time.
168
169
### In Version
203
-master, 0.4.7
170
+
171
+0.4.7
172
173
### How to enable
174
+
175
Generate a pre-shared-key using [ipfs-swarm-key-gen](https://github.com/Kubuxu/go-ipfs-swarm-key-gen)):
176
```
177
go get github.com/Kubuxu/go-ipfs-swarm-key-gen/ipfs-swarm-key-gen
@@ -240,10 +209,10 @@ variable to `1` to force the usage of private networks. If no private network is
209
configured, the daemon will fail to start.
210
211
### Road to being a real feature
243
-- [ ] Needs more people to use and report on how well it works
244
-- [ ] More documentation
212
246
----
213
+- [x] Needs more people to use and report on how well it works
214
+- [ ] More documentation
215
+- [ ] Needs better tooling/UX.
216
217
## ipfs p2p
218
@@ -253,11 +222,11 @@ similar.
222
223
### State
224
256
-Experimental
225
+Experimental, will be stabilized in 0.6.0
226
227
### In Version
228
260
-master, 0.4.10
229
+0.4.10
230
231
### How to enable
232
@@ -351,11 +320,8 @@ with `ssh [user]@127.0.0.1 -p 2222`.
320
321
322
### Road to being a real feature
354
-- [ ] Needs more people to use and report on how well it works / fits use cases
355
-- [ ] More documentation
356
-- [ ] Support other protocols (e.g, Unix domain sockets, WebSockets, etc.)
323
358
----
324
+- [ ] More documentation
325
326
## p2p http proxy
327
@@ -367,7 +333,7 @@ Experimental
333
334
### In Version
335
370
-master, 0.4.19
336
+0.4.19
337
338
### How to enable
339
@@ -429,62 +395,15 @@ the remote machine (which needs to be a http server!) with path `$FORWARDED_PATH
395
You should now see the resulting HTTP response: IPFS rocks!
396
397
### Custom protocol names
398
+
399
We also support the use of protocol names of the form /x/$NAME/http where $NAME doesn't contain any "/"'s
400
401
### Road to being a real feature
402
+
403
- [ ] Needs p2p streams to graduate from experiments
404
- [ ] Needs more people to use and report on how well it works / fits use cases
405
- [ ] More documentation
438
-
439
----
440
-
441
-## Circuit Relay
442
-
443
-Allows peers to connect through an intermediate relay node when there
444
-is no direct connectivity.
445
-
446
-### State
447
-Experimental
448
-
449
-### In Version
450
-master, 0.4.11
451
-
452
-### How to enable
453
-
454
-The relay transport is enabled by default, which allows peers to dial through
455
-a relay and listens for incoming relay connections. The transport can be disabled
456
-by setting `Swarm.DisableRelay = true` in the configuration.
457
-
458
-By default, peers don't act as intermediate nodes (relays). This can be enabled
459
-by setting `Swarm.EnableRelayHop = true` in the configuration. Note that the
460
-option needs to be set before online services are started to have an effect; an
461
-already online node would have to be restarted.
462
-
463
-### Basic Usage:
464
-
465
-To connect peers QmA and QmB through a relay node QmRelay:
466
-
467
-- Both peers should connect to the relay:
468
-`ipfs swarm connect /transport/address/p2p/QmRelay`
469
-- Peer QmA can then connect to peer QmB using the relay:
470
-`ipfs swarm connect /p2p/QmRelay/p2p-circuit/p2p/QmB`
471
-
472
-Peers can also connect with an unspecific relay address, which will
473
-try to dial through known relays:
474
-`ipfs swarm connect /p2p-circuit/p2p/QmB`
475
-
476
-Peers can see their (unspecific) relay address in the output of
477
-`ipfs swarm addrs listen`
478
-
479
-### Road to being a real feature
480
-
481
-- [ ] Needs more people to use it and report on how well it works.
482
-- [ ] Advertise relay addresses to the DHT for NATed or otherwise unreachable
483
- peers.
484
-- [ ] Active relay discovery for specific relay address advertisement. We would
485
- like advertised relay addresses to designate specific relays for efficient dialing.
486
-- [ ] Dialing priorities for relay addresses; arguably, relay addresses should
487
- have lower priority than direct dials.
406
+- [ ] Need better integration with the subdomain gateway feature.
407
408
## Plugins
409
@@ -502,41 +421,11 @@ See [Plugin docs](./plugins.md)
421
422
### Road to being a real feature
423
505
-- [ ] Better support for platforms other than Linux
506
-- [ ] More plugins and plugin types
424
+- [x] More plugins and plugin types
425
+- [ ] A way to reliably build and distribute plugins.
426
+- [ ] Better support for platforms other than Linux & MacOS
427
- [ ] Feedback on stability
428
509
----
510
-
511
-## Badger datastore
512
-
513
-### In Version
514
-
515
-0.4.11
516
-
517
-Badger-ds is new datastore implementation based on
518
-https://github.com/dgraph-io/badger.
519
-
520
-
521
-### Basic Usage
522
-
523
-```
524
-$ ipfs init --profile=badgerds
525
-```
526
-or install https://github.com/ipfs/ipfs-ds-convert/ and
527
-```
528
-[BACKUP ~/.ipfs]
529
-$ ipfs config profile apply badgerds
530
-$ ipfs-ds-convert convert
531
-```
532
-
533
-You can read more in the [datastore](./datastores.md#badgerds) documentation.
534
-
535
-### Road to being a real feature
536
-
537
-- [ ] Needs more testing
538
-- [ ] Make sure there are no unknown major problems
539
-
429
## Directory Sharding / HAMT
430
431
### In Version
@@ -562,8 +451,6 @@ ipfs config --json Experimental.ShardingEnabled true
451
- [ ] Make sure that objects that don't have to be sharded aren't
452
- [ ] Generalize sharding and define a new layer between IPLD and IPFS
453
565
----
566
-
454
## IPNS pubsub
455
456
### In Version
@@ -595,8 +482,6 @@ run your daemon with the `--enable-namesys-pubsub` flag; enables pubsub.
482
so that we don't have to hit the DHT for the initial resolution.
483
Alternatively, we could republish the last record periodically.
484
598
----
599
-
485
## QUIC
486
487
### In Version
@@ -605,7 +490,7 @@ run your daemon with the `--enable-namesys-pubsub` flag; enables pubsub.
490
491
### State
492
608
-Experiment, disabled by default
493
+Candidate, disabled by default but it will be enabled by default in 0.6.0.
494
495
### How to enable
496
@@ -643,31 +528,16 @@ Automatically discovers relays and advertises relay addresses when the node is b
528
Modify your ipfs config:
529
530
```
531
+ipfs config --json Swarm.EnableRelayHop false
532
ipfs config --json Swarm.EnableAutoRelay true
533
```
534
649
-Bootstrappers (and other public nodes) need to also enable the AutoNATService:
650
-```
651
-ipfs config --json Swarm.EnableAutoNATService true
652
-```
535
+NOTE: Ensuring `Swarm.EnableRelayHop` is _false_ is extremely important here. If you set it to true, you will _act_ as a public relay for the rest of the network instead of _using_ the public relays.
536
537
### Road to being a real feature
538
539
- [ ] needs testing
540
658
-
659
-## TLS 1.3 as default handshake protocol
660
-
661
-### In Version
662
-
663
-0.5.0
664
-
665
-### State
666
-
667
-Stable
668
-
669
----
670
-
541
## Strategic Providing
542
543
### State
@@ -694,8 +564,6 @@ ipfs config --json Experimental.StrategicProviding true
564
- [ ] provide all
565
- [ ] provide strategic
566
697
----
698
-
567
## GraphSync
568
569
### State