mirrors/actix-web
1
0
Fork 0
mirror of https://github.com/actix/actix-web.git synced 2024-12-03 14:56:44 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #165 from tazjin/docs/various-doc-fixes

Browse source 
Various minor documentation fixes
This commit is contained in:
Nikolay Kim 2018-04-07 09:53:19 -07:00 committed by GitHub
commit 89bf12605d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 143 additions and 108 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
README.md
View file

@ -1,6 +1,6 @@
# Actix web [![Build Status](https://travis-ci.org/actix/actix-web.svg?branch=master)](https://travis-ci.org/actix/actix-web) [![Build status](https://ci.appveyor.com/api/projects/status/kkdb4yce7qhm5w85/branch/master?svg=true)](https://ci.appveyor.com/project/fafhrd91/actix-web-hdy9d/branch/master) [![codecov](https://codecov.io/gh/actix/actix-web/branch/master/graph/badge.svg)](https://codecov.io/gh/actix/actix-web) [![crates.io](https://meritbadge.herokuapp.com/actix-web)](https://crates.io/crates/actix-web) [![Join the chat at https://gitter.im/actix/actix](https://badges.gitter.im/actix/actix.svg)](https://gitter.im/actix/actix?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) # Actix web [![Build Status](https://travis-ci.org/actix/actix-web.svg?branch=master)](https://travis-ci.org/actix/actix-web) [![Build status](https://ci.appveyor.com/api/projects/status/kkdb4yce7qhm5w85/branch/master?svg=true)](https://ci.appveyor.com/project/fafhrd91/actix-web-hdy9d/branch/master) [![codecov](https://codecov.io/gh/actix/actix-web/branch/master/graph/badge.svg)](https://codecov.io/gh/actix/actix-web) [![crates.io](https://meritbadge.herokuapp.com/actix-web)](https://crates.io/crates/actix-web) [![Join the chat at https://gitter.im/actix/actix](https://badges.gitter.im/actix/actix.svg)](https://gitter.im/actix/actix?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
Actix web is a simple, pragmatic, extremely fast, web framework for Rust. Actix web is a simple, pragmatic and extremely fast web framework for Rust.
* Supported *HTTP/1.x* and [*HTTP/2.0*](https://actix.github.io/actix-web/guide/qs_13.html) protocols * Supported *HTTP/1.x* and [*HTTP/2.0*](https://actix.github.io/actix-web/guide/qs_13.html) protocols
* Streaming and pipelining * Streaming and pipelining
@ -11,14 +11,14 @@ Actix web is a simple, pragmatic, extremely fast, web framework for Rust.
* Graceful server shutdown * Graceful server shutdown
* Multipart streams * Multipart streams
* Static assets * Static assets
* SSL support with openssl or native-tls * SSL support with OpenSSL or `native-tls`
* Middlewares ([Logger](https://actix.github.io/actix-web/guide/qs_10.html#logging), * Middlewares ([Logger](https://actix.github.io/actix-web/guide/qs_10.html#logging),
[Session](https://actix.github.io/actix-web/guide/qs_10.html#user-sessions), [Session](https://actix.github.io/actix-web/guide/qs_10.html#user-sessions),
[Redis sessions](https://github.com/actix/actix-redis), [Redis sessions](https://github.com/actix/actix-redis),
[DefaultHeaders](https://actix.github.io/actix-web/guide/qs_10.html#default-headers), [DefaultHeaders](https://actix.github.io/actix-web/guide/qs_10.html#default-headers),
[CORS](https://actix.github.io/actix-web/actix_web/middleware/cors/index.html), [CORS](https://actix.github.io/actix-web/actix_web/middleware/cors/index.html),
[CSRF](https://actix.github.io/actix-web/actix_web/middleware/csrf/index.html)) [CSRF](https://actix.github.io/actix-web/actix_web/middleware/csrf/index.html))
* Built on top of [Actix actor framework](https://github.com/actix/actix). * Built on top of [Actix actor framework](https://github.com/actix/actix)
## Documentation ## Documentation
@ -31,7 +31,7 @@ Actix web is a simple, pragmatic, extremely fast, web framework for Rust.
## Example ## Example
At the moment all examples uses actix-web master. At the moment all examples are based on the actix-web `master` branch.
```toml ```toml
[dependencies] [dependencies]

109
src/application.rs
View file

@ -140,7 +140,7 @@ pub struct App<S=()> {
impl App<()> { impl App<()> {
/// Create application with empty state. Application can /// Create application with empty state. Application can
/// be configured with builder-like pattern. /// be configured with a builder-like pattern.
pub fn new() -> App<()> { pub fn new() -> App<()> {
App { App {
parts: Some(ApplicationParts { parts: Some(ApplicationParts {
@ -166,11 +166,11 @@ impl Default for App<()> {
impl<S> App<S> where S: 'static { impl<S> App<S> where S: 'static {
/// Create application with specific state. Application can be /// Create application with specified state. Application can be
/// configured with builder-like pattern. /// configured with a builder-like pattern.
/// ///
/// State is shared with all resources within same application and could be /// State is shared with all resources within same application and
/// accessed with `HttpRequest::state()` method. /// could be accessed with `HttpRequest::state()` method.
pub fn with_state(state: S) -> App<S> { pub fn with_state(state: S) -> App<S> {
App { App {
parts: Some(ApplicationParts { parts: Some(ApplicationParts {
@ -187,18 +187,24 @@ impl<S> App<S> where S: 'static {
} }
} }
/// Set application prefix /// Set application prefix.
/// ///
/// Only requests that matches application's prefix get processed by this application. /// Only requests that match the application's prefix get
/// Application prefix always contains leading "/" slash. If supplied prefix /// processed by this application.
/// does not contain leading slash, it get inserted. Prefix should
/// consists valid path segments. i.e for application with
/// prefix `/app` any request with following paths `/app`, `/app/` or `/app/test`
/// would match, but path `/application` would not match.
/// ///
/// In the following example only requests with "/app/" path prefix /// The application prefix always contains a leading slash (`/`).
/// get handled. Request with path "/app/test/" would be handled, /// If the supplied prefix does not contain leading slash, it is
/// but request with path "/application" or "/other/..." would return *NOT FOUND* /// inserted.
///
/// Prefix should consist of valid path segments. i.e for an
/// application with the prefix `/app` any request with the paths
/// `/app`, `/app/` or `/app/test` would match, but the path
/// `/application` would not.
///
/// In the following example only requests with an `/app/` path
/// prefix get handled. Requests with path `/app/test/` would be
/// handled, while requests with the paths `/application` or
/// `/other/...` would return `NOT FOUND`.
/// ///
/// ```rust /// ```rust
/// # extern crate actix_web; /// # extern crate actix_web;
@ -226,12 +232,14 @@ impl<S> App<S> where S: 'static {
self self
} }
/// Configure route for specific path. /// Configure route for a specific path.
/// ///
/// This is simplified version of `App::resource()` method. /// This is a simplified version of the `App::resource()` method.
/// Handler function needs to accept one request extractor argument. /// Handler functions need to accept one request extractor
/// This method could be called multiple times, in that case multiple routes /// argument.
/// would be registered for same resource path. ///
/// This method could be called multiple times, in that case
/// multiple routes would be registered for same resource path.
/// ///
/// ```rust /// ```rust
/// # extern crate actix_web; /// # extern crate actix_web;
@ -272,23 +280,25 @@ impl<S> App<S> where S: 'static {
self self
} }
/// Configure resource for specific path. /// Configure resource for a specific path.
/// ///
/// Resource may have variable path also. For instance, a resource with /// Resources may have variable path segments. For example, a
/// the path */a/{name}/c* would match all incoming requests with paths /// resource with the path `/a/{name}/c` would match all incoming
/// such as */a/b/c*, */a/1/c*, and */a/etc/c*. /// requests with paths such as `/a/b/c`, `/a/1/c`, or `/a/etc/c`.
/// ///
/// A variable part is specified in the form `{identifier}`, where /// A variable segment is specified in the form `{identifier}`,
/// the identifier can be used later in a request handler to access the matched /// where the identifier can be used later in a request handler to
/// value for that part. This is done by looking up the identifier /// access the matched value for that segment. This is done by
/// in the `Params` object returned by `HttpRequest.match_info()` method. /// looking up the identifier in the `Params` object returned by
/// `HttpRequest.match_info()` method.
/// ///
/// By default, each part matches the regular expression `[^{}/]+`. /// By default, each segment matches the regular expression `[^{}/]+`.
/// ///
/// You can also specify a custom regex in the form `{identifier:regex}`: /// 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 /// For instance, to route `GET`-requests on any route matching
/// store userid and friend in the exposed Params object: /// `/users/{userid}/{friend}` and store `userid` and `friend` in
/// the exposed `Params` object:
/// ///
/// ```rust /// ```rust
/// # extern crate actix_web; /// # extern crate actix_web;
@ -318,7 +328,8 @@ impl<S> App<S> where S: 'static {
self self
} }
/// Default resource is used if no matched route could be found. /// Default resource to be used if no matching route could be
/// found.
pub fn default_resource<F, R>(mut self, f: F) -> App<S> pub fn default_resource<F, R>(mut self, f: F) -> App<S>
where F: FnOnce(&mut ResourceHandler<S>) -> R + 'static where F: FnOnce(&mut ResourceHandler<S>) -> R + 'static
{ {
@ -339,11 +350,11 @@ impl<S> App<S> where S: 'static {
self self
} }
/// Register external resource. /// Register an external resource.
/// ///
/// External resources are useful for URL generation purposes only and /// External resources are useful for URL generation purposes only
/// are never considered for matching at request time. /// and are never considered for matching at request time. Calls to
/// Call to `HttpRequest::url_for()` will work as expected. /// `HttpRequest::url_for()` will work as expected.
/// ///
/// ```rust /// ```rust
/// # extern crate actix_web; /// # extern crate actix_web;
@ -380,9 +391,10 @@ impl<S> App<S> where S: 'static {
/// Configure handler for specific path prefix. /// Configure handler for specific path prefix.
/// ///
/// Path prefix consists valid path segments. i.e for prefix `/app` /// A path prefix consists of valid path segments, i.e for the
/// any request with following paths `/app`, `/app/` or `/app/test` /// prefix `/app` any request with the paths `/app`, `/app/` or
/// would match, but path `/application` would not match. /// `/app/test` would match, but the path `/application` would
/// not.
/// ///
/// ```rust /// ```rust
/// # extern crate actix_web; /// # extern crate actix_web;
@ -408,18 +420,19 @@ impl<S> App<S> where S: 'static {
self self
} }
/// Register a middleware /// Register a middleware.
pub fn middleware<M: Middleware<S>>(mut self, mw: M) -> App<S> { pub fn middleware<M: Middleware<S>>(mut self, mw: M) -> App<S> {
self.parts.as_mut().expect("Use after finish") self.parts.as_mut().expect("Use after finish")
.middlewares.push(Box::new(mw)); .middlewares.push(Box::new(mw));
self self
} }
/// Run external configuration as part of application building process /// Run external configuration as part of the application building
/// process
/// ///
/// This function is useful for moving part of configuration to a different /// This function is useful for moving parts of configuration to a
/// module or event library. For example we can move some of the resources /// different module or event library. For example we can move
/// configuration to different module. /// some of the resources' configuration to different module.
/// ///
/// ```rust /// ```rust
/// # extern crate actix_web; /// # extern crate actix_web;
@ -447,7 +460,7 @@ impl<S> App<S> where S: 'static {
cfg(self) cfg(self)
} }
/// Finish application configuration and create HttpHandler object /// Finish application configuration and create `HttpHandler` object.
pub fn finish(&mut self) -> HttpApplication<S> { pub fn finish(&mut self) -> HttpApplication<S> {
let parts = self.parts.take().expect("Use after finish"); let parts = self.parts.take().expect("Use after finish");
let prefix = parts.prefix.trim().trim_right_matches('/'); let prefix = parts.prefix.trim().trim_right_matches('/');
@ -478,10 +491,10 @@ impl<S> App<S> where S: 'static {
} }
} }
/// Convenience method for creating `Box<HttpHandler>` instance. /// Convenience method for creating `Box<HttpHandler>` instances.
/// ///
/// This method is useful if you need to register multiple application instances /// This method is useful if you need to register multiple
/// with different state. /// application instances with different state.
/// ///
/// ```rust /// ```rust
/// # use std::thread; /// # use std::thread;

46
src/client/connector.rs
View file

@ -33,8 +33,8 @@ use server::IoStream;
#[derive(Debug)] #[derive(Debug)]
/// `Connect` type represents message that can be send to `ClientConnector` /// `Connect` type represents a message that can be sent to
/// with connection request. /// `ClientConnector` with a connection request.
pub struct Connect { pub struct Connect {
pub(crate) uri: Uri, pub(crate) uri: Uri,
pub(crate) wait_timeout: Duration, pub(crate) wait_timeout: Duration,
@ -51,16 +51,16 @@ impl Connect {
}) })
} }
/// Connection timeout, max time to connect to remote host. /// Connection timeout, i.e. max time to connect to remote host.
/// By default connect timeout is 1 seccond. /// Set to 1 second by default.
pub fn conn_timeout(mut self, timeout: Duration) -> Self { pub fn conn_timeout(mut self, timeout: Duration) -> Self {
self.conn_timeout = timeout; self.conn_timeout = timeout;
self self
} }
/// If connection pool limits are enabled, wait time indicates /// If connection pool limits are enabled, wait time indicates
/// max time to wait for available connection. /// max time to wait for a connection to become available.
/// By default wait timeout is 5 secconds. /// Set to 5 seconds by default.
pub fn wait_timeout(mut self, timeout: Duration) -> Self { pub fn wait_timeout(mut self, timeout: Duration) -> Self {
self.wait_timeout = timeout; self.wait_timeout = timeout;
self self
@ -99,11 +99,11 @@ impl Message for Pause {
#[derive(Message)] #[derive(Message)]
pub struct Resume; pub struct Resume;
/// A set of errors that can occur during connecting to a http host /// A set of errors that can occur while connecting to an HTTP host
#[derive(Fail, Debug)] #[derive(Fail, Debug)]
pub enum ClientConnectorError { pub enum ClientConnectorError {
/// Invalid url /// Invalid URL
#[fail(display="Invalid url")] #[fail(display="Invalid URL")]
InvalidUrl, InvalidUrl,
/// SSL feature is not enabled /// SSL feature is not enabled
@ -125,14 +125,14 @@ pub enum ClientConnectorError {
Connector(#[cause] ConnectorError), Connector(#[cause] ConnectorError),
/// Connection took too long /// Connection took too long
#[fail(display = "Timeout out while establishing connection")] #[fail(display = "Timeout while establishing connection")]
Timeout, Timeout,
/// Connector has been disconnected /// Connector has been disconnected
#[fail(display = "Internal error: connector has been disconnected")] #[fail(display = "Internal error: connector has been disconnected")]
Disconnected, Disconnected,
/// Connection io error /// Connection IO error
#[fail(display = "{}", _0)] #[fail(display = "{}", _0)]
IoError(#[cause] io::Error), IoError(#[cause] io::Error),
} }
@ -152,8 +152,8 @@ struct Waiter {
conn_timeout: Duration, conn_timeout: Duration,
} }
/// `ClientConnector` type is responsible for transport layer of a client connection /// `ClientConnector` type is responsible for transport layer of a
/// of a client connection. /// client connection.
pub struct ClientConnector { pub struct ClientConnector {
#[cfg(all(feature="alpn"))] #[cfg(all(feature="alpn"))]
connector: SslConnector, connector: SslConnector,
@ -242,9 +242,9 @@ impl ClientConnector {
#[cfg(feature="alpn")] #[cfg(feature="alpn")]
/// Create `ClientConnector` actor with custom `SslConnector` instance. /// Create `ClientConnector` actor with custom `SslConnector` instance.
/// ///
/// By default `ClientConnector` uses very simple ssl configuration. /// By default `ClientConnector` uses very a simple SSL configuration.
/// With `with_connector` method it is possible to use custom `SslConnector` /// With `with_connector` method it is possible to use a custom
/// object. /// `SslConnector` object.
/// ///
/// ```rust /// ```rust
/// # #![cfg(feature="alpn")] /// # #![cfg(feature="alpn")]
@ -313,7 +313,7 @@ impl ClientConnector {
/// Set total number of simultaneous connections to the same endpoint. /// Set total number of simultaneous connections to the same endpoint.
/// ///
/// Endpoints are the same if they are have equal (host, port, ssl) triplet. /// Endpoints are the same if they have equal (host, port, ssl) triplets.
/// If limit is 0, the connector has no limit. The default limit size is 0. /// If limit is 0, the connector has no limit. The default limit size is 0.
pub fn limit_per_host(mut self, limit: usize) -> Self { pub fn limit_per_host(mut self, limit: usize) -> Self {
self.limit_per_host = limit; self.limit_per_host = limit;
@ -322,9 +322,9 @@ impl ClientConnector {
/// Set keep-alive period for opened connection. /// Set keep-alive period for opened connection.
/// ///
/// Keep-alive period is period between connection usage. /// Keep-alive period is the period between connection usage. If
/// if deley between connection usage exceeds this period /// the delay between repeated usages of the same connection
/// connection closes. /// exceeds this period, the connection is closed.
pub fn conn_keep_alive(mut self, dur: Duration) -> Self { pub fn conn_keep_alive(mut self, dur: Duration) -> Self {
self.conn_keep_alive = dur; self.conn_keep_alive = dur;
self self
@ -333,7 +333,7 @@ impl ClientConnector {
/// Set max lifetime period for connection. /// Set max lifetime period for connection.
/// ///
/// Connection lifetime is max lifetime of any opened connection /// Connection lifetime is max lifetime of any opened connection
/// until it get closed regardless of keep-alive period. /// until it is closed regardless of keep-alive period.
pub fn conn_lifetime(mut self, dur: Duration) -> Self { pub fn conn_lifetime(mut self, dur: Duration) -> Self {
self.conn_lifetime = dur; self.conn_lifetime = dur;
self self
@ -514,7 +514,7 @@ impl ClientConnector {
self.install_wait_timeout(next.unwrap()); self.install_wait_timeout(next.unwrap());
} }
} }
fn install_wait_timeout(&mut self, time: Instant) { fn install_wait_timeout(&mut self, time: Instant) {
if let Some(ref mut wait) = self.wait_timeout { if let Some(ref mut wait) = self.wait_timeout {
if wait.0 < time { if wait.0 < time {
@ -601,7 +601,7 @@ impl Handler<Connect> for ClientConnector {
if self.pool.task.borrow().is_none() { if self.pool.task.borrow().is_none() {
*self.pool.task.borrow_mut() = Some(current_task()); *self.pool.task.borrow_mut() = Some(current_task());
} }
let host = uri.host().unwrap().to_owned(); let host = uri.host().unwrap().to_owned();
let port = uri.port().unwrap_or_else(|| proto.port()); let port = uri.port().unwrap_or_else(|| proto.port());
let key = Key {host, port, ssl: proto.is_secure()}; let key = Key {host, port, ssl: proto.is_secure()};

13
src/client/mod.rs
View file

@ -1,4 +1,4 @@
//! Http client //! HTTP client
mod connector; mod connector;
mod parser; mod parser;
mod request; mod request;
@ -22,7 +22,6 @@ use httpresponse::HttpResponse;
/// Convert `SendRequestError` to a `HttpResponse` /// Convert `SendRequestError` to a `HttpResponse`
impl ResponseError for SendRequestError { impl ResponseError for SendRequestError {
fn error_response(&self) -> HttpResponse { fn error_response(&self) -> HttpResponse {
match *self { match *self {
SendRequestError::Connector(_) => HttpResponse::BadGateway(), SendRequestError::Connector(_) => HttpResponse::BadGateway(),
@ -32,7 +31,7 @@ impl ResponseError for SendRequestError {
} }
} }
/// Create request builder for `GET` request /// Create request builder for `GET` requests
/// ///
/// ```rust /// ```rust
/// # extern crate actix; /// # extern crate actix;
@ -66,28 +65,28 @@ pub fn get<U: AsRef<str>>(uri: U) -> ClientRequestBuilder {
builder builder
} }
/// Create request builder for `HEAD` request /// Create request builder for `HEAD` requests
pub fn head<U: AsRef<str>>(uri: U) -> ClientRequestBuilder { pub fn head<U: AsRef<str>>(uri: U) -> ClientRequestBuilder {
let mut builder = ClientRequest::build(); let mut builder = ClientRequest::build();
builder.method(Method::HEAD).uri(uri); builder.method(Method::HEAD).uri(uri);
builder builder
} }
/// Create request builder for `POST` request /// Create request builder for `POST` requests
pub fn post<U: AsRef<str>>(uri: U) -> ClientRequestBuilder { pub fn post<U: AsRef<str>>(uri: U) -> ClientRequestBuilder {
let mut builder = ClientRequest::build(); let mut builder = ClientRequest::build();
builder.method(Method::POST).uri(uri); builder.method(Method::POST).uri(uri);
builder builder
} }
/// Create request builder for `PUT` request /// Create request builder for `PUT` requests
pub fn put<U: AsRef<str>>(uri: U) -> ClientRequestBuilder { pub fn put<U: AsRef<str>>(uri: U) -> ClientRequestBuilder {
let mut builder = ClientRequest::build(); let mut builder = ClientRequest::build();
builder.method(Method::PUT).uri(uri); builder.method(Method::PUT).uri(uri);
builder builder
} }
/// Create request builder for `DELETE` request /// Create request builder for `DELETE` requests
pub fn delete<U: AsRef<str>>(uri: U) -> ClientRequestBuilder { pub fn delete<U: AsRef<str>>(uri: U) -> ClientRequestBuilder {
let mut builder = ClientRequest::build(); let mut builder = ClientRequest::build();
builder.method(Method::DELETE).uri(uri); builder.method(Method::DELETE).uri(uri);

9
src/client/pipeline.rs
View file

@ -22,11 +22,11 @@ use super::{Connect, Connection, ClientConnector, ClientConnectorError};
use super::HttpClientWriter; use super::HttpClientWriter;
use super::{HttpResponseParser, HttpResponseParserError}; use super::{HttpResponseParser, HttpResponseParserError};
/// A set of errors that can occur during sending request and reading response /// A set of errors that can occur during request sending and response reading
#[derive(Fail, Debug)] #[derive(Fail, Debug)]
pub enum SendRequestError { pub enum SendRequestError {
/// Response took too long /// Response took too long
#[fail(display = "Timeout out while waiting for response")] #[fail(display = "Timeout while waiting for response")]
Timeout, Timeout,
/// Failed to connect to host /// Failed to connect to host
#[fail(display="Failed to connect to host: {}", _0)] #[fail(display="Failed to connect to host: {}", _0)]
@ -62,7 +62,8 @@ enum State {
None, None,
} }
/// `SendRequest` is a `Future` which represents asynchronous sending process. /// `SendRequest` is a `Future` which represents an asynchronous
/// request sending process.
#[must_use = "SendRequest does nothing unless polled"] #[must_use = "SendRequest does nothing unless polled"]
pub struct SendRequest { pub struct SendRequest {
req: ClientRequest, req: ClientRequest,
@ -102,7 +103,7 @@ impl SendRequest {
/// Set request timeout /// Set request timeout
/// ///
/// Request timeout is a total time before response should be received. /// Request timeout is the total time before a response must be received.
/// Default value is 5 seconds. /// Default value is 5 seconds.
pub fn timeout(mut self, timeout: Duration) -> Self { pub fn timeout(mut self, timeout: Duration) -> Self {
self.timeout = Some(Timeout::new(timeout, Arbiter::handle()).unwrap()); self.timeout = Some(Timeout::new(timeout, Arbiter::handle()).unwrap());

34
src/client/request.rs
View file

@ -146,13 +146,13 @@ impl ClientRequest {
source.into() source.into()
} }
/// Get the request uri /// Get the request URI
#[inline] #[inline]
pub fn uri(&self) -> &Uri { pub fn uri(&self) -> &Uri {
&self.uri &self.uri
} }
/// Set client request uri /// Set client request URI
#[inline] #[inline]
pub fn set_uri(&mut self, uri: Uri) { pub fn set_uri(&mut self, uri: Uri) {
self.uri = uri self.uri = uri
@ -164,13 +164,13 @@ impl ClientRequest {
&self.method &self.method
} }
/// Set http `Method` for the request /// Set HTTP `Method` for the request
#[inline] #[inline]
pub fn set_method(&mut self, method: Method) { pub fn set_method(&mut self, method: Method) {
self.method = method self.method = method
} }
/// Get http version for the request /// Get HTTP version for the request
#[inline] #[inline]
pub fn version(&self) -> Version { pub fn version(&self) -> Version {
self.version self.version
@ -222,8 +222,8 @@ impl ClientRequest {
pub fn write_buffer_capacity(&self) -> usize { pub fn write_buffer_capacity(&self) -> usize {
self.buffer_capacity self.buffer_capacity
} }
/// Get body os this response /// Get body of this response
#[inline] #[inline]
pub fn body(&self) -> &Body { pub fn body(&self) -> &Body {
&self.body &self.body
@ -234,14 +234,14 @@ impl ClientRequest {
self.body = body.into(); self.body = body.into();
} }
/// Extract body, replace it with Empty /// Extract body, replace it with `Empty`
pub(crate) fn replace_body(&mut self, body: Body) -> Body { pub(crate) fn replace_body(&mut self, body: Body) -> Body {
mem::replace(&mut self.body, body) mem::replace(&mut self.body, body)
} }
/// Send request /// Send request
/// ///
/// This method returns future that resolves to a ClientResponse /// This method returns a future that resolves to a ClientResponse
pub fn send(mut self) -> SendRequest { pub fn send(mut self) -> SendRequest {
let timeout = self.timeout.take(); let timeout = self.timeout.take();
let send = match mem::replace(&mut self.conn, ConnectionType::Default) { let send = match mem::replace(&mut self.conn, ConnectionType::Default) {
@ -281,7 +281,7 @@ pub struct ClientRequestBuilder {
} }
impl ClientRequestBuilder { impl ClientRequestBuilder {
/// Set HTTP uri of request. /// Set HTTP URI of request.
#[inline] #[inline]
pub fn uri<U: AsRef<str>>(&mut self, uri: U) -> &mut Self { pub fn uri<U: AsRef<str>>(&mut self, uri: U) -> &mut Self {
match Url::parse(uri.as_ref()) { match Url::parse(uri.as_ref()) {
@ -325,7 +325,7 @@ impl ClientRequestBuilder {
/// Set HTTP version of this request. /// Set HTTP version of this request.
/// ///
/// By default requests's http version depends on network stream /// By default requests's HTTP version depends on network stream
#[inline] #[inline]
pub fn version(&mut self, version: Version) -> &mut Self { pub fn version(&mut self, version: Version) -> &mut Self {
if let Some(parts) = parts(&mut self.request, &self.err) { if let Some(parts) = parts(&mut self.request, &self.err) {
@ -364,7 +364,7 @@ impl ClientRequestBuilder {
/// Append a header. /// Append a header.
/// ///
/// Header get appended to existing header. /// Header gets appended to existing header.
/// To override header use `set_header()` method. /// To override header use `set_header()` method.
/// ///
/// ```rust /// ```rust
@ -540,7 +540,7 @@ impl ClientRequestBuilder {
self self
} }
/// Send request using existing Connection /// Send request using existing `Connection`
pub fn with_connection(&mut self, conn: Connection) -> &mut Self { pub fn with_connection(&mut self, conn: Connection) -> &mut Self {
if let Some(parts) = parts(&mut self.request, &self.err) { if let Some(parts) = parts(&mut self.request, &self.err) {
parts.conn = ConnectionType::Connection(conn); parts.conn = ConnectionType::Connection(conn);
@ -548,7 +548,8 @@ impl ClientRequestBuilder {
self self
} }
/// This method calls provided closure with builder reference if value is true. /// This method calls provided closure with builder reference if
/// value is `true`.
pub fn if_true<F>(&mut self, value: bool, f: F) -> &mut Self pub fn if_true<F>(&mut self, value: bool, f: F) -> &mut Self
where F: FnOnce(&mut ClientRequestBuilder) where F: FnOnce(&mut ClientRequestBuilder)
{ {
@ -558,7 +559,8 @@ impl ClientRequestBuilder {
self self
} }
/// This method calls provided closure with builder reference if value is Some. /// This method calls provided closure with builder reference if
/// value is `Some`.
pub fn if_some<T, F>(&mut self, value: Option<T>, f: F) -> &mut Self pub fn if_some<T, F>(&mut self, value: Option<T>, f: F) -> &mut Self
where F: FnOnce(T, &mut ClientRequestBuilder) where F: FnOnce(T, &mut ClientRequestBuilder)
{ {
@ -610,7 +612,7 @@ impl ClientRequestBuilder {
Ok(request) Ok(request)
} }
/// Set a json body and generate `ClientRequest` /// Set a JSON body and generate `ClientRequest`
/// ///
/// `ClientRequestBuilder` can not be used after this call. /// `ClientRequestBuilder` can not be used after this call.
pub fn json<T: Serialize>(&mut self, value: T) -> Result<ClientRequest, Error> { pub fn json<T: Serialize>(&mut self, value: T) -> Result<ClientRequest, Error> {
@ -685,7 +687,7 @@ impl fmt::Debug for ClientRequestBuilder {
/// Create `ClientRequestBuilder` from `HttpRequest` /// Create `ClientRequestBuilder` from `HttpRequest`
/// ///
/// It is useful for proxy requests. This implementation /// It is useful for proxy requests. This implementation
/// copies all request's headers and method. /// copies all request headers and the method.
impl<'a, S: 'static> From<&'a HttpRequest<S>> for ClientRequestBuilder { impl<'a, S: 'static> From<&'a HttpRequest<S>> for ClientRequestBuilder {
fn from(req: &'a HttpRequest<S>) -> ClientRequestBuilder { fn from(req: &'a HttpRequest<S>) -> ClientRequestBuilder {
let mut builder = ClientRequest::build(); let mut builder = ClientRequest::build();

32
src/lib.rs
View file

@ -1,4 +1,5 @@
//! Actix web is a small, pragmatic, extremely fast, web framework for Rust. //! Actix web is a small, pragmatic, and extremely fast web framework
//! for Rust.
//! //!
//! ```rust //! ```rust
//! use actix_web::{server, App, Path}; //! use actix_web::{server, App, Path};
@ -19,13 +20,31 @@
//! } //! }
//! ``` //! ```
//! //!
//! ## Documentation //! ## Documentation & community resources
//!
//! Besides the API documentation (which you are currently looking
//! at!), several other resources are available:
//! //!
//! * [User Guide](http://actix.github.io/actix-web/guide/) //! * [User Guide](http://actix.github.io/actix-web/guide/)
//! * [Chat on gitter](https://gitter.im/actix/actix) //! * [Chat on gitter](https://gitter.im/actix/actix)
//! * [GitHub repository](https://github.com/actix/actix-web) //! * [GitHub repository](https://github.com/actix/actix-web)
//! * [Cargo package](https://crates.io/crates/actix-web) //! * [Cargo package](https://crates.io/crates/actix-web)
//! * Supported Rust version: 1.21 or later //!
//! To get started navigating the API documentation you may want to
//! consider looking at the following pages:
//!
//! * [App](struct.App.html): This struct represents an actix-web
//! application and is used to configure routes and other common
//! settings.
//!
//! * [HttpServer](server/struct.HttpServer.html): This struct
//! represents an HTTP server instance and is used to instantiate and
//! configure servers.
//!
//! * [HttpRequest](struct.HttpRequest.html) and
//! [HttpResponse](struct.HttpResponse.html): These structs
//! represent HTTP requests and responses and expose various methods
//! for inspecting, creating and otherwise utilising them.
//! //!
//! ## Features //! ## Features
//! //!
@ -37,9 +56,10 @@
//! * Configurable request routing //! * Configurable request routing
//! * Graceful server shutdown //! * Graceful server shutdown
//! * Multipart streams //! * Multipart streams
//! * SSL support with openssl or native-tls //! * SSL support with OpenSSL or `native-tls`
//! * Middlewares (`Logger`, `Session`, `CORS`, `CSRF`, `DefaultHeaders`) //! * Middlewares (`Logger`, `Session`, `CORS`, `CSRF`, `DefaultHeaders`)
//! * Built on top of [Actix actor framework](https://github.com/actix/actix). //! * Built on top of [Actix actor framework](https://github.com/actix/actix)
//! * Supported Rust version: 1.21 or later
#![cfg_attr(actix_nightly, feature( #![cfg_attr(actix_nightly, feature(
specialization, // for impl ErrorResponse for std::error::Error specialization, // for impl ErrorResponse for std::error::Error
@ -189,7 +209,7 @@ pub mod dev {
} }
pub mod http { pub mod http {
//! Various http related types //! Various HTTP related types
// re-exports // re-exports
pub use modhttp::{Method, StatusCode, Version}; pub use modhttp::{Method, StatusCode, Version};