Updating to use custom error struct, adding docs

src/consts/champion.rs

@@ -1,7 +1,7 @@
 
 // This file is automatically generated.
 // Do not directly edit.
-// Generated on 2019-10-23T01:41:03.103Z
+// Generated on 2019-10-23T07:19:13.049Z
 
 use std::fmt;
 use num_derive;

src/consts/mod.rs

@@ -1,3 +1,5 @@
+//! Constant data and Enums relevant to the Riot Games API.
+
 mod region;
 mod champion;
 

src/consts/region.rs

@@ -1,3 +1,6 @@
+//! A region served by a single game server.
+//! Each Riot Games API request is directed at a particular region,
+//! with tournament API requests directed at the AMERICAS "global" region.
 #[derive(Debug)]
 #[derive(PartialEq, Eq, Hash, PartialOrd, Ord)]
 #[derive(Clone, Copy)]
@@ -54,6 +57,7 @@ impl Region {
         AMERICAS => "AMERICAS";
         EUROPE   => "EUROPE";
         ASIA     => "ASIA";
+
     }
 }
 

src/endpoints.rs

@@ -1,11 +1,13 @@
 
 // This file is automatically generated.
 // Do not directly edit.
-// Generated on 2019-10-23T01:41:03.165Z
+// Generated on 2019-10-23T07:19:13.042Z
 
 // http://www.mingweisamuel.com/riotapi-schema/tool/
 // Version 0c74167e0eaaeb6de1c7e8219fecaabcf8386d1f
 
+//! Automatically generated endpoint handles and data transfer structs.
+
 mod dto;
 pub use dto::*;
 

src/endpoints/dto.rs

@@ -1,7 +1,7 @@
 
 // This file is automatically generated.
 // Do not directly edit.
-// Generated on 2019-10-23T01:41:03.173Z
+// Generated on 2019-10-23T07:19:13.050Z
 
 // http://www.mingweisamuel.com/riotapi-schema/tool/
 // Version 0c74167e0eaaeb6de1c7e8219fecaabcf8386d1f

src/lib.rs

@@ -1,5 +1,7 @@
-pub use reqwest::Error as Error;
-pub use reqwest::Result as Result;
+//! Module docs TODO.
+
+mod riot_api_error;
+pub use riot_api_error::*;
 
 pub mod consts;
 

src/req/regional_requester.rs

@@ -6,6 +6,7 @@ use reqwest::{ Client, StatusCode, Url };
 use tokio_timer::delay_for;
 
 use crate::Result;
+use crate::RiotApiError;
 use crate::riot_api_config::RiotApiConfig;
 use crate::consts::Region;
 use crate::util::InsertOnlyCHashMap;
