docs: clarify Routing.Type=custom as experimental (#11111)
* 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>
Marcin Rataj committed
Jan 11, 2026 at 00:39 UTC
447109df6423898edb7bcf86a534606df3945d6d
3 files changed
+135
-107
docs/config.md
+85
-87
@@ -157,14 +157,14 @@ config file at runtime.
157
- [`Reprovider.Strategy`](#providestrategy)
158
- [`Routing`](#routing)
159
- [`Routing.Type`](#routingtype)
160
+ - [`Routing.DelegatedRouters`](#routingdelegatedrouters)
161
- [`Routing.AcceleratedDHTClient`](#routingaccelerateddhtclient)
162
- [`Routing.LoopbackAddressesOnLanDHT`](#routingloopbackaddressesonlandht)
163
- [`Routing.IgnoreProviders`](#routingignoreproviders)
163
- - [`Routing.DelegatedRouters`](#routingdelegatedrouters)
164
- [`Routing.Routers`](#routingrouters)
165
- - [`Routing.Routers: Type`](#routingrouters-type)
166
- - [`Routing.Routers: Parameters`](#routingrouters-parameters)
167
- - [`Routing: Methods`](#routing-methods)
165
+ - [`Routing.Routers.[name].Type`](#routingroutersnametype)
166
+ - [`Routing.Routers.[name].Parameters`](#routingroutersnameparameters)
167
+ - [`Routing.Methods`](#routingmethods)
168
- [`Swarm`](#swarm)
169
- [`Swarm.AddrFilters`](#swarmaddrfilters)
170
- [`Swarm.DisableBandwidthMetrics`](#swarmdisablebandwidthmetrics)
@@ -2575,57 +2575,69 @@ Contains options for content, peer, and IPNS routing mechanisms.
2575
2576
### `Routing.Type`
2577
2578
-There are multiple routing options: "auto", "autoclient", "none", "dht", "dhtclient", "delegated", and "custom".
2578
+Controls how your node discovers content and peers on the network.
2579
2580
-- **DEFAULT:** If unset, or set to "auto", your node will use the public IPFS DHT (aka "Amino")
2581
- and parallel [`Routing.DelegatedRouters`](#routingdelegatedrouters) for additional speed.
2580
+**Production options:**
2581
2583
-- If set to "autoclient", your node will behave as in "auto" but without running a DHT server.
2582
+- **`auto`** (default): Uses both the public IPFS DHT (Amino) and HTTP routers
2583
+ from [`Routing.DelegatedRouters`](#routingdelegatedrouters) for faster lookups.
2584
+ Your node starts as a DHT client and automatically switches to server mode
2585
+ when reachable from the public internet.
2586
2585
-- If set to "none", your node will use _no_ routing system. You'll have to
2586
- explicitly connect to peers that have the content you're looking for.
2587
+- **`autoclient`**: Same as `auto`, but never runs a DHT server.
2588
+ Use this if your node is behind a firewall or NAT.
2589
2588
-- If set to "dht" (or "dhtclient"/"dhtserver"), your node will ONLY use the Amino DHT (no HTTP routers).
2590
+- **`dht`**: Uses only the Amino DHT (no HTTP routers). Automatically switches
2591
+ between client and server mode based on reachability.
2592
2590
-- If set to "custom", all default routers are disabled, and only ones defined in `Routing.Routers` will be used.
2593
+- **`dhtclient`**: DHT-only, always running as a client. Lower resource usage.
2594
2592
-When the DHT is enabled, it can operate in two modes: client and server.
2595
+- **`dhtserver`**: DHT-only, always running as a server.
2596
+ Only use this if your node is reachable from the public internet.
2597
2594
-- In server mode, your node will query other peers for DHT records, and will
2595
- respond to requests from other peers (both requests to store records and
2596
- requests to retrieve records).
2598
+- **`none`**: Disables all routing. You must manually connect to peers.
2599
2598
-- In client mode, your node will query the DHT as a client but will not respond
2599
- to requests from other peers. This mode is less resource-intensive than server
2600
- mode.
2600
+**About DHT client vs server mode:**
2601
+When the DHT is enabled, your node can operate as either a client or server.
2602
+In server mode, it queries other peers and responds to their queries - this helps
2603
+the network but uses more resources. In client mode, it only queries others without
2604
+responding, which is less resource-intensive. With `auto` or `dht`, your node starts
2605
+as a client and switches to server when it detects public reachability.
2606
2602
-When `Routing.Type` is set to `auto` or `dht`, your node will start as a DHT client, and
2603
-switch to a DHT server when and if it determines that it's reachable from the
2604
-public internet (e.g., it's not behind a firewall).
2607
+> [!CAUTION]
2608
+> **`Routing.Type` Experimental options:**
2609
+>
2610
+> These modes are for research and testing only, not production use.
2611
+> They may change without notice between releases.
2612
+>
2613
+> - **`delegated`**: Uses only HTTP routers from [`Routing.DelegatedRouters`](#routingdelegatedrouters)
2614
+> and IPNS publishers from [`Ipns.DelegatedPublishers`](#ipnsdelegatedpublishers),
2615
+> without initializing the DHT. Useful when peer-to-peer connectivity is unavailable.
2616
+> Note: cannot provide content to the network (no DHT means no provider records).
2617
+>
2618
+> - **`custom`**: Disables all default routers. You define your own routing in
2619
+> [`Routing.Routers`](#routingrouters). See [delegated-routing.md](delegated-routing.md).
2620
2606
-To force a specific Amino DHT-only mode, client or server, set `Routing.Type` to
2607
-`dhtclient` or `dhtserver` respectively. Please do not set this to `dhtserver`
2608
-unless you're sure your node is reachable from the public network.
2621
+Default: `auto`
2622
2610
-When `Routing.Type` is set to `auto` or `autoclient` your node will accelerate some types of routing
2611
-by leveraging [`Routing.DelegatedRouters`](#routingdelegatedrouters) HTTP endpoints compatible with [Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/)
2612
-introduced in [IPIP-337](https://github.com/ipfs/specs/pull/337)
2613
-in addition to the Amino DHT.
2623
+Type: `optionalString` (`null`/missing means the default)
2624
+
2625
+### `Routing.DelegatedRouters`
2626
2615
-When `Routing.Type` is set to `delegated`, your node will use **only** HTTP delegated routers and IPNS publishers,
2616
-without initializing the Amino DHT at all. This mode is useful for environments where peer-to-peer DHT connectivity
2617
-is not available or desired, while still enabling content routing and IPNS publishing via HTTP APIs.
2618
-This mode requires configuring [`Routing.DelegatedRouters`](#routingdelegatedrouters) for content routing and
2619
-[`Ipns.DelegatedPublishers`](#ipnsdelegatedpublishers) for IPNS publishing.
2627
+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`.
2628
+These endpoints must support the [Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/).
2629
2621
-**Note:** `delegated` mode operates as read-only for content providing - your node cannot announce content to the network
2622
-since there is no DHT connectivity. Content providing is automatically disabled when using this routing type.
2630
+The special value `"auto"` uses delegated routers from [AutoConf](#autoconf) when enabled.
2631
+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.
2632
2624
-[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`.
2633
+> [!TIP]
2634
+> 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.
2635
+>
2636
+> 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).
2637
2626
-Default: `auto` (DHT + [`Routing.DelegatedRouters`](#routingdelegatedrouters))
2638
+Default: `["auto"]`
2639
2628
-Type: `optionalString` (`null`/missing means the default)
2640
+Type: `array[string]` (URLs or `"auto"`)
2641
2642
### `Routing.AcceleratedDHTClient`
2643
@@ -2656,27 +2668,21 @@ When it is enabled:
2668
This is critical to maintain to not harm the network.
2669
- The operations `ipfs stats dht` will default to showing information about the accelerated DHT client
2670
2659
-**Caveats:**
2660
-
2661
-1. Running the accelerated client likely will result in more resource consumption (connections, RAM, CPU, bandwidth)
2662
- - Users that are limited in the number of parallel connections their machines/networks can perform will likely suffer
2663
- - The resource usage is not smooth as the client crawls the network in rounds and reproviding is similarly done in rounds
2664
- - Users who previously had a lot of content but were unable to advertise it on the network will see an increase in
2665
- egress bandwidth as their nodes start to advertise all of their CIDs into the network. If you have lots of data
2666
- entering your node that you don't want to advertise, then consider using [Provide Strategies](#providestrategy)
2667
- to reduce the number of CIDs that you are reproviding. Similarly, if you are running a node that deals mostly with
2668
- short-lived temporary data (e.g. you use a separate node for ingesting data then for storing and serving it) then
2669
- you may benefit from using [Strategic Providing](experimental-features.md#strategic-providing) to prevent advertising
2670
- of data that you ultimately will not have.
2671
-2. Currently, the DHT is not usable for queries for the first 5-10 minutes of operation as the routing table is being
2672
-prepared. This means operations like searching the DHT for particular peers or content will not work initially.
2673
- - You can see if the DHT has been initially populated by running `ipfs stats dht`
2674
-3. Currently, the accelerated DHT client is not compatible with LAN-based DHTs and will not perform operations against
2675
-them
2676
-4. (⚠️ 0.39 limitation) When used with [`Provide.DHT.SweepEnabled`](#providedhtsweepenabled), the sweep provider may
2677
-fail to estimate DHT size during the accelerated client's network crawl, resulting in all CIDs grouped into a
2678
-single region. Content still gets reprovided, but without sweep efficiency gains. Consider disabling the
2679
-accelerated client when using sweep mode.
2671
+> [!CAUTION]
2672
+> **`Routing.AcceleratedDHTClient` Caveats:**
2673
+>
2674
+> 1. Running the accelerated client likely will result in more resource consumption (connections, RAM, CPU, bandwidth)
2675
+> - Users that are limited in the number of parallel connections their machines/networks can perform will be most affected
2676
+> - The resource usage is not smooth as the client crawls the network in rounds and reproviding is similarly done in rounds
2677
+> - Users who previously had a lot of content but were unable to advertise it on the network will see an increase in
2678
+> egress bandwidth as their nodes start to advertise all of their CIDs into the network. If you have lots of data
2679
+> entering your node that you don't want to advertise, consider using [`Provide.*`](#provide) configuration
2680
+> to control which CIDs are reprovided.
2681
+> 2. Currently, the DHT is not usable for queries for the first 5-10 minutes of operation as the routing table is being
2682
+> prepared. This means operations like searching the DHT for particular peers or content will not work initially.
2683
+> - You can see if the DHT has been initially populated by running `ipfs stats dht`
2684
+> 3. Currently, the accelerated DHT client is not compatible with LAN-based DHTs and will not perform operations against
2685
+> them.
2686
2687
Default: `false`
2688
@@ -2710,30 +2716,18 @@ Default: `[]`
2716
2717
Type: `array[string]`
2718
2713
-### `Routing.DelegatedRouters`
2714
-
2715
-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`.
2716
-These endpoints must support the [Delegated Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/).
2717
-
2718
-The special value `"auto"` uses delegated routers from [AutoConf](#autoconf) when enabled.
2719
-
2720
-> [!TIP]
2721
-> 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.
2722
->
2723
-> 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).
2724
-
2725
-Default: `["auto"]`
2726
-
2727
-Type: `array[string]` (URLs or `"auto"`)
2728
-
2719
### `Routing.Routers`
2720
2721
Alternative configuration used when `Routing.Type=custom`.
2722
2733
-> [!WARNING]
2734
-> **EXPERIMENTAL: `Routing.Routers` configuration may change in future release**
2723
+> [!CAUTION]
2724
+> **EXPERIMENTAL: `Routing.Routers` is for research and testing only, not production use.**
2725
+>
2726
+> - The configuration format and behavior may change without notice between releases.
2727
+> - Bugs and regressions may not be prioritized.
2728
+> - HTTP-only configurations cannot reliably provide content. See [delegated-routing.md](delegated-routing.md#limitations).
2729
>
2736
-> 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).
2730
+> Most users should use `Routing.Type=auto` or `autoclient` with [`Routing.DelegatedRouters`](#routingdelegatedrouters).
2731
2732
Allows for replacing the default routing (Amino DHT) with alternative Router
2733
implementations.
@@ -2744,9 +2738,9 @@ Default: `{}`
2738
2739
Type: `object[string->object]`
2740
2747
-#### `Routing.Routers: Type`
2741
+#### `Routing.Routers.[name].Type`
2742
2749
-**EXPERIMENTAL: `Routing.Routers` configuration may change in future release**
2743
+**⚠️ EXPERIMENTAL: For research and testing only. May change without notice.**
2744
2745
It specifies the routing type that will be created.
2746
@@ -2758,9 +2752,9 @@ Currently supported types:
2752
2753
Type: `string`
2754
2761
-#### `Routing.Routers: Parameters`
2755
+#### `Routing.Routers.[name].Parameters`
2756
2763
-**EXPERIMENTAL: `Routing.Routers` configuration may change in future release**
2757
+**⚠️ EXPERIMENTAL: For research and testing only. May change without notice.**
2758
2759
Parameters needed to create the specified router. Supported params per router type:
2760
@@ -2797,14 +2791,18 @@ Default: `{}` (use the safe implicit defaults)
2791
2792
Type: `object[string->string]`
2793
2800
-### `Routing: Methods`
2794
+### `Routing.Methods`
2795
2796
`Methods:map` will define which routers will be executed per method used when `Routing.Type=custom`.
2797
2804
-> [!WARNING]
2805
-> **EXPERIMENTAL: `Routing.Routers` configuration may change in future release**
2798
+> [!CAUTION]
2799
+> **EXPERIMENTAL: `Routing.Methods` is for research and testing only, not production use.**
2800
+>
2801
+> - The configuration format and behavior may change without notice between releases.
2802
+> - Bugs and regressions may not be prioritized.
2803
+> - HTTP-only configurations cannot reliably provide content. See [delegated-routing.md](delegated-routing.md#limitations).
2804
>
2807
-> 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).
2805
+> Most users should use `Routing.Type=auto` or `autoclient` with [`Routing.DelegatedRouters`](#routingdelegatedrouters).
2806
2807
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.
2808
docs/delegated-routing.md
+43
-20
@@ -1,4 +1,15 @@
1
-# New multi-router configuration system
1
+# Delegated Routing Notes
2
+
3
+- Status Date: 2025-12
4
+
5
+> [!IMPORTANT]
6
+> 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.
7
+>
8
+> The rest of this documentation describes experimental features intended only for researchers and advanced users.
9
+
10
+----
11
+
12
+# Custom Multi-Router Configuration (Experimental)
13
14
- Start Date: 2022-08-15
15
- Related Issues:
@@ -6,27 +17,16 @@
17
- https://github.com/ipfs/kubo/issues/9079
18
- https://github.com/ipfs/kubo/pull/9877
19
9
-## Summary
10
-
11
-Previously we only used the Amino DHT for content routing and content
12
-providing.
13
-
14
-Kubo 0.14 introduced experimental support for [delegated routing](https://github.com/ipfs/kubo/pull/8997),
15
-which then got changed and standardized as [Routing V1 HTTP API](https://specs.ipfs.tech/routing/http-routing-v1/).
16
-
17
-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).
18
-
19
-
20
-> [!TIP]
21
-> Kubo 0.35 added support for [`Routing.DelegatedRouters`](https://github.com/ipfs/kubo/blob/master/docs/config.md#routingdelegatedrouters).
20
+> [!CAUTION]
21
+> **`Routing.Type=custom` with `Routing.Routers` and `Routing.Methods` is EXPERIMENTAL.**
22
>
23
-> 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.
23
+> This feature is provided for **research and testing purposes only**. It is **not suitable for production use**.
24
>
25
-> The rest of this documentation should be considered only by advanced users and researchers.
26
-
27
-Now we need a better way to add different routers using different protocols
28
-like [Routing V1](https://specs.ipfs.tech/routing/http-routing-v1/) or Amino
29
-DHT, and be able to configure them (future routing systems to come) to cover different use cases.
25
+> - The configuration format and behavior may change without notice between Kubo releases.
26
+> - Bugs and regressions affecting custom routing may not be prioritized or fixed promptly.
27
+> - HTTP-only routing configurations (without DHT) cannot reliably provide content to the network (👉️ see [Limitations](#limitations) below).
28
+>
29
+> **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).
30
31
## Motivation
32
@@ -362,6 +362,29 @@ I got ideas from all of the following links to create this design document:
362
- https://www.notion.so/pl-strflt/Delegated-Routing-Thoughts-very-very-WIP-0543bc51b1bd4d63a061b0f28e195d38
363
- https://gist.github.com/guseggert/effa027ff4cbadd7f67598efb6704d12
364
365
+### Limitations
366
+
367
+#### HTTP-only routing cannot reliably provide content
368
+
369
+Configurations that use only HTTP routers (without any DHT router) are unable to reliably announce content (provider records) to the network.
370
+
371
+This limitation exists because:
372
+
373
+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.
374
+
375
+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.
376
+
377
+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.
378
+
379
+**Workarounds for testing:**
380
+
381
+If you need to test HTTP providing, you can try:
382
+
383
+- Setting `Provide.DHT.SweepEnabled=false` to use the legacy provider system
384
+- Including at least one DHT router in your custom configuration alongside HTTP routers
385
+
386
+These workarounds are not guaranteed to work across Kubo versions and should not be relied upon for production use.
387
+
388
### Copyright
389
390
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
routing/delegated.go
+7
@@ -31,6 +31,13 @@ import (
31
32
var log = logging.Logger("routing/delegated")
33
34
+// Parse creates a composed router from the custom routing configuration.
35
+//
36
+// EXPERIMENTAL: Custom routing (Routing.Type=custom with Routing.Routers and
37
+// Routing.Methods) is for research and testing only, not production use.
38
+// The configuration format and behavior may change without notice between
39
+// releases. HTTP-only configurations cannot reliably provide content.
40
+// See docs/delegated-routing.md for limitations.
41
func Parse(routers config.Routers, methods config.Methods, extraDHT *ExtraDHTParams, extraHTTP *ExtraHTTPParams) (routing.Routing, error) {
42
if err := methods.Check(); err != nil {
43
return nil, err