From 447109df6423898edb7bcf86a534606df3945d6d Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Sun, 11 Jan 2026 00:39:30 +0100 Subject: [PATCH] docs: clarify Routing.Type=custom as experimental (#11111) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: mark custom routing as experimental reorganize Routing.Type section for clarity, group production and experimental options, consolidate DHT explanation, add limitations section to delegated-routing.md documenting that HTTP-only routing cannot provide content reliably * chore(config): reorder Routing sections and improve callout formatting move DelegatedRouters after Type, add config option names to CAUTION headers * docs: address reviewer feedback on config.md - clarify that `auto` can be combined with custom URLs in `Routing.DelegatedRouters` - rename headers for consistency: `Routing.Routers.[name].Type`, `Routing.Routers.[name].Parameters`, `Routing.Methods` - replace deprecated Strategic Providing reference with `Provide.*` config - remove outdated caveat about 0.39 sweep limitation - wording: "likely suffer" → "will be most affected" * docs: remove redundant Summary section from delegated-routing.md the IMPORTANT callout and Motivation section already cover what users need to know. historical version info was noise for researchers trying to configure custom routing. addresses reviewer feedback from #11111. --------- Co-authored-by: Daniel Norman <2color@users.noreply.github.com> Co-authored-by: Andrew Gillis <11790789+gammazero@users.noreply.github.com> --- docs/config.md | 180 +++++++++++++++++++------------------- docs/delegated-routing.md | 63 ++++++++----- routing/delegated.go | 7 ++ 3 files changed, 139 insertions(+), 111 deletions(-) diff --git a/docs/config.md b/docs/config.md index 9d41ef4e5..986798296 100644 --- a/docs/config.md +++ b/docs/config.md @@ -157,14 +157,14 @@ config file at runtime. - [`Reprovider.Strategy`](#providestrategy) - [`Routing`](#routing) - [`Routing.Type`](#routingtype) + - [`Routing.DelegatedRouters`](#routingdelegatedrouters) - [`Routing.AcceleratedDHTClient`](#routingaccelerateddhtclient) - [`Routing.LoopbackAddressesOnLanDHT`](#routingloopbackaddressesonlandht) - [`Routing.IgnoreProviders`](#routingignoreproviders) - - [`Routing.DelegatedRouters`](#routingdelegatedrouters) - [`Routing.Routers`](#routingrouters) - - [`Routing.Routers: Type`](#routingrouters-type) - - [`Routing.Routers: Parameters`](#routingrouters-parameters) - - [`Routing: Methods`](#routing-methods) + - [`Routing.Routers.[name].Type`](#routingroutersnametype) + - [`Routing.Routers.[name].Parameters`](#routingroutersnameparameters) + - [`Routing.Methods`](#routingmethods) - [`Swarm`](#swarm) - [`Swarm.AddrFilters`](#swarmaddrfilters) - [`Swarm.DisableBandwidthMetrics`](#swarmdisablebandwidthmetrics) @@ -2575,58 +2575,70 @@ Contains options for content, peer, and IPNS routing mechanisms. ### `Routing.Type` -There are multiple routing options: "auto", "autoclient", "none", "dht", "dhtclient", "delegated", and "custom". +Controls how your node discovers content and peers on the network. -- **DEFAULT:** If unset, or set to "auto", your node will use the public IPFS DHT (aka "Amino") - and parallel [`Routing.DelegatedRouters`](#routingdelegatedrouters) for additional speed. +**Production options:** -- If set to "autoclient", your node will behave as in "auto" but without running a DHT server. +- **`auto`** (default): Uses both the public IPFS DHT (Amino) and HTTP routers + from [`Routing.DelegatedRouters`](#routingdelegatedrouters) for faster lookups. + Your node starts as a DHT client and automatically switches to server mode + when reachable from the public internet. -- If set to "none", your node will use _no_ routing system. You'll have to - explicitly connect to peers that have the content you're looking for. +- **`autoclient`**: Same as `auto`, but never runs a DHT server. + Use this if your node is behind a firewall or NAT. -- If set to "dht" (or "dhtclient"/"dhtserver"), your node will ONLY use the Amino DHT (no HTTP routers). +- **`dht`**: Uses only the Amino DHT (no HTTP routers). Automatically switches + between client and server mode based on reachability. -- If set to "custom", all default routers are disabled, and only ones defined in `Routing.Routers` will be used. +- **`dhtclient`**: DHT-only, always running as a client. Lower resource usage. -When the DHT is enabled, it can operate in two modes: client and server. +- **`dhtserver`**: DHT-only, always running as a server. + Only use this if your node is reachable from the public internet. -- In server mode, your node will query other peers for DHT records, and will - respond to requests from other peers (both requests to store records and - requests to retrieve records). +- **`none`**: Disables all routing. You must manually connect to peers. -- In client mode, your node will query the DHT as a client but will not respond - to requests from other peers. This mode is less resource-intensive than server - mode. +**About DHT client vs server mode:** +When the DHT is enabled, your node can operate as either a client or server. +In server mode, it queries other peers and responds to their queries - this helps +the network but uses more resources. In client mode, it only queries others without +responding, which is less resource-intensive. With `auto` or `dht`, your node starts +as a client and switches to server when it detects public reachability. -When `Routing.Type` is set to `auto` or `dht`, your node will start as a DHT client, and -switch to a DHT server when and if it determines that it's reachable from the -public internet (e.g., it's not behind a firewall). +> [!CAUTION] +> **`Routing.Type` Experimental options:** +> +> These modes are for research and testing only, not production use. +> They may change without notice between releases. +> +> - **`delegated`**: Uses only HTTP routers from [`Routing.DelegatedRouters`](#routingdelegatedrouters) +> and IPNS publishers from [`Ipns.DelegatedPublishers`](#ipnsdelegatedpublishers), +> without initializing the DHT. Useful when peer-to-peer connectivity is unavailable. +> Note: cannot provide content to the network (no DHT means no provider records). +> +> - **`custom`**: Disables all default routers. You define your own routing in +> [`Routing.Routers`](#routingrouters). See [delegated-routing.md](delegated-routing.md). -To force a specific Amino DHT-only mode, client or server, set `Routing.Type` to -`dhtclient` or `dhtserver` respectively. Please do not set this to `dhtserver` -unless you're sure your node is reachable from the public network. - -When `Routing.Type` is set to `auto` or `autoclient` your node will accelerate some types of routing -by leveraging [`Routing.DelegatedRouters`](#routingdelegatedrouters) HTTP endpoints compatible with [Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/) -introduced in [IPIP-337](https://github.com/ipfs/specs/pull/337) -in addition to the Amino DHT. - -When `Routing.Type` is set to `delegated`, your node will use **only** HTTP delegated routers and IPNS publishers, -without initializing the Amino DHT at all. This mode is useful for environments where peer-to-peer DHT connectivity -is not available or desired, while still enabling content routing and IPNS publishing via HTTP APIs. -This mode requires configuring [`Routing.DelegatedRouters`](#routingdelegatedrouters) for content routing and -[`Ipns.DelegatedPublishers`](#ipnsdelegatedpublishers) for IPNS publishing. - -**Note:** `delegated` mode operates as read-only for content providing - your node cannot announce content to the network -since there is no DHT connectivity. Content providing is automatically disabled when using this routing type. - -[Advanced routing rules](https://github.com/ipfs/kubo/blob/master/docs/delegated-routing.md) can be configured in `Routing.Routers` after setting `Routing.Type` to `custom`. - -Default: `auto` (DHT + [`Routing.DelegatedRouters`](#routingdelegatedrouters)) +Default: `auto` Type: `optionalString` (`null`/missing means the default) +### `Routing.DelegatedRouters` + +An array of URL hostnames for delegated routers to be queried in addition to the Amino DHT when `Routing.Type` is set to `auto` (default) or `autoclient`. +These endpoints must support the [Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/). + +The special value `"auto"` uses delegated routers from [AutoConf](#autoconf) when enabled. +You can combine `"auto"` with custom URLs (e.g., `["auto", "https://custom.example.com"]`) to query both the default delegated routers and your own endpoints. The first `"auto"` entry gets substituted with autoconf values, and other URLs are preserved. + +> [!TIP] +> Delegated routing allows IPFS implementations to offload tasks like content routing, peer routing, and naming to a separate process or server while also benefiting from HTTP caching. +> +> One can run their own delegated router either by implementing the [Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/) themselves, or by using [Someguy](https://github.com/ipfs/someguy), a turn-key implementation that proxies requests to other routing systems. A public utility instance of Someguy is hosted at [`https://delegated-ipfs.dev`](https://docs.ipfs.tech/concepts/public-utilities/#delegated-routing). + +Default: `["auto"]` + +Type: `array[string]` (URLs or `"auto"`) + ### `Routing.AcceleratedDHTClient` This alternative Amino DHT client with a Full-Routing-Table strategy will @@ -2656,27 +2668,21 @@ When it is enabled: This is critical to maintain to not harm the network. - The operations `ipfs stats dht` will default to showing information about the accelerated DHT client -**Caveats:** - -1. Running the accelerated client likely will result in more resource consumption (connections, RAM, CPU, bandwidth) - - Users that are limited in the number of parallel connections their machines/networks can perform will likely suffer - - The resource usage is not smooth as the client crawls the network in rounds and reproviding is similarly done in rounds - - Users who previously had a lot of content but were unable to advertise it on the network will see an increase in - egress bandwidth as their nodes start to advertise all of their CIDs into the network. If you have lots of data - entering your node that you don't want to advertise, then consider using [Provide Strategies](#providestrategy) - to reduce the number of CIDs that you are reproviding. Similarly, if you are running a node that deals mostly with - short-lived temporary data (e.g. you use a separate node for ingesting data then for storing and serving it) then - you may benefit from using [Strategic Providing](experimental-features.md#strategic-providing) to prevent advertising - of data that you ultimately will not have. -2. Currently, the DHT is not usable for queries for the first 5-10 minutes of operation as the routing table is being -prepared. This means operations like searching the DHT for particular peers or content will not work initially. - - You can see if the DHT has been initially populated by running `ipfs stats dht` -3. Currently, the accelerated DHT client is not compatible with LAN-based DHTs and will not perform operations against -them -4. (⚠️ 0.39 limitation) When used with [`Provide.DHT.SweepEnabled`](#providedhtsweepenabled), the sweep provider may -fail to estimate DHT size during the accelerated client's network crawl, resulting in all CIDs grouped into a -single region. Content still gets reprovided, but without sweep efficiency gains. Consider disabling the -accelerated client when using sweep mode. +> [!CAUTION] +> **`Routing.AcceleratedDHTClient` Caveats:** +> +> 1. Running the accelerated client likely will result in more resource consumption (connections, RAM, CPU, bandwidth) +> - Users that are limited in the number of parallel connections their machines/networks can perform will be most affected +> - The resource usage is not smooth as the client crawls the network in rounds and reproviding is similarly done in rounds +> - Users who previously had a lot of content but were unable to advertise it on the network will see an increase in +> egress bandwidth as their nodes start to advertise all of their CIDs into the network. If you have lots of data +> entering your node that you don't want to advertise, consider using [`Provide.*`](#provide) configuration +> to control which CIDs are reprovided. +> 2. Currently, the DHT is not usable for queries for the first 5-10 minutes of operation as the routing table is being +> prepared. This means operations like searching the DHT for particular peers or content will not work initially. +> - You can see if the DHT has been initially populated by running `ipfs stats dht` +> 3. Currently, the accelerated DHT client is not compatible with LAN-based DHTs and will not perform operations against +> them. Default: `false` @@ -2710,30 +2716,18 @@ Default: `[]` Type: `array[string]` -### `Routing.DelegatedRouters` - -An array of URL hostnames for delegated routers to be queried in addition to the Amino DHT when `Routing.Type` is set to `auto` (default) or `autoclient`. -These endpoints must support the [Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/). - -The special value `"auto"` uses delegated routers from [AutoConf](#autoconf) when enabled. - -> [!TIP] -> Delegated routing allows IPFS implementations to offload tasks like content routing, peer routing, and naming to a separate process or server while also benefiting from HTTP caching. -> -> One can run their own delegated router either by implementing the [Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/) themselves, or by using [Someguy](https://github.com/ipfs/someguy), a turn-key implementation that proxies requests to other routing systems. A public utility instance of Someguy is hosted at [`https://delegated-ipfs.dev`](https://docs.ipfs.tech/concepts/public-utilities/#delegated-routing). - -Default: `["auto"]` - -Type: `array[string]` (URLs or `"auto"`) - ### `Routing.Routers` Alternative configuration used when `Routing.Type=custom`. -> [!WARNING] -> **EXPERIMENTAL: `Routing.Routers` configuration may change in future release** +> [!CAUTION] +> **EXPERIMENTAL: `Routing.Routers` is for research and testing only, not production use.** > -> Consider this advanced low-level config: Most users can simply use `Routing.Type=auto` or `autoclient` and set up basic config in user-friendly [`Routing.DelegatedRouters`](https://github.com/ipfs/kubo/blob/master/docs/config.md#routingdelegatedrouters). +> - The configuration format and behavior may change without notice between releases. +> - Bugs and regressions may not be prioritized. +> - HTTP-only configurations cannot reliably provide content. See [delegated-routing.md](delegated-routing.md#limitations). +> +> Most users should use `Routing.Type=auto` or `autoclient` with [`Routing.DelegatedRouters`](#routingdelegatedrouters). Allows for replacing the default routing (Amino DHT) with alternative Router implementations. @@ -2744,9 +2738,9 @@ Default: `{}` Type: `object[string->object]` -#### `Routing.Routers: Type` +#### `Routing.Routers.[name].Type` -**EXPERIMENTAL: `Routing.Routers` configuration may change in future release** +**⚠️ EXPERIMENTAL: For research and testing only. May change without notice.** It specifies the routing type that will be created. @@ -2758,9 +2752,9 @@ Currently supported types: Type: `string` -#### `Routing.Routers: Parameters` +#### `Routing.Routers.[name].Parameters` -**EXPERIMENTAL: `Routing.Routers` configuration may change in future release** +**⚠️ EXPERIMENTAL: For research and testing only. May change without notice.** Parameters needed to create the specified router. Supported params per router type: @@ -2797,14 +2791,18 @@ Default: `{}` (use the safe implicit defaults) Type: `object[string->string]` -### `Routing: Methods` +### `Routing.Methods` `Methods:map` will define which routers will be executed per method used when `Routing.Type=custom`. -> [!WARNING] -> **EXPERIMENTAL: `Routing.Routers` configuration may change in future release** +> [!CAUTION] +> **EXPERIMENTAL: `Routing.Methods` is for research and testing only, not production use.** > -> Consider this advanced low-level config: Most users can simply use `Routing.Type=auto` or `autoclient` and set up basic config in user-friendly [`Routing.DelegatedRouters`](https://github.com/ipfs/kubo/blob/master/docs/config.md#routingdelegatedrouters). +> - The configuration format and behavior may change without notice between releases. +> - Bugs and regressions may not be prioritized. +> - HTTP-only configurations cannot reliably provide content. See [delegated-routing.md](delegated-routing.md#limitations). +> +> Most users should use `Routing.Type=auto` or `autoclient` with [`Routing.DelegatedRouters`](#routingdelegatedrouters). The key will be the name of the method: `"provide"`, `"find-providers"`, `"find-peers"`, `"put-ipns"`, `"get-ipns"`. All methods must be added to the list. diff --git a/docs/delegated-routing.md b/docs/delegated-routing.md index ddc4e48ed..5e781c147 100644 --- a/docs/delegated-routing.md +++ b/docs/delegated-routing.md @@ -1,4 +1,15 @@ -# New multi-router configuration system +# Delegated Routing Notes + +- Status Date: 2025-12 + +> [!IMPORTANT] +> Most users are best served by setting delegated HTTP router URLs in [`Routing.DelegatedRouters`](https://github.com/ipfs/kubo/blob/master/docs/config.md#routingdelegatedrouters) and `Routing.Type` to `auto` or `autoclient`, rather than using custom routing with `Routing.Routers` and `Routing.Methods` directly. +> +> The rest of this documentation describes experimental features intended only for researchers and advanced users. + +---- + +# Custom Multi-Router Configuration (Experimental) - Start Date: 2022-08-15 - Related Issues: @@ -6,27 +17,16 @@ - https://github.com/ipfs/kubo/issues/9079 - https://github.com/ipfs/kubo/pull/9877 -## Summary - -Previously we only used the Amino DHT for content routing and content -providing. - -Kubo 0.14 introduced experimental support for [delegated routing](https://github.com/ipfs/kubo/pull/8997), -which then got changed and standardized as [Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/). - -Kubo 0.23.0 release added support for [self-hosting Routing V1 HTTP API server](https://github.com/ipfs/kubo/blob/master/docs/changelogs/v0.23.md#self-hosting-routingv1-endpoint-for-delegated-routing-needs). - - -> [!TIP] -> Kubo 0.35 added support for [`Routing.DelegatedRouters`](https://github.com/ipfs/kubo/blob/master/docs/config.md#routingdelegatedrouters). +> [!CAUTION] +> **`Routing.Type=custom` with `Routing.Routers` and `Routing.Methods` is EXPERIMENTAL.** > -> Most of users are best served by setting delegated HTTP router URLs there and `Routing.Type` to `auto` or `autoclient`, rather than custom routing with complex `Routing.Routers` and `Routing.Methods` directly. +> This feature is provided for **research and testing purposes only**. It is **not suitable for production use**. > -> The rest of this documentation should be considered only by advanced users and researchers. - -Now we need a better way to add different routers using different protocols -like [Routing V1](https://specs.ipfs.tech/routing/http-routing-v1/) or Amino -DHT, and be able to configure them (future routing systems to come) to cover different use cases. +> - The configuration format and behavior may change without notice between Kubo releases. +> - Bugs and regressions affecting custom routing may not be prioritized or fixed promptly. +> - HTTP-only routing configurations (without DHT) cannot reliably provide content to the network (👉️ see [Limitations](#limitations) below). +> +> **For production deployments**, use `Routing.Type=auto` (default) or `Routing.Type=autoclient` with [`Routing.DelegatedRouters`](https://github.com/ipfs/kubo/blob/master/docs/config.md#routingdelegatedrouters). ## Motivation @@ -362,6 +362,29 @@ I got ideas from all of the following links to create this design document: - https://www.notion.so/pl-strflt/Delegated-Routing-Thoughts-very-very-WIP-0543bc51b1bd4d63a061b0f28e195d38 - https://gist.github.com/guseggert/effa027ff4cbadd7f67598efb6704d12 +### Limitations + +#### HTTP-only routing cannot reliably provide content + +Configurations that use only HTTP routers (without any DHT router) are unable to reliably announce content (provider records) to the network. + +This limitation exists because: + +1. **No standardized HTTP API for providing**: The [Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/) spec only defines read operations (`GET /routing/v1/providers/{cid}`). The write operation (`PUT /routing/v1/providers`) was never standardized. + +2. **Legacy experimental API**: The only available HTTP providing mechanism is an undocumented `PUT /routing/v1/providers` request format called `ProvideBitswap`, which is a historical experiment. See [IPIP-526](https://github.com/ipfs/specs/pull/526) for ongoing discussion about formalizing HTTP-based provider announcements. + +3. **Provider system integration**: Kubo's default provider system (`Provide.DHT.SweepEnabled=true` since v0.38) is designed for DHT-based providing. When no DHT is configured, the provider system may silently skip HTTP routers or behave unexpectedly. + +**Workarounds for testing:** + +If you need to test HTTP providing, you can try: + +- Setting `Provide.DHT.SweepEnabled=false` to use the legacy provider system +- Including at least one DHT router in your custom configuration alongside HTTP routers + +These workarounds are not guaranteed to work across Kubo versions and should not be relied upon for production use. + ### Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/routing/delegated.go b/routing/delegated.go index 9f6a39667..1c6d45ae1 100644 --- a/routing/delegated.go +++ b/routing/delegated.go @@ -31,6 +31,13 @@ import ( var log = logging.Logger("routing/delegated") +// Parse creates a composed router from the custom routing configuration. +// +// EXPERIMENTAL: Custom routing (Routing.Type=custom with Routing.Routers and +// Routing.Methods) is for research and testing only, not production use. +// The configuration format and behavior may change without notice between +// releases. HTTP-only configurations cannot reliably provide content. +// See docs/delegated-routing.md for limitations. func Parse(routers config.Routers, methods config.Methods, extraDHT *ExtraDHTParams, extraHTTP *ExtraHTTPParams) (routing.Routing, error) { if err := methods.Check(); err != nil { return nil, err