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 <[email protected]>
Co-authored-by: Andrew Gillis <[email protected]>

Author: 3 people

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,57 +2575,69 @@ 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.
+Default: `auto`
 
-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.
+Type: `optionalString` (`null`/missing means the default)
+
+### `Routing.DelegatedRouters`
 
-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.
+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/).
 
-**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.
+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.
 
-[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`.
+> [!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` (DHT + [`Routing.DelegatedRouters`](#routingdelegatedrouters))
+Default: `["auto"]`
 
-Type: `optionalString` (`null`/missing means the default)
+Type: `array[string]` (URLs or `"auto"`)
 
 ### `Routing.AcceleratedDHTClient`
 
@@ -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.**
+>
+> - 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).
 >
-> 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).
+> 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.**
+>
+> - 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).
 >
-> 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).
+> 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.
 

docs/delegated-routing.md

@@ -1,32 +1,32 @@
-# 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:
   - https://github.com/ipfs/kubo/issues/9188
   - 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/).