Package 'reqres'

Description

This set of functions throws a classed error indicating that the request should be responded to with an HTTP problem according to the spec defined in RFC 9457 or a bare response code. These conditions should be caught and handled by the handle_problem() function.

Usage

abort_http_problem(
  code,
  detail,
  title = NULL,
  type = NULL,
  instance = NULL,
  ...,
  message = detail,
  call = caller_env()
)

abort_status(code, message = status_phrase(code), ..., call = caller_env())

abort_bad_request(
  detail,
  instance = NULL,
  ...,
  message = detail,
  call = caller_env()
)

abort_unauthorized(
  detail,
  instance = NULL,
  ...,
  message = detail,
  call = caller_env()
)

abort_forbidden(
  detail,
  instance = NULL,
  ...,
  message = detail,
  call = caller_env()
)

abort_not_found(
  detail,
  instance = NULL,
  ...,
  message = detail,
  call = caller_env()
)

abort_method_not_allowed(
  detail,
  instance = NULL,
  ...,
  message = detail,
  call = caller_env()
)

abort_not_acceptable(
  detail,
  instance = NULL,
  ...,
  message = detail,
  call = caller_env()
)

abort_conflict(
  detail,
  instance = NULL,
  ...,
  message = detail,
  call = caller_env()
)

abort_gone(detail, instance = NULL, ..., message = detail, call = caller_env())

abort_internal_error(
  detail,
  instance = NULL,
  ...,
  message = detail,
  call = caller_env()
)

handle_problem(response, cnd)

is_reqres_problem(cnd)

Arguments

Description

This list matches the most normal mime types with their respective formatters using default arguments. For a no-frills request parsing this can be supplied directly to Response$format(). To add or modify to this list simply supply the additional parsers as second, third, etc, argument and they will overwrite or add depending on whether it specifies a mime type already present.

Usage

default_formatters

See Also

formatters for an overview of the build in formatters in reqres

Examples

## Not run: 
res$format(default_formatters, 'text/plain' = format_plain(sep = ' '))

## End(Not run)

Description

This list matches the most normal mime types with their respective parsers using default arguments. For a no-frills request parsing this can be supplied directly to Request$parse(). To add or modify to this list simply supply the additional parsers as second, third, etc, argument and they will overwrite or add depending on whether it specifies a mime type already present.

Usage

default_parsers

See Also

parsers for an overview of the build in parsers in reqres

Examples

## Not run: 
req$parse(default_parsers, 'application/json' = parse_json(flatten = TRUE))

## End(Not run)

Description

This set of functions can be used to construct formatting functions adhering to the Response$format() requirements.

Usage

format_json(
  dataframe = "rows",
  matrix = "rowmajor",
  Date = "ISO8601",
  POSIXt = "string",
  factor = "string",
  complex = "string",
  raw = "base64",
  null = "list",
  na = "null",
  auto_unbox = FALSE,
  digits = 4,
  pretty = FALSE,
  force = FALSE
)

format_plain(sep = "\n")

format_xml(encoding = "UTF-8", options = "as_xml")

format_html(encoding = "UTF-8", options = "as_html")

format_table(...)

Arguments

Value

A function accepting an R object

See Also

parsers for converting Request bodies into R objects

default_formatters for a list that maps the most common mime types to their respective formatters

Examples

fake_rook <- fiery::fake_request(
  'http://example.com/test',
  content = '',
  headers = list(
    Content_Type = 'text/plain',
    Accept = 'application/json, text/csv'
  )
)

req <- Request$new(fake_rook)
res <- req$respond()
res$body <- mtcars
res$format(json = format_json(), csv = format_table(sep=','))
res$body

# Cleaning up connections
rm(fake_rook, req, res)
gc()

Description

This set of functions can be used to construct parsing functions adhering to the Request$parse() requirements.

Usage

parse_json(
  simplifyVector = TRUE,
  simplifyDataFrame = simplifyVector,
  simplifyMatrix = simplifyVector,
  flatten = FALSE
)

parse_plain(sep = "\n")

parse_xml(encoding = "", options = "NOBLANKS", base_url = "")

parse_html(
  encoding = "",
  options = c("RECOVER", "NOERROR", "NOBLANKS"),
  base_url = ""
)

parse_multiform()

parse_queryform(delim = NULL)

parse_table(...)

Arguments

Value

A function accepting a raw vector and a named list of directives

