use std::fmt;
use crate::ratelimit::RateLimitInfo;
pub type Result<T> = std::result::Result<T, Error>;
#[derive(Debug)]
#[non_exhaustive]
pub enum Error {
Api(ApiError),
MaxRetries {
attempts: u32,
last: Box<Error>,
},
MissingParam(String),
UnknownEndpoint(String),
Transport(Box<ureq::Error>),
Decode(serde_json::Error),
InvalidConfig(String),
InvalidUtf8(std::string::FromUtf8Error),
}
#[derive(Debug, Clone, Default)]
pub struct ApiError {
pub status: u16,
pub message: String,
pub rate_limit: RateLimitInfo,
pub body: Vec<u8>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum ApiErrorKind {
BadRequest,
NotFound,
Timeout,
RateLimit,
InternalServer,
ServiceUnavailable,
Other(u16),
}
impl ApiError {
pub fn kind(&self) -> ApiErrorKind {
match self.status {
400 => ApiErrorKind::BadRequest,
404 => ApiErrorKind::NotFound,
408 => ApiErrorKind::Timeout,
429 => ApiErrorKind::RateLimit,
500 => ApiErrorKind::InternalServer,
503 => ApiErrorKind::ServiceUnavailable,
other => ApiErrorKind::Other(other),
}
}
}
pub fn status_description(status: u16) -> Option<(&'static str, &'static str)> {
Some(match status {
200 => (
"OK",
"Request was a success. Only process data from the service when you receive this code",
),
400 => (
"Bad Request",
"Occurs during exceptional circumstances such as the service is unable to find an ID. If JSON, the object contains the error message",
),
403 => (
"Forbidden",
"You are submitting far too many requests and have been temporarily forbidden access. Wait and retry with a maximum of 15 requests per second",
),
404 => (
"Not Found",
"Indicates a badly formatted request. Check your URL",
),
408 => (
"Timeout",
"The request was not processed in time. Wait and retry later",
),
415 => (
"Unsupported Media Type",
"The server is refusing to service the request because the entity format is not supported",
),
429 => (
"Too Many Requests",
"You have been rate-limited; wait and retry",
),
500 => (
"Internal Server Error",
"Internal server error. Check your input or contact the Ensembl team if issue persists",
),
503 => (
"Service Unavailable",
"The service is temporarily down; retry after a pause",
),
_ => return None,
})
}
pub fn reason_phrase(status: u16) -> &'static str {
ureq::http::StatusCode::from_u16(status)
.ok()
.and_then(|c| c.canonical_reason())
.unwrap_or("")
}
impl fmt::Display for ApiError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let desc = status_description(self.status);
let name = desc.map_or_else(|| reason_phrase(self.status), |d| d.0);
let msg: &str = if self.message.is_empty() {
desc.map_or("", |d| d.1)
} else {
&self.message
};
if self.status == 0 {
return write!(f, "EnsEMBL REST API error: {msg}");
}
if self.status == 429
&& let Some(retry_after) = self.rate_limit.retry_after
{
return write!(
f,
"EnsEMBL REST API returned a {} ({name}): {msg} \
(Rate limit hit: Retry after {} seconds)",
self.status, retry_after as i64
);
}
write!(
f,
"EnsEMBL REST API returned a {} ({name}): {msg}",
self.status
)
}
}
impl std::error::Error for ApiError {}
impl Error {
pub fn api_kind(&self) -> Option<ApiErrorKind> {
match self {
Error::Api(e) => Some(e.kind()),
Error::MaxRetries { last, .. } => last.api_kind(),
_ => None,
}
}
pub fn is_bad_request(&self) -> bool {
self.api_kind() == Some(ApiErrorKind::BadRequest)
}
pub fn is_not_found(&self) -> bool {
self.api_kind() == Some(ApiErrorKind::NotFound)
}
pub fn is_rate_limited(&self) -> bool {
self.api_kind() == Some(ApiErrorKind::RateLimit)
}
pub fn is_service_unavailable(&self) -> bool {
self.api_kind() == Some(ApiErrorKind::ServiceUnavailable)
}
}
impl fmt::Display for Error {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Error::Api(e) => write!(f, "{e}"),
Error::MaxRetries { attempts, last } => {
write!(
f,
"ensembl: maximum retry attempts reached: {last} (attempts: {attempts})"
)
}
Error::MissingParam(name) => write!(f, "mandatory param \"{name}\" not specified"),
Error::UnknownEndpoint(name) => {
write!(f, "unknown Ensembl REST API endpoint \"{name}\"")
}
Error::Transport(e) => write!(f, "ensembl: transport error: {e}"),
Error::Decode(e) => write!(f, "failed to decode response as JSON: {e}"),
Error::InvalidConfig(msg) => write!(f, "ensembl: invalid configuration: {msg}"),
Error::InvalidUtf8(e) => write!(f, "ensembl: response was not valid UTF-8: {e}"),
}
}
}
impl std::error::Error for Error {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
match self {
Error::Api(e) => Some(e),
Error::MaxRetries { last, .. } => Some(&**last),
Error::Transport(e) => Some(&**e),
Error::Decode(e) => Some(e),
Error::InvalidUtf8(e) => Some(e),
_ => None,
}
}
}
pub fn parse_error_message(body: &[u8], default_msg: &str) -> String {
if body.is_empty() {
return default_msg.to_string();
}
#[derive(serde::Deserialize)]
struct Wire {
#[serde(default)]
error: String,
#[serde(default)]
message: String,
}
if let Ok(w) = serde_json::from_slice::<Wire>(body) {
if !w.error.is_empty() {
return w.error;
}
if !w.message.is_empty() {
return w.message;
}
}
String::from_utf8_lossy(body).into_owned()
}
#[cfg(test)]
mod tests {
use super::*;
fn api(status: u16, message: &str) -> ApiError {
ApiError {
status,
message: message.to_string(),
rate_limit: RateLimitInfo::default(),
body: message.as_bytes().to_vec(),
}
}
#[test]
fn display_matches_the_go_port_exactly() {
let e = api(404, "ID not found");
assert_eq!(
e.to_string(),
"EnsEMBL REST API returned a 404 (Not Found): ID not found"
);
}
#[test]
fn display_appends_retry_after_for_429() {
let mut e = api(429, "slow down");
e.rate_limit.retry_after = Some(3.0);
assert_eq!(
e.to_string(),
"EnsEMBL REST API returned a 429 (Too Many Requests): slow down \
(Rate limit hit: Retry after 3 seconds)"
);
}
#[test]
fn empty_message_falls_back_to_the_status_description() {
let e = api(503, "");
assert_eq!(
e.to_string(),
"EnsEMBL REST API returned a 503 (Service Unavailable): \
The service is temporarily down; retry after a pause"
);
}
#[test]
fn kind_maps_each_documented_status() {
assert_eq!(api(400, "").kind(), ApiErrorKind::BadRequest);
assert_eq!(api(404, "").kind(), ApiErrorKind::NotFound);
assert_eq!(api(408, "").kind(), ApiErrorKind::Timeout);
assert_eq!(api(429, "").kind(), ApiErrorKind::RateLimit);
assert_eq!(api(500, "").kind(), ApiErrorKind::InternalServer);
assert_eq!(api(503, "").kind(), ApiErrorKind::ServiceUnavailable);
assert_eq!(api(418, "").kind(), ApiErrorKind::Other(418));
}
#[test]
fn max_retries_exposes_the_underlying_api_kind_through_source() {
let inner = Error::Api(api(503, "down"));
let e = Error::MaxRetries {
attempts: 5,
last: Box::new(inner),
};
assert_eq!(e.api_kind(), Some(ApiErrorKind::ServiceUnavailable));
assert!(std::error::Error::source(&e).is_some());
}
#[test]
fn is_not_found_is_a_convenience_over_api_kind() {
assert!(Error::Api(api(404, "")).is_not_found());
assert!(!Error::Api(api(400, "")).is_not_found());
}
#[test]
fn parse_error_message_prefers_json_error_then_message_then_raw() {
assert_eq!(parse_error_message(br#"{"error":"boom"}"#, "d"), "boom");
assert_eq!(parse_error_message(br#"{"message":"bang"}"#, "d"), "bang");
assert_eq!(parse_error_message(b"not json", "d"), "not json");
assert_eq!(parse_error_message(b"", "d"), "d");
}
}