Add function to get_runtimes() from Connect server (#320)

Co-authored-by: Barret Schloerke <[email protected]>

Author: toph-allen

NAMESPACE

@@ -85,6 +85,7 @@ export(get_my_permission)
 export(get_oauth_credentials)
 export(get_procs)
 export(get_runtime_caches)
+export(get_runtimes)
 export(get_tag_data)
 export(get_tags)
 export(get_thumbnail)

NEWS.md

@@ -12,7 +12,8 @@
   remote groups and checking for existing local groups. (#216)
 - New functions to let you view and delete runtime caches on a Connect server:
   `get_runtime_caches()`, `delete_runtime_cache()` (#312)
-
+- New `get_runtimes()` lets you view available runtimes and versions on a
+  Connect server. (#311)
 
 ## Lifecycle changes
 
@@ -23,6 +24,8 @@
   `set_thumbnail()`, which works both with local file paths and remote URLs to
   images. Likewise, `has_image()` and `delete_image()` have been deprecated in
   favor of `has_thumbnail()` and `delete_thumbnail()`. (#294, #304)
+- `Connect$server_settings_r()` has been deprecated in favor of
+  `get_runtimes(client, "r")`. (#311)
 
 ## Minor improvements and fixes
 

R/connect.R

@@ -824,6 +824,7 @@ Connect <- R6::R6Class(
 
     #' @description Get R installations.
     server_settings_r = function() {
+      lifecycle::deprecate_soft("0.3.1", "Connect$server_settings_r()", "get_runtimes()")
       self$GET(v1_url("server_settings", "r"))
     },
 

R/get.R

@@ -702,3 +702,59 @@ get_oauth_credentials = function(connect, user_session_token) {
     body = body
   )
 }
+
+#' Get available runtimes on server
+#' 
+#' Get a table showing available versions of R, Python, Quarto, and Tensorflow
+#' on the Connect server.
+#' 
+#' @param client A `Connect` object.
+#' @param runtimes Optional. A character vector of runtimes to include. Must be
+#' some combination of `"r"`, `"python"`, `"quarto"`, and `"tensorflow"`. Quarto
+#' is only supported on Connect >= 2021.08.0, and Tensorflow is only supported
+#' on Connect >= 2024.03.0.
+
+#' @return A tibble with columns for `runtime`, `version`, and `cluster_name`
+#' and `image_name`. Cluster name and image name are only meaningful on Connect
+#' instances running off-host execution.
+#' 
+#' @examples
+#' \dontrun{
+#' library(connectapi)
+#' client <- connect()
+#' get_runtimes(client, runtimes = c("r", "python", "tensorflow"))
+#' }
+#' 
+#' @export
+get_runtimes <- function(client, runtimes = NULL) {
+  validate_R6_class(client, "Connect")
+
+  # Construct valid runtimes for the Connect version.
+  supported <- c(
+    "r",
+    "python",
+    if (compare_connect_version(client$version, "2021.08.0") >= 0) {
+      "quarto"
+    },
+    if (compare_connect_version(client$version, "2024.05.0") >= 0) {
+      "tensorflow"
+    }
+  )
+  if (is.null(runtimes)) {
+    runtimes <- supported
+  } else {
+    if (any(!runtimes %in% supported)) {
+      stop(glue::glue(
+        "`runtimes` must be one of ",
+        "{paste(paste0('\"', supported, '\"'), collapse = ', ')}; ",
+        "received: {paste(paste0('\"', runtimes, '\"'), collapse = ', ')}."
+      ))
+    }
+  }
+
+  purrr::map_dfr(runtimes, function(runtime) {
+    res <- client$GET(paste0("v1/server_settings/", runtime))
+    res_df <- purrr::map_dfr(res$installations, ~tibble::as_tibble(.))
+    tibble::add_column(res_df, runtime = runtime, .before = 1)
+  })
+}

man/get_groups.Rd

@@ -79,7 +79,8 @@ MockConnect <- R6Class(
     # same URL.
     mock_response = function(method, path, content, status_code = 200L, headers = c("Content-Type" = "application/json; charset=utf-8")) {
       url <- self$api_url(path)
-    
+      route <- paste(method, url)
+
       res <- new_mock_response(url, content, status_code, headers)
 
       route <- paste(method, url)

man/get_runtimes.Rd

@@ -0,0 +1,117 @@
+test_that("get_runtimes() gets all runtimes if none specified", {
+  client <- MockConnect$new("2024.10.0")
+
+  client$mock_response(
+    "GET", "v1/server_settings/r",
+    content = list(
+      installations = list(
+        list(version = "4.3.1", cluster_name = "Local", image_name = "Local"), 
+        list(version = "4.4.0", cluster_name = "Local", image_name = "Local")
+      )
+    )
+  )
+  client$mock_response(
+    "GET", "v1/server_settings/python",
+    content = list(
+      installations = list(
+        list(version = "3.11.3", cluster_name = "Local", image_name = "Local"), 
+        list(version = "3.12.4", cluster_name = "Local", image_name = "Local")
+      )
+    )
+  )
+  client$mock_response(
+    "GET", "v1/server_settings/quarto",
+    content = list(
+      installations = list(
+        list(version = "1.4.557", cluster_name = "Local", image_name = "Local"), 
+        list(version = "1.5.55", cluster_name = "Local", image_name = "Local")
+      )
+    )
+  )
+  client$mock_response(
+    "GET", "v1/server_settings/tensorflow",
+    content = list(
+      installations = list(
+        list(version = "2.16.1", cluster_name = "Local", image_name = "Local")
+      )
+    )
+  )
+
+  expected <- tibble::as_tibble(list(
+    runtime = c(
+    "r", "r", "python", "python", "quarto",
+    "quarto", "tensorflow"
+    ), version = c(
+      "4.3.1", "4.4.0", "3.11.3",
+      "3.12.4", "1.4.557", "1.5.55", "2.16.1"
+    ), cluster_name = c(
+      "Local",
+      "Local", "Local", "Local", "Local", "Local", "Local"
+    ), image_name = c(
+      "Local",
+      "Local", "Local", "Local", "Local", "Local", "Local"
+    )
+  ))
+  expect_identical(get_runtimes(client), expected)
+  expect_identical(client$call_log, c(
+    "GET https://connect.example/__api__/v1/server_settings/r",
+    "GET https://connect.example/__api__/v1/server_settings/python",
+    "GET https://connect.example/__api__/v1/server_settings/quarto",
+    "GET https://connect.example/__api__/v1/server_settings/tensorflow"
+  ))
+})
+
+test_that("get_runtimes() only specified runtimes", {
+  client <- MockConnect$new("2024.10.0")
+
+  client$mock_response(
+    "GET", "v1/server_settings/python",
+    content = list(
+      installations = list(
+        list(version = "3.11.3", cluster_name = "Local", image_name = "Local"), 
+        list(version = "3.12.4", cluster_name = "Local", image_name = "Local")
+      )
+    )
+  )
+  client$mock_response(
+    "GET", "v1/server_settings/tensorflow",
+    content = list(
+      installations = list(
+        list(version = "2.16.1", cluster_name = "Local", image_name = "Local")
+      )
+    )
+  )
+
+  expected <- tibble::as_tibble(list(
+    runtime = c("python", "python", "tensorflow"),
+    version = c("3.11.3", "3.12.4", "2.16.1"),
+    cluster_name = c("Local", "Local", "Local"), 
+    image_name = c("Local", "Local", "Local")
+  ))
+  expect_identical(get_runtimes(client, c("python", "tensorflow")), expected)
+  expect_identical(client$call_log, c(
+    "GET https://connect.example/__api__/v1/server_settings/python",
+    "GET https://connect.example/__api__/v1/server_settings/tensorflow"
+  ))
+})
+
+test_that("get_runtimes() restricts available runtimes based on Connect version.", {
+  client <- MockConnect$new("2024.10.0")
+  expect_error(
+    get_runtimes(client, c("r", "python", "foofy")),
+    '`runtimes` must be one of "r", "python", "quarto", "tensorflow"; received: "r", "python", "foofy".'
+  )
+
+  client <- MockConnect$new("2024.02.0")
+  expect_error(
+    get_runtimes(client, "tensorflow"),
+    '`runtimes` must be one of "r", "python", "quarto"; received: "tensorflow".'
+  )
+
+  client <- MockConnect$new("1.8.3")
+  expect_error(
+    get_runtimes(client, c("r", "quarto")),
+    '`runtimes` must be one of "r", "python"; received: "r", "quarto".'
+  )
+})
+

tests/testthat/setup.R

@@ -1,5 +1,4 @@
 test_that("get_timezones() gets timeszones from v1 url when available", {
-  # With version available
   client <- MockConnect$new()
 
   client$mock_response(