See Also

formatters for converting Response bodies into compatible types

default_parsers for a list that maps the most common mime types to their respective parsers

Examples

fake_rook <- fiery::fake_request(
  'http://example.com/test',
  content = '[1, 2, 3, 4]',
  headers = list(
    Content_Type = 'application/json'
  )
)

req <- Request$new(fake_rook)
req$parse(json = parse_json())
req$body

# Cleaning up connections
rm(fake_rook, req)
gc()

Description

This function facilitates the parsing of querystrings, either from the URL or a POST or PUT body with Content-Type set to application/x-www-form-urlencoded.

Usage

query_parser(query = NULL, delim = NULL)

Arguments

Value

A named list giving the keys and values of the query. Values fron the same key are combined if given multiple times

Examples

# Using delimiter to provide array
query_parser("?name=Thomas%20Lin%20Pedersen&numbers=1 2 3", delim = " ")

# No delimiter (exploded form)
query_parser("?name=Thomas%20Lin%20Pedersen&numbers=1&numbers=2&numbers=3")

Description

The encryption/decryption used in reqres is based on the sodium package and requires a 32-bit encryption key encoded as hexadecimal values. While you can craft your own, this function will take care of creating a compliant key using a cryptographically secure pseudorandom number generator from sodium::helpers().

Usage

random_key()

Details

Keep your encryption keys safe! Anyone with the key will be able to eavesdrop on your communication and tamper with the information stored in encrypted cookies through man-in-the-middle attacks. The best approach is to use the keyring package to manage your keys, but as an alternative you can store it as environment variables.

NEVER STORE THE KEY IN PLAIN TEXT.

NEVER PUT THE KEY SOMEWHERE WHERE IT CAN ACCIDENTALLY BE COMMITTED TO GIT OR OTHER VERSION CONTROL SOFTWARE

Value

A 32-bit key as a hex-encoded string

Examples

# Store a key with keyring and use it
keyring::key_set_with_value("reqres_key", random_key())

rook <- fiery::fake_request("http://example.com")

Request$new(rook, key = keyring::key_get("reqres_key"))

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

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

Active bindings

Methods

Public methods

• Request$new()

• Request$print()

• Request$set_body()

• Request$set_cookies()

• Request$accepts()

• Request$accepts_charsets()

• Request$accepts_encoding()

• Request$accepts_language()

• Request$is()

• Request$get_header()

• Request$respond()

• Request$parse()

• Request$parse_raw()

• Request$as_message()

• Request$encode_string()

• Request$decode_string()

• Request$forward()

• Request$clone()

Method new()

Create a new request from a rook object

Usage

Request$new(rook, trust = FALSE, key = NULL, session_cookie = NULL)

Arguments

Method print()

Pretty printing of the object

Usage

Request$print(...)

Arguments

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

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

Method accepts()

Given a vector of response content types it returns the preferred one based on the Accept header.

Usage

Request$accepts(types)

Arguments

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

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

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

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

Method get_header()

Get the header of the specified name.

Usage

Request$get_header(name)

Arguments

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

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

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

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

Method forward()

Forward a request to a new url, optionally setting different headers, queries, etc. Uses httr2 under the hood

Usage

Request$forward(
  url,
  query = NULL,
  method = NULL,
  headers = NULL,
  body = NULL,
  ...
)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Request$clone(deep = FALSE)

Arguments

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

Description

This class handles all functionality involved in crafting a http response. 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 Response object can be converted to a compliant list object to be passed on to e.g. the httpuv handler. A Response object is always created as a response to a Request object and contains a reference to the originating Request object. A Response is always initialized with a 404 Not Found code, an empty string as body and the Content-Type header set to text/plain. As the Content-Type header is required for httpuv to function, it will be inferred if missing when converting to a list. If the body is a raw vector it will be set to application/octet-stream and otherwise it will be set to text/plain. It is always advised to consciously set the Content-Type header though. The only exception is when attaching a standard file where the type is inferred from the file extension automatically. Unless the body is a raw vector it will automatically be converted to a character vector and collapsed to a single string with "\n" separating the individual elements before the Response object is converted to a list (that is, the body can exist as any type of object up until the moment where the Response object is converted to a list). To facilitate communication between different middleware the Response object contains a data store where information can be stored during the lifetime of the response.

Usage

## S3 method for class 'Response'
as.list(x, ...)

