Add CLI timeout for retrieval/resolution

[Rinse12]

Checklist

• This is a bug report, not a question. Ask questions on discuss.ipfs.tech.
• I have searched on the issue tracker for my bug.
• I am running the latest kubo version or have an issue updating.

Installation method

dist.ipfs.tech or ipfs-update

Version

Kubo version: 0.37.0
Repo version: 17
System version: amd64/linux
Golang version: go1.25.0

Config

{
  "API": {
    "HTTPHeaders": {}
  },
  "Addresses": {
    "API": "/ip4/127.0.0.1/tcp/54322",
    "Announce": [],
    "AppendAnnounce": [],
    "Gateway": "/ip4/127.0.0.1/tcp/54323",
    "NoAnnounce": [],
    "Swarm": [
      "/ip4/0.0.0.0/tcp/54321",
      "/ip6/::/tcp/54321",
      "/ip4/0.0.0.0/udp/54321/webrtc-direct",
      "/ip4/0.0.0.0/udp/54321/quic-v1",
      "/ip4/0.0.0.0/udp/54321/quic-v1/webtransport",
      "/ip6/::/udp/54321/webrtc-direct",
      "/ip6/::/udp/54321/quic-v1",
      "/ip6/::/udp/54321/quic-v1/webtransport"
    ]
  },
  "AutoConf": {},
  "AutoNAT": {},
  "AutoTLS": {},
  "Bitswap": {},
  "Bootstrap": ["auto"],
  "DNS": {
    "Resolvers": {
      ".": "auto"
    }
  },
  "Datastore": {
    "BlockKeyCacheSize": null,
    "BloomFilterSize": 0,
    "GCPeriod": "1h",
    "HashOnRead": false,
    "Spec": {
      "mounts": [
        {
          "mountpoint": "/blocks",
          "path": "blocks",
          "prefix": "flatfs.datastore",
          "shardFunc": "/repo/flatfs/shard/v1/next-to-last/2",
          "sync": false,
          "type": "flatfs"
        },
        {
          "compression": "none",
          "mountpoint": "/",
          "path": "datastore",
          "prefix": "leveldb.datastore",
          "type": "levelds"
        }
      ],
      "type": "mount"
    },
    "StorageGCWatermark": 90,
    "StorageMax": "10GB"
  },
  "Discovery": {
    "MDNS": {
      "Enabled": false
    }
  },
  "Experimental": {
    "FilestoreEnabled": false,
    "Libp2pStreamMounting": false,
    "OptimisticProvide": false,
    "OptimisticProvideJobsPoolSize": 0,
    "P2pHttpProxy": false,
    "UrlstoreEnabled": false
  },
  "Gateway": {
    "DeserializedResponses": null,
    "DisableHTMLErrors": null,
    "ExposeRoutingAPI": null,
    "HTTPHeaders": {},
    "NoDNSLink": false,
    "NoFetch": false,
    "PublicGateways": null,
    "RootRedirect": ""
  },
  "HTTPRetrieval": {},
  "Identity": {
    "PeerID": "12D3KooWCwKzba6nE1KW6YrDfjWGGAYspZAP6unutUULtpYXmMXC"
  },
  "Import": {
    "BatchMaxNodes": null,
    "BatchMaxSize": null,
    "CidVersion": null,
    "HashFunction": null,
    "UnixFSChunker": null,
    "UnixFSDirectoryMaxLinks": null,
    "UnixFSFileMaxLinks": null,
    "UnixFSHAMTDirectoryMaxFanout": null,
    "UnixFSHAMTDirectorySizeThreshold": null,
    "UnixFSRawLeaves": null
  },
  "Internal": {},
  "Ipns": {
    "DelegatedPublishers": ["auto"],
    "RecordLifetime": "",
    "RepublishPeriod": "",
    "ResolveCacheSize": 128
  },
  "Migration": {},
  "Mounts": {
    "FuseAllowOther": false,
    "IPFS": "/ipfs",
    "IPNS": "/ipns",
    "MFS": "/mfs"
  },
  "Peering": {
    "Peers": null
  },
  "Pinning": {
    "RemoteServices": {}
  },
  "Plugins": {
    "Plugins": null
  },
  "Provider": {},
  "Pubsub": {
    "DisableSigning": false,
    "Router": ""
  },
  "Reprovider": {},
  "Routing": {
    "Methods": {
      "find-peers": {
        "RouterName": "HttpRouterNotSupported"
      },
      "find-providers": {
        "RouterName": "HttpRoutersParallel"
      },
      "get-ipns": {
        "RouterName": "HttpRouterNotSupported"
      },
      "provide": {
        "RouterName": "HttpRoutersParallel"
      },
      "put-ipns": {
        "RouterName": "HttpRouterNotSupported"
      }
    },
    "Routers": {
      "HttpRouter1": {
        "Parameters": {
          "Endpoint": "http://127.0.0.1:19999"
        },
        "Type": "http"
      },
      "HttpRouter2": {
        "Parameters": {
          "Endpoint": "http://127.0.0.1:19998"
        },
        "Type": "http"
      },
      "HttpRouterNotSupported": {
        "Parameters": {
          "Endpoint": "http://kubohttprouternotsupported"
        },
        "Type": "http"
      },
      "HttpRoutersParallel": {
        "Parameters": {
          "Routers": [
            {
              "IgnoreErrors": false,
              "RouterName": "HttpRouter1",
              "Timeout": "5s"
            },
            {
              "IgnoreErrors": false,
              "RouterName": "HttpRouter2",
              "Timeout": "5s"
            }
          ]
        },
        "Type": "parallel"
      }
    },
    "Type": "custom"
  },
  "Swarm": {
    "AddrFilters": null,
    "ConnMgr": {},
    "DisableBandwidthMetrics": false,
    "DisableNatPortMap": false,
    "RelayClient": {},
    "RelayService": {},
    "ResourceMgr": {},
    "Transports": {
      "Multiplexers": {},
      "Network": {},
      "Security": {}
    }
  },
  "Version": {}
}

