Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: update delegated routing docs #1802

Merged
merged 5 commits into from
Feb 7, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions docs/concepts/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
### Delegated 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 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/).

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.

[More about delegated routing](../concepts/nodes.md#types)

### DHT

Expand Down
31 changes: 13 additions & 18 deletions docs/concepts/nodes.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

# 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 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.

Expand All @@ -28,7 +28,7 @@

- [Relay](#relay)
- [Bootstrap](#bootstrap)
- [Delegate routing](#delegate-routing-node)
- [Delegated Routing](#delegated-routing)

### Relay

Expand All @@ -47,13 +47,12 @@

#### 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)

### 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:

Expand All @@ -67,25 +66,21 @@

[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

- 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/)
- [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`.

Check failure on line 79 in docs/concepts/nodes.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/concepts/nodes.md#L79

[ipfs-docs-style.PLNSpelling] Did you really mean 'someguy'?
Raw output
{"message": "[ipfs-docs-style.PLNSpelling] Did you really mean 'someguy'?", "location": {"path": "docs/concepts/nodes.md", "range": {"start": {"line": 79, "column": 4}}}, "severity": "ERROR"}

Check failure on line 79 in docs/concepts/nodes.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/concepts/nodes.md#L79

[ipfs-docs-style.PLNSpelling] Did you really mean 'someguy'?
Raw output
{"message": "[ipfs-docs-style.PLNSpelling] Did you really mean 'someguy'?", "location": {"path": "docs/concepts/nodes.md", "range": {"start": {"line": 79, "column": 273}}}, "severity": "ERROR"}
- 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](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

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)
Loading