docs(stream): fix some docs

Author: gakonst

crates/interledger-stream/src/client.rs

@@ -28,7 +28,7 @@ const MAX_TIME_SINCE_LAST_FULFILL: Duration = Duration::from_secs(30);
 pub struct StreamDelivery {
     /// The sender's ILP Address
     pub from: Address,
-    /// The receivers ILP Address
+    /// The receiver's ILP Address
     pub to: Address,
     // StreamDelivery variables which we know ahead of time
     /// The amount sent by the sender
@@ -113,6 +113,8 @@ where
         last_fulfill_time: Instant::now(),
     };
 
+    // Fires off STREAM packets until the congestion controller tells us to stop
+    // or we've sent the total amount or maximum time since last fulfill has elapsed
     loop {
         if let Some(error) = sender.error.take() {
             error!("Send money stopped because of error: {:?}", error);
@@ -175,21 +177,26 @@ struct SendMoneyFuture<S: IncomingService<A>, A: Account> {
     destination_account: Address,
     /// The shared secret generated by the sender and the receiver
     shared_secret: Bytes,
-    /// The amount sent by the sender
+    /// The amount (in the sender's units) remaining to be sent by the sender,
+    /// excluding the in-flight amount
     source_amount: u64,
-    /// The [congestion controller](./../congestion/struct.CongestionController.html) for this stream
+    /// The [congestion controller](./../congestion/struct.CongestionController.html) for this stream, which is used to send bigger or smaller amounts inside the packets as the stream gets processed
     congestion_controller: CongestionController,
     /// The [StreamDelivery](./struct.StreamDelivery.html) receipt of this stream
     receipt: StreamDelivery,
     /// Boolean indicating if the source account should also be sent to the receiver
     should_send_source_account: bool,
-    /// The sequence number of this stream
+    /// The sequence number of this stream, which is also used for tracking the number of fulfilled packets
     sequence: u64,
-    /// The amount of rejected packets by the stream
+    /// Number of packets rejected throughout the stream
     rejected_packets: u64,
     /// The STREAM error for this stream
     error: Option<Error>,
     /// The last time a packet was fulfilled for this stream.
+    // TOOD:  Seems weird that this is set initially to Instant::now()
+    // even though no packets have been fulfilled yet. Maybe make it an Option
+    // which starts as None, and set it to Some(Instant::now()) when we receive the first
+    // fulfill?
     last_fulfill_time: Instant,
 }
 
@@ -199,8 +206,7 @@ where
     A: Account,
 {
     #[inline]
-    /// Fires off STREAM inside Prepare packets until the congestion controller tells us to stop
-    /// or we've sent the total amount or maximum time since last fulfill has elapsed
+    /// Fires off 1 STREAM-inside-Prepare packet
     async fn try_send_money(&mut self) -> Result<(), Error> {
         let amount = min(
             self.source_amount,
@@ -313,8 +319,8 @@ where
     /// Parses the provided Fulfill packet.
     /// 1. Logs the fulfill in the congestion controller
     /// 1. Updates the last fulfill time of the send money future
-    /// 1. It tries to aprse a Stream Packet inside the fulfill packet's data field
-    ///    If successful, it icnrements the delivered amount by the Stream packet's prepare amount
+    /// 1. It tries to parse a Stream Packet inside the fulfill packet's data field
+    ///    If successful, it increments the delivered amount by the Stream packet's prepare amount
     fn handle_fulfill(&mut self, sequence: u64, amount: u64, fulfill: Fulfill) {
         // TODO should we check the fulfillment and expiry or can we assume the plugin does that?
         self.congestion_controller.fulfill(amount);

crates/interledger-stream/src/congestion.rs

@@ -17,11 +17,19 @@ use std::io;
 /// control algorithms.
 pub struct CongestionController {
     state: CongestionState,
+    /// Amount which is added to `max_in_flight` per fulfill
     increase_amount: u64,
+    /// Divide `max_in_flight` by this factor per reject with code for insufficient liquidity
+    /// or if there is no `max_packet_amount` specified
     decrease_factor: f64,
+    /// The maximum amount we are allowed to add in a packet. This gets automatically set if
+    /// we receive a reject packet with a `F08_AMOUNT_TOO_LARGE` error
     max_packet_amount: Option<u64>,
+    /// The current amount in flight
     amount_in_flight: u64,
+    /// The maximum allowed amount to be in flight
     max_in_flight: u64,
+    /// Writer object to write our metrics to a csv
     #[cfg(feature = "metrics_csv")]
     csv_writer: csv::Writer<io::Stdout>,
 }
@@ -33,6 +41,7 @@ enum CongestionState {
 }
 
 impl CongestionController {
+    /// Constructs a new congestion controller
     pub fn new(start_amount: u64, increase_amount: u64, decrease_factor: f64) -> Self {
         #[cfg(feature = "metrics_csv")]
         let mut csv_writer = csv::Writer::from_writer(io::stdout());
@@ -53,6 +62,7 @@ impl CongestionController {
         }
     }
 
+    /// The maximum amount which can be sent is the maximum amount in flight minus the current amount in flight
     pub fn get_max_amount(&mut self) -> u64 {
         if self.amount_in_flight > self.max_in_flight {
             return 0;
@@ -66,6 +76,7 @@ impl CongestionController {
         }
     }
 
+    /// Increments the amount in flight by the provided amount
     pub fn prepare(&mut self, amount: u64) {
         if amount > 0 {
             self.amount_in_flight += amount;
@@ -76,6 +87,8 @@ impl CongestionController {
         }
     }
 
+    /// Decrements the amount in flight by the provided amount
+    /// Increases the allowed max in flight amount cap
     pub fn fulfill(&mut self, prepare_amount: u64) {
         self.amount_in_flight -= prepare_amount;
 
@@ -111,6 +124,8 @@ impl CongestionController {
         self.log_stats(prepare_amount);
     }
 
+    /// Decrements the amount in flight by the provided amount
+    /// Decreases the allowed max in flight amount cap
     pub fn reject(&mut self, prepare_amount: u64, reject: &Reject) {
         self.amount_in_flight -= prepare_amount;
 

crates/interledger-stream/src/crypto.rs

@@ -133,7 +133,6 @@ fn encrypt_with_nonce(
 /// The nonce and auth tag are extracted from the first 12 and 16 bytes
 /// of the ciphertext.
 pub fn decrypt(shared_secret: &[u8], mut ciphertext: BytesMut) -> Result<BytesMut, ()> {
-    println!("Got ciphertext with length {:?}", ciphertext.len());
     // ciphertext must include at least a nonce and tag,
     if ciphertext.len() < AUTH_TAG_LENGTH {
         return Err(());

crates/interledger-stream/src/packet.rs

@@ -19,7 +19,9 @@ pub struct StreamPacketBuilder<'a> {
     pub sequence: u64,
     /// The [ILP Packet Type](../interledger_packet/enum.PacketType.html)
     pub ilp_packet_type: IlpPacketType,
-    /// The amount inside the stream packet
+    /// Destination amount of the ILP Prepare, used for enforcing minimum exchange rates and congestion control.
+    /// Within an ILP Prepare, represents the minimum amount the recipient needs to receive in order to fulfill the packet.
+    /// Within an ILP Fulfill or ILP Reject, represents the amount received by the recipient.
     pub prepare_amount: u64,
     /// The stream frames
     pub frames: &'a [Frame<'a>],
@@ -121,7 +123,9 @@ pub struct StreamPacket {
     sequence: u64,
     /// The [ILP Packet Type](../interledger_packet/enum.PacketType.html)
     ilp_packet_type: IlpPacketType,
-    /// The amount inside the stream packet
+    /// Destination amount of the ILP Prepare, used for enforcing minimum exchange rates and congestion control.
+    /// Within an ILP Prepare, represents the minimum amount the recipient needs to receive in order to fulfill the packet.
+    /// Within an ILP Fulfill or ILP Reject, represents the amount received by the recipient.
     prepare_amount: u64,
     /// The offset after which frames can be found inside the `buffer_unencrypted` field
     frames_offset: usize,
@@ -132,19 +136,21 @@ impl StreamPacket {
     /// and a shared secret
     ///
     /// # Errors
+    /// 1. If the version of the Stream Protocol does not match
     /// 1. If the decryption fails
-    /// 1. If the decrypted bytes cannot be parsed to a unencrypted [Stream Packet](./struct.StreamPacket.html)
+    /// 1. If the decrypted bytes cannot be parsed to an unencrypted [Stream Packet](./struct.StreamPacket.html)
     pub fn from_encrypted(shared_secret: &[u8], ciphertext: BytesMut) -> Result<Self, ParseError> {
         // TODO handle decryption failure
         let decrypted = decrypt(shared_secret, ciphertext)
             .map_err(|_err| ParseError::InvalidPacket(String::from("Unable to decrypt packet")))?;
         StreamPacket::from_bytes_unencrypted(decrypted)
     }
 
-    /// Constructs a [Stream Packet](./struct.StreamPacket.html) from an buffer
+    /// Constructs a [Stream Packet](./struct.StreamPacket.html) from a buffer
     ///
     /// # Errors
-    /// 1. If the decrypted bytes cannot be parsed to a unencrypted [Stream Packet](./struct.StreamPacket.html)
+    /// 1. If the version of the Stream Protocol does not match
+    /// 1. If the decrypted bytes cannot be parsed to an unencrypted [Stream Packet](./struct.StreamPacket.html)
     fn from_bytes_unencrypted(buffer_unencrypted: BytesMut) -> Result<Self, ParseError> {
         // TODO don't copy the whole packet again
         let mut reader = &buffer_unencrypted[..];
@@ -200,7 +206,7 @@ impl StreamPacket {
         self.ilp_packet_type
     }
 
-    /// The packet's prepare amount
+    /// Destination amount of the ILP Prepare, used for enforcing minimum exchange rates and congestion control.
     pub fn prepare_amount(&self) -> u64 {
         self.prepare_amount
     }

crates/interledger-stream/src/server.rs

@@ -85,18 +85,18 @@ impl ConnectionGenerator {
     }
 }
 
-/// A payment notification data type to be used by Pubsub API consumers
+/// Notification that STREAM fulfilled a packet and received a single Interledger payment, used by Pubsub API consumers
 #[derive(Debug, Deserialize, Serialize)]
 pub struct PaymentNotification {
-    /// The username of the receiver of the payment notification
+    /// The username of the account that received the Interledger payment
     pub to_username: Username,
-    /// The username of the sender of the payment notification
+    /// The username of the account that routed the Interledger payment to this node
     pub from_username: Username,
     /// The ILP Address of the receiver of the payment notification
     pub destination: Address,
     /// The amount received
     pub amount: u64,
-    /// The time this payment notification was fired
+    /// The time this payment notification was fired in RFC3339 format
     pub timestamp: String,
 }