From 0a0078c5670c48729230661620fb4f86ef63f6bd Mon Sep 17 00:00:00 2001 From: Arlo Date: Sat, 16 Aug 2025 16:47:18 -0500 Subject: [PATCH 1/5] feat(core/pin): consolidate Add into AddAsync(path, PinAddOptions); add PinAddOptions --- src/CoreApi/IPinApi.cs | 41 +++++++++++++++++++----------------- src/CoreApi/PinAddOptions.cs | 19 +++++++++++++++++ 2 files changed, 41 insertions(+), 19 deletions(-) create mode 100644 src/CoreApi/PinAddOptions.cs diff --git a/src/CoreApi/IPinApi.cs b/src/CoreApi/IPinApi.cs index 2746ae9e..4e4f6886 100644 --- a/src/CoreApi/IPinApi.cs +++ b/src/CoreApi/IPinApi.cs @@ -10,25 +10,28 @@ namespace Ipfs.CoreApi /// Pin API spec public interface IPinApi { - /// - /// Adds an IPFS object to the pinset and also stores it to the IPFS repo. pinset is the set of hashes currently pinned (not gc'able). - /// - /// - /// A CID or path to an existing object, such as "QmXarR6rgkQ2fDSHjSY5nM2kuCXKYGViky5nohtwgF65Ec/about" - /// or "QmZTR5bcpQD7cFgTorqxZDYaew1Wqgfbd2ud9QqGPAkK2V" - /// - /// - /// true to recursively pin links of the object; otherwise, false to only pin - /// the specified object. Default is true. - /// - /// - /// Is used to stop the task. When cancelled, the is raised. - /// - /// - /// A task that represents the asynchronous operation. The task's value - /// is a sequence of that were pinned. - /// - Task> AddAsync(string path, bool recursive = true, CancellationToken cancel = default); + + + /// + /// Adds an IPFS object to the pinset and also stores it to the IPFS repo. pinset is the set of hashes currently pinned (not gc'able). + /// + /// + /// A CID or path to an existing object, such as "QmXarR6rgkQ2fDSHjSY5nM2kuCXKYGViky5nohtwgF65Ec/about" + /// or "QmZTR5bcpQD7cFgTorqxZDYaew1Wqgfbd2ud9QqGPAkK2V" + /// + /// + /// Options for pinning (name and recursion). If null, defaults are used. + /// + /// + /// Is used to stop the task. When cancelled, the is raised. + /// + /// + /// A task that represents the asynchronous operation. The task's value + /// is a sequence of that were pinned. + /// + Task> AddAsync(string path, PinAddOptions options, CancellationToken cancel = default); + + // Removed multiple AddAsync overloads in favor of options-based overload above. /// /// List all the objects pinned to local storage. diff --git a/src/CoreApi/PinAddOptions.cs b/src/CoreApi/PinAddOptions.cs new file mode 100644 index 00000000..94eff599 --- /dev/null +++ b/src/CoreApi/PinAddOptions.cs @@ -0,0 +1,19 @@ +namespace Ipfs.CoreApi +{ + /// + /// Options for pin add. + /// + public class PinAddOptions + { + /// + /// Optional name for created pin(s). + /// + public string? Name { get; set; } + + /// + /// True to recursively pin links of the object; otherwise, false to only pin the specified object. + /// Default is true. + /// + public bool Recursive { get; set; } = true; + } +} From fc8f4863c5653430aafd3311eb989a0cc1882d9e Mon Sep 17 00:00:00 2001 From: Arlo Date: Sat, 16 Aug 2025 18:46:22 -0500 Subject: [PATCH 2/5] Pin API: list options overload; AddAsync progress via IProgress; records-based JSON; tests updated (in dependent http client) --- src/CoreApi/IPinApi.cs | 75 ++++++++++++++++++++--------------- src/CoreApi/PinAddOptions.cs | 66 +++++++++++++++++++++++------- src/CoreApi/PinListOptions.cs | 34 ++++++++++++++++ 3 files changed, 129 insertions(+), 46 deletions(-) create mode 100644 src/CoreApi/PinListOptions.cs diff --git a/src/CoreApi/IPinApi.cs b/src/CoreApi/IPinApi.cs index 4e4f6886..d79925db 100644 --- a/src/CoreApi/IPinApi.cs +++ b/src/CoreApi/IPinApi.cs @@ -1,6 +1,9 @@ using System.Collections.Generic; +using System.Collections; using System.Threading; using System.Threading.Tasks; +using System.Runtime.CompilerServices; +using System; namespace Ipfs.CoreApi { @@ -10,40 +13,43 @@ namespace Ipfs.CoreApi /// Pin API spec public interface IPinApi { - - - /// - /// Adds an IPFS object to the pinset and also stores it to the IPFS repo. pinset is the set of hashes currently pinned (not gc'able). - /// - /// - /// A CID or path to an existing object, such as "QmXarR6rgkQ2fDSHjSY5nM2kuCXKYGViky5nohtwgF65Ec/about" - /// or "QmZTR5bcpQD7cFgTorqxZDYaew1Wqgfbd2ud9QqGPAkK2V" - /// - /// - /// Options for pinning (name and recursion). If null, defaults are used. - /// - /// - /// Is used to stop the task. When cancelled, the is raised. - /// - /// - /// A task that represents the asynchronous operation. The task's value - /// is a sequence of that were pinned. - /// - Task> AddAsync(string path, PinAddOptions options, CancellationToken cancel = default); - - // Removed multiple AddAsync overloads in favor of options-based overload above. - /// - /// List all the objects pinned to local storage. + /// Adds an IPFS object to the pinset and also stores it to the IPFS repo. pinset is the set of hashes currently pinned (not gc'able). /// + /// + /// A CID or path to an existing object, such as "QmXarR6rgkQ2fDSHjSY5nM2kuCXKYGViky5nohtwgF65Ec/about" + /// or "QmZTR5bcpQD7cFgTorqxZDYaew1Wqgfbd2ud9QqGPAkK2V" + /// + /// + /// Options for pinning (name and recursion). If null, defaults are used. + /// /// /// Is used to stop the task. When cancelled, the is raised. /// /// /// A task that represents the asynchronous operation. The task's value - /// is a sequence of . + /// is a sequence of that were pinned. /// - Task> ListAsync(CancellationToken cancel = default); + Task> AddAsync(string path, PinAddOptions options, CancellationToken cancel = default); + + /// + /// Adds an IPFS object to the pinset with progress reporting. + /// + /// The CID or path of the object to pin. + /// Options for pinning (name and recursion). + /// Receives cumulative blocks-pinned updates. + /// Cancellation token. + /// Pinned CIDs on completion. + Task> AddAsync(string path, PinAddOptions options, IProgress progress, CancellationToken cancel = default); + + /// + /// List all the objects pinned to local storage. + /// + /// + /// Is used to stop the task. When cancelled, the is raised. + /// + /// An async sequence of . + IAsyncEnumerable ListAsync(CancellationToken cancel = default); /// /// List all the objects pinned to local storage. @@ -54,11 +60,16 @@ public interface IPinApi /// /// Is used to stop the task. When cancelled, the is raised. /// - /// - /// A task that represents the asynchronous operation. The task's value - /// is a sequence of . - /// - Task> ListAsync(PinType type, CancellationToken cancel = default); + /// An async sequence of . + IAsyncEnumerable ListAsync(PinType type, CancellationToken cancel = default); + + /// + /// List pinned objects with advanced options. + /// + /// List options (type filter, names, stream, etc.). + /// Cancellation token. + /// An async sequence of . + IAsyncEnumerable ListAsync(PinListOptions options, CancellationToken cancel = default); /// /// Unpin an object. @@ -78,5 +89,7 @@ public interface IPinApi /// is a sequence of that were unpinned. /// Task> RemoveAsync(Cid id, bool recursive = true, CancellationToken cancel = default); + + } } diff --git a/src/CoreApi/PinAddOptions.cs b/src/CoreApi/PinAddOptions.cs index 94eff599..34d8c0a6 100644 --- a/src/CoreApi/PinAddOptions.cs +++ b/src/CoreApi/PinAddOptions.cs @@ -1,19 +1,55 @@ -namespace Ipfs.CoreApi +using System.Collections.Generic; + +namespace Ipfs.CoreApi; + + +/// +/// A unified representation of a pin list entry that works for both +/// streaming and non-streaming list responses. +/// +public record PinListItem +{ + /// + /// The CID of the pinned object. + /// + public Ipfs.Cid Cid { get; init; } = null!; + + /// + /// The pin type (direct, indirect, recursive). + /// + public PinType Type { get; init; } + + /// + /// Optional pin name (present when names are requested and set). + /// + public string? Name { get; init; } +} + + +/// +/// Options for pin add. +/// +public record PinAddOptions +{ + /// + /// Optional name for created pin(s). + /// + public string? Name { get; set; } + + /// + /// True to recursively pin links of the object; otherwise, false to only pin the specified object. + /// Default is true. + /// + public bool Recursive { get; set; } = true; +} + +/// +/// Progress notification for pin/add reporting cumulative blocks pinned. +/// +public record BlocksPinnedProgress { /// - /// Options for pin add. + /// The cumulative number of blocks pinned so far. /// - public class PinAddOptions - { - /// - /// Optional name for created pin(s). - /// - public string? Name { get; set; } - - /// - /// True to recursively pin links of the object; otherwise, false to only pin the specified object. - /// Default is true. - /// - public bool Recursive { get; set; } = true; - } + public int BlocksPinned { get; init; } } diff --git a/src/CoreApi/PinListOptions.cs b/src/CoreApi/PinListOptions.cs new file mode 100644 index 00000000..efb43822 --- /dev/null +++ b/src/CoreApi/PinListOptions.cs @@ -0,0 +1,34 @@ +namespace Ipfs.CoreApi; + +/// +/// Options for pin list. +/// +public record PinListOptions +{ + /// + /// The type of pinned keys to list. Can be "direct", "indirect", "recursive", or "all". + /// Default is "all". + /// + public PinType Type { get; set; } = PinType.All; + + /// + /// Output only the CIDs of pins. + /// + public bool Quiet { get; set; } + + /// + /// Limit returned pins to ones with names that contain the value provided (case-sensitive, partial match). + /// Implies Names = true. + /// + public string? Name { get; set; } + + /// + /// Enable streaming of pins as they are discovered. + /// + public bool Stream { get; set; } + + /// + /// Include pin names in the output (slower, disabled by default). + /// + public bool Names { get; set; } +} From abe9f5eb2c4a330500af44a15c5763dc90d3b61f Mon Sep 17 00:00:00 2001 From: Arlo Date: Sat, 16 Aug 2025 18:53:34 -0500 Subject: [PATCH 3/5] AddFileOptions: add PinName for v0.37.0; docs to wire HTTP client pin-name param later --- src/CoreApi/AddFileOptions.cs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/CoreApi/AddFileOptions.cs b/src/CoreApi/AddFileOptions.cs index d0129233..71008255 100644 --- a/src/CoreApi/AddFileOptions.cs +++ b/src/CoreApi/AddFileOptions.cs @@ -17,6 +17,14 @@ public class AddFileOptions /// public bool? Pin { get; set; } + /// + /// Optional name to assign to the pin when pinning during add (Kubo v0.37.0+). + /// + /// + /// Forwarded as the 'pin-name' parameter to the add RPC. Effective when pinning is enabled. + /// + public string? PinName { get; set; } + /// /// Chunking algorithm, size-[bytes], rabin-[min]-[avg]-[max] or buzhash. Required: no. /// From 1d5a7defa6884b0787deb74d6efef96fc2a9e641 Mon Sep 17 00:00:00 2001 From: Arlo Date: Sat, 16 Aug 2025 19:11:44 -0500 Subject: [PATCH 4/5] pin: clarify RemoveAsync remarks that unpinning does not delete blocks; GC required to reclaim --- src/CoreApi/IPinApi.cs | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/CoreApi/IPinApi.cs b/src/CoreApi/IPinApi.cs index d79925db..65a23d13 100644 --- a/src/CoreApi/IPinApi.cs +++ b/src/CoreApi/IPinApi.cs @@ -71,9 +71,13 @@ public interface IPinApi /// An async sequence of . IAsyncEnumerable ListAsync(PinListOptions options, CancellationToken cancel = default); - /// - /// Unpin an object. - /// + /// + /// Unpin an object. + /// + /// + /// Unpinning does not delete the object's blocks; they become eligible for garbage + /// collection and are removed only when GC runs on the node. + /// /// /// The CID of the object. /// From 737d350429691061c27f60ee7ee41d18c75064bd Mon Sep 17 00:00:00 2001 From: Arlo Date: Sat, 16 Aug 2025 19:45:22 -0500 Subject: [PATCH 5/5] Cleanup, split classes into files --- src/CoreApi/BlocksPinnedProgress.cs | 12 ++++++++++ src/CoreApi/IPinApi.cs | 14 ++++++------ src/CoreApi/PinAddOptions.cs | 35 ----------------------------- src/CoreApi/PinListItem.cs | 23 +++++++++++++++++++ 4 files changed, 42 insertions(+), 42 deletions(-) create mode 100644 src/CoreApi/BlocksPinnedProgress.cs create mode 100644 src/CoreApi/PinListItem.cs diff --git a/src/CoreApi/BlocksPinnedProgress.cs b/src/CoreApi/BlocksPinnedProgress.cs new file mode 100644 index 00000000..6e4c7633 --- /dev/null +++ b/src/CoreApi/BlocksPinnedProgress.cs @@ -0,0 +1,12 @@ +namespace Ipfs.CoreApi; + +/// +/// Progress notification for pin/add reporting cumulative blocks pinned. +/// +public record BlocksPinnedProgress +{ + /// + /// The cumulative number of blocks pinned so far. + /// + public int BlocksPinned { get; init; } +} diff --git a/src/CoreApi/IPinApi.cs b/src/CoreApi/IPinApi.cs index 65a23d13..6c3f6d86 100644 --- a/src/CoreApi/IPinApi.cs +++ b/src/CoreApi/IPinApi.cs @@ -71,13 +71,13 @@ public interface IPinApi /// An async sequence of . IAsyncEnumerable ListAsync(PinListOptions options, CancellationToken cancel = default); - /// - /// Unpin an object. - /// - /// - /// Unpinning does not delete the object's blocks; they become eligible for garbage - /// collection and are removed only when GC runs on the node. - /// + /// + /// Unpin an object. + /// + /// + /// Unpinning does not delete the object's blocks; they become eligible for garbage + /// collection and are removed only when GC runs on the node. + /// /// /// The CID of the object. /// diff --git a/src/CoreApi/PinAddOptions.cs b/src/CoreApi/PinAddOptions.cs index 34d8c0a6..7101abd3 100644 --- a/src/CoreApi/PinAddOptions.cs +++ b/src/CoreApi/PinAddOptions.cs @@ -2,30 +2,6 @@ namespace Ipfs.CoreApi; - -/// -/// A unified representation of a pin list entry that works for both -/// streaming and non-streaming list responses. -/// -public record PinListItem -{ - /// - /// The CID of the pinned object. - /// - public Ipfs.Cid Cid { get; init; } = null!; - - /// - /// The pin type (direct, indirect, recursive). - /// - public PinType Type { get; init; } - - /// - /// Optional pin name (present when names are requested and set). - /// - public string? Name { get; init; } -} - - /// /// Options for pin add. /// @@ -42,14 +18,3 @@ public record PinAddOptions /// public bool Recursive { get; set; } = true; } - -/// -/// Progress notification for pin/add reporting cumulative blocks pinned. -/// -public record BlocksPinnedProgress -{ - /// - /// The cumulative number of blocks pinned so far. - /// - public int BlocksPinned { get; init; } -} diff --git a/src/CoreApi/PinListItem.cs b/src/CoreApi/PinListItem.cs new file mode 100644 index 00000000..813bf17f --- /dev/null +++ b/src/CoreApi/PinListItem.cs @@ -0,0 +1,23 @@ +namespace Ipfs.CoreApi; + +/// +/// A unified representation of a pin list entry that works for both +/// streaming and non-streaming list responses. +/// +public record PinListItem +{ + /// + /// The CID of the pinned object. + /// + public Ipfs.Cid Cid { get; init; } = null!; + + /// + /// The pin type (direct, indirect, recursive). + /// + public PinType Type { get; init; } + + /// + /// Optional pin name (present when names are requested and set). + /// + public string? Name { get; init; } +}