docs(settlement): extend settlement docs

Author: gakonst

crates/interledger-settlement/Cargo.toml

@@ -26,11 +26,9 @@ tokio-retry = { version = "0.2.0", default-features = false }
 tokio = { version = "0.2.6", default-features = false, features = ["macros", "rt-core"] }
 num-bigint = { version = "0.2.3", default-features = false, features = ["std"] }
 num-traits = { version = "0.2.8", default-features = false }
-# warp = { version = "0.1.20", default-features = false }
-warp = { git = "https://github.com/seanmonstar/warp", default-features = false }
+warp = { version = "0.2", default-features = false }
 http = "0.2.0"
-# redis_crate = { package = "redis", version = "0.13.0", optional = true }
-redis_crate = { package = "redis", git = "https://github.com/mitsuhiko/redis-rs", optional = true, features = ["tokio-rt-core"] }
+redis_crate = { package = "redis", version = "0.15.1", optional = true, features = ["tokio-rt-core"] }
 async-trait = "0.1.22"
 
 [dev-dependencies]

crates/interledger-settlement/src/api/client.rs

@@ -6,18 +6,27 @@ use reqwest::Client;
 use serde_json::json;
 use uuid::Uuid;
 
+/// Helper struct to execute settlements
 #[derive(Clone)]
 pub struct SettlementClient {
+    /// Asynchronous reqwest client
     http_client: Client,
 }
 
 impl SettlementClient {
+    /// Simple constructor
     pub fn new() -> Self {
         SettlementClient {
             http_client: Client::new(),
         }
     }
 
+    /// Sends a settlement request to the node's settlement engine for the provided account and amount
+    ///
+    /// # Errors
+    /// 1. Account has no engine configured
+    /// 1. HTTP request to engine failed from node side
+    /// 1. HTTP response from engine was an error
     pub async fn send_settlement<A: SettlementAccount + Account>(
         &self,
         account: A,

crates/interledger-settlement/src/api/message_service.rs

@@ -10,9 +10,15 @@ use tokio_retry::{strategy::ExponentialBackoff, Retry};
 
 const PEER_FULFILLMENT: [u8; 32] = [0; 32];
 
+/// Service which implements [`IncomingService`](../../interledger_service/trait.IncomingService.html).
+/// Responsible for catching incoming requests which are sent to `peer.settle` and forward them to
+/// the node's settlement engine via HTTP
 #[derive(Clone)]
 pub struct SettlementMessageService<I, A> {
+    /// The next incoming service which requests that don't get caught get sent to
     next: I,
+    /// HTTP client used to notify the engine corresponding to the account about
+    /// an incoming message from a peer's engine
     http_client: Client,
     account_type: PhantomData<A>,
 }

crates/interledger-settlement/src/api/mod.rs

@@ -1,13 +1,16 @@
+/// Settlement-related client methods
 mod client;
+/// [`IncomingService`](../../interledger_service/trait.IncomingService.html) which catches
+/// incoming requests which are sent to `peer.settle` (the node's settlement engine ILP address)
 mod message_service;
+/// The Warp API exposed by the connector
 mod node_api;
 
 #[cfg(test)]
 mod fixtures;
 #[cfg(test)]
 mod test_helpers;
 
-// Expose the API creation filter method and the necessary services
 pub use client::SettlementClient;
 pub use message_service::SettlementMessageService;
 pub use node_api::create_settlements_filter;

crates/interledger-settlement/src/api/node_api.rs

@@ -23,11 +23,14 @@ use std::{
 use uuid::Uuid;
 use warp::{self, reject::Rejection, Filter};
 
+/// Prepare packet's execution condition as defined in the [RFC](https://interledger.org/rfcs/0038-settlement-engines/#exchanging-messages)
 static PEER_PROTOCOL_CONDITION: [u8; 32] = [
     102, 104, 122, 173, 248, 98, 189, 119, 108, 143, 193, 139, 142, 159, 142, 32, 8, 151, 20, 133,
     110, 226, 51, 179, 144, 42, 89, 29, 13, 95, 41, 37,
 ];
 
+/// Makes an idempotent call to [`do_receive_settlement`](./fn.do_receive_settlement.html)
+/// Returns Status Code 201
 async fn receive_settlement<S, A>(
     account_id: String,
     idempotency_key: Option<String>,
@@ -65,6 +68,8 @@ where
         .unwrap())
 }
 
+/// Makes an idempotent call to [`do_send_outgoing_message`](./fn.do_send_outgoing_message.html)
+/// Returns Status Code 201
 async fn send_message<S, A, O>(
     account_id: String,
     idempotency_key: Option<String>,
@@ -103,6 +108,11 @@ where
         .unwrap())
 }
 
+/// Returns a Node Settlement filter which exposes a Warp-compatible
+/// idempotent API which
+/// 1. receives messages about incoming settlements from the engine
+/// 1. sends messages from the connector's engine to the peer's
+///    message service which are sent to the peer's engine
 pub fn create_settlements_filter<S, O, A>(
     store: S,
     outgoing_handler: O,
@@ -153,6 +163,10 @@ where
         .boxed()
 }
 
+/// Receives a settlement message from the connector's engine, proceeds to scale it to the
+/// asset scale which corresponds to the account, and finally increases the account's balance
+/// by the processed amount. This implements the main functionality by which an account's credit
+/// is repaid, allowing them to send out more payments
 async fn do_receive_settlement<S, A>(
     store: S,
     account_id: String,
@@ -270,6 +284,10 @@ where
     Ok(ApiResponse::Default)
 }
 
+/// Sends a messages via the provided `outgoing_handler` with the `peer.settle`
+/// ILP Address as ultimate destination. This messages should get caught by the
+/// peer's message service, get forwarded to their engine, and then the response
+/// should be communicated back via a Fulfill or Reject packet
 async fn do_send_outgoing_message<S, O, A>(
     store: S,
     outgoing_handler: O,
@@ -337,7 +355,7 @@ where
     match packet {
         Ok(fulfill) => {
             // TODO: Can we avoid copying here?
-            let data = Bytes::copy_from_slice(fulfill.as_ref());
+            let data = Bytes::copy_from_slice(fulfill.data());
             Ok(ApiResponse::Data(data))
         }
         Err(reject) => {

crates/interledger-settlement/src/core/backends_common/redis/mod.rs

@@ -21,20 +21,26 @@ use async_trait::async_trait;
 #[cfg(test)]
 mod test_helpers;
 
+/// Domain separator for leftover amounts
 static UNCREDITED_AMOUNT_KEY: &str = "uncredited_engine_settlement_amount";
+
+/// Helper function to get a redis key
 fn uncredited_amount_key(account_id: &str) -> String {
     format!("{}:{}", UNCREDITED_AMOUNT_KEY, account_id)
 }
 
+/// Builder object to create a Redis connection for the engine
 pub struct EngineRedisStoreBuilder {
     redis_url: ConnectionInfo,
 }
 
 impl EngineRedisStoreBuilder {
+    /// Simple constructor
     pub fn new(redis_url: ConnectionInfo) -> Self {
         EngineRedisStoreBuilder { redis_url }
     }
 
+    /// Connects to the provided redis_url and returns a Redis connection for the Settlement Engine
     pub async fn connect(&self) -> Result<EngineRedisStore, ()> {
         let client = match Client::open(self.redis_url.clone()) {
             Ok(c) => c,
@@ -133,6 +139,7 @@ impl IdempotentStore for EngineRedisStore {
     }
 }
 
+/// Helper datatype for storing and loading quantities of a number with different scales
 #[derive(Debug, Clone)]
 struct AmountWithScale {
     num: BigUint,
@@ -152,11 +159,11 @@ impl ToRedisArgs for AmountWithScale {
 }
 
 impl AmountWithScale {
+    /// Iterates over all values because in this case it's making
+    /// an lrange call. This returns all the tuple elements in 1 array, and
+    /// it cannot differentiate between 1 AmountWithScale value or multiple
+    /// ones. This looks like a limitation of redis.rs
     fn parse_multi_values(items: &[Value]) -> Option<Self> {
-        // We have to iterate over all values because in this case we're making
-        // an lrange call. This returns all the tuple elements in 1 array, and
-        // it cannot differentiate between 1 AmountWithScale value or multiple
-        // ones. This looks like a limitation of redis.rs
         let len = items.len();
         let mut iter = items.iter();
 

crates/interledger-settlement/src/core/engines_api.rs

@@ -19,6 +19,8 @@ pub struct CreateAccount {
     id: String,
 }
 
+/// Makes an idempotent call to [`engine.create_account`](../types/trait.SettlementEngine.html#tymethod.create_account)
+/// Returns `Status Code 201`
 async fn create_engine_account<E, S>(
     idempotency_key: Option<String>,
     account_id: CreateAccount,
@@ -47,6 +49,8 @@ where
         .unwrap())
 }
 
+/// Makes an idempotent call to [`engine.delete_account`](../types/trait.SettlementEngine.html#tymethod.delete_account)
+/// Returns Status Code `204`.
 async fn delete_engine_account<E, S>(
     account_id: String,
     idempotency_key: Option<String>,
@@ -75,6 +79,8 @@ where
         .unwrap())
 }
 
+/// Makes an idempotent call to [`engine.send_money`](../types/trait.SettlementEngine.html#tymethod.send_money)
+/// Returns Status Code `201`
 async fn engine_send_money<E, S>(
     id: String,
     idempotency_key: Option<String>,
@@ -105,6 +111,8 @@ where
         .unwrap())
 }
 
+/// Makes an idempotent call to [`engine.receive_message`](../types/trait.SettlementEngine.html#tymethod.receive_message)
+/// Returns Status Code `201`
 async fn engine_receive_message<E, S>(
     id: String,
     idempotency_key: Option<String>,

crates/interledger-settlement/src/core/idempotency.rs

@@ -7,14 +7,19 @@ use http::StatusCode;
 use interledger_http::error::*;
 use log::error;
 
+/// Data stored for the idempotency features
 #[derive(Debug, Clone, PartialEq)]
 pub struct IdempotentData {
+    /// The HTTP Status Code of the API's response
     pub status: StatusCode,
+    /// The body of the API's response
     pub body: Bytes,
+    /// The hash of the serialized input parameters which generated the API's response
     pub input_hash: [u8; 32],
 }
 
 impl IdempotentData {
+    /// Simple constructor
     pub fn new(status: StatusCode, body: Bytes, input_hash: [u8; 32]) -> Self {
         Self {
             status,
@@ -24,6 +29,7 @@ impl IdempotentData {
     }
 }
 
+/// Store trait which should be implemented for idempotency related features
 #[async_trait]
 pub trait IdempotentStore {
     /// Returns the API response that was saved when the idempotency key was used
@@ -34,7 +40,8 @@ pub trait IdempotentStore {
     ) -> Result<Option<IdempotentData>, ()>;
 
     /// Saves the data that was passed along with the api request for later
-    /// The store MUST also save a hash of the input, so that it errors out on requests
+    /// The store also saves the hash of the input, so that it errors out on requests
+    /// with conflicting input hashes for the same idempotency key
     async fn save_idempotent_data(
         &self,
         idempotency_key: String,
@@ -44,9 +51,9 @@ pub trait IdempotentStore {
     ) -> Result<(), ()>;
 }
 
-// Helper function that returns any idempotent data that corresponds to a
-// provided idempotency key. It fails if the hash of the input that
-// generated the idempotent data does not match the hash of the provided input.
+/// Helper function that returns any idempotent data that corresponds to a
+/// provided idempotency key. It fails if the hash of the input that
+/// generated the idempotent data does not match the hash of the provided input.
 async fn check_idempotency<S>(
     store: S,
     idempotency_key: String,
@@ -136,11 +143,12 @@ where
                     }
                 };
 
-                // NOTE: This is bytes 0.4.12. API Response is defined over it.
                 let data = match ret {
                     ApiResponse::Default => default_return_value,
                     ApiResponse::Data(d) => d,
                 };
+                // TODO refactor for readability, can unify the 2 idempotency calls, the error and the data
+                // are both Bytes
                 store
                     .save_idempotent_data(
                         idempotency_key,

crates/interledger-settlement/src/core/mod.rs

@@ -2,10 +2,14 @@
 /// Only exported if the `backends_common` feature flag is enabled
 #[cfg(feature = "backends_common")]
 pub mod backends_common;
-/// The REST API for the settlement engines
+
+/// Web service which exposes settlement related endpoints as described in the [RFC](https://interledger.org/rfcs/0038-settlement-engines/),
+/// All endpoints are idempotent.
 pub mod engines_api;
+
 /// Expose useful utilities for implementing idempotent functionalities
 pub mod idempotency;
+
 /// Expose useful traits
 pub mod types;
 
@@ -14,6 +18,27 @@ use num_traits::Zero;
 use ring::digest::{digest, SHA256};
 use types::{Convert, ConvertDetails};
 
+/// Converts a number from a precision to another while taking precision loss into account
+///
+/// # Examples
+/// ```rust
+/// # use num_bigint::BigUint;
+/// # use interledger_settlement::core::scale_with_precision_loss;
+/// assert_eq!(
+///     scale_with_precision_loss(BigUint::from(905u32), 9, 11),
+///     (BigUint::from(9u32), BigUint::from(5u32))
+/// );
+///
+/// assert_eq!(
+///     scale_with_precision_loss(BigUint::from(8053u32), 9, 12),
+///     (BigUint::from(8u32), BigUint::from(53u32))
+/// );
+///
+/// assert_eq!(
+///     scale_with_precision_loss(BigUint::from(1u32), 9, 6),
+///     (BigUint::from(1000u32), BigUint::from(0u32))
+/// );
+/// ```
 pub fn scale_with_precision_loss(
     amount: BigUint,
     local_scale: u8,
@@ -49,9 +74,7 @@ pub fn scale_with_precision_loss(
     }
 }
 
-// Helper function that returns any idempotent data that corresponds to a
-// provided idempotency key. It fails if the hash of the input that
-// generated the idempotent data does not match the hash of the provided input.
+/// Returns the 32-bytes SHA256 hash of the provided preimage
 pub fn get_hash_of(preimage: &[u8]) -> [u8; 32] {
     let mut hash = [0; 32];
     hash.copy_from_slice(digest(&SHA256, preimage).as_ref());