Skip to content

Commit

Permalink
fix: update delegate routing docs
Browse files Browse the repository at this point in the history 
fixes #1752
  • Loading branch information
@2color
2color committed Jan 31, 2024
1 parent 0427b6e commit 2c15a63
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 15 deletions.
8 changes: 6 additions & 2 deletions docs/concepts/glossary.md
View file
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
### 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

Expand Down
25 changes: 12 additions & 13 deletions docs/concepts/nodes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

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

View workflow job for this annotation

GitHub Actions / vale

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

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

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 @@ 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

Expand Down Expand Up @@ -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.

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

View workflow job for this annotation

GitHub Actions / vale

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

[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": 80, "column": 4}}}, "severity": "ERROR"}

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

View workflow job for this annotation

GitHub Actions / vale

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

[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": 80, "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) 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

Expand Down

0 comments on commit 2c15a63

Please sign in to comment.