Merge pull request #13 from Derrick-/MFS-Api

IMfsApi and supporting models for making calls to /files endpoints

src/CoreApi/FileStat.cs

@@ -0,0 +1,64 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace Ipfs.CoreApi
+{
+    /// <summary>
+    ///   Information on a MFS file path
+    /// </summary>
+    /// <seealso cref="IMfsApi.StatAsync(string, System.Threading.CancellationToken)"/>
+    public class FileStatResult
+    {
+        /// <summary>
+        /// The <see cref="Cid"/> of the file or directory.
+        /// </summary>
+        public Cid Hash { get; set; }
+
+        /// <summary>
+        ///   The serialised size (in bytes) of the linked node.
+        /// </summary>
+        public Int64 Size { get; set; }
+
+        /// <summary>
+        ///   Size of object and its references.
+        /// </summary>
+        public Int64 CumulativeSize { get; set; }
+
+        /// <summary>
+        ///   Determines if the node is a directory (folder).
+        /// </summary>
+        /// <value>
+        ///   <b>true</b> if the node is a directory; Otherwise <b>false</b>,
+        ///   it is some type of a file.
+        /// </value>
+        public bool IsDirectory { get; set; }
+
+        /// <summary>
+        /// Number of blocks
+        /// </summary>
+        public int Blocks { get; set; }
+    }
+
+    /// <summary>
+    ///   Expanded <see cref="FileStatResult"/> result when parameter is-local=true is used.
+    /// </summary>
+    /// <seealso cref="IMfsApi.StatAsync(string, bool, System.Threading.CancellationToken)"/>
+    public class FileStatWithLocalityResult : FileStatResult
+    {
+        /// <summary>
+        ///   Is local object.
+        /// </summary>
+        public bool Local { get; set; }
+
+        /// <summary>
+        ///   The serialised size (in bytes) of the linked node that is local.
+        /// </summary>
+        public Int64 SizeLocal { get; set; }
+
+        /// <summary>
+        ///   Reflection of the parameter is-local.
+        /// </summary>
+        public bool WithLocality { get; set; }
+    }
+}

src/CoreApi/IMfsApi.cs