is.Response(x)

Arguments

Value

A rook-compliant list-response (in case of as.list()) or a logical indicating whether the object is a Response (in case of is.Response())

Initialization

A new 'Response'-object is initialized using the new() method on the generator:

Usage

But often it will be provided by the request using the respond() method, which will provide the response, creating one if it doesn't exist

Usage

Arguments

Fields

The following fields are accessible in a Response object:

status

Gets or sets the status code of the response. Is initialised with 404L

body

Set or get he body of the response. If it is a character vector with a single element named 'file' it will be interpreted as the location of a file. It is better to use the file field for creating a response referencing a file as it will automatically set the correct headers.

file

Set or get the location of a file that should be used as the body of the response. If the body is not referencing a file (but contains something else) it will return NULL. The Content-Type header will automatically be inferred from the file extension, if known. If unknown it will defaults to application/octet-stream. If the file has no extension it will be text/plain. Existence of the file will be checked.

type

Get or sets the Content-Type header of the response based on a file extension or mime-type.

request

Get the original Request object that the object is responding to.

Active bindings

Methods

Public methods

• Response$new()

• Response$print()

• Response$set_header()

• Response$get_header()

• Response$remove_header()

• Response$has_header()

• Response$append_header()

• Response$set_data()

• Response$get_data()

• Response$remove_data()

• Response$has_data()

• Response$timestamp()

• Response$attach()

• Response$as_download()

• Response$status_with_text()

• Response$problem()

• Response$set_cookie()

• Response$remove_cookie()

• Response$clear_cookie()

• Response$has_cookie()

• Response$set_links()

• Response$format()

• Response$set_formatter()

• Response$compress()

• Response$content_length()

• Response$as_list()

• Response$as_message()

• Response$encode_string()

• Response$decode_string()

• Response$clone()

Method new()

Create a new response from a Request object

Usage

Response$new(request)

Arguments

Method print()

Pretty printing of the object

Usage

Response$print(...)

Arguments

Method set_header()

Sets the header given by name. value will be converted to character. A header will be added for each element in value. Use append_header() for setting headers without overwriting existing ones.

Usage

Response$set_header(name, value)

Arguments

Method get_header()

Returns the header(s) given by name

Usage

Response$get_header(name)

Arguments

Method remove_header()

Removes all headers given by name

Usage

Response$remove_header(name)

Arguments

Method has_header()

Test for the existence of any header given by name

Usage

Response$has_header(name)

Arguments

Method append_header()

Adds an additional header given by name with the value given by value. If the header does not exist yet it will be created.

Usage

Response$append_header(name, value)

Arguments

Method set_data()

Adds value to the internal data store and stores it with key

Usage

Response$set_data(key, value)

Arguments

Method get_data()

Retrieves the data stored under key in the internal data store.

Usage

Response$get_data(key)

Arguments

Method remove_data()

Removes the data stored under key in the internal data store.

Usage

Response$remove_data(key)

Arguments

Method has_data()

Queries whether the data store has an entry given by key

Usage

Response$has_data(key)

Arguments

Method timestamp()

Set the Date header to the current time

Usage

Response$timestamp()

Method attach()

Sets the body to the file given by file and marks the response as a download by setting the Content-Disposition to ⁠attachment; filename=<filename>⁠. Use the type argument to overwrite the automatic type inference from the file extension.

Usage

Response$attach(file, filename = basename(file), type = NULL)

Arguments

Method as_download()

Marks the response as a downloadable file, rather than data to be shown in the browser

Usage

Response$as_download(filename = NULL)

Arguments

Method status_with_text()

Sets the status to code and sets the body to the associated status code description (e.g. ⁠Bad Gateway⁠ for 502L)

Usage

Response$status_with_text(code, clear_headers = FALSE)

Arguments

Method problem()

Signals an API problem using the HTTP Problems spec RFC 9457. This should only be used in cases where returning a bare response code is insufficient to describe the issue.

Usage

Response$problem(
  code,
  detail,
  title = NULL,
  type = NULL,
  instance = NULL,
  clear_headers = TRUE
)

Arguments

Method set_cookie()

Sets a cookie on the response. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie for a longer description

Usage

Response$set_cookie(
  name,
  value,
  encode = TRUE,
  expires = NULL,
  http_only = NULL,
  max_age = NULL,
  path = NULL,
  secure = NULL,
  same_site = NULL
)

