diff --git a/.github/actions/prepare-test-runtime/action.yml b/.github/actions/prepare-test-runtime/action.yml index 098f8b037..420de66f5 100644 --- a/.github/actions/prepare-test-runtime/action.yml +++ b/.github/actions/prepare-test-runtime/action.yml @@ -37,27 +37,19 @@ runs: - name: Compile test files run: pnpm run clean && pnpm exec tsc shell: bash - - name: Install arf binary for Interactive tests + # src/test/node/mise.toml and mise.lock pin the arf version and its + # checksums. + - name: Install arf for Interactive tests + if: runner.os != 'Windows' + uses: jdx/mise-action@6612f0ef07ed2a736cd1e00a94a065522dd41195 # v5.2.5 + with: + working_directory: src/test/node + - name: Expose arf for Interactive tests if: runner.os != 'Windows' shell: bash - env: - RUNNER_OS_NAME: ${{ runner.os }} + working-directory: src/test/node run: | - ARF_ARCH="$(uname -m)" - if [ "${ARF_ARCH}" = "arm64" ]; then ARF_ARCH="aarch64"; fi - if [ "${RUNNER_OS_NAME}" = "macOS" ]; then - ARF_TARGET="${ARF_ARCH}-apple-darwin" - else - ARF_TARGET="${ARF_ARCH}-unknown-linux-gnu" - fi - ARF_ARCHIVE="arf-console-${ARF_TARGET}.tar.xz" - ARF_RELEASE="https://github.com/eitsupi/arf/releases/download/v0.5.3" - curl -fsSL "${ARF_RELEASE}/${ARF_ARCHIVE}" -o "${RUNNER_TEMP}/${ARF_ARCHIVE}" - curl -fsSL "${ARF_RELEASE}/sha256.sum" -o "${RUNNER_TEMP}/arf.sha256" - (cd "${RUNNER_TEMP}" && awk -v name="${ARF_ARCHIVE}" '$2 == name || $2 == "*" name' arf.sha256 > arf-selected.sha256 && test -s arf-selected.sha256 && shasum -a 256 -c arf-selected.sha256) - mkdir -p "${RUNNER_TEMP}/arf" - tar -xJf "${RUNNER_TEMP}/${ARF_ARCHIVE}" -C "${RUNNER_TEMP}/arf" - ARF_EXECUTABLE=$(find "${RUNNER_TEMP}/arf" -type f -name arf | head -n 1) - test -n "${ARF_EXECUTABLE}" - echo "$(dirname "${ARF_EXECUTABLE}")" >> "$GITHUB_PATH" + ARF_EXECUTABLE="$(mise which arf)" + test -x "${ARF_EXECUTABLE}" + "${ARF_EXECUTABLE}" --version echo "ARF_PATH=${ARF_EXECUTABLE}" >> "$GITHUB_ENV" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d49b5cfa8..987614d34 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -86,7 +86,7 @@ Interactive session. Run the source/bootstrap checks with The [architecture and backend contract](src/interactive/README.md) live beside the implementation. User setup and behavior belong in the [R Interactive documentation page](https://reditorsupport.github.io/vscode-R/features/r-interactive). -Use Linux or macOS for Interactive runtime tests, with R and an installed arf 0.5.3 executable. Bundled sess is pure R and needs no compiler when its Imports are already installed; missing Imports are installed from the configured repository. Windows runs the remaining extension checks; persistent Interactive supervision remains limited to Linux/macOS. From the repository root, after installing pnpm dependencies, prepare a test library: +Use Linux or macOS for Interactive runtime tests, with R and arf 0.7.2-rc.1 or later. Running `mise install` in `src/test/node` installs the arf version pinned in `src/test/node/mise.toml`, which CI also uses. Bundled sess is pure R and needs no compiler when its Imports are already installed; missing Imports are installed from the configured repository. Windows runs the remaining extension checks; persistent Interactive supervision remains limited to Linux/macOS. From the repository root, after installing pnpm dependencies, prepare a test library: ```sh export R_LIBS=/path/to/test-library @@ -106,6 +106,8 @@ pnpm run pretest VSCR_TEST_TMUX=1 pnpm exec mocha out/test/node/interactiveRuntime.test.js --ui tdd --timeout 60000 --grep "standalone agent survives its launcher process exiting" ``` +Inspection runs as arf handler calls, whose output is captured. Tests that need to know when inspection code has started should have the R code write a file rather than wait for output. + The provider is arf. `ARF_PATH` selects its executable; `VSCR_TEST_STATIC=1` selects standard graphics. The tmux variant needs tmux and exercises a real supervised agent, as Linux CI does. These variables can be combined. Check skipped tests when assessing coverage: a missing optional runtime or package is not a verified pass for that feature. `pnpm run test` prepares the bundle and test files, runs `src/test/node/` directly diff --git a/sess/R/dispatch.R b/sess/R/dispatch.R index ac14cac18..84a8b036b 100644 --- a/sess/R/dispatch.R +++ b/sess/R/dispatch.R @@ -1,3 +1,12 @@ +#' Serialize a message with the settings used for every IPC frame (internal) +#' +#' Sharing one encoder keeps the frames on the socket and the results of arf handler calls identical +#' for the same R value. +#' @keywords internal +ipc_json <- function(data) { + jsonlite::toJSON(data, auto_unbox = TRUE, null = "null", force = TRUE, digits = NA) +} + #' Write a JSON object to the IPC pipe as a NDJSON line (internal) #' @keywords internal ipc_write <- function(data) { @@ -12,7 +21,7 @@ ipc_write <- function(data) { return(invisible(FALSE)) } - json <- jsonlite::toJSON(data, auto_unbox = TRUE, null = "null", force = TRUE, digits = NA) + json <- ipc_json(data) line <- c(charToRaw(enc2utf8(json)), as.raw(0x0a)) tryCatch( { diff --git a/sess/R/inspection_call.R b/sess/R/inspection_call.R new file mode 100644 index 000000000..e15ce1ecc --- /dev/null +++ b/sess/R/inspection_call.R @@ -0,0 +1,286 @@ +# Inspection methods for handler calls published through arf's `--ipc-expose`. +# +# Interactive reaches the same per-method logic through two transports: +# +# - The sess socket runs a request from a `later` callback, where arf does not +# deliver interrupts, so a slow request cannot be stopped. +# - An arf handler call runs on the R thread under an execution deadline, and +# arf interrupts the handler when the deadline passes. +# +# Both use the handlers of `inspection_handlers()`. Both resolve `hover` and +# `completion` with `inspection_hover()` and `inspection_completion()`, which +# never evaluate the request text. The socket turns every error into no result, +# while a handler call reports it, so the client can tell an invalid request +# from a failure. Handlers published to arf run outside arf's evaluation policy +# and approval, so they must not accept code from the client. +# +# Contract of the `vscode-r.inspect.json` namespace: a handler takes the method +# parameters as one JSON string, the same object the socket carries as +# `params`, and returns the result as one JSON string. The string is a JSON +# object with `version` and, unless the result is NULL, `result`. Omitting +# `result` for NULL keeps NULL distinct from NA, as in a socket reply. A +# strict-JSON variant that needs no string decoding would use another +# namespace. + +inspection_call_namespace <- "vscode-r.inspect.json" + +# The only methods that can be called. `interactive_stop` and `plot_latest` stay +# on the socket, and no entry point selects a function by name. +inspection_call_methods <- c( + "workspace", + "workspace_children", + "workspace_view", + "listview_navigate", + "listview_view", + "hover", + "completion", + "dataview_init", + "dataview_page", + "dataview_dispose" +) + +# Encoded results beyond this size would exceed the client's frame limit. +inspection_call_max_bytes <- 4L * 1024L * 1024L + +# Per-method logic shared by the socket and handler calls. Each function takes +# the decoded parameters of its request. +inspection_handlers <- function() { + list( + workspace = function(p) get_workspace_data(p$revision), + workspace_children = function(p) get_workspace_children(p$name, p$path, p$start, p$view_id), + workspace_view = function(p) handle_workspace_view(p$name, p$path), + listview_navigate = function(p) handle_listview_navigate(p$view_id, p$path), + listview_view = function(p) handle_listview_view(p$view_id, p$index, p$path), + dataview_init = function(p) handle_dataview_init(p), + dataview_page = function(p) handle_dataview_page(p), + dataview_dispose = function(p) handle_dataview_dispose(p) + ) +} + +# The table that handler calls dispatch through, in the order of +# `inspection_call_methods`. +inspection_call_handlers <- function() { + handlers <- c( + inspection_handlers(), + list( + hover = function(p) inspection_hover(p$expr), + completion = function(p) inspection_completion(p$expr, p$trigger) + ) + ) + handlers[inspection_call_methods] +} + +# Argument validation. A check returns its value or signals an invalid request. + +inspection_check_string <- function(value, name, max_bytes = 100000L) { + if ( + !is.character(value) || + length(value) != 1L || + is.na(value) || + nchar(value, type = "bytes") > max_bytes + ) { + inspection_invalid(sprintf("%s must be a single string", name)) + } + value +} + +inspection_is_number <- function(value) is.numeric(value) && length(value) == 1L && is.finite(value) + +inspection_check_number <- function(value, name) { + if (!inspection_is_number(value)) { + inspection_invalid(sprintf("%s must be a single finite number", name)) + } + value +} + +inspection_is_index <- function(value) { + inspection_is_number(value) && + value == floor(value) && + value >= 1 && + value <= .Machine$integer.max +} + +inspection_check_index <- function(value, name) { + if (!inspection_is_index(value)) { + inspection_invalid(sprintf("%s must be a positive whole number", name)) + } + value +} + +inspection_check_flag <- function(value, name) { + if (!is.logical(value) || length(value) != 1L || is.na(value)) { + inspection_invalid(sprintf("%s must be TRUE or FALSE", name)) + } + value +} + +inspection_check_list <- function(value, name) { + if (!is.list(value)) { + inspection_invalid(sprintf("%s must be an array or object", name)) + } + value +} + +inspection_max_path <- 10000L + +# A path inside a list view: positive item indices. +inspection_check_index_path <- function(value, name) { + if (!is.list(value) || length(value) > inspection_max_path) { + inspection_invalid(sprintf("%s must be an array of positive whole numbers", name)) + } + for (item in value) { + if (!inspection_is_index(item)) { + inspection_invalid(sprintf("%s must be an array of positive whole numbers", name)) + } + } + value +} + +# A path inside a workspace object: selectors of the kinds that +# `workspace_object()` resolves. +inspection_check_selector_path <- function(value, name) { + if (!is.list(value) || length(value) > inspection_max_path) { + inspection_invalid(sprintf("%s must be an array of selectors", name)) + } + for (item in value) { + kind <- if (is.list(item)) item[["kind"]] else NULL + selector <- if (is.list(item)) item[["value"]] else NULL + valid <- is.character(kind) && + length(kind) == 1L && + !is.na(kind) && + if (identical(kind, "index")) { + inspection_is_index(selector) + } else if (kind %in% c("name", "slot")) { + is.character(selector) && + length(selector) == 1L && + !is.na(selector) && + nzchar(selector) && + nchar(selector, type = "bytes") <= 10000L + } else { + FALSE + } + if (!valid) { + inspection_invalid(sprintf("%s must be an array of selectors", name)) + } + } + value +} + +# Read an optional parameter. NULL, including a JSON null, means absent. +inspection_param <- function(params, name, check, default = NULL, required = FALSE) { + value <- params[[name]] + if (is.null(value)) { + if (required) { + inspection_invalid(sprintf("%s is required", name)) + } + return(default) + } + check(value, name) +} + +# Validate the parameters of one method, and return only the fields that the +# method reads. Fields that are not validated never reach a handler. +inspection_validate <- function(method, params) { + string <- inspection_check_string + number <- inspection_check_number + index <- inspection_check_index + one <- function(name, check, ...) inspection_param(params, name, check, ...) + # Absent fields are omitted rather than set to NULL. + fields <- function(...) Filter(Negate(is.null), list(...)) + switch( + method, + workspace = fields(revision = one("revision", number)), + workspace_children = { + view_id <- one("view_id", string) + name <- one("name", string) + if (is.null(view_id) && is.null(name)) { + inspection_invalid("name or view_id is required") + } + # A list view is addressed by item indices, a workspace object by selectors. + path_check <- if (is.null(view_id)) { + inspection_check_selector_path + } else { + inspection_check_index_path + } + fields( + name = name, + view_id = view_id, + path = one("path", path_check, default = list()), + start = one("start", index, default = 1L) + ) + }, + workspace_view = fields( + name = one("name", string, required = TRUE), + path = one("path", inspection_check_selector_path, default = list()) + ), + listview_navigate = fields( + view_id = one("view_id", string, required = TRUE), + path = one("path", inspection_check_index_path, default = list()) + ), + listview_view = fields( + view_id = one("view_id", string, required = TRUE), + path = one("path", inspection_check_index_path, default = list()), + index = one("index", index, required = TRUE) + ), + hover = fields(expr = one("expr", string, required = TRUE)), + completion = fields( + expr = one("expr", string, required = TRUE), + trigger = one("trigger", string) + ), + dataview_init = fields(view_id = one("view_id", string, required = TRUE)), + dataview_page = fields( + view_id = one("view_id", string, required = TRUE), + startRow = one("startRow", number), + endRow = one("endRow", number), + sortModel = one("sortModel", inspection_check_list), + filterModel = one("filterModel", inspection_check_list), + formatNumbers = one("formatNumbers", inspection_check_flag) + ), + dataview_dispose = fields( + view_id = one("view_id", string, required = TRUE), + state_generation = one("state_generation", number) + ), + inspection_invalid("unknown inspection method") + ) +} + +# Decode the argument string like `dispatch_message()` decodes a socket line. +inspection_decode <- function(args) { + if (!is.character(args) || length(args) != 1L || is.na(args)) { + inspection_invalid("arguments must be one JSON string") + } + params <- tryCatch( + jsonlite::fromJSON(args, simplifyVector = FALSE), + error = function(e) inspection_invalid("arguments are not valid JSON") + ) + # An empty JSON object decodes to a named empty list, an array to a list + # without names. + if (!is.list(params) || (length(params) > 0L && is.null(names(params)))) { + inspection_invalid("arguments must be a JSON object") + } + params +} + +# Encode a result with the socket's settings, as a classless length-1 string. +inspection_encode <- function(result) { + message <- list(version = 1L) + # Assigning NULL leaves the field out, as in a socket reply. + message$result <- result + json <- enc2utf8(as.character(ipc_json(message))) + if (nchar(json, type = "bytes") > inspection_call_max_bytes) { + stop("Inspection result exceeds the size limit", call. = FALSE) + } + json +} + +# Run one inspection method for a handler call. Decoding, the handler and +# encoding all run here so that an execution deadline covers them. Errors and +# interrupts propagate: arf reports them, and neither becomes a value. +inspection_call <- function(method, args) { + handlers <- inspection_call_handlers() + if (!is.character(method) || length(method) != 1L || !method %in% names(handlers)) { + inspection_invalid("unknown inspection method") + } + params <- inspection_validate(method, inspection_decode(args)) + inspection_encode(handlers[[method]](params)) +} diff --git a/sess/R/interactive.R b/sess/R/interactive.R index 78beb36c9..ccd178c1b 100644 --- a/sess/R/interactive.R +++ b/sess/R/interactive.R @@ -53,6 +53,26 @@ invisible(NULL) } +# Under arf, tell the agent which arf execution runs this submission, so that +# it can interrupt that execution by ID. The event carries arf's execution ID. +# Detect the routines on each call: on Unix arf registers them only after +# startup, so an early negative result must not be cached. +.interactive_arf_started <- function(id) { + # arity-lint skip routine-registration: arf registers these routines in the embedding host, not in a package that sess could bind + if ( + is.loaded("arf_api_version", PACKAGE = "(embedding)", type = ".Call") && + identical(.Call("arf_api_version", PACKAGE = "(embedding)"), 1L) + ) { + .Call( + "arf_publish_event", + "vscode-r.interactive.started", + list(id = id), + PACKAGE = "(embedding)" + ) + } + invisible(NULL) +} + .interactive_write <- function(connection, text) { remaining <- processx::conn_write(connection, charToRaw(enc2utf8(text))) while (is.raw(remaining) && length(remaining)) { @@ -333,6 +353,7 @@ interactive_execute <- function(id, code, source = NULL) { # The agent can interrupt as soon as started arrives. Install the condition # handlers before publishing it or doing any interruptible setup work. .interactive_event("started") + .interactive_arf_started(id) .interactive_plot_context() trace_state$depth <- sys.nframe() filename <- if (is.null(source$uri)) "" else source$uri diff --git a/sess/R/server.R b/sess/R/server.R index 082923a6d..48c100470 100644 --- a/sess/R/server.R +++ b/sess/R/server.R @@ -552,22 +552,17 @@ dispatch_message <- function(line) { } } else if (has_method && has_id) { # Request from vscode → R must reply - handlers <- list( - "interactive_stop" = function(p) { - interactive_stop() - TRUE - }, - "workspace" = function(p) get_workspace_data(p$revision), - "workspace_children" = function(p) get_workspace_children(p$name, p$path, p$start, p$view_id), - "workspace_view" = function(p) handle_workspace_view(p$name, p$path), - "hover" = function(p) handle_hover(p$expr), - "completion" = function(p) handle_complete(p$expr, p$trigger), - "plot_latest" = function(p) handle_plot_latest(p), - "listview_navigate" = function(p) handle_listview_navigate(p$view_id, p$path), - "listview_view" = function(p) handle_listview_view(p$view_id, p$index, p$path), - "dataview_init" = function(p) handle_dataview_init(p), - "dataview_page" = function(p) handle_dataview_page(p), - "dataview_dispose" = function(p) handle_dataview_dispose(p) + handlers <- c( + list( + "interactive_stop" = function(p) { + interactive_stop() + TRUE + }, + "hover" = function(p) handle_hover(p$expr), + "completion" = function(p) handle_complete(p$expr, p$trigger), + "plot_latest" = function(p) handle_plot_latest(p) + ), + inspection_handlers() ) if (payload$method %in% names(handlers)) { diff --git a/sess/inst/arf/expose-inspection.R b/sess/inst/arf/expose-inspection.R new file mode 100644 index 000000000..a568afbfe --- /dev/null +++ b/sess/inst/arf/expose-inspection.R @@ -0,0 +1,65 @@ +# Handlers that Interactive publishes to arf with `--ipc-expose`. +# +# arf evaluates the expression after the R profiles and before Interactive loads +# sess from its private library, so this file cannot use sess. Each handler +# finds sess when it is called, and never loads it: loading here or in a handler +# could bring in a different sess from the user's library. A call before +# Interactive has started sess fails with an error instead. +# +# The handlers only forward to `inspection_call()` in sess, which validates the +# arguments, runs the method and encodes the result, all inside the call so that +# the call's execution deadline covers them. The selectors are +# `vscode-r.inspect.json/`; see R/inspection_call.R in sess for the +# contract. The set of methods is fixed here and must match +# `inspection_call_methods` in sess, which the sess tests check. +# +# The file's value is a function of the private library and returns the named +# list for `--ipc-expose`. +function(library) { + namespace <- "vscode-r.inspect.json" + methods <- c( + "workspace", + "workspace_children", + "workspace_view", + "listview_navigate", + "listview_view", + "hover", + "completion", + "dataview_init", + "dataview_page", + "dataview_dispose" + ) + expected <- base::file.path(library, "sess") + + # The namespace of the sess that Interactive started, or an error. + runtime <- function() { + # .getNamespace() returns NULL for a namespace that is not loaded, where + # asNamespace() and loadNamespace() would load it. + ns <- base::.getNamespace("sess") + if (base::is.null(ns)) { + base::stop("The Interactive runtime has not been loaded yet", call. = FALSE) + } + same <- base::identical( + base::normalizePath(base::getNamespaceInfo(ns, "path"), mustWork = FALSE), + base::normalizePath(expected, mustWork = FALSE) + ) + if (!same) { + base::stop("The loaded sess is not the Interactive runtime", call. = FALSE) + } + state <- base::get(".sess_env", envir = ns, inherits = FALSE) + if (!base::isTRUE(state$interactive_connected)) { + base::stop("The Interactive runtime has not started yet", call. = FALSE) + } + ns + } + + handlers <- base::lapply(methods, function(method) { + base::force(method) + function(args) { + call <- base::get("inspection_call", envir = runtime(), inherits = FALSE) + call(method, args) + } + }) + base::names(handlers) <- base::paste0(namespace, "/", methods) + handlers +} diff --git a/sess/inst/tinytest/test-inspection-call.R b/sess/inst/tinytest/test-inspection-call.R new file mode 100644 index 000000000..1846a450f --- /dev/null +++ b/sess/inst/tinytest/test-inspection-call.R @@ -0,0 +1,375 @@ +# Inspection methods published to arf as handler calls. +local({ + ns <- asNamespace("sess") + .sess_env <- sess:::.sess_env + call <- sess:::inspection_call + prefix <- "sess_inspection_call_" + methods <- c( + "workspace", + "workspace_children", + "workspace_view", + "listview_navigate", + "listview_view", + "hover", + "completion", + "dataview_init", + "dataview_page", + "dataview_dispose" + ) + json <- function(...) as.character(jsonlite::toJSON(list(...), auto_unbox = TRUE)) + invalid <- function(method, args) { + condition <- tryCatch(call(method, args), error = function(e) e) + inherits(condition, "sess_inspection_invalid") + } + decode <- function(text) jsonlite::fromJSON(text, simplifyVector = FALSE) + library_path <- dirname(system.file(package = "sess")) + on.exit( + rm(list = ls(.GlobalEnv, all.names = TRUE, pattern = paste0("^", prefix)), envir = .GlobalEnv), + add = TRUE + ) + + # The published table: exactly the ten methods, none of the socket-only + # ones, and nothing that selects a function by name. + expect_identical(sess:::inspection_call_methods, methods) + expect_identical(sess:::inspection_call_namespace, "vscode-r.inspect.json") + expect_identical(names(sess:::inspection_call_handlers()), methods) + expect_true(all(vapply(sess:::inspection_call_handlers(), is.function, logical(1)))) + expect_false(any( + c("interactive_stop", "plot_latest") %in% names(sess:::inspection_call_handlers()) + )) + # The socket table reuses the shared handlers instead of defining them again. + expect_identical( + sort(names(sess:::inspection_handlers())), + sort(setdiff(methods, c("hover", "completion"))) + ) + + # The functions published before sess is loaded carry the same selectors. + file <- system.file("arf", "expose-inspection.R", package = "sess") + expect_true(nzchar(file)) + stub <- source(file, local = new.env(parent = baseenv()))$value + published <- stub(library_path) + expect_identical(names(published), paste0("vscode-r.inspect.json/", methods)) + expect_true(all(vapply(published, is.function, logical(1)))) + expect_true(all(vapply(published, function(f) identical(names(formals(f)), "args"), logical(1)))) + expect_false(any(grepl("interactive_stop|plot_latest", names(published)))) + + # Before Interactive has started sess, and for a different sess, the + # handlers fail with an error and never load or run anything. + hover <- published[["vscode-r.inspect.json/hover"]] + was_connected <- .sess_env$interactive_connected + on.exit(.sess_env$interactive_connected <- was_connected, add = TRUE) + .sess_env$interactive_connected <- NULL + expect_error(hover(json(expr = "pi")), "has not started") + .sess_env$interactive_connected <- TRUE + expect_error( + stub(file.path(tempdir(), "other-library"))[[1L]](json(expr = "pi")), + "not the Interactive" + ) + expect_identical(decode(hover(json(expr = "pi")))$result$str, sess:::capture_str(pi)) + .sess_env$interactive_connected <- was_connected + + # A fresh R process has not loaded sess: the handler reports that, and the + # attempt does not load it. + rscript <- file.path(R.home("bin"), "Rscript") + if (file.exists(rscript)) { + code <- sprintf( + paste0( + "handlers <- base::source(%s, local = base::new.env(parent = base::baseenv()))$value(%s);", + "message <- tryCatch(handlers[[1L]]('{}'), error = function(e) conditionMessage(e));", + "cat(message, 'loaded:', 'sess' %%in%% loadedNamespaces(), sep = '|')" + ), + deparse(file), + deparse(library_path) + ) + output <- system2( + rscript, + c("--vanilla", "-e", shQuote(code)), + env = paste0("R_LIBS=", paste(.libPaths(), collapse = .Platform$path.sep)), + stdout = TRUE, + stderr = TRUE + ) + expect_identical(output, "The Interactive runtime has not been loaded yet|loaded:|FALSE") + } + + # Argument validation does not depend on the client. + expect_true(invalid("nonexistent", "{}")) + expect_true(invalid("interactive_stop", "{}")) + expect_true(invalid("plot_latest", "{}")) + expect_true(invalid(NA_character_, "{}")) + expect_true(invalid(c("hover", "hover"), "{}")) + # Arguments that are not one string holding a JSON object. + for (args in list(NULL, NA_character_, 1L, c("{}", "{}"), list(expr = "x"))) { + expect_true(invalid("hover", args)) + } + expect_true(invalid("hover", "{")) + expect_true(invalid("hover", "[]")) + expect_true(invalid("hover", "[1]")) + expect_true(invalid("hover", '"expr"')) + expect_true(invalid("hover", "null")) + # Required fields and field types. + expect_true(invalid("hover", "{}")) + expect_true(invalid("hover", json(expr = NULL))) + expect_true(invalid("hover", json(expr = 1L))) + expect_true(invalid("hover", json(expr = c("a", "b")))) + expect_true(invalid("hover", json(expr = list("a")))) + expect_true(invalid("hover", json(expr = TRUE))) + expect_true(invalid("completion", json(expr = "x", trigger = 1L))) + expect_true(invalid("completion", json(expr = "x", trigger = c("$", "@")))) + expect_true(invalid("workspace", json(revision = "1"))) + expect_true(invalid("workspace", json(revision = c(1, 2)))) + expect_true(invalid("workspace_children", "{}")) + expect_true(invalid("workspace_children", json(name = "x", start = 0L))) + expect_true(invalid("workspace_children", json(name = "x", start = 1.5))) + expect_true(invalid("workspace_children", json(name = "x", start = "1"))) + expect_true(invalid("workspace_children", json(name = 1L))) + expect_true(invalid("workspace_children", json(name = "x", path = "a"))) + expect_true(invalid("workspace_children", json(name = "x", path = list(1L)))) + expect_true(invalid( + "workspace_children", + json(name = "x", path = list(list(kind = "call", value = "f"))) + )) + expect_true(invalid( + "workspace_children", + json(name = "x", path = list(list(kind = "name", value = ""))) + )) + expect_true(invalid( + "workspace_children", + json(name = "x", path = list(list(kind = "index", value = 0L))) + )) + expect_true(invalid("workspace_children", json(name = "x", path = list(list(kind = "slot"))))) + # A list view is addressed by indices, not selectors. + expect_true(invalid( + "workspace_children", + json(view_id = "v", path = list(list(kind = "index", value = 1L))) + )) + expect_true(invalid("workspace_children", json(view_id = "v", path = list(0L)))) + expect_true(invalid("workspace_view", "{}")) + expect_true(invalid("workspace_view", json(name = "x", path = list("a")))) + expect_true(invalid("listview_navigate", "{}")) + expect_true(invalid("listview_navigate", json(view_id = "v", path = list("a")))) + expect_true(invalid("listview_navigate", json(view_id = "v", path = list(-1L)))) + expect_true(invalid("listview_view", json(view_id = "v", path = list(1L)))) + expect_true(invalid("listview_view", json(view_id = "v", index = 0L))) + expect_true(invalid("listview_view", json(view_id = "v", index = "1"))) + expect_true(invalid("dataview_init", "{}")) + expect_true(invalid("dataview_init", json(view_id = list("a")))) + expect_true(invalid("dataview_page", json(view_id = "v", startRow = "0"))) + expect_true(invalid("dataview_page", json(view_id = "v", endRow = c(1, 2)))) + expect_true(invalid("dataview_page", json(view_id = "v", sortModel = "asc"))) + expect_true(invalid("dataview_page", json(view_id = "v", filterModel = 1L))) + expect_true(invalid("dataview_page", json(view_id = "v", formatNumbers = "yes"))) + expect_true(invalid("dataview_dispose", "{}")) + expect_true(invalid("dataview_dispose", json(view_id = "v", state_generation = "1"))) + + # Valid arguments pass validation, and only the fields that a method reads + # reach its handler. + validate <- sess:::inspection_validate + expect_length(validate("workspace", decode("{}")), 0L) + expect_identical(validate("workspace", decode('{"revision":3}')), list(revision = 3L)) + expect_identical( + validate("workspace_children", decode('{"name":"x","extra":true}')), + list(name = "x", path = list(), start = 1L) + ) + expect_identical( + validate("workspace_children", decode('{"view_id":"v","path":[1,2],"start":3}'))$path, + list(1L, 2L) + ) + expect_identical(names(validate("completion", decode('{"expr":"x"}'))), "expr") + expect_identical( + validate("listview_view", decode('{"view_id":"v","index":2,"unused":1}')), + list(view_id = "v", path = list(), index = 2L) + ) + expect_identical( + sort(names(validate( + "dataview_page", + decode( + '{"view_id":"v","startRow":0,"endRow":10,"sortModel":[],"filterModel":{},"formatNumbers":true}' + ) + ))), + sort(c("view_id", "startRow", "endRow", "sortModel", "filterModel", "formatNumbers")) + ) + # A JSON null is an absent optional field. + expect_length(validate("workspace", decode('{"revision":null}')), 0L) + + # Results encode like a socket reply: the same R value decodes to the same + # JSON value, and a NULL result stays distinct from NA. + pipe <- processx::conn_create_pipepair() + orig_con <- .sess_env$con + on.exit( + { + .sess_env$con <- orig_con + lapply(pipe, close) + }, + add = TRUE + ) + .sess_env$con <- pipe[[2L]] + socket_result <- function(result) { + sess:::rpc_reply("reply", result) + reply <- decode(processx::conn_read_chars(pipe[[1L]])) + list(present = "result" %in% names(reply), value = reply$result) + } + call_result <- function(result) { + encoded <- sess:::inspection_encode(result) + expect_true(is.character(encoded) && length(encoded) == 1L && is.null(attributes(encoded))) + reply <- decode(encoded) + list(present = "result" %in% names(reply), value = reply$result) + } + results <- list( + null = NULL, + na = NA, + na_character = NA_character_, + na_integer = NA_integer_, + flag = TRUE, + number = 1.5, + integer = 3L, + string = "text", + unicode = "café あ\U0001F600", + quotes = "a \"quoted\" \\ value\n", + empty_string = "", + empty_vector = character(0), + empty_integer = integer(0), + empty_list = list(), + empty_object = structure(list(), names = character()), + vector = c(1L, 2L, 3L), + named_vector = c(a = 1, b = 2), + nested = list(a = list(b = list(1, "two", NULL)), c = I(1L)), + na_inside = list(a = NA, b = c(1, NA), c = c("x", NA)), + nan = NaN, + infinite = c(Inf, -Inf), + special = list(nan = NaN, inf = Inf, ninf = -Inf, na = NA_real_), + large = 1e300, + precise = 0.1 + 0.2, + list_of_lists = list(list(a = 1), list(a = 2)), + factor = factor(c("a", "b")), + date = as.Date("2026-01-02"), + frame = data.frame(x = 1:2, y = c("a", NA)), + unchanged = list(revision = 3, unchanged = TRUE) + ) + for (name in names(results)) { + expect_identical(call_result(results[[name]]), socket_result(results[[name]]), info = name) + } + # A list holding NULL is not NULL. + expect_identical(call_result(list(NULL))$present, TRUE) + expect_identical(call_result(NULL), list(present = FALSE, value = NULL)) + expect_null(call_result(NA)$value) + expect_true(call_result(NA)$present) + # Encoded results are bounded below the client's frame limit. + expect_error(sess:::inspection_encode(strrep("a", 5L * 1024L * 1024L)), "size limit") + + # The same request gives the same result on both transports. + view_id <- sess:::dataview_register(data.frame(value = 1:3, label = c("a", "b", NA)))$view_id + on.exit(.sess_env$dataviews[[view_id]] <- NULL, add = TRUE) + socket <- function(method, params) { + sess:::dispatch_message(as.character(jsonlite::toJSON( + list(jsonrpc = "2.0", id = "request", method = method, params = params), + auto_unbox = TRUE + ))) + decode(processx::conn_read_chars(pipe[[1L]]))$result + } + assign("sess_inspection_call_children", list(first = 1L, second = list(3L)), envir = .GlobalEnv) + requests <- list( + list("dataview_init", list(view_id = view_id)), + list("dataview_page", list(view_id = view_id, startRow = 0L, endRow = 2L)), + list( + "dataview_page", + list(view_id = view_id, startRow = 1L, endRow = 5L, formatNumbers = TRUE) + ), + list( + "dataview_page", + list(view_id = view_id, sortModel = list(list(colId = "1", sort = "desc"))) + ), + list("workspace_children", list(name = "sess_inspection_call_children")), + list("dataview_dispose", list(view_id = "unknown")) + ) + for (request in requests) { + method <- request[[1L]] + params <- do.call(json, request[[2L]]) + expect_identical( + decode(call(method, params))$result, + socket(method, request[[2L]]), + info = method + ) + } + + # Hover and completion resolve names and member chains without evaluating + # the request text. + marker <- paste0(prefix, "evaluated") + assign(paste0(prefix, "value"), list(a = 1L, b = "x"), envir = .GlobalEnv) + hovered <- decode(call("hover", json(expr = paste0(prefix, "value")))) + expect_identical(hovered$result$str, sess:::capture_str(list(a = 1L, b = "x"))) + hovered <- decode(call("hover", json(expr = paste0(prefix, "value$a")))) + expect_identical(hovered$result$str, sess:::capture_str(1L)) + expect_false("result" %in% names(decode(call("hover", json(expr = paste0(prefix, "absent")))))) + completed <- decode(call("completion", json(expr = paste0(prefix, "value"), trigger = "$"))) + expect_identical(vapply(completed$result, function(item) item$name, character(1)), c("a", "b")) + expect_false("result" %in% names(decode(call("completion", json(expr = "pi"))))) + assignment <- paste0("assign('", marker, "', TRUE, envir = .GlobalEnv)") + for (expr in c( + assignment, + paste0("local(", assignment, ")"), + paste0("repeat ", prefix, "value"), + paste0(prefix, "value[[1]]"), + paste0(prefix, "value; ", assignment), + paste0("(", assignment, ")"), + "base::pi", + "-1", + "if (TRUE) 1", + "{", + "" + )) { + expect_true(invalid("hover", json(expr = expr)), info = expr) + expect_true(invalid("completion", json(expr = expr, trigger = "$")), info = expr) + } + expect_false(exists(marker, envir = .GlobalEnv, inherits = FALSE)) + # Completion on an expression without an accessor reads nothing. + makeActiveBinding( + paste0(prefix, "touched"), + function() { + assign(marker, TRUE, envir = .GlobalEnv) + list(a = 1L) + }, + .GlobalEnv + ) + call("completion", json(expr = paste0(prefix, "touched"))) + expect_false(exists(marker, envir = .GlobalEnv, inherits = FALSE)) + + # Errors and interrupts propagate: neither becomes a successful value. + makeActiveBinding( + paste0(prefix, "fails"), + function() stop("binding failed", call. = FALSE), + .GlobalEnv + ) + makeActiveBinding( + paste0(prefix, "interrupts"), + function() signalCondition(structure(class = c("interrupt", "condition"), list())), + .GlobalEnv + ) + for (method in c("hover", "completion")) { + for (name in c("fails", "interrupts")) { + expr <- paste0(prefix, name) + args <- if (method == "hover") json(expr = expr) else json(expr = expr, trigger = "$") + value <- tryCatch( + call(method, args), + error = function(e) paste("error:", conditionMessage(e)), + interrupt = function(e) "interrupt" + ) + expect_identical( + value, + if (name == "fails") "error: binding failed" else "interrupt", + info = paste(method, name) + ) + } + } + unknown <- tryCatch(call("dataview_init", json(view_id = "unknown")), error = function(e) e) + expect_true(inherits(unknown, "error")) + expect_true(grepl("Unknown dataview id", conditionMessage(unknown), fixed = TRUE)) + # Validation errors have their own class; other errors do not. + expect_false(inherits(unknown, "sess_inspection_invalid")) + expect_true(inherits( + tryCatch(call("dataview_init", "{}"), error = function(e) e), + "sess_inspection_invalid" + )) + # A result that cannot be encoded is an error, too. + .sess_env$dataviews[[view_id]]$columns[[2L]]$headerTooltip <- 1 + 2i + expect_error(suppressWarnings(call("dataview_init", json(view_id = view_id)))) +}) diff --git a/src/interactive/README.md b/src/interactive/README.md index 286d1d4ea..6b953f187 100644 --- a/src/interactive/README.md +++ b/src/interactive/README.md @@ -39,9 +39,10 @@ The shipped `sess` backend uses arf with pure R sess helpers: [SessBackend](backends/sessBackend.ts) owns readiness, metadata, capabilities, and ordered output. [SessBridge](backends/sessBridge.ts) owns authenticated sess JSON-RPC, inspection, rich events, and requests to the editor. [Arf](backends/arf.ts) -owns launch/adoption and dispatch; [process.ts](backends/process.ts) handles -signals, ownership, and confirmed process exit. Shared discovery/HTTP helpers -remain in [arf.ts](arf.ts). Plain R Interactive creation is unavailable; ordinary +owns launch/adoption, dispatch, interruption, and Stop; [process.ts](backends/process.ts) +handles ownership, signals, and confirmed process exit. Shared discovery/HTTP +helpers and the version check remain in [arf.ts](arf.ts), and the long-lived +connection in [arfAttach.ts](arfAttach.ts). Plain R Interactive creation is unavailable; ordinary R terminals are unaffected, and existing agents can still be reconnected. Managed sessions dispatch the private `sess:::interactive_execute` entry point @@ -55,6 +56,53 @@ R sinks, frontend styling, and forked workers cannot rewrite those frames. A server reply timeout after execution started does not cancel R; its events still establish completion. Other transport failures remain ambiguous without retries. +The backend attaches to arf before submitting code. Before running a submission, +sess publishes an arf event carrying its ID, so the event's arf execution ID +identifies that submission; a managed `user_input` acknowledgement reports the +same ID. Interruption is an arf IPC `interrupt` for that execution ID, held until +the ID is known and dropped once sess reports completion. It is never a signal: +headless arf ends the whole session on SIGINT when R is idle, so a signal that +races with completion would end the session. sess reports the outcome; arf's +acceptance does not. Stop sends arf `shutdown` and waits for the process to exit, +killing it after a deadline. An interactive arf rejects `shutdown` as an unknown +method; only that answer makes Stop fall back to SIGTERM and then SIGKILL. + +Inspection (workspace, hover/completion, and data-viewer requests) is an arf +handler `call` with an execution deadline, not a sess socket request. Under arf +the sess socket is served from idle event processing, where R interrupts are +suppressed, so a slow request there cannot be stopped; arf delivers the deadline +as an interrupt to a handler call and replies only after the handler stopped. +Managed arf starts with `--ipc-expose`, which publishes ten selectors +`vscode-r.inspect.json/` from a table installed with sess +([expose-inspection.R](../../sess/inst/arf/expose-inspection.R)); startup fails +if the session does not report all of them as published. arf evaluates +that expression before the bootstrap loads sess from the private library, so the +handlers only forward to sess when called: they fail with an error until the +private sess has started, and never load a sess themselves. A handler takes the +request parameters as one JSON string, validates them in R, and returns the +result as one JSON string, decoded like a socket reply. `interactive_stop` and +`plot_latest` are not published, and nothing calls an arbitrary function by +name. Hover and completion resolve names and `$`/`@` chains without evaluating +the request text; other input is an R error, which reads as no result. + +The request's `timeout` is the execution deadline, and also how long a request +may wait to start. The reply to a call that hit its deadline follows the +handler's stop, so the transport wait is longer than both. Errors keep their +cause: queue timeout (R was busy and the request never ran), execution deadline +(R interrupted it), transport timeout (the client stopped waiting and it may +still run), R error, interrupt, and an unpublished handler. Calls go through the +long-lived attach connection, so arf drops calls that have not started when it +closes, and replies need no connection per request. Requests are sent one at a +time: identical read-only requests share a call, and the number of waiting +requests is bounded, so the arf call queue shared by all clients does not fill. + +An adopted arf uses calls only when `session.handler_api` is locked and lists +every selector, which its user must have published; otherwise inspection stays +on the sess socket and cannot be interrupted. The `inspectionDeadline` +capability reports which one applies. Manual interruption of a running +inspection is not offered: an interrupt request stops submitted code, and an +inspection stops at its deadline. + Adopted sessions use visible arf evaluation and return captured console output on completion, while rich events use sess RPC. The backend waits for both completion and the captured response. There is no subscription for arbitrary terminal console @@ -64,7 +112,8 @@ sess hooks without changing frontend console callbacks or killing adopted R. Both providers report notebook stdin/debugger support as unavailable: arf IPC `user_input` submits code, rather than answering nested R prompts. Use ordinary R terminals for `readline`, `scan`, and debugger interaction. arf IPC is -experimental; the integration is tested against arf 0.5.3. Persistent supervision +experimental; the integration requires arf 0.7.2-rc.1 or later and is tested with +the version pinned in `src/test/node/mise.toml`. Persistent supervision currently remains limited to Linux/macOS. [SessGraphics](backends/sessGraphics.ts) owns JGD negotiation, its font-metrics worker, plot attribution/coalescing, SVG production, and resize transport. It emits display payloads with stable identities. The agent stores assets and journals references. Static graphics remains available without JGD; another backend can supply SVG/PNG directly. @@ -106,8 +155,8 @@ Use the types in [backend.ts](backend.ts) as the source of truth. The essential - `dispatch()` acknowledges transport, not evaluation completion. `started` and `finished` events establish the result and can arrive before the dispatch promise settles. The agent records admission and the current execution first; late replies must not complete an execution twice. - Events carry execution IDs where known. External terminal output stays identifiable as external; missing source or uncertain boundaries must not be invented. - A transport failure can leave execution outcome unknown. Block further dispatch until the outcome is established; never automatically retry submitted R code. Transport loss does not prove process death, particularly for adopted arf. -- Inspection is a typed set of workspace, hover/completion, and data-viewer operations. Keep sockets, subprocesses, wire packets, and transport request IDs inside the backend. Runtime requests to the editor use opaque backend IDs; expired prompts must not become actionable on replay. -- The agent validates input identity, generation, and controlling-client authorization. The backend delivers input/replies and handles interruption, including slow inspection after its editor request timed out. +- Inspection is a typed set of workspace, hover/completion, and data-viewer operations. Keep sockets, subprocesses, wire packets, and transport request IDs inside the backend. `InspectionRequest.timeout` is a deadline, and a backend that can interrupt the request reports `inspectionDeadline`. Runtime requests to the editor use opaque backend IDs; expired prompts must not become actionable on replay. +- The agent validates input identity, generation, and controlling-client authorization. The backend delivers input/replies and handles interruption of submissions. A slow inspection ends at its execution deadline rather than by an interrupt request. - Runtime capabilities come from the backend; persistence, history, rename, and queue cancellation remain agent-owned. Use capabilities and ownership for operational checks, with compatibility defaults for older manifests. ## Lifecycle diff --git a/src/interactive/agent.ts b/src/interactive/agent.ts index ad4221a2e..b123c6c73 100644 --- a/src/interactive/agent.ts +++ b/src/interactive/agent.ts @@ -519,8 +519,10 @@ export class SessionAgent { if (params.id && params.id !== this.current) { throw new Error('Execution is no longer running'); } - // Inspection can still be running after its request timed out, - // without a submitted execution in `current`. + // Only a submission is interrupted. An inspection stops by itself + // at its execution deadline, where the runtime supports one, so + // it is not an interrupt target; the backend rejects the request + // when nothing has been submitted. await this.backend.interrupt(); break; case 'input': diff --git a/src/interactive/arf.ts b/src/interactive/arf.ts index e4ba799ff..97663cb5e 100644 --- a/src/interactive/arf.ts +++ b/src/interactive/arf.ts @@ -13,6 +13,124 @@ export interface ArfSession { session_type?: string; } +// 0.7.2-rc.1 keeps forked R workers from crashing on macOS, reports an R error +// that follows a caught interrupt as an error rather than as interrupted, and +// bounds console reads that cannot be answered. +// TODO: Require arf 0.7.2 once it is released. +export const MIN_ARF_VERSION = '0.7.2-rc.1'; + +/** arf JSON-RPC error codes that the Interactive client acts on. */ +export const ARF_METHOD_NOT_FOUND = -32601; +export const ARF_TIMEOUT = -32007; +/** Errors of the `call` method. */ +export const ARF_HANDLER_NOT_FOUND = -32010; +export const ARF_HANDLER_QUEUE_FULL = -32011; +export const ARF_HANDLER_QUEUE_TIMEOUT = -32012; +export const ARF_HANDLER_R_ERROR = -32014; +export const ARF_HANDLER_INTERRUPTED = -32016; +export const ARF_HANDLER_EXECUTION_TIMEOUT = -32019; + +/** A JSON-RPC error response from arf, keeping its code and data. */ +export class ArfRpcError extends Error { + constructor( + readonly code: number, + readonly rpcMessage: string, + readonly data: unknown, + raw: unknown, + ) { + super(JSON.stringify(raw)); + this.name = 'ArfRpcError'; + } +} + +/** The client stopped waiting for arf; the request may still be running. */ +export class ArfTransportTimeoutError extends Error { + constructor() { + super('arf request timed out; evaluation may still be running'); + this.name = 'ArfTransportTimeoutError'; + } +} + +export function rpcError(error: unknown): ArfRpcError { + const value = + error && typeof error === 'object' && !Array.isArray(error) + ? (error as Record) + : {}; + return new ArfRpcError( + typeof value.code === 'number' ? value.code : NaN, + typeof value.message === 'string' ? value.message : '', + value.data, + error, + ); +} + +/** + * Whether `version` has at least the precedence of `minimum` under SemVer 2.0.0: + * a prerelease is older than its release, and prerelease identifiers compare + * field by field (numbers numerically and below text). Build metadata is ignored. + */ +export function arfVersionAtLeast(version: unknown, minimum: string): boolean { + const parse = (text: string) => { + const match = + /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z.-]+)?$/.exec( + text, + ); + return match + ? { + core: [Number(match[1]), Number(match[2]), Number(match[3])], + pre: match[4]?.split('.') ?? [], + } + : undefined; + }; + const actual = typeof version === 'string' ? parse(version) : undefined; + const required = parse(minimum); + if (!actual || !required) { + return false; + } + for (let i = 0; i < 3; i++) { + if (actual.core[i] !== required.core[i]) { + return actual.core[i] > required.core[i]; + } + } + // A release is newer than any of its prereleases. + if (!actual.pre.length || !required.pre.length) { + return !actual.pre.length; + } + const numeric = /^\d+$/; + for (let i = 0; i < Math.min(actual.pre.length, required.pre.length); i++) { + const [a, b] = [actual.pre[i], required.pre[i]]; + if (a === b) { + continue; + } + if (numeric.test(a) && numeric.test(b)) { + return Number(a) > Number(b); + } + if (numeric.test(a) !== numeric.test(b)) { + return !numeric.test(a); + } + return a > b; + } + // With equal leading identifiers, the longer prerelease is newer. + return actual.pre.length >= required.pre.length; +} + +/** Rejects sessions older than MIN_ARF_VERSION, or without the deadline used by inspection. */ +export function checkArfSession(session: Record): void { + if (!arfVersionAtLeast(session.arf_version, MIN_ARF_VERSION)) { + const actual = + typeof session.arf_version === 'string' ? session.arf_version : 'an unknown version'; + throw new Error( + `R Interactive requires arf ${MIN_ARF_VERSION} or later, but the session runs ${actual}. Update arf and start a new session.`, + ); + } + const capabilities = Array.isArray(session.capabilities) ? session.capabilities : []; + if (!capabilities.includes('call_execution_timeout')) { + throw new Error( + 'This arf session does not support execution deadlines for handler calls. Update arf and start a new session.', + ); + } +} + /** arf speaks HTTP JSON-RPC, not sess's JSON Lines framing. */ export function arfRequest( endpoint: string, @@ -52,7 +170,7 @@ export function arfRequest( try { const result = object(JSON.parse(Buffer.concat(chunks).toString('utf8'))); if (result.error) { - reject(new Error(JSON.stringify(result.error))); + reject(rpcError(result.error)); } else { resolve(result.result); } @@ -63,11 +181,7 @@ export function arfRequest( }, ); if (timeout > 0) { - request.setTimeout(timeout, () => - request.destroy( - new Error('arf request timed out; evaluation may still be running'), - ), - ); + request.setTimeout(timeout, () => request.destroy(new ArfTransportTimeoutError())); } request.on('error', reject); request.end(body); diff --git a/src/interactive/arfAttach.ts b/src/interactive/arfAttach.ts new file mode 100644 index 000000000..e05fab441 --- /dev/null +++ b/src/interactive/arfAttach.ts @@ -0,0 +1,221 @@ +import * as net from 'net'; +import { JsonLines } from './framing'; +import { object } from './protocol'; +import { ArfTransportTimeoutError, rpcError } from './arf'; + +/** One event notification from an attached arf connection. */ +export interface ArfEvent { + seq: number; + topic: string; + data: unknown; + /** arf's execution ID, or null when the event belongs to no execution. */ + execution: number | null; +} + +export interface ArfAttachResult { + connectionId: number; + apiVersion: number; + capabilities: string[]; + sessionId: string; + session: Record; +} + +export interface ArfAttachOptions { + subscribe?: string[]; + client?: { name: string; version?: string }; + /** Bounds connecting and the attach response, not later requests. */ + timeout?: number; + /** Longest accepted line from arf; the default is the Interactive message limit. */ + maxLineBytes?: number; + /** Registered before attaching, so no event after the response is missed. */ + onEvent?: (event: ArfEvent) => void; + onClose?: (reason: Error) => void; +} + +interface Pending { + resolve(value: unknown): void; + reject(error: Error): void; + timer?: NodeJS.Timeout; +} + +/** + * A long-lived arf IPC connection (newline-delimited JSON-RPC). + * + * Responses are matched by ID because they arrive in completion order. A + * request whose wait ends locally (timeout or abort) may still run in R; its + * late response is ignored and its ID is never reused. The connection closes + * once, rejecting every pending request with the same reason, and is never + * reopened: callers attach again and reconcile their own state. + */ +export class ArfAttachConnection { + private pending = new Map(); + private nextId = 1; + private closeReason?: Error; + + private constructor( + private socket: net.Socket, + private onClose?: (reason: Error) => void, + ) {} + + static open( + endpoint: string, + options: ArfAttachOptions = {}, + ): Promise<{ connection: ArfAttachConnection; result: ArfAttachResult }> { + return new Promise((resolve, reject) => { + const socket = net.connect(endpoint); + const connection = new ArfAttachConnection(socket, options.onClose); + const attachId = connection.nextId++; + let attached = false; + const timer = setTimeout( + () => connection.close(new ArfTransportTimeoutError()), + options.timeout ?? 30000, + ); + connection.pending.set(attachId, { + resolve: (value) => { + clearTimeout(timer); + try { + const result = object(value); + attached = true; + resolve({ + connection, + result: { + connectionId: Number(result.connection_id), + apiVersion: Number(result.api_version), + capabilities: Array.isArray(result.capabilities) + ? result.capabilities.map(String) + : [], + sessionId: + typeof result.session_id === 'string' ? result.session_id : '', + session: object(result.session), + }, + }); + } catch (error) { + connection.close(error as Error); + reject(error); + } + }, + reject: (error) => { + clearTimeout(timer); + // arf closes the connection after refusing attach. + connection.close(error); + reject(error); + }, + }); + const parser = new JsonLines((message) => { + // No event is sent before the attach response. + if (message.method === 'event' && attached) { + options.onEvent?.(event(message.params)); + } else if (message.id !== undefined) { + connection.response(message); + } + }, options.maxLineBytes); + socket.on('data', (chunk: Buffer) => { + try { + parser.push(chunk); + } catch (error) { + connection.close(error as Error); + } + }); + socket.on('error', (error) => connection.close(error)); + socket.on('close', () => connection.close(new Error('arf closed the IPC connection'))); + socket.write( + JSON.stringify({ + jsonrpc: '2.0', + id: attachId, + method: 'attach', + params: { + protocol: 1, + subscribe: options.subscribe ?? [], + client: options.client ?? { name: 'vscode-R' }, + }, + }) + '\n', + ); + }); + } + + get closed(): Error | undefined { + return this.closeReason; + } + + request( + method: string, + params: Record = {}, + options: { timeout?: number; signal?: AbortSignal } = {}, + ): Promise { + if (this.closeReason) { + return Promise.reject(this.closeReason); + } + const id = this.nextId++; + return new Promise((resolve, reject) => { + const settle = (): void => { + clearTimeout(entry.timer); + options.signal?.removeEventListener('abort', abort); + this.pending.delete(id); + }; + const abort = (): void => { + settle(); + reject(new Error('arf request was aborted; it may still be running')); + }; + const entry: Pending = { + resolve: (value) => { + settle(); + resolve(value); + }, + reject: (error) => { + settle(); + reject(error); + }, + }; + if (options.timeout && options.timeout > 0) { + entry.timer = setTimeout(() => { + settle(); + reject(new ArfTransportTimeoutError()); + }, options.timeout); + } + if (options.signal?.aborted) { + abort(); + return; + } + options.signal?.addEventListener('abort', abort, { once: true }); + this.pending.set(id, entry); + this.socket.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n'); + }); + } + + close(reason: Error = new Error('arf IPC connection was closed')): void { + if (this.closeReason) { + return; + } + this.closeReason = reason; + for (const entry of this.pending.values()) { + entry.reject(reason); + } + this.pending.clear(); + this.socket.destroy(); + this.onClose?.(reason); + } + + private response(message: Record): void { + const entry = typeof message.id === 'number' ? this.pending.get(message.id) : undefined; + if (!entry) { + // A request that timed out or was aborted locally. + return; + } + this.pending.delete(Number(message.id)); + if (message.error !== undefined) { + entry.reject(rpcError(message.error)); + } else { + entry.resolve(message.result); + } + } +} + +function event(params: unknown): ArfEvent { + const value = object(params); + return { + seq: Number(value.seq), + topic: String(value.topic), + data: value.data, + execution: Number.isSafeInteger(value.execution) ? Number(value.execution) : null, + }; +} diff --git a/src/interactive/backend.ts b/src/interactive/backend.ts index 3192841da..89369088a 100644 --- a/src/interactive/backend.ts +++ b/src/interactive/backend.ts @@ -9,20 +9,26 @@ export interface RuntimeMetadata { rPath?: string; libraryPaths?: string[]; } -export type InspectionMethod = - | 'workspace' - | 'workspace_children' - | 'workspace_view' - | 'listview_navigate' - | 'listview_view' - | 'hover' - | 'completion' - | 'dataview_init' - | 'dataview_page' - | 'dataview_dispose'; +export const INSPECTION_METHODS = [ + 'workspace', + 'workspace_children', + 'workspace_view', + 'listview_navigate', + 'listview_view', + 'hover', + 'completion', + 'dataview_init', + 'dataview_page', + 'dataview_dispose', +] as const; +export type InspectionMethod = (typeof INSPECTION_METHODS)[number]; export interface InspectionRequest { method: InspectionMethod; params: Record; + /** + * Milliseconds. Over arf this is the execution deadline: R interrupts the + * request when it passes. A request waits at most as long again to start. + */ timeout?: number; } export interface InputReply { @@ -79,20 +85,7 @@ export interface SessionBackend { export type BackendFactory = (settings: AgentSettings) => SessionBackend; export function inspectionMethod(value: unknown): InspectionMethod { - if ( - ![ - 'workspace', - 'workspace_children', - 'workspace_view', - 'listview_navigate', - 'listview_view', - 'hover', - 'completion', - 'dataview_init', - 'dataview_page', - 'dataview_dispose', - ].includes(String(value)) - ) { + if (!(INSPECTION_METHODS as readonly string[]).includes(String(value))) { throw new Error('Unsupported inspection method'); } return value as InspectionMethod; diff --git a/src/interactive/backends/arf.ts b/src/interactive/backends/arf.ts index 064dfa4e1..bfc3fcda3 100644 --- a/src/interactive/backends/arf.ts +++ b/src/interactive/backends/arf.ts @@ -1,15 +1,56 @@ -import { arfRequest } from '../arf'; -import { BackendEvent } from '../backend'; -import { object, Submission } from '../protocol'; +import { + ARF_METHOD_NOT_FOUND, + ARF_TIMEOUT, + ArfRpcError, + arfRequest, + checkArfSession, +} from '../arf'; +import { ArfAttachConnection, ArfEvent } from '../arfAttach'; +import { BackendEvent, InspectionRequest } from '../backend'; +import { MAX_MESSAGE_BYTES, object, Submission } from '../protocol'; import { RuntimeProcess } from './process'; import { rString } from './rCode'; import { ArfOutput } from './arfOutput'; +import { + ArfHandlerApi, + CallLimits, + InspectionCalls, + inspectionCallsAvailable, + parseHandlerApi, +} from './arfInspection'; + +/** Topic that sess publishes before running submitted code under arf. */ +const STARTED_TOPIC = 'vscode-r.interactive.started'; + +/** + * Longest line accepted on the attach connection. A handler's result is + * limited to MAX_MESSAGE_BYTES before it is sent as a JSON string, which can + * escape every character once more. + */ +const MAX_ATTACH_LINE_BYTES = 8 * MAX_MESSAGE_BYTES; + +/** The submission sent to arf, and arf's execution ID once known. */ +interface Execution { + submission: string; + id?: number; + interruptRequested: boolean; +} export class Arf { readonly process: RuntimeProcess; ready = false; private abort = new AbortController(); private started = false; + private attach?: ArfAttachConnection; + private attaching?: Promise>; + private handlerApi?: ArfHandlerApi; + private inspections = new InspectionCalls((selector, args, limits) => + this.callHandler(selector, args, limits), + ); + private sessionId?: string; + private execution?: Execution; + private failure?: Error; + private stopping?: Promise; constructor( private command: string, private directory: string, @@ -24,7 +65,11 @@ export class Arf { markStarted(): void { this.started = true; } - async start(bootstrap: string, env: NodeJS.ProcessEnv): Promise { + /** + * `expose` is the R expression that arf evaluates, after the R profiles, + * to publish handlers. It applies only when this adapter starts arf. + */ + async start(bootstrap: string, env: NodeJS.ProcessEnv, expose?: string): Promise { if (!this.process.adopted) { const output = new Map( ['stdout', 'stderr'].map((channel) => [ @@ -48,7 +93,7 @@ export class Arf { ); const child = this.process.launch( this.command, - ['headless', '--json'], + ['headless', '--json', ...(expose ? ['--ipc-expose', expose] : [])], this.directory, env, (text, channel) => { @@ -100,9 +145,13 @@ export class Arf { if (!this.endpoint) { throw new Error('Missing arf endpoint'); } - const metadata = object( - await arfRequest(this.endpoint, 'session', {}, 30000, this.abort.signal), - ); + // Subscribe before submitting anything so that no started event is missed. + const metadata = await this.connect(); + checkArfSession(metadata); + // The published table must match the selectors that inspection calls. + if (!this.process.adopted && !this.callsInspection()) { + throw new Error('arf did not publish the R Interactive inspection handlers'); + } this.emit({ type: 'provider', data: { @@ -120,19 +169,216 @@ export class Arf { this.abort.signal, ), ); - if (result.error) { - throw new Error( - typeof result.error === 'string' ? result.error : JSON.stringify(result.error), - ); + // A missing or unknown status is not a successful bootstrap. + if (result.status !== 'ok') { + const detail = + typeof result.error === 'string' && result.error + ? result.error + : typeof result.stderr === 'string' && result.stderr.trim() + ? result.stderr.trim() + : `status ${JSON.stringify(result.status ?? null)}`; + throw new Error(`Interactive bootstrap failed in arf: ${detail}`); + } + } + /** Attaches, or joins an attach that is already in progress. */ + private connect(): Promise> { + return (this.attaching ??= this.attachOnce().finally(() => { + this.attaching = undefined; + })); + } + private async attachOnce(): Promise> { + const { connection, result } = await ArfAttachConnection.open(this.endpoint!, { + subscribe: [STARTED_TOPIC], + client: { name: 'vscode-R Interactive' }, + maxLineBytes: MAX_ATTACH_LINE_BYTES, + onEvent: (event) => this.arfEvent(event), + }); + if (this.sessionId !== undefined && result.sessionId !== this.sessionId) { + connection.close(); + throw new Error('The arf endpoint now belongs to a different session'); + } + if (this.abort.signal.aborted) { + connection.close(); + throw new Error('arf adapter was disposed'); + } + this.sessionId = result.sessionId; + this.attach = connection; + this.handlerApi = parseHandlerApi(result.session); + return result.session; + } + /** The attach connection, reattaching to the same session if it was lost. */ + private async attached(): Promise { + if (!this.attach || this.attach.closed) { + await this.connect(); } + return this.attach!; + } + /** + * Whether inspection uses handler calls, which stop at their execution + * deadline, rather than the sess socket, which cannot be interrupted. + */ + callsInspection(): boolean { + return inspectionCallsAvailable(this.handlerApi); + } + /** Runs an inspection as a handler call with the request's execution deadline. */ + inspect(request: InspectionRequest): Promise { + return this.inspections.request(request); + } + private async callHandler( + selector: string, + args: string, + limits: CallLimits, + ): Promise { + // A long-lived connection drops a call that has not started when it + // closes, so disposal does not leave inspections queued in R. + const connection = await this.attached(); + return connection.request( + 'call', + { + handler: selector, + args, + queue_timeout_ms: limits.queue, + execution_timeout_ms: limits.execution, + }, + { timeout: limits.transport, signal: this.abort.signal }, + ); } dispose(): void { this.abort.abort(); + this.inspections.close(new Error('R session was disposed')); + this.attach?.close(); this.process.dispose(); } + /** Called once sess reports that a submission finished. */ + finished(submission: string): void { + if (this.execution?.submission === submission) { + this.execution = undefined; + } + } + async interrupt(): Promise { + const execution = this.execution; + if (!execution) { + // Inspection is stopped by its execution deadline, not by this request. + throw new Error('No submitted code is running'); + } + execution.interruptRequested = true; + if (execution.id !== undefined) { + await this.sendInterrupt(execution); + } else if (this.attach?.closed) { + throw new Error( + 'Cannot interrupt: the connection to arf was lost before the execution started', + ); + } + // Otherwise the request is sent once arf reports the execution ID. + } + private async sendInterrupt(execution: Execution): Promise { + if (this.execution !== execution || execution.id === undefined) { + return; + } + // Acceptance only registers the request; sess reports the outcome. A + // rejection means the execution already ended, which races with Stop. + await arfRequest(this.endpoint!, 'interrupt', { execution_id: execution.id }, 5000); + } + /** Records arf's execution ID for a submission, from its reply or its started event. */ + private register(submission: unknown, id: unknown): void { + const execution = this.execution; + if (!execution || execution.submission !== submission) { + return; + } + if (!Number.isSafeInteger(id) || (id as number) < 0) { + this.fail(new Error('arf reported an invalid execution ID')); + return; + } + if (execution.id === undefined) { + execution.id = id as number; + if (execution.interruptRequested) { + void this.sendInterrupt(execution).catch((error: Error) => + this.emit({ type: 'error', message: error.message }), + ); + } + } else if (execution.id !== id) { + this.fail(new Error('arf reported conflicting execution IDs for one submission')); + } + } + private arfEvent(event: ArfEvent): void { + if (event.topic !== STARTED_TOPIC) { + return; + } + const data = event.data; + const submission = + data && typeof data === 'object' ? (data as Record).id : undefined; + this.register(submission, event.execution); + } + private fail(error: Error): void { + this.failure ??= error; + this.emit({ type: 'unavailable', message: error.message }); + } + stop(force = false): Promise { + return (this.stopping ??= this.stopRuntime(force).finally(() => { + this.stopping = undefined; + })); + } + private async stopRuntime(force: boolean): Promise { + if (!this.process.alive()) { + this.process.markExited(); + return; + } + if (force) { + await this.kill(undefined, 0); + return; + } + if (!this.endpoint) { + if (this.process.adopted) { + throw new Error('The arf endpoint is unknown'); + } + await this.kill('SIGTERM', 3000); + return; + } + try { + await arfRequest(this.endpoint, 'shutdown', {}, 5000); + } catch (error) { + if ( + this.process.adopted && + error instanceof ArfRpcError && + error.code === ARF_METHOD_NOT_FOUND + ) { + // An interactive arf rejects shutdown; stop it as a terminal would. + await this.kill('SIGTERM', 3000); + return; + } + if (!this.process.adopted) { + // The managed process is ours even if its IPC no longer answers. + await this.kill('SIGTERM', 3000); + return; + } + throw error; + } + // Acceptance only starts shutdown, and running R code may delay it. + await this.kill(undefined, 5000); + } + /** Sends `first`, waits up to `grace` ms, then kills; resolves after a confirmed exit. */ + private async kill(first: NodeJS.Signals | undefined, grace: number): Promise { + if (first) { + this.process.send(first); + } + if (await this.process.waitForExit(grace)) { + return; + } + this.process.send('SIGKILL'); + if (!(await this.process.waitForExit(2000))) { + throw new Error('R has not exited after Stop'); + } + } async dispatch(submission: Submission): Promise { + if (this.failure) { + throw this.failure; + } + // The previous execution has finished, so attaching again loses no + // state; the session must still be the same arf process. + await this.attached(); const code = `sess:::interactive_execute(${rString(submission.id)}, ${rString(submission.code)}, jsonlite::fromJSON(${rString(JSON.stringify(submission.source ?? null))}, simplifyVector=FALSE))`; this.started = false; + this.execution = { submission: submission.id, interruptRequested: false }; // Managed sessions use send to avoid arf's unbounded evaluation capture. // R's ordered events establish the outcome even if arf's reply times out. let result: Record; @@ -149,11 +395,20 @@ export class Arf { } catch (error) { // A server timeout does not cancel R. Keep accepting its event stream. // Other transport failures remain ambiguous and must block dispatch. - if (!this.process.adopted && this.started && /timed out|timeout/i.test(String(error))) { + if ( + !this.process.adopted && + this.started && + error instanceof ArfRpcError && + error.code === ARF_TIMEOUT + ) { return; } + if (!this.started) { + this.finished(submission.id); + } throw error; } + this.register(submission.id, result.execution_id); if (this.process.adopted) { for (const channel of ['stdout', 'stderr']) { if (typeof result[channel] === 'string' && result[channel]) { diff --git a/src/interactive/backends/arfInspection.ts b/src/interactive/backends/arfInspection.ts new file mode 100644 index 000000000..9ad446c59 --- /dev/null +++ b/src/interactive/backends/arfInspection.ts @@ -0,0 +1,370 @@ +import * as path from 'path'; +import { + ARF_HANDLER_EXECUTION_TIMEOUT, + ARF_HANDLER_INTERRUPTED, + ARF_HANDLER_NOT_FOUND, + ARF_HANDLER_QUEUE_FULL, + ARF_HANDLER_QUEUE_TIMEOUT, + ARF_HANDLER_R_ERROR, + ArfRpcError, + ArfTransportTimeoutError, +} from '../arf'; +import { INSPECTION_METHODS, InspectionMethod, InspectionRequest } from '../backend'; +import { object } from '../protocol'; +import { rString } from './rCode'; + +/** + * Namespace of the handlers that sess publishes to arf. The `.json` marks the + * contract: a handler takes the request parameters as one JSON string and + * returns one JSON string. A strict-JSON variant would use another namespace. + */ +export const INSPECTION_NAMESPACE = 'vscode-r.inspect.json'; + +export function inspectionSelector(method: InspectionMethod): string { + return `${INSPECTION_NAMESPACE}/${method}`; +} + +export const INSPECTION_SELECTORS: readonly string[] = INSPECTION_METHODS.map(inspectionSelector); + +/** + * The R expression for arf's `--ipc-expose`. It reads the handler table from + * the installed private sess without loading sess, which arf could not load + * from the private library yet, and without picking up a sess of the user's. + */ +export function exposeInspectionExpression(library: string): string { + const file = path.join(library, 'sess', 'arf', 'expose-inspection.R'); + return ( + `base::source(${rString(file)}, local=base::new.env(parent=base::baseenv()))$value(` + + `${rString(library)})` + ); +} + +/** The handler table that arf reports for a session. */ +export interface ArfHandlerApi { + state: string; + handlers: string[]; +} + +export function parseHandlerApi(session: Record): ArfHandlerApi | undefined { + const api = session.handler_api; + if (!api || typeof api !== 'object' || Array.isArray(api)) { + return undefined; + } + const { state, handlers } = api as Record; + return typeof state === 'string' && Array.isArray(handlers) + ? { state, handlers: handlers.filter((name): name is string => typeof name === 'string') } + : undefined; +} + +/** + * Whether inspection can use handler calls and their execution deadlines: the + * session's handler list is locked and has every selector. A session started + * by Interactive must publish them; an adopted one without them keeps + * inspection on the sess socket, where it cannot be interrupted. + */ +export function inspectionCallsAvailable(api: ArfHandlerApi | undefined): boolean { + return ( + api?.state === 'locked' && + INSPECTION_SELECTORS.every((selector) => api.handlers.includes(selector)) + ); +} + +export type InspectionFailure = + /** R did not start the request in time, so it did not run. */ + | 'queue_timeout' + /** The request started and was interrupted when its execution deadline passed. */ + | 'deadline' + /** The client stopped waiting; the request may still be running. */ + | 'transport_timeout' + /** The handler raised an R error. */ + | 'r_error' + /** The handler was interrupted without a deadline. */ + | 'interrupted' + /** The handler is not published, or has been revoked. */ + | 'unpublished' + /** arf refused the call for another reason, such as a full queue. */ + | 'rejected' + /** More requests are waiting than the client allows. */ + | 'overloaded' + | 'closed'; + +export class InspectionError extends Error { + constructor( + readonly kind: InspectionFailure, + message: string, + /** The R condition classes of an R error. */ + readonly rClass: string[] = [], + ) { + super(message); + this.name = 'InspectionError'; + } +} + +/** Limits of one call, in milliseconds. */ +export interface CallLimits { + queue: number; + execution: number; + /** How long to wait for arf's reply, which follows the handler's stop. */ + transport: number; +} + +function strings(value: unknown): string[] { + return Array.isArray(value) + ? value.filter((item): item is string => typeof item === 'string') + : []; +} + +/** Names the failure of a call, keeping the cause apart from the others. */ +export function inspectionFailure(error: unknown, method: string, limits: CallLimits): unknown { + if (error instanceof ArfTransportTimeoutError) { + return new InspectionError( + 'transport_timeout', + `R inspection '${method}' received no reply within ${limits.transport} ms; it may still be running in R`, + ); + } + if (!(error instanceof ArfRpcError)) { + return error; + } + const data = + error.data && typeof error.data === 'object' && !Array.isArray(error.data) + ? (error.data as Record) + : {}; + switch (error.code) { + case ARF_HANDLER_EXECUTION_TIMEOUT: + return new InspectionError( + 'deadline', + `R inspection '${method}' exceeded its execution deadline of ${limits.execution} ms and was interrupted`, + strings(data.class), + ); + case ARF_HANDLER_QUEUE_TIMEOUT: + return new InspectionError( + 'queue_timeout', + `R inspection '${method}' did not start within ${limits.queue} ms; R was busy`, + ); + case ARF_HANDLER_R_ERROR: + return new InspectionError( + 'r_error', + `R inspection '${method}' failed: ${typeof data.message === 'string' ? data.message : error.rpcMessage}`, + strings(data.class), + ); + case ARF_HANDLER_INTERRUPTED: + return new InspectionError( + 'interrupted', + `R inspection '${method}' was interrupted`, + strings(data.class), + ); + case ARF_HANDLER_NOT_FOUND: + return new InspectionError( + 'unpublished', + `R inspection '${method}' is not published by this arf session, or its handlers were revoked`, + ); + case ARF_HANDLER_QUEUE_FULL: + default: + return new InspectionError( + 'rejected', + `arf rejected R inspection '${method}': ${error.rpcMessage || error.message}`, + ); + } +} + +/** + * Decodes a handler call's result: its `value` is a JSON string holding an + * object with a version and, unless R returned NULL, a `result`. A missing + * result decodes to `undefined`, as an omitted result does on the sess socket. + */ +export function decodeInspectionResult(reply: unknown): unknown { + const value = object(reply).value; + if (typeof value !== 'string') { + throw new Error('arf returned an inspection result that is not a JSON string'); + } + let message: Record; + try { + message = object(JSON.parse(value)); + } catch { + throw new Error('arf returned an inspection result that is not valid JSON'); + } + if (message.version !== 1) { + throw new Error('sess returned an inspection result of an unsupported version'); + } + return message.result; +} + +/** The most requests that wait for R at once. */ +const MAX_PENDING = 32; +/** The longest arf accepts for either of its call timeouts. */ +const MAX_CALL_TIMEOUT = 300000; +/** Added to the transport wait so that arf's reply can arrive after a deadline. */ +const TRANSPORT_MARGIN = 5000; +/** Requests that only read, so identical ones in flight can share an answer. */ +const COALESCED: ReadonlySet = new Set([ + 'workspace', + 'workspace_children', + 'hover', + 'completion', + 'dataview_page', +]); + +interface Job { + request: InspectionRequest; + key?: string; + limits: CallLimits; + /** When the request must have started, waiting here and in arf together. */ + startBy: number; + promise: Promise; + resolve(value: unknown): void; + reject(error: unknown): void; + timer?: NodeJS.Timeout; +} + +export type CallTransport = ( + selector: string, + args: string, + limits: CallLimits, +) => Promise; + +/** + * Sends inspection requests to arf one at a time. + * + * arf serializes calls anyway, so waiting here costs no time while keeping + * its queue (64 calls, shared by all clients) from filling up. Requests that + * wait are bounded: identical read-only ones share one call, a request that + * has waited as long as its own timeout fails as a queue timeout, and there is + * a hard limit on how many wait. Requests that differ are never dropped for + * one another, since they can come from different clients. + * + * Each request's timeout is its execution deadline. A request stopped by its + * deadline is an error, as is an interrupt or a failure to reach arf. An R + * error in hover or completion means that nothing was found and is `null`. + * + * After a transport timeout the next request is sent although the previous + * handler may still be running, for example in native code that ignores the + * interrupt. It cannot run alongside: arf runs calls one at a time, so it + * waits in arf's queue and is dropped unrun when its queue timeout passes. The + * connection is not closed to cancel it, because it also carries the events + * that track submitted code. A late reply is ignored by its request ID. + */ +export class InspectionCalls { + private waiting: Job[] = []; + private running?: Job; + private closed?: Error; + + constructor(private readonly transport: CallTransport) {} + + request(request: InspectionRequest): Promise { + if (this.closed) { + return Promise.reject(this.closed); + } + const timeout = Math.min( + MAX_CALL_TIMEOUT, + Math.max(1, Math.trunc(Number(request.timeout ?? 5000)) || 1), + ); + const key = COALESCED.has(request.method) + ? `${request.method}\0${timeout}\0${JSON.stringify(request.params)}` + : undefined; + if (key) { + for (const job of [this.running, ...this.waiting]) { + if (job?.key === key) { + return job.promise; + } + } + } + if (this.waiting.length >= MAX_PENDING) { + return Promise.reject( + new InspectionError('overloaded', 'Too many R inspection requests are waiting'), + ); + } + const limits = { + queue: timeout, + execution: timeout, + transport: 2 * timeout + TRANSPORT_MARGIN, + }; + const job = { request, key, limits, startBy: Date.now() + timeout } as Job; + job.promise = new Promise((resolve, reject) => { + job.resolve = resolve; + job.reject = reject; + }); + job.timer = setTimeout(() => { + this.drop(job); + job.reject( + new InspectionError( + 'queue_timeout', + `R inspection '${request.method}' waited ${timeout} ms for earlier requests`, + ), + ); + }, timeout); + this.waiting.push(job); + this.pump(); + return job.promise; + } + + /** Fails the waiting requests; one that already runs ends with its call. */ + close(reason: Error = new Error('R inspection was closed')): void { + this.closed ??= reason; + for (const job of this.waiting.splice(0)) { + clearTimeout(job.timer); + job.reject(reason); + } + } + + private drop(job: Job): void { + clearTimeout(job.timer); + const index = this.waiting.indexOf(job); + if (index >= 0) { + this.waiting.splice(index, 1); + } + } + + private pump(): void { + if (this.running || this.closed) { + return; + } + const job = this.waiting.shift(); + if (!job) { + return; + } + clearTimeout(job.timer); + // The time spent waiting here counts towards the wait to start, so arf + // gets only what is left of it. + const queue = Math.ceil(job.startBy - Date.now()); + if (queue < 1) { + job.reject( + new InspectionError( + 'queue_timeout', + `R inspection '${job.request.method}' waited ${job.limits.queue} ms for earlier requests`, + ), + ); + this.pump(); + return; + } + job.limits = { + queue, + execution: job.limits.execution, + transport: queue + job.limits.execution + TRANSPORT_MARGIN, + }; + this.running = job; + const { method, params } = job.request; + void Promise.resolve() + .then(() => + this.transport(inspectionSelector(method), JSON.stringify(params), job.limits), + ) + .then(decodeInspectionResult, (error: unknown) => { + const failure = inspectionFailure(error, method, job.limits); + if ( + failure instanceof InspectionError && + failure.kind === 'r_error' && + (method === 'hover' || method === 'completion') + ) { + return null; + } + throw failure; + }) + .then( + (value) => job.resolve(value), + (error: unknown) => job.reject(error), + ) + .finally(() => { + this.running = undefined; + this.pump(); + }); + } +} diff --git a/src/interactive/backends/process.ts b/src/interactive/backends/process.ts index 8263df2c3..0c8643d5f 100644 --- a/src/interactive/backends/process.ts +++ b/src/interactive/backends/process.ts @@ -9,7 +9,6 @@ export class RuntimeProcess { private exited = false; private closed = false; private monitor?: NodeJS.Timeout; - private stopping?: Promise; constructor( readonly adopted: boolean, private emit: (event: BackendEvent) => void, @@ -53,7 +52,7 @@ export class RuntimeProcess { this.monitor.unref(); } } - private alive(): boolean { + alive(): boolean { if (this.exited || !this.pid) { return false; } @@ -77,7 +76,15 @@ export class RuntimeProcess { this.emit({ type: 'exit', code, signal }); } } - private signal(signal: NodeJS.Signals): void { + /** Records an exit observed without a process event, such as an adopted PID that vanished. */ + markExited(): void { + this.exit(); + } + /** + * Sends a signal to the R process. The interrupt and stop paths use arf IPC + * instead: headless arf ends the whole session on SIGINT. + */ + send(signal: NodeJS.Signals): void { if (!this.alive()) { this.exit(); return; @@ -92,46 +99,27 @@ export class RuntimeProcess { } } } - interrupt(): void { - this.signal('SIGINT'); - } - stop(force = false): Promise { - return (this.stopping ??= this.stopProcess(force)); - } - private async stopProcess(force: boolean): Promise { - if (!this.pid) { - return; - } - this.signal(force ? 'SIGKILL' : 'SIGINT'); + /** Resolves true once the process has exited, or false after `timeout` ms. */ + async waitForExit(timeout: number): Promise { const start = Date.now(); - let terminated = force, - killed = force; while (this.alive()) { if (this.closed) { - return; - } - const elapsed = Date.now() - start; - if (!terminated && elapsed >= 100) { - this.signal('SIGTERM'); - terminated = true; - } - if (!killed && elapsed >= 3000) { - this.signal('SIGKILL'); - killed = true; + return true; } - if (elapsed > 5000) { - throw new Error('R has not exited after Stop'); + if (Date.now() - start >= timeout) { + return false; } await new Promise((resolve) => setTimeout(resolve, 25)); } this.exit(); + return true; } dispose(): void { if (this.closed) { return; } if (!this.adopted) { - this.signal('SIGKILL'); + this.send('SIGKILL'); } this.closed = true; clearInterval(this.monitor); diff --git a/src/interactive/backends/sessBackend.ts b/src/interactive/backends/sessBackend.ts index 39736be14..141c2cae1 100644 --- a/src/interactive/backends/sessBackend.ts +++ b/src/interactive/backends/sessBackend.ts @@ -19,6 +19,7 @@ import { SessBridge } from './sessBridge'; import { SessGraphics } from './sessGraphics'; import { Arf } from './arf'; import { rString } from './rCode'; +import { exposeInspectionExpression } from './arfInspection'; const run = promisify(execFile); export interface SessOptions { @@ -70,6 +71,9 @@ export class SessBackend implements SessionBackend { tables: true, html: true, inspection: true, + // Whether a slow inspection is stopped at its deadline, which needs + // arf handler calls. An adopted session is known only after attaching. + inspectionDeadline: options.ownership === 'managed', interrupt: process.platform !== 'win32', jgd: false, plotResize: false, @@ -172,11 +176,18 @@ export class SessBackend implements SessionBackend { const code = `base::source(${rString(path.join(this.options.resources, 'interactive-worker.R'))}, local=base::new.env(parent=base::baseenv()))$value(` + `${rString(this.options.library)}, ${rString(bootstrap)}, c(${support.map(rString).join(',')}), managed=${this.ownership === 'managed' ? 'TRUE' : 'FALSE'})`; - await this.frontend.start(code, { - ...process.env, - SESS_ENDPOINT: path.join(this.runtime, 'sess.sock'), - JGD_SOCKET: this.graphics.endpoint, - }); + // arf evaluates this after the R profiles and before the bootstrap loads + // sess, so the published handlers find sess when they are called. + const expose = exposeInspectionExpression(this.options.library); + await this.frontend.start( + code, + { + ...process.env, + SESS_ENDPOINT: path.join(this.runtime, 'sess.sock'), + JGD_SOCKET: this.graphics.endpoint, + }, + expose, + ); } async dispatch(submission: Submission): Promise { await this.startup; @@ -194,7 +205,10 @@ export class SessBackend implements SessionBackend { } } inspect(request: InspectionRequest): Promise { - return this.bridge.request(request.method, request.params, request.timeout ?? 5000); + // An adopted session that does not publish the handlers keeps the socket. + return this.frontend.callsInspection() + ? this.frontend.inspect(request) + : this.bridge.request(request.method, request.params, request.timeout ?? 5000); } replyInput(_reply: InputReply): Promise { return Promise.reject( @@ -208,13 +222,12 @@ export class SessBackend implements SessionBackend { return Promise.resolve(); } interrupt(): Promise { - this.frontend.process.interrupt(); - return Promise.resolve(); + return this.frontend.interrupt(); } async stop(options?: { force?: boolean }): Promise { // Stop may arrive after the control endpoint opens but before R is spawned. await this.startup; - await this.frontend.process.stop(options?.force); + await this.frontend.stop(options?.force); } resizePlot(request: ResizePlotRequest): Promise { this.graphics.resize(request); @@ -259,6 +272,7 @@ export class SessBackend implements SessionBackend { break; case 'ready': this.frontend.ready = true; + this.capabilities.inspectionDeadline = this.frontend.callsInspection(); this.emit({ type: 'ready', capabilities: { ...this.capabilities }, @@ -394,6 +408,7 @@ export class SessBackend implements SessionBackend { return; } this.graphics.flush(executionId); + this.frontend.finished(executionId); this.current = undefined; this.completion = undefined; this.emit({ diff --git a/src/test/node/arfAttach.test.ts b/src/test/node/arfAttach.test.ts new file mode 100644 index 000000000..a370f292e --- /dev/null +++ b/src/test/node/arfAttach.test.ts @@ -0,0 +1,721 @@ +import * as assert from 'assert'; +import * as fs from 'fs'; +import * as net from 'net'; +import * as os from 'os'; +import * as path from 'path'; +import { + ArfRpcError, + ArfTransportTimeoutError, + arfVersionAtLeast, + checkArfSession, +} from '../../interactive/arf'; +import { ArfAttachConnection, ArfEvent } from '../../interactive/arfAttach'; +import { INSPECTION_METHODS } from '../../interactive/backend'; +import { + CallLimits, + INSPECTION_SELECTORS, + InspectionCalls, + InspectionError, + InspectionFailure, + decodeInspectionResult, + exposeInspectionExpression, + inspectionCallsAvailable, + inspectionFailure, + parseHandlerApi, +} from '../../interactive/backends/arfInspection'; + +/** A fake arf server that hands each parsed line to `handle`. */ +function fakeArf( + handle: (message: Record, socket: net.Socket) => void, +): Promise<{ endpoint: string; server: net.Server; dispose(): void }> { + const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'r-arf-attach-')); + // arf listens on a named pipe on Windows and a Unix socket elsewhere. + const endpoint = + process.platform === 'win32' + ? `\\\\.\\pipe\\${path.basename(directory)}` + : path.join(directory, 'arf.sock'); + const sockets = new Set(); + const server = net.createServer((socket) => { + sockets.add(socket); + let buffer = ''; + socket.on('data', (chunk) => { + buffer += chunk.toString(); + let newline: number; + while ((newline = buffer.indexOf('\n')) >= 0) { + const line = buffer.slice(0, newline); + buffer = buffer.slice(newline + 1); + handle(JSON.parse(line) as Record, socket); + } + }); + socket.on('error', () => undefined); + }); + return new Promise((resolve) => + server.listen(endpoint, () => + resolve({ + endpoint, + server, + dispose() { + sockets.forEach((socket) => socket.destroy()); + server.close(); + fs.rmSync(directory, { recursive: true, force: true }); + }, + }), + ), + ); +} + +const line = (message: unknown): string => JSON.stringify(message) + '\n'; +async function until(predicate: () => boolean, timeout = 3000): Promise { + const deadline = Date.now() + timeout; + while (!predicate()) { + if (Date.now() > deadline) { + throw new Error('Timed out waiting for the fake arf'); + } + await new Promise((resolve) => setTimeout(resolve, 5)); + } +} +const attachResult = { + connection_id: 3, + api_version: 1, + capabilities: ['events', 'call_execution_timeout'], + session_id: 'session-a', + session: { arf_version: '0.7.1', capabilities: ['call_execution_timeout'] }, +}; + +suite('arf attach connection', () => { + test('delivers an event that arrives in the same chunk as the attach response', async () => { + const arf = await fakeArf((message, socket) => { + if (message.method === 'attach') { + socket.write( + line({ jsonrpc: '2.0', id: message.id, result: attachResult }) + + line({ + jsonrpc: '2.0', + method: 'event', + params: { + seq: 9, + topic: 'demo.started', + data: { id: 'a' }, + execution: 7, + }, + }), + ); + } + }); + try { + const events: ArfEvent[] = []; + const { connection, result } = await ArfAttachConnection.open(arf.endpoint, { + subscribe: ['demo.*'], + onEvent: (event) => events.push(event), + }); + assert.strictEqual(result.sessionId, 'session-a'); + assert.strictEqual(result.session.arf_version, '0.7.1'); + await new Promise((resolve) => setImmediate(resolve)); + assert.deepStrictEqual(events, [ + { seq: 9, topic: 'demo.started', data: { id: 'a' }, execution: 7 }, + ]); + connection.close(); + } finally { + arf.dispose(); + } + }); + + test('matches responses by ID and keeps RPC error codes and data', async () => { + const held: Record[] = []; + const arf = await fakeArf((message, socket) => { + if (message.method === 'attach') { + socket.write(line({ jsonrpc: '2.0', id: message.id, result: attachResult })); + } else { + held.push(message); + if (held.length === 2) { + // Answer in reverse order, the second one with an error. + socket.write( + line({ + jsonrpc: '2.0', + id: held[1].id, + error: { + code: -32007, + message: 'Request timed out', + data: { execution_id: 4 }, + }, + }) + line({ jsonrpc: '2.0', id: held[0].id, result: { first: true } }), + ); + } + } + }); + try { + const { connection } = await ArfAttachConnection.open(arf.endpoint); + const first = connection.request('session'); + const second = connection.request('evaluate', { code: '1' }).then( + () => assert.fail('expected an RPC error'), + (error: unknown) => error, + ); + assert.deepStrictEqual(await first, { first: true }); + const error = (await second) as ArfRpcError; + assert.ok(error instanceof ArfRpcError); + assert.strictEqual(error.code, -32007); + assert.strictEqual(error.rpcMessage, 'Request timed out'); + assert.deepStrictEqual(error.data, { execution_id: 4 }); + connection.close(); + } finally { + arf.dispose(); + } + }); + + test('ignores a late response after a local timeout and never reuses its ID', async () => { + const ids: unknown[] = []; + let late: (() => void) | undefined; + const arf = await fakeArf((message, socket) => { + if (message.method === 'attach') { + socket.write(line({ jsonrpc: '2.0', id: message.id, result: attachResult })); + return; + } + ids.push(message.id); + if (message.method === 'slow') { + late = () => socket.write(line({ jsonrpc: '2.0', id: message.id, result: 'late' })); + } else { + late?.(); + socket.write(line({ jsonrpc: '2.0', id: message.id, result: 'fresh' })); + } + }); + try { + const { connection } = await ArfAttachConnection.open(arf.endpoint); + await assert.rejects( + connection.request('slow', {}, { timeout: 20 }), + ArfTransportTimeoutError, + ); + assert.strictEqual(await connection.request('fast'), 'fresh'); + assert.notStrictEqual(ids[0], ids[1]); + assert.strictEqual(connection.closed, undefined); + connection.close(); + } finally { + arf.dispose(); + } + }); + + test('closes once, rejecting pending and later requests with the same reason', async () => { + const arf = await fakeArf((message, socket) => { + if (message.method === 'attach') { + socket.write(line({ jsonrpc: '2.0', id: message.id, result: attachResult })); + } else { + socket.destroy(); + } + }); + try { + const closes: Error[] = []; + const { connection } = await ArfAttachConnection.open(arf.endpoint, { + onClose: (reason) => closes.push(reason), + }); + const pending = connection.request('evaluate').then( + () => assert.fail('expected the request to fail'), + (error: Error) => error, + ); + const reason = await pending; + assert.strictEqual(closes.length, 1); + assert.strictEqual(closes[0], reason); + assert.strictEqual(connection.closed, reason); + await assert.rejects(connection.request('session'), (error) => error === reason); + connection.close(); + assert.strictEqual(closes.length, 1); + } finally { + arf.dispose(); + } + }); + + test('rejects a refused attach with its RPC error', async () => { + const arf = await fakeArf((message, socket) => { + socket.end( + line({ + jsonrpc: '2.0', + id: message.id, + error: { code: -32602, message: 'unsupported protocol', data: null }, + }), + ); + }); + try { + await assert.rejects( + ArfAttachConnection.open(arf.endpoint), + (error) => error instanceof ArfRpcError && error.code === -32602, + ); + } finally { + arf.dispose(); + } + }); +}); + +suite('arf version requirement', () => { + test('compares versions with SemVer precedence', () => { + assert.ok(arfVersionAtLeast('0.7.2-rc.1', '0.7.2-rc.1')); + assert.ok(arfVersionAtLeast('0.7.2-rc.10', '0.7.2-rc.2')); + assert.ok(arfVersionAtLeast('0.7.2', '0.7.2-rc.1')); + assert.ok(arfVersionAtLeast('0.10.0', '0.7.2')); + assert.ok(!arfVersionAtLeast('0.7.2-beta.9', '0.7.2-rc.1')); + assert.ok(!arfVersionAtLeast('0.7.1', '0.7.2-rc.1')); + assert.ok(!arfVersionAtLeast('latest', '0.7.1')); + }); + + test('rejects old sessions and sessions without handler call deadlines', () => { + checkArfSession({ arf_version: '0.7.2-rc.1', capabilities: ['call_execution_timeout'] }); + assert.throws( + () => + checkArfSession({ arf_version: '0.7.1', capabilities: ['call_execution_timeout'] }), + /requires arf 0\.7\.2-rc\.1 or later, but the session runs 0\.7\.1/, + ); + assert.throws(() => checkArfSession({}), /an unknown version/); + assert.throws( + () => checkArfSession({ arf_version: '0.7.2-rc.1', capabilities: [] }), + /execution deadlines/, + ); + }); +}); + +/** The `value` of a handler call reply, as sess encodes an inspection result. */ +const callReply = (result?: unknown, version = 1) => ({ + value: JSON.stringify(result === undefined ? { version } : { version, result }), + stdout: '', + stderr: '', + execution_id: 1, +}); +const rpcFailure = (id: unknown, code: number, message: string, data?: unknown): string => + line({ jsonrpc: '2.0', id, error: { code, message, data } }); + +suite('arf inspection calls', () => { + /** Runs `InspectionCalls` over a real attach connection to a fake arf. */ + async function withInspection( + handle: (message: Record, socket: net.Socket) => void, + body: (inspection: InspectionCalls, requests: Record[]) => Promise, + ): Promise { + const requests: Record[] = []; + const arf = await fakeArf((message, socket) => { + if (message.method === 'attach') { + socket.write(line({ jsonrpc: '2.0', id: message.id, result: attachResult })); + } else { + requests.push(message); + handle(message, socket); + } + }); + try { + const { connection } = await ArfAttachConnection.open(arf.endpoint); + const inspection = new InspectionCalls((selector, args, limits) => + connection.request( + 'call', + { + handler: selector, + args, + queue_timeout_ms: limits.queue, + execution_timeout_ms: limits.execution, + }, + { timeout: limits.transport }, + ), + ); + try { + await body(inspection, requests); + } finally { + inspection.close(); + connection.close(); + } + } finally { + arf.dispose(); + } + } + const reply = (socket: net.Socket, message: Record, result?: unknown) => + socket.write(line({ jsonrpc: '2.0', id: message.id, result: callReply(result) })); + const params = (message: Record) => message.params as Record; + const failure = (promise: Promise): Promise => + promise.then( + () => assert.fail('expected the inspection to fail'), + (error: unknown) => { + assert.ok(error instanceof InspectionError, String(error)); + return error; + }, + ); + + test('calls the published selector with the parameters as one JSON string and the deadline', async () => { + await withInspection( + (message, socket) => reply(socket, message, { str: 'x' }), + async (inspection, requests) => { + const result = await inspection.request({ + method: 'hover', + params: { expr: 'obj$name' }, + timeout: 1500, + }); + assert.deepStrictEqual(result, { str: 'x' }); + assert.strictEqual(requests.length, 1); + assert.strictEqual(requests[0].method, 'call'); + const { queue_timeout_ms: queue, ...sent } = params(requests[0]); + assert.deepStrictEqual(sent, { + handler: 'vscode-r.inspect.json/hover', + args: '{"expr":"obj$name"}', + execution_timeout_ms: 1500, + }); + // What is left of the wait to start, measured from the request. + assert.ok(Number(queue) > 0 && Number(queue) <= 1500, String(queue)); + }, + ); + }); + + test('decodes results as the socket delivered them, with NULL as no result', async () => { + const results = [undefined, null, [], {}, false, 'text', { rows: [[1, null]], n: 2 }]; + let index = 0; + await withInspection( + (message, socket) => reply(socket, message, results[index++]), + async (inspection) => { + for (const expected of results) { + const actual = await inspection.request({ + method: 'dataview_dispose', + params: { view_id: String(index) }, + }); + assert.deepStrictEqual(actual, expected); + } + }, + ); + assert.strictEqual(decodeInspectionResult(callReply()), undefined); + assert.strictEqual(decodeInspectionResult(callReply(null)), null); + assert.throws(() => decodeInspectionResult({ value: 3 }), /not a JSON string/); + assert.throws(() => decodeInspectionResult({ value: '{' }), /not valid JSON/); + assert.throws(() => decodeInspectionResult({ value: '[1]' }), /not valid JSON/); + assert.throws(() => decodeInspectionResult(callReply({}, 2)), /unsupported version/); + }); + + test('distinguishes queue timeout, deadline, R error, interrupt and unpublished handler', async () => { + const cases: [number, string, unknown, InspectionFailure, RegExp][] = [ + [-32012, 'Handler call expired', { timeout_ms: 7 }, 'queue_timeout', /did not start/], + [ + -32019, + 'Handler execution exceeded its 7 ms deadline', + { timeout_ms: 7, class: ['interrupt', 'condition'] }, + 'deadline', + /execution deadline of 7 ms/, + ], + [ + -32014, + 'R error', + { message: 'Unknown dataview id: v', class: ['simpleError', 'error', 'condition'] }, + 'r_error', + /failed: Unknown dataview id: v/, + ], + [-32016, 'Interrupted', { class: ['interrupt'] }, 'interrupted', /was interrupted/], + [-32010, 'No such handler', undefined, 'unpublished', /not published/], + [-32011, 'Queue full', undefined, 'rejected', /rejected.*Queue full/], + ]; + let index = 0; + await withInspection( + (message, socket) => { + const [code, text, data] = cases[index++]; + socket.write(rpcFailure(message.id, code, text, data)); + }, + async (inspection) => { + for (const [, , data, kind, pattern] of cases) { + const error = await failure( + inspection.request({ + method: 'dataview_init', + params: { view_id: String(index) }, + timeout: 7, + }), + ); + assert.strictEqual(error.kind, kind); + assert.match(error.message, pattern); + if (data && typeof data === 'object' && 'class' in data) { + assert.deepStrictEqual(error.rClass, data.class); + } + } + }, + ); + }); + + test('an R error in hover and completion is no result, and anything else is an error', async () => { + const codes = [-32014, -32014, -32019, -32016, -32012, -32014]; + let index = 0; + await withInspection( + (message, socket) => socket.write(rpcFailure(message.id, codes[index++], 'failed', {})), + async (inspection) => { + assert.strictEqual( + await inspection.request({ method: 'hover', params: { expr: '1 + 1' } }), + null, + ); + assert.strictEqual( + await inspection.request({ + method: 'completion', + params: { expr: '1 + 1', trigger: '$' }, + }), + null, + ); + // A deadline, an interrupt and a queue timeout stay errors. + for (const kind of ['deadline', 'interrupted', 'queue_timeout']) { + const error = await failure( + inspection.request({ method: 'hover', params: { expr: kind } }), + ); + assert.strictEqual(error.kind, kind); + } + // Other methods propagate an R error. + const error = await failure( + inspection.request({ method: 'workspace_view', params: { name: 'x' } }), + ); + assert.strictEqual(error.kind, 'r_error'); + }, + ); + }); + + test('waits for the reply that follows a deadline, longer than queue and execution limits', async () => { + await withInspection( + (message, socket) => { + // arf replies only after the handler stopped, which may take a while. + setTimeout( + () => socket.write(rpcFailure(message.id, -32019, 'deadline', { class: [] })), + 150, + ); + }, + async (inspection) => { + const started = Date.now(); + const error = await failure( + inspection.request({ method: 'workspace', params: {}, timeout: 50 }), + ); + assert.strictEqual(error.kind, 'deadline'); + assert.ok(Date.now() - started >= 140); + }, + ); + }); + + test('reports a lost reply as a transport timeout that may still be running', async () => { + const limits: CallLimits = { queue: 10, execution: 10, transport: 40 }; + const transport = new InspectionCalls(() => Promise.reject(new ArfTransportTimeoutError())); + const error = await failure(transport.request({ method: 'workspace', params: {} })); + assert.strictEqual(error.kind, 'transport_timeout'); + assert.match(error.message, /may still be running/); + assert.strictEqual( + (inspectionFailure(new ArfTransportTimeoutError(), 'hover', limits) as InspectionError) + .kind, + 'transport_timeout', + ); + // Failures that are not arf's replies pass through unchanged. + const lost = new Error('arf closed the IPC connection'); + assert.strictEqual(inspectionFailure(lost, 'hover', limits), lost); + }); + + test('sends one call at a time and shares identical read-only requests', async () => { + let socket!: net.Socket; + await withInspection( + (_message, connection) => { + socket = connection; + }, + async (inspection, requests) => { + const answer = async (index: number, value: unknown): Promise => { + await until(() => requests.length > index); + socket.write( + line({ jsonrpc: '2.0', id: requests[index].id, result: callReply(value) }), + ); + }; + const first = inspection.request({ method: 'workspace', params: { revision: 1 } }); + const same = inspection.request({ method: 'workspace', params: { revision: 1 } }); + const other = inspection.request({ method: 'workspace', params: { revision: 2 } }); + // Not read-only requests: each one runs. + const dispose = inspection.request({ + method: 'dataview_dispose', + params: { view_id: 'v' }, + }); + const disposeAgain = inspection.request({ + method: 'dataview_dispose', + params: { view_id: 'v' }, + }); + await until(() => requests.length === 1); + await new Promise((resolve) => setTimeout(resolve, 50)); + assert.strictEqual(requests.length, 1, 'a second call waits for the first reply'); + await answer(0, 'first'); + assert.strictEqual(await first, 'first'); + assert.strictEqual(await same, 'first'); + await answer(1, 'second'); + assert.strictEqual(await other, 'second'); + await answer(2, true); + assert.strictEqual(await dispose, true); + await answer(3, true); + assert.strictEqual(await disposeAgain, true); + assert.strictEqual(requests.length, 4); + assert.deepStrictEqual( + requests.map((request) => params(request).args), + ['{"revision":1}', '{"revision":2}', '{"view_id":"v"}', '{"view_id":"v"}'], + ); + }, + ); + }); + + test('distinct waiting hovers are each answered, as they can come from different clients', async () => { + let socket!: net.Socket; + await withInspection( + (_message, connection) => { + socket = connection; + }, + async (inspection, requests) => { + const running = inspection.request({ method: 'workspace', params: {} }); + await until(() => requests.length === 1); + const hovers = ['a', 'b'].map((expr) => + inspection.request({ method: 'hover', params: { expr } }), + ); + socket.write( + line({ jsonrpc: '2.0', id: requests[0].id, result: callReply('done') }), + ); + assert.strictEqual(await running, 'done'); + for (const [index, expr] of ['a', 'b'].entries()) { + await until(() => requests.length === index + 2); + socket.write( + line({ + jsonrpc: '2.0', + id: requests[index + 1].id, + result: callReply({ str: expr }), + }), + ); + assert.deepStrictEqual(await hovers[index], { str: expr }); + } + assert.deepStrictEqual( + requests.map((request) => params(request).args), + ['{}', '{"expr":"a"}', '{"expr":"b"}'], + ); + }, + ); + }); + + test('a request that waits as long as its timeout fails without being sent', async () => { + let socket!: net.Socket; + await withInspection( + (_message, connection) => { + socket = connection; + }, + async (inspection, requests) => { + const running = inspection.request({ + method: 'workspace', + params: {}, + timeout: 5000, + }); + await until(() => requests.length === 1); + const error = await failure( + inspection.request({ + method: 'workspace_view', + params: { name: 'x' }, + timeout: 40, + }), + ); + assert.strictEqual(error.kind, 'queue_timeout'); + assert.match(error.message, /waited 40 ms/); + socket.write(line({ jsonrpc: '2.0', id: requests[0].id, result: callReply(1) })); + assert.strictEqual(await running, 1); + await new Promise((resolve) => setTimeout(resolve, 30)); + assert.strictEqual(requests.length, 1, 'the expired request is never sent'); + }, + ); + }); + + test('a request that waited here gets only the rest of its wait to start from arf', async () => { + let socket!: net.Socket; + await withInspection( + (_message, connection) => { + socket = connection; + }, + async (inspection, requests) => { + const running = inspection.request({ method: 'workspace', params: {} }); + await until(() => requests.length === 1); + const waiting = inspection.request({ + method: 'workspace_view', + params: { name: 'x' }, + timeout: 5000, + }); + await new Promise((resolve) => setTimeout(resolve, 300)); + socket.write(line({ jsonrpc: '2.0', id: requests[0].id, result: callReply(1) })); + assert.strictEqual(await running, 1); + await until(() => requests.length === 2); + const sent = params(requests[1]); + // It waited at least 300 ms here; allow for coarse timers. + assert.ok(Number(sent.queue_timeout_ms) <= 4800, String(sent.queue_timeout_ms)); + assert.strictEqual(sent.execution_timeout_ms, 5000); + socket.write(line({ jsonrpc: '2.0', id: requests[1].id, result: callReply(2) })); + assert.strictEqual(await waiting, 2); + }, + ); + }); + + test('bounds how many requests wait and fails them when closed', async () => { + await withInspection( + () => undefined, + async (inspection, requests) => { + const first = inspection.request({ + method: 'dataview_init', + params: { view_id: '0' }, + }); + await until(() => requests.length === 1); + const waiting = Array.from({ length: 32 }, (_, index) => + inspection.request({ + method: 'dataview_init', + params: { view_id: String(index + 1) }, + }), + ); + const overflow = await failure( + inspection.request({ method: 'dataview_init', params: { view_id: 'more' } }), + ); + assert.strictEqual(overflow.kind, 'overloaded'); + inspection.close(new Error('closed for the test')); + for (const promise of waiting) { + await assert.rejects(promise, /closed for the test/); + } + await assert.rejects( + inspection.request({ method: 'workspace', params: {} }), + /closed for the test/, + ); + void first.catch(() => undefined); + }, + ); + }); +}); + +suite('arf inspection handlers', () => { + const handlers = (names: string[], state = 'locked') => ({ state, handlers: names }); + + test('publishes ten selectors in one namespace, and none for socket-only methods', () => { + assert.strictEqual(INSPECTION_SELECTORS.length, 10); + assert.strictEqual(new Set(INSPECTION_SELECTORS).size, 10); + assert.ok(INSPECTION_SELECTORS.every((name) => name.startsWith('vscode-r.inspect.json/'))); + assert.deepStrictEqual( + INSPECTION_SELECTORS, + INSPECTION_METHODS.map((method) => `vscode-r.inspect.json/${method}`), + ); + for (const method of ['interactive_stop', 'plot_latest']) { + assert.ok(!INSPECTION_SELECTORS.some((name) => name.endsWith(`/${method}`))); + } + }); + + test('inspection calls need a locked handler list with every selector', () => { + assert.ok(inspectionCallsAvailable(handlers([...INSPECTION_SELECTORS, 'demo/add']))); + assert.ok(!inspectionCallsAvailable(undefined)); + assert.ok(!inspectionCallsAvailable(handlers([], 'unexposed'))); + assert.ok(!inspectionCallsAvailable(handlers([...INSPECTION_SELECTORS], 'revoked'))); + assert.ok(!inspectionCallsAvailable(handlers([...INSPECTION_SELECTORS], 'unexposed'))); + assert.ok(!inspectionCallsAvailable(handlers(INSPECTION_SELECTORS.slice(1)))); + assert.ok( + !inspectionCallsAvailable( + handlers(INSPECTION_SELECTORS.map((name) => name.replace('.json', '.other'))), + ), + ); + }); + + test('reads the handler table of a session', () => { + assert.deepStrictEqual( + parseHandlerApi({ handler_api: { state: 'locked', handlers: ['a/b', 3, 'c/d'] } }), + { state: 'locked', handlers: ['a/b', 'c/d'] }, + ); + assert.strictEqual(parseHandlerApi({}), undefined); + assert.strictEqual(parseHandlerApi({ handler_api: [] }), undefined); + assert.strictEqual(parseHandlerApi({ handler_api: { state: 'locked' } }), undefined); + }); + + test('the published expression sources the installed table without loading sess', () => { + const expression = exposeInspectionExpression(path.join('/lib with "quote"', 'x')); + assert.match(expression, /^base::source\(/); + assert.ok( + expression.includes( + JSON.stringify( + path.join('/lib with "quote"', 'x', 'sess', 'arf', 'expose-inspection.R'), + ), + ), + ); + assert.ok( + expression.endsWith(`$value(${JSON.stringify(path.join('/lib with "quote"', 'x'))})`), + ); + assert.ok(!/loadNamespace|library\(|requireNamespace/.test(expression)); + }); +}); diff --git a/src/test/node/interactiveBackend.test.ts b/src/test/node/interactiveBackend.test.ts index 61fd303cb..8c7551b0f 100644 --- a/src/test/node/interactiveBackend.test.ts +++ b/src/test/node/interactiveBackend.test.ts @@ -4,6 +4,7 @@ import * as os from 'os'; import * as path from 'path'; import { randomUUID } from 'crypto'; import { createServer } from 'http'; +import * as net from 'net'; import { SessionAgent } from '../../interactive/agent'; import { AgentClient } from '../../interactive/client'; import { AgentConfig, ExecutionRecord, SessionEvent, Submission } from '../../interactive/protocol'; @@ -16,6 +17,8 @@ import { withBackend, } from '../../interactive/backendRegistry'; import { Arf } from '../../interactive/backends/arf'; +import { INSPECTION_SELECTORS } from '../../interactive/backends/arfInspection'; +import { SessBackend } from '../../interactive/backends/sessBackend'; class FakeBackend implements SessionBackend { readonly ownership = 'managed' as const; @@ -449,11 +452,41 @@ suite('Interactive backend configuration', () => { return; } } - response.end(JSON.stringify({ jsonrpc: '2.0', id: 1, result: {} })); + response.end(JSON.stringify({ jsonrpc: '2.0', id: 1, result: { status: 'ok' } })); }); }); + // arf serves attach (newline-delimited JSON) and HTTP on one endpoint. + const listener = net.createServer((socket) => { + socket.once('data', (chunk: Buffer) => { + if (chunk[0] === '{'.charCodeAt(0)) { + const attach = JSON.parse(chunk.toString()) as { id: number }; + socket.write( + JSON.stringify({ + jsonrpc: '2.0', + id: attach.id, + result: { + connection_id: 1, + api_version: 1, + capabilities: ['events', 'call_execution_timeout'], + session_id: 'fake', + session: { + arf_version: '0.7.2-rc.1', + capabilities: ['call_execution_timeout'], + }, + }, + }) + '\n', + ); + } else { + socket.pause(); + socket.unshift(chunk); + server.emit('connection', socket); + socket.resume(); + } + }); + socket.on('error', () => undefined); + }); const endpoint = path.join(root, 'arf.sock'); - await new Promise((resolve) => server.listen(endpoint, resolve)); + await new Promise((resolve) => listener.listen(endpoint, resolve)); const adapter = new Arf( 'unused', root, @@ -474,7 +507,272 @@ suite('Interactive backend configuration', () => { } finally { adapter.dispose(); server.closeAllConnections(); - await new Promise((resolve) => server.close(() => resolve())); + await new Promise((resolve) => listener.close(() => resolve())); } }); }); + +(process.platform === 'win32' ? suite.skip : suite)('Interactive inspection routing', function () { + this.timeout(10000); + let root: string; + let endpoints = 0; + setup(() => { + root = fs.mkdtempSync(path.join(os.tmpdir(), 'r-inspection-routing-')); + }); + teardown(() => fs.rmSync(root, { recursive: true, force: true })); + + /** + * An arf that serves attach and handler calls on the attach connection and + * evaluate over HTTP, as the real one does on one endpoint. + */ + async function fakeAttachedArf(handlerApi: Record): Promise<{ + endpoint: string; + calls: Record[]; + close(): Promise; + }> { + const calls: Record[] = []; + const http = createServer((request, response) => { + request.resume(); + request.on('end', () => + response.end(JSON.stringify({ jsonrpc: '2.0', id: 1, result: { status: 'ok' } })), + ); + }); + const sockets = new Set(); + const listener = net.createServer((socket) => { + sockets.add(socket); + socket.on('error', () => undefined); + socket.once('data', (chunk: Buffer) => { + if (chunk[0] !== '{'.charCodeAt(0)) { + socket.pause(); + socket.unshift(chunk); + http.emit('connection', socket); + socket.resume(); + return; + } + const answer = (message: Record): void => { + if (message.method === 'attach') { + socket.write( + JSON.stringify({ + jsonrpc: '2.0', + id: message.id, + result: { + connection_id: 1, + api_version: 1, + capabilities: ['events', 'call_execution_timeout'], + session_id: 'fake', + session: { + arf_version: '0.7.2', + capabilities: ['call_execution_timeout'], + handler_api: handlerApi, + }, + }, + }) + '\n', + ); + } else if (message.method === 'call') { + calls.push(message.params as Record); + socket.write( + JSON.stringify({ + jsonrpc: '2.0', + id: message.id, + result: { + value: JSON.stringify({ version: 1, result: { str: 'fake' } }), + stdout: '', + stderr: '', + execution_id: 1, + }, + }) + '\n', + ); + } + }; + let buffer = ''; + const read = (data: Buffer): void => { + buffer += data.toString(); + let newline: number; + while ((newline = buffer.indexOf('\n')) >= 0) { + answer(JSON.parse(buffer.slice(0, newline)) as Record); + buffer = buffer.slice(newline + 1); + } + }; + read(chunk); + socket.on('data', read); + }); + }); + // macOS limits Unix socket paths to 104 bytes, and its temporary + // directory is already long. + const endpoint = path.join(root, `arf-${++endpoints}.sock`); + await new Promise((resolve) => listener.listen(endpoint, resolve)); + return { + endpoint, + calls, + close: async () => { + sockets.forEach((socket) => socket.destroy()); + http.closeAllConnections(); + await new Promise((resolve) => listener.close(() => resolve())); + }, + }; + } + + async function adopt(handlerApi: Record): Promise<{ + adapter: Arf; + calls: Record[]; + close(): Promise; + }> { + const arf = await fakeAttachedArf(handlerApi); + const adapter = new Arf( + 'unused', + root, + arf.endpoint, + true, + () => undefined, + 'token', + () => undefined, + ); + await adapter.start('bootstrap', {}); + return { + adapter, + calls: arf.calls, + close: async () => { + adapter.dispose(); + await arf.close(); + }, + }; + } + + test('an adopted arf with every selector locked runs inspection as a handler call', async () => { + const session = await adopt({ state: 'locked', handlers: [...INSPECTION_SELECTORS] }); + try { + assert.ok(session.adapter.callsInspection()); + assert.deepStrictEqual( + await session.adapter.inspect({ + method: 'hover', + params: { expr: 'x' }, + timeout: 2000, + }), + { str: 'fake' }, + ); + assert.deepStrictEqual(session.calls, [ + { + handler: 'vscode-r.inspect.json/hover', + args: '{"expr":"x"}', + queue_timeout_ms: 2000, + execution_timeout_ms: 2000, + }, + ]); + } finally { + await session.close(); + } + }); + + test('an adopted arf without the locked selectors keeps the socket and says so', async () => { + for (const handlerApi of [ + { state: 'unexposed', handlers: [] }, + { state: 'locked', handlers: INSPECTION_SELECTORS.slice(1) }, + { state: 'revoked', handlers: [...INSPECTION_SELECTORS] }, + ]) { + const session = await adopt(handlerApi); + try { + assert.ok(!session.adapter.callsInspection(), JSON.stringify(handlerApi)); + } finally { + await session.close(); + } + } + }); + + test('a managed arf that does not publish every selector fails to start', async () => { + const arf = await fakeAttachedArf({ + state: 'locked', + handlers: INSPECTION_SELECTORS.slice(1), + }); + // Stands in for `arf headless --json`: it reports the fake's endpoint. + const command = path.join(root, 'arf'); + fs.writeFileSync( + command, + `#!/bin/sh\necho '${JSON.stringify({ socket_path: arf.endpoint })}'\nexec sleep 30\n`, + { mode: 0o755 }, + ); + const adapter = new Arf( + command, + root, + undefined, + false, + () => undefined, + 'token', + () => undefined, + ); + try { + await assert.rejects( + adapter.start('bootstrap', {}), + /did not publish the R Interactive inspection handlers/, + ); + } finally { + adapter.dispose(); + await arf.close(); + } + }); + + function sessBackend(ownership: 'managed' | 'adopted'): SessBackend { + return new SessBackend( + { + id: 'id', + generation: 'generation', + label: 'Routing', + directory: root, + storage: root, + provider: ownership === 'managed' ? 'arf' : 'arf-existing', + supervision: 'test', + historyLimit: 50, + maxOutputBytes: 1024, + maxJournalBytes: 1024, + }, + { + frontend: 'arf', + ownership, + rPath: 'R', + library: path.join(root, 'library'), + resources: path.join(root, 'resources'), + plotBackend: 'standard', + }, + ); + } + + test('inspection goes to arf handler calls when available and to the socket otherwise', async () => { + const requests: unknown[] = []; + for (const [ownership, calls] of [ + ['managed', true], + ['adopted', true], + ['adopted', false], + ] as const) { + const backend = sessBackend(ownership); + try { + (backend as unknown as { frontend: unknown }).frontend = { + callsInspection: () => calls, + inspect: (request: unknown) => { + requests.push(request); + return Promise.resolve('call'); + }, + dispose: () => undefined, + }; + if (calls) { + assert.strictEqual( + await backend.inspect({ method: 'workspace', params: {} }), + 'call', + ); + } else { + // The socket bridge is not connected here, so it rejects. + await assert.rejects( + backend.inspect({ method: 'workspace', params: {} }), + /R session is disconnected/, + ); + } + } finally { + await backend.dispose(); + } + } + assert.strictEqual(requests.length, 2); + }); + + test('only a managed session promises interruptible inspection before it is ready', () => { + assert.strictEqual(sessBackend('managed').capabilities.inspectionDeadline, true); + assert.strictEqual(sessBackend('adopted').capabilities.inspectionDeadline, false); + }); +}); diff --git a/src/test/node/interactiveRuntime.test.ts b/src/test/node/interactiveRuntime.test.ts index 20d1cfa95..68421b18c 100644 --- a/src/test/node/interactiveRuntime.test.ts +++ b/src/test/node/interactiveRuntime.test.ts @@ -408,41 +408,86 @@ sess::display("display-${cell}", "text/plain"); cat("stderr-${cell}\\n", file=st assert.match(text(next), /17/); }); - test('interrupts a slow inspection and continues serving R requests', async () => { - for (const afterTimeout of [false, true]) { - const marker = `inspection-started-${String(afterTimeout)}`; - // Hover does not evaluate its request, so make reading the binding slow. - const binding = `slow_inspection_${String(afterTimeout)}`; - const setup = await submit( - `makeActiveBinding("${binding}", function() { cat("${marker}"); Sys.sleep(30); 42 }, .GlobalEnv)`, + test('an interrupt between executions does not end the session', async () => { + // A signal that reaches idle headless arf ends the session, so an + // interrupt that races with completion must not be sent as a signal. + const first = await submit('kept_between <- 23'); + assert.strictEqual((await finished(first)).state, 'success'); + await assert.rejects(client.request('interrupt'), /No submitted code is running/); + const next = await submit('kept_between'); + assert.strictEqual((await finished(next)).state, 'success'); + assert.match(text(next), /23/); + }); + + test('stops a slow inspection at its execution deadline and continues serving R requests', async () => { + // Hovering a plain name reads the binding, which runs R code. It takes + // 30 seconds unless it is interrupted, and files record how far it got: + // stdout is captured by the call and cannot be used as a signal. + const started = path.join(temporary, `${randomUUID()}-started`); + const completed = path.join(temporary, `${randomUUID()}-completed`); + const binding = await submit(`makeActiveBinding( + "slow_binding", + function() { + writeLines("started", ${rString(started)}) + for (i in 1:60) Sys.sleep(0.5) + writeLines("completed", ${rString(completed)}) + 1L + }, + globalenv() +)`); + assert.strictEqual((await finished(binding)).state, 'success'); + + const begun = Date.now(); + const failure = await client + .request('inspect', { method: 'hover', params: { expr: 'slow_binding' } }) + .then( + () => undefined, + (error: Error) => error, ); - assert.strictEqual((await finished(setup)).state, 'success'); - const inspection = client - .request('inspect', { - method: 'hover', - params: { expr: binding }, - }) - .then( - () => '', - (error: Error) => error.message, - ); - await until(() => - events.some( - (event) => event.type === 'stream' && String(event.data.text).includes(marker), - ), + const elapsed = Date.now() - begun; + assert.ok(failure, 'a slow inspection must fail rather than return a value'); + assert.match(failure.message, /execution deadline/i); + assert.ok(fs.existsSync(started), 'the binding must have started'); + // The deadline is 5 seconds; the binding alone would take 30. + assert.ok(elapsed >= 4000 && elapsed < 15000, `stopped after ${elapsed} ms`); + + // R is free again at once: it was not left running the binding. + const next = await submit('21 * 2'); + assert.strictEqual((await finished(next)).state, 'success'); + assert.match(text(next), /42/); + assert.ok(Date.now() - begun < 20000); + assert.ok(!fs.existsSync(completed), 'the binding must have been interrupted'); + assert.ok(await client.request('inspect', { method: 'workspace' })); + }); + + test('hover and completion do not evaluate their request text', async () => { + const id = await submit('evaluated <- FALSE; items <- list(a = 1, b = 2)'); + assert.strictEqual((await finished(id)).state, 'success'); + // A request that is not a name or an accessor chain finds nothing. + for (const expr of ['{ evaluated <<- TRUE; 1 }', 'evaluated <<- TRUE', 'repeat items']) { + assert.ok(!(await client.request('inspect', { method: 'hover', params: { expr } }))); + assert.ok( + !(await client.request('inspect', { + method: 'completion', + params: { expr, trigger: '$' }, + })), ); - if (afterTimeout) { - assert.match(await inspection, /timed out/i); - } - await client.request('interrupt'); - if (!afterTimeout) { - assert.match(await inspection, /interrupted/i); - } - const next = await submit('21 * 2'); - assert.strictEqual((await finished(next)).state, 'success'); - assert.match(text(next), /42/); - assert.ok(await client.request('inspect', { method: 'workspace' })); } + const hover = await client.request<{ str: string }>('inspect', { + method: 'hover', + params: { expr: 'items$a' }, + }); + assert.match(hover.str, /1/); + const items = await client.request<{ name: string }[]>('inspect', { + method: 'completion', + params: { expr: 'items', trigger: '$' }, + }); + assert.deepStrictEqual( + items.map((item) => item.name), + ['a', 'b'], + ); + const check = await submit('stopifnot(!evaluated)'); + assert.strictEqual((await finished(check)).state, 'success'); }); test('data inspection preserves random draws and reproducible resampling across cells', async () => { diff --git a/src/test/node/mise.lock b/src/test/node/mise.lock new file mode 100644 index 000000000..0ec64bf97 --- /dev/null +++ b/src/test/node/mise.lock @@ -0,0 +1,25 @@ +# @generated - this file is auto-generated by `mise lock` https://mise.jdx.dev/dev-tools/mise-lock.html + +[[tools."github:eitsupi/arf"]] +version = "0.7.2-rc.1" +backend = "github:eitsupi/arf" + +[tools."github:eitsupi/arf"."platforms.linux-arm64"] +checksum = "sha256:d6b39a00952ff696a798911c2bfad9f67ba7e60ffd879b16f712bb9660139238" +url = "https://github.com/eitsupi/arf/releases/download/v0.7.2-rc.1/arf-console-aarch64-unknown-linux-gnu.tar.xz" +url_api = "https://api.github.com/repos/eitsupi/arf/releases/assets/750984106" + +[tools."github:eitsupi/arf"."platforms.linux-x64"] +checksum = "sha256:1ebd9711834874549471109e9aa280cb0cc8b02d941d751cf5770fd3a00792b6" +url = "https://github.com/eitsupi/arf/releases/download/v0.7.2-rc.1/arf-console-x86_64-unknown-linux-gnu.tar.xz" +url_api = "https://api.github.com/repos/eitsupi/arf/releases/assets/750984182" + +[tools."github:eitsupi/arf"."platforms.macos-arm64"] +checksum = "sha256:1814f7057bf324908b98a5586a5ae7970b71c57572b81be7445836727cc6f9dc" +url = "https://github.com/eitsupi/arf/releases/download/v0.7.2-rc.1/arf-console-aarch64-apple-darwin.tar.xz" +url_api = "https://api.github.com/repos/eitsupi/arf/releases/assets/750984111" + +[tools."github:eitsupi/arf"."platforms.macos-x64"] +checksum = "sha256:123dd5fa45b14d96c2b46609063c8424fdba25ced91976b4ebab9eae187178f3" +url = "https://github.com/eitsupi/arf/releases/download/v0.7.2-rc.1/arf-console-x86_64-apple-darwin.tar.xz" +url_api = "https://api.github.com/repos/eitsupi/arf/releases/assets/750984161" diff --git a/src/test/node/mise.toml b/src/test/node/mise.toml new file mode 100644 index 000000000..752eb4bef --- /dev/null +++ b/src/test/node/mise.toml @@ -0,0 +1,8 @@ +# Tools for the Interactive runtime tests. mise.lock pins each platform's +# download and checksum; run `mise lock` after changing a version. +[tools] +# arf is not installed on Windows, where Interactive runtime tests do not run. +"github:eitsupi/arf" = { version = "0.7.2-rc.1", os = ["linux", "macos"] } + +[settings] +lockfile = true diff --git a/website/docs/features/r-interactive.md b/website/docs/features/r-interactive.md index 7fda3f803..361f58042 100644 --- a/website/docs/features/r-interactive.md +++ b/website/docs/features/r-interactive.md @@ -18,7 +18,7 @@ The R host needs: - The session agent automatically uses the extension host's bundled runtime: VS Code's Electron runtime in Node mode on desktop, or VS Code Server's Node runtime remotely. A separate Node.js installation is optional. - `tmux` is optional. On Linux, the default supervisor uses tmux when available and otherwise starts an independent detached process. `systemd --user` is another configurable option. - R packages processx, later, jsonlite, and rstudioapi. Install languageserver for language features, jgd and systemfonts for jgd graphics, svglite for the static fallback, and htmlwidgets/htmltools for HTML output. -- arf. Creating a new Interactive session requires an arf executable on the R host. Connecting to an already-running arf uses its socket and does not require arf on the extension host's PATH. The provider contract is tested with arf 0.5.3. +- arf. Creating a new Interactive session requires an arf executable on the R host. Connecting to an already-running arf uses its socket and does not require arf on the extension host's PATH. R Interactive requires arf 0.7.2-rc.1 or later. For example, run in the R installation used on the server: