Request: HTTP Request Handling
In thomasp85/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)
Active bindings
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
sessionThe content of the session cookie. If session cookies has
not been activated it will be an empty write-protected list. If session
cookies are activated but the request did not contain one it will be an
empty list. The content of this field will be send encrypted as part of
the response according to the cookie settings in
$session_cookie_settings. This field is reflected in the
Response$session field and using either produces the same result
has_session_cookieQuery whether the request came with a session
cookie Immutable
session_cookie_settingsGet the settings for the session cookie as
they were provided during initialisation
cookie Immutable
has_keyQuery whether the request was initialised with an
encryption key Immutable
compression_limitQuery the compression limit the request was
initialized with 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. Immutable
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
query_delimThe delimiter used for specifying multiple values in a
query. If NULL then queries are expected to contain multiple key-value
pairs for the same key in order to provide an array, e.g.
?arg1=3&arg1=7. If setting it to ","", "|", or " " then an array
can be provided in a single key-value pair, e.g. ?arg1=3|7
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 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. Changing this will force the request to reparse
itself.
responseIf a Response object has been created for this request
it is accessible through this field. Immutable
lockedSet the locked status on the request. This flag does not
result in any different behaviour in the request but can be used by
frameworks to signal that the request should not be altered in some way
Methods
Public methods
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Method new()
Create a new request from a rook object
Usage
Request$new(
rook,
trust = FALSE,
key = NULL,
session_cookie = NULL,
compression_limit = 0
)
Arguments
rookThe rook object to base the request on
trustIs this request trusted blindly. If TRUE X-Forwarded-*
headers will be returned when querying host, ip, and protocol
keyA 32-bit secret key as a hex encoded string or a raw vector to
use for $encode_string() and $decode_string() and by extension to
encrypt a session cookie. It must be given to turn on session cookie
support. A valid key can be generated using random_key(). NEVER STORE
THE KEY IN PLAIN TEXT. Optimalle use the keyring package to store it or
set it as an environment variable
session_cookieSettings for the session cookie created using
session_cookie(). Will be ignored if key is not provided to ensure
session cookies are properly encrypted
compression_limitThe size threshold in bytes for trying to
compress the response body (it is still dependant on content negotiation)
Method print()
Pretty printing of the object
Usage
Request$print(...)
Arguments
...ignored
Method set_body()
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
Usage
Request$set_body(content)
Arguments
contentAn R object representing the body of the request
Method set_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
Usage
Request$set_cookies(cookies)
Arguments
cookiesA named list of cookie values
Method accepts()
Given a vector of response content types it returns the
preferred one based on the Accept header.
Usage
Request$accepts(types)
Arguments
typesA vector of types
Method accepts_charsets()
Given a vector of possible character encodings it returns
the preferred one based on the Accept-Charset header.
Usage
Request$accepts_charsets(charsets)
Arguments
charsetsA vector of charsets
Method accepts_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.
Usage
Request$accepts_encoding(encoding)
Arguments
encodingA vector of encoding names
Method accepts_language()
Given a vector of possible content languages it selects the
best one based on the Accept-Language header.
Usage
Request$accepts_language(language)
Arguments
languageA vector of languages
Method is()
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.
Usage
Request$is(type)
Arguments
typeA vector of content types to check for. Can be fully
qualified MIME types, a file extension, or a mime type with wildcards
Method get_header()
Get the header of the specified name.
Usage
Request$get_header(name)
Arguments
nameThe name of the header to get
Method respond()
Creates a new Response object from the request
Usage
Request$respond()
Method parse()
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
Usage
Request$parse(..., autofail = TRUE)
Arguments
...A named set of parser functions
autofailAutomatically populate the response if parsing fails
Method parse_raw()
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.
Usage
Request$parse_raw(autofail = TRUE)
Arguments
autofailAutomatically populate the response if parsing fails
Method as_message()
Prints a HTTP representation of the request to the output
stream.
Usage
Request$as_message()
Method encode_string()
base64-encode a string. If a key has been provided during
initialisation the string is first encrypted and the final result is a
combination of the encrypted text and the nonce, both base64 encoded and
combined with a "_".
Usage
Request$encode_string(val)
Arguments
valA single string to encrypt
Method decode_string()
base64-decodes a string. If a key has been provided during
initialisation the input is first split by "_" and then the two parts
are base64 decoded and decrypted. Otherwise the input is base64-decoded
as-is. It will always hold that
val == decode_string(encode_string(val)).
Usage
Request$decode_string(val)
Arguments
valA single string to encrypt
Method clear()
Clears the content of the request and, if created, the
related response. This method exists only to allow reuse of the request
and response object to save a few milliseconds in latency. Use with
caution and see e.g. how fiery maintains a poll of request objects
Usage
Request$clear()
Method forward()
Forward a request to a new url, optionally setting different
headers, queries, etc. Uses curl and mirai under the hood and returns a
promise
Usage
Request$forward(
url,
query = NULL,
method = NULL,
headers = NULL,
body = NULL,
return = NULL,
...
)
Arguments
urlThe url to forward to
queryOptional querystring to append to url. If NULL the query
string of the current request will be used
methodThe HTTP method to use. If NULL the method of the current
request will be used
headersA list of headers to add to the headers of the current
request. You can remove a header from the current request by setting it
to NULL here
bodyThe body to send with the forward. If NULL the body of the
current request will be used
returnA function that takes in the fulfilled response object and
whose return value is returned by the promise
...ignored
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()
thomasp85/reqres documentation built on June 15, 2025, 1:20 a.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)
|
Active bindings
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). ImmutablesessionThe content of the session cookie. If session cookies has not been activated it will be an empty write-protected list. If session cookies are activated but the request did not contain one it will be an empty list. The content of this field will be send encrypted as part of the response according to the cookie settings in
$session_cookie_settings. This field is reflected in theResponse$sessionfield and using either produces the same resulthas_session_cookieQuery whether the request came with a session cookie Immutable
session_cookie_settingsGet the settings for the session cookie as they were provided during initialisation cookie Immutable
has_keyQuery whether the request was initialised with an encryption key Immutable
compression_limitQuery the compression limit the request was initialized with 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 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. ImmutableipReturns 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
query_delimThe delimiter used for specifying multiple values in a query. If
NULLthen queries are expected to contain multiple key-value pairs for the same key in order to provide an array, e.g.?arg1=3&arg1=7. If setting it to","","|", or" "then an array can be provided in a single key-value pair, e.g.?arg1=3|7querystringThe 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 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. Changing this will force the request to reparse itself.responseIf a
Responseobject has been created for this request it is accessible through this field. ImmutablelockedSet the
lockedstatus on the request. This flag does not result in any different behaviour in the request but can be used by frameworks to signal that the request should not be altered in some way
Methods
Public methods
Method new()
Create a new request from a rook object
Usage
Request$new( rook, trust = FALSE, key = NULL, session_cookie = NULL, compression_limit = 0 )
Arguments
rookThe rook object to base the request on
trustIs this request trusted blindly. If
TRUEX-Forwarded-*headers will be returned when querying host, ip, and protocolkeyA 32-bit secret key as a hex encoded string or a raw vector to use for
$encode_string()and$decode_string()and by extension to encrypt a session cookie. It must be given to turn on session cookie support. A valid key can be generated usingrandom_key(). NEVER STORE THE KEY IN PLAIN TEXT. Optimalle use the keyring package to store it or set it as an environment variablesession_cookieSettings for the session cookie created using
session_cookie(). Will be ignored ifkeyis not provided to ensure session cookies are properly encryptedcompression_limitThe size threshold in bytes for trying to compress the response body (it is still dependant on content negotiation)
Method print()
Pretty printing of the object
Usage
Request$print(...)
Arguments
...ignored
Method set_body()
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
Usage
Request$set_body(content)
Arguments
contentAn R object representing the body of the request
Method set_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
Usage
Request$set_cookies(cookies)
Arguments
cookiesA named list of cookie values
Method accepts()
Given a vector of response content types it returns the
preferred one based on the Accept header.
Usage
Request$accepts(types)
Arguments
typesA vector of types
Method accepts_charsets()
Given a vector of possible character encodings it returns
the preferred one based on the Accept-Charset header.
Usage
Request$accepts_charsets(charsets)
Arguments
charsetsA vector of charsets
Method accepts_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.
Usage
Request$accepts_encoding(encoding)
Arguments
encodingA vector of encoding names
Method accepts_language()
Given a vector of possible content languages it selects the
best one based on the Accept-Language header.
Usage
Request$accepts_language(language)
Arguments
languageA vector of languages
Method is()
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.
Usage
Request$is(type)
Arguments
typeA vector of content types to check for. Can be fully qualified MIME types, a file extension, or a mime type with wildcards
Method get_header()
Get the header of the specified name.
Usage
Request$get_header(name)
Arguments
nameThe name of the header to get
Method respond()
Creates a new Response object from the request
Usage
Request$respond()
Method parse()
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
Usage
Request$parse(..., autofail = TRUE)
Arguments
...A named set of parser functions
autofailAutomatically populate the response if parsing fails
Method parse_raw()
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.
Usage
Request$parse_raw(autofail = TRUE)
Arguments
autofailAutomatically populate the response if parsing fails
Method as_message()
Prints a HTTP representation of the request to the output stream.
Usage
Request$as_message()
Method encode_string()
base64-encode a string. If a key has been provided during
initialisation the string is first encrypted and the final result is a
combination of the encrypted text and the nonce, both base64 encoded and
combined with a "_".
Usage
Request$encode_string(val)
Arguments
valA single string to encrypt
Method decode_string()
base64-decodes a string. If a key has been provided during
initialisation the input is first split by "_" and then the two parts
are base64 decoded and decrypted. Otherwise the input is base64-decoded
as-is. It will always hold that
val == decode_string(encode_string(val)).
Usage
Request$decode_string(val)
Arguments
valA single string to encrypt
Method clear()
Clears the content of the request and, if created, the related response. This method exists only to allow reuse of the request and response object to save a few milliseconds in latency. Use with caution and see e.g. how fiery maintains a poll of request objects
Usage
Request$clear()
Method forward()
Forward a request to a new url, optionally setting different headers, queries, etc. Uses curl and mirai under the hood and returns a promise
Usage
Request$forward( url, query = NULL, method = NULL, headers = NULL, body = NULL, return = NULL, ... )
Arguments
urlThe url to forward to
queryOptional querystring to append to
url. IfNULLthe query string of the current request will be usedmethodThe HTTP method to use. If
NULLthe method of the current request will be usedheadersA list of headers to add to the headers of the current request. You can remove a header from the current request by setting it to
NULLherebodyThe body to send with the forward. If
NULLthe body of the current request will be usedreturnA function that takes in the fulfilled response object and whose return value is returned by the promise
...ignored
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.