This document describes LSP extensions used by rust-analyzer.
It's a best effort document, when in doubt, consult the source (and send a PR with clarification ;-) ).
We aim to upstream all non Rust-specific extensions to the protocol, but this is not a top priority.
All capabilities are enabled via the experimental field of ClientCapabilities or ServerCapabilities.
Requests which we hope to upstream live under experimental/ namespace.
Requests, which are likely to always remain specific to rust-analyzer are under rust-analyzer/ namespace.
If you want to be notified about the changes to this document, subscribe to #4604.
Upstream Issue: microsoft/language-server-protocol#567
The initializationOptions field of the InitializeParams of the initialization request should contain the "rust-analyzer" section of the configuration.
rust-analyzer normally sends a "workspace/configuration" request with { "items": ["rust-analyzer"] } payload.
However, the server can't do this during initialization.
At the same time some essential configuration parameters are needed early on, before servicing requests.
For this reason, we ask that initializationOptions contains the configuration, as if the server did make a "workspace/configuration" request.
If a language client does not know about rust-analyzer's configuration options it can get sensible defaults by doing any of the following:
- Not sending
initializationOptions - Sending
"initializationOptions": null - Sending
"initializationOptions": {}
Upstream Issue: microsoft/language-server-protocol#724
Experimental Client Capability: { "snippetTextEdit": boolean }
If this capability is set, WorkspaceEdits returned from codeAction requests and TextEdits returned from textDocument/onTypeFormatting requests might contain SnippetTextEdits instead of usual TextEdits:
interface SnippetTextEdit extends TextEdit {
insertTextFormat?: InsertTextFormat;
annotationId?: ChangeAnnotationIdentifier;
}export interface TextDocumentEdit {
textDocument: OptionalVersionedTextDocumentIdentifier;
edits: (TextEdit | SnippetTextEdit)[];
}When applying such code action or text edit, the editor should insert snippet, with tab stops and placeholders.
At the moment, rust-analyzer guarantees that only a single TextDocumentEdit will have edits which can be InsertTextFormat.Snippet.
Any additional TextDocumentEdits will only have edits which are InsertTextFormat.PlainText.
"Add derive" code action transforms struct S; into #[derive($0)] struct S;
- Where exactly are
SnippetTextEdits allowed (only in code actions at the moment)? - Can snippets span multiple files (so far, no)?
Upstream Issue: microsoft/language-server-protocol#994
Experimental Client Capability: { "codeActionGroup": boolean }
If this capability is set, CodeActions returned from the server contain an additional field, group:
interface CodeAction {
title: string;
group?: string;
...
}All code-actions with the same group should be grouped under single (extendable) entry in lightbulb menu.
The set of actions [ { title: "foo" }, { group: "frobnicate", title: "bar" }, { group: "frobnicate", title: "baz" }] should be rendered as
💡
+-------------+
| foo |
+-------------+-----+
| frobnicate >| bar |
+-------------+-----+
| baz |
+-----+
Alternatively, selecting frobnicate could present a user with an additional menu to choose between bar and baz.
fn main() {
let x: Entry/*cursor here*/ = todo!();
}Invoking code action at this position will yield two code actions for importing Entry from either collections::HashMap or collection::BTreeMap, grouped under a single "import" group.
- Is a fixed two-level structure enough?
- Should we devise a general way to encode custom interaction protocols for GUI refactorings?
Upstream Issue: microsoft/language-server-protocol#1002
Experimental Server Capability: { "parentModule": boolean }
This request is sent from client to server to handle "Goto Parent Module" editor action.
Method: experimental/parentModule
Request: TextDocumentPositionParams
Response: Location | Location[] | LocationLink[] | null
// src/main.rs
mod foo;
// src/foo.rs
/* cursor here*/experimental/parentModule returns a single Link to the mod foo; declaration.
- An alternative would be to use a more general "gotoSuper" request, which would work for super methods, super classes and super modules. This is the approach IntelliJ Rust is taking. However, experience shows that super module (which generally has a feeling of navigation between files) should be separate. If you want super module, but the cursor happens to be inside an overridden function, the behavior with single "gotoSuper" request is surprising.
Upstream Issue: microsoft/language-server-protocol#992
Experimental Server Capability: { "joinLines": boolean }
This request is sent from client to server to handle "Join Lines" editor action.
Method: experimental/joinLines
Request:
interface JoinLinesParams {
textDocument: TextDocumentIdentifier,
/// Currently active selections/cursor offsets.
/// This is an array to support multiple cursors.
ranges: Range[],
}Response: TextEdit[]
fn main() {
/*cursor here*/let x = {
92
};
}experimental/joinLines yields (curly braces are automagically removed)
fn main() {
let x = 92;
}- What is the position of the cursor after
joinLines? Currently, this is left to editor's discretion, but it might be useful to specify on the server via snippets. However, it then becomes unclear how it works with multi cursor.
Upstream Issue: microsoft/language-server-protocol#1001
Experimental Server Capability: { "onEnter": boolean }
This request is sent from client to server to handle the Enter key press.
Method: experimental/onEnter
Request:: TextDocumentPositionParams
Response:
SnippetTextEdit[]fn main() {
// Some /*cursor here*/ docs
let x = 92;
}experimental/onEnter returns the following snippet
fn main() {
// Some
// $0 docs
let x = 92;
}The primary goal of onEnter is to handle automatic indentation when opening a new line.
This is not yet implemented.
The secondary goal is to handle fixing up syntax, like continuing doc strings and comments, and escaping \n in string literals.
As proper cursor positioning is raison d'être for onEnter, it uses SnippetTextEdit.
- How to deal with synchronicity of the request? One option is to require the client to block until the server returns the response. Another option is to do a operational transforms style merging of edits from client and server. A third option is to do a record-replay: client applies heuristic on enter immediately, then applies all user's keypresses. When the server is ready with the response, the client rollbacks all the changes and applies the recorded actions on top of the correct response.
- How to deal with multiple carets?
- Should we extend this to arbitrary typed events and not just
onEnter?
Experimental Server Capability: { "ssr": boolean }
This request is sent from client to server to handle structural search replace -- automated syntax tree based transformation of the source.
Method: experimental/ssr
Request:
interface SsrParams {
/// Search query.
/// The specific syntax is specified outside of the protocol.
query: string,
/// If true, only check the syntax of the query and don't compute the actual edit.
parseOnly: boolean,
/// The current text document. This and `position` will be used to determine in what scope
/// paths in `query` should be resolved.
textDocument: TextDocumentIdentifier;
/// Position where SSR was invoked.
position: Position;
/// Current selections. Search/replace will be restricted to these if non-empty.
selections: Range[];
}Response:
WorkspaceEditSSR with query foo($a, $b) ==>> ($a).foo($b) will transform, eg foo(y + 5, z) into (y + 5).foo(z).
- Probably needs search without replace mode
- Needs a way to limit the scope to certain files.
Upstream Issue: microsoft/language-server-protocol#999
Experimental Server Capability: { "matchingBrace": boolean }
This request is sent from client to server to handle "Matching Brace" editor action.
Method: experimental/matchingBrace
Request:
interface MatchingBraceParams {
textDocument: TextDocumentIdentifier,
/// Position for each cursor
positions: Position[],
}Response:
Position[]fn main() {
let x: Vec<()>/*cursor here*/ = vec![];
}experimental/matchingBrace yields the position of <.
In many cases, matching braces can be handled by the editor.
However, some cases (like disambiguating between generics and comparison operations) need a real parser.
Moreover, it would be cool if editors didn't need to implement even basic language parsing
- Should we return a nested brace structure, to allow paredit-like actions of jump out of the current brace pair?
This is how
SelectionRangerequest works. - Alternatively, should we perhaps flag certain
SelectionRanges as being brace pairs?
Upstream Issue: microsoft/language-server-protocol#944
Experimental Server Capability: { "runnables": { "kinds": string[] } }
This request is sent from client to server to get the list of things that can be run (tests, binaries, cargo check -p).
Method: experimental/runnables
Request:
interface RunnablesParams {
textDocument: TextDocumentIdentifier;
/// If null, compute runnables for the whole file.
position?: Position;
}Response: Runnable[]
interface Runnable {
label: string;
/// If this Runnable is associated with a specific function/module, etc., the location of this item
location?: LocationLink;
/// Running things is necessary technology specific, `kind` needs to be advertised via server capabilities,
// the type of `args` is specific to `kind`. The actual running is handled by the client.
kind: string;
args: any;
}rust-analyzer supports only one kind, "cargo". The args for "cargo" look like this:
{
workspaceRoot?: string;
cargoArgs: string[];
cargoExtraArgs: string[];
executableArgs: string[];
expectTest?: boolean;
overrideCargo?: string;
}Experimental Client Capability: { "testExplorer": boolean }
If this capability is set, the experimental/discoveredTests notification will be sent from the
server to the client.
Method: experimental/discoverTest
Request: DiscoverTestParams
interface DiscoverTestParams {
// The test that we need to resolve its children. If not present,
// the response should return top level tests.
testId?: string | undefined;
}Response: DiscoverTestResults
interface TestItem {
// A unique identifier for the test
id: string;
// The file containing this test
textDocument?: lc.TextDocumentIdentifier | undefined;
// The range in the file containing this test
range?: lc.Range | undefined;
// A human readable name for this test
label: string;
// The kind of this test item. Based on the kind,
// an icon is chosen by the editor.
kind: "package" | "module" | "test";
// True if this test may have children not available eagerly
canResolveChildren: boolean;
// The id of the parent test in the test tree. If not present, this test
// is a top level test.
parent?: string | undefined;
// The information useful for running the test. The client can use `runTest`
// request for simple execution, but for more complex execution forms
// like debugging, this field is useful.
// Note that this field includes some information about label and location as well, but
// those exist just for keeping things in sync with other methods of running runnables
// (for example using one consistent name in the vscode's launch.json) so for any propose
// other than running tests this field should not be used.
runnable?: Runnable | undefined;
};
interface DiscoverTestResults {
// The discovered tests.
tests: TestItem[];
// For each test which its id is in this list, the response
// contains all tests that are children of this test, and
// client should remove old tests not included in the response.
scope: string[] | undefined;
// For each file which its uri is in this list, the response
// contains all tests that are located in this file, and
// client should remove old tests not included in the response.
scopeFile: lc.TextDocumentIdentifier[] | undefined;
}Method: experimental/discoveredTests
Notification: DiscoverTestResults
This notification is sent from the server to the client when the
server detect changes in the existing tests. The DiscoverTestResults is
the same as the one in experimental/discoverTest response.
Method: experimental/runTest
Request: RunTestParams
interface RunTestParams {
// Id of the tests to be run. If a test is included, all of its children are included implicitly. If
// this property is undefined, then the server should simply run all tests.
include?: string[] | undefined;
// An array of test ids the user has marked as excluded from the test included in this run; exclusions
// should apply after inclusions.
// May be omitted if no exclusions were requested. Server should not run excluded tests or
// any children of excluded tests.
exclude?: string[] | undefined;
}Response: void
Method: experimental/endRunTest
Notification:
This notification is sent from the server to the client when the current running session is finished. The server should not send any run notification after this.
Method: experimental/abortRunTest
Notification:
This notification is sent from the client to the server when the user is no longer
interested in the test results. The server should clean up its resources and send
a experimental/endRunTest when is done.
Method: experimental/changeTestState
Notification: ChangeTestStateParams
type TestState = { tag: "passed" }
| {
tag: "failed";
// The standard error of the test, containing the panic message. Clients should
// render it similar to a terminal, and e.g. handle ansi colors.
message: string;
}
| { tag: "started" }
| { tag: "enqueued" }
| { tag: "skipped" };
interface ChangeTestStateParams {
testId: string;
state: TestState;
}Method: experimental/appendOutputToRunTest
Notification: string
This notification is used for reporting messages independent of any single test and related to the run session in general, e.g. cargo compiling progress messages or warnings.
This request is sent from the client to the server to obtain web and local URL(s) for documentation related to the symbol under the cursor, if available.
Method: experimental/externalDocs
Request: TextDocumentPositionParams
Response: string | null
Experimental Client Capability: { "localDocs": boolean }
If this capability is set, the Open External Documentation request returned from the server will have the following structure:
interface ExternalDocsResponse {
web?: string;
local?: string;
}Method: rust-analyzer/analyzerStatus
Request:
interface AnalyzerStatusParams {
/// If specified, show dependencies of the current file.
textDocument?: TextDocumentIdentifier;
}Response: string
Returns internal status message, mostly for debugging purposes.
Method: rust-analyzer/reloadWorkspace
Request: null
Response: null
Reloads project information (that is, re-executes cargo metadata).
Method: rust-analyzer/rebuildProcMacros
Request: null
Response: null
Rebuilds build scripts and proc-macros, and runs the build scripts to reseed the build data.
Experimental Client Capability: { "unindexedProject": boolean }
Method: rust-analyzer/unindexedProject
Notification:
interface UnindexedProjectParams {
/// A list of documents that rust-analyzer has determined are not indexed.
textDocuments: lc.TextDocumentIdentifier[]
}This notification is sent from the server to the client. The client is expected
to determine the appropriate owners of textDocuments and update linkedProjects
if an owner can be determined successfully.
Experimental Client Capability: { "serverStatusNotification": boolean }
Method: experimental/serverStatus
Notification:
interface ServerStatusParams {
/// `ok` means that the server is completely functional.
///
/// `warning` means that the server is partially functional.
/// It can answer correctly to most requests, but some results
/// might be wrong due to, for example, some missing dependencies.
///
/// `error` means that the server is not functional. For example,
/// there's a fatal build configuration problem. The server might
/// still give correct answers to simple requests, but most results
/// will be incomplete or wrong.
health: "ok" | "warning" | "error",
/// Is there any pending background work which might change the status?
/// For example, are dependencies being downloaded?
quiescent: boolean,
/// Explanatory message to show on hover.
message?: string,
}This notification is sent from server to client.
The client can use it to display persistent status to the user (in modline).
It is similar to the showMessage, but is intended for stares rather than point-in-time events.
Note that this functionality is intended primarily to inform the end user about the state of the server.
In particular, it's valid for the client to completely ignore this extension.
Clients are discouraged from but are allowed to use the health status to decide if it's worth sending a request to the server.
The flycheck/checkOnSave feature can be controlled via notifications sent by the client to the server.
Method: rust-analyzer/runFlycheck
Notification:
interface RunFlycheckParams {
/// The text document whose cargo workspace flycheck process should be started.
/// If the document is null or does not belong to a cargo workspace all flycheck processes will be started.
textDocument: lc.TextDocumentIdentifier | null;
}Triggers the flycheck processes.
Method: rust-analyzer/clearFlycheck
Notification:
interface ClearFlycheckParams {}Clears the flycheck diagnostics.
Method: rust-analyzer/cancelFlycheck
Notification:
interface CancelFlycheckParams {}Cancels all running flycheck processes.
Method: rust-analyzer/syntaxTree
Request:
interface SyntaxTreeParams {
textDocument: TextDocumentIdentifier,
range?: Range,
}Response: string
Returns textual representation of a parse tree for the file/selected region. Primarily for debugging, but very useful for all people working on rust-analyzer itself.
Method: rust-analyzer/viewHir
Request: TextDocumentPositionParams
Response: string
Returns a textual representation of the HIR of the function containing the cursor. For debugging or when working on rust-analyzer itself.
Method: rust-analyzer/viewMir
Request: TextDocumentPositionParams
Response: string
Returns a textual representation of the MIR of the function containing the cursor. For debugging or when working on rust-analyzer itself.
Method: rust-analyzer/interpretFunction
Request: TextDocumentPositionParams
Response: string
Tries to evaluate the function using internal rust analyzer knowledge, without compiling the code. Currently evaluates the function under cursor, but will give a runnable in future. Highly experimental.
Method: rust-analyzer/viewFileText
Request: TextDocumentIdentifier
Response: string
Returns the text of a file as seen by the server. This is for debugging file sync problems.
Method: rust-analyzer/viewItemTree
Request:
interface ViewItemTreeParams {
textDocument: TextDocumentIdentifier,
}Response: string
Returns a textual representation of the ItemTree of the currently open file, for debugging.
Method: rust-analyzer/viewCrateGraph
Request:
interface ViewCrateGraphParams {
full: boolean,
}Response: string
Renders rust-analyzer's crate graph as an SVG image.
If full is true, the graph includes non-workspace crates (crates.io dependencies as well as sysroot crates).
Method: rust-analyzer/shuffleCrateGraph
Request: null
Shuffles the crate IDs in the crate graph, for debugging purposes.
Method: rust-analyzer/expandMacro
Request:
interface ExpandMacroParams {
textDocument: TextDocumentIdentifier,
position: Position,
}Response:
interface ExpandedMacro {
name: string,
expansion: string,
}Expands macro call at a given position.
Experimental Client Capability: { "hoverActions": boolean }
If this capability is set, Hover request returned from the server might contain an additional field, actions:
interface Hover {
...
actions?: CommandLinkGroup[];
}
interface CommandLink extends Command {
/**
* A tooltip for the command, when represented in the UI.
*/
tooltip?: string;
}
interface CommandLinkGroup {
title?: string;
commands: CommandLink[];
}Such actions on the client side are appended to a hover bottom as command links:
+-----------------------------+
| Hover content |
| |
+-----------------------------+
| _Action1_ | _Action2_ | <- first group, no TITLE
+-----------------------------+
| TITLE _Action1_ | _Action2_ | <- second group
+-----------------------------+
...
Upstream Issue: rust-lang#6462
Experimental Server Capability: { "openCargoToml": boolean }
This request is sent from client to server to open the current project's Cargo.toml
Method: experimental/openCargoToml
Request: OpenCargoTomlParams
Response: Location | null
// Cargo.toml
[package]
// src/main.rs
/* cursor here*/experimental/openCargoToml returns a single Link to the start of the [package] keyword.
This request is sent from client to server to get the list of tests for the specified position.
Method: rust-analyzer/relatedTests
Request: TextDocumentPositionParams
Response: TestInfo[]
interface TestInfo {
runnable: Runnable;
}Upstream Issue: microsoft/language-server-protocol#377
Experimental Server Capability: { "hoverRange": boolean }
This extension allows passing a Range as a position field of HoverParams.
The primary use-case is to use the hover request to show the type of the expression currently selected.
interface HoverParams extends WorkDoneProgressParams {
textDocument: TextDocumentIdentifier;
position: Range | Position;
}Whenever the client sends a Range, it is understood as the current selection and any hover included in the range will show the type of the expression if possible.
fn main() {
let expression = $01 + 2 * 3$0;
}Triggering a hover inside the selection above will show a result of i32.
Upstream Issue: rust-lang#6823
This request is sent from client to server to move item under cursor or selection in some direction.
Method: experimental/moveItem
Request: MoveItemParams
Response: SnippetTextEdit[]
export interface MoveItemParams {
textDocument: TextDocumentIdentifier,
range: Range,
direction: Direction
}
export const enum Direction {
Up = "Up",
Down = "Down"
}Upstream Issue: microsoft/language-server-protocol#941
Experimental Server Capability: { "workspaceSymbolScopeKindFiltering": boolean }
Extends the existing workspace/symbol request with ability to filter symbols by broad scope and kind of symbol.
If this capability is set, workspace/symbol parameter gains two new optional fields:
interface WorkspaceSymbolParams {
/**
* Return only the symbols defined in the specified scope.
*/
searchScope?: WorkspaceSymbolSearchScope;
/**
* Return only the symbols of specified kinds.
*/
searchKind?: WorkspaceSymbolSearchKind;
...
}
const enum WorkspaceSymbolSearchScope {
Workspace = "workspace",
WorkspaceAndDependencies = "workspaceAndDependencies"
}
const enum WorkspaceSymbolSearchKind {
OnlyTypes = "onlyTypes",
AllSymbols = "allSymbols"
}Upstream Issue: microsoft/language-server-protocol#642
Experimental Client Capability: { "commands?": ClientCommandOptions }
Certain LSP types originating on the server, notably code lenses, embed commands. Commands can be serviced either by the server or by the client. However, the server doesn't know which commands are available on the client.
This extensions allows the client to communicate this info.
export interface ClientCommandOptions {
/**
* The commands to be executed on the client
*/
commands: string[];
}Experimental Client Capability: { "colorDiagnosticOutput": boolean }
If this capability is set, the "full compiler diagnostics" provided by checkOnSave
will include ANSI color and style codes to render the diagnostic in a similar manner
as cargo. This is translated into --message-format=json-diagnostic-rendered-ansi
when flycheck is run, instead of the default --message-format=json.
The full compiler rendered diagnostics are included in the server response regardless of this capability:
// https://microsoft.github.io/language-server-protocol/specifications/specification-current#diagnostic
export interface Diagnostic {
...
data?: {
/**
* The human-readable compiler output as it would be printed to a terminal.
* Includes ANSI color and style codes if the client has set the experimental
* `colorDiagnosticOutput` capability.
*/
rendered?: string;
};
}Method: rust-analyzer/fetchDependencyList
Request:
export interface FetchDependencyListParams {}Response:
export interface FetchDependencyListResult {
crates: {
name: string;
version: string;
path: string;
}[];
}Returns all crates from this workspace, so it can be used create a viewTree to help navigate the dependency tree.
Method: rust-analyzer/viewRecursiveMemoryLayout
Request: TextDocumentPositionParams
Response:
export interface RecursiveMemoryLayoutNode = {
/// Name of the item, or [ROOT], `.n` for tuples
item_name: string;
/// Full name of the type (type aliases are ignored)
typename: string;
/// Size of the type in bytes
size: number;
/// Alignment of the type in bytes
alignment: number;
/// Offset of the type relative to its parent (or 0 if its the root)
offset: number;
/// Index of the node's parent (or -1 if its the root)
parent_idx: number;
/// Index of the node's children (or -1 if it does not have children)
children_start: number;
/// Number of child nodes (unspecified it does not have children)
children_len: number;
};
export interface RecursiveMemoryLayout = {
nodes: RecursiveMemoryLayoutNode[];
};Returns a vector of nodes representing items in the datatype as a tree, RecursiveMemoryLayout::nodes[0] is the root node.
If RecursiveMemoryLayout::nodes::length == 0 we could not find a suitable type.
Generic Types do not give anything because they are incomplete. Fully specified generic types do not give anything if they are selected directly but do work when a child of other types this is consistent with other behavior.
- How should enums/unions be represented? currently they do not produce any children because they have multiple distinct sets of children.
- Should niches be represented? currently they are not reported.
- A visual representation of the memory layout is not specified, see the provided implementation for an example, however it may not translate well to terminal based editors or other such things.