From 12180fb6ecb0c8de4742b72db957a867eba5360a Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sun, 15 Nov 2026 07:54:25 +0000 Subject: [PATCH 01/19] feat(interactive): keep arf JSON-RPC errors and require arf 0.7.1 arfRequest now rejects with an ArfRpcError that keeps the error code and data, and with ArfTransportTimeoutError when the client stops waiting, so callers can tell a server timeout from other failures without matching messages. Add the version check for Interactive sessions: arf 0.7.1 or later, with execution deadlines for handler calls. Prereleases count as older than their release. A TODO records that the minimum should move to 0.7.2 once it is released. --- src/interactive/arf.ts | 89 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 83 insertions(+), 6 deletions(-) diff --git a/src/interactive/arf.ts b/src/interactive/arf.ts index e4ba799ff..38af2921a 100644 --- a/src/interactive/arf.ts +++ b/src/interactive/arf.ts @@ -13,6 +13,87 @@ export interface ArfSession { session_type?: string; } +// TODO: Require arf 0.7.2 once it is released. It reports an R error that +// follows a caught interrupt as an error rather than as interrupted, and bounds +// console reads that cannot be answered. +export const MIN_ARF_VERSION = '0.7.1'; + +/** arf JSON-RPC error codes that the Interactive client acts on. */ +export const ARF_METHOD_NOT_FOUND = -32601; +export const ARF_TIMEOUT = -32007; + +/** 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, + ); +} + +/** Compares release versions; prereleases count as older than their release. */ +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.-]+)?$/.exec(text); + return match + ? { core: [Number(match[1]), Number(match[2]), Number(match[3])], pre: !!match[4] } + : 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]; + } + } + return !actual.pre || required.pre; +} + +/** 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 +133,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 +144,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); From 5df0c24acb34ec1bf85eacb2a33524554c6cf21d Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sun, 15 Nov 2026 07:54:25 +0000 Subject: [PATCH 02/19] feat(interactive): add a long-lived arf IPC connection ArfAttachConnection attaches to arf over newline-delimited JSON-RPC, matches responses by ID, and delivers events to a listener registered before attaching, so an event in the same chunk as the attach response is not lost. A request that times out or is aborted locally may still run in R; its late response is ignored and its ID is not reused. The connection closes once and rejects every pending request with the same reason; it never reconnects. --- src/interactive/arfAttach.ts | 219 ++++++++++++++++++++++++++++ src/test/node/arfAttach.test.ts | 246 ++++++++++++++++++++++++++++++++ 2 files changed, 465 insertions(+) create mode 100644 src/interactive/arfAttach.ts create mode 100644 src/test/node/arfAttach.test.ts diff --git a/src/interactive/arfAttach.ts b/src/interactive/arfAttach.ts new file mode 100644 index 000000000..e080eee3e --- /dev/null +++ b/src/interactive/arfAttach.ts @@ -0,0 +1,219 @@ +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; + /** 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); + } + }); + 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/test/node/arfAttach.test.ts b/src/test/node/arfAttach.test.ts new file mode 100644 index 000000000..efece97c0 --- /dev/null +++ b/src/test/node/arfAttach.test.ts @@ -0,0 +1,246 @@ +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'; + +/** 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-')); + const endpoint = 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'; +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 release versions and treats prereleases as older', () => { + assert.ok(arfVersionAtLeast('0.7.1', '0.7.1')); + assert.ok(arfVersionAtLeast('0.7.2', '0.7.1')); + assert.ok(arfVersionAtLeast('0.10.0', '0.7.1')); + assert.ok(arfVersionAtLeast('1.0.0', '0.7.1')); + assert.ok(arfVersionAtLeast('0.7.2-beta.1', '0.7.1')); + assert.ok(!arfVersionAtLeast('0.7.1-beta.1', '0.7.1')); + assert.ok(!arfVersionAtLeast('0.7.0', '0.7.1')); + assert.ok(!arfVersionAtLeast('0.5.3', '0.7.1')); + assert.ok(!arfVersionAtLeast(undefined, '0.7.1')); + assert.ok(!arfVersionAtLeast('0.7', '0.7.1')); + assert.ok(!arfVersionAtLeast('latest', '0.7.1')); + }); + + test('rejects old sessions and sessions without handler call deadlines', () => { + checkArfSession({ arf_version: '0.7.1', capabilities: ['call_execution_timeout'] }); + assert.throws( + () => checkArfSession({ arf_version: '0.5.3', capabilities: [] }), + /requires arf 0\.7\.1 or later, but the session runs 0\.5\.3/, + ); + assert.throws(() => checkArfSession({}), /an unknown version/); + assert.throws( + () => checkArfSession({ arf_version: '0.7.1', capabilities: [] }), + /execution deadlines/, + ); + }); +}); From 699041a732474af301422986a924d59b2e3874ca Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sun, 15 Nov 2026 07:54:25 +0000 Subject: [PATCH 03/19] fix(interactive): interrupt and stop arf through IPC instead of signals Interrupting an Interactive submission sent SIGINT to the arf process. When the signal reached headless arf while R was idle, for example just before evaluation started or after it finished, it ended the whole session; this made the adopted-session interrupt test fail intermittently. The backend now attaches to arf before submitting code, and sess publishes an event with the submission ID before running it, so the event's arf execution ID identifies the submission (a managed user_input acknowledgement reports the same ID). An interrupt is sent as an arf IPC interrupt for that ID, held until the ID is known and dropped once sess reports completion. With nothing running, interrupt now fails instead of signalling R. Stop sends arf shutdown, waits for the process to exit and kills it after a deadline. An interactive arf rejects shutdown as an unknown method, and only that answer falls back to SIGTERM and then SIGKILL. The bootstrap evaluation must report status "ok". Interrupting slow inspection is not supported yet; it will use execution deadlines of handler calls. --- sess/R/interactive.R | 20 +++ src/interactive/README.md | 21 ++- src/interactive/backends/arf.ts | 199 ++++++++++++++++++++++- src/interactive/backends/process.ts | 46 ++---- src/interactive/backends/sessBackend.ts | 6 +- src/test/node/interactiveBackend.test.ts | 37 ++++- src/test/node/interactiveRuntime.test.ts | 11 ++ 7 files changed, 292 insertions(+), 48 deletions(-) diff --git a/sess/R/interactive.R b/sess/R/interactive.R index 78beb36c9..5c6ee2004 100644 --- a/sess/R/interactive.R +++ b/sess/R/interactive.R @@ -53,6 +53,25 @@ 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) { + 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 +352,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/src/interactive/README.md b/src/interactive/README.md index 290745047..fc8e7fe88 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,17 @@ 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. + 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 +76,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.1 or later and is tested with +the version pinned in `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. diff --git a/src/interactive/backends/arf.ts b/src/interactive/backends/arf.ts index 064dfa4e1..79b04f395 100644 --- a/src/interactive/backends/arf.ts +++ b/src/interactive/backends/arf.ts @@ -1,15 +1,37 @@ -import { arfRequest } from '../arf'; +import { + ARF_METHOD_NOT_FOUND, + ARF_TIMEOUT, + ArfRpcError, + arfRequest, + checkArfSession, +} from '../arf'; +import { ArfAttachConnection, ArfEvent } from '../arfAttach'; import { BackendEvent } from '../backend'; import { object, Submission } from '../protocol'; import { RuntimeProcess } from './process'; import { rString } from './rCode'; import { ArfOutput } from './arfOutput'; +/** Topic that sess publishes before running submitted code under arf. */ +const STARTED_TOPIC = 'vscode-r.interactive.started'; + +/** 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 sessionId?: string; + private execution?: Execution; + private failure?: Error; + private stopping?: Promise; constructor( private command: string, private directory: string, @@ -100,9 +122,9 @@ 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); this.emit({ type: 'provider', data: { @@ -120,19 +142,169 @@ 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}`); } } + private async connect(): Promise> { + const { connection, result } = await ArfAttachConnection.open(this.endpoint!, { + subscribe: [STARTED_TOPIC], + client: { name: 'vscode-R Interactive' }, + 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'); + } + this.sessionId = result.sessionId; + this.attach = connection; + return result.session; + } dispose(): void { this.abort.abort(); + 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) { + // TODO: Interrupt slow inspection through execution deadlines of + // handler calls; sess runs it where arf does not deliver interrupts. + 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; + } + if (!this.attach || this.attach.closed) { + // The previous execution has finished, so attaching again loses no + // state; the session must still be the same arf process. + await this.connect(); + } 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 +321,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/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..01e15bb5e 100644 --- a/src/interactive/backends/sessBackend.ts +++ b/src/interactive/backends/sessBackend.ts @@ -208,13 +208,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); @@ -394,6 +393,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/interactiveBackend.test.ts b/src/test/node/interactiveBackend.test.ts index 61fd303cb..e894ea725 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'; @@ -449,11 +450,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.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 +505,7 @@ suite('Interactive backend configuration', () => { } finally { adapter.dispose(); server.closeAllConnections(); - await new Promise((resolve) => server.close(() => resolve())); + await new Promise((resolve) => listener.close(() => resolve())); } }); }); diff --git a/src/test/node/interactiveRuntime.test.ts b/src/test/node/interactiveRuntime.test.ts index a7543c33d..b948c0bf8 100644 --- a/src/test/node/interactiveRuntime.test.ts +++ b/src/test/node/interactiveRuntime.test.ts @@ -408,6 +408,17 @@ sess::display("display-${cell}", "text/plain"); cat("stderr-${cell}\\n", file=st assert.match(text(next), /17/); }); + 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('interrupts a slow inspection and continues serving R requests', async () => { for (const afterTimeout of [false, true]) { const marker = `inspection-started-${String(afterTimeout)}`; From 929bc90217c1cdb49f344579526b7aa6678f4f5f Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sun, 15 Nov 2026 07:54:25 +0000 Subject: [PATCH 04/19] ci: install arf 0.7.1 for Interactive tests with mise mise.toml pins arf, and mise.lock records the download and checksum for each platform, replacing the hand-written download and checksum script. arf is still not installed on Windows. ARF_PATH points at the installed binary. --- .../actions/prepare-test-runtime/action.yml | 28 ++++++------------- CONTRIBUTING.md | 2 +- mise.lock | 25 +++++++++++++++++ mise.toml | 8 ++++++ 4 files changed, 42 insertions(+), 21 deletions(-) create mode 100644 mise.lock create mode 100644 mise.toml diff --git a/.github/actions/prepare-test-runtime/action.yml b/.github/actions/prepare-test-runtime/action.yml index 098f8b037..821fe45d5 100644 --- a/.github/actions/prepare-test-runtime/action.yml +++ b/.github/actions/prepare-test-runtime/action.yml @@ -37,27 +37,15 @@ runs: - name: Compile test files run: pnpm run clean && pnpm exec tsc shell: bash - - name: Install arf binary for Interactive tests + # 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 + - name: Expose arf for Interactive tests if: runner.os != 'Windows' shell: bash - env: - RUNNER_OS_NAME: ${{ runner.os }} 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 c0091396b..642d31879 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 wiki page](https://github.com/REditorSupport/vscode-R/wiki/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.1 or later. `mise install` installs the arf version pinned in `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 diff --git a/mise.lock b/mise.lock new file mode 100644 index 000000000..b2eb53bd7 --- /dev/null +++ b/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.1" +backend = "github:eitsupi/arf" + +[tools."github:eitsupi/arf"."platforms.linux-arm64"] +checksum = "sha256:ac305016f81568a8382ce60e4840ec1e08d10c19784accaf3d20fc60c4be35a2" +url = "https://github.com/eitsupi/arf/releases/download/v0.7.1/arf-console-aarch64-unknown-linux-gnu.tar.xz" +url_api = "https://api.github.com/repos/eitsupi/arf/releases/assets/747777115" + +[tools."github:eitsupi/arf"."platforms.linux-x64"] +checksum = "sha256:05e9f4df17b6def75a6b8356e732c64d70e173ff4dee41d844d50c63b136f211" +url = "https://github.com/eitsupi/arf/releases/download/v0.7.1/arf-console-x86_64-unknown-linux-gnu.tar.xz" +url_api = "https://api.github.com/repos/eitsupi/arf/releases/assets/747777208" + +[tools."github:eitsupi/arf"."platforms.macos-arm64"] +checksum = "sha256:c790f1459355c6774589f8a7f058be203519c105f8605c9380d5b94fca6e935a" +url = "https://github.com/eitsupi/arf/releases/download/v0.7.1/arf-console-aarch64-apple-darwin.tar.xz" +url_api = "https://api.github.com/repos/eitsupi/arf/releases/assets/747777120" + +[tools."github:eitsupi/arf"."platforms.macos-x64"] +checksum = "sha256:a2b9cd4b00775674a1d2d2af56e4684268a5042afa6f12b0d02dd9407c498f44" +url = "https://github.com/eitsupi/arf/releases/download/v0.7.1/arf-console-x86_64-apple-darwin.tar.xz" +url_api = "https://api.github.com/repos/eitsupi/arf/releases/assets/747777182" diff --git a/mise.toml b/mise.toml new file mode 100644 index 000000000..40270fe1d --- /dev/null +++ b/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.1", os = ["linux", "macos"] } + +[settings] +lockfile = true From d68b2b312d97fb604b1efcff5a789066840d978b Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sun, 15 Nov 2026 08:08:01 +0000 Subject: [PATCH 05/19] test(interactive): run the fake arf on a named pipe on Windows Also suppress Arity's routine-registration rule where sess calls the arf routines: they are registered by the embedding host, so there is no package symbol to bind. --- sess/R/interactive.R | 1 + src/test/node/arfAttach.test.ts | 6 +++++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/sess/R/interactive.R b/sess/R/interactive.R index 5c6ee2004..ccd178c1b 100644 --- a/sess/R/interactive.R +++ b/sess/R/interactive.R @@ -58,6 +58,7 @@ # 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) diff --git a/src/test/node/arfAttach.test.ts b/src/test/node/arfAttach.test.ts index efece97c0..bb0bca127 100644 --- a/src/test/node/arfAttach.test.ts +++ b/src/test/node/arfAttach.test.ts @@ -16,7 +16,11 @@ 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-')); - const endpoint = path.join(directory, 'arf.sock'); + // 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); From d9a983f74f5cb9ba10552f6a0d3584f747de044a Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sun, 15 Nov 2026 08:38:45 +0000 Subject: [PATCH 06/19] test: experiment without attach to isolate a macOS fork failure (to be reverted) --- sess/R/interactive.R | 1 + src/interactive/backends/arf.ts | 11 +++++------ src/test/node/interactiveRuntime.test.ts | 6 +++++- 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/sess/R/interactive.R b/sess/R/interactive.R index ccd178c1b..38768c627 100644 --- a/sess/R/interactive.R +++ b/sess/R/interactive.R @@ -58,6 +58,7 @@ # 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) { + return(invisible(NULL)) # EXPERIMENT: no publish # 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") && diff --git a/src/interactive/backends/arf.ts b/src/interactive/backends/arf.ts index 79b04f395..3ab26528c 100644 --- a/src/interactive/backends/arf.ts +++ b/src/interactive/backends/arf.ts @@ -123,7 +123,10 @@ export class Arf { throw new Error('Missing arf endpoint'); } // Subscribe before submitting anything so that no started event is missed. - const metadata = await this.connect(); + // EXPERIMENT: no attach, to isolate a macOS fork failure. + const metadata = object( + await arfRequest(this.endpoint, 'session', {}, 30000, this.abort.signal), + ); checkArfSession(metadata); this.emit({ type: 'provider', @@ -297,11 +300,7 @@ export class Arf { if (this.failure) { throw this.failure; } - if (!this.attach || this.attach.closed) { - // The previous execution has finished, so attaching again loses no - // state; the session must still be the same arf process. - await this.connect(); - } + // EXPERIMENT: no attach. 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 }; diff --git a/src/test/node/interactiveRuntime.test.ts b/src/test/node/interactiveRuntime.test.ts index b948c0bf8..73a0c4cbc 100644 --- a/src/test/node/interactiveRuntime.test.ts +++ b/src/test/node/interactiveRuntime.test.ts @@ -1093,10 +1093,14 @@ dt`); for (j in 1:10) cat(strrep(as.character(i), 8192)) i * 2L }, mc.cores = 4) + cat("\nEXPERIMENT values:\n"); print(lapply(values, function(v) list(class = class(v), value = if (inherits(v, "try-error")) conditionMessage(attr(v, "condition")) else v))) + print(warnings()); cat("EXPERIMENT warn option:", getOption("warn"), "\n") stopifnot(identical(unlist(values), c(2L, 4L, 6L, 8L))) cat("parallel complete") `); - assert.strictEqual((await finished(id)).state, 'success'); + const state = (await finished(id)).state; + console.log('EXPERIMENT transcript:', JSON.stringify(text(id).slice(-4000))); + assert.strictEqual(state, 'success'); assert.match(text(id), /parallel complete/); const next = await submit('21 * 2'); assert.strictEqual((await finished(next)).state, 'success'); From 9dcc503bff8c01039c20abc3f933e88d67b43104 Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sun, 15 Nov 2026 08:48:00 +0000 Subject: [PATCH 07/19] Revert "test: experiment without attach to isolate a macOS fork failure (to be reverted)" This reverts commit d9a983f74f5cb9ba10552f6a0d3584f747de044a. --- sess/R/interactive.R | 1 - src/interactive/backends/arf.ts | 11 ++++++----- src/test/node/interactiveRuntime.test.ts | 6 +----- 3 files changed, 7 insertions(+), 11 deletions(-) diff --git a/sess/R/interactive.R b/sess/R/interactive.R index 38768c627..ccd178c1b 100644 --- a/sess/R/interactive.R +++ b/sess/R/interactive.R @@ -58,7 +58,6 @@ # 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) { - return(invisible(NULL)) # EXPERIMENT: no publish # 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") && diff --git a/src/interactive/backends/arf.ts b/src/interactive/backends/arf.ts index 3ab26528c..79b04f395 100644 --- a/src/interactive/backends/arf.ts +++ b/src/interactive/backends/arf.ts @@ -123,10 +123,7 @@ export class Arf { throw new Error('Missing arf endpoint'); } // Subscribe before submitting anything so that no started event is missed. - // EXPERIMENT: no attach, to isolate a macOS fork failure. - const metadata = object( - await arfRequest(this.endpoint, 'session', {}, 30000, this.abort.signal), - ); + const metadata = await this.connect(); checkArfSession(metadata); this.emit({ type: 'provider', @@ -300,7 +297,11 @@ export class Arf { if (this.failure) { throw this.failure; } - // EXPERIMENT: no attach. + if (!this.attach || this.attach.closed) { + // The previous execution has finished, so attaching again loses no + // state; the session must still be the same arf process. + await this.connect(); + } 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 }; diff --git a/src/test/node/interactiveRuntime.test.ts b/src/test/node/interactiveRuntime.test.ts index 73a0c4cbc..b948c0bf8 100644 --- a/src/test/node/interactiveRuntime.test.ts +++ b/src/test/node/interactiveRuntime.test.ts @@ -1093,14 +1093,10 @@ dt`); for (j in 1:10) cat(strrep(as.character(i), 8192)) i * 2L }, mc.cores = 4) - cat("\nEXPERIMENT values:\n"); print(lapply(values, function(v) list(class = class(v), value = if (inherits(v, "try-error")) conditionMessage(attr(v, "condition")) else v))) - print(warnings()); cat("EXPERIMENT warn option:", getOption("warn"), "\n") stopifnot(identical(unlist(values), c(2L, 4L, 6L, 8L))) cat("parallel complete") `); - const state = (await finished(id)).state; - console.log('EXPERIMENT transcript:', JSON.stringify(text(id).slice(-4000))); - assert.strictEqual(state, 'success'); + assert.strictEqual((await finished(id)).state, 'success'); assert.match(text(id), /parallel complete/); const next = await submit('21 * 2'); assert.strictEqual((await finished(next)).state, 'success'); From fc651857c4e08be1631d6978119dc80bc4b588e8 Mon Sep 17 00:00:00 2001 From: eitsupi Date: Mon, 16 Nov 2026 07:57:05 +0000 Subject: [PATCH 08/19] ci: keep the arf mise config with the Node tests Move mise.toml and mise.lock from the repository root to src/test/node, next to the Interactive runtime tests that use arf, and run mise there in CI. --- .github/actions/prepare-test-runtime/action.yml | 6 +++++- CONTRIBUTING.md | 2 +- src/interactive/README.md | 2 +- mise.lock => src/test/node/mise.lock | 0 mise.toml => src/test/node/mise.toml | 0 5 files changed, 7 insertions(+), 3 deletions(-) rename mise.lock => src/test/node/mise.lock (100%) rename mise.toml => src/test/node/mise.toml (100%) diff --git a/.github/actions/prepare-test-runtime/action.yml b/.github/actions/prepare-test-runtime/action.yml index 821fe45d5..420de66f5 100644 --- a/.github/actions/prepare-test-runtime/action.yml +++ b/.github/actions/prepare-test-runtime/action.yml @@ -37,13 +37,17 @@ runs: - name: Compile test files run: pnpm run clean && pnpm exec tsc shell: bash - # mise.toml and mise.lock pin the arf version and its checksums. + # 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 + working-directory: src/test/node run: | ARF_EXECUTABLE="$(mise which arf)" test -x "${ARF_EXECUTABLE}" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5ea83a5fd..8a6194336 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 arf 0.7.1 or later. `mise install` installs the arf version pinned in `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: +Use Linux or macOS for Interactive runtime tests, with R and arf 0.7.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 diff --git a/src/interactive/README.md b/src/interactive/README.md index fd9862365..516569bf0 100644 --- a/src/interactive/README.md +++ b/src/interactive/README.md @@ -77,7 +77,7 @@ 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 requires arf 0.7.1 or later and is tested with -the version pinned in `mise.toml`. Persistent supervision +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. diff --git a/mise.lock b/src/test/node/mise.lock similarity index 100% rename from mise.lock rename to src/test/node/mise.lock diff --git a/mise.toml b/src/test/node/mise.toml similarity index 100% rename from mise.toml rename to src/test/node/mise.toml From 1fd6b11a99195ad3dea0c847a86176fcc4ae719d Mon Sep 17 00:00:00 2001 From: eitsupi Date: Mon, 16 Nov 2026 07:57:21 +0000 Subject: [PATCH 09/19] ci: test Interactive with arf 0.7.2-rc.1 The release candidate includes the fix that keeps forked R workers from crashing on macOS. The minimum supported version stays 0.7.1 until 0.7.2 is released. --- src/test/node/mise.lock | 26 +++++++++++++------------- src/test/node/mise.toml | 2 +- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/src/test/node/mise.lock b/src/test/node/mise.lock index b2eb53bd7..0ec64bf97 100644 --- a/src/test/node/mise.lock +++ b/src/test/node/mise.lock @@ -1,25 +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.1" +version = "0.7.2-rc.1" backend = "github:eitsupi/arf" [tools."github:eitsupi/arf"."platforms.linux-arm64"] -checksum = "sha256:ac305016f81568a8382ce60e4840ec1e08d10c19784accaf3d20fc60c4be35a2" -url = "https://github.com/eitsupi/arf/releases/download/v0.7.1/arf-console-aarch64-unknown-linux-gnu.tar.xz" -url_api = "https://api.github.com/repos/eitsupi/arf/releases/assets/747777115" +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:05e9f4df17b6def75a6b8356e732c64d70e173ff4dee41d844d50c63b136f211" -url = "https://github.com/eitsupi/arf/releases/download/v0.7.1/arf-console-x86_64-unknown-linux-gnu.tar.xz" -url_api = "https://api.github.com/repos/eitsupi/arf/releases/assets/747777208" +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:c790f1459355c6774589f8a7f058be203519c105f8605c9380d5b94fca6e935a" -url = "https://github.com/eitsupi/arf/releases/download/v0.7.1/arf-console-aarch64-apple-darwin.tar.xz" -url_api = "https://api.github.com/repos/eitsupi/arf/releases/assets/747777120" +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:a2b9cd4b00775674a1d2d2af56e4684268a5042afa6f12b0d02dd9407c498f44" -url = "https://github.com/eitsupi/arf/releases/download/v0.7.1/arf-console-x86_64-apple-darwin.tar.xz" -url_api = "https://api.github.com/repos/eitsupi/arf/releases/assets/747777182" +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 index 40270fe1d..752eb4bef 100644 --- a/src/test/node/mise.toml +++ b/src/test/node/mise.toml @@ -2,7 +2,7 @@ # 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.1", os = ["linux", "macos"] } +"github:eitsupi/arf" = { version = "0.7.2-rc.1", os = ["linux", "macos"] } [settings] lockfile = true From bb209862cc1e734e144d1d4dc410160aceb5fd54 Mon Sep 17 00:00:00 2001 From: eitsupi Date: Mon, 16 Nov 2026 08:37:15 +0000 Subject: [PATCH 10/19] feat(interactive): run inspection as arf handler calls with deadlines Managed arf publishes the sess inspection handlers at startup, and inspection uses arf call with the request timeout as its execution deadline, so a slow inspection is interrupted instead of blocking R. Errors keep their cause: queue timeout, execution deadline, transport timeout, R error, interrupt, or an unpublished handler. Requests go out one at a time over the attach connection; identical read-only ones share a call and a newer hover or completion replaces one that has not started. An adopted arf uses calls only when it publishes every handler; otherwise inspection stays on the sess socket. The inspectionDeadline capability reports which applies. The slow inspection test now hovers a slow active binding and checks that the deadline stops it. --- CONTRIBUTING.md | 2 + src/interactive/README.md | 40 +- src/interactive/agent.ts | 6 +- src/interactive/arf.ts | 7 + src/interactive/arfAttach.ts | 4 +- src/interactive/backend.ts | 43 +- src/interactive/backends/arf.ts | 94 ++++- src/interactive/backends/arfInspection.ts | 357 +++++++++++++++++ src/interactive/backends/sessBackend.ts | 27 +- src/test/node/arfAttach.test.ts | 458 ++++++++++++++++++++++ src/test/node/interactiveBackend.test.ts | 232 +++++++++++ src/test/node/interactiveRuntime.test.ts | 96 +++-- 12 files changed, 1289 insertions(+), 77 deletions(-) create mode 100644 src/interactive/backends/arfInspection.ts diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8a6194336..f8b42307c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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/src/interactive/README.md b/src/interactive/README.md index 516569bf0..374a43c62 100644 --- a/src/interactive/README.md +++ b/src/interactive/README.md @@ -67,6 +67,42 @@ 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)). 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, a newer hover or completion +replaces an older one that has not started, 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 @@ -119,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 38af2921a..c79bcdc68 100644 --- a/src/interactive/arf.ts +++ b/src/interactive/arf.ts @@ -21,6 +21,13 @@ export const MIN_ARF_VERSION = '0.7.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 { diff --git a/src/interactive/arfAttach.ts b/src/interactive/arfAttach.ts index e080eee3e..e05fab441 100644 --- a/src/interactive/arfAttach.ts +++ b/src/interactive/arfAttach.ts @@ -25,6 +25,8 @@ export interface ArfAttachOptions { 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; @@ -106,7 +108,7 @@ export class ArfAttachConnection { } else if (message.id !== undefined) { connection.response(message); } - }); + }, options.maxLineBytes); socket.on('data', (chunk: Buffer) => { try { parser.push(chunk); 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 79b04f395..7ab809f7c 100644 --- a/src/interactive/backends/arf.ts +++ b/src/interactive/backends/arf.ts @@ -6,15 +6,29 @@ import { checkArfSession, } from '../arf'; import { ArfAttachConnection, ArfEvent } from '../arfAttach'; -import { BackendEvent } from '../backend'; -import { object, Submission } from '../protocol'; +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; @@ -28,6 +42,11 @@ export class Arf { 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; @@ -46,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) => [ @@ -70,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) => { @@ -153,22 +176,72 @@ export class Arf { throw new Error(`Interactive bootstrap failed in arf: ${detail}`); } } - private async connect(): Promise> { + /** 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.process.adopted, 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(); } @@ -181,8 +254,7 @@ export class Arf { async interrupt(): Promise { const execution = this.execution; if (!execution) { - // TODO: Interrupt slow inspection through execution deadlines of - // handler calls; sess runs it where arf does not deliver interrupts. + // Inspection is stopped by its execution deadline, not by this request. throw new Error('No submitted code is running'); } execution.interruptRequested = true; @@ -297,11 +369,9 @@ export class Arf { if (this.failure) { throw this.failure; } - if (!this.attach || this.attach.closed) { - // The previous execution has finished, so attaching again loses no - // state; the session must still be the same arf process. - await this.connect(); - } + // 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 }; diff --git a/src/interactive/backends/arfInspection.ts b/src/interactive/backends/arfInspection.ts new file mode 100644 index 000000000..7e69f7caa --- /dev/null +++ b/src/interactive/backends/arfInspection.ts @@ -0,0 +1,357 @@ +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. A + * session started by Interactive publishes the handlers itself. An adopted one + * is trusted only when its handler list is locked and has every selector; + * otherwise inspection stays on the sess socket, where it cannot be interrupted. + */ +export function inspectionCallsAvailable( + adopted: boolean, + api: ArfHandlerApi | undefined, +): boolean { + if (!adopted) { + return true; + } + 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', +]); +/** An editor asks again whenever the cursor moves; only the latest request matters. */ +const SUPERSEDED: ReadonlySet = new Set(['hover', 'completion']); + +interface Job { + request: InspectionRequest; + key?: string; + limits: CallLimits; + 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 newer hover or + * completion replaces an older one that has not started, 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. + * + * 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`. + */ +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 (SUPERSEDED.has(request.method)) { + for (const job of this.waiting.filter((job) => job.request.method === request.method)) { + this.drop(job); + job.resolve(null); + } + } + 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 } 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); + 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/sessBackend.ts b/src/interactive/backends/sessBackend.ts index 01e15bb5e..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( @@ -258,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 }, diff --git a/src/test/node/arfAttach.test.ts b/src/test/node/arfAttach.test.ts index bb0bca127..32d5b4008 100644 --- a/src/test/node/arfAttach.test.ts +++ b/src/test/node/arfAttach.test.ts @@ -10,6 +10,19 @@ import { 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( @@ -52,6 +65,15 @@ function fakeArf( } 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, @@ -248,3 +270,439 @@ suite('arf version requirement', () => { ); }); }); + +/** 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'); + assert.deepStrictEqual(params(requests[0]), { + handler: 'vscode-r.inspect.json/hover', + args: '{"expr":"obj$name"}', + queue_timeout_ms: 1500, + execution_timeout_ms: 1500, + }); + }, + ); + }); + + 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('a newer hover or completion replaces an older one that has not started', 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', 'c'].map((expr) => + inspection.request({ method: 'hover', params: { expr } }), + ); + const completions = ['a', 'b'].map((expr) => + inspection.request({ method: 'completion', params: { expr, trigger: '$' } }), + ); + socket.write( + line({ jsonrpc: '2.0', id: requests[0].id, result: callReply('done') }), + ); + assert.strictEqual(await running, 'done'); + await until(() => requests.length === 2); + socket.write( + line({ jsonrpc: '2.0', id: requests[1].id, result: callReply({ str: 'c' }) }), + ); + assert.deepStrictEqual(await hovers[2], { str: 'c' }); + assert.strictEqual(await hovers[0], null); + assert.strictEqual(await hovers[1], null); + assert.strictEqual(await completions[0], null); + await until(() => requests.length === 3); + socket.write( + line({ + jsonrpc: '2.0', + id: requests[2].id, + result: callReply([{ name: 'b' }]), + }), + ); + assert.deepStrictEqual(await completions[1], [{ name: 'b' }]); + assert.deepStrictEqual( + requests.map((request) => params(request).args), + ['{}', '{"expr":"c"}', '{"expr":"b","trigger":"$"}'], + ); + }, + ); + }); + + 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('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('a managed session always calls; an adopted one only with every selector locked', () => { + assert.ok(inspectionCallsAvailable(false, undefined)); + assert.ok(inspectionCallsAvailable(false, handlers([], 'unexposed'))); + assert.ok(inspectionCallsAvailable(true, handlers([...INSPECTION_SELECTORS, 'demo/add']))); + assert.ok(!inspectionCallsAvailable(true, undefined)); + assert.ok(!inspectionCallsAvailable(true, handlers([], 'unexposed'))); + assert.ok(!inspectionCallsAvailable(true, handlers([...INSPECTION_SELECTORS], 'revoked'))); + assert.ok( + !inspectionCallsAvailable(true, handlers([...INSPECTION_SELECTORS], 'unexposed')), + ); + assert.ok(!inspectionCallsAvailable(true, handlers(INSPECTION_SELECTORS.slice(1)))); + assert.ok( + !inspectionCallsAvailable( + true, + 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 e894ea725..774f82f60 100644 --- a/src/test/node/interactiveBackend.test.ts +++ b/src/test/node/interactiveBackend.test.ts @@ -17,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; @@ -509,3 +511,233 @@ suite('Interactive backend configuration', () => { } }); }); + +(process.platform === 'win32' ? suite.skip : suite)('Interactive inspection routing', function () { + this.timeout(10000); + let root: string; + 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); + }); + }); + const endpoint = path.join(root, `arf-${randomUUID()}.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(); + } + } + }); + + 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 b948c0bf8..68421b18c 100644 --- a/src/test/node/interactiveRuntime.test.ts +++ b/src/test/node/interactiveRuntime.test.ts @@ -419,37 +419,75 @@ sess::display("display-${cell}", "text/plain"); cat("stderr-${cell}\\n", file=st assert.match(text(next), /23/); }); - test('interrupts a slow inspection and continues serving R requests', async () => { - for (const afterTimeout of [false, true]) { - const marker = `inspection-started-${String(afterTimeout)}`; - const inspection = client - .request('inspect', { - method: 'hover', - params: { - expr: `local({ cat("${marker}"); Sys.sleep(30); 42 })`, - }, - }) - .then( - () => '', - (error: Error) => error.message, - ); - await until(() => - events.some( - (event) => event.type === 'stream' && String(event.data.text).includes(marker), - ), + 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, + ); + 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 () => { From 50dc0d0d352176e883325e17815ce458c6ad8b27 Mon Sep 17 00:00:00 2001 From: eitsupi Date: Mon, 16 Nov 2026 08:37:24 +0000 Subject: [PATCH 11/19] feat(sess): publish inspection as arf handlers Add a fixed table of the ten Interactive inspection methods that arf can publish with --ipc-expose under the vscode-r.inspect.json namespace. Each handler takes the request parameters as one JSON string, validates them in R, and returns the result as one JSON string encoded like a socket reply, so the call's execution deadline covers decoding, the handler and encoding. Hover and completion resolve names and $/@ chains without evaluating the request. The per-method logic is shared with the socket handler table, whose behavior is unchanged. The published functions look up the private sess only when called, because arf evaluates the expression before the bootstrap loads it. --- sess/R/dispatch.R | 11 +- sess/R/inspection_call.R | 286 +++++++++++++++++ sess/R/server.R | 27 +- sess/inst/arf/expose-inspection.R | 65 ++++ sess/inst/tinytest/test-inspection-call.R | 375 ++++++++++++++++++++++ 5 files changed, 747 insertions(+), 17 deletions(-) create mode 100644 sess/R/inspection_call.R create mode 100644 sess/inst/arf/expose-inspection.R create mode 100644 sess/inst/tinytest/test-inspection-call.R 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..b47f60b8d --- /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()`. Only `hover` and +# `completion` differ: the socket path still evaluates the request text, while +# a handler call resolves it with `inspection_hover()` and +# `inspection_completion()`, which never evaluate it. 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/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)))) +}) From 55cd7711e6fa6089c866e2a8af30c61848622d7e Mon Sep 17 00:00:00 2001 From: eitsupi Date: Mon, 16 Nov 2026 08:45:31 +0000 Subject: [PATCH 12/19] docs(sess): describe socket hover after the resolver change The socket path no longer evaluates hover and completion requests; it differs from handler calls only in turning errors into no result. --- sess/R/inspection_call.R | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/sess/R/inspection_call.R b/sess/R/inspection_call.R index b47f60b8d..e15ce1ecc 100644 --- a/sess/R/inspection_call.R +++ b/sess/R/inspection_call.R @@ -7,12 +7,12 @@ # - 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()`. Only `hover` and -# `completion` differ: the socket path still evaluates the request text, while -# a handler call resolves it with `inspection_hover()` and -# `inspection_completion()`, which never evaluate it. Handlers published to arf -# run outside arf's evaluation policy and approval, so they must not accept -# code from the client. +# 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 From 1a1be3934fb63cfd7ea562ef0645400927bb02be Mon Sep 17 00:00:00 2001 From: eitsupi Date: Mon, 16 Nov 2026 09:02:45 +0000 Subject: [PATCH 13/19] test(interactive): keep fake arf socket paths short on macOS macOS limits Unix socket paths to 104 bytes, and a UUID file name under its long temporary directory exceeded that, so the inspection routing tests could not listen. --- src/test/node/interactiveBackend.test.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/test/node/interactiveBackend.test.ts b/src/test/node/interactiveBackend.test.ts index 774f82f60..89745b53f 100644 --- a/src/test/node/interactiveBackend.test.ts +++ b/src/test/node/interactiveBackend.test.ts @@ -515,6 +515,7 @@ suite('Interactive backend configuration', () => { (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-')); }); @@ -596,7 +597,9 @@ suite('Interactive backend configuration', () => { socket.on('data', read); }); }); - const endpoint = path.join(root, `arf-${randomUUID()}.sock`); + // 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, From 2ec74efa498f90bb6be4b0642f5119b3e6fc1252 Mon Sep 17 00:00:00 2001 From: eitsupi Date: Mon, 16 Nov 2026 09:15:17 +0000 Subject: [PATCH 14/19] fix(interactive): do not drop waiting hover and completion requests Inspection requests reach the agent from every client, so a newer hover or completion is not necessarily a replacement for an older one. Replacing them by method answered another client's request with no result. Keep sharing calls only between identical requests. --- src/interactive/README.md | 5 ++- src/interactive/backends/arfInspection.ts | 16 +++------- src/test/node/arfAttach.test.ts | 37 +++++++++-------------- 3 files changed, 20 insertions(+), 38 deletions(-) diff --git a/src/interactive/README.md b/src/interactive/README.md index 374a43c62..c62159982 100644 --- a/src/interactive/README.md +++ b/src/interactive/README.md @@ -92,9 +92,8 @@ cause: queue timeout (R was busy and the request never ran), execution deadline 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, a newer hover or completion -replaces an older one that has not started, and the number of waiting requests -is bounded, so the arf call queue shared by all clients does not fill. +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 diff --git a/src/interactive/backends/arfInspection.ts b/src/interactive/backends/arfInspection.ts index 7e69f7caa..76be5c599 100644 --- a/src/interactive/backends/arfInspection.ts +++ b/src/interactive/backends/arfInspection.ts @@ -209,8 +209,6 @@ const COALESCED: ReadonlySet = new Set([ 'completion', 'dataview_page', ]); -/** An editor asks again whenever the cursor moves; only the latest request matters. */ -const SUPERSEDED: ReadonlySet = new Set(['hover', 'completion']); interface Job { request: InspectionRequest; @@ -233,10 +231,10 @@ export type CallTransport = ( * * 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 newer hover or - * completion replaces an older one that has not started, 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. + * 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 @@ -267,12 +265,6 @@ export class InspectionCalls { } } } - if (SUPERSEDED.has(request.method)) { - for (const job of this.waiting.filter((job) => job.request.method === request.method)) { - this.drop(job); - job.resolve(null); - } - } if (this.waiting.length >= MAX_PENDING) { return Promise.reject( new InspectionError('overloaded', 'Too many R inspection requests are waiting'), diff --git a/src/test/node/arfAttach.test.ts b/src/test/node/arfAttach.test.ts index 32d5b4008..f1d7be230 100644 --- a/src/test/node/arfAttach.test.ts +++ b/src/test/node/arfAttach.test.ts @@ -538,7 +538,7 @@ suite('arf inspection calls', () => { ); }); - test('a newer hover or completion replaces an older one that has not started', async () => { + test('distinct waiting hovers are each answered, as they can come from different clients', async () => { let socket!: net.Socket; await withInspection( (_message, connection) => { @@ -547,36 +547,27 @@ suite('arf inspection calls', () => { async (inspection, requests) => { const running = inspection.request({ method: 'workspace', params: {} }); await until(() => requests.length === 1); - const hovers = ['a', 'b', 'c'].map((expr) => + const hovers = ['a', 'b'].map((expr) => inspection.request({ method: 'hover', params: { expr } }), ); - const completions = ['a', 'b'].map((expr) => - inspection.request({ method: 'completion', params: { expr, trigger: '$' } }), - ); socket.write( line({ jsonrpc: '2.0', id: requests[0].id, result: callReply('done') }), ); assert.strictEqual(await running, 'done'); - await until(() => requests.length === 2); - socket.write( - line({ jsonrpc: '2.0', id: requests[1].id, result: callReply({ str: 'c' }) }), - ); - assert.deepStrictEqual(await hovers[2], { str: 'c' }); - assert.strictEqual(await hovers[0], null); - assert.strictEqual(await hovers[1], null); - assert.strictEqual(await completions[0], null); - await until(() => requests.length === 3); - socket.write( - line({ - jsonrpc: '2.0', - id: requests[2].id, - result: callReply([{ name: 'b' }]), - }), - ); - assert.deepStrictEqual(await completions[1], [{ name: 'b' }]); + 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":"c"}', '{"expr":"b","trigger":"$"}'], + ['{}', '{"expr":"a"}', '{"expr":"b"}'], ); }, ); From 9554b2055677f13e417c0c4a0510265401c4bc3b Mon Sep 17 00:00:00 2001 From: eitsupi Date: Mon, 16 Nov 2026 09:15:28 +0000 Subject: [PATCH 15/19] docs(interactive): explain requests sent after an inspection transport timeout --- src/interactive/backends/arfInspection.ts | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/interactive/backends/arfInspection.ts b/src/interactive/backends/arfInspection.ts index 76be5c599..06fb68871 100644 --- a/src/interactive/backends/arfInspection.ts +++ b/src/interactive/backends/arfInspection.ts @@ -239,6 +239,13 @@ export type CallTransport = ( * 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[] = []; From d68667d1d988610cb73524922f40d6fa9fc321cc Mon Sep 17 00:00:00 2001 From: eitsupi Date: Mon, 16 Nov 2026 09:16:49 +0000 Subject: [PATCH 16/19] fix(interactive): check that managed arf publishes every inspection handler A managed session used handler calls without checking what arf reported, so a mismatch between the selectors in TypeScript and the table installed with sess would only show up as failing inspections. Check the handler list for managed sessions as for adopted ones, and fail startup when it is incomplete. --- src/interactive/README.md | 3 ++- src/interactive/backends/arf.ts | 6 ++++- src/interactive/backends/arfInspection.ts | 16 ++++-------- src/test/node/arfAttach.test.ts | 19 +++++--------- src/test/node/interactiveBackend.test.ts | 32 +++++++++++++++++++++++ 5 files changed, 51 insertions(+), 25 deletions(-) diff --git a/src/interactive/README.md b/src/interactive/README.md index c62159982..8d7f171b0 100644 --- a/src/interactive/README.md +++ b/src/interactive/README.md @@ -74,7 +74,8 @@ 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)). arf evaluates +([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 diff --git a/src/interactive/backends/arf.ts b/src/interactive/backends/arf.ts index 7ab809f7c..bfc3fcda3 100644 --- a/src/interactive/backends/arf.ts +++ b/src/interactive/backends/arf.ts @@ -148,6 +148,10 @@ export class Arf { // 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: { @@ -214,7 +218,7 @@ export class Arf { * deadline, rather than the sess socket, which cannot be interrupted. */ callsInspection(): boolean { - return inspectionCallsAvailable(this.process.adopted, this.handlerApi); + return inspectionCallsAvailable(this.handlerApi); } /** Runs an inspection as a handler call with the request's execution deadline. */ inspect(request: InspectionRequest): Promise { diff --git a/src/interactive/backends/arfInspection.ts b/src/interactive/backends/arfInspection.ts index 06fb68871..03e9e595a 100644 --- a/src/interactive/backends/arfInspection.ts +++ b/src/interactive/backends/arfInspection.ts @@ -57,18 +57,12 @@ export function parseHandlerApi(session: Record): ArfHandlerApi } /** - * Whether inspection can use handler calls and their execution deadlines. A - * session started by Interactive publishes the handlers itself. An adopted one - * is trusted only when its handler list is locked and has every selector; - * otherwise inspection stays on the sess socket, where it cannot be interrupted. + * 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( - adopted: boolean, - api: ArfHandlerApi | undefined, -): boolean { - if (!adopted) { - return true; - } +export function inspectionCallsAvailable(api: ArfHandlerApi | undefined): boolean { return ( api?.state === 'locked' && INSPECTION_SELECTORS.every((selector) => api.handlers.includes(selector)) diff --git a/src/test/node/arfAttach.test.ts b/src/test/node/arfAttach.test.ts index f1d7be230..a57bae98e 100644 --- a/src/test/node/arfAttach.test.ts +++ b/src/test/node/arfAttach.test.ts @@ -652,20 +652,15 @@ suite('arf inspection handlers', () => { } }); - test('a managed session always calls; an adopted one only with every selector locked', () => { - assert.ok(inspectionCallsAvailable(false, undefined)); - assert.ok(inspectionCallsAvailable(false, handlers([], 'unexposed'))); - assert.ok(inspectionCallsAvailable(true, handlers([...INSPECTION_SELECTORS, 'demo/add']))); - assert.ok(!inspectionCallsAvailable(true, undefined)); - assert.ok(!inspectionCallsAvailable(true, handlers([], 'unexposed'))); - assert.ok(!inspectionCallsAvailable(true, handlers([...INSPECTION_SELECTORS], 'revoked'))); - assert.ok( - !inspectionCallsAvailable(true, handlers([...INSPECTION_SELECTORS], 'unexposed')), - ); - assert.ok(!inspectionCallsAvailable(true, handlers(INSPECTION_SELECTORS.slice(1)))); + 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( - true, handlers(INSPECTION_SELECTORS.map((name) => name.replace('.json', '.other'))), ), ); diff --git a/src/test/node/interactiveBackend.test.ts b/src/test/node/interactiveBackend.test.ts index 89745b53f..6b8ef2682 100644 --- a/src/test/node/interactiveBackend.test.ts +++ b/src/test/node/interactiveBackend.test.ts @@ -678,6 +678,38 @@ suite('Interactive backend configuration', () => { } }); + 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( { From c8d11dacddcab6b5e35953e19c4dd062c15f32fd Mon Sep 17 00:00:00 2001 From: eitsupi Date: Mon, 16 Nov 2026 09:17:46 +0000 Subject: [PATCH 17/19] feat(interactive): require arf 0.7.2-rc.1 The release candidate fixes forked R workers crashing on macOS and the status of an R error after a caught interrupt. Compare prerelease versions with SemVer precedence so that a prerelease minimum rejects earlier prereleases. --- CONTRIBUTING.md | 2 +- src/interactive/README.md | 2 +- src/interactive/arf.ts | 46 +++++++++++++++++++----- src/test/node/arfAttach.test.ts | 24 ++++++++++--- src/test/node/interactiveBackend.test.ts | 2 +- website/docs/features/r-interactive.md | 2 +- 6 files changed, 61 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f8b42307c..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 arf 0.7.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: +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 diff --git a/src/interactive/README.md b/src/interactive/README.md index 8d7f171b0..6b953f187 100644 --- a/src/interactive/README.md +++ b/src/interactive/README.md @@ -112,7 +112,7 @@ 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 requires arf 0.7.1 or later and is tested with +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. diff --git a/src/interactive/arf.ts b/src/interactive/arf.ts index c79bcdc68..97663cb5e 100644 --- a/src/interactive/arf.ts +++ b/src/interactive/arf.ts @@ -13,10 +13,11 @@ export interface ArfSession { session_type?: string; } -// TODO: Require arf 0.7.2 once it is released. It reports an R error that -// follows a caught interrupt as an error rather than as interrupted, and bounds -// console reads that cannot be answered. -export const MIN_ARF_VERSION = '0.7.1'; +// 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; @@ -63,12 +64,22 @@ export function rpcError(error: unknown): ArfRpcError { ); } -/** Compares release versions; prereleases count as older than their release. */ +/** + * 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.-]+)?$/.exec(text); + 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] } + ? { + core: [Number(match[1]), Number(match[2]), Number(match[3])], + pre: match[4]?.split('.') ?? [], + } : undefined; }; const actual = typeof version === 'string' ? parse(version) : undefined; @@ -81,7 +92,26 @@ export function arfVersionAtLeast(version: unknown, minimum: string): boolean { return actual.core[i] > required.core[i]; } } - return !actual.pre || required.pre; + // 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. */ diff --git a/src/test/node/arfAttach.test.ts b/src/test/node/arfAttach.test.ts index a57bae98e..31c3f4431 100644 --- a/src/test/node/arfAttach.test.ts +++ b/src/test/node/arfAttach.test.ts @@ -243,7 +243,7 @@ suite('arf attach connection', () => { }); suite('arf version requirement', () => { - test('compares release versions and treats prereleases as older', () => { + test('compares versions with SemVer precedence', () => { assert.ok(arfVersionAtLeast('0.7.1', '0.7.1')); assert.ok(arfVersionAtLeast('0.7.2', '0.7.1')); assert.ok(arfVersionAtLeast('0.10.0', '0.7.1')); @@ -255,17 +255,31 @@ suite('arf version requirement', () => { assert.ok(!arfVersionAtLeast(undefined, '0.7.1')); assert.ok(!arfVersionAtLeast('0.7', '0.7.1')); assert.ok(!arfVersionAtLeast('latest', '0.7.1')); + // Prerelease minimums. + assert.ok(arfVersionAtLeast('0.7.2-rc.1', '0.7.2-rc.1')); + assert.ok(arfVersionAtLeast('0.7.2-rc.1+build.5', '0.7.2-rc.1')); + assert.ok(arfVersionAtLeast('0.7.2-rc.2', '0.7.2-rc.1')); + assert.ok(arfVersionAtLeast('0.7.2-rc.10', '0.7.2-rc.2')); + assert.ok(arfVersionAtLeast('0.7.2-rc.1.1', '0.7.2-rc.1')); + assert.ok(arfVersionAtLeast('0.7.2-rc.a', '0.7.2-rc.1')); + assert.ok(arfVersionAtLeast('0.7.2', '0.7.2-rc.1')); + assert.ok(arfVersionAtLeast('0.7.3-alpha', '0.7.2-rc.1')); + assert.ok(!arfVersionAtLeast('0.7.2-rc.0', '0.7.2-rc.1')); + assert.ok(!arfVersionAtLeast('0.7.2-beta.9', '0.7.2-rc.1')); + assert.ok(!arfVersionAtLeast('0.7.2-rc', '0.7.2-rc.1')); + assert.ok(!arfVersionAtLeast('0.7.1', '0.7.2-rc.1')); }); test('rejects old sessions and sessions without handler call deadlines', () => { - checkArfSession({ arf_version: '0.7.1', capabilities: ['call_execution_timeout'] }); + checkArfSession({ arf_version: '0.7.2-rc.1', capabilities: ['call_execution_timeout'] }); assert.throws( - () => checkArfSession({ arf_version: '0.5.3', capabilities: [] }), - /requires arf 0\.7\.1 or later, but the session runs 0\.5\.3/, + () => + 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.1', capabilities: [] }), + () => checkArfSession({ arf_version: '0.7.2-rc.1', capabilities: [] }), /execution deadlines/, ); }); diff --git a/src/test/node/interactiveBackend.test.ts b/src/test/node/interactiveBackend.test.ts index 6b8ef2682..8c7551b0f 100644 --- a/src/test/node/interactiveBackend.test.ts +++ b/src/test/node/interactiveBackend.test.ts @@ -470,7 +470,7 @@ suite('Interactive backend configuration', () => { capabilities: ['events', 'call_execution_timeout'], session_id: 'fake', session: { - arf_version: '0.7.1', + arf_version: '0.7.2-rc.1', capabilities: ['call_execution_timeout'], }, }, 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: From 7e876b3984924576d8ad34a511f5ec313c6d61c9 Mon Sep 17 00:00:00 2001 From: eitsupi Date: Mon, 16 Nov 2026 09:23:08 +0000 Subject: [PATCH 18/19] test(interactive): keep representative arf version comparisons --- src/test/node/arfAttach.test.ts | 21 ++------------------- 1 file changed, 2 insertions(+), 19 deletions(-) diff --git a/src/test/node/arfAttach.test.ts b/src/test/node/arfAttach.test.ts index 31c3f4431..eb8fd5e56 100644 --- a/src/test/node/arfAttach.test.ts +++ b/src/test/node/arfAttach.test.ts @@ -244,30 +244,13 @@ suite('arf attach connection', () => { suite('arf version requirement', () => { test('compares versions with SemVer precedence', () => { - assert.ok(arfVersionAtLeast('0.7.1', '0.7.1')); - assert.ok(arfVersionAtLeast('0.7.2', '0.7.1')); - assert.ok(arfVersionAtLeast('0.10.0', '0.7.1')); - assert.ok(arfVersionAtLeast('1.0.0', '0.7.1')); - assert.ok(arfVersionAtLeast('0.7.2-beta.1', '0.7.1')); - assert.ok(!arfVersionAtLeast('0.7.1-beta.1', '0.7.1')); - assert.ok(!arfVersionAtLeast('0.7.0', '0.7.1')); - assert.ok(!arfVersionAtLeast('0.5.3', '0.7.1')); - assert.ok(!arfVersionAtLeast(undefined, '0.7.1')); - assert.ok(!arfVersionAtLeast('0.7', '0.7.1')); - assert.ok(!arfVersionAtLeast('latest', '0.7.1')); - // Prerelease minimums. assert.ok(arfVersionAtLeast('0.7.2-rc.1', '0.7.2-rc.1')); - assert.ok(arfVersionAtLeast('0.7.2-rc.1+build.5', '0.7.2-rc.1')); - assert.ok(arfVersionAtLeast('0.7.2-rc.2', '0.7.2-rc.1')); assert.ok(arfVersionAtLeast('0.7.2-rc.10', '0.7.2-rc.2')); - assert.ok(arfVersionAtLeast('0.7.2-rc.1.1', '0.7.2-rc.1')); - assert.ok(arfVersionAtLeast('0.7.2-rc.a', '0.7.2-rc.1')); assert.ok(arfVersionAtLeast('0.7.2', '0.7.2-rc.1')); - assert.ok(arfVersionAtLeast('0.7.3-alpha', '0.7.2-rc.1')); - assert.ok(!arfVersionAtLeast('0.7.2-rc.0', '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.2-rc', '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', () => { From e085dc7bff331643c325e6be1f1e8d3a27a899c4 Mon Sep 17 00:00:00 2001 From: eitsupi Date: Mon, 16 Nov 2026 09:45:45 +0000 Subject: [PATCH 19/19] fix(interactive): count local waiting towards the inspection start limit A request that waited behind earlier inspection requests was still given its full timeout as the arf queue limit, so it could wait almost twice as long as documented before starting. Send arf only what is left of the wait. --- src/interactive/backends/arfInspection.ts | 22 ++++++++++++++- src/test/node/arfAttach.test.ts | 34 +++++++++++++++++++++-- 2 files changed, 53 insertions(+), 3 deletions(-) diff --git a/src/interactive/backends/arfInspection.ts b/src/interactive/backends/arfInspection.ts index 03e9e595a..9ad446c59 100644 --- a/src/interactive/backends/arfInspection.ts +++ b/src/interactive/backends/arfInspection.ts @@ -208,6 +208,8 @@ 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; @@ -276,7 +278,7 @@ export class InspectionCalls { execution: timeout, transport: 2 * timeout + TRANSPORT_MARGIN, }; - const job = { request, key, limits } as Job; + const job = { request, key, limits, startBy: Date.now() + timeout } as Job; job.promise = new Promise((resolve, reject) => { job.resolve = resolve; job.reject = reject; @@ -321,6 +323,24 @@ export class InspectionCalls { 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() diff --git a/src/test/node/arfAttach.test.ts b/src/test/node/arfAttach.test.ts index eb8fd5e56..a370f292e 100644 --- a/src/test/node/arfAttach.test.ts +++ b/src/test/node/arfAttach.test.ts @@ -341,12 +341,14 @@ suite('arf inspection calls', () => { assert.deepStrictEqual(result, { str: 'x' }); assert.strictEqual(requests.length, 1); assert.strictEqual(requests[0].method, 'call'); - assert.deepStrictEqual(params(requests[0]), { + const { queue_timeout_ms: queue, ...sent } = params(requests[0]); + assert.deepStrictEqual(sent, { handler: 'vscode-r.inspect.json/hover', args: '{"expr":"obj$name"}', - queue_timeout_ms: 1500, 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)); }, ); }); @@ -600,6 +602,34 @@ suite('arf inspection calls', () => { ); }); + 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,