From ae6c9cb7fa1174ad3078bd1cd52646d557405aed Mon Sep 17 00:00:00 2001 From: Nikolay Kim Date: Thu, 29 Mar 2018 10:44:26 -0700 Subject: [PATCH] re-arrange exports, some doc string updates --- Cargo.toml | 2 +- src/fs.rs | 2 +- src/httprequest.rs | 2 +- src/json.rs | 57 ++++++++++++++++++++++++++++++++++--- src/lib.rs | 14 +++++---- src/server/h1writer.rs | 2 +- src/server/h2writer.rs | 2 +- src/{ => server}/helpers.rs | 0 src/server/mod.rs | 1 + src/server/settings.rs | 2 +- src/ws/client.rs | 4 +++ src/ws/mod.rs | 2 +- 12 files changed, 74 insertions(+), 16 deletions(-) rename src/{ => server}/helpers.rs (100%) diff --git a/Cargo.toml b/Cargo.toml index aa9f2df7..6b91f1b3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "actix-web" -version = "0.4.11" +version = "0.5.0-dev" authors = ["Nikolay Kim "] description = "Actix web is a simple, pragmatic, extremely fast, web framework for Rust." readme = "README.md" diff --git a/src/fs.rs b/src/fs.rs index 8026fd85..b6edfb17 100644 --- a/src/fs.rs +++ b/src/fs.rs @@ -433,7 +433,7 @@ impl StaticFiles { self } - /// Sets default resource which is used when no matched file could be found. + /// Sets default handler which is used when no matched file could be found. pub fn default_handler>(mut self, handler: H) -> StaticFiles { self.default = Box::new(WrapHandler::new(handler)); self diff --git a/src/httprequest.rs b/src/httprequest.rs index 91523321..e545d09a 100644 --- a/src/httprequest.rs +++ b/src/httprequest.rs @@ -20,7 +20,7 @@ use router::Router; use payload::Payload; use httpmessage::HttpMessage; use httpresponse::{HttpResponse, HttpResponseBuilder}; -use helpers::SharedHttpInnerMessage; +use server::helpers::SharedHttpInnerMessage; use error::{UrlGenerationError, CookieParseError, PayloadError}; diff --git a/src/json.rs b/src/json.rs index deb64c3b..44a97108 100644 --- a/src/json.rs +++ b/src/json.rs @@ -1,4 +1,5 @@ use std::fmt; +use std::ops::{Deref, DerefMut}; use bytes::{Bytes, BytesMut}; use futures::{Poll, Future, Stream}; use http::header::CONTENT_LENGTH; @@ -15,11 +16,15 @@ use httprequest::HttpRequest; use httpresponse::HttpResponse; use extractor::HttpRequestExtractor; -/// Json response helper +/// Json helper /// -/// The `Json` type allows you to respond with well-formed JSON data: simply return a value of -/// type Json where T is the type of a structure to serialize into *JSON*. The -/// type `T` must implement the `Serialize` trait from *serde*. +/// Json can be used for two different purpose. First is for json response generation +/// and second is for extracting typed information from request's payload. +/// +/// The `Json` type allows you to respond with well-formed JSON data: simply +/// return a value of type Json where T is the type of a structure +/// to serialize into *JSON*. The type `T` must implement the `Serialize` +/// trait from *serde*. /// /// ```rust /// # extern crate actix_web; @@ -36,8 +41,52 @@ use extractor::HttpRequestExtractor; /// } /// # fn main() {} /// ``` +/// +/// To extract typed information from request's body, the type `T` must implement the +/// `Deserialize` trait from *serde*. +/// +/// ## Example +/// +/// ```rust +/// # extern crate bytes; +/// # extern crate actix_web; +/// # extern crate futures; +/// #[macro_use] extern crate serde_derive; +/// # use actix_web::*; +/// use actix_web::Json; +/// +/// #[derive(Deserialize)] +/// struct Info { +/// username: String, +/// } +/// +/// /// extract `Info` using serde +/// fn index(info: Json) -> Result { +/// Ok(format!("Welcome {}!", info.username)) +/// } +/// +/// fn main() { +/// let app = Application::new().resource( +/// "/index.html", +/// |r| r.method(Method::POST).with(index)); // <- use `with` extractor +/// } +/// ``` pub struct Json(pub T); +impl Deref for Json { + type Target = T; + + fn deref(&self) -> &T { + &self.0 + } +} + +impl DerefMut for Json { + fn deref_mut(&mut self) -> &mut T { + &mut self.0 + } +} + impl fmt::Debug for Json where T: fmt::Debug { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { write!(f, "Json: {:?}", self.0) diff --git a/src/lib.rs b/src/lib.rs index 6390fbdc..4003cefc 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -107,7 +107,6 @@ mod application; mod body; mod context; mod handler; -mod helpers; mod httpmessage; mod httprequest; mod httpresponse; @@ -141,8 +140,6 @@ pub use httpmessage::HttpMessage; pub use httprequest::HttpRequest; pub use httpresponse::HttpResponse; pub use handler::{Either, Responder, NormalizePath, AsyncResponder, FutureResponse}; -pub use route::Route; -pub use resource::Resource; pub use context::HttpContext; pub use server::HttpServer; pub use extractor::{Path, Query}; @@ -163,14 +160,19 @@ pub(crate) const HAS_TLS: bool = false; #[doc(hidden)] #[deprecated(since="0.4.4", note="please use `actix::header` module")] pub mod headers { -//! Headers implementation - + //! Headers implementation pub use httpresponse::ConnectionType; pub use cookie::{Cookie, CookieBuilder}; pub use http_range::HttpRange; pub use header::ContentEncoding; } +pub mod helpers { + //! Various helpers + + pub use handler::{NormalizePath}; +} + pub mod dev { //! The `actix-web` prelude for library developers //! @@ -186,6 +188,8 @@ pub mod dev { pub use context::Drain; pub use info::ConnectionInfo; pub use handler::{Handler, Reply}; + pub use route::Route; + pub use resource::Resource; pub use with::WithHandler; pub use json::JsonBody; pub use router::{Router, Pattern}; diff --git a/src/server/h1writer.rs b/src/server/h1writer.rs index 67b026e4..0e01c8c1 100644 --- a/src/server/h1writer.rs +++ b/src/server/h1writer.rs @@ -8,11 +8,11 @@ use tokio_io::AsyncWrite; use http::{Method, Version}; use http::header::{HeaderValue, CONNECTION, CONTENT_LENGTH, DATE}; -use helpers; use body::{Body, Binary}; use headers::ContentEncoding; use httprequest::HttpInnerMessage; use httpresponse::HttpResponse; +use super::helpers; use super::{Writer, WriterState, MAX_WRITE_BUFFER_SIZE}; use super::shared::SharedBytes; use super::encoding::ContentEncoder; diff --git a/src/server/h2writer.rs b/src/server/h2writer.rs index 32f70961..17c4de1a 100644 --- a/src/server/h2writer.rs +++ b/src/server/h2writer.rs @@ -9,11 +9,11 @@ use http2::server::SendResponse; use http::{Version, HttpTryFrom, Response}; use http::header::{HeaderValue, CONNECTION, TRANSFER_ENCODING, DATE, CONTENT_LENGTH}; -use helpers; use body::{Body, Binary}; use headers::ContentEncoding; use httprequest::HttpInnerMessage; use httpresponse::HttpResponse; +use super::helpers; use super::encoding::ContentEncoder; use super::shared::SharedBytes; use super::settings::WorkerSettings; diff --git a/src/helpers.rs b/src/server/helpers.rs similarity index 100% rename from src/helpers.rs rename to src/server/helpers.rs diff --git a/src/server/mod.rs b/src/server/mod.rs index d33ce7ed..1b80b771 100644 --- a/src/server/mod.rs +++ b/src/server/mod.rs @@ -16,6 +16,7 @@ mod h2; mod h1writer; mod h2writer; mod settings; +pub(crate) mod helpers; pub(crate) mod shared; pub(crate) mod utils; diff --git a/src/server/settings.rs b/src/server/settings.rs index 8b37edb9..07b00042 100644 --- a/src/server/settings.rs +++ b/src/server/settings.rs @@ -8,7 +8,7 @@ use bytes::BytesMut; use http::StatusCode; use futures_cpupool::{Builder, CpuPool}; -use helpers; +use super::helpers; use super::KeepAlive; use super::channel::Node; use super::shared::{SharedBytes, SharedBytesPool}; diff --git a/src/ws/client.rs b/src/ws/client.rs index 61001c47..8b7fa2d6 100644 --- a/src/ws/client.rs +++ b/src/ws/client.rs @@ -268,6 +268,10 @@ struct Inner { closed: bool, } +/// Future that implementes client websocket handshake process. +/// +/// It resolves to a pair of `ClientReadr` and `ClientWriter` that +/// can be used for reading and writing websocket frames. pub struct ClientHandshake { request: Option, tx: Option>, diff --git a/src/ws/mod.rs b/src/ws/mod.rs index 9b7ad8fe..f9f8563b 100644 --- a/src/ws/mod.rs +++ b/src/ws/mod.rs @@ -82,7 +82,7 @@ pub type WsError = ProtocolError; #[deprecated(since="0.4.2", note="please use `ws::HandshakeError` instead")] pub type WsHandshakeError = HandshakeError; -/// Websocket errors +/// Websocket protocol errors #[derive(Fail, Debug)] pub enum ProtocolError { /// Received an unmasked frame from client