Struct actix_web::HttpRequest

pub struct HttpRequest { /* private fields */ }

An incoming request.

Implementations

impl HttpRequest

pub fn head(&self) -> &RequestHead

This method returns reference to the request head

pub fn uri(&self) -> &Uri

Request’s uri.

pub fn full_url(&self) -> Url

Returns request’s original full URL.

Reconstructed URL is best-effort, using connection_info to get forwarded scheme & host.

use actix_web::test::TestRequest;
let req = TestRequest::with_uri("http://10.1.2.3:8443/api?id=4&name=foo")
    .insert_header(("host", "example.com"))
    .to_http_request();

assert_eq!(
    req.full_url().as_str(),
    "http://example.com/api?id=4&name=foo",
);

pub fn method(&self) -> &Method

Read the Request method.

pub fn version(&self) -> Version

Read the Request Version.

pub fn headers(&self) -> &HeaderMap

Returns request’s headers.

pub fn path(&self) -> &str

The target path of this request.

pub fn query_string(&self) -> &str

The query string in the URL.

Example: id=10

pub fn match_info(&self) -> &Path<Url>

Returns a reference to the URL parameters container.

A URL parameter is specified in the form {identifier}, where the identifier can be used later in a request handler to access the matched value for that parameter.

Percent Encoding and URL Parameters

Because each URL parameter is able to capture multiple path segments, none of ["%2F", "%25", "%2B"] found in the request URI are decoded into ["/", "%", "+"] in order to preserve path integrity. If a URL parameter is expected to contain these characters, then it is on the user to decode them or use the web::Path extractor which will decode these special sequences.

pub fn match_pattern(&self) -> Option<String>

The resource definition pattern that matched the path. Useful for logging and metrics.

For example, when a resource with pattern /user/{id}/profile is defined and a call is made to /user/123/profile this function would return Some("/user/{id}/profile").

Returns a None when no resource is fully matched, including default services.

pub fn match_name(&self) -> Option<&str>

The resource name that matched the path. Useful for logging and metrics.

Returns a None when no resource is fully matched, including default services.

pub fn conn_data<T: 'static>(&self) -> Option<&T>

Returns a reference a piece of connection data set in an on-connect callback.

let opt_t = req.conn_data::<PeerCertificate>();

pub fn url_for<U, I>( &self, name: &str, elements: U, ) -> Result<Url, UrlGenerationError>

where U: IntoIterator<Item = I>, I: AsRef<str>,

Generates URL for a named resource.

This substitutes in sequence all URL parameters that appear in the resource itself and in parent scopes, if any.

It is worth noting that the characters ['/', '%'] are not escaped and therefore a single URL parameter may expand into multiple path segments and elements can be percent-encoded beforehand without worrying about double encoding. Any other character that is not valid in a URL path context is escaped using percent-encoding.

Examples

fn index(req: HttpRequest) -> HttpResponse {
    let url = req.url_for("foo", &["1", "2", "3"]); // <- generate URL for "foo" resource
    HttpResponse::Ok().into()
}

let app = App::new()
    .service(web::resource("/test/{one}/{two}/{three}")
         .name("foo")  // <- set resource name so it can be used in `url_for`
         .route(web::get().to(|| HttpResponse::Ok()))
    );

pub fn url_for_static(&self, name: &str) -> Result<Url, UrlGenerationError>

Generate URL for named resource

This method is similar to HttpRequest::url_for() but it can be used for urls that do not contain variable parts.

pub fn resource_map(&self) -> &ResourceMap

Get a reference to a ResourceMap of current application.

pub fn peer_addr(&self) -> Option<SocketAddr>

Returns peer socket address.

Peer address is the directly connected peer’s socket address. If a proxy is used in front of the Actix Web server, then it would be address of this proxy.

For expanded client connection information, use connection_info instead.

Will only return None when called in unit tests unless TestRequest::peer_addr is used.

pub fn connection_info(&self) -> Ref<'_, ConnectionInfo>

Returns connection info for the current request.

The return type, ConnectionInfo, can also be used as an extractor.

Panics

Panics if request’s extensions container is already borrowed.

pub fn app_config(&self) -> &AppConfig

Returns a reference to the application’s connection configuration.

pub fn app_data<T: 'static>(&self) -> Option<&T>

Retrieves a piece of application state.

Extracts any object stored with App::app_data() (or the counterpart methods on Scope and Resource) during application configuration.

Since the Actix Web router layers application data, the returned object will reference the “closest” instance of the type. For example, if an App stores a u32, a nested Scope also stores a u32, and the delegated request handler falls within that Scope, then calling .app_data::<u32>() on an HttpRequest within that handler will return the Scope’s instance. However, using the same router set up and a request that does not get captured by the Scope, .app_data::<u32>() would return the App’s instance.

If the state was stored using the Data wrapper, then it must also be retrieved using this same type.

See also the Data extractor.

Examples

let opt_t: Option<&Data<T>> = req.app_data::<Data<T>>();

pub fn cookies(&self) -> Result<Ref<'_, Vec<Cookie<'static>>>, CookieParseError>

Available on crate feature cookies only.

Load request cookies.

pub fn cookie(&self, name: &str) -> Option<Cookie<'static>>

Available on crate feature cookies only.

Return request cookie.

Trait Implementations

impl Clone for HttpRequest

fn clone(&self) -> HttpRequest

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HttpRequest

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for HttpRequest

fn drop(&mut self)

Executes the destructor for this type.

impl FromRequest for HttpRequest

It is possible to get HttpRequest as an extractor handler parameter

Examples

use actix_web::{web, App, HttpRequest};
use serde::Deserialize;

/// extract `Thing` from request
async fn index(req: HttpRequest) -> String {
   format!("Got thing: {:?}", req)
}

let app = App::new().service(
    web::resource("/users/{first}").route(
        web::get().to(index))
);

type Error = Error

The associated error which can be returned.

type Future = Ready<Result<HttpRequest, Error>>

Future that resolves to a Self.

fn from_request(req: &HttpRequest, _: &mut Payload) -> Self::Future

Create a Self from request parts asynchronously.

fn extract(req: &HttpRequest) -> Self::Future

Create a Self from request head asynchronously.

impl HttpMessage for HttpRequest

type Stream = ()

Type of message payload stream

fn headers(&self) -> &HeaderMap

Read the message headers.

fn extensions(&self) -> Ref<'_, Extensions>

Returns a reference to the request-local data/extensions container.

fn extensions_mut(&self) -> RefMut<'_, Extensions>

Returns a mutable reference to the request-local data/extensions container.

fn take_payload(&mut self) -> Payload<Self::Stream>

Message payload stream

fn content_type(&self) -> &str

Read the request content type. If request did not contain a Content-Type header, an empty string is returned.

fn encoding(&self) -> Result<&'static Encoding, ContentTypeError>

Get content type encoding.

fn mime_type(&self) -> Result<Option<Mime>, ContentTypeError>

Convert the request content type to a known mime type.

fn chunked(&self) -> Result<bool, ParseError>

Check if request has chunked transfer encoding.