docs(http): extend http docs

Author: gakonst

crates/interledger-http/Cargo.toml

@@ -15,8 +15,7 @@ interledger-service = { path = "../interledger-service", version = "^0.4.0", def
 log = { version = "0.4.8", default-features = false }
 reqwest = { version = "0.10.0", default-features = false, features = ["default-tls"] }
 url = { version = "2.1.0", default-features = false }
-# warp = { version = "0.1.20", default-features = false }
-warp = { git = "https://github.com/seanmonstar/warp.git" }
+warp = { version = "0.2", default-features = false }
 serde = { version = "1.0.101", default-features = false, features = ["derive"] }
 serde_json = { version = "1.0.41", default-features = false }
 serde_path_to_error = { version = "0.1", default-features = false }
@@ -25,7 +24,7 @@ chrono = { version = "0.4.9", features = ["clock"], default-features = false }
 regex = { version ="1.3.1", default-features = false, features = ["std"] }
 lazy_static = { version ="1.4.0", default-features = false }
 mime = { version ="0.3.14", default-features = false }
-secrecy = "0.5.2"
+secrecy = "0.6"
 async-trait = "0.1.22"
 
 [dev-dependencies]

crates/interledger-http/src/client.rs

@@ -12,10 +12,20 @@ use reqwest::{
 use secrecy::{ExposeSecret, SecretString};
 use std::{convert::TryFrom, marker::PhantomData, sync::Arc, time::Duration};
 
+/// The HttpClientService implements [OutgoingService](../../interledger_service/trait.OutgoingService)
+/// for sending ILP Prepare packets over to the HTTP URL associated with the provided account
+/// If no [ILP-over-HTTP](https://interledger.org/rfcs/0035-ilp-over-http) URL is specified for
+/// the account in the request, then it is forwarded to the next service.
 #[derive(Clone)]
 pub struct HttpClientService<S, O, A> {
+    /// An HTTP client configured with a 30 second timeout by default. It is used to send the
+    /// ILP over HTTP messages to the peer
     client: Client,
+    /// The store used by the client to get the node's ILP Address,
+    /// used to populate the `triggered_by` field in Reject packets
     store: Arc<S>,
+    /// The next outgoing service to which non ILP-over-HTTP requests should
+    /// be forwarded to
     next: O,
     account_type: PhantomData<A>,
 }
@@ -26,6 +36,7 @@ where
     O: OutgoingService<A> + Clone,
     A: HttpAccount,
 {
+    /// Constructs the HttpClientService
     pub fn new(store: S, next: O) -> Self {
         let mut headers = HeaderMap::with_capacity(2);
         headers.insert(
@@ -103,6 +114,13 @@ where
     }
 }
 
+/// Parses an ILP over HTTP response.
+///
+/// # Errors
+/// 1. If the response's status code is an error
+/// 1. If the response's body cannot be parsed as bytes
+/// 1. If the response's body is not a valid Packet (Fulfill or Reject)
+/// 1. If the packet is a Reject packet
 async fn parse_packet_from_response(response: HttpResponse, ilp_address: Address) -> IlpResult {
     let response = response.error_for_status().map_err(|err| {
         error!("HTTP error sending ILP over HTTP packet: {:?}", err);

crates/interledger-http/src/error/error_types.rs

@@ -1,80 +1,99 @@
-// APIs should implement their own `ApiErrorType`s to provide more detailed information
-// about what were the problem, for example, `JSON_SYNTAX_TYPE` or `ACCOUNT_NOT_FOUND_TYPE`.
-
 use super::{ApiError, ApiErrorType, ProblemType};
 use http::StatusCode;
 use lazy_static::lazy_static;
 
-// Default errors
+// Common HTTP errors
+
 #[allow(dead_code)]
+/// 400 Bad Request HTTP Status Code
 pub const DEFAULT_BAD_REQUEST_TYPE: ApiErrorType = ApiErrorType {
     r#type: &ProblemType::Default,
     title: "Bad Request",
     status: StatusCode::BAD_REQUEST,
 };
+
+/// 500 Internal Server Error HTTP Status Code
 pub const DEFAULT_INTERNAL_SERVER_ERROR_TYPE: ApiErrorType = ApiErrorType {
     r#type: &ProblemType::Default,
     title: "Internal Server Error",
     status: StatusCode::INTERNAL_SERVER_ERROR,
 };
+
+/// 401 Unauthorized HTTP Status Code
 pub const DEFAULT_UNAUTHORIZED_TYPE: ApiErrorType = ApiErrorType {
     r#type: &ProblemType::Default,
     title: "Unauthorized",
     status: StatusCode::UNAUTHORIZED,
 };
+
+/// 404 Not Found HTTP Status Code
 pub const DEFAULT_NOT_FOUND_TYPE: ApiErrorType = ApiErrorType {
     r#type: &ProblemType::Default,
     title: "Not Found",
     status: StatusCode::NOT_FOUND,
 };
+
+/// 405 Method Not Allowed HTTP Status Code
 pub const DEFAULT_METHOD_NOT_ALLOWED_TYPE: ApiErrorType = ApiErrorType {
     r#type: &ProblemType::Default,
     title: "Method Not Allowed",
     status: StatusCode::METHOD_NOT_ALLOWED,
 };
+
+/// 409 Conflict HTTP Status Code (used for Idempotency Conflicts)
 pub const DEFAULT_IDEMPOTENT_CONFLICT_TYPE: ApiErrorType = ApiErrorType {
     r#type: &ProblemType::Default,
     title: "Provided idempotency key is tied to other input",
     status: StatusCode::CONFLICT,
 };
 
 // ILP over HTTP specific errors
+
+/// ILP over HTTP invalid packet error type  (400 Bad Request)
 pub const INVALID_ILP_PACKET_TYPE: ApiErrorType = ApiErrorType {
     r#type: &ProblemType::InterledgerHttpApi("ilp-over-http/invalid-packet"),
     title: "Invalid Packet",
     status: StatusCode::BAD_REQUEST,
 };
 
-// JSON deserialization errors
+/// Wrong JSON syntax error type (400 Bad Request)
 pub const JSON_SYNTAX_TYPE: ApiErrorType = ApiErrorType {
     r#type: &ProblemType::InterledgerHttpApi("json-syntax"),
     title: "JSON Syntax Error",
     status: StatusCode::BAD_REQUEST,
 };
+
+/// Wrong JSON data error type (400 Bad Request)
 pub const JSON_DATA_TYPE: ApiErrorType = ApiErrorType {
     r#type: &ProblemType::InterledgerHttpApi("json-data"),
     title: "JSON Data Error",
     status: StatusCode::BAD_REQUEST,
 };
+
+/// JSON EOF error type (400 Bad Request)
 pub const JSON_EOF_TYPE: ApiErrorType = ApiErrorType {
     r#type: &ProblemType::InterledgerHttpApi("json-eof"),
     title: "JSON Unexpected EOF",
     status: StatusCode::BAD_REQUEST,
 };
+
+/// JSON IO error type (400 Bad Request)
 pub const JSON_IO_TYPE: ApiErrorType = ApiErrorType {
     r#type: &ProblemType::InterledgerHttpApi("json-io"),
     title: "JSON IO Error",
     status: StatusCode::BAD_REQUEST,
 };
 
 // Account specific errors
+
+/// Account Not Found error type (404 Not Found)
 pub const ACCOUNT_NOT_FOUND_TYPE: ApiErrorType = ApiErrorType {
     r#type: &ProblemType::InterledgerHttpApi("accounts/account-not-found"),
     title: "Account Not Found",
     status: StatusCode::NOT_FOUND,
 };
 
-// Node settings specific errors
+/// Invalid Account Id error type (400 Bad Request)
 pub const INVALID_ACCOUNT_ID_TYPE: ApiErrorType = ApiErrorType {
     r#type: &ProblemType::InterledgerHttpApi("settings/invalid-account-id"),
     title: "Invalid Account Id",
@@ -84,14 +103,17 @@ pub const INVALID_ACCOUNT_ID_TYPE: ApiErrorType = ApiErrorType {
 // String used for idempotency errors
 pub static IDEMPOTENCY_CONFLICT_ERR: &str = "Provided idempotency key is tied to other input";
 
-// Idempotency errors
+/// 409 Conflict HTTP Status Code (used for Idempotency Conflicts)
+// TODO: Remove this since it is a duplicate of DEFAULT_IDEMPOTENT_CONFLICT_TYPE
 pub const IDEMPOTENT_STORE_CALL_ERROR_TYPE: ApiErrorType = ApiErrorType {
     r#type: &ProblemType::Default,
     title: "Store idempotency error",
     status: StatusCode::CONFLICT,
 };
 
 lazy_static! {
+    /// Error which must be returned when the same idempotency key is
+    /// used for more than 1 input
     pub static ref IDEMPOTENT_STORE_CALL_ERROR: ApiError =
         ApiError::from_api_error_type(&IDEMPOTENT_STORE_CALL_ERROR_TYPE)
             .detail("Could not process idempotent data in store");

crates/interledger-http/src/error/mod.rs

@@ -1,3 +1,5 @@
+/// APIs should implement their own `ApiErrorType`s to provide more detailed information
+/// about what were the problem, for example, `JSON_SYNTAX_TYPE` or `ACCOUNT_NOT_FOUND_TYPE`.
 mod error_types;
 pub use error_types::*;
 
@@ -70,6 +72,7 @@ pub struct ApiError {
     pub extension_members: Option<Map<String, Value>>,
 }
 
+/// Distinguishes between RFC7807 and Interledger API Errors
 #[derive(Clone, Copy, Debug)]
 pub enum ProblemType {
     /// `Default` is a [pre-defined value](https://tools.ietf.org/html/rfc7807#section-4.2) which is
@@ -81,10 +84,14 @@ pub enum ProblemType {
     InterledgerHttpApi(&'static str),
 }
 
+/// Error type used as a basis for creating Warp-compatible Errors
 #[derive(Clone, Copy, Debug)]
 pub struct ApiErrorType {
+    /// Interledger or RFC7807 Error
     pub r#type: &'static ProblemType,
+    /// The Title to be used for the error page
     pub title: &'static str,
+    /// The HTTP Status Code for the error
     pub status: http::StatusCode,
 }
 
@@ -110,6 +117,7 @@ where
 }
 
 impl ApiError {
+    /// Constructs an API Error from a [ApiErrorType](./struct.ApiErrorType.html)
     pub fn from_api_error_type(problem_type: &ApiErrorType) -> Self {
         ApiError {
             r#type: problem_type.r#type,
@@ -123,39 +131,49 @@ impl ApiError {
 
     // Note that we should basically avoid using the following default errors because
     // we should provide more detailed information for developers
+
     #[allow(dead_code)]
+    /// Returns a Bad Request [ApiError](./struct.ApiError.html)
     pub fn bad_request() -> Self {
         ApiError::from_api_error_type(&DEFAULT_BAD_REQUEST_TYPE)
     }
 
+    /// Returns an Internal Server Error [ApiError](./struct.ApiError.html)
     pub fn internal_server_error() -> Self {
         ApiError::from_api_error_type(&DEFAULT_INTERNAL_SERVER_ERROR_TYPE)
     }
 
+    /// Returns an Unauthorized [ApiError](./struct.ApiError.html)
     pub fn unauthorized() -> Self {
         ApiError::from_api_error_type(&DEFAULT_UNAUTHORIZED_TYPE)
     }
 
     #[allow(dead_code)]
+    /// Returns an Error Not Found [ApiError](./struct.ApiError.html)
     pub fn not_found() -> Self {
         ApiError::from_api_error_type(&DEFAULT_NOT_FOUND_TYPE)
     }
 
     #[allow(dead_code)]
+    /// Returns a Method Not Found [ApiError](./struct.ApiError.html)
     pub fn method_not_allowed() -> Self {
         ApiError::from_api_error_type(&DEFAULT_METHOD_NOT_ALLOWED_TYPE)
     }
 
+    /// Returns an Account not Found [ApiError](./struct.ApiError.html)
     pub fn account_not_found() -> Self {
         ApiError::from_api_error_type(&ACCOUNT_NOT_FOUND_TYPE)
             .detail("Username was not found.".to_owned())
     }
 
     #[allow(dead_code)]
+    /// Returns an Idempotency Conflict [ApiError](./struct.ApiError.html)
+    /// via the [default idempotency conflict ApiErrorType](./error_types/constant.DEFAULT_IDEMPOTENT_CONFLICT_TYPE.html)
     pub fn idempotency_conflict() -> Self {
         ApiError::from_api_error_type(&DEFAULT_IDEMPOTENT_CONFLICT_TYPE)
     }
 
+    /// Returns an Invalid Account Id [ApiError](./struct.ApiError.html)
     pub fn invalid_account_id(invalid_account_id: Option<&str>) -> Self {
         let detail = match invalid_account_id {
             Some(invalid_account_id) => match invalid_account_id.len() {
@@ -167,10 +185,12 @@ impl ApiError {
         ApiError::from_api_error_type(&INVALID_ACCOUNT_ID_TYPE).detail(detail)
     }
 
+    /// Returns an Invalid ILP over HTTP [ApiError](./struct.ApiError.html)
     pub fn invalid_ilp_packet() -> Self {
         ApiError::from_api_error_type(&INVALID_ILP_PACKET_TYPE)
     }
 
+    /// Sets the [`detail`](./struct.ApiError.html#structfield.detail) field
     pub fn detail<T>(mut self, detail: T) -> Self
     where
         T: Into<String>,
@@ -180,6 +200,7 @@ impl ApiError {
     }
 
     #[allow(dead_code)]
+    /// Sets the [`instance`](./struct.ApiError.html#structfield.instance) field
     pub fn instance<T>(mut self, instance: T) -> Self
     where
         T: Into<String>,
@@ -188,8 +209,9 @@ impl ApiError {
         self
     }
 
-    pub fn extension_members(mut self, extension_members: Option<Map<String, Value>>) -> Self {
-        self.extension_members = extension_members;
+    /// Sets the [`extension_members`](./struct.ApiError.html#structfield.extension_members) field
+    pub fn extension_members(mut self, extension_members: Map<String, Value>) -> Self {
+        self.extension_members = Some(extension_members);
         self
     }
 
@@ -298,15 +320,14 @@ impl Reply for JsonDeserializeError {
             Category::Io => &JSON_IO_TYPE,
         };
         let detail = self.detail;
-        let extension_members = match extension_members.keys().len() {
-            0 => None,
-            _ => Some(extension_members),
-        };
 
-        ApiError::from_api_error_type(api_error_type)
-            .detail(detail)
-            .extension_members(extension_members)
-            .into_response()
+        let mut error = ApiError::from_api_error_type(api_error_type).detail(detail);
+
+        if extension_members.keys().len() > 0 {
+            error = error.extension_members(extension_members);
+        }
+
+        error.into_response()
     }
 }
 

crates/interledger-http/src/lib.rs

@@ -11,17 +11,21 @@ use serde::de::DeserializeOwned;
 use url::Url;
 use warp::{self, Filter, Rejection};
 
+/// [ILP over HTTP](https://interledger.org/rfcs/0035-ilp-over-http/) Outgoing Service
 mod client;
-mod server;
-
-// So that settlement engines can use errors
+/// [RFC7807](https://tools.ietf.org/html/rfc7807) compliant errors
 pub mod error;
+/// [ILP over HTTP](https://interledger.org/rfcs/0035-ilp-over-http/) API (implemented with [Warp](https://docs.rs/warp/0.2.0/warp/))
+mod server;
 
 pub use self::client::HttpClientService;
 pub use self::server::HttpServer;
 
+/// Extention trait for [Account](../interledger_service/trait.Account.html) with [ILP over HTTP](https://interledger.org/rfcs/0035-ilp-over-http/) related information
 pub trait HttpAccount: Account {
+    /// Returns the HTTP URL corresponding to this account
     fn get_http_url(&self) -> Option<&Url>;
+    /// Returns the HTTP token which is sent as an HTTP header on each ILP over HTTP request
     fn get_http_auth_token(&self) -> Option<SecretString>;
 }
 
@@ -42,6 +46,9 @@ pub trait HttpStore: Clone + Send + Sync + 'static {
 
 // TODO: Do we really need this custom deserialization function?
 // You'd expect that Serde would be able to handle this.
+/// Helper function to deserialize JSON inside Warp
+/// The content-type MUST be application/json and if a charset
+/// is specified, it MUST be UTF-8
 pub fn deserialize_json<T: DeserializeOwned + Send>(
 ) -> impl Filter<Extract = (T,), Error = Rejection> + Copy {
     warp::header::<String>("content-type")