feat(routing): opt-in persistence of the DHT routing table

config/routing.go

@@ -12,23 +12,22 @@ import (
 const (
 	DefaultAcceleratedDHTClient      = false
 	DefaultLoopbackAddressesOnLanDHT = false
+	DefaultPersistDHTRoutingTable    = false
 	DefaultRoutingType               = "auto"
 	CidContactRoutingURL             = "https://cid.contact"
 	PublicGoodDelegatedRoutingURL    = "https://delegated-ipfs.dev" // cid.contact + amino dht (incl. IPNS PUTs)
 	EnvHTTPRouters                   = "IPFS_HTTP_ROUTERS"
 	EnvHTTPRoutersFilterProtocols    = "IPFS_HTTP_ROUTERS_FILTER_PROTOCOLS"
 )
 
-var (
-	// Default filter-protocols to pass along with delegated routing requests (as defined in IPIP-484)
-	// and also filter out locally
-	DefaultHTTPRoutersFilterProtocols = getEnvOrDefault(EnvHTTPRoutersFilterProtocols, []string{
-		"unknown", // allow results without protocol list, we can do libp2p identify to test them
-		"transport-bitswap",
-		// http is added dynamically in routing/delegated.go.
-		// 'transport-ipfs-gateway-http'
-	})
-)
+// Default filter-protocols to pass along with delegated routing requests (as defined in IPIP-484)
+// and also filter out locally
+var DefaultHTTPRoutersFilterProtocols = getEnvOrDefault(EnvHTTPRoutersFilterProtocols, []string{
+	"unknown", // allow results without protocol list, we can do libp2p identify to test them
+	"transport-bitswap",
+	// http is added dynamically in routing/delegated.go.
+	// 'transport-ipfs-gateway-http'
+})
 
 // Routing defines configuration options for libp2p routing.
 type Routing struct {
@@ -44,6 +43,11 @@ type Routing struct {
 
 	LoopbackAddressesOnLanDHT Flag `json:",omitempty"`
 
+	// PersistDHTRoutingTable saves the Amino DHT routing table to the repo and,
+	// on the next start, reconnects to those peers before contacting the
+	// bootstrap peers. It has no effect with an empty Bootstrap list.
+	PersistDHTRoutingTable Flag `json:",omitempty"`
+
 	IgnoreProviders []string `json:",omitempty"`
 
 	// Simplified configuration used by default when Routing.Type=auto|autoclient

core/builder.go

@@ -143,7 +143,17 @@ func NewNode(ctx context.Context, cfg *BuildCfg) (*IpfsNode, error) {
 		return n, nil
 	}
 
-	return n, n.Bootstrap(bootstrap.DefaultBootstrapConfig)
+	repoCfg, err := n.Repo.Config()
+	if err != nil {
+		return n, err
+	}
+	bootstrapCfg := bootstrap.DefaultBootstrapConfig
+	// A WAN DHT that persists its routing table reconnects to its saved peers
+	// first, and dials the bootstrap peers itself if they fall short. The
+	// first round here waits one Period as a backstop, instead of dialing the
+	// bootstrap peers right away.
+	bootstrapCfg.DeferFirstRound = n.persistsRoutingTable(repoCfg)
+	return n, n.Bootstrap(bootstrapCfg)
 }
 
 // Log the entire `app.Err()` but return only the innermost one to the user

core/core.go

@@ -259,7 +259,17 @@ func (n *IpfsNode) Bootstrap(cfg bootstrap.BootstrapConfig) error {
 			return ps
 		}
 	}
-	if load, _ := cfg.BackupPeers(); load == nil {
+	repoConf, err := n.Repo.Config()
+	if err != nil {
+		return err
+	}
+	if n.persistsRoutingTable(repoConf) {
+		// The DHT routing table snapshot replaces the backup bootstrap peers
+		// saved while Routing.PersistDHTRoutingTable was off, so drop them.
+		if err := n.Repo.Datastore().Delete(n.Context(), TempBootstrapPeersKey); err != nil {
+			log.Warnf("failed to remove the backup bootstrap peers: %s", err)
+		}
+	} else if load, _ := cfg.BackupPeers(); load == nil {
 		save := func(ctx context.Context, peerList []peer.AddrInfo) {
 			err := n.saveTempBootstrapPeers(ctx, peerList)
 			if err != nil {
@@ -278,10 +288,6 @@ func (n *IpfsNode) Bootstrap(cfg bootstrap.BootstrapConfig) error {
 		cfg.SetBackupPeers(load, save)
 	}
 
-	repoConf, err := n.Repo.Config()
-	if err != nil {
-		return err
-	}
 	if repoConf.Internal.BackupBootstrapInterval != nil {
 		cfg.BackupBootstrapInterval = repoConf.Internal.BackupBootstrapInterval.WithDefault(time.Hour)
 	}
@@ -290,6 +296,17 @@ func (n *IpfsNode) Bootstrap(cfg bootstrap.BootstrapConfig) error {
 	return err
 }
 
+// persistsRoutingTable reports whether the WAN DHT saves its routing table
+// and reconnects to the saved peers on its own (Routing.PersistDHTRoutingTable).
+// Like the DHT, it treats an empty Bootstrap list as turning that off.
+func (n *IpfsNode) persistsRoutingTable(cfg *config.Config) bool {
+	if n.DHT == nil || !cfg.Routing.PersistDHTRoutingTable.WithDefault(config.DefaultPersistDHTRoutingTable) {
+		return false
+	}
+	peers, err := cfg.BootstrapPeersWithAutoConf()
+	return err == nil && len(peers) > 0
+}
+
 var TempBootstrapPeersKey = datastore.NewKey("/local/temp_bootstrap_peers")
 
 func (n *IpfsNode) loadBootstrapPeers() ([]peer.AddrInfo, error) {

core/node/libp2p/host.go

@@ -74,6 +74,7 @@ func Host(mctx helpers.MetricsCtx, lc fx.Lifecycle, params P2PHostIn) (out P2PHo
 		OptimisticProvide:             optimisticProvide,
 		OptimisticProvideJobsPoolSize: cfg.Experimental.OptimisticProvideJobsPoolSize,
 		LoopbackAddressesOnLanDHT:     cfg.Routing.LoopbackAddressesOnLanDHT.WithDefault(config.DefaultLoopbackAddressesOnLanDHT),
+		PersistDHTRoutingTable:        cfg.Routing.PersistDHTRoutingTable.WithDefault(config.DefaultPersistDHTRoutingTable),
 	}
 	opts = append(opts, libp2p.Routing(func(h host.Host) (routing.PeerRouting, error) {
 		args := routingOptArgs

core/node/libp2p/routingopt.go

@@ -30,6 +30,7 @@ type RoutingOptionArgs struct {
 	OptimisticProvide             bool
 	OptimisticProvideJobsPoolSize int
 	LoopbackAddressesOnLanDHT     bool
+	PersistDHTRoutingTable        bool
 }
 
 type RoutingOption func(args RoutingOptionArgs) (routing.Routing, error)
@@ -259,6 +260,13 @@ func constructDHTRouting(mode dht.ModeOpt) RoutingOption {
 		wanOptions := []dht.Option{
 			dht.BootstrapPeers(args.BootstrapPeers...),
 		}
+		// An empty Bootstrap list turns off all automatic dialing, saved
+		// peers included.
+		if args.PersistDHTRoutingTable && len(args.BootstrapPeers) > 0 {
+			wanOptions = append(wanOptions, dht.BootstrapOrder(dht.PersistedFirst))
+		} else {
+			wanOptions = append(wanOptions, dht.RoutingTablePersistence(0))
+		}
 		// In stub mode, allow loopback peers in the WAN routing
 		// table so Provide/PutValue work with ephemeral test peers.
 		if os.Getenv("TEST_DHT_STUB") != "" {

docs/changelogs/v0.44.md

@@ -6,13 +6,39 @@
 
 - [Overview](#overview)
 - [🔦 Highlights](#-highlights)
+  - [🧭 Opt-in: restarts rejoin the DHT through known peers](#-opt-in-restarts-rejoin-the-dht-through-known-peers)
 - [📝 Changelog](#-changelog)
 - [👨‍👩‍👧‍👦 Contributors](#-contributors)
 
 ### Overview
 
 ### 🔦 Highlights
 
+#### 🧭 Opt-in: restarts rejoin the DHT through known peers
+
+With the new
+[`Routing.PersistDHTRoutingTable`](https://github.com/ipfs/kubo/blob/master/docs/config.md#routingpersistdhtroutingtable)
+option, Kubo saves its Amino DHT routing table to the repo after 10 minutes,
+then every hour, and on shutdown. On the next start it reconnects to those
+peers first, and contacts the
+[`Bootstrap`](https://github.com/ipfs/kubo/blob/master/docs/config.md#bootstrap)
+peers only if fewer than 10 of the saved peers answer within 20 seconds.
+Restarts then depend less on the same small set of bootstrap peers, and a node
+that knows the network can rejoin it even when those peers are unreachable. A
+new node, which has no saved peers yet, still starts from the bootstrap peers.
+
+Saved peers are checked like any other peer before they enter the routing
+table, and a node with an empty `Bootstrap` list neither saves its routing
+table nor dials saved peers. With the option on, startup no longer waits for a
+first bootstrap round, and the snapshot replaces the backup bootstrap peers:
+the list at `/local/temp_bootstrap_peers` is deleted on startup. With
+[`Routing.AcceleratedDHTClient`](https://github.com/ipfs/kubo/blob/master/docs/config.md#routingaccelerateddhtclient),
+the network crawls still start from the bootstrap peers. The snapshot is stored
+in the repo datastore under `/kad-dht/routing-table/`.
+
+To try it, run `ipfs config --json Routing.PersistDHTRoutingTable true` and
+restart the daemon.
+
 #### 📦️ Dependency updates
 
 - update `go-libp2p` to [v0.50.0](https://github.com/libp2p/go-libp2p/releases/tag/v0.50.0)

docs/config.md

@@ -173,6 +173,7 @@ config file at runtime.
     - [`Routing.DelegatedRouters`](#routingdelegatedrouters)
     - [`Routing.AcceleratedDHTClient`](#routingaccelerateddhtclient)
     - [`Routing.LoopbackAddressesOnLanDHT`](#routingloopbackaddressesonlandht)
+    - [`Routing.PersistDHTRoutingTable`](#routingpersistdhtroutingtable)
     - [`Routing.IgnoreProviders`](#routingignoreproviders)
     - [`Routing.Routers`](#routingrouters)
       - [`Routing.Routers.[name].Type`](#routingroutersnametype)
@@ -923,7 +924,7 @@ The special value `"auto"` automatically uses curated, up-to-date bootstrap peer
 - **Automatic updates**: New bootstrap peers are added as the network evolves
 - **Custom control**: Add your own trusted peers alongside or instead of the defaults
 
-An empty list turns off all bootstrap dialing, including backup peers saved from earlier runs. The node then connects only to `Peering.Peers`, peers found through mDNS, and peers you connect manually. Backup peers are dialed only after the configured peers, when those leave the node below the minimum peer count.
+An empty list turns off all bootstrap dialing, including backup peers saved from earlier runs and the peers saved by [`Routing.PersistDHTRoutingTable`](#routingpersistdhtroutingtable). The node then connects only to `Peering.Peers`, peers found through mDNS, and peers you connect manually. Backup peers are dialed only after the configured peers, when those leave the node below the minimum peer count.
 
 Default: `["auto"]`
 
@@ -3151,6 +3152,39 @@ Default: `false`
 
 Type: `bool` (missing means `false`)
 
+### `Routing.PersistDHTRoutingTable`
+
+Whether the node saves its Amino DHT routing table, and reconnects to those
+peers when it starts instead of going through the [`Bootstrap`](#bootstrap)
+peers first.
+
+When enabled, the peers in the routing table and their addresses are saved to
+the repo after 10 minutes, then every hour, and on shutdown. On the next start,
+the node dials them first. The bootstrap peers are contacted only if fewer than
+10 saved peers answer within 20 seconds, for example after a long time offline.
+Restarts then depend less on a small set of bootstrap peers, and keep working
+when those are unreachable.
+
+Saved peers are checked like any other peer before they enter the routing
+table. A node with an empty [`Bootstrap`](#bootstrap) list neither saves its
+routing table nor dials saved peers. The setting applies to the Amino DHT used
+when [`Routing.Type`](#routingtype) is `auto`, `autoclient`, `dht`, `dhtclient`
+or `dhtserver`. With
+[`Routing.AcceleratedDHTClient`](#routingaccelerateddhtclient), the network
+crawls still start from the bootstrap peers.
+
+When enabled for one of these routing types, this replaces the backup bootstrap
+peers that the node otherwise saves from its connected peers every hour: that
+list is deleted on startup, and `Internal.BackupBootstrapInterval` has no
+effect.
+
+When disabled, the routing table isn't saved, and every start goes through the
+bootstrap peers, with the backup bootstrap peers as a fallback.
+
+Default: `false`
+
+Type: `flag`
+
 ### `Routing.IgnoreProviders`
 
 An array of [string-encoded PeerIDs](https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md#string-representation). Any provider record associated to one of these peer IDs is ignored.

docs/examples/kubo-as-a-library/go.mod

@@ -7,7 +7,7 @@ go 1.26.5
 replace github.com/ipfs/kubo => ./../../..
 
 require (
-	github.com/ipfs/boxo v0.43.0
+	github.com/ipfs/boxo v0.43.1-0.20261021124930-a3f9255caf56
 	github.com/ipfs/kubo v0.0.0-00010101000000-000000000000
 	github.com/libp2p/go-libp2p v0.50.0
 	github.com/multiformats/go-multiaddr v0.16.1
@@ -116,7 +116,7 @@ require (
 	github.com/libp2p/go-doh-resolver v0.6.0 // indirect
 	github.com/libp2p/go-flow-metrics v0.3.0 // indirect
 	github.com/libp2p/go-libp2p-asn-util v0.4.1 // indirect
-	github.com/libp2p/go-libp2p-kad-dht v0.42.2 // indirect
+	github.com/libp2p/go-libp2p-kad-dht v0.43.0 // indirect
 	github.com/libp2p/go-libp2p-kbucket v0.9.0 // indirect
 	github.com/libp2p/go-libp2p-pubsub v0.17.0 // indirect
 	github.com/libp2p/go-libp2p-pubsub-router v0.6.0 // indirect

docs/examples/kubo-as-a-library/go.sum

@@ -266,8 +266,8 @@ github.com/ipfs-shipyard/nopfs/ipfs v0.25.0 h1:OqNqsGZPX8zh3eFMO8Lf8EHRRnSGBMqcd
 github.com/ipfs-shipyard/nopfs/ipfs v0.25.0/go.mod h1:BxhUdtBgOXg1B+gAPEplkg/GpyTZY+kCMSfsJvvydqU=
 github.com/ipfs/bbloom v0.1.0 h1:nIWwfIE3AaG7RCDQIsrUonGCOTp7qSXzxH7ab/ss964=
 github.com/ipfs/bbloom v0.1.0/go.mod h1:lDy3A3i6ndgEW2z1CaRFvDi5/ZTzgM1IxA/pkL7Wgts=
-github.com/ipfs/boxo v0.43.0 h1:nhIbfBBxgLoAxUi8upOIO5RATy++2WigMVWniRJFjnw=
-github.com/ipfs/boxo v0.43.0/go.mod h1:n9HNLPLfAGexg2DGoQ5B4BMVlmj9g4+5dIcuo7w95iI=
+github.com/ipfs/boxo v0.43.1-0.20261021124930-a3f9255caf56 h1:LiSieCK2yysUDcrGbw9eCrhHDDaoznC7rv+Dja3wsLM=
+github.com/ipfs/boxo v0.43.1-0.20261021124930-a3f9255caf56/go.mod h1:88j5vdrVF+ZacX8+73uS2489c6qi2yezKPpU8KnIIdU=
 github.com/ipfs/go-bitfield v1.1.0 h1:fh7FIo8bSwaJEh6DdTWbCeZ1eqOaOkKFI74SCnsWbGA=
 github.com/ipfs/go-bitfield v1.1.0/go.mod h1:paqf1wjq/D2BBmzfTVFlJQ9IlFOZpg422HL0HqsGWHU=
 github.com/ipfs/go-block-format v0.2.4 h1:pgsT9i8zB4YQkBIQRrBwqbQiXPogRCiQnfxd2bC4koI=
@@ -404,8 +404,8 @@ github.com/libp2p/go-libp2p-asn-util v0.4.1 h1:xqL7++IKD9TBFMgnLPZR6/6iYhawHKHl9
 github.com/libp2p/go-libp2p-asn-util v0.4.1/go.mod h1:d/NI6XZ9qxw67b4e+NgpQexCIiFYJjErASrYW4PFDN8=
 github.com/libp2p/go-libp2p-core v0.2.4/go.mod h1:STh4fdfa5vDYr0/SzYYeqnt+E6KfEV5VxfIrm0bcI0g=
 github.com/libp2p/go-libp2p-core v0.3.0/go.mod h1:ACp3DmS3/N64c2jDzcV429ukDpicbL6+TrrxANBjPGw=
-github.com/libp2p/go-libp2p-kad-dht v0.42.2 h1:5RtESYeBbjaF+KIPmU47xz2DOb2iLqvoRCZcsjxCS48=
-github.com/libp2p/go-libp2p-kad-dht v0.42.2/go.mod h1:oLGZ7xq317zXmoeJe0dwgUdOeWeJ85MDJ/+fbKqFoK0=
+github.com/libp2p/go-libp2p-kad-dht v0.43.0 h1:PTa4Qea87dAd+ecAIPIrRIHByFsErjKFkFuYO0rgENU=
+github.com/libp2p/go-libp2p-kad-dht v0.43.0/go.mod h1:H5knPH7Fc8Qp1va9h5C7Dp09MeVB5V30fnKTX847rPs=
 github.com/libp2p/go-libp2p-kbucket v0.3.1/go.mod h1:oyjT5O7tS9CQurok++ERgc46YLwEpuGoFq9ubvoUOio=
 github.com/libp2p/go-libp2p-kbucket v0.9.0 h1:9kTf74R8CHGIk3QK+gwEOnJ/t+JzuxqQSfAAASl1VhM=
 github.com/libp2p/go-libp2p-kbucket v0.9.0/go.mod h1:lKhHVjRq1z/Cl/bFzB2vPzYY0KCdmON6HlBwEAanqjk=

go.mod

@@ -22,7 +22,7 @@ require (
 	github.com/hashicorp/go-version v1.9.0
 	github.com/ipfs-shipyard/nopfs v0.0.14
 	github.com/ipfs-shipyard/nopfs/ipfs v0.25.0
-	github.com/ipfs/boxo v0.43.0
+	github.com/ipfs/boxo v0.43.1-0.20261021124930-a3f9255caf56
 	github.com/ipfs/go-block-format v0.2.4
 	github.com/ipfs/go-cid v0.6.2
 	github.com/ipfs/go-cidutil v0.1.2
@@ -53,7 +53,7 @@ require (
 	github.com/libp2p/go-doh-resolver v0.6.0
 	github.com/libp2p/go-libp2p v0.50.0
 	github.com/libp2p/go-libp2p-http v0.5.0
-	github.com/libp2p/go-libp2p-kad-dht v0.42.2
+	github.com/libp2p/go-libp2p-kad-dht v0.43.0
 	github.com/libp2p/go-libp2p-kbucket v0.9.0
 	github.com/libp2p/go-libp2p-pubsub v0.17.0
 	github.com/libp2p/go-libp2p-pubsub-router v0.6.0

go.sum

@@ -338,8 +338,8 @@ github.com/ipfs-shipyard/nopfs/ipfs v0.25.0 h1:OqNqsGZPX8zh3eFMO8Lf8EHRRnSGBMqcd
 github.com/ipfs-shipyard/nopfs/ipfs v0.25.0/go.mod h1:BxhUdtBgOXg1B+gAPEplkg/GpyTZY+kCMSfsJvvydqU=
 github.com/ipfs/bbloom v0.1.0 h1:nIWwfIE3AaG7RCDQIsrUonGCOTp7qSXzxH7ab/ss964=
 github.com/ipfs/bbloom v0.1.0/go.mod h1:lDy3A3i6ndgEW2z1CaRFvDi5/ZTzgM1IxA/pkL7Wgts=
-github.com/ipfs/boxo v0.43.0 h1:nhIbfBBxgLoAxUi8upOIO5RATy++2WigMVWniRJFjnw=
-github.com/ipfs/boxo v0.43.0/go.mod h1:n9HNLPLfAGexg2DGoQ5B4BMVlmj9g4+5dIcuo7w95iI=
+github.com/ipfs/boxo v0.43.1-0.20261021124930-a3f9255caf56 h1:LiSieCK2yysUDcrGbw9eCrhHDDaoznC7rv+Dja3wsLM=
+github.com/ipfs/boxo v0.43.1-0.20261021124930-a3f9255caf56/go.mod h1:88j5vdrVF+ZacX8+73uS2489c6qi2yezKPpU8KnIIdU=
 github.com/ipfs/go-bitfield v1.1.0 h1:fh7FIo8bSwaJEh6DdTWbCeZ1eqOaOkKFI74SCnsWbGA=
 github.com/ipfs/go-bitfield v1.1.0/go.mod h1:paqf1wjq/D2BBmzfTVFlJQ9IlFOZpg422HL0HqsGWHU=
 github.com/ipfs/go-block-format v0.2.4 h1:pgsT9i8zB4YQkBIQRrBwqbQiXPogRCiQnfxd2bC4koI=
@@ -492,8 +492,8 @@ github.com/libp2p/go-libp2p-gostream v0.6.0 h1:QfAiWeQRce6pqnYfmIVWJFXNdDyfiR/qk
 github.com/libp2p/go-libp2p-gostream v0.6.0/go.mod h1:Nywu0gYZwfj7Jc91PQvbGU8dIpqbQQkjWgDuOrFaRdA=
 github.com/libp2p/go-libp2p-http v0.5.0 h1:+x0AbLaUuLBArHubbbNRTsgWz0RjNTy6DJLOxQ3/QBc=
 github.com/libp2p/go-libp2p-http v0.5.0/go.mod h1:glh87nZ35XCQyFsdzZps6+F4HYI6DctVFY5u1fehwSg=
-github.com/libp2p/go-libp2p-kad-dht v0.42.2 h1:5RtESYeBbjaF+KIPmU47xz2DOb2iLqvoRCZcsjxCS48=
-github.com/libp2p/go-libp2p-kad-dht v0.42.2/go.mod h1:oLGZ7xq317zXmoeJe0dwgUdOeWeJ85MDJ/+fbKqFoK0=
+github.com/libp2p/go-libp2p-kad-dht v0.43.0 h1:PTa4Qea87dAd+ecAIPIrRIHByFsErjKFkFuYO0rgENU=
+github.com/libp2p/go-libp2p-kad-dht v0.43.0/go.mod h1:H5knPH7Fc8Qp1va9h5C7Dp09MeVB5V30fnKTX847rPs=
 github.com/libp2p/go-libp2p-kbucket v0.3.1/go.mod h1:oyjT5O7tS9CQurok++ERgc46YLwEpuGoFq9ubvoUOio=
 github.com/libp2p/go-libp2p-kbucket v0.9.0 h1:9kTf74R8CHGIk3QK+gwEOnJ/t+JzuxqQSfAAASl1VhM=
 github.com/libp2p/go-libp2p-kbucket v0.9.0/go.mod h1:lKhHVjRq1z/Cl/bFzB2vPzYY0KCdmON6HlBwEAanqjk=

routing/delegated.go

@@ -353,7 +353,11 @@ func createDHT(params *ExtraDHTParams, public bool, mode dht.ModeOpt) (routing.R
 		dht.Datastore(params.Datastore),
 		dht.ValueDatastore(DHTValueDatastore(params.Datastore)),
 		dht.Validator(params.Validator),
-		dht.BootstrapPeers(params.BootstrapPeers...))
+		dht.BootstrapPeers(params.BootstrapPeers...),
+		// Custom routers are never closed, so they would only save on a
+		// timer, and their address filtering differs from the default DHT.
+		// Keep them out of routing table persistence for now.
+		dht.RoutingTablePersistence(0))
 
 	return dht.New(params.Host, opts...)
 }

test/cli/backup_bootstrap_test.go

@@ -23,6 +23,9 @@ func TestBackupBootstrapPeers(t *testing.T) {
 			cfg.Addresses.Swarm = []string{fmt.Sprintf("/ip4/127.0.0.1/tcp/%d", harness.NewRandPort())}
 			cfg.Discovery.MDNS.Enabled = false
 			cfg.Internal.BackupBootstrapInterval = config.NewOptionalDuration(250 * time.Millisecond)
+			// Backup bootstrap peers are only saved while the routing table
+			// isn't.
+			cfg.Routing.PersistDHTRoutingTable = config.False
 		})
 	})