mirrors/actix-web
1
0
Fork 0
mirror of https://github.com/actix/actix-web.git synced 2024-10-21 09:23:54 +00:00
Code Issues Projects Releases Wiki Activity

docs(client): Minor formatting and spelling fixes in module docs

Browse source
This commit is contained in:
Vincent Ambo 2018-04-07 17:00:57 +02:00
parent 1045a6c6f0
commit 38063b9873
4 changed files with 52 additions and 50 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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();