Perform authorized HTTP requests

Perform authorized HTTP requests to an ArtifactDB REST endpoint.

authorizedVerb(FUN, ..., user.agent = NULL, allow.redirect = FALSE)

checkResponse(x, allow.redirect = FALSE)

identityAvailable(fun)

identityHeaders(fun)

Arguments

FUN

A httr function defining a verb, e.g., GET.

...

Further arguments to pass to FUN.

user.agent

String specifying the user agent, defaults to the current R installation and zircon version.

allow.redirect

Logical scalar indicating whether a redirect should not be considered a failure.

x

Response list from httr verb functions.

fun

Functions that check the identity and create HTTP request headers, see Details.

Value

For authorizedVerb, the output of FUN without checking for errors.

For checkResponse, an error is raised with an appropriate message if the request failed. Otherwise, an invisible NULL.

For identityAvailable and identityHeaders, if fun is missing, the current function is returned. If fun is supplied, it is used as the checker/creator function inside authorizedVerb, and the previous value of the function is invisibly returned.

Details

The fun in identityAvailable should accept no arguments and should return a logical scalar specifying whether a user identity is available for the current R session.

The fun in identityHeaders should accept no arguments and should return a named list of HTTP request headers that authenticates the user to the ArtifactDB backend. The exact nature of these headers depends on the authentication system used by the backend, e.g., Authorization headers with JSON web tokens, SSH keys, or others. If the corresponding credentials are not available, identityHeaders should prompt the user to create them (or fail outright in non-interactive sessions).

If identityAvailable is not available or returns FALSE, authorizedVerb will attempt to perform an unauthenticated request. If this fails and identityHeader is available, it will repeat the request after calling identityHeader to create authentication headers. This process avoids burdening the user with authentication issues when requesting publicly available resources, falling back to some authentication process as required.

See also

useGitHubIdentities, which sets up authorization based on GitHub personal access tokens.

Author

Aaron Lun

Examples

library(httr)
URL <- file.path(example.url, "files", URLencode(example.id, reserved=TRUE))
authorizedVerb(GET, url=URL)
#> Response [https://gypsum-test.bfb2e522e0b245720424784fcf7c04c0.r2.cloudflarestorage.com/test-public/base/blah.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ae0f6ee0f014deff554f709698940ab3%2F20230202%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20230202T004449Z&X-Amz-Expires=120&X-Amz-Signature=63f60419053dd19b7bb0298c66499e2b3f9aa2d60a5f158bfe5164aae82a6226&X-Amz-SignedHeaders=host&x-id=GetObject]
#>   Date: 2023-02-02 00:44
#>   Status: 200
#>   Content-Type: text/plain
#>   Size: 52 B
#> A
#> B
#> C
#> D
#> E
#> F
#> G
#> H
#> I
#> J
#> ...

# Triggering failures:
URL2 <- file.path(example.url, "files", "something_is_absent")
out <- authorizedVerb(GET, url=URL2)
try(.checkResponse(out))
#> Error in .checkResponse(out) : could not find function ".checkResponse"