Arguments

Method remove_cookie()

Removes the cookie named name from the response.

Usage

Response$remove_cookie(name)

Arguments

Method clear_cookie()

Request the client to delete the given cookie

Usage

Response$clear_cookie(name)

Arguments

Method has_cookie()

Queries whether the response contains a cookie named name

Usage

Response$has_cookie(name)

Arguments

Method set_links()

Sets the Link header based on the named arguments passed to .... The names will be used for the rel directive.

Usage

Response$set_links(...)

Arguments

Method format()

Based on the formatters passed in through ... content negotiation is performed with the request and the preferred formatter is chosen and applied. The Content-Type header is set automatically. If compress = TRUE the compress() method will be called after formatting. If an error is encountered and autofail = TRUE the response will be set to 500. If a formatter is not found and autofail = TRUE the response will be set to 406. If formatting is successful it will return TRUE, if not it will return FALSE

Usage

Response$format(..., autofail = TRUE, compress = TRUE, default = NULL)

Arguments

Method set_formatter()

Based on the formatters passed in through ... content negotiation is performed with the request and the preferred formatter is chosen. The Content-Type header is set automatically. If a formatter is not found and autofail = TRUE the response will be set to 406. The found formatter is registered with the response and will be applied just before handing off the response to httpuv, unless the response has been manually formatted.

Usage

Response$set_formatter(..., autofail = TRUE, default = NULL)

Arguments

Method compress()

Based on the provided priority, an encoding is negotiated with the request and applied. The Content-Encoding header is set to the chosen compression algorithm.

Usage

Response$compress(
  priority = c("gzip", "deflate", "br", "identity"),
  force = FALSE
)

Arguments

Method content_length()

Calculates the length (in bytes) of the body. This is the number that goes into the Content-Length header. Note that the Content-Length header is set automatically by httpuv so this method should only be called if the response size is needed for other reasons.

Usage

Response$content_length()

Method as_list()

Converts the object to a list for further processing by a Rook compliant server such as httpuv. Will set Content-Type header if missing and convert a non-raw body to a single character string. Will apply the formatter set by set_formatter() unless the body has already been formatted. Will add a Date header if none exist.

Usage

Response$as_list()

Method as_message()

Prints a HTTP representation of the response to the output stream.

Usage

Response$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

Response$encode_string(val)

Arguments

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

Response$decode_string(val)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Response$clone(deep = FALSE)

Arguments

See Also

Request for handling http requests

Examples

fake_rook <- fiery::fake_request(
  'http://example.com/test?id=34632&question=who+is+hadley',
  content = 'This is elaborate ruse',
  headers = list(
    Accept = 'application/json; text/*',
    Content_Type = 'text/plain'
  )
)

req <- Request$new(fake_rook)
res <- Response$new(req)
res

# Set the body to the associated status text
res$status_with_text(200L)
res$body

# Infer Content-Type from file extension
res$type <- 'json'
res$type

# Prepare a file for download
res$attach(system.file('DESCRIPTION', package = 'reqres'))
res$type
res$body
res$get_header('Content-Disposition')

# Cleaning up connections
rm(fake_rook, req, res)
gc()

Description

A session cookie is just like any other cookie, but reqres treats this one different, parsing it's value and making it available in the ⁠$session⁠ field. However, the same settings as any other cookies applies and can be given during request initialisation using this function.

Usage

session_cookie(
  name = "reqres",
  expires = NULL,
  max_age = NULL,
  path = NULL,
  secure = NULL,
  same_site = NULL
)

is_session_cookie_settings(x)

Arguments

Value

A session_cookie_settings object that can be used during request initialisation. Can be cached and reused for all requests in a server

Note

As opposed to regular cookies the session cookie is forced to be HTTP only which is why this argument is missing.

Examples

session_cookie <- session_cookie()

rook <- fiery::fake_request("http://example.com")

# A key must be provided for session_cookie to be used
Request$new(rook, key = random_key(), session_cookie = session_cookie)

Description

Dates/times in HTTP headers needs a specific format to be valid, and is furthermore always given in GMT time. These two functions aids in converting back and forth between the required format.

Usage

to_http_date(time, format = NULL)

from_http_date(time)

Arguments

Value

to_http_date() returns a properly formatted string, while from_http_date() returns a POSIXct object

Examples

time <- to_http_date(Sys.time())
time
from_http_date(time)