@cryptotaxi247 / kubo / commits / 8d2850781

docs: gateway-http-over-libp2p

Marcin Rataj committed Sep 6, 2023 at 02:57 UTC 8d28507814021d9705ea9d2d5480f6e580237cf6
2 files changed +33 -23
docs/changelogs/v0.23.md
+12 -11
@@ -10,7 +10,7 @@
10 - [Gateway: meaningful CAR responses on Not Found errors](#gateway-meaningful-car-responses-on-not-found-errors)
11 - [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)
12 - [Self-hosting `/routing/v1` endpoint for delegated routing needs](#self-hosting-routingv1-endpoint-for-delegated-routing-needs)
13 - - [Gateway Over Libp2p Experiment](#gateway-over-libp2p-experiment)
13 + - [Trustless Gateway Over Libp2p Experiment](#trustless-gateway-over-libp2p-experiment)
14 - [📝 Changelog](#-changelog)
15 - [👨‍👩‍👧‍👦 Contributors](#-contributors)
16
@@ -68,19 +68,20 @@ HTTP [Routing V1](https://specs.ipfs.tech/routing/http-routing-v1/) API endpoint
68 self-hosting and experimentation with custom delegated routers. This is disabled by default,
69 but can be enabled by setting [`Gateway.ExposeRoutingAPI`](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewayexposeroutingapi) to `true` .
70
71 -#### Gateway Over Libp2p Experiment
71 +#### Trustless Gateway Over Libp2p Experiment
72
73 -It is now possible to serve [Trustless Gateway API](https://specs.ipfs.tech/http-gateways/trustless-gateway/) responses
74 -such as for blocks and CARs over libp2p. This takes advantage of the [specification work](https://github.com/libp2p/specs/pull/508)
75 -in libp2p expanding beyond the basics of performing HTTP requests over libp2p streams that have been available in libp2p
76 -and in kubo experimental features such as [p2p-http-proxy](https://github.com/ipfs/kubo/blob/master/docs/experimental-features.md#p2p-http-proxy).
73 +In this update, we've introduced an experimental opt-in feature allowing users to
74 +serve a subset of [Trustless Gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/) responses,
75 +such as blocks and CARs, over libp2p. This enhancement leverages the ongoing
76 +[`/http/1.1` specification work in libp2p](https://github.com/libp2p/specs/pull/508)
77 +to make it easier to support HTTP semantics over libp2p streams.
78
78 -This means that implementations that want to use the Trustless Gateway API as a data transport mechanism can do so even
79 -when standard HTTP transports would fail (e.g. when the endpoint is behind a firewall, or wants to serve data to a browser
80 -but does not have a CA certificate).
79 +This development means that if users wish to utilize the Trustless Gateway API
80 +for data transport, they can now do so even in scenarios where standard HTTP
81 +might be problematic, such as when the endpoint is behind a firewall or when
82 +attempting to serve data to a browser without a CA certificate.
83
82 -See [HTTP Gateway over Libp2p](https://github.com/ipfs/kubo/blob/master/docs/experimental-features.md#http-gateway-over-libp2p)
83 -for more details.
84 +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.
85
86 ### 📝 Changelog
87
docs/experimental-features.md
+21 -12
@@ -629,19 +629,25 @@ ipfs config --json Experimental.OptimisticProvideJobsPoolSize 120
629
630 Experimental, disabled by default.
631
632 -Enables serving the [IPFS HTTP Gateway](https://specs.ipfs.tech/http-gateways/) protocol over libp2p transports and
633 -as described in the [specification](https://github.com/ipfs/specs/pull/434).
632 +Enables serving a subset of the [IPFS HTTP Gateway](https://specs.ipfs.tech/http-gateways/) semantics over libp2p `/http/1.1` protocol.
633
634 Notes:
636 -- This feature currently is only about serving the gateway requests over libp2p, not about fetching data this way using
637 -[Trustless Gateway Specification](https://specs.ipfs.tech/http-gateways/trustless-gateway/).
638 -- While kubo currently mounts the gateway API at the root (i.e. `/`) of the libp2p `/http/1.1` protocol that is subject to
639 -change. The way to reliably discover where a given HTTP protocol is mounted on a libp2p endpoint is via the `.well-known/libp2p`
640 -resource specified in the [http+libp2p specification](https://github.com/libp2p/specs/pull/508)
641 -- Kubo currently hard codes the gateway-over-libp2p behavior to:
642 - - Only operate on `/ipfs` resources
643 - - Only satisfy the Trustless Gateway API
644 - - Only serve data that is already local to the node (i.e. similar to a `NoFetch` gateway)
635 +- This feature only about serving verifiable gateway requests over libp2p:
636 + - Deserialized responses are not supported.
637 + - Only operate on `/ipfs` resources (no `/ipns` atm)
638 + - Only support requests for `application/vnd.ipld.raw` and
639 + `application/vnd.ipld.car` (from [Trustless Gateway Specification](https://specs.ipfs.tech/http-gateways/trustless-gateway/),
640 + where data integrity can be verified).
641 + - Only serve data that is already local to the node (i.e. similar to a
642 + [`Gateway.NoFetch`](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewaynofetch))
643 +- While Kubo currently mounts the gateway API at the root (i.e. `/`) of the
644 + libp2p `/http/1.1` protocol, that is subject to change.
645 + - The way to reliably discover where a given HTTP protocol is mounted on a
646 + libp2p endpoint is via the `.well-known/libp2p` resource specified in the
647 + [http+libp2p specification](https://github.com/libp2p/specs/pull/508)
648 + - The identifier of the protocol mount point under `/http/1.1` listener is
649 + `/ipfs/gateway`, as noted in
650 + [ipfs/specs#434](https://github.com/ipfs/specs/pull/434).
651
652 ### How to enable
653
@@ -653,4 +659,7 @@ ipfs config --json Experimental.GatewayOverLibp2p true
659
660 ### Road to being a real feature
661
656 -- [ ] Needs more people to use and report on how well it works
\ No newline at end of file
662 +- [ ] Needs more people to use and report on how well it works
663 +- [ ] Needs UX work for exposing non-recursive "HTTP transport" (NoFetch) over both libp2p and plain TCP (and sharing the configuration)
664 +- [ ] Needs a mechanism for HTTP handler to signal supported features ([IPIP-425](https://github.com/ipfs/specs/pull/425))
665 +- [ ] 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))