feat: add experimental on-demand pinning

[ihlec]

Summary

Automatically pin content when DHT provider counts fall below a configurable replication target, and unpin once
replication has been above target for a grace period.

Helps keeping critical data around, without wasting storage on overly replicated CIDs.

The feature is described in this draft: ipfs/specs#532
The feature is gated behind Experimental.OnDemandPinningEnabled.

CLI commands for ipfs pin ondemand:

• add -- register CIDs for on-demand pinning
• rm -- deregister and unpin
• ls -- list registered CIDs

Design

• Pin partitioning: the checker needs to distinguish its pins from user
  pins to avoid accidental deletion. This implementation uses boxo's pin name
  field ("on-demand") for that.
• Storage budget: skips pinning when repo usage exceeds
  StorageMax * StorageGCWatermark.
• Idle timeout: DAG fetches timeout after 2 minutes
  without receiving new blocks (allows large downloads while skipping dead records).
• Provide after pin: the checker publishes a DHT provider record after pinning.
• Sybil limitation: provider counts come from DHT queries, which are
  susceptible to Sybil manipulation. Documented as a known limitation.

Configuration Parameters (TBD)

Option	Default	Description
OnDemandPinning.ReplicationTarget	5	Minimum providers in DHT (excluding self)
OnDemandPinning.CheckInterval	"10m"	How often the checker runs
OnDemandPinning.UnpinGracePeriod	"24h"	How long above target before unpinning

Tests

Unit tests for the checker and store in ondemandpin/.

Visualization of Feature

(out of scope for this CLI PR, but helpful to get the idea)

[ihlec]

Please focus the review on:

1. Core logic — ondemandpin/

• ondemandpin/store.go (143 lines) — Datastore with CRUD to manage on-demand pinning CIDs.
• ondemandpin/checker.go (282 lines) — Frequently queries the DHT for provider counts and pins/unpins accordingly.

2. Kubo integration — wiring and CLI

• core/node/ondemandpin.go (168 lines) — translates Kubo's pinning system into a simple interface for checker.go.
• core/commands/pin/ondemandpin.go (280 lines) — Standard cmds boilerplate for on-demand pinning.

*The rest of the files are configuration, glue code, and documentation.

[ihlec]

@guillaumemichel Please re-run the checks. I addressed the failing ones for overfull lines , typos, and changelog.

[ihlec]

the ondemand ls command shows the locally stored pin records (CID, pinned status, timestamps). With ---live, it additionally queries the DHT in real-time to report how many providers currently exist

[ihlec]

DHT queries are sequential. Doing ipfs pin ondemand ls --live on hundreds of CIDs will take a long time. Still handy for debugging and development.

[lidel]

Triage note: we run out of time to review this in 0.41 iteration, but we've added it to 0.42. Thank you for your contribution and patience. 🙏

[gammazero]

Triage: need careful review and testing.

[lidel]

Triage: short on review bandwidth for v0.42, so we'd like to land this in v0.43 instead. I've rebased on latest master and moved the changelog entry to docs/changelogs/v0.43.md. Nothing for you to do; we'll continue review against v0.43 once the time comes.