From 457b75c9950657b1c402570da4b2538f5a4e0141 Mon Sep 17 00:00:00 2001 From: Nikolay Kim Date: Sat, 30 Mar 2019 10:04:38 -0700 Subject: [PATCH] update api docs; move web to submodule --- CHANGES.md | 5 + Cargo.toml | 2 +- src/lib.rs | 213 +-------------------------------------- src/test.rs | 2 + src/web.rs | 285 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 298 insertions(+), 209 deletions(-) create mode 100644 src/web.rs diff --git a/CHANGES.md b/CHANGES.md index e18635916..e8389910e 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,5 +1,10 @@ # Changes +### Removed + +* Removed unused `actix_web::web::md()` + + ## [1.0.0-alpha.2] - 2019-03-29 ### Added diff --git a/Cargo.toml b/Cargo.toml index f7f285091..fb53008eb 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "actix-web" -version = "1.0.0-alpha.2" +version = "1.0.0-alpha.3" authors = ["Nikolay Kim "] description = "Actix web is a simple, pragmatic and extremely fast web framework for Rust." readme = "README.md" diff --git a/src/lib.rs b/src/lib.rs index 2bef6a526..cb29fa5b0 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -42,6 +42,9 @@ //! represents an HTTP server instance and is used to instantiate and //! configure servers. //! +//! * [web](web/index.html): This module +//! provide essentials helper functions and types for application registration. +//! //! * [HttpRequest](struct.HttpRequest.html) and //! [HttpResponse](struct.HttpResponse.html): These structs //! represent HTTP requests and responses and expose various methods @@ -67,7 +70,7 @@ //! * `tls` - enables ssl support via `native-tls` crate //! * `ssl` - enables ssl support via `openssl` crate, supports `http/2` //! * `rust-tls` - enables ssl support via `rustls` crate, supports `http/2` -//! * `cookies` - enables cookies support, includes `ring` crate as +//! * `secure-cookies` - enables secure cookies support, includes `ring` crate as //! dependency //! * `brotli` - enables `brotli` compression support, requires `c` //! compiler @@ -98,6 +101,7 @@ mod server; mod service; pub mod test; mod types; +pub mod web; #[allow(unused_imports)] #[macro_use] @@ -159,213 +163,6 @@ pub mod dev { } } -pub mod web { - //! Various types - use actix_http::{http::Method, Response}; - use actix_service::{fn_transform, Service, Transform}; - use futures::{Future, IntoFuture}; - - pub use actix_http::Response as HttpResponse; - pub use bytes::{Bytes, BytesMut}; - - use crate::error::{BlockingError, Error}; - use crate::extract::FromRequest; - use crate::handler::{AsyncFactory, Factory}; - use crate::resource::Resource; - use crate::responder::Responder; - use crate::route::Route; - use crate::scope::Scope; - use crate::service::{ServiceRequest, ServiceResponse}; - - pub use crate::data::{Data, RouteData}; - pub use crate::request::HttpRequest; - pub use crate::types::*; - - /// Create resource for a specific path. - /// - /// Resources may have variable path segments. For example, a - /// resource with the path `/a/{name}/c` would match all incoming - /// requests with paths such as `/a/b/c`, `/a/1/c`, or `/a/etc/c`. - /// - /// A variable segment is specified in the form `{identifier}`, - /// where the identifier can be used later in a request handler to - /// access the matched value for that segment. This is done by - /// looking up the identifier in the `Params` object returned by - /// `HttpRequest.match_info()` method. - /// - /// By default, each segment matches the regular expression `[^{}/]+`. - /// - /// You can also specify a custom regex in the form `{identifier:regex}`: - /// - /// For instance, to route `GET`-requests on any route matching - /// `/users/{userid}/{friend}` and store `userid` and `friend` in - /// the exposed `Params` object: - /// - /// ```rust - /// # extern crate actix_web; - /// use actix_web::{web, http, App, HttpResponse}; - /// - /// fn main() { - /// let app = App::new().service( - /// web::resource("/users/{userid}/{friend}") - /// .route(web::get().to(|| HttpResponse::Ok())) - /// .route(web::head().to(|| HttpResponse::MethodNotAllowed())) - /// ); - /// } - /// ``` - pub fn resource(path: &str) -> Resource

