From 2c15a631799a2e7dc80e00a7ad7f829a9d216329 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Wed, 31 Jan 2024 16:27:31 +0100 Subject: [PATCH 1/5] fix: update delegate routing docs fixes #1752 --- docs/concepts/glossary.md | 8 ++++++-- docs/concepts/nodes.md | 25 ++++++++++++------------- 2 files changed, 18 insertions(+), 15 deletions(-) diff --git a/docs/concepts/glossary.md b/docs/concepts/glossary.md index 91dce487a..a46137ada 100644 --- a/docs/concepts/glossary.md +++ b/docs/concepts/glossary.md @@ -164,9 +164,13 @@ The Datastore is the on-disk storage system used by an IPFS node. Configuration Direct Connection Upgrade through Relay (DCUtR) protocol enables [hole punching](#hole-punching) for NAT traversal when port forwarding is not possible. A peer will coordinate with the counterparty using a [relayed connection](#circuit-relay-v2), to upgrade to a direct connection through a NAT/firewall whenever possible. [More about DCUtR](https://github.com/libp2p/specs/blob/master/relay/DCUtR.md) -### Delegate routing node +### Delegate routing -[Kubo](#kubo) nodes with a subset of RPC API commands exposed. JS-IPFS nodes use them to query the DHT and also publish content without having to actually run DHT logic on their own. See [Delegate routing](../concepts/nodes.md#types) +[Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/) is not a routing system but a general API to offload **content**, **peer**, and **IPNS** routing queries. + +This is useful in browsers and other constrained environments where it's infeasible to be a DHT client/server. More broadly, it enables experimentation and innovation in content routing while maintaining interoperability and modularity. + +See [Delegate routing](../concepts/nodes.md#types) ### DHT diff --git a/docs/concepts/nodes.md b/docs/concepts/nodes.md index f59b651af..0dbda4d2b 100644 --- a/docs/concepts/nodes.md +++ b/docs/concepts/nodes.md @@ -6,7 +6,7 @@ sidebarDepth: 2 # Nodes -Participants in the IPFS network are called _nodes_. A _node_ is a program or process implementing IPFS that you run on your local computer (directly or via a browser) to store files and connect to the IPFS network. They're the most crucial aspect of IPFS. Without nodes running as an IPFS _daemon_ (explained below), there would be no IPFS Network. +Participants in the IPFS network are called _nodes_. A _node_ is an instance of an implemention IPFS that you run on your local computer (directly or via a browser) to store files and connect to the IPFS network. They're the most crucial aspect of IPFS. Without IPFS nodes, there would be no IPFS Network. You're likely to see the term _node_ throughout the IPFS docs, issues, and related code. It's a very general term, so its meaning depends on the context. There are three main categories of nodes: IPFS nodes, data nodes, and libp2p nodes for applications. @@ -28,7 +28,7 @@ There are different types of IPFS nodes. And depending on the use-case, a single - [Relay](#relay) - [Bootstrap](#bootstrap) -- [Delegate routing](#delegate-routing-node) +- [Delegate routing](#delegate-routing) ### Relay @@ -67,22 +67,21 @@ Both Kubo and Helia _nodes_ use bootstrap _nodes_ to initially enter the DHT. [More about Bootstrapping](../how-to/modify-bootstrap-list.md) -### Delegate routing node +### Delegated Routing -When IPFS nodes are unable to run Distributed Hash Table (DHT) logic on their own, they _delegate_ the task to a delegate routing node. Publishing works with arbitrary CID codecs (compression/decompression technology), as the [js-libp2p-delegated-content-routing module](https://github.com/libp2p/js-libp2p-delegated-content-routing/blob/master/src/index.ts) publishes CIDs at the block level rather than the IPLD or DAG level. +IPFS nodes _delegate_ the content and peer routing tasks to a **Delegated Routing V1 HTTP API** ([spec](https://specs.ipfs.tech/routing/http-routing-v1/)). -#### Features of a delegate routing node: +Delegated routing over HTTP is not a routing system but a general API to offload routing work. This is useful in browsers and other constrained environments where it's infeasible to be a DHT server/client contacting many other peers. More broadly, it enables experimentation and innovation in content routing while maintaining interoperability. -- They are IPFS _nodes_ with their API ports exposed and some [Kubo RPC API](../reference/kubo/rpc.md) commands accessible at path `/api/v0`. -- Usable by both Kubo and Helia _nodes_. -- Helia _nodes_ can use them to query the DHT and also publish content without having to actually run DHT logic on their own. - - The libp2p _node_ configured for a Helia _node_ can be configured for delegate routing by following instructions at in the [js-libp2p configuration doc](https://github.com/libp2p/js-libp2p/blob/master/doc/CONFIGURATION.md#setup-with-content-and-peer-routing) +The [HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/) can used to resolve **content**, **peer**, and **IPNS name** routing requests. -#### Limitations of a delegate routing node: +#### Support for delegated routing in IPFS implementations + +- [someguy](https://github.com/ipfs-shipyard/someguy) is a Delegated Routing V1 server that proxies requests to the IPFS Amino DHT and the [cid.contact Network Indexer](https://cid.contact/). The IPFS Foundation operates a public good delegated routing endpoint backed by someguy with the URL https://delegated-ipfs.dev. +- The [cid.contact Network Indexer](https://cid.contact/) also implements the Delegated Routing V1 HTTP API. +- [Helia](https://github.com/ipfs/helia/tree/main/packages/http#example---with-custom-gateways-and-delegated-routing-endpoints) can be configured to use a delegated routing endpoint. +- [`Kubo`](https://github.com/ipfs/kubo/blob/master/docs/delegated-routing.md) can be configured with multiple delegated routing endpoints (Kubo as a client) in addition to exposing the delegated routing endpoint on the [gateway](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewayexposeroutingapi) (Kubo as a delegated routing server). -- On default delegate _nodes_ provided by Protocol Labs, the garbage collection happens every hour, so provided content only survives for that long. -- Only Kubo is known to implement the [Kubo RPC API](../reference/kubo/rpc.md) at the time of writing. - - There is a successor to the delegated routing functionality of the Kubo RPC API called [Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/) ## Implementations From 97c5802ef7ea2a9ae699fbbb3054226e31e2c383 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Wed, 31 Jan 2024 16:31:11 +0100 Subject: [PATCH 2/5] fix: typo --- docs/concepts/nodes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/concepts/nodes.md b/docs/concepts/nodes.md index 0dbda4d2b..239da240e 100644 --- a/docs/concepts/nodes.md +++ b/docs/concepts/nodes.md @@ -6,7 +6,7 @@ sidebarDepth: 2 # Nodes -Participants in the IPFS network are called _nodes_. A _node_ is an instance of an implemention IPFS that you run on your local computer (directly or via a browser) to store files and connect to the IPFS network. They're the most crucial aspect of IPFS. Without IPFS nodes, there would be no IPFS Network. +Participants in the IPFS network are called _nodes_. A _node_ is an instance of an implementation IPFS that you run on your local computer (directly or via a browser) to store files and connect to the IPFS network. They're the most crucial aspect of IPFS. Without IPFS nodes, there would be no IPFS Network. You're likely to see the term _node_ throughout the IPFS docs, issues, and related code. It's a very general term, so its meaning depends on the context. There are three main categories of nodes: IPFS nodes, data nodes, and libp2p nodes for applications. @@ -53,7 +53,7 @@ See [p2p-circuit relay](https://github.com/libp2p/specs/tree/master/relay) ### Bootstrap -Both Kubo and Helia _nodes_ use bootstrap _nodes_ to initially enter the DHT. +Both Kubo and Helia _nodes_ use bootstrap _nodes_ to find peers on the DHT. #### Features of a bootstrap node: From 521a50b270eece513868e3f462123d757d14cd11 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Wed, 31 Jan 2024 16:51:36 +0100 Subject: [PATCH 3/5] fix: clean implementations section --- docs/concepts/nodes.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/concepts/nodes.md b/docs/concepts/nodes.md index 239da240e..eb7d5e004 100644 --- a/docs/concepts/nodes.md +++ b/docs/concepts/nodes.md @@ -28,7 +28,7 @@ There are different types of IPFS nodes. And depending on the use-case, a single - [Relay](#relay) - [Bootstrap](#bootstrap) -- [Delegate routing](#delegate-routing) +- [Delegated Routing](#delegated-routing) ### Relay @@ -47,7 +47,6 @@ If an IPFS node deems itself unreachable by the public internet, IPFS nodes may #### Limitations of relay nodes: - v2 relays are "limited relays" that are designed to be used for [Direct Connection Upgrade through Relay](https://github.com/libp2p/specs/blob/master/relay/DCUtR.md) (aka hole punching). -- Not configurable in Kubo; uses a preset list of relays See [p2p-circuit relay](https://github.com/libp2p/specs/tree/master/relay) @@ -80,11 +79,8 @@ The [HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/) can used to res - [someguy](https://github.com/ipfs-shipyard/someguy) is a Delegated Routing V1 server that proxies requests to the IPFS Amino DHT and the [cid.contact Network Indexer](https://cid.contact/). The IPFS Foundation operates a public good delegated routing endpoint backed by someguy with the URL https://delegated-ipfs.dev. - The [cid.contact Network Indexer](https://cid.contact/) also implements the Delegated Routing V1 HTTP API. - [Helia](https://github.com/ipfs/helia/tree/main/packages/http#example---with-custom-gateways-and-delegated-routing-endpoints) can be configured to use a delegated routing endpoint. -- [`Kubo`](https://github.com/ipfs/kubo/blob/master/docs/delegated-routing.md) can be configured with multiple delegated routing endpoints (Kubo as a client) in addition to exposing the delegated routing endpoint on the [gateway](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewayexposeroutingapi) (Kubo as a delegated routing server). - +- [Kubo](https://github.com/ipfs/kubo/blob/master/docs/delegated-routing.md) can be configured with multiple delegated routing endpoints (Kubo as a client), in addition to exposing the delegated routing endpoint on the [gateway](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewayexposeroutingapi) (Kubo as a delegated routing server). ## Implementations -Protocol Labs manages two implementations of the IPFS spec: Kubo and Helia. These implementations use specific types of _nodes_ to perform server, browser, and other client functions. - -[Read more about our implementations](./ipfs-implementations.md) +[Read more about IPFS implementations](./ipfs-implementations.md) \ No newline at end of file From a098ba38d3cc4a776e344aab6445c2d01d806a48 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Fri, 2 Feb 2024 16:37:48 +0100 Subject: [PATCH 4/5] fix: use delegated routing --- docs/concepts/glossary.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/concepts/glossary.md b/docs/concepts/glossary.md index a46137ada..9f8b8bc87 100644 --- a/docs/concepts/glossary.md +++ b/docs/concepts/glossary.md @@ -164,13 +164,13 @@ The Datastore is the on-disk storage system used by an IPFS node. Configuration Direct Connection Upgrade through Relay (DCUtR) protocol enables [hole punching](#hole-punching) for NAT traversal when port forwarding is not possible. A peer will coordinate with the counterparty using a [relayed connection](#circuit-relay-v2), to upgrade to a direct connection through a NAT/firewall whenever possible. [More about DCUtR](https://github.com/libp2p/specs/blob/master/relay/DCUtR.md) -### Delegate routing +### Delegated routing -[Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/) is not a routing system but a general API to offload **content**, **peer**, and **IPNS** routing queries. +Delegated routing is a mechanism by which IPFS implementations can offload content routing, peer routing, and naming (IPNS) to another process/server. The most widely adopted vendor-agnostic spec for delegated routing is the [Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/). -This is useful in browsers and other constrained environments where it's infeasible to be a DHT client/server. More broadly, it enables experimentation and innovation in content routing while maintaining interoperability and modularity. +Delegated routing is useful in browsers and other constrained environments where it's infeasible to be a DHT client/server. More broadly, it enables experimentation and innovation in content routing while maintaining interoperability and modularity. -See [Delegate routing](../concepts/nodes.md#types) +[More about delegated routing](../concepts/nodes.md#types) ### DHT From c3d484af2110077d20833d0b520d9a6a462b8e0e Mon Sep 17 00:00:00 2001 From: Daniel Norman <1992255+2color@users.noreply.github.com> Date: Wed, 7 Feb 2024 12:41:38 +0100 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Marcin Rataj --- docs/concepts/nodes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/concepts/nodes.md b/docs/concepts/nodes.md index eb7d5e004..65e8eee47 100644 --- a/docs/concepts/nodes.md +++ b/docs/concepts/nodes.md @@ -76,10 +76,10 @@ The [HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/) can used to res #### Support for delegated routing in IPFS implementations -- [someguy](https://github.com/ipfs-shipyard/someguy) is a Delegated Routing V1 server that proxies requests to the IPFS Amino DHT and the [cid.contact Network Indexer](https://cid.contact/). The IPFS Foundation operates a public good delegated routing endpoint backed by someguy with the URL https://delegated-ipfs.dev. +- [someguy](https://github.com/ipfs-shipyard/someguy) is a Delegated Routing V1 server that proxies requests to the IPFS Amino DHT and the [cid.contact Network Indexer](https://cid.contact/). The IPFS Foundation operates a public good delegated routing endpoint backed by someguy with the URL `https://delegated-ipfs.dev/routing/v1`. - The [cid.contact Network Indexer](https://cid.contact/) also implements the Delegated Routing V1 HTTP API. - [Helia](https://github.com/ipfs/helia/tree/main/packages/http#example---with-custom-gateways-and-delegated-routing-endpoints) can be configured to use a delegated routing endpoint. -- [Kubo](https://github.com/ipfs/kubo/blob/master/docs/delegated-routing.md) can be configured with multiple delegated routing endpoints (Kubo as a client), in addition to exposing the delegated routing endpoint on the [gateway](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewayexposeroutingapi) (Kubo as a delegated routing server). +- [Kubo](https://github.com/ipfs/kubo/blob/master/docs/delegated-routing.md) can be configured with multiple delegated routing endpoints ([Kubo as a client](https://github.com/ipfs/kubo/blob/master/docs/config.md#routingtype)), in addition to exposing the delegated routing endpoint on the gateway ([Kubo as a delegated routing server](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewayexposeroutingapi)). ## Implementations