Merge pull request #89 from richardschneider/88-bitswap-ledger

Bitswap ledger with another peer

src/CoreApi/BitswapLedger.cs

@@ -0,0 +1,79 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace Ipfs.CoreApi
+{
+    /// <summary>
+    ///   Statistics on the <see cref="IBitswapApi">bitswap</see> blocks exchanged with another <see cref="Peer"/>.
+    /// </summary>
+    /// <seealso cref="IBitswapApi.LedgerAsync"/>
+    public class BitswapLedger
+    {
+        /// <summary>
+        ///   The <see cref="Peer"/> that pertains to this ledger.
+        /// </summary>
+        /// <value>
+        ///   The peer that is being monitored.
+        /// </value>
+        public Peer Peer { get; set; }
+
+        /// <summary>
+        ///   The number of blocks sent by the <see cref="Peer"/> to us.
+        /// </summary>
+        /// <value>
+        ///   The number of blocks.
+        /// </value>
+        public ulong BlocksReceived { get; set; }
+
+        /// <summary>
+        ///   The number of blocks sent by us to the <see cref="Peer"/>.
+        /// </summary>
+        /// <value>
+        ///   The number of blocks.
+        /// </value>
+        public ulong BlocksSent { get; set; }
+
+        /// <summary>
+        ///   The number of bytes sent by the <see cref="Peer"/> to us.
+        /// </summary>
+        /// <value>
+        ///   The number of bytes.
+        /// </value>
+        public ulong DataReceived { get; set; }
+
+
+        /// <summary>
+        ///   The number of bytes sent by us to the <see cref="Peer"/>
+        /// </summary>
+        /// <value>
+        ///   The number of bytes.
+        /// </value>
+        public ulong DataSent { get; set; }
+
+        /// <summary>
+        ///   The calculated debt to the peer.
+        /// </summary>
+        /// <value>
+        ///   <see cref="DataSent"/> divided by <see cref="DataReceived"/>.
+        ///   A value less than 1 indicates that we are in debt to the 
+        ///   <see cref="Peer"/>.
+        /// </value>
+        public float DebtRatio
+        {
+            get
+            {
+                return (float)DataSent / (float)(DataReceived + 1); // +1 is to prevent division by zero
+            }
+        }
+
+        /// <summary>
+        ///   Determines if we owe the <see cref="Peer"/> some blocks.
+        /// </summary>
+        /// <value>
+        ///   <b>true</b> if we owe data to the peer; otherwise, <b>false</b>.
+        /// </value>
+        public bool IsInDebt => DebtRatio < 1;
+
+    }
+}

src/CoreApi/IBitswapApi.cs

@@ -11,9 +11,19 @@ namespace Ipfs.CoreApi
     ///   send blocks to other peers in the network.
     /// </summary>
     /// <remarks>
-    ///   Bitswap has two primary jobs (1) Attempt to acquire blocks from the network that 
-    ///   have been requested by the client and (2) Judiciously(though strategically)
-    ///   send blocks in its possession to other peers who want them.
+    ///   Bitswap has two primary jobs
+    ///   <list type="bullet">
+    ///     <item>
+    ///       <description>
+    ///       Attempt to acquire blocks from the network that  have been requested by the client
+    ///       </description>
+    ///     </item>
+    ///     <item>
+    ///       <description>
+    ///       Judiciously (though strategically) send blocks in its possession to other peers who want them
+    ///       </description>
+    ///     </item>
+    ///   </list>
     /// </remarks>
     /// <seealso href="https://github.com/ipfs/specs/tree/master/bitswap">Bitswap spec</seealso>
     public interface IBitswapApi
@@ -68,6 +78,22 @@ public interface IBitswapApi
         ///   Any outstanding <see cref="GetAsync(Cid, CancellationToken)"/> for the
         ///   <paramref name="id"/> are cancelled.
         /// </remarks>
-        Task UnwantAsync(Cid id, CancellationToken cancel = default(CancellationToken));
+        Task UnwantAsync(Cid id, CancellationToken cancel = default(CancellationToken));
+
+        /// <summary>
+        ///   Gets information on the blocks exchanged with a specific <see cref="Peer"/>.
+        /// </summary>
+        /// <param name="peer">
+        ///   The peer to get information on.  If the peer is unknown, then a ledger
+        ///   with zeros is returned.
+        /// </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
+        ///   contains the <see cref="BitswapLedger"/> for the <paramref name="peer"/>.
+        /// </returns>
+        Task<BitswapLedger> LedgerAsync(Peer peer, CancellationToken cancel = default(CancellationToken));
     }
 }

test/CoreApi/BitswapLedgerTest.cs

@@ -0,0 +1,41 @@
+using System;
+using System.Linq;
+using System.Text;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+namespace Ipfs.CoreApi
+{
+    [TestClass]
+    public class BitswapLedgerTest
+    {
+        [TestMethod]
+        public void Defaults()
+        {
+            var ledger = new BitswapLedger();
+
+            Assert.IsNull(ledger.Peer);
+            Assert.AreEqual(0ul, ledger.BlocksReceived);
+            Assert.AreEqual(0ul, ledger.BlocksSent);
+            Assert.AreEqual(0ul, ledger.DataReceived);
+            Assert.AreEqual(0ul, ledger.DataSent);
+            Assert.AreEqual(0f, ledger.DebtRatio);
+            Assert.IsTrue(ledger.IsInDebt);
+        }
+
+        [TestMethod]
+        public void DebtRatio_Positive()
+        {
+            var ledger = new BitswapLedger { DataSent = 1024 * 1024 };
+            Assert.IsTrue(ledger.DebtRatio >= 1);
+            Assert.IsFalse(ledger.IsInDebt);
+        }
+
+        [TestMethod]
+        public void DebtRatio_Negative()
+        {
+            var ledger = new BitswapLedger { DataReceived = 1024 * 1024 };
+            Assert.IsTrue(ledger.DebtRatio < 1);
+            Assert.IsTrue(ledger.IsInDebt);
+        }
+    }
+}