feat: add functions to get_runtime_caches() and delete_runtime_caches() (#318)

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

Author: toph-allen

NAMESPACE

@@ -57,6 +57,7 @@ export(dashboard_url)
 export(dashboard_url_chr)
 export(delete_bundle)
 export(delete_image)
+export(delete_runtime_cache)
 export(delete_tag)
 export(delete_thumbnail)
 export(delete_vanity_url)
@@ -83,6 +84,7 @@ export(get_jobs)
 export(get_my_permission)
 export(get_oauth_credentials)
 export(get_procs)
+export(get_runtime_caches)
 export(get_tag_data)
 export(get_tags)
 export(get_thumbnail)

NEWS.md

@@ -10,6 +10,9 @@
 - `groups_create_remote()` now has an `exact` parameter. Setting `exact` causes
   the function to consider only exact group name matches when searching for
   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)
+
 
 ## Lifecycle changes
 
@@ -26,6 +29,8 @@
 - Upgrade `pkgdown` to bootstrap 5 to enable search (@fh-mthomson, #275)
 - The `get_timezones()` function now uses the `v1/timezones` endpoint if
   available. (#300)
+- `connect$DELETE()` now respects the `parser` argument rather than always using
+  `NULL`.
 
 # connectapi 0.3.0
 

R/connect.R

@@ -196,7 +196,7 @@ Connect <- R6::R6Class(
     #' will be returned. Otherwise, the argument is forwarded to
     #' `httr::content(res, as = parser)`.
     DELETE = function(path, ..., url = self$api_url(path), parser = NULL) {
-      self$request("DELETE", url, parser = NULL, ...)
+      self$request("DELETE", url, parser = parser, ...)
     },
 
     #' @description Perform an HTTP PATCH request of the named API path.

R/runtime-caches.R

@@ -0,0 +1,76 @@
+#' Get runtime caches
+#' 
+#' View the runtime caches on a Connect server.
+#' Requires Administrator privileges.
+#' 
+#' @param client A `Connect` object.
+#' 
+#' @returns A tibble of runtime caches on the server, showing `language`,
+#' `version` and `image_name`. For Connect servers not using off-host execution,
+#' `image_name` is `"Local"`.
+#' 
+#' @examples
+#' \dontrun{
+#' client <- connect()
+#' get_runtime_caches(client)
+#' }
+#' 
+#' @family server management functions
+#' @seealso [delete_runtime_cache()]
+#' @export
+get_runtime_caches <- function(client) {
+  validate_R6_class(client, "Connect")
+  res <- client$GET(v1_url("system/caches/runtime"))
+  purrr::map_dfr(res$caches, ~.x)
+}
+
+#' Delete a runtime cache
+#' 
+#' Delete a runtime cache from a Connect server.
+#' Requires Administrator privileges.
+#' 
+#' @param client A `Connect` object.
+#' @param language The language of the cache, either "R" or "Python".
+#' @param version The version of the cache, e.g. "4.3.3".
+#' @param image_name Optional. The name of the off-host execution image for
+#'   the cache, or "Local" (the default) for native execution caches.
+#' @param dry_run Optional, default `FALSE`. If true, perform a dry run of
+#'   the deletion.
+#'
+#' @returns A `Task` object representing the deletion task. If `dry_run` is
+#' `TRUE`, returns `NULL` or throws an error if the deletion would fail.
+#'
+#' @examples
+#' \dontrun{
+#' client <- connect()
+#' task <- delete_runtime_cache(client, "R", "4.3.3")
+#' poll_task(task)
+#' }
+#' 
+#' @family server management functions
+#' @seealso [get_runtime_caches()]
+#' @export
+delete_runtime_cache <- function(client, language, version, image_name = "Local", dry_run = FALSE) {
+  res <- client$DELETE(
+    path = v1_url("system/caches/runtime"),
+    body = list(
+      language = language,
+      version = version,
+      image_name = image_name,
+      dry_run = dry_run
+    ),
+    encode = "json",
+    parser = "parsed"
+  )
+
+  if (dry_run == TRUE) {
+    message(glue::glue(
+      "Runtime cache deletion dry run did not encounter any errors ",
+      '(language = "{language}", version = "{version}", image_name = "{image_name}")'
+    ))
+    return(invisible(NULL))
+  }
+
+  task_data <- client$GET(v1_url("tasks", res$task_id))
+  Task$new(client, task_data)
+}

_pkgdown.yml

@@ -69,7 +69,7 @@ reference:
 
   - title: "Other"
     desc: >
-      Oher functions
+      Other functions
     contents:
       - promote
       - connect
@@ -81,6 +81,7 @@ reference:
       - create_random_name
       - dashboard_url
       - dashboard_url_chr
+      - delete_runtime_cache
 
 
   - title: "R6 classes"

man/delete_runtime_cache.Rd

@@ -0,0 +1,6 @@
+{
+    "language": "Python",
+    "version": "3.11.3",
+    "image_name": "Local",
+    "task_id": "eKm0RFxyzIKR3jnI"
+}

man/get_runtime_caches.Rd

@@ -0,0 +1,6 @@
+{
+    "language": "Python",
+    "version": "3.11.3",
+    "image_name": "Local",
+    "task_id": null
+}

tests/testthat/2024.08.0/__api__/v1/system/caches/runtime-399c82-DELETE.json

@@ -0,0 +1,8 @@
+structure(
+  list(
+    request <- list(url = "__api__/v1/system/caches/runtime"),
+    url = "__api__/v1/system/caches/runtime", status_code = 404L,
+    content = charToRaw("{\"code\":4,\"error\":\"Cache does not exist\",\"payload\":null}")
+  ),
+  class = "response"
+)

tests/testthat/2024.08.0/__api__/v1/system/caches/runtime-9dcc8a-DELETE.json

@@ -0,0 +1,14 @@
+{
+    "caches": [
+        {
+            "language": "R",
+            "version": "4.3.0",
+            "image_name": "Local"
+        },
+        {
+            "language": "Python",
+            "version": "3.11.3",
+            "image_name": "Local"
+        }
+    ]
+}

tests/testthat/2024.08.0/__api__/v1/system/caches/runtime-f2c7a9-DELETE.R

@@ -0,0 +1,11 @@
+{
+    "id": "eKm0RFxyzIKR3jnI",
+    "output": [
+        "Deleting runtime cache..."
+    ],
+    "result": null,
+    "finished": false,
+    "code": 0,
+    "error": "",
+    "last": 1
+}

tests/testthat/2024.08.0/__api__/v1/system/caches/runtime.json

@@ -0,0 +1,39 @@
+with_mock_api({
+  client <- connect(server = "https://connect.example", api_key = "fake")
+
+  test_that("get_runtime_caches() gets runtime caches", {
+    caches <- get_runtime_caches(client)
+    expect_equal(
+      get_runtime_caches(client),
+      tibble::tibble(
+        language = c("R", "Python"),
+        version = c("4.3.0", "3.11.3"),
+        image_name = c("Local", "Local")
+      )
+    )
+  })
+
+  test_that("delete_runtime_cache() prints message and returns NULL when dry_run == TRUE", {
+    expect_message(
+      res <- delete_runtime_cache(client, "Python", "3.11.3", dry_run = TRUE),
+      paste0(
+        "Runtime cache deletion dry run did not encounter any errors ",
+        '\\(language = "Python", version = "3.11.3", image_name = "Local"\\)'
+      )
+    )
+    expect_null(res)
+  })
+
+  test_that("delete_runtime_cache() returns a task object when dry_run == FALSE", {
+    res <- delete_runtime_cache(client, "Python", "3.11.3")
+    expect_true(validate_R6_class(res, "Task"))
+    expect_equal(res$task$id, "eKm0RFxyzIKR3jnI")
+  })
+
+  test_that("delete_runtime_cache() on a nonexistent cache throws a 404 error", {
+    expect_error(
+      delete_runtime_cache(client, "Python", "3.11.2"),
+      "request failed with Client error: \\(404\\) Not Found"
+    )
+  })
+})