Request: HTTP Request Handling
In reqres: Powerful Classes for HTTP Requests and Responses
Request R Documentation
HTTP Request Handling
Description
This class wraps all functionality related to extracting information from a
http request. Much of the functionality is inspired by the Request class in
Express.js, so the documentation
for this will complement this document. As reqres is build on top of the
Rook specifications
the Request object is initialized from a Rook-compliant object. This will
often be the request object provided by the httpuv framework. While it
shouldn't be needed, the original Rook object is always accessible and can be
modified, though any modifications will not propagate to derived values in
the Request object (e.g. changing the HTTP_HOST element of the Rook
object will not change the host field of the Request object). Because of
this, direct manipulation of the Rook object is generally discouraged.
Usage
as.Request(x, ...)
is.Request(x)
Arguments
x
An object coercible to a Request.
...
Parameters passed on to Request$new()
Value
A Request object (for as.Request()) or a logical indicating whether
the object is a Request (for is.Request())
Initialization
A new 'Request'-object is initialized using the new() method on the
generator:
Usage
req <- Request$new(rook, trust = FALSE)
Arguments
rook The rook request that the new object should wrap
trust Is this request trusted blindly. If TRUE X-Forwarded-* headers will be returned when querying host, ip, and protocol
Fields
The following fields are accessible in a Request object:
trustA logical indicating whether the request is trusted. Mutable
methodA string indicating the request method (in lower case, e.g.
'get', 'put', etc.). Immutable
bodyAn object holding the body of the request. This is an empty
string by default and needs to be populated using the set_body() method
(this is often done using a body parser that accesses the Rook$input
stream). Immutable
cookiesAccess a named list of all cookies in the request. These
have been URI decoded. Immutable
headersAccess a named list of all headers in the request. In order
to follow R variable naming standards - have been substituted with _.
Use the get_header() method to lookup based on the correct header name.
Immutable
hostReturn the domain of the server given by the "Host" header if
trust == FALSE. If trust == true returns the X-Forwarded-Host instead.
ipReturns the remote address of the request if trust == FALSE.
if trust == TRUE it will instead return the first value of the
X-Forwarded-For header. Immutable
ipsIf trust == TRUE it will return the full list of ips in the
X-Forwarded-For header. If trust == FALSE it will return an empty
vector. Immutable
protocolReturns the protocol (e.g. 'http') used for the request.
If trust == TRUE it will use the value of the X-Forwarded-Proto header.
Immutable
rootThe mount point of the application receiving this request. Can
be empty if the application is mounted on the server root. Immutable
pathThe part of the url following the root. Defines the local
target of the request (independent of where it is mounted). Immutable
urlThe full URL of the request. Immutable
queryThe query string of the request (anything following "?" in
the URL) parsed into a named list. The query has been url decoded and "+"
has been substituted with space. Multiple queries are expected to be
separated by either "&" or "|". Immutable
querystringThe unparsed query string of the request, including
"?". If no query string exists it will be "" rather than "?"
xhrA logical indicating whether the X-Requested-With header
equals XMLHttpRequest thus indicating that the request was performed using
a JavaScript library such as jQuery. Immutable
secureA logical indicating whether the request was performed using
a secure connection, i.e. protocol == 'https'. Immutable
originThe original object used to create the Request object. As
reqres currently only works with rook this will always return the original
rook object. Immutable, though the content of the rook object itself might
be manipulated as it is an environment.
responseIf a Response object has been created for this request
it is accessible through this field. Immutable
Methods
The following methods are available in a Request object:
set_body(content)Sets the content of the request body. This method
should mainly be used in concert with a body parser that reads the
rook$input stream
set_cookies(cookies)Sets the cookies of the request. The cookies
are automatically parsed and populated, so this method is mainly available
to facilitate cookie signing and encryption
get_header(name)Get the header of the specified name.
accepts(types)Given a vector of response content types it returns
the preferred one based on the Accept header.
accepts_charsets(charsets)Given a vector of possible character
encodings it returns the preferred one based on the Accept-Charset
header.
accepts_encoding(encoding)Given a vector of possible content
encodings (usually compression algorithms) it selects the preferred one
based on the Accept-Encoding header. If there is no match it will return
"identity" signaling no compression.
accepts_language(language)Given a vector of possible content
languages it selects the best one based on the Accept-Language header.
is(type)Queries whether the body of the request is in a given
format by looking at the Content-Type header. Used for selecting the best
parsing method.
respond()Creates a new Response object from the request
parse(..., autofail = TRUE)Based on provided parsers it selects
the appropriate one by looking at the Content-Type header and assigns the
result to the request body. A parser is a function accepting a raw vector,
and a named list of additional directives,
and returns an R object of any kind (if the parser knows the input to be
plain text, simply wrap it in rawToChar()). If the body is compressed, it
will be decompressed based on the Content-Encoding header prior to passing
it on to the parser. See parsers for a list of pre-supplied parsers.
Parsers are either supplied in a named list or as named arguments to the
parse method. The names should correspond to mime types or known file
extensions. If autofail = TRUE the response will be set with the correct
error code if parsing fails. parse() returns TRUE if parsing was
successful and FALSE if not
parse_raw(autofail = TRUE)This is a simpler version of the
parse() method. It will attempt to decompress the body and set the body
field to the resulting raw vector. It is then up to the server to decide how
to handle the payload. It returns TRUE if successful and FALSE
otherwise.
as_message()Prints a HTTP representation of the request to the
output stream.
Methods
Public methods
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Method new()
Usage
Request$new(rook, trust = FALSE)
Method print()
Usage
Request$print(...)
Method set_body()
Usage
Request$set_body(content)
Method set_cookies()
Usage
Request$set_cookies(cookies)
Method accepts()
Usage
Request$accepts(types)
Method accepts_charsets()
Usage
Request$accepts_charsets(charsets)
Method accepts_encoding()
Usage
Request$accepts_encoding(encoding)
Method accepts_language()
Usage
Request$accepts_language(language)
Method is()
Usage
Request$is(type)
Method get_header()
Usage
Request$get_header(name)
Method respond()
Usage
Request$respond()
Method parse()
Usage
Request$parse(..., autofail = TRUE)
Method parse_raw()
Usage
Request$parse_raw(autofail = TRUE)
Method as_message()
Usage
Request$as_message()
Method clone()
The objects of this class are cloneable with this method.
Usage
Request$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
See Also
Response for handling http responses
Examples
fake_rook <- fiery::fake_request(
'http://example.com/test?id=34632&question=who+is+hadley',
content = 'This is an elaborate ruse',
headers = list(
Accept = 'application/json; text/*',
Content_Type = 'text/plain'
)
)
req <- Request$new(fake_rook)
# Get full URL
req$url
# Get list of query parameters
req$query
# Test if content is text
req$is('txt')
# Perform content negotiation for the response
req$accepts(c('html', 'json', 'txt'))
# Cleaning up connections
rm(fake_rook, req)
gc()
reqres documentation built on Aug. 19, 2022, 5:18 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| Request | R Documentation |
HTTP Request Handling
Description
This class wraps all functionality related to extracting information from a
http request. Much of the functionality is inspired by the Request class in
Express.js, so the documentation
for this will complement this document. As reqres is build on top of the
Rook specifications
the Request object is initialized from a Rook-compliant object. This will
often be the request object provided by the httpuv framework. While it
shouldn't be needed, the original Rook object is always accessible and can be
modified, though any modifications will not propagate to derived values in
the Request object (e.g. changing the HTTP_HOST element of the Rook
object will not change the host field of the Request object). Because of
this, direct manipulation of the Rook object is generally discouraged.
Usage
as.Request(x, ...) is.Request(x)
Arguments
x |
An object coercible to a |
... |
Parameters passed on to |
Value
A Request object (for as.Request()) or a logical indicating whether
the object is a Request (for is.Request())
Initialization
A new 'Request'-object is initialized using the new() method on the
generator:
Usage
req <- Request$new(rook, trust = FALSE)
|
Arguments
rook | The rook request that the new object should wrap | |
trust | Is this request trusted blindly. If TRUE X-Forwarded-* headers will be returned when querying host, ip, and protocol
|
Fields
The following fields are accessible in a Request object:
trustA logical indicating whether the request is trusted. Mutable
methodA string indicating the request method (in lower case, e.g. 'get', 'put', etc.). Immutable
bodyAn object holding the body of the request. This is an empty string by default and needs to be populated using the
set_body()method (this is often done using a body parser that accesses the Rook$input stream). ImmutablecookiesAccess a named list of all cookies in the request. These have been URI decoded. Immutable
headersAccess a named list of all headers in the request. In order to follow R variable naming standards
-have been substituted with_. Use theget_header()method to lookup based on the correct header name. ImmutablehostReturn the domain of the server given by the "Host" header if
trust == FALSE. Iftrust == truereturns theX-Forwarded-Hostinstead.ipReturns the remote address of the request if
trust == FALSE. iftrust == TRUEit will instead return the first value of theX-Forwarded-Forheader. ImmutableipsIf
trust == TRUEit will return the full list of ips in theX-Forwarded-Forheader. Iftrust == FALSEit will return an empty vector. ImmutableprotocolReturns the protocol (e.g. 'http') used for the request. If
trust == TRUEit will use the value of theX-Forwarded-Protoheader. ImmutablerootThe mount point of the application receiving this request. Can be empty if the application is mounted on the server root. Immutable
pathThe part of the url following the root. Defines the local target of the request (independent of where it is mounted). Immutable
urlThe full URL of the request. Immutable
queryThe query string of the request (anything following "?" in the URL) parsed into a named list. The query has been url decoded and "+" has been substituted with space. Multiple queries are expected to be separated by either "&" or "|". Immutable
querystringThe unparsed query string of the request, including "?". If no query string exists it will be
""rather than"?"xhrA logical indicating whether the
X-Requested-Withheader equalsXMLHttpRequestthus indicating that the request was performed using a JavaScript library such as jQuery. ImmutablesecureA logical indicating whether the request was performed using a secure connection, i.e.
protocol == 'https'. ImmutableoriginThe original object used to create the
Requestobject. Asreqrescurrently only works with rook this will always return the original rook object. Immutable, though the content of the rook object itself might be manipulated as it is an environment.responseIf a
Responseobject has been created for this request it is accessible through this field. Immutable
Methods
The following methods are available in a Request object:
set_body(content)Sets the content of the request body. This method should mainly be used in concert with a body parser that reads the
rook$inputstreamset_cookies(cookies)Sets the cookies of the request. The cookies are automatically parsed and populated, so this method is mainly available to facilitate cookie signing and encryption
get_header(name)Get the header of the specified name.
accepts(types)Given a vector of response content types it returns the preferred one based on the
Acceptheader.accepts_charsets(charsets)Given a vector of possible character encodings it returns the preferred one based on the
Accept-Charsetheader.accepts_encoding(encoding)Given a vector of possible content encodings (usually compression algorithms) it selects the preferred one based on the
Accept-Encodingheader. If there is no match it will return"identity"signaling no compression.accepts_language(language)Given a vector of possible content languages it selects the best one based on the
Accept-Languageheader.is(type)Queries whether the body of the request is in a given format by looking at the
Content-Typeheader. Used for selecting the best parsing method.respond()Creates a new
Responseobject from the requestparse(..., autofail = TRUE)Based on provided parsers it selects the appropriate one by looking at the
Content-Typeheader and assigns the result to the request body. A parser is a function accepting a raw vector, and a named list of additional directives, and returns an R object of any kind (if the parser knows the input to be plain text, simply wrap it inrawToChar()). If the body is compressed, it will be decompressed based on theContent-Encodingheader prior to passing it on to the parser. See parsers for a list of pre-supplied parsers. Parsers are either supplied in a named list or as named arguments to the parse method. The names should correspond to mime types or known file extensions. Ifautofail = TRUEthe response will be set with the correct error code if parsing fails.parse()returnsTRUEif parsing was successful andFALSEif notparse_raw(autofail = TRUE)This is a simpler version of the
parse()method. It will attempt to decompress the body and set thebodyfield to the resulting raw vector. It is then up to the server to decide how to handle the payload. It returnsTRUEif successful andFALSEotherwise.as_message()Prints a HTTP representation of the request to the output stream.
Methods
Public methods
Method new()
Usage
Request$new(rook, trust = FALSE)
Method print()
Usage
Request$print(...)
Method set_body()
Usage
Request$set_body(content)
Method set_cookies()
Usage
Request$set_cookies(cookies)
Method accepts()
Usage
Request$accepts(types)
Method accepts_charsets()
Usage
Request$accepts_charsets(charsets)
Method accepts_encoding()
Usage
Request$accepts_encoding(encoding)
Method accepts_language()
Usage
Request$accepts_language(language)
Method is()
Usage
Request$is(type)
Method get_header()
Usage
Request$get_header(name)
Method respond()
Usage
Request$respond()
Method parse()
Usage
Request$parse(..., autofail = TRUE)
Method parse_raw()
Usage
Request$parse_raw(autofail = TRUE)
Method as_message()
Usage
Request$as_message()
Method clone()
The objects of this class are cloneable with this method.
Usage
Request$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
See Also
Response for handling http responses
Examples
fake_rook <- fiery::fake_request(
'http://example.com/test?id=34632&question=who+is+hadley',
content = 'This is an elaborate ruse',
headers = list(
Accept = 'application/json; text/*',
Content_Type = 'text/plain'
)
)
req <- Request$new(fake_rook)
# Get full URL
req$url
# Get list of query parameters
req$query
# Test if content is text
req$is('txt')
# Perform content negotiation for the response
req$accepts(c('html', 'json', 'txt'))
# Cleaning up connections
rm(fake_rook, req)
gc()
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.