Add OAuth vignette & cache path customisation

NAMESPACE

@@ -13,6 +13,7 @@ S3method(print,httr2_token)
 S3method(print,httr2_url)
 S3method(str,httr2_obfuscated)
 export("%>%")
+export(cache_path)
 export(curl_help)
 export(curl_translate)
 export(example_url)

NEWS.md

@@ -1,5 +1,11 @@
 # httr2 (development version)
 
+* New `cache_path()` that returns path to httr2's cache directory. Additionally, 
+  you can now change the cache location by setting the `HTTR2_CACHE` env var.
+
+* New `vignette("oauth")` makes the details of OAuth usage easier to find 
+  (#234).
+
 * `req_perform()` now throws error with class `httr2_failure` if the 
   request fails. And that error now captures the curl error as the parent.
 

R/oauth-flow-auth-code.R

@@ -6,6 +6,8 @@
 #' The token is automatically cached (either in memory or on disk) to minimise
 #' the number of times the flow is performed.
 #'
+#' Learn more about the overall flow in `vignette("oauth")`.
+#'
 #' # Security considerations
 #'
 #' The authorization code flow is used for both web applications and native
@@ -29,8 +31,8 @@
 #' @inheritParams req_perform
 #' @param cache_disk Should the access token be cached on disk? This reduces
 #'   the number of times that you need to re-authenticate at the cost of
-#'   storing access credentials on disk. Cached tokens are encrypted and
-#'   automatically deleted 30 days after creation.
+#'   storing access credentials on disk. Cached tokens are encrypted,
+#'   automatically deleted 30 days after creation, and stored in [cache_path()].
 #' @param cache_key If you want to cache multiple tokens per app, use this
 #'   key to disambiguate them.
 #' @returns A modified HTTP [request].

R/oauth-flow-client-credentials.R

@@ -5,6 +5,8 @@
 #' which is then used to authentication the request with [req_auth_bearer_token()].
 #' The token is cached in memory.
 #'
+#' Learn more about the overall flow in `vignette("oauth")`.
+#'
 #' @export
 #' @inheritParams req_perform
 #' @inheritParams oauth_flow_client_credentials

R/oauth-flow-device.R

@@ -6,6 +6,8 @@
 #' The token is automatically cached (either in memory or on disk) to minimise
 #' the number of times the flow is performed.
 #'
+#' Learn more about the overall flow in `vignette("oauth")`.
+#'
 #' @export
 #' @inheritParams oauth_flow_password
 #' @inheritParams req_oauth_auth_code

R/oauth-flow-jwt.R

@@ -5,6 +5,8 @@
 #' used to authenticate the request with [req_auth_bearer_token()].
 #' The token is cached in memory.
 #'
+#' Learn more about the overall flow in `vignette("oauth")`.
+#'
 #' @export
 #' @inheritParams req_perform
 #' @inheritParams oauth_flow_bearer_jwt

R/oauth-flow-password.R

@@ -7,6 +7,8 @@
 #' or on disk); the password is used once to get the token and is then
 #' discarded.
 #'
+#' Learn more about the overall flow in `vignette("oauth")`.
+#'
 #' @export
 #' @inheritParams oauth_flow_password
 #' @inheritParams req_oauth_auth_code

R/oauth-flow-refresh.R

@@ -12,6 +12,8 @@
 #' token. If this happens, `oauth_flow_refresh()` will warn, and you'll have to
 #' update your stored refresh token.
 #'
+#' Learn more about the overall flow in `vignette("oauth")`.
+#'
 #' @export
 #' @inheritParams req_perform
 #' @inheritParams oauth_flow_refresh

R/oauth.R

@@ -116,3 +116,20 @@ cache_disk_prune <- function(days = 30, path = rappdirs::user_cache_dir("httr2")
   old <- mtime < (Sys.time() - days * 86400)
   unlink(files[old])
 }
+
+#' httr2 cache location
+#'
+#' When opted-in to, httr2 caches OAuth tokens in this directory. By default,
+#' it uses a OS-standard cache directory, but, if needed, you can override the
+#' location by setting the `HTTR2_CACHE` env var.
+#'
+#' @export
+#' @keywords internal
+cache_path <- function() {
+  path <- Sys.getenv("HTTR2_CACHE")
+  if (path != "") {
+    return(path)
+  }
+
+  rappdirs::user_cache_dir("httr2")
+}

R/req-cache.R

@@ -53,7 +53,7 @@ req_cache <- function(req, path, use_on_error = FALSE, debug = FALSE) {
 # Do I need to worry about hash collisions?
 # No - even if the user stores a billion urls, the probably of a collision
 # is ~ 1e-20: https://preshing.com/20110504/hash-collision-probabilities/
-cache_path <- function(req, ext = ".rds") {
+req_cache_path <- function(req, ext = ".rds") {
   file.path(req$policies$cache_path, paste0(hash(req$url), ext))
 }
 cache_use_on_error <- function(req) {
@@ -69,26 +69,26 @@ cache_exists <- function(req) {
   if (!req_policy_exists(req, "cache_path")) {
     FALSE
   } else {
-    file.exists(cache_path(req))
+    file.exists(req_cache_path(req))
   }
 }
 
 # Callers responsibility to check that cache exists
 cache_get <- function(req) {
-  path <- cache_path(req)
+  path <- req_cache_path(req)
 
   touch(path)
   readRDS(path)
 }
 
 cache_set <- function(req, resp) {
   if (is_path(resp$body)) {
-    body_path <- cache_path(req, ".body")
+    body_path <- req_cache_path(req, ".body")
     file.copy(resp$body, body_path, overwrite = TRUE)
     resp$body <- new_path(body_path)
   }
 
-  saveRDS(resp, cache_path(req, ".rds"))
+  saveRDS(resp, req_cache_path(req, ".rds"))
   invisible()
 }
 

_pkgdown.yml

@@ -70,3 +70,10 @@ reference:
   contents:
   - starts_with("oauth_")
   - starts_with("jwt_")
+
+articles:
+- title: Using httr2
+  navbar: ~
+  contents:
+  - articles/wrapping-apis
+  - articles/oauth

tests/testthat/test-oauth.R

@@ -55,3 +55,10 @@ test_that("can prune old files", {
   cache_disk_prune(2, path)
   expect_equal(dir(path), "a-token.rds")
 })
+
+# cache_path --------------------------------------------------------------
+
+test_that("can override path with env var", {
+  withr::local_envvar("HTTR2_CACHE" = "/tmp")
+  expect_equal(cache_path(), "/tmp")
+})

tests/testthat/test-req-cache.R

@@ -145,7 +145,7 @@ test_that("handles responses with files", {
   cache_set(req, resp)
 
   # File should be copied in cache directory, and response body updated
-  body_path <- cache_path(req, ".body")
+  body_path <- req_cache_path(req, ".body")
   expect_equal(readLines(body_path), "Hi there")
   expect_equal(cache_get(req)$body, new_path(body_path))