actix/actix-extras
1
0
Fork 0
mirror of https://github.com/actix/actix-extras.git synced 2024-11-24 07:53:00 +01:00
Code Issues Releases Wiki Activity

update api docs

Browse Source
This commit is contained in:
Nikolay Kim 2019-03-03 14:45:56 -08:00
parent e50d4c5e0e
commit 360082f99f
6 changed files with 237 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
src/app.rs
View File

@ -245,8 +245,8 @@ where
}
}
/// Structure that follows the builder pattern for building application
/// instances.
/// Application router builder - Structure that follows the builder pattern
/// for building application instances.
pub struct AppRouter<C, P, B, T> {
chain: C,
services: Vec<(ResourceDef, HttpNewService<P>)>,

168
src/extract.rs
View File

@ -165,17 +165,63 @@ impl<T> From<T> for Path<T> {
}
}
/// Extract typed information from the request's path.
///
/// ## Example
///
/// ```rust
/// use actix_web::{web, http, App, extract::Path};
///
/// /// extract path info from "/{username}/{count}/index.html" url
/// /// {username} - deserializes to a String
/// /// {count} - - deserializes to a u32
/// fn index(info: Path<(String, u32)>) -> String {
/// format!("Welcome {}! {}", info.0, info.1)
/// }
///
/// fn main() {
/// let app = App::new().resource(
/// "/{username}/{count}/index.html", // <- define path parameters
/// |r| r.route(web::get().to(index)) // <- register handler with `Path` extractor
/// );
/// }
/// ```
///
/// It is possible to extract path information to a specific type that
/// implements `Deserialize` trait from *serde*.
///
/// ```rust
/// #[macro_use] extern crate serde_derive;
/// use actix_web::{web, App, extract::Path, Error};
///
/// #[derive(Deserialize)]
/// struct Info {
/// username: String,
/// }
///
/// /// extract `Info` from a path using serde
/// fn index(info: Path<Info>) -> Result<String, Error> {
/// Ok(format!("Welcome {}!", info.username))
/// }
///
/// fn main() {
/// let app = App::new().resource(
/// "/{username}/index.html", // <- define path parameters
/// |r| r.route(web::get().to(index)) // <- use handler with Path` extractor
/// );
/// }
/// ```
impl<T, P> FromRequest<P> for Path<T>
where
T: DeserializeOwned,
{
type Error = Error;
type Future = FutureResult<Self, Error>;
type Future = Result<Self, Error>;
type Config = ();
#[inline]
fn from_request(req: &mut ServiceFromRequest<P>) -> Self::Future {
Self::extract(req).map_err(ErrorNotFound).into_future()
Self::extract(req).map_err(ErrorNotFound)
}
}
@ -200,17 +246,17 @@ impl<T: fmt::Display> fmt::Display for Path<T> {
/// #[macro_use] extern crate serde_derive;
/// use actix_web::{web, extract, App};
///
///#[derive(Debug, Deserialize)]
///pub enum ResponseType {
/// #[derive(Debug, Deserialize)]
/// pub enum ResponseType {
/// Token,
/// Code
///}
/// }
///
///#[derive(Deserialize)]
///pub struct AuthRequest {
/// #[derive(Deserialize)]
/// pub struct AuthRequest {
/// id: u64,
/// response_type: ResponseType,
///}
/// }
///
/// // Use `Query` extractor for query information.
/// // This handler get called only if request's query contains `username` field
@ -248,19 +294,52 @@ impl<T> Query<T> {
}
}
/// Extract typed information from from the request's query.
///
/// ## Example
///
/// ```rust
/// #[macro_use] extern crate serde_derive;
/// use actix_web::{web, extract, App};
///
/// #[derive(Debug, Deserialize)]
/// pub enum ResponseType {
/// Token,
/// Code
/// }
///
/// #[derive(Deserialize)]
/// pub struct AuthRequest {
/// id: u64,
/// response_type: ResponseType,
/// }
///
/// // Use `Query` extractor for query information.
/// // This handler get called only if request's query contains `username` field
/// // The correct request for this handler would be `/index.html?id=64&response_type=Code"`
/// fn index(info: extract::Query<AuthRequest>) -> String {
/// format!("Authorization request for client with id={} and type={:?}!", info.id, info.response_type)
/// }
///
/// fn main() {
/// let app = App::new().resource(
/// "/index.html",
/// |r| r.route(web::get().to(index))); // <- use `Query` extractor
/// }
/// ```
impl<T, P> FromRequest<P> for Query<T>
where
T: de::DeserializeOwned,
{
type Error = Error;
type Future = FutureResult<Self, Error>;
type Future = Result<Self, Error>;
type Config = ();
#[inline]
fn from_request(req: &mut ServiceFromRequest<P>) -> Self::Future {
serde_urlencoded::from_str::<T>(req.query_string())
.map(|val| ok(Query(val)))
.unwrap_or_else(|e| err(e.into()))
.map(|val| Ok(Query(val)))
.unwrap_or_else(|e| Err(e.into()))
}
}
@ -282,7 +361,7 @@ impl<T: fmt::Display> fmt::Display for Query<T> {
/// To extract typed information from request's body, the type `T` must
/// implement the `Deserialize` trait from *serde*.
///
/// [**FormConfig**](dev/struct.FormConfig.html) allows to configure extraction
/// [**FormConfig**](struct.FormConfig.html) allows to configure extraction
/// process.
///
/// ## Example
@ -436,7 +515,7 @@ impl Default for FormConfig {
/// To extract typed information from request's body, the type `T` must
/// implement the `Deserialize` trait from *serde*.
///
/// [**JsonConfig**](dev/struct.JsonConfig.html) allows to configure extraction
/// [**JsonConfig**](struct.JsonConfig.html) allows to configure extraction
/// process.
///
/// ## Example
@ -526,20 +605,51 @@ where
impl<T: Serialize> Responder for Json<T> {
type Error = Error;
type Future = FutureResult<Response, Error>;
type Future = Result<Response, Error>;
fn respond_to(self, _: &HttpRequest) -> Self::Future {
let body = match serde_json::to_string(&self.0) {
Ok(body) => body,
Err(e) => return err(e.into()),
Err(e) => return Err(e.into()),
};
ok(Response::build(StatusCode::OK)
Ok(Response::build(StatusCode::OK)
.content_type("application/json")
.body(body))
}
}
/// Json extractor. Allow to extract typed information from request's
/// payload.
///
/// To extract typed information from request's body, the type `T` must
/// implement the `Deserialize` trait from *serde*.
///
/// [**JsonConfig**](struct.JsonConfig.html) allows to configure extraction
/// process.
///
/// ## Example
///
/// ```rust
/// #[macro_use] extern crate serde_derive;
/// use actix_web::{web, extract, App};
///
/// #[derive(Deserialize)]
/// struct Info {
/// username: String,
/// }
///
/// /// deserialize `Info` from request's body
/// fn index(info: extract::Json<Info>) -> String {
/// format!("Welcome {}!", info.username)
/// }
///
/// fn main() {
/// let app = App::new().resource(
/// "/index.html",
/// |r| r.route(web::post().to(index)));
/// }
/// ```
impl<T, P> FromRequest<P> for Json<T>
where
T: DeserializeOwned + 'static,
@ -632,7 +742,7 @@ impl Default for JsonConfig {
///
/// Loads request's payload and construct Bytes instance.
///
/// [**PayloadConfig**](dev/struct.PayloadConfig.html) allows to configure
/// [**PayloadConfig**](struct.PayloadConfig.html) allows to configure
/// extraction process.
///
/// ## Example
@ -677,7 +787,7 @@ where
///
/// Text extractor automatically decode body according to the request's charset.
///
/// [**PayloadConfig**](dev/struct.PayloadConfig.html) allows to configure
/// [**PayloadConfig**](struct.PayloadConfig.html) allows to configure
/// extraction process.
///
/// ## Example
@ -931,6 +1041,17 @@ impl Default for PayloadConfig {
}
}
#[doc(hidden)]
impl<P> FromRequest<P> for () {
type Error = Error;
type Future = FutureResult<(), Error>;
type Config = ();
fn from_request(_req: &mut ServiceFromRequest<P>) -> Self::Future {
ok(())
}
}
macro_rules! tuple_config ({ $($T:ident),+} => {
impl<$($T,)+> ExtractorConfig for ($($T,)+)
where $($T: ExtractorConfig + Clone,)+
@ -944,6 +1065,7 @@ macro_rules! tuple_config ({ $($T:ident),+} => {
macro_rules! tuple_from_req ({$fut_type:ident, $(($n:tt, $T:ident)),+} => {
/// FromRequest implementation for tuple
#[doc(hidden)]
impl<P, $($T: FromRequest<P> + 'static),+> FromRequest<P> for ($($T,)+)
{
type Error = Error;
@ -995,16 +1117,6 @@ macro_rules! tuple_from_req ({$fut_type:ident, $(($n:tt, $T:ident)),+} => {
}
});
impl<P> FromRequest<P> for () {
type Error = Error;
type Future = FutureResult<(), Error>;
type Config = ();
fn from_request(_req: &mut ServiceFromRequest<P>) -> Self::Future {
ok(())
}
}
#[rustfmt::skip]
mod m {
use super::*;

11
src/lib.rs
View File

@ -2,7 +2,7 @@
mod app;
pub mod extract;
pub mod handler;
mod handler;
// mod info;
pub mod blocking;
pub mod guard;
@ -19,7 +19,7 @@ pub mod test;
pub use actix_http::Response as HttpResponse;
pub use actix_http::{error, http, Error, HttpMessage, ResponseError, Result};
pub use crate::app::App;
pub use crate::app::{App, AppRouter};
pub use crate::extract::{FromRequest, Json};
pub use crate::request::HttpRequest;
pub use crate::resource::Resource;
@ -37,30 +37,37 @@ pub mod web {
use crate::responder::Responder;
use crate::Route;
/// Create **route** without configuration.
pub fn route<P: 'static>() -> Route<P> {
Route::new()
}
/// Create **route** with `GET` method guard.
pub fn get<P: 'static>() -> Route<P> {
Route::get()
}
/// Create **route** with `POST` method guard.
pub fn post<P: 'static>() -> Route<P> {
Route::post()
}
/// Create **route** with `PUT` method guard.
pub fn put<P: 'static>() -> Route<P> {
Route::put()
}
/// Create **route** with `DELETE` method guard.
pub fn delete<P: 'static>() -> Route<P> {
Route::delete()
}
/// Create **route** with `HEAD` method guard.
pub fn head<P: 'static>() -> Route<P> {
Route::new().method(Method::HEAD)
}
/// Create **route** and add method guard.
pub fn method<P: 'static>(method: Method) -> Route<P> {
Route::new().method(method)
}

27
src/request.rs
View File

@ -6,12 +6,12 @@ use std::rc::Rc;
use actix_http::http::{HeaderMap, Method, Uri, Version};
use actix_http::{Error, Extensions, HttpMessage, Message, Payload, RequestHead};
use actix_router::{Path, Url};
use futures::future::{ok, FutureResult};
use crate::extract::FromRequest;
use crate::service::ServiceFromRequest;
#[derive(Clone)]
/// An HTTP Request
pub struct HttpRequest {
pub(crate) head: Message<RequestHead>,
pub(crate) path: Path<Url>,
@ -20,7 +20,7 @@ pub struct HttpRequest {
impl HttpRequest {
#[inline]
pub fn new(
pub(crate) fn new(
head: Message<RequestHead>,
path: Path<Url>,
extensions: Rc<Extensions>,
@ -140,14 +140,33 @@ impl HttpMessage for HttpRequest {
}
}
/// It is possible to get `HttpRequest` as an extractor handler parameter
///
/// ## Example
///
/// ```rust
/// # #[macro_use] extern crate serde_derive;
/// use actix_web::{web, App, HttpRequest};
///
/// /// extract `Thing` from request
/// fn index(req: HttpRequest) -> String {
/// format!("Got thing: {:?}", req)
/// }
///
/// fn main() {
/// let app = App::new().resource("/users/:first", |r| {
/// r.route(web::get().to(index))
/// });
/// }
/// ```
impl<P> FromRequest<P> for HttpRequest {
type Error = Error;
type Future = FutureResult<Self, Error>;
type Future = Result<Self, Error>;
type Config = ();
#[inline]
fn from_request(req: &mut ServiceFromRequest<P>) -> Self::Future {
ok(req.clone())
Ok(req.clone())
}
}

46
src/resource.rs
View File

@ -18,10 +18,24 @@ use crate::service::{ServiceRequest, ServiceResponse};
type HttpService<P> = BoxedService<ServiceRequest<P>, ServiceResponse, ()>;
type HttpNewService<P> = BoxedNewService<(), ServiceRequest<P>, ServiceResponse, (), ()>;
/// Resource route definition
/// *Resource* is an entry in route table which corresponds to requested URL.
///
/// Route uses builder-like pattern for configuration.
/// If handler is not explicitly set, default *404 Not Found* handler is used.
/// Resource in turn has at least one route.
/// Route consists of an handlers objects and list of guards
/// (objects that implement `Guard` trait).
/// Resources and rouets uses builder-like pattern for configuration.
/// During request handling, resource object iterate through all routes
/// and check guards for specific route, if request matches all
/// guards, route considered matched and route handler get called.
///
/// ```rust
/// use actix_web::{web, App, HttpResponse};
///
/// fn main() {
/// let app = App::new()
/// .resource(
/// "/", |r| r.route(web::get().to(|| HttpResponse::Ok())));
/// }
pub struct Resource<P, T = ResourceEndpoint<P>> {
routes: Vec<Route<P>>,
endpoint: T,
@ -58,8 +72,6 @@ where
>,
{
/// Register a new route.
/// *Route* is used for route configuration, i.e. adding guards,
/// setting up handler.
///
/// ```rust
/// use actix_web::{web, guard, App, HttpResponse};
@ -74,12 +86,31 @@ where
/// });
/// }
/// ```
///
/// Multiple routes could be added to a resource.
///
/// ```rust
/// use actix_web::{web, guard, App, HttpResponse};
///
/// fn main() {
/// let app = App::new()
/// .resource("/container/", |r| {
/// r.route(web::get().to(get_handler))
/// .route(web::post().to(post_handler))
/// .route(web::delete().to(delete_handler))
/// });
/// }
/// # fn get_handler() {}
/// # fn post_handler() {}
/// # fn delete_handler() {}
/// ```
pub fn route(mut self, route: Route<P>) -> Self {
self.routes.push(route.finish());
self
}
/// Register a new route and add handler.
/// Register a new route and add handler. This route get called for all
/// requests.
///
/// ```rust
/// use actix_web::*;
@ -148,7 +179,8 @@ where
/// Register a resource middleware
///
/// This is similar to `App's` middlewares, but
/// middlewares get invoked on resource level.
/// middleware is not allowed to change response type (i.e modify response's body).
/// Middleware get invoked on resource level.
pub fn middleware<M, F>(
self,
mw: F,

48
src/state.rs
View File

@ -3,7 +3,6 @@ use std::rc::Rc;
use actix_http::error::{Error, ErrorInternalServerError};
use actix_http::Extensions;
use futures::future::{err, ok, FutureResult};
use futures::{Async, Future, IntoFuture, Poll};
use crate::extract::FromRequest;
@ -19,60 +18,61 @@ pub(crate) trait StateFactoryResult {
}
/// Application state
pub struct State<S>(Rc<S>);
pub struct State<T>(Rc<T>);
impl<S> State<S> {
pub fn new(state: S) -> State<S> {
impl<T> State<T> {
pub(crate) fn new(state: T) -> State<T> {
State(Rc::new(state))
}
pub fn get_ref(&self) -> &S {
/// Get referecnce to inner state type.
pub fn get_ref(&self) -> &T {
self.0.as_ref()
}
}
impl<S> Deref for State<S> {
type Target = S;
impl<T> Deref for State<T> {
type Target = T;
fn deref(&self) -> &S {
fn deref(&self) -> &T {
self.0.as_ref()
}
}
impl<S> Clone for State<S> {
fn clone(&self) -> State<S> {
impl<T> Clone for State<T> {
fn clone(&self) -> State<T> {
State(self.0.clone())
}
}
impl<S: 'static, P> FromRequest<P> for State<S> {
impl<T: 'static, P> FromRequest<P> for State<T> {
type Error = Error;
type Future = FutureResult<Self, Error>;
type Future = Result<Self, Error>;
type Config = ();
#[inline]
fn from_request(req: &mut ServiceFromRequest<P>) -> Self::Future {
if let Some(st) = req.app_extensions().get::<State<S>>() {
ok(st.clone())
if let Some(st) = req.app_extensions().get::<State<T>>() {
Ok(st.clone())
} else {
err(ErrorInternalServerError(
"State is not configured, use App::state()",
Err(ErrorInternalServerError(
"State is not configured, to configure use App::state()",
))
}
}
}
impl<S: 'static> StateFactory for State<S> {
impl<T: 'static> StateFactory for State<T> {
fn construct(&self) -> Box<StateFactoryResult> {
Box::new(StateFut { st: self.clone() })
}
}
struct StateFut<S> {
st: State<S>,
struct StateFut<T> {
st: State<T>,
}
impl<S: 'static> StateFactoryResult for StateFut<S> {
impl<T: 'static> StateFactoryResult for StateFut<T> {
fn poll_result(&mut self, extensions: &mut Extensions) -> Poll<(), ()> {
extensions.insert(self.st.clone());
Ok(Async::Ready(()))
@ -92,17 +92,17 @@ where
}
}
struct StateFactoryFut<S, F>
struct StateFactoryFut<T, F>
where
F: Future<Item = S>,
F: Future<Item = T>,
F::Error: std::fmt::Debug,
{
fut: F,
}
impl<S: 'static, F> StateFactoryResult for StateFactoryFut<S, F>
impl<T: 'static, F> StateFactoryResult for StateFactoryFut<T, F>
where
F: Future<Item = S>,
F: Future<Item = T>,
F::Error: std::fmt::Debug,
{
fn poll_result(&mut self, extensions: &mut Extensions) -> Poll<(), ()> {