{ - Resource::new(path) - } - - /// Configure scope for common root path. - /// - /// Scopes collect multiple paths under a common path prefix. - /// Scope path can contain variable path segments as resources. - /// - /// ```rust - /// # extern crate actix_web; - /// use actix_web::{web, App, HttpRequest, HttpResponse}; - /// - /// fn main() { - /// let app = App::new().service( - /// web::scope("/{project_id}") - /// .service(web::resource("/path1").to(|| HttpResponse::Ok())) - /// .service(web::resource("/path2").to(|| HttpResponse::Ok())) - /// .service(web::resource("/path3").to(|| HttpResponse::MethodNotAllowed())) - /// ); - /// } - /// ``` - /// - /// In the above example, three routes get added: - /// * /{project_id}/path1 - /// * /{project_id}/path2 - /// * /{project_id}/path3 - /// - pub fn scope(path: &str) -> Scope

{ - Scope::new(path) - } - - /// Create *route* without configuration. - pub fn route() -> Route

{ - Route::new() - } - - /// Create *route* with `GET` method guard. - pub fn get() -> Route

{ - Route::new().method(Method::GET) - } - - /// Create *route* with `POST` method guard. - pub fn post() -> Route

{ - Route::new().method(Method::POST) - } - - /// Create *route* with `PUT` method guard. - pub fn put() -> Route

{ - Route::new().method(Method::PUT) - } - - /// Create *route* with `PATCH` method guard. - pub fn patch() -> Route

{ - Route::new().method(Method::PATCH) - } - - /// Create *route* with `DELETE` method guard. - pub fn delete() -> Route

{ - Route::new().method(Method::DELETE) - } - - /// Create *route* with `HEAD` method guard. - pub fn head() -> Route

{ - Route::new().method(Method::HEAD) - } - - /// Create *route* and add method guard. - pub fn method(method: Method) -> Route

{ - Route::new().method(method) - } - - /// Create a new route and add handler. - /// - /// ```rust - /// use actix_web::{web, App, HttpResponse}; - /// - /// fn index() -> HttpResponse { - /// unimplemented!() - /// } - /// - /// App::new().service( - /// web::resource("/").route( - /// web::to(index)) - /// ); - /// ``` - pub fn to(handler: F) -> Route

- where - F: Factory + 'static, - I: FromRequest

+ 'static, - R: Responder + 'static, - { - Route::new().to(handler) - } - - /// Create a new route and add async handler. - /// - /// ```rust - /// use actix_web::{web, App, HttpResponse, Error}; - /// - /// fn index() -> impl futures::Future { - /// futures::future::ok(HttpResponse::Ok().finish()) - /// } - /// - /// App::new().service(web::resource("/").route( - /// web::to_async(index)) - /// ); - /// ``` - pub fn to_async(handler: F) -> Route

- where - F: AsyncFactory, - I: FromRequest

+ 'static, - R: IntoFuture + 'static, - R::Item: Into, - R::Error: Into, - { - Route::new().to_async(handler) - } - - /// Execute blocking function on a thread pool, returns future that resolves - /// to result of the function execution. - pub fn block(f: F) -> impl Future> - where - F: FnOnce() -> Result + Send + 'static, - I: Send + 'static, - E: Send + std::fmt::Debug + 'static, - { - actix_threadpool::run(f).from_err() - } - - /// Create middleare - pub fn md( - f: F, - ) -> impl Transform< - S, - Request = ServiceRequest

, - Response = ServiceResponse, - Error = Error, - InitError = (), - > - where - S: Service< - Request = ServiceRequest