Description

When using kubo 0.37.0 with custom HTTP routing, CID fetching operations hang until timeout in two scenarios: when routers are offline, and when routers return "no providers found" (HTTP 404).

What I was doing:

Testing CID fetching with ipfs cat <cid> under two scenarios:

1. Offline HTTP routers - endpoints that refuse connections (127.0.0.1:19999 and 127.0.0.1:19998)
2. HTTP routers returning 404 - endpoints that respond with "no providers found"

Both configurations use IgnoreErrors: false and 5-second timeouts. I have tested with IgnoreErrors: true with same result.

Expected behavior:

For offline routers:

• Immediate failure with clear error message when endpoints are unreachable
• No waiting since connection is refused

For routers returning "no providers found" (HTTP 404):

• Immediate failure after first round of queries
• HTTP 404 should be treated as definitive answer, and kubo shouldn't keep on retrying
• Clear error message explaining no providers were found

Actual behavior:

For offline routers:

• Hangs indefinitely during provider discovery phase
• No error output explaining http routers are down
• Operation must be killed manually

For routers returning "no providers found" (HTTP 404):

• Hangs until timeout by repeatedly retrying the same routers
• Makes 4-6+ provider queries over 60-120 seconds instead of failing after first round
• Eventually times out with no error messages explaining no providers were found

Steps to reproduce:

1. git clone https://github.com/Rinse12/kubo_fetch_cid_not_throwing_if_providers_offline
2. Run npm i
3. Run node test-offline-peer-routing.js (tests offline routers)
4. Run node test-no-providers-http-routing.js (tests 404 responses)

Configuration details:

• Routing type: custom with parallel HTTP routers
• Router endpoints: offline (127.0.0.1:19999, 127.0.0.1:19998)
• IgnoreErrors: false (failures should not be ignored)
• Timeout: 5s per router

[lidel]

Triage notes:

• if all routing systems return error (e.g. http endpoint being down) there is still one extra "routing system" which is bitswap broadcast and "being connected to other peers" -- the connection "hangs" because there is a chance some of peers you are connected to you will respond to your bitswap broadcast
• we could add a feature / configuration flag which disables waiting for things like bitswap broadcasts, and return as fast as all explicitly configured routing systems in Routing.Routers respond or error
• note:
  • Kubo 0.37 has Gateway.RetrievalTimeout, what we could do is to implement equivalent for CLI and it would cover all the bases across all routing configurations
  • Kubo 0.38 will ship user-friendly boxo/retrieval.State errors, we could also surface them in CLI