docs: add WebTransport docs
Jorropo committed
Sep 26, 2022 at 17:38 UTC
b539cd4e47e90e2b26aae13826e4b7bbc5d4ff66
2 files changed
+94
-16
docs/changelogs/v0.16.md
+32
@@ -11,6 +11,7 @@ Below is an outline of all that is in this release, so you get a sense of all th
11
- [Overview](#overview)
12
- [🔦 Highlights](#-highlights)
13
- [🛣️ More configurable delegated routing system](#️-more-configurable-delegated-routing-system)
14
+ - [🌍 WebTransport new experimental Transport](#-webtransport-new-experimental-transport)
15
- [Changelog](#changelog)
16
- [Contributors](#contributors)
17
@@ -85,6 +86,37 @@ $ ipfs config Routing.Methods --json '{
86
87
```
88
89
+### 🌍 WebTransport new experimental Transport
90
+
91
+A new feature of [`go-libp2p`](https://github.com/libp2p/go-libp2p/releases/tag/v0.23.0) is [WebTransport](https://github.com/libp2p/go-libp2p/issues/1717).
92
+
93
+For now it is **disabled by default** and considered **experimental**.
94
+If you find issues running it please [report them to us](https://github.com/ipfs/kubo/issues/new).
95
+
96
+In the future Kubo will listen on WebTransport by default for anyone already listening on QUIC addresses.
97
+
98
+WebTransport is a new transport protocol currently under development by the [IETF](https://datatracker.ietf.org/wg/webtrans/about/) and the [W3C](https://www.w3.org/TR/webtransport/), and [already implemented by Chrome](https://caniuse.com/webtransport).
99
+Conceptually, it’s like WebSocket run over QUIC instead of TCP. Most importantly, it allows browsers to establish (secure!) connections to WebTransport servers without the need for CA-signed certificates,
100
+thereby enabling any js-libp2p node running in a browser to connect to any kubo node, with zero manual configuration involved.
101
+
102
+The previous alternative is websocket secure, which require installing a reverse proxy and TLS certificates manually.
103
+
104
+#### How to enable WebTransport
105
+
106
+Thoses steps are temporary and wont be needed once we make it enabled by default.
107
+
108
+1. Enable the WebTransport transport:
109
+ `ipfs config Swarm.Transports.Network.WebTransport --json true`
110
+1. Add a listener address for WebTransport to your `Addresses.Swarm` key, for example:
111
+ ```json
112
+ [
113
+ "/ip4/0.0.0.0/tcp/4001",
114
+ "/ip4/0.0.0.0/udp/4001/quic",
115
+ "/ip4/0.0.0.0/udp/4002/quic/webtransport"
116
+ ]
117
+ ```
118
+1. Restart your daemon to apply the config changes.
119
+
120
### Changelog
121
122
<!-- TODO -->
docs/config.md
+62
-16
@@ -148,6 +148,8 @@ config file at runtime.
148
- [`Swarm.Transports.Network.Websocket`](#swarmtransportsnetworkwebsocket)
149
- [`Swarm.Transports.Network.QUIC`](#swarmtransportsnetworkquic)
150
- [`Swarm.Transports.Network.Relay`](#swarmtransportsnetworkrelay)
151
+ - [`Swarm.Transports.Network.WebTransport`](#swarmtransportsnetworkwebtransport)
152
+ - [`How to enable WebTransport`](#how-to-enable-webtransport)
153
- [`Swarm.Transports.Security`](#swarmtransportssecurity)
154
- [`Swarm.Transports.Security.TLS`](#swarmtransportssecuritytls)
155
- [`Swarm.Transports.Security.SECIO`](#swarmtransportssecuritysecio)
@@ -205,7 +207,7 @@ documented in `ipfs config profile --help`.
207
208
Configures the node to use the flatfs datastore. Flatfs is the default datastore.
209
208
- This is the most battle-tested and reliable datastore.
210
+ This is the most battle-tested and reliable datastore.
211
You should use this datastore if:
212
213
- You need a very simple and very reliable datastore, and you trust your
@@ -223,9 +225,9 @@ documented in `ipfs config profile --help`.
225
226
Configures the node to use the experimental badger datastore. Keep in mind that this **uses an outdated badger 1.x**.
227
226
- Use this datastore if some aspects of performance,
228
+ Use this datastore if some aspects of performance,
229
especially the speed of adding many gigabytes of files, are critical. However, be aware that:
228
-
230
+
231
- This datastore will not properly reclaim space when your datastore is
232
smaller than several gigabytes. If you run IPFS with `--enable-gc`, you plan on storing very little data in
233
your IPFS node, and disk usage is more critical than performance, consider using
@@ -358,6 +360,7 @@ Supported Transports:
360
* tcp/ip{4,6} - `/ipN/.../tcp/...`
361
* websocket - `/ipN/.../tcp/.../ws`
362
* quic - `/ipN/.../udp/.../quic`
363
+* webtransport (*experiemental*) - `/ipN/.../udp/.../quic/webtransport` - require using a different port than the QUIC listener for now
364
365
Default:
366
```json
@@ -804,17 +807,17 @@ Below is a list of the most common public gateway setups.
807
}'
808
```
809
- **Backward-compatible:** this feature enables automatic redirects from content paths to subdomains:
807
-
810
+
811
`http://dweb.link/ipfs/{cid}` → `http://{cid}.ipfs.dweb.link`
809
-
812
+
813
- **X-Forwarded-Proto:** if you run Kubo behind a reverse proxy that provides TLS, make it add a `X-Forwarded-Proto: https` HTTP header to ensure users are redirected to `https://`, not `http://`. It will also ensure DNSLink names are inlined to fit in a single DNS label, so they work fine with a wildcart TLS cert ([details](https://github.com/ipfs/in-web-browsers/issues/169)). The NGINX directive is `proxy_set_header X-Forwarded-Proto "https";`.:
811
-
814
+
815
`http://dweb.link/ipfs/{cid}` → `https://{cid}.ipfs.dweb.link`
813
-
816
+
817
`http://dweb.link/ipns/your-dnslink.site.example.com` → `https://your--dnslink-site-example-com.ipfs.dweb.link`
815
-
818
+
819
- **X-Forwarded-Host:** we also support `X-Forwarded-Host: example.com` if you want to override subdomain gateway host from the original request:
817
-
820
+
821
`http://dweb.link/ipfs/{cid}` → `http://{cid}.ipfs.example.com`
822
823
@@ -839,7 +842,7 @@ Below is a list of the most common public gateway setups.
842
Disable fetching of remote data (`NoFetch: true`) and resolving DNSLink at unknown hostnames (`NoDNSLink: true`).
843
Then, enable DNSLink gateway only for the specific hostname (for which data
844
is already present on the node), without exposing any content-addressing `Paths`:
842
-
845
+
846
```console
847
$ ipfs config --json Gateway.NoFetch true
848
$ ipfs config --json Gateway.NoDNSLink true
@@ -871,7 +874,7 @@ Type: `string` (base64 encoded)
874
875
This section includes internal knobs for various subsystems to allow advanced users with big or private infrastructures to fine-tune some behaviors without the need to recompile Kubo.
876
874
-**Be aware that making informed change here requires in-depth knowledge and most users should leave these untouched. All knobs listed here are subject to breaking changes between versions.**
877
+**Be aware that making informed change here requires in-depth knowledge and most users should leave these untouched. All knobs listed here are subject to breaking changes between versions.**
878
879
### `Internal.Bitswap`
880
@@ -1317,7 +1320,7 @@ Parallel:
1320
- `ExecuteAfter:duration`: Providing this param will delay the execution of that router at the specified time. It accepts strings compatible with Go `time.ParseDuration(string)` (`10s`, `1m`, `2h`).
1321
- `IgnoreErrors:bool`: It will specify if that router should be ignored if an error occurred.
1322
- `Timeout:duration`: Global timeout. It accepts strings compatible with Go `time.ParseDuration(string)` (`10s`, `1m`, `2h`).
1320
-
1323
+
1324
Sequential:
1325
- `Routers`: A list of routers that will be executed in order:
1326
- `Name:string`: Name of the router. It should be one of the previously added to `Routers` list.
@@ -1346,7 +1349,7 @@ Type: `object[string->string]`
1349
1350
### `Routing: Methods`
1351
1349
-`Methods:map` will define which routers will be executed per method. The key will be the name of the method: `"provide"`, `"find-providers"`, `"find-peers"`, `"put-ipns"`, `"get-ipns"`. All methods must be added to the list.
1352
+`Methods:map` will define which routers will be executed per method. The key will be the name of the method: `"provide"`, `"find-providers"`, `"find-peers"`, `"put-ipns"`, `"get-ipns"`. All methods must be added to the list.
1353
1354
The value will contain:
1355
- `RouterName:string`: Name of the router. It should be one of the previously added to `Routing.Routers` list.
@@ -1619,7 +1622,7 @@ Type: `optionalInteger`
1622
1623
#### `Swarm.RelayService.ReservationTTL`
1624
1622
-Duration of a new or refreshed reservation.
1625
+Duration of a new or refreshed reservation.
1626
1627
Default: `"1h"`
1628
@@ -1858,7 +1861,7 @@ Configuration section for libp2p _network_ transports. Transports enabled in
1861
this section will be used for dialing. However, to receive connections on these
1862
transports, multiaddrs for these transports must be added to `Addresses.Swarm`.
1863
1861
-Supported transports are: QUIC, TCP, WS, and Relay.
1864
+Supported transports are: QUIC, TCP, WS, Relay and WebTransport.
1865
1866
Each field in this section is a `flag`.
1867
@@ -1934,6 +1937,49 @@ Listen Addresses:
1937
* This transport is special. Any node that enables this transport can receive
1938
inbound connections on this transport, without specifying a listen address.
1939
1940
+
1941
+#### `Swarm.Transports.Network.WebTransport`
1942
+
1943
+A new feature of [`go-libp2p`](https://github.com/libp2p/go-libp2p/releases/tag/v0.23.0)
1944
+is the [WebTransport](https://github.com/libp2p/go-libp2p/issues/1717) transport.
1945
+
1946
+This is a spiritual descendant of WebSocket but over `HTTP/3`.
1947
+Since this runs on top of `HTTP/3` it uses `QUIC` under the hood.
1948
+We expect it to perform worst than `QUIC` because of the extra overhead,
1949
+this transport is really meant at agents that cannot do `TCP` or `QUIC` (like browsers).
1950
+
1951
+For now it is **disabled by default** and considered **experimental**.
1952
+If you find issues running it please [report them to us](https://github.com/ipfs/kubo/issues/new).
1953
+
1954
+In the future Kubo will listen on WebTransport by default for anyone already listening on QUIC addresses.
1955
+
1956
+WebTransport is a new transport protocol currently under development by the IETF and the W3C, and already implemented by Chrome.
1957
+Conceptually, it’s like WebSocket run over QUIC instead of TCP. Most importantly, it allows browsers to establish (secure!) connections to WebTransport servers without the need for CA-signed certificates,
1958
+thereby enabling any js-libp2p node running in a browser to connect to any kubo node, with zero manual configuration involved.
1959
+
1960
+The previous alternative is websocket secure, which require installing a reverse proxy and TLS certificates manually.
1961
+
1962
+Default: Disabled
1963
+
1964
+Type: `flag`
1965
+
1966
+
1967
+#### How to enable WebTransport
1968
+
1969
+Thoses steps are temporary and wont be needed once we make it enabled by default.
1970
+
1971
+1. Enable the WebTransport transport:
1972
+ `ipfs config Swarm.Transports.Network.WebTransport --json true`
1973
+1. Add a listener address for WebTransport to your `Addresses.Swarm` key, for example:
1974
+ ```json
1975
+ [
1976
+ "/ip4/0.0.0.0/tcp/4001",
1977
+ "/ip4/0.0.0.0/udp/4001/quic",
1978
+ "/ip4/0.0.0.0/udp/4002/quic/webtransport"
1979
+ ]
1980
+ ```
1981
+1. Restart your daemon to apply the config changes.
1982
+
1983
### `Swarm.Transports.Security`
1984
1985
Configuration section for libp2p _security_ transports. Transports enabled in
@@ -2071,4 +2117,4 @@ Note: this does NOT work with Go's default DNS resolver. To make this a global s
2117
2118
Default: Respect DNS Response TTL
2119
2074
-Type: `optionalDuration`
\ No newline at end of file
2120
+Type: `optionalDuration`