gargle_oauth_client_type: new option and accessor (#244)

* gargle_oaut_client_type: new option and accessor

* Add NEWS bullet

Author: jennybc

NAMESPACE

@@ -33,6 +33,7 @@ export(gargle_map_cli)
 export(gargle_oauth_cache)
 export(gargle_oauth_client)
 export(gargle_oauth_client_from_json)
+export(gargle_oauth_client_type)
 export(gargle_oauth_email)
 export(gargle_oauth_sitrep)
 export(gargle_oob_default)

NEWS.md

@@ -20,6 +20,12 @@ Changes of note:
 
 gargle is better able to detect when it's running on Posit Workbench or RStudio Server, e.g., in a subprocess.
 
+`gargle_oauth_client_type()` is a new function that returns either "installed"
+or "web".
+It returns the value of the new global option by the same name (`"gargle_oauth_client_type"`), if defined.
+If the option is not defined, returns "web" on RStudio Server, Posit Workbench, or Posit Cloud, and "installed" otherwise.
+In the context of out-of-band (OOB) auth, an "installed" client type leads to the conventional OOB flow (only available for GCP projects in testing mode) and a "web" client leads to the new pseudo-OOB flow.
+
 # gargle 1.3.0
 
 ## (Partial) deprecation out-of-band (OOB) auth flow

R/gargle-package.R

@@ -94,3 +94,24 @@ gargle_oob_default <- function() {
 gargle_oauth_cache <- function() {
   getOption("gargle_oauth_cache", default = NA)
 }
+
+#' @rdname gargle_options
+#' @export
+#' @section `gargle_oauth_client_type`:
+#' `gargle_oauth_client_type()` returns the option named
+#' "gargle_oauth_client_type", if defined. If defined, the option must be either
+#' "installed" or "web". If the option is not defined, the function returns:
+#' * "web" on RStudio Server, Posit Workbench, or Posit Cloud
+#' * "installed" otherwise
+#' Primarily intended to help infer the most suitable OAuth client when a user
+#' is relying on a built-in client, such as the tidyverse client used by
+#' packages like bigrquery, googledrive, and googlesheets4.
+gargle_oauth_client_type <- function() {
+  opt <- getOption("gargle_oauth_client_type")
+  if (is.null(opt)) {
+    if(is_rstudio_server()) "web" else "installed"
+  } else {
+    check_string(opt)
+    arg_match(opt, values = c("installed", "web"))
+  }
+}

R/gargle_oauth_client.R

@@ -199,7 +199,7 @@ list_redact <- function(x, names, case_sensitive = TRUE) {
 #' }
 gargle_client <- function(type = NULL) {
   if (is.null(type) || is.na(type)) {
-    type <- if(is_rstudio_server()) "web" else "installed"
+    type <- gargle_oauth_client_type()
   }
   check_string(type)
   type <- arg_match(type, values = c("installed", "web"))
@@ -218,7 +218,7 @@ tidyverse_client <- function(type = NULL) {
   check_permitted_package(parent.frame())
 
   if (is.null(type) || is.na(type)) {
-    type <- if(is_rstudio_server()) "web" else "installed"
+    type <- gargle_oauth_client_type()
   }
   check_string(type)
   type <- arg_match(type, values = c("installed", "web"))

man/gargle_options.Rd

@@ -2,15 +2,18 @@ test_that("default options", {
   withr::local_options(list(
     gargle_oauth_cache = NULL,
     gargle_oob_default = NULL, httr_oob_default = NULL,
+    gargle_oauth_client_type = NULL,
     gargle_oauth_email = NULL,
     gargle_verbosity   = NULL,
     gargle_quiet       = NULL
   ))
   expect_equal(gargle_oauth_cache(), NA)
   if (is_rstudio_server()) {
     expect_true(gargle_oob_default())
+    expect_equal(gargle_oauth_client_type(), "web")
   } else {
     expect_false(gargle_oob_default())
+    expect_equal(gargle_oauth_client_type(), "installed")
   }
   expect_null(gargle_oauth_email())
   expect_equal(gargle_verbosity(), "info")
@@ -32,6 +35,11 @@ test_that("gargle_oob_default() consults httr's option", {
   expect_true(gargle_oob_default())
 })
 
+test_that("gargle_oauth_client_type() consults the option", {
+  withr::local_options(list(gargle_oauth_client_type = "web"))
+  expect_equal(gargle_oauth_client_type(), "web")
+})
+
 test_that("gargle API key", {
   key <- gargle_api_key()
   expect_true(is_string(key))