@@ -0,0 +1,219 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Ipfs.CoreApi
+{
+    /// <summary>
+    ///   Manages the files/directories in MPS.
+    /// </summary>
+    /// <seealso href="https://docs.ipfs.tech/reference/kubo/rpc/#api-v0-files-chcid">Files API docs</seealso>
+    /// <seealso href="https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md">Files API spec</seealso>
+    public interface IMfsApi
+    {
+        /// <summary>
+        ///   Add references to IPFS files and directories in MFS (or copy within MFS).
+        /// </summary>
+        /// <param name="sourceMfsPathOrCid">
+        ///   Source IPFS or MFS path to copy. Required: yes
+        /// </param>
+        /// <param name="destMfsPath">
+        ///   Destination within MFS. Required: yes
+        /// </param>
+        /// <param name="parents">
+        ///   Make parent directories as needed. Required: no
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        Task CopyAsync(string sourceMfsPathOrCid, string destMfsPath, bool? parents = null, CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///   Flush a given path's data to disk.
+        /// </summary>
+        /// <param name="path">
+        ///   Path to flush. Default: '/'. Required: no
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <returns>
+        ///   <see cref="Cid"/> of the flushed path.
+        /// </returns>
+        Task<Cid> FlushAsync(string path = null, CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///   List directories in the local mutable namespace.
+        /// </summary>
+        /// <param name="path">Path to show listing for. Defaults to '/'. Required: no
+        /// </param>
+        /// <param name="U">Do not sort; list entries in directory order. Required: no
+        /// </param>
+        /// <param name="cancel">Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <returns>Collection of <see cref="IFileSystemNode"/>
+        /// </returns>
+        /// <remarks>
+        ///   Paramter long is ommitted and should always be passed as true in implementation.
+        /// </remarks>
+        Task<IEnumerable<IFileSystemNode>> ListAsync(string path, bool? U = null, CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///   Make directories in the local mutable namespace.
+        /// </summary>
+        /// <param name="path">
+        ///   Path to dir to make. Required: yes
+        /// </param>
+        /// <param name="parents">
+        ///   No error if existing, make parent directories as needed. Required: no
+        /// </param>
+        /// <param name="cidVersion">
+        ///   Cid version to use. (experimental). Required: no
+        /// </param>
+        /// <param name="multiHash">
+        ///   The <see cref="MultiHash"/> algorithm name used to produce the <see cref="Cid"/>
+        ///   Will set Cid version to 1 if used. (experimental). Required: no
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        Task MakeDirectoryAsync(string path, bool? parents = null, int? cidVersion = null, string multiHash = null, CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///    Move file or directory to another path in MFS.
+        /// </summary>
+        /// <param name="sourceMfsPath">
+        ///   Source file to move. Required: yes
+        /// </param>
+        /// <param name="destMfsPath">
+        ///   Destination path for file to be moved to. Required: yes
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        Task MoveAsync(string sourceMfsPath, string destMfsPath, CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///   Read a file from MFS.
+        /// </summary>
+        /// <param name="path">
+        ///   Path to file to be read. Required: yes
+        /// </param>
+        /// <param name="offset">
+        ///   Byte offset to begin reading from. Required: no
+        /// </param>
+        /// <param name="count">
+        ///   Maximum number of bytes to read. Required: no
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        Task<string> ReadFileAsync(string path, Int64? offset = null, Int64? count = null, CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///   Remove a file or directory or from MFS.
+        /// </summary>
+        /// <param name="path">
+        ///   File or directory to remove. Required: yes
+        /// </param>
+        /// <param name="recursive">
+        ///   Recursively remove directories. Must be true to remove a directory. Required: no
+        /// </param>
+        /// <param name="force">
+        ///   Forcibly remove target at path; implies recursive for directories. Required: no
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        Task RemoveAsync(string path, bool? recursive = null, bool? force = null, CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///   Get file or directory status info.
+        /// </summary>
+        /// <param name="path">
+        ///   Path to node to stat. Required: yes
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <returns>
+        ///   <see cref="FileStatResult"/> information about the path.
+        /// </returns>
+        Task<FileStatResult> StatAsync(string path, CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///   Get file or directory status info including information about locality of data.
+        /// </summary>
+        /// <param name="path">
+        ///   Path to node to stat. Required: yes
+        /// </param>
+        /// <param name="withLocal">
+        ///   Populate locality information in result.
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <returns>
+        ///   <see cref="FileStatWithLocalityResult"/> information about the path including 
+        ///   additional information on locality if withLocal=true.
+        /// </returns>
+        Task<FileStatWithLocalityResult> StatAsync(string path, bool withLocal, CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///   Append to (modify) a text file in MFS.
+        /// </summary>
+        /// <param name="path">
+        ///   Path to write to. Required: yes
+        /// </param>
+        /// <param name="text">
+        ///   A <see cref="string"/> containing the text to write.
+        /// </param>
+        /// <param name="options">
+        ///   The options when adding data to the IPFS file system.
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <seealso cref="MfsWriteOptions"/>
+        Task WriteAsync(string path, string text, MfsWriteOptions options, CancellationToken cancel = default);
+
+        /// <summary>
+        ///   Append to (modify) a binary file in MFS.
+        /// </summary>
+        /// <param name="path">
+        ///   Path to write to. Required: yes
+        /// </param>
+        /// <param name="data">
+        ///   A <see cref="string"/> containing the text to write.
+        /// </param>
+        /// <param name="options">
+        ///   The options when adding data to the IPFS file system.
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <seealso cref="MfsWriteOptions"/>
+        Task WriteAsync(string path, byte[] data, MfsWriteOptions options, CancellationToken cancel = default);
+
+        /// <summary>
+        ///   Append to (modify) a file in MFS.
+        /// </summary>
+        /// <param name="path">
+        ///   Path to write to. Required: yes
+        /// </param>
+        /// <param name="data">
+        ///   A <see cref="Stream"/> containing the data to upload.
+        /// </param>
+        /// <param name="options">
+        ///   The options when adding data to the IPFS file system.
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <seealso cref="MfsWriteOptions"/>
+        Task WriteAsync(string path, Stream data, MfsWriteOptions options, CancellationToken cancel = default(CancellationToken));
+    }
+}

src/CoreApi/MfsWriteOptions.cs

@@ -0,0 +1,83 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace Ipfs.CoreApi
+{
+    /// <summary>
+    ///   The options when adding data to the MFS file system.
+    /// </summary>
+    /// <seealso cref="IMfsApi.WriteAsync(string, string, MfsWriteOptions, System.Threading.CancellationToken)"/>
+    /// <seealso cref="IMfsApi.WriteAsync(string, System.IO.Stream, MfsWriteOptions, System.Threading.CancellationToken)"/>
+    public class MfsWriteOptions
+    {
+        /// <summary>
+        ///   Create the file if it does not exist
+        /// </summary>
+        /// <value>
+        ///   The default is <b>null</b> and the server will use its default of false.
+        /// </value>
+        public bool? Create { get; set; } = null;
+
+        /// <summary>
+        ///   Make parent directories as needed.
+        /// </summary>
+        /// <value>
+        ///   The default is <b>null</b> and the server will use its default of false.
+        /// </value>
+        public bool? Parents { get; set; } = null;
+
+        /// <summary>
+        ///   Byte offset to begin writing at.
+        /// </summary>
+        /// <value>
+        ///   The default is <b>null</b> and the argument will be omitted.
+        ///   If ommitted the offset is zero.
+        /// </value>
+        public Int64? Offset { get; set; } = null;
+
+        /// <summary>
+        ///   Maximum number of bytes to write.
+        /// </summary>
+        /// <value>
+        ///   The default is <b>null</b> and the argument will be omitted.
+        ///   If ommitted, all the data will be written.
+        /// </value>
+        public Int64? Count { get; set; } = null;
+
+        /// <summary>
+        ///    Cid version to use.
+        /// </summary>
+        /// <value>
+        ///   The default is <b>null</b> and the server will use its default Cid Version.
+        /// </value>
+        /// <seealso cref="Cid.Version"/>
+        public int? CidVersion { get; set; } = null;
+
+        /// <summary>
+        ///   Truncate the file to size zero before writing
+        /// </summary>
+        /// <value>
+        ///   The default is <b>null</b> and the server will use its default of false.
+        /// </value>
+        public bool? Truncate { get; set; } = null;
+
+        /// <summary>
+        ///   Use raw blocks for newly created leaf nodes.
+        /// </summary>
+        /// <value>
+        ///   The default is <b>null</b> and the server will use its default of false.
+        /// </value>
+        public bool? RawLeaves { get; set; } = null;
+
+        /// <summary>
+        ///   The hashing algorithm name to use.
+        /// </summary>
+        /// <value>
+        ///   The <see cref="MultiHash"/> algorithm name used to produce the <see cref="Cid"/>.
+        ///   The default is <b>null</b> and the server will use its default algorithm name.
+        /// </value>
+        /// <seealso cref="MultiHash.DefaultAlgorithmName"/>
+        public string Hash { get; set; } = null;
+    }
+}