coosld/kubo
1
0
Fork 0
mirror of https://github.com/ipfs/kubo.git synced 2026-02-21 10:27:46 +08:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

docs: gateway-http-over-libp2p

Browse Source
This commit is contained in:
Marcin Rataj 2023-09-06 02:57:14 +02:00
parent 1efd9d47aa
commit 8d28507814
No known key found for this signature in database
GPG Key ID: 222B6784D5A79E42
2 changed files with 33 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
docs/changelogs/v0.23.md
View File

@ -10,7 +10,7 @@
- [Gateway: meaningful CAR responses on Not Found errors](#gateway-meaningful-car-responses-on-not-found-errors)
- [Binary characters in file names: no longer works with old clients and new Kubo servers](#binary-characters-in-file-names-no-longer-works-with-old-clients-and-new-kubo-servers)
- [Self-hosting `/routing/v1` endpoint for delegated routing needs](#self-hosting-routingv1-endpoint-for-delegated-routing-needs)
- [Gateway Over Libp2p Experiment](#gateway-over-libp2p-experiment)
- [Trustless Gateway Over Libp2p Experiment](#trustless-gateway-over-libp2p-experiment)
- [📝 Changelog](#-changelog)
- [👨‍👩‍👧‍👦 Contributors](#-contributors)
@ -68,19 +68,20 @@ HTTP [Routing V1](https://specs.ipfs.tech/routing/http-routing-v1/) API endpoint
self-hosting and experimentation with custom delegated routers. This is disabled by default,
but can be enabled by setting [`Gateway.ExposeRoutingAPI`](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewayexposeroutingapi) to `true` .
#### Gateway Over Libp2p Experiment
#### Trustless Gateway Over Libp2p Experiment
It is now possible to serve [Trustless Gateway API](https://specs.ipfs.tech/http-gateways/trustless-gateway/) responses
such as for blocks and CARs over libp2p. This takes advantage of the [specification work](https://github.com/libp2p/specs/pull/508)
in libp2p expanding beyond the basics of performing HTTP requests over libp2p streams that have been available in libp2p
and in kubo experimental features such as [p2p-http-proxy](https://github.com/ipfs/kubo/blob/master/docs/experimental-features.md#p2p-http-proxy).
In this update, we've introduced an experimental opt-in feature allowing users to
serve a subset of [Trustless Gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/) responses,
such as blocks and CARs, over libp2p. This enhancement leverages the ongoing
[`/http/1.1` specification work in libp2p](https://github.com/libp2p/specs/pull/508)
to make it easier to support HTTP semantics over libp2p streams.
This means that implementations that want to use the Trustless Gateway API as a data transport mechanism can do so even
when standard HTTP transports would fail (e.g. when the endpoint is behind a firewall, or wants to serve data to a browser
but does not have a CA certificate).
This development means that if users wish to utilize the Trustless Gateway API
for data transport, they can now do so even in scenarios where standard HTTP
might be problematic, such as when the endpoint is behind a firewall or when
attempting to serve data to a browser without a CA certificate.
See [HTTP Gateway over Libp2p](https://github.com/ipfs/kubo/blob/master/docs/experimental-features.md#http-gateway-over-libp2p)
for more details.
See [HTTP Gateway over Libp2p](https://github.com/ipfs/kubo/blob/master/docs/experimental-features.md#http-gateway-over-libp2p) for details about this experiment.
### 📝 Changelog

33
docs/experimental-features.md
View File

@ -629,19 +629,25 @@ ipfs config --json Experimental.OptimisticProvideJobsPoolSize 120
Experimental, disabled by default.
Enables serving the [IPFS HTTP Gateway](https://specs.ipfs.tech/http-gateways/) protocol over libp2p transports and
as described in the [specification](https://github.com/ipfs/specs/pull/434).
Enables serving a subset of the [IPFS HTTP Gateway](https://specs.ipfs.tech/http-gateways/) semantics over libp2p `/http/1.1` protocol.
Notes:
- This feature currently is only about serving the gateway requests over libp2p, not about fetching data this way using
[Trustless Gateway Specification](https://specs.ipfs.tech/http-gateways/trustless-gateway/).
- While kubo currently mounts the gateway API at the root (i.e. `/`) of the libp2p `/http/1.1` protocol that is subject to
change. The way to reliably discover where a given HTTP protocol is mounted on a libp2p endpoint is via the `.well-known/libp2p`
resource specified in the [http+libp2p specification](https://github.com/libp2p/specs/pull/508)
- Kubo currently hard codes the gateway-over-libp2p behavior to:
- Only operate on `/ipfs` resources
- Only satisfy the Trustless Gateway API
- Only serve data that is already local to the node (i.e. similar to a `NoFetch` gateway)
- This feature only about serving verifiable gateway requests over libp2p:
- Deserialized responses are not supported.
- Only operate on `/ipfs` resources (no `/ipns` atm)
- Only support requests for `application/vnd.ipld.raw` and
`application/vnd.ipld.car` (from [Trustless Gateway Specification](https://specs.ipfs.tech/http-gateways/trustless-gateway/),
where data integrity can be verified).
- Only serve data that is already local to the node (i.e. similar to a
[`Gateway.NoFetch`](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewaynofetch))
- While Kubo currently mounts the gateway API at the root (i.e. `/`) of the
libp2p `/http/1.1` protocol, that is subject to change.
- The way to reliably discover where a given HTTP protocol is mounted on a
libp2p endpoint is via the `.well-known/libp2p` resource specified in the
[http+libp2p specification](https://github.com/libp2p/specs/pull/508)
- The identifier of the protocol mount point under `/http/1.1` listener is
`/ipfs/gateway`, as noted in
[ipfs/specs#434](https://github.com/ipfs/specs/pull/434).
### How to enable
@ -653,4 +659,7 @@ ipfs config --json Experimental.GatewayOverLibp2p true
### Road to being a real feature
- [ ] Needs more people to use and report on how well it works
- [ ] Needs more people to use and report on how well it works
- [ ] Needs UX work for exposing non-recursive "HTTP transport" (NoFetch) over both libp2p and plain TCP (and sharing the configuration)
- [ ] Needs a mechanism for HTTP handler to signal supported features ([IPIP-425](https://github.com/ipfs/specs/pull/425))
- [ ] Needs an option for Kubo to detect peers that have it enabled and prefer HTTP transport before falling back to bitswap (and use CAR if peer supports dag-scope=entity from [IPIP-402](https://github.com/ipfs/specs/pull/402))