feat: create, update, and delete integrations (stacked version)

NAMESPACE

@@ -8,8 +8,6 @@ S3method(api_build,op_head)
 S3method(as.data.frame,connect_integration_list)
 S3method(as.data.frame,connect_list_hits)
 S3method(as.data.frame,tbl_connect)
-S3method(as_integration,default)
-S3method(as_integration,list)
 S3method(as_tibble,connect_integration_list)
 S3method(as_tibble,connect_list_hits)
 S3method(connect_vars,op_base)
@@ -60,12 +58,14 @@ export(content_title)
 export(content_update)
 export(content_update_access_type)
 export(content_update_owner)
+export(create_integration)
 export(create_random_name)
 export(create_tag)
 export(create_tag_tree)
 export(dashboard_url)
 export(delete_bundle)
 export(delete_image)
+export(delete_integration)
 export(delete_runtime_cache)
 export(delete_tag)
 export(delete_thumbnail)
@@ -162,6 +162,7 @@ export(swap_vanity_url)
 export(swap_vanity_urls)
 export(tbl_connect)
 export(terminate_jobs)
+export(update_integration)
 export(user_guid_from_username)
 export(users_create_remote)
 export(vanity_is_available)

NEWS.md

@@ -6,6 +6,9 @@
   from a Connect server. (#431)
 - `get_integrations()` can now be passed a `Content` class object to retrieve a
   list of integrations associated with that piece of content. (#432)
+- New functions allow you to manage the OAuth integrations on your Connect
+  server: `create_integration()`, `update_integration()` and
+  `delete_integration()`. (#434)
 
 # connectapi 0.8.0
 

R/integrations.R

@@ -11,7 +11,7 @@
 #' @param x A `Connect` or `Content` R6 object.
 #'
 #' @return A list of class `connect_integration_list`, where each element is a `connect_integration` object
-#'   with the following fields (all character strings unless noted otherwise):
+#'   with the following fields. (Raw API fields are character strings unless noted otherwise):
 #'
 #'   * `id`: The internal identifier of this OAuth integration.
 #'   * `guid`: The GUID of this OAuth integration.
@@ -67,15 +67,15 @@ get_integrations.default <- function(x) {
   stop(
     "Cannot get integrations for an object of class '",
     class(x)[1],
-    "'"
+    "'. 'x' must be a 'Connect' or 'Content' object."
   )
 }
 
 #' @export
 get_integrations.Connect <- function(x) {
   error_if_less_than(x$version, "2024.12.0")
   integrations <- x$GET(v1_url("oauth", "integrations"))
-  integrations <- lapply(integrations, as_integration)
+  integrations <- purrr::map(integrations, ~ as_integration(.x, client = x))
   class(integrations) <- c("connect_integration_list", class(integrations))
   integrations
 }
@@ -101,7 +101,7 @@ get_integrations.Content <- function(x) {
 #' Convert integrations list to a data frame
 #'
 #' @description
-#' Converts an list returned by [get_integrations()] into a data frame.
+#' Converts a list returned by [get_integrations()] into a data frame.
 #'
 #' @param x A `connect_integration_list` object (from [get_integrations()]).
 #' @param row.names Passed to [base::as.data.frame()].
@@ -144,25 +144,20 @@ as_tibble.connect_integration_list <- function(x, ...) {
 #' Convert objects to integration class
 #'
 #' @param x An object to convert to an integration.
-#' @param ... Unused.
+#' @param client The Connect client object where the integration comes from.
 #'
-#' @return An integration object
-as_integration <- function(x, ...) {
-  UseMethod("as_integration")
-}
-
-#' @export
-as_integration.default <- function(x, ...) {
-  stop(
-    "Cannot convert object of class '",
-    class(x)[1],
-    "' to an integration"
-  )
-}
-
-#' @export
-as_integration.list <- function(x, ...) {
-  structure(x, class = c("connect_integration", "list"))
+#' @return An integration object. The object has all the fields from the
+#' integrations endpoint (see [get_integrations()]) and a Connect client as a
+#' `client` attribute (`attr(x, "client")`)
+as_integration <- function(x, client) {
+  if (!inherits(x, "list")) {
+    stop(
+      "Cannot convert object of class '",
+      class(x)[1],
+      "' to an integration"
+    )
+  }
+  structure(x, class = c("connect_integration", "list"), client = client)
 }
 
 #' @export
@@ -212,10 +207,11 @@ print.connect_integration <- function(x, ...) {
 #' @export
 get_integration <- function(client, guid) {
   validate_R6_class(client, "Connect")
-  as_integration(client$GET(v1_url("oauth", "integrations", guid)))
+  error_if_less_than(client$version, "2024.12.0")
+  as_integration(client$GET(v1_url("oauth", "integrations", guid)), client)
 }
 
-# Get and set integrations on content
+# Get and set integrations on content ----
 
 #' Set all OAuth integrations for a content item
 #'
@@ -341,3 +337,209 @@ get_associations <- function(x) {
     "associations"
   ))
 }
+
+
+# Manage integrations ----
+
+#' Create an OAuth integration
+#'
+#' @description
+#' Creates a new OAuth integration on the Posit Connect server. OAuth integrations
+#' allow content to access external resources using OAuth credentials.
+#'
+#' You must have administrator privileges to perform this action.
+#'
+#' See the Posit Connect documentation on
+#' [OAuth integrations](https://docs.posit.co/connect/admin/integrations/oauth-integrations/) for
+#' more information.
+#'
+#' @param client A `Connect` R6 client object.
+#' @param name A descriptive name to identify the integration.
+#' @param description Optional, default `NULL.` A brief description of the integration.
+#' @param template The template to use to configure this integration (e.g.,
+#'   "custom", "github", "google", "connect").
+#' @param config A list containing the configuration for the integration. The
+#'   required fields vary depending on the template selected.
+#'
+#' @return A `connect_integration` object representing the newly created
+#'   integration. See [get_integration()] for details on the returned object.
+#'
+#' @seealso [get_integrations()], [get_integration()], [update_integration()],
+#'   [delete_integration()]
+#'
+#' @examples
+#' \dontrun{
+#' client <- connect()
+#'
+#' # Create a GitHub OAuth integration
+#' github_integration <- create_integration(
+#'   client,
+#'   name = "GitHub Integration",
+#'   description = "Integration with GitHub for OAuth access",
+#'   template = "github",
+#'   config = list(
+#'     client_id = "your-client-id",
+#'     client_secret = "your-client-secret"
+#'   )
+#' )
+#'
+#' # Create a custom OAuth integration
+#' custom_integration <- create_integration(
+#'   client,
+#'   name = "Custom API Integration",
+#'   description = "Integration with our custom API",
+#'   template = "custom",
+#'   config = list(
+#'     auth_mode = "Confidential",
+#'     auth_type = "Viewer",
+#'     authorization_uri = "https://api.example.com/oauth/authorize",
+#'     client_id = "your-client-id",
+#'     client_secret = "your-client-secret",
+#'     token_uri = "https://api.example.com/oauth/token"
+#'   )
+#' )
+#' }
+#'
+#' @family oauth integration functions
+#' @export
+create_integration <- function(
+  client,
+  name,
+  description = NULL,
+  template,
+  config
+) {
+  validate_R6_class(client, "Connect")
+  error_if_less_than(client$version, "2024.12.0")
+  result <- client$POST(
+    v1_url("oauth", "integrations"),
+    body = list(
+      name = name,
+      description = description,
+      template = template,
+      config = config
+    )
+  )
+  as_integration(result, client)
+}
+
+#' Update an OAuth integration
+#'
+#' @description
+#' Updates an existing OAuth integration. All fields except `integration` are optional,
+#' and are unchanged if not provided.
+#'
+#' You must have administrator privileges to perform this action.
+#'
+#' See the Posit Connect documentation on
+#' [OAuth integrations](https://docs.posit.co/connect/admin/integrations/oauth-integrations/) for
+#' more information.
+#'
+#' @param integration A `connect_integration` object (as returned by [get_integrations()],
+#'   [get_integration()], or [create_integration()]).
+#' @param name A new name for the integration.
+#' @param description A new description for the integration.
+#' @param template The template to use (generally not changed after creation).
+#' @param config A list with updated OAuth integration configuration. If `NULL`
+#'   (default), the configuration remains unchanged. You can update individual
+#'   configuration fields without affecting others.
+#'
+#' @return A `connect_integration` object representing the updated OAuth
+#'   integration. See [get_integration()] for details on the returned object.
+#'
+#' @seealso [get_integrations()], [get_integration()], [create_integration()],
+#'   [delete_integration()]
+#'
+#' @examples
+#' \dontrun{
+#' client <- connect()
+#'
+#' # Get an existing integration
+#' integration <- get_integration(client, "your-integration-guid")
+#'
+#' # Update the integration's name and description
+#' updated_integration <- update_integration(
+#'   integration,
+#'   name = "Updated GitHub Integration",
+#'   description = "A more descriptive description."
+#' )
+#'
+#' # Update only the client secret in the configuration
+#' updated_integration <- update_integration(
+#'   integration,
+#'   config = list(
+#'     client_secret = "your-new-client-secret"
+#'   )
+#' )
+#' }
+#'
+#' @family oauth integration functions
+#' @export
+update_integration <- function(
+  integration,
+  name = NULL,
+  description = NULL,
+  template = NULL,
+  config = NULL
+) {
+  if (!inherits(integration, "connect_integration")) {
+    stop("'integration' must be a 'connect_integration' object")
+  }
+  client <- attr(integration, "client")
+  validate_R6_class(client, "Connect")
+  error_if_less_than(client$version, "2024.12.0")
+  result <- client$PATCH(
+    v1_url("oauth", "integrations", integration$guid),
+    body = list(
+      name = name,
+      description = description,
+      template = template,
+      config = config
+    )
+  )
+  as_integration(result, client)
+}
+
+#' Delete an OAuth integration
+#'
+#' @description
+#' Deletes an OAuth integration from the Posit Connect server. This permanently
+#' removes the integration and any associated content associations.
+#'
+#' You must have administrator privileges to perform this action.
+#'
+#' See the Posit Connect documentation on
+#' [OAuth integrations](https://docs.posit.co/connect/admin/integrations/oauth-integrations/) for
+#' more information.
+#'
+#' @param integration A `connect_integration` object (as returned by [get_integrations()],
+#'   [get_integration()], or [create_integration()]).
+#'
+#' @return Returns `NULL` invisibly if successful.
+#'
+#' @seealso [get_integrations()], [get_integration()], [create_integration()],
+#'   [update_integration()]
+#'
+#' @examples
+#' \dontrun{
+#' client <- connect()
+#'
+#' # Get an integration to delete
+#' integration <- get_integration(client, "your-integration-guid")
+#'
+#' # Delete the integration
+#' delete_integration(integration)
+#' }
+#'
+#' @family oauth integration functions
+#' @export
+delete_integration <- function(integration) {
+  if (!inherits(integration, "connect_integration")) {
+    stop("'integration' must be a 'connect_integration' object")
+  }
+  client <- attr(integration, "client")
+  validate_R6_class(client, "Connect")
+  error_if_less_than(client$version, "2024.12.0")
+  client$DELETE(v1_url("oauth", "integrations", integration$guid))
+  invisible(NULL)
+}

R/utils-ci.R

@@ -107,10 +107,6 @@ compose_find_hosts <- function(prefix) {
   ports <- sub(".*0\\.0\\.0\\.0:([0-9]+)->3939.*", "\\1", containers)
   cat_line(glue::glue("docker: got ports {ports[1]} and {ports[2]}"))
 
-  # TODO: make this silly sleep more savvy
-  cat_line("connect: sleeping - waiting for connect to start")
-  Sys.sleep(10)
-
   paste0("http://localhost:", ports)
 }
 
@@ -139,7 +135,9 @@ update_renviron_creds <- function(
     "{prefix}_API_KEY={api_key}",
     .sep = "\n"
   )
-  if (!fs::file_exists(.file)) fs::file_touch(.file)
+  if (!fs::file_exists(.file)) {
+    fs::file_touch(.file)
+  }
   writeLines(output_environ, .file)
   invisible()
 }
@@ -164,6 +162,36 @@ build_test_env <- function(
   # this is a regex so it will match either
   hosts <- compose_find_hosts(prefix = "ci.connect")
 
+  wait_for_connect_ready <- function(host, timeout = 120) {
+    client <- HackyConnect$new(server = host, api_key = NULL)
+    start_time <- Sys.time()
+    last_msg <- start_time
+    ping_url <- client$server_url("__ping__")
+
+    while (
+      as.numeric(difftime(Sys.time(), start_time, units = "secs")) < timeout
+    ) {
+      ok <- try(
+        {
+          res <- client$GET(url = client$server_url("__ping__"), parser = NULL)
+          httr::status_code(res) == 200
+        }
+      )
+      if (isTRUE(ok)) {
+        return(invisible(TRUE))
+      }
+      if (difftime(Sys.time(), last_msg, units = "secs") >= 5) {
+        cat_line(glue::glue("waiting for {ping_url} ..."))
+        last_msg <- Sys.time()
+      }
+      Sys.sleep(1)
+    }
+    stop("Connect did not become ready in time: ", ping_url)
+  }
+
+  wait_for_connect_ready(hosts[1])
+  wait_for_connect_ready(hosts[2])
+
   cat_line("connect: creating first admin...")
   a1 <- create_first_admin(
     hosts[1],