feat: define the IPFS Core API for .Net

README.md

@@ -5,7 +5,7 @@
 [![Version](https://img.shields.io/nuget/v/Ipfs.Core.svg)](https://www.nuget.org/packages/Ipfs.Core)
 [![docs](https://cdn.rawgit.com/richardschneider/net-ipfs-core/master/doc/images/docs-latest-green.svg)](https://richardschneider.github.io/net-ipfs-core)
 
-The core objects of the [IPFS](https://github.com/ipfs/ipfs) (Inter Planetary File System) for .Net (C#, VB, F# etc.)
+The core objects and interfaces of the [IPFS](https://github.com/ipfs/ipfs) (Inter Planetary File System) for .Net (C#, VB, F# etc.)
 
 The interplanetary file system is the permanent web. It is a new hypermedia distribution protocol, addressed by content and identities. IPFS enables the creation of completely distributed applications. It aims to make the web faster, safer, and more open.
 

src/CoreApi/IBitswapApi.cs

@@ -5,8 +5,12 @@
 namespace Ipfs.CoreApi
 {
     /// <summary>
-    ///   TODO
+    ///   Interact with the bitswap agent.
     /// </summary>
+    /// <remarks>
+    ///   <note>Not yet ready for prime time.</note>
+    /// </remarks>
+    /// <seealso href="https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/BITSWAP.md">Bitswap API spec</seealso>
     public interface IBitswapApi
     {
     }

src/CoreApi/IBlockApi.cs

@@ -1,4 +1,5 @@
 
+using System.IO;
 using System.Threading;
 using System.Threading.Tasks;
 
@@ -55,15 +56,41 @@ public interface IBlockApi
         ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
         /// </param>
         /// <returns>
-        ///    A task that represents the asynchronous put operation. The task's value
-        ///    contains the block's id and data.
+        ///    A task that represents the asynchronous put operation. The task's value is
+        ///    the block's <see cref="Cid"/>.
         /// </returns>
-        Task<IDataBlock> PutAsync(
+        Task<Cid> PutAsync(
             byte[] data,
             string contentType = Cid.DefaultContentType,
             string multiHash = MultiHash.DefaultAlgorithmName,
             CancellationToken cancel = default(CancellationToken));
 
+        /// <summary>
+        ///   Stores a stream as a IPFS block.
+        /// </summary>
+        /// <param name="data">
+        ///   The <see cref="Stream"/> of data to send to the IPFS network.
+        /// </param>
+        /// <param name="contentType">
+        ///   The content type or format of the <paramref name="data"/>; such as "raw" or "dag-db".
+        ///   See <see cref="MultiCodec"/> for more details.
+        /// </param>
+        /// <param name="multiHash">
+        ///   The <see cref="MultiHash"/> algorithm name used to produce the <see cref="Cid"/>.
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <returns>
+        ///    A task that represents the asynchronous put operation. The task's value is
+        ///    the block's <see cref="Cid"/>.
+        /// </returns>
+        Task<Cid> PutAsync(
+            Stream data,
+            string contentType = Cid.DefaultContentType,
+            string multiHash = MultiHash.DefaultAlgorithmName,
+            CancellationToken cancel = default(CancellationToken));
+
         /// <summary>
         ///   Information on a IPFS block.
         /// </summary>
@@ -75,7 +102,7 @@ public interface IBlockApi
         /// </param>
         /// <returns>
         ///    A task that represents the asynchronous operation. The task's value
-        ///    contains the block's id and data.
+        ///    contains the block's id and size.
         /// </returns>
         Task<IDataBlock> StatAsync(Cid id, CancellationToken cancel = default(CancellationToken));
 
@@ -93,14 +120,14 @@ public interface IBlockApi
         ///   exist.  Default value is <b>false</b>.
         /// </param>
         /// <returns>
-        ///   The awaited Task will return the deleted <paramref name="id"/> or
-        ///   <see cref="string.Empty"/> if the hash does not exist and <paramref name="ignoreNonexistent"/>
+        ///   The awaited Task will return the deleted <paramref name="id"/> or <b>null</b>
+        ///   if the <paramref name="id"/> does not exist and <paramref name="ignoreNonexistent"/>
         ///   is <b>true</b>.
         /// </returns>
         /// <remarks>
         ///   This removes the block from the local cache and does not affect other peers.
         /// </remarks>
-        Task<string> RemoveAsync(Cid id, bool ignoreNonexistent = false, CancellationToken cancel = default(CancellationToken));
+        Task<Cid> RemoveAsync(Cid id, bool ignoreNonexistent = false, CancellationToken cancel = default(CancellationToken));
     }
 
 }

src/CoreApi/ICoreApi.cs

@@ -5,8 +5,12 @@
 namespace Ipfs.CoreApi
 {
     /// <summary>
-    ///   TODO
+    ///   The IPFS Core API.
     /// </summary>
+    /// <remarks>
+    ///   The Core API defines a set of interfaces to manage IPFS.
+    /// </remarks>
+    /// <seealso href="https://github.com/ipfs/interface-ipfs-core"/>
     public interface ICoreApi
     {
         /// <summary>

src/CoreApi/IDagApi.cs

@@ -1,13 +1,62 @@
 using System;
 using System.Collections.Generic;
 using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
 
 namespace Ipfs.CoreApi
 {
     /// <summary>
-    ///   TODO
+    ///   Manages the IPLD Directed Acrylic Graph.
     /// </summary>
+    /// <remarks>
+    ///   The dag API is a replacement of the <see cref="IObjectApi"/>, which only supported 'dag-pb'.
+    ///   This API supports other IPLD formats, such as dag-cbor, ethereum-block, git, ...
+    /// </remarks>
+    /// <seealso cref="IObjectApi"/>
+    /// <seealso cref="ILinkedNode"/>
+    /// <seealso href="https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/DAG.md">Dag API spec</seealso>
     public interface IDagApi
     {
+        /// <summary>
+        ///  Put an IPLD node.
+        /// </summary>
+        /// <param name="data">
+        ///   The data to send to the network.
+        /// </param>
+        /// <param name="contentType">
+        ///   The content type or format of the <paramref name="data"/>; such as "raw" or "dag-db".
+        ///   See <see cref="MultiCodec"/> for more details.
+        /// </param>
+        /// <param name="multiHash">
+        ///   The <see cref="MultiHash"/> algorithm name used to produce the <see cref="Cid"/>.
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <returns>
+        ///    A task that represents the asynchronous put operation. The task's value is
+        ///    the data's <see cref="Cid"/>.
+        /// </returns>
+        Task<Cid> PutAsync(
+            ILinkedNode data,
+            string contentType,
+            string multiHash = MultiHash.DefaultAlgorithmName,
+            CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///   Get an IPLD node.
+        /// </summary>
+        /// <param name="path">
+        ///   The CID or path to an IPLD node.
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <returns>
+        ///   A task that represents the asynchronous get operation. The task's value
+        ///   contains the node's content.
+        /// </returns>
+        Task<ILinkedNode> GetAsync(string path, CancellationToken cancel = default(CancellationToken));
     }
 }

src/CoreApi/IDhtApi.cs

@@ -1,13 +1,44 @@
 using System;
 using System.Collections.Generic;
 using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
 
 namespace Ipfs.CoreApi
 {
-    /// <summary>
-    ///   TODO
-    /// </summary>
+    /// <summary>
+    ///   Manages the Distributed Hash Table.
+    /// </summary>
+    /// <remarks>
+    ///   The DHT is a place to store, not the value, but pointers to peers who have 
+    ///   the actual value.
+    /// </remarks>
+    /// <seealso href="https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/DHT.md">DHT API spec</seealso>
     public interface IDhtApi
     {
+        /// <summary>
+        ///   Information about an IPFS peer.
+        /// </summary>
+        /// <param name="id">
+        ///   The <see cref="MultiHash"/> ID of the IPFS peer.  
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        Task<Peer> FindPeerAsync(MultiHash id, CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///   Find the providers for the specified content.
+        /// </summary>
+        /// <param name="id">
+        ///   The <see cref="Cid"/> of the content.
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <returns>
+        ///   A sequence of IPFS <see cref="Peer"/>.
+        /// </returns>
+        Task<IEnumerable<Peer>> FindProvidersAsync(Cid id, CancellationToken cancel = default(CancellationToken));
     }
 }

src/CoreApi/IFileSystemApi.cs

@@ -1,13 +1,123 @@
 using System;
 using System.Collections.Generic;
+using System.IO;
 using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
 
 namespace Ipfs.CoreApi
 {
-    /// <summary>
-    ///   TODO
-    /// </summary>
+    /// <summary>
+    ///   Manages the files/directories in IPFS.
+    /// </summary>
+    /// <seealso href="https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md">Files API spec</seealso>
     public interface IFileSystemApi
     {
+        /// <summary>
+        ///   Add a local file to the interplanetary file system.
+        /// </summary>
+        /// <param name="path">
+        ///   The name of the local file.
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <returns>
+        ///    A task that represents the asynchronous operation. The task's value is
+        ///    the file's <see cref="Cid"/>.
+        /// </returns>
+        Task<Cid> AddFileAsync(string path, CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///   Add some text to the interplanetary file system.
+        /// </summary>
+        /// <param name="text">
+        ///   The string to add to IPFS.  It is UTF-8 encoded.
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <returns>
+        ///   A task that represents the asynchronous operation. The task's value is
+        ///   the text's <see cref="Cid"/>.
+        /// </returns>
+        Task<Cid> AddTextAsync(string text, CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///   Add a <see cref="Stream"/> to interplanetary file system.
+        /// </summary>
+        /// <param name="stream"></param>
+        /// <param name="name"></param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <returns>
+        ///   A task that represents the asynchronous operation. The task's value is
+        ///   the data's <see cref="Cid"/>.
+        /// </returns>
+        Task<Cid> AddAsync(Stream stream, string name = "", CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///   Add a directory and its files to the interplanetary file system.
+        /// </summary>
+        /// <param name="path">
+        ///   The path to directory.
+        /// </param>
+        /// <param name="recursive">
+        ///   <b>true</b> to add sub-folders.
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <returns>
+        ///   A task that represents the asynchronous operation. The task's value is
+        ///   the directory's <see cref="Cid"/>.
+        /// </returns>
+        Task<Cid> AddDirectoryAsync(string path, bool recursive = true, CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///   Reads the content of an existing IPFS file as text.
+        /// </summary>
+        /// <param name="path">
+        ///   A path to an existing file, such as "QmXarR6rgkQ2fDSHjSY5nM2kuCXKYGViky5nohtwgF65Ec/about"
+        ///   or "QmZTR5bcpQD7cFgTorqxZDYaew1Wqgfbd2ud9QqGPAkK2V"
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <returns>
+        ///   A task that represents the asynchronous operation. The task's value is
+        ///   the contents of the <paramref name="path"/> as a <see cref="string"/>.
+        /// </returns>
+        Task<String> ReadAllTextAsync(string path, CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///   Reads an existing IPFS file.
+        /// </summary>
+        /// <param name="path">
+        ///   A path to an existing file, such as "QmXarR6rgkQ2fDSHjSY5nM2kuCXKYGViky5nohtwgF65Ec/about"
+        ///   or "QmZTR5bcpQD7cFgTorqxZDYaew1Wqgfbd2ud9QqGPAkK2V"
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <returns>
+        ///   A task that represents the asynchronous operation. The task's value is
+        ///   a <see cref="Stream"/> to the file contents.
+        /// </returns>
+        Task<Stream> ReadFileAsync(string path, CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///   Get information about the file or directory.
+        /// </summary>
+        /// <param name="path">
+        ///   A path to an existing file or directory, such as "QmXarR6rgkQ2fDSHjSY5nM2kuCXKYGViky5nohtwgF65Ec/about"
+        ///   or "QmZTR5bcpQD7cFgTorqxZDYaew1Wqgfbd2ud9QqGPAkK2V"
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <returns></returns>
+        Task<IFileSystemNode> ListFileAsync(string path, CancellationToken cancel = default(CancellationToken));
     }
 }

src/CoreApi/IGenericApi.cs

@@ -1,13 +1,36 @@
 using System;
 using System.Collections.Generic;
 using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
 
 namespace Ipfs.CoreApi
 {
     /// <summary>
-    ///   TODO
+    ///   Some miscellaneous methods.
     /// </summary>
+    /// <seealso href="https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/MISCELLANEOUS.md">Generic API spec</seealso>
     public interface IGenericApi
     {
+        /// <summary>
+        ///   Information about an IPFS peer.
+        /// </summary>
+        /// <param name="peer">
+        ///   The id of the IPFS peer.  If not specified (e.g. null), then the local
+        ///   peer is used.
+        /// </param>
+        /// <param name="cancel">
+        ///   Is used to stop the task.  When cancelled, the <see cref="TaskCanceledException"/> is raised.
+        /// </param>
+        /// <returns>
+        ///   Information on the peer node.
+        /// </returns>
+        Task<Peer> IdAsync(MultiHash peer = null, CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///   Get the version information.
+        /// </summary>
+        Task<Dictionary<string, string>> VersionAsync(CancellationToken cancel = default(CancellationToken));
+
     }
 }