From 1e3df189d0dc37880219338c53607152ae0c87e0 Mon Sep 17 00:00:00 2001 From: Trinity Pointard Date: Fri, 26 Mar 2021 22:32:09 +0100 Subject: [PATCH] document api crate --- src/api/api_server.rs | 1 + src/api/encoding.rs | 5 +++++ src/api/error.rs | 16 ++++++++++++++++ src/api/lib.rs | 21 +++++++++++++-------- src/api/s3_get.rs | 5 ++++- src/garage/server.rs | 4 ++-- src/model/key_table.rs | 1 - src/web/error.rs | 2 +- 8 files changed, 42 insertions(+), 13 deletions(-) diff --git a/src/api/api_server.rs b/src/api/api_server.rs index 2feb0e3a..dcc9f478 100644 --- a/src/api/api_server.rs +++ b/src/api/api_server.rs @@ -20,6 +20,7 @@ use crate::s3_get::*; use crate::s3_list::*; use crate::s3_put::*; +/// Run the S3 API server pub async fn run_api_server( garage: Arc, shutdown_signal: impl Future, diff --git a/src/api/encoding.rs b/src/api/encoding.rs index 25999207..63c5dee2 100644 --- a/src/api/encoding.rs +++ b/src/api/encoding.rs @@ -1,9 +1,13 @@ +//! Module containing various helpers for encoding + +/// Escape &str for xml inclusion pub fn xml_escape(s: &str) -> String { s.replace("<", "<") .replace(">", ">") .replace("\"", """) } +/// Encode &str for use in a URI pub fn uri_encode(string: &str, encode_slash: bool) -> String { let mut result = String::with_capacity(string.len() * 2); for c in string.chars() { @@ -24,6 +28,7 @@ pub fn uri_encode(string: &str, encode_slash: bool) -> String { result } +/// Encode &str either as an uri, or a valid string for xml inclusion pub fn xml_encode_key(k: &str, urlencode: bool) -> String { if urlencode { uri_encode(k, true) diff --git a/src/api/error.rs b/src/api/error.rs index 42a7ab10..acd8ebf7 100644 --- a/src/api/error.rs +++ b/src/api/error.rs @@ -3,44 +3,57 @@ use hyper::StatusCode; use garage_util::error::Error as GarageError; +/// Errors of this crate #[derive(Debug, Error)] pub enum Error { // Category: internal error + /// Error related to deeper parts of Garage #[error(display = "Internal error: {}", _0)] InternalError(#[error(source)] GarageError), + /// Error related to Hyper #[error(display = "Internal error (Hyper error): {}", _0)] Hyper(#[error(source)] hyper::Error), + /// Error related to HTTP #[error(display = "Internal error (HTTP error): {}", _0)] HTTP(#[error(source)] http::Error), // Category: cannot process + /// No proper api key was used, or the signature was invalid #[error(display = "Forbidden: {}", _0)] Forbidden(String), + /// The object requested don't exists #[error(display = "Not found")] NotFound, // Category: bad request + /// The request used an invalid path #[error(display = "Invalid UTF-8: {}", _0)] InvalidUTF8Str(#[error(source)] std::str::Utf8Error), + /// The request used an invalid path #[error(display = "Invalid UTF-8: {}", _0)] InvalidUTF8String(#[error(source)] std::string::FromUtf8Error), + /// Some base64 encoded data was badly encoded #[error(display = "Invalid base64: {}", _0)] InvalidBase64(#[error(source)] base64::DecodeError), + /// The client sent invalid XML data #[error(display = "Invalid XML: {}", _0)] InvalidXML(String), + /// The client sent a header with invalid value #[error(display = "Invalid header value: {}", _0)] InvalidHeader(#[error(source)] hyper::header::ToStrError), + /// The client sent a range header with invalid value #[error(display = "Invalid HTTP range: {:?}", _0)] InvalidRange(#[error(from)] http_range::HttpRangeParseError), + /// The client sent an invalid request #[error(display = "Bad request: {}", _0)] BadRequest(String), } @@ -52,6 +65,7 @@ impl From for Error { } impl Error { + /// Convert an error into an Http status code pub fn http_status_code(&self) -> StatusCode { match self { Error::NotFound => StatusCode::NOT_FOUND, @@ -65,6 +79,7 @@ impl Error { } } +/// Trait to map error to the Bad Request error code pub trait OkOrBadRequest { type S2; fn ok_or_bad_request(self, reason: &'static str) -> Self::S2; @@ -93,6 +108,7 @@ impl OkOrBadRequest for Option { } } +/// Trait to map an error to an Internal Error code pub trait OkOrInternalError { type S2; fn ok_or_internal_error(self, reason: &'static str) -> Self::S2; diff --git a/src/api/lib.rs b/src/api/lib.rs index 9bb07925..d036cdd6 100644 --- a/src/api/lib.rs +++ b/src/api/lib.rs @@ -1,15 +1,20 @@ +#![deny(missing_crate_level_docs, missing_docs)] +//! Crate for serving a S3 compatible API #[macro_use] extern crate log; -pub mod error; +mod error; +pub use error::Error; -pub mod encoding; +mod encoding; -pub mod api_server; -pub mod signature; +mod api_server; +pub use api_server::run_api_server; -pub mod s3_copy; -pub mod s3_delete; +mod signature; + +mod s3_copy; +mod s3_delete; pub mod s3_get; -pub mod s3_list; -pub mod s3_put; +mod s3_list; +mod s3_put; diff --git a/src/api/s3_get.rs b/src/api/s3_get.rs index 2590c9bd..15c0ed0a 100644 --- a/src/api/s3_get.rs +++ b/src/api/s3_get.rs @@ -1,3 +1,4 @@ +//! Function related to GET and HEAD requests use std::sync::Arc; use std::time::{Duration, UNIX_EPOCH}; @@ -79,6 +80,7 @@ fn try_answer_cached( } } +/// Handle HEAD request pub async fn handle_head( garage: Arc, req: &Request, @@ -118,6 +120,7 @@ pub async fn handle_head( Ok(response) } +/// Handle GET request pub async fn handle_get( garage: Arc, req: &Request, @@ -224,7 +227,7 @@ pub async fn handle_get( } } -pub async fn handle_get_range( +async fn handle_get_range( garage: Arc, version: &ObjectVersion, version_data: &ObjectVersionData, diff --git a/src/garage/server.rs b/src/garage/server.rs index a5bf68a6..97a9bec2 100644 --- a/src/garage/server.rs +++ b/src/garage/server.rs @@ -8,7 +8,7 @@ use garage_util::background::*; use garage_util::config::*; use garage_util::error::Error; -use garage_api::api_server; +use garage_api::run_api_server; use garage_model::garage::Garage; use garage_rpc::rpc_server::RpcServer; use garage_web::run_web_server; @@ -62,7 +62,7 @@ pub async fn run_server(config_file: PathBuf) -> Result<(), Error> { info!("Initializing RPC and API servers..."); let run_rpc_server = Arc::new(rpc_server).run(wait_from(watch_cancel.clone())); - let api_server = api_server::run_api_server(garage.clone(), wait_from(watch_cancel.clone())); + let api_server = run_api_server(garage.clone(), wait_from(watch_cancel.clone())); let web_server = run_web_server(garage, wait_from(watch_cancel.clone())); futures::try_join!( diff --git a/src/model/key_table.rs b/src/model/key_table.rs index 653a38e2..444f3949 100644 --- a/src/model/key_table.rs +++ b/src/model/key_table.rs @@ -10,7 +10,6 @@ pub struct Key { pub key_id: String, /// The secret_key associated - // shouldn't it be hashed or something, so it's trully secret? pub secret_key: String, /// Name for the key diff --git a/src/web/error.rs b/src/web/error.rs index 6da86199..2b8aeebe 100644 --- a/src/web/error.rs +++ b/src/web/error.rs @@ -8,7 +8,7 @@ use garage_util::error::Error as GarageError; pub enum Error { /// An error received from the API crate #[error(display = "API error: {}", _0)] - ApiError(#[error(source)] garage_api::error::Error), + ApiError(#[error(source)] garage_api::Error), // Category: internal error /// Error internal to garage