diff --git a/docs/changelogs/v0.23.md b/docs/changelogs/v0.23.md index 701f05701..6085c21c7 100644 --- a/docs/changelogs/v0.23.md +++ b/docs/changelogs/v0.23.md @@ -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 diff --git a/docs/experimental-features.md b/docs/experimental-features.md index 52bfe703d..6527f883b 100644 --- a/docs/experimental-features.md +++ b/docs/experimental-features.md @@ -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 \ No newline at end of file +- [ ] 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))