@@ -63,7 +64,8 @@ impl RegionalRequester {
                 let response = client.get(url)
                     .header(Self::RIOT_KEY_HEADER, &*config.api_key)
                     .send()
-                    .await?;
+                    .await
+                    .map_err(|e| RiotApiError::new(e, retries, None))?;
 
                 // Maybe update rate limits (based on response headers).
                 self.app_rate_limit.on_response(&response);
@@ -81,7 +83,8 @@ impl RegionalRequester {
                     // Success.
                     Ok(_) => {
                         let value = response.json::<T>().await;
-                        break value.map(|v| Some(v));
+                        break value.map(|v| Some(v))
+                            .map_err(|e| RiotApiError::new(e, retries, None));
                     },
                     // Failure, may or may not be retryable.
                     Err(err) => {
@@ -91,7 +94,7 @@ impl RegionalRequester {
                             (StatusCode::TOO_MANY_REQUESTS != status
                             && !status.is_server_error())
                         {
-                            break Err(err);
+                            break Err(RiotApiError::new(err, retries, Some(response)));
                         }
                     },
                 };

src/riot_api.rs

@@ -3,11 +3,13 @@ use std::future::Future;
 use log;
 use reqwest::Client;
 
+use crate::Result;
 use crate::RiotApiConfig;
 use crate::consts::Region;
 use crate::req::RegionalRequester;
 use crate::util::InsertOnlyCHashMap;
 
+/// For retrieving data from the Riot Games API.
 pub struct RiotApi {
     /// Configuration settings.
     config: RiotApiConfig,
@@ -34,7 +36,7 @@ impl RiotApi {
 
     pub fn get<'a, T: serde::de::DeserializeOwned + 'a>(&'a self,
         method_id: &'static str, region: Region, path: String, query: Option<String>)
-        -> impl Future<Output = Result<Option<T>, reqwest::Error>> + 'a
+        -> impl Future<Output = Result<Option<T>>> + 'a
     {
         // TODO: max concurrent requests? Or can configure client?
         self.regional_requesters

src/riot_api_config.rs

@@ -1,3 +1,4 @@
+/// Configuration for instantiating RiotApi.
 #[derive(Debug)]
 pub struct RiotApiConfig {
     pub api_key: String,

src/riot_api_error.rs

@@ -0,0 +1,50 @@
+use std::error::Error;
+use std::fmt;
+
+pub use reqwest::Error as ReqwestError;
+pub use reqwest::Response;
+
+/// Result containing RiotApiError on failure.
+pub type Result<T> = std::result::Result<T, RiotApiError>;
+
+/// An error that occurred while processing a Riot API request.
+///
+/// Although Riven may make multiple requests due to retries, this will always
+/// contain exactly one ReqwestError for the final request which failed.
+#[derive(Debug)]
+pub struct RiotApiError {
+    reqwest_error: ReqwestError,
+    retries: u8,
+    response: Option<Response>,
+}
+impl RiotApiError {
+    pub fn new(reqwest_error: ReqwestError, retries: u8, response: Option<Response>) -> Self {
+        Self {
+            reqwest_error: reqwest_error,
+            retries: retries,
+            response: response,
+        }
+    }
+    /// The ReqwestError for the final failed request.
+    pub fn source_reqwest_error(&self) -> &ReqwestError {
+        &self.reqwest_error
+    }
+    /// The number of retires attempted. Zero means exactly one request, zero retries.
+    pub fn retries(&self) -> u8 {
+        self.retries
+    }
+    /// The failed response, if the request sent.
+    pub fn response<'a>(&self) -> Option<&Response> {
+        self.response.as_ref()
+    }
+}
+impl fmt::Display for RiotApiError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{:#?}", self)
+    }
+}
+impl Error for RiotApiError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        Some(&self.reqwest_error)
+    }
+}

srcgen/dotUtils.js

@@ -13,6 +13,12 @@ Array.prototype.groupBy = function(lambda) {
   }, {}));
 }
 
+function preamble() {
+  return `// This file is automatically generated.
+// Do not directly edit.
+// Generated on ${(new Date).toISOString()}.`;
+}
+
 function capitalize(input) {
   return input[0].toUpperCase() + input.slice(1);
 }
@@ -112,6 +118,7 @@ function formatRouteArgument(route, pathParams = []) {
 
 module.exports = {
   changeCase,
+  preamble,
   capitalize,
   decapitalize,
   normalizeSchemaName,

srcgen/endpoints.rs.dt

@@ -9,6 +9,8 @@
 // http://www.mingweisamuel.com/riotapi-schema/tool/
 // Version {{= spec.info.version }}
 
+//! Automatically generated endpoint handles and data transfer structs.
+
 mod dto;
 pub use dto::*;
 

srcgen/index.js

@@ -14,6 +14,10 @@ const files = [
   [
     'http://www.mingweisamuel.com/riotapi-schema/openapi-3.0.0.json',
     '.spec.json'
+  ],
+  [
+    'http://static.developer.riotgames.com/docs/lol/seasons.json',
+    '.seasons.json'
   ]
 ]