feat: add experimental on-demand pinning

config/config.go

@@ -45,6 +45,8 @@ type Config struct {
 	Import        Import
 	Version       Version
 
+	OnDemandPinning OnDemandPinning
+
 	Internal Internal // experimental/unstable options
 
 	Bitswap Bitswap

config/experiments.go

@@ -10,6 +10,7 @@ type Experiments struct {
 	OptimisticProvide             bool
 	OptimisticProvideJobsPoolSize int
 	GatewayOverLibp2p             bool `json:",omitempty"`
+	OnDemandPinningEnabled        bool
 
 	GraphsyncEnabled     graphsyncEnabled                 `json:",omitempty"`
 	AcceleratedDHTClient experimentalAcceleratedDHTClient `json:",omitempty"`

config/ondemandpin.go

@@ -0,0 +1,74 @@
+package config
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/libp2p/go-libp2p-kad-dht/amino"
+)
+
+const (
+	DefaultOnDemandPinReplicationTargetMin = 5
+	DefaultOnDemandPinReplicationTargetMax = 7
+	DefaultOnDemandPinCheckInterval        = 10 * time.Minute
+
+	// Must exceed amino.DefaultProvideValidity so stale DHT records expire
+	// before unpin. The extra day covers check-interval skew.
+	DefaultOnDemandPinUnpinGracePeriod = amino.DefaultProvideValidity + 24*time.Hour
+
+	// Max NextCheckAt delay after repeated check failures (Cap).
+	DefaultOnDemandPinCheckBackoffMax = DefaultOnDemandPinUnpinGracePeriod
+)
+
+type OnDemandPinning struct {
+	// Pin when fewer than this many providers are found in the DHT (excluding self).
+	ReplicationTargetMin OptionalInteger
+
+	// Start the unpin grace period only when more than this many providers are found.
+	ReplicationTargetMax OptionalInteger
+
+	// How often the checker evaluates all registered CIDs.
+	CheckInterval OptionalDuration
+
+	// How long replication must stay above max before unpinning; checker adds up to 2*CheckInterval of jitter.
+	UnpinGracePeriod OptionalDuration
+
+	// When true, the checker logs pin/unpin decisions but does not change the pinset.
+	DryRun Flag `json:",omitempty"`
+}
+
+// ValidateOnDemandPinningConfig rejects invalid min/max and non-positive durations.
+func ValidateOnDemandPinningConfig(cfg *OnDemandPinning) error {
+	min := cfg.ReplicationTargetMin.WithDefault(DefaultOnDemandPinReplicationTargetMin)
+	max := cfg.ReplicationTargetMax.WithDefault(DefaultOnDemandPinReplicationTargetMax)
+	if min < 1 {
+		return fmt.Errorf("OnDemandPinning.ReplicationTargetMin must be at least 1, got %d", min)
+	}
+	if max < min {
+		return fmt.Errorf("OnDemandPinning.ReplicationTargetMax (%d) must be >= ReplicationTargetMin (%d)", max, min)
+	}
+	if interval := cfg.CheckInterval.WithDefault(DefaultOnDemandPinCheckInterval); interval <= 0 {
+		return fmt.Errorf("OnDemandPinning.CheckInterval must be positive, got %v", interval)
+	}
+	if grace := cfg.UnpinGracePeriod.WithDefault(DefaultOnDemandPinUnpinGracePeriod); grace <= 0 {
+		return fmt.Errorf("OnDemandPinning.UnpinGracePeriod must be positive, got %v", grace)
+	}
+	return nil
+}
+
+// ValidateOnDemandPinningRouting rejects Routing.Type=none.
+// Otherwise the checker would pin every registered CID on a null router.
+func ValidateOnDemandPinningRouting(routingType string) error {
+	if routingType == "none" {
+		return fmt.Errorf("on-demand pinning needs provider lookups; Routing.Type=%q is not usable", routingType)
+	}
+	return nil
+}
+
+// ValidateOnDemandPinningProvide rejects Provide.Enabled=false (pins would be invisible).
+func ValidateOnDemandPinningProvide(provideEnabled bool) error {
+	if !provideEnabled {
+		return fmt.Errorf("on-demand pinning needs Provide.Enabled; other nodes cannot discover local pins when providing is off")
+	}
+	return nil
+}

config/ondemandpin_test.go

@@ -0,0 +1,54 @@
+package config
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestValidateOnDemandPinningConfig(t *testing.T) {
+	t.Run("defaults are valid", func(t *testing.T) {
+		err := ValidateOnDemandPinningConfig(&OnDemandPinning{})
+		assert.NoError(t, err)
+	})
+
+	t.Run("zero replication min is rejected", func(t *testing.T) {
+		cfg := &OnDemandPinning{ReplicationTargetMin: *NewOptionalInteger(0)}
+		err := ValidateOnDemandPinningConfig(cfg)
+		assert.ErrorContains(t, err, "ReplicationTargetMin")
+	})
+
+	t.Run("max below min is rejected", func(t *testing.T) {
+		cfg := &OnDemandPinning{
+			ReplicationTargetMin: *NewOptionalInteger(5),
+			ReplicationTargetMax: *NewOptionalInteger(4),
+		}
+		err := ValidateOnDemandPinningConfig(cfg)
+		assert.ErrorContains(t, err, "ReplicationTargetMax")
+	})
+
+	t.Run("zero check interval is rejected", func(t *testing.T) {
+		cfg := &OnDemandPinning{CheckInterval: *NewOptionalDuration(0)}
+		err := ValidateOnDemandPinningConfig(cfg)
+		assert.ErrorContains(t, err, "CheckInterval")
+	})
+
+	t.Run("negative grace period is rejected", func(t *testing.T) {
+		cfg := &OnDemandPinning{UnpinGracePeriod: *NewOptionalDuration(-time.Hour)}
+		err := ValidateOnDemandPinningConfig(cfg)
+		assert.ErrorContains(t, err, "UnpinGracePeriod")
+	})
+}
+
+func TestValidateOnDemandPinningRouting(t *testing.T) {
+	assert.NoError(t, ValidateOnDemandPinningRouting("auto"))
+	assert.NoError(t, ValidateOnDemandPinningRouting("dht"))
+	assert.NoError(t, ValidateOnDemandPinningRouting("delegated"))
+	assert.ErrorContains(t, ValidateOnDemandPinningRouting("none"), "none")
+}
+
+func TestValidateOnDemandPinningProvide(t *testing.T) {
+	assert.NoError(t, ValidateOnDemandPinningProvide(true))
+	assert.ErrorContains(t, ValidateOnDemandPinningProvide(false), "Provide.Enabled")
+}

core/commands/cmdutils/utils.go

@@ -3,6 +3,7 @@ package cmdutils
 import (
 	"fmt"
 	"slices"
+	"strings"
 
 	cmds "github.com/ipfs/go-ipfs-cmds"
 
@@ -54,14 +55,24 @@ func CheckBlockSize(req *cmds.Request, size uint64) error {
 	return nil
 }
 
-// ValidatePinName validates that a pin name does not exceed the maximum allowed byte length.
-// Returns an error if the name exceeds MaxPinNameBytes (255 bytes).
+// ReservedPinNamePrefix is the namespace for pins created by Kubo-internal
+// features rather than by users (e.g. "kubo:on-demand" for on-demand pinning).
+// ValidatePinName rejects user-supplied names with this prefix, so a pin name
+// under this namespace reliably identifies a Kubo-internal pin.
+const ReservedPinNamePrefix = "kubo:"
+
+// ValidatePinName validates that a pin name does not exceed the maximum allowed
+// byte length and does not use the Kubo-internal "kubo:" namespace.
 func ValidatePinName(name string) error {
 	if name == "" {
 		// Empty names are allowed
 		return nil
 	}
 
+	if strings.HasPrefix(name, ReservedPinNamePrefix) {
+		return fmt.Errorf("pin names starting with %q are reserved for kubo-internal pins", ReservedPinNamePrefix)
+	}
+
 	nameBytes := len([]byte(name))
 	if nameBytes > MaxPinNameBytes {
 		return fmt.Errorf("pin name is %d bytes (max %d bytes)", nameBytes, MaxPinNameBytes)

core/commands/cmdutils/utils_test.go

@@ -178,4 +178,10 @@ func TestValidatePinName(t *testing.T) {
 		require.Error(t, err)
 		assert.Contains(t, err.Error(), "bytes")
 	})
+
+	t.Run("pin name with reserved prefix is rejected", func(t *testing.T) {
+		err := ValidatePinName(ReservedPinNamePrefix + "on-demand")
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "reserved")
+	})
 }

core/commands/commands_test.go

@@ -168,6 +168,10 @@ func TestCommands(t *testing.T) {
 		"/pin/remote/service/add",
 		"/pin/remote/service/ls",
 		"/pin/remote/service/rm",
+		"/pin/ondemand",
+		"/pin/ondemand/add",
+		"/pin/ondemand/rm",
+		"/pin/ondemand/ls",
 		"/pin/rm",
 		"/pin/update",
 		"/pin/verify",