Implement req_headers_redacted() (#608)

I think this is a friendlier interface than the `.redact` argument to `req_headers()`. Fixes #561

NAMESPACE

@@ -67,6 +67,7 @@ export(req_cookies_set)
 export(req_dry_run)
 export(req_error)
 export(req_headers)
+export(req_headers_redacted)
 export(req_method)
 export(req_oauth)
 export(req_oauth_auth_code)

NEWS.md

@@ -1,5 +1,6 @@
 # httr2 (development version)
 
+* New `req_headers_redacted()` provides a user-friendlier way to set redacted headers (#561).
 * `resp_link_url()` now works if there are multiple `Link` headers (#587).
 * New `url_modify()` makes it easier to modify an existing url (#464).
 * New `req_url_relative()` for constructing relative urls (#449).

R/req-headers.R

@@ -1,7 +1,12 @@
 #' Modify request headers
 #'
+#' @description
 #' `req_headers()` allows you to set the value of any header.
 #'
+#' `req_headers_redacted()` is a variation that adds "redacted" headers, which
+#' httr2 avoids printing on the console. This is good practice for
+#' authentication headers to avoid accidentally leaking them in log files.
+#'
 #' @param .req A [request].
 #' @param ... <[`dynamic-dots`][rlang::dyn-dots]> Name-value pairs of headers
 #'   and their values.
@@ -46,13 +51,16 @@
 #' # If you have headers in a list, use !!!
 #' headers <- list(HeaderOne = "one", HeaderTwo = "two")
 #' req |>
-#'    req_headers(!!!headers, HeaderThree = "three") |>
-#'    req_dry_run()
-#'
-#' # Use `.redact` to hide a header in the output
-#' req |>
-#'   req_headers(Secret = "this-is-private", Public = "but-this-is-not", .redact = "Secret") |>
+#'   req_headers(!!!headers, HeaderThree = "three") |>
 #'   req_dry_run()
+#'
+#' # Use `req_headers_redacted()`` to hide a header in the output
+#' req_secret <- req |>
+#'   req_headers_redacted(Secret = "this-is-private") |>
+#'   req_headers(Public = "but-this-is-not")
+#'
+#' req_secret
+#' req_secret |> req_dry_run()
 req_headers <- function(.req, ..., .redact = NULL) {
   check_request(.req)
 
@@ -68,3 +76,12 @@ req_headers <- function(.req, ..., .redact = NULL) {
 
   .req
 }
+
+#' @export
+#' @rdname req_headers
+req_headers_redacted <- function(.req, ...) {
+  check_request(.req)
+
+  dots <- list(...)
+  req_headers(.req, !!!dots, .redact = names(dots))
+}

tests/testthat/test-req-headers.R

@@ -30,6 +30,8 @@ test_that("can control which headers to redact", {
   expect_redact(req_headers(req, a = 1L, b = 2L, .redact = c("a", "b")), c("a", "b"))
   expect_redact(req_headers(req, a = 1L, b = 2L, .redact = "a"), "a")
 
+  expect_redact(req_headers_redacted(req, a = 1L, b = 2L), c("a", "b"))
+
   expect_snapshot(error = TRUE, {
     req_headers(req, a = 1L, b = 2L, .redact = 1L)
   })