, - Response = ServiceResponse, - Error = Error, - >, - F: FnMut(ServiceRequest

, &mut S) -> R + Clone, - R: IntoFuture, Error = Error>, - { - fn_transform(f) - } -} - #[cfg(feature = "client")] pub mod client { //! An HTTP Client diff --git a/src/test.rs b/src/test.rs index a9aa22789..f18fc2b31 100644 --- a/src/test.rs +++ b/src/test.rs @@ -56,6 +56,7 @@ where .unwrap() } +/// Create service that always responds with `HttpResponse::Ok()` pub fn ok_service() -> impl Service< Request = ServiceRequest, Response = ServiceResponse, @@ -64,6 +65,7 @@ pub fn ok_service() -> impl Service< default_service(StatusCode::OK) } +/// Create service that responds with response with specified status code pub fn default_service( status_code: StatusCode, ) -> impl Service< diff --git a/src/web.rs b/src/web.rs new file mode 100644 index 000000000..65b3cfc70 --- /dev/null +++ b/src/web.rs @@ -0,0 +1,285 @@ +//! Essentials helper functions and types for application registration. +use actix_http::{http::Method, Response}; +use futures::{Future, IntoFuture}; + +pub use actix_http::Response as HttpResponse; +pub use bytes::{Bytes, BytesMut}; + +use crate::error::{BlockingError, Error}; +use crate::extract::FromRequest; +use crate::handler::{AsyncFactory, Factory}; +use crate::resource::Resource; +use crate::responder::Responder; +use crate::route::Route; +use crate::scope::Scope; + +pub use crate::data::{Data, RouteData}; +pub use crate::request::HttpRequest; +pub use crate::types::*; + +/// Create resource for a specific path. +/// +/// Resources may have variable path segments. For example, a +/// resource with the path `/a/{name}/c` would match all incoming +/// requests with paths such as `/a/b/c`, `/a/1/c`, or `/a/etc/c`. +/// +/// A variable segment is specified in the form `{identifier}`, +/// where the identifier can be used later in a request handler to +/// access the matched value for that segment. This is done by +/// looking up the identifier in the `Params` object returned by +/// `HttpRequest.match_info()` method. +/// +/// By default, each segment matches the regular expression `[^{}/]+`. +/// +/// You can also specify a custom regex in the form `{identifier:regex}`: +/// +/// For instance, to route `GET`-requests on any route matching +/// `/users/{userid}/{friend}` and store `userid` and `friend` in +/// the exposed `Params` object: +/// +/// ```rust +/// # extern crate actix_web; +/// use actix_web::{web, App, HttpResponse}; +/// +/// fn main() { +/// let app = App::new().service( +/// web::resource("/users/{userid}/{friend}") +/// .route(web::get().to(|| HttpResponse::Ok())) +/// .route(web::head().to(|| HttpResponse::MethodNotAllowed())) +/// ); +/// } +/// ``` +pub fn resource(path: &str) -> Resource

{ + Resource::new(path) +} + +/// Configure scope for common root path. +/// +/// Scopes collect multiple paths under a common path prefix. +/// Scope path can contain variable path segments as resources. +/// +/// ```rust +/// use actix_web::{web, App, HttpResponse}; +/// +/// fn main() { +/// let app = App::new().service( +/// web::scope("/{project_id}") +/// .service(web::resource("/path1").to(|| HttpResponse::Ok())) +/// .service(web::resource("/path2").to(|| HttpResponse::Ok())) +/// .service(web::resource("/path3").to(|| HttpResponse::MethodNotAllowed())) +/// ); +/// } +/// ``` +/// +/// In the above example, three routes get added: +/// * /{project_id}/path1 +/// * /{project_id}/path2 +/// * /{project_id}/path3 +/// +pub fn scope(path: &str) -> Scope

{ + Scope::new(path) +} + +/// Create *route* without configuration. +pub fn route() -> Route

{ + Route::new() +} + +/// Create *route* with `GET` method guard. +/// +/// ```rust +/// use actix_web::{web, App, HttpResponse}; +/// +/// fn main() { +/// let app = App::new().service( +/// web::resource("/{project_id}") +/// .route(web::get().to(|| HttpResponse::Ok())) +/// ); +/// } +/// ``` +/// +/// In the above example, one `GET` route get added: +/// * /{project_id} +/// +pub fn get() -> Route

{ + Route::new().method(Method::GET) +} + +/// Create *route* with `POST` method guard. +/// +/// ```rust +/// use actix_web::{web, App, HttpResponse}; +/// +/// fn main() { +/// let app = App::new().service( +/// web::resource("/{project_id}") +/// .route(web::post().to(|| HttpResponse::Ok())) +/// ); +/// } +/// ``` +/// +/// In the above example, one `POST` route get added: +/// * /{project_id} +/// +pub fn post() -> Route

{ + Route::new().method(Method::POST) +} + +/// Create *route* with `PUT` method guard. +/// +/// ```rust +/// use actix_web::{web, App, HttpResponse}; +/// +/// fn main() { +/// let app = App::new().service( +/// web::resource("/{project_id}") +/// .route(web::put().to(|| HttpResponse::Ok())) +/// ); +/// } +/// ``` +/// +/// In the above example, one `PUT` route get added: +/// * /{project_id} +/// +pub fn put() -> Route

{ + Route::new().method(Method::PUT) +} + +/// Create *route* with `PATCH` method guard. +/// +/// ```rust +/// use actix_web::{web, App, HttpResponse}; +/// +/// fn main() { +/// let app = App::new().service( +/// web::resource("/{project_id}") +/// .route(web::patch().to(|| HttpResponse::Ok())) +/// ); +/// } +/// ``` +/// +/// In the above example, one `PATCH` route get added: +/// * /{project_id} +/// +pub fn patch() -> Route

{ + Route::new().method(Method::PATCH) +} + +/// Create *route* with `DELETE` method guard. +/// +/// ```rust +/// use actix_web::{web, App, HttpResponse}; +/// +/// fn main() { +/// let app = App::new().service( +/// web::resource("/{project_id}") +/// .route(web::delete().to(|| HttpResponse::Ok())) +/// ); +/// } +/// ``` +/// +/// In the above example, one `DELETE` route get added: +/// * /{project_id} +/// +pub fn delete() -> Route

{ + Route::new().method(Method::DELETE) +} + +/// Create *route* with `HEAD` method guard. +/// +/// ```rust +/// use actix_web::{web, App, HttpResponse}; +/// +/// fn main() { +/// let app = App::new().service( +/// web::resource("/{project_id}") +/// .route(web::head().to(|| HttpResponse::Ok())) +/// ); +/// } +/// ``` +/// +/// In the above example, one `HEAD` route get added: +/// * /{project_id} +/// +pub fn head() -> Route

{ + Route::new().method(Method::HEAD) +} + +/// Create *route* and add method guard. +/// +/// ```rust +/// use actix_web::{web, http, App, HttpResponse}; +/// +/// fn main() { +/// let app = App::new().service( +/// web::resource("/{project_id}") +/// .route(web::method(http::Method::GET).to(|| HttpResponse::Ok())) +/// ); +/// } +/// ``` +/// +/// In the above example, one `GET` route get added: +/// * /{project_id} +/// +pub fn method(method: Method) -> Route

{ + Route::new().method(method) +} + +/// Create a new route and add handler. +/// +/// ```rust +/// use actix_web::{web, App, HttpResponse}; +/// +/// fn index() -> HttpResponse { +/// unimplemented!() +/// } +/// +/// App::new().service( +/// web::resource("/").route( +/// web::to(index)) +/// ); +/// ``` +pub fn to(handler: F) -> Route

+where + F: Factory + 'static, + I: FromRequest

+ 'static, + R: Responder + 'static, +{ + Route::new().to(handler) +} + +/// Create a new route and add async handler. +/// +/// ```rust +/// # use futures::future::{ok, Future}; +/// use actix_web::{web, App, HttpResponse, Error}; +/// +/// fn index() -> impl Future { +/// ok(HttpResponse::Ok().finish()) +/// } +/// +/// App::new().service(web::resource("/").route( +/// web::to_async(index)) +/// ); +/// ``` +pub fn to_async(handler: F) -> Route

+where + F: AsyncFactory, + I: FromRequest

+ 'static, + R: IntoFuture + 'static, + R::Item: Into, + R::Error: Into, +{ + Route::new().to_async(handler) +} + +/// Execute blocking function on a thread pool, returns future that resolves +/// to result of the function execution. +pub fn block(f: F) -> impl Future> +where + F: FnOnce() -> Result + Send + 'static, + I: Send + 'static, + E: Send + std::fmt::Debug + 'static, +{ + actix_threadpool::run(f).from_err() +}