Make redirect_uri the primary interface (#294)

And include `path` in listener. Fixes #149

Author: hadley

NEWS.md

@@ -1,5 +1,17 @@
 # httr2 (development version)
 
+* `oauth_flow_auth_code()` gains a `redirect_uri` argument rather than deriving
+  this URL automatically from the `host_name` and `port` (#248). It uses
+  this argument to automatically choose which strategy to use for gathering the 
+  auth code, either launching a temporary web server or, new, allowing you to 
+  manually enter the details with the help of a custom JS/HTML page hosted
+  elsewhere. The temporary web server now also respects the path component
+  of `redirect_uri`, if the API needs a specific path (#149).
+
+* `oauth_flow_auth_code()` deprecates `host_name` and `port` arguments in favour
+  of using `redirect_uri`. It also deprecates `host_ip` since it seems unlikely
+  that changing this is ever useful.
+
 * New `oauth_cache_path()` returns the path that httr2 uses for caching OAuth
   tokens. Additionally, you can now change the cache location by setting the
   `HTTR2_OAUTH_CACHE` env var.
@@ -74,13 +86,6 @@
 * `oauth_flow_refresh()` now only warns if the `refresh_token` changes, making
   it a little easier to use in manual workflows (#186).
 
-* `oauth_flow_auth_code()` now attempts to detect when you're running in a 
-  hosted environment (e.g. Google Collab/Posit Workbench/Posit cloud) and 
-  allows users to enter the authorisation code into the console manually (#248).
-
-* `oauth_flow_auth_code()` gains a `redirect_uri` argument rather than deriving
-  this URL automatically from the `host_name` and `port` (#248).
-
 # httr2 0.2.3
 
 * New `example_url()` to launch a local server, making tests and examples 

R/oauth-flow-auth-code.R

@@ -59,25 +59,27 @@ req_oauth_auth_code <- function(req, client,
                                 pkce = TRUE,
                                 auth_params = list(),
                                 token_params = list(),
-                                type = c("desktop", "web"),
-                                host_name = "localhost",
-                                host_ip = "127.0.0.1",
-                                port = httpuv::randomPort(),
-                                redirect_uri = "http://localhost"
+                                redirect_uri = "http://localhost",
+                                host_name = deprecated(),
+                                host_ip = deprecated(),
+                                port = deprecated()
                                 ) {
 
+  redirect <- normalize_redirect_uri(
+    redirect_uri = redirect_uri,
+    host_name = host_name,
+    host_ip = host_ip,
+    port = port
+  )
+
   params <- list(
     client = client,
     auth_url = auth_url,
     scope = scope,
     pkce = pkce,
     auth_params = auth_params,
     token_params = token_params,
-    type = type,
-    host_name = host_name,
-    host_ip = host_ip,
-    port = port,
-    redirect_uri = redirect_uri
+    redirect_uri = redirect$uri
   )
 
   cache <- cache_choose(client, cache_disk, cache_key)
@@ -123,20 +125,27 @@ req_oauth_auth_code <- function(req, client,
 #' @param auth_params List containing additional parameters passed to `oauth_flow_auth_code_url()`
 #' @param token_params List containing additional parameters passed to the
 #'   `token_url`.
-#' @param host_name `r lifecycle::badge("deprecated")` Use `redirect_uri`
-#'   instead.
+#' @param host_name,host_ip,port `r lifecycle::badge("deprecated")`
+#'   Now use `redirect_uri` instead.
 #' @param host_ip IP address for the temporary webserver used to capture the
 #'   authorization code.
-#' @param type Either `desktop` or `web`. Use desktop when running on the
-#'   desktop in an environment where you can redirect the user to `localhost`.
-#'   Use `web` when running in a hosted web environment.
-#' @param port Port to bind the temporary webserver to. Used only when
-#'   `redirect_uri` is `"http(s)://localhost"`. By default, this uses a random
-#'   port. You may need to set it to a fixed port if the API requires that the
-#'   `redirect_uri` specified in the client exactly matches the `redirect_uri`
-#'   generated by this function.
+#' @param port Port to bind the temporary webserver to.
 #' @param redirect_uri URL to redirect back to after authorization is complete.
 #'   Often this must be registered with the API in advance.
+#'
+#'   httr2 supports two forms of redirect. Firstly, you can use a `localhost`
+#'   url (the default), where httr2 will set up a temporary webserver to listen
+#'   for the OAuth redirect. In this case, httr2 will automatically append a
+#'   random port. If you need to set it to a fixed port because the API requires
+#'   it, then specify it with (e.g.) `"http://localhost:1011"`. This technique
+#'   works well when you are working on your own computer.
+#'
+#'   Alternatively, you can provide a URL to a website that uses javascript to
+#'   give the user a code to copy and paste back into the R session (see
+#'   <https://www.tidyverse.org/google-callback/>, for an example). This is
+#'   less convenient (because it requires more user interaction) but also works
+#'   in hosted environments.
+#'
 #' @returns An [oauth_token].
 #' @export
 #' @keywords internal
@@ -160,38 +169,20 @@ oauth_flow_auth_code <- function(client,
                                  pkce = TRUE,
                                  auth_params = list(),
                                  token_params = list(),
+                                 redirect_uri = "http://localhost",
                                  host_name = deprecated(),
-                                 host_ip = "127.0.0.1",
-                                 type = c("desktop", "web"),
-                                 port = httpuv::randomPort(),
-                                 redirect_uri = "http://localhost"
+                                 host_ip = deprecated(),
+                                 port = deprecated()
 ) {
 
-  type <- arg_match(type)
-  if (type == "desktop") {
-    check_installed("httpuv", "desktop OAuth")
-    if (is_hosted_session()) {
-      cli::cli_abort("Only type='web' is supported in the current session")
-    }
-  }
-
   oauth_flow_check("authorization code", client, interactive = TRUE)
 
-  # For backwards compatibility, fall back to the original redirect URL
-  # construction.
-  if (lifecycle::is_present(host_name)) {
-    lifecycle::deprecate_warn(
-      when = "0.3.0",
-      what = "oauth_flow_auth_code(host_name)",
-      with = "oauth_flow_auth_code(redirect_uri)"
-    )
-    redirect_uri <- paste0("http://", host_name, ":", port, "/")
-  }
-
-  # Only append a port if we have a bare HTTP(s) localhost redirect.
-  if (grepl("https?://localhost$", redirect_uri)) {
-    redirect_uri <- paste0(redirect_uri, ":", port, "/")
-  }
+  redirect <- normalize_redirect_uri(
+    redirect_uri = redirect_uri,
+    host_name = host_name,
+    host_ip = host_ip,
+    port = port
+  )
 
   if (pkce) {
     code <- oauth_flow_auth_code_pkce()
@@ -205,16 +196,19 @@ oauth_flow_auth_code <- function(client,
   # Redirect user to authorisation url.
   user_url <- oauth_flow_auth_code_url(client,
     auth_url = auth_url,
-    redirect_uri = redirect_uri,
+    redirect_uri = redirect$uri,
     scope = scope,
     state = state,
     auth_params = auth_params
   )
   utils::browseURL(user_url)
 
-  if (type == "desktop") {
-    # Listen on localhost for the result.
-    result <- oauth_flow_auth_code_listen(host_ip, port)
+  if (redirect$localhost) {
+    # Listen on localhost for the result
+    result <- oauth_flow_auth_code_listen(
+      port = redirect$port,
+      path = redirect$path
+    )
     code <- oauth_flow_auth_code_parse(result, state)
   } else {
     # Allow the user to retrieve the token out of band manually and enter it
@@ -233,6 +227,61 @@ oauth_flow_auth_code <- function(client,
   )
 }
 
+normalize_redirect_uri <- function(redirect_uri,
+                                   host_name = deprecated(),
+                                   host_ip = deprecated(),
+                                   port = deprecated(),
+                                   error_call = caller_env()) {
+
+  parsed <- url_parse(redirect_uri)
+
+  if (lifecycle::is_present(host_name)) {
+    lifecycle::deprecate_warn(
+      when = "0.3.0",
+      what = "oauth_flow_auth_code(host_name)",
+      with = "oauth_flow_auth_code(redirect_uri)"
+    )
+    parsed$hostname <- host_name
+  }
+
+  if (lifecycle::is_present(port)) {
+    lifecycle::deprecate_warn(
+      when = "0.3.0",
+      what = "oauth_flow_auth_code(port)",
+      with = "oauth_flow_auth_code(redirect_uri)"
+    )
+    parsed$port <- port
+  }
+
+  if (lifecycle::is_present(host_ip)) {
+    lifecycle::deprecate_warn("0.3.0", "oauth_flow_auth_code(host_ip)")
+  }
+
+  localhost <- parsed$hostname == "localhost"
+
+  if (localhost) {
+    check_installed("httpuv", "desktop OAuth")
+    if (is_hosted_session()) {
+      cli::cli_abort(
+        "Can't use localhost {.arg redirect_uri} in a hosted environment",
+        call = error_call
+      )
+    }
+
+    if (is.null(parsed$port)) {
+      parsed$port <- httpuv::randomPort()
+    }
+  }
+
+  list(
+    uri = url_build(parsed),
+    localhost = localhost,
+    port = parsed$port,
+    path = parsed$path %||% "/"
+  )
+
+}
+
 # Authorisation request: make a url that the user navigates to
 # https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1
 #' @export
@@ -261,11 +310,11 @@ oauth_flow_auth_code_url <- function(client,
 
 #' @export
 #' @rdname oauth_flow_auth_code
-oauth_flow_auth_code_listen <- function(host_ip = "127.0.0.1", port = 1410) {
+oauth_flow_auth_code_listen <- function(host_ip = "127.0.0.1", port = 1410, path = "/") {
   complete <- FALSE
   info <- NULL
   listen <- function(env) {
-    if (!identical(env$PATH_INFO, "/")) {
+    if (!identical(env$PATH_INFO, path)) {
       return(list(
         status = 404L,
         headers = list("Content-Type" = "text/plain"),