Building a Rust Language Server

A Complete Guide to Implementing LSP in Rust

Chapter 1: What Is a Language Server?

1. The Problem Every IDE Solver Must Solve
2. From Proprietary Plugins to a Universal Protocol
3. How Language Servers Fit Into Modern Development
4. What We Are Building: Scope and Roadmap

Chapter 2: The Language Server Protocol

1. LSP Architecture: Client and Server Roles
2. JSON-RPC 2.0: The Transport Layer
3. The Initialization Handshake
4. Capability Negotiation and Feature Discovery

Chapter 3: Rust Tooling and Project Setup

1. Choosing Your LSP Crate: lsp-server and Alternatives
2. Project Structure and Cargo Configuration
3. Async Runtime Selection: Tokio vs. Others
4. First Compile: Hello, Language Server

Chapter 4: LSP Messages and Transport

1. Requests, Responses and Notifications
2. Message Routing and Handler Registration
3. Error Handling and JSON-RPC Errors
4. Building a Minimal Request Handler

Chapter 5: Initialization and Capabilities

1. The initialize Request and Its Parameters
2. Declaring Server Capabilities
3. Handling initialized Notifications
4. Exposing Workspace and Document Support

Chapter 6: Document Synchronization

1. Opening, Changing, Saving and Closing Documents
2. Incremental vs. Full Document Updates
3. URI Handling and Encoding
4. Building an In-Memory Document Store

Chapter 7: Positions, Ranges and Text Operations

1. LSP Position, Range and Location Types
2. Converting Between Byte Offsets and Positions
3. TextEdit and OptionalVersionedTextDocumentContentChangeEvent
4. Building a Text Document Model

Chapter 8: Parsing and Syntax Analysis

1. Designing a Minimal Language for Our Server
2. Writing a Lexer: Tokenization in Rust

Chapter 9: Diagnostics and Error Reporting

1. Diagnostic Severity, Codes and Ranges
2. Generating Diagnostics from Parse Errors
3. Semantic Diagnostics: Type Checking Basics
4. Publishing Diagnostics with publishDiagnostics

Chapter 10: Symbol Indexing

1. Collecting Symbols from the AST
2. Symbol Kinds and Hierarchical Relationships
3. Building a Fast Symbol Index
4. Scope Resolution and Name Lookup

Chapter 11: Document Symbols and Workspace Symbols

1. The documentSymbol Request: Generating Outlines
2. The workspaceSymbol Request: Global Search
3. Symbol Filters and Result Scoring
4. Performance Considerations for Large Workspaces

Chapter 12: Go to Definition

1. The definition Request and Its Protocol
2. Resolving References to Definitions
3. Handling Multiple Definitions and Ambiguities
4. Cross-File Navigation

Chapter 13: Find All References

1. The references Request and ReferenceContext
2. Walking the AST for Reference Collection
3. Excluding the Definition Itself
4. Scaling Reference Search Across Files

Chapter 14: Hover Information

1. The hover Request and MarkupKinds
2. Resolving Symbols Under the Cursor
3. Formatting Hover Content with Markdown
4. Including Type Information and Signatures

Chapter 15: Completions

1. The completion Request and CompletionItem Types
2. Trigger Characters and Context-Aware Suggestions
3. CompletionItemKinds and Detail Formatting
4. Completion Item Resolve and Snippets

Chapter 16: Signature Help

1. The signatureHelp Request and Trigger Types
2. Identifying the Active Parameter
3. SignatureInformation and ParameterInformation
4. Handling Nested Calls and Overloads

Chapter 17: Code Actions

1. The codeAction Request and Diagnostic Context
2. Quick Fixes: Converting Diagnostics to Actions
3. Refactoring Code Actions
4. Command Execution and CodeActionResolve

Chapter 18: Rename

1. The rename and prepareRename Requests
2. Collecting All References Before Renaming
3. Preparing the WorkspaceEdit
4. Validation and Conflict Detection

Chapter 19: Semantic Tokens

1. Semantic Tokens Overview and Encoding
2. Token Types and Modifiers
3. Generating Tokens from the AST
4. Incremental Token Updates and Performance

Chapter 20: Code Lenses

1. The codeLens Request and Its Use Cases
2. Generating Lenses from AST Analysis
3. CodeLens Resolve and Dynamic Actions
4. Real-World Examples: Run, Test, References

Chapter 21: Code Formatting

1. The formatting Requests and FormattingOptions
2. Building a Formatter from the AST
3. Preserving Source Formatting Where Possible
4. Formatter Configuration and Style Rules

Chapter 22: Concurrency and Async Architecture

1. The Event Loop and Request Processing Model
2. Async/Await Patterns in Language Servers
3. Thread Pools and Parallel Work
4. Avoiding Deadlocks and Priority Inversion

Chapter 23: Performance and Optimization

1. Profiling a Language Server
2. Incremental Parsing and AST Caching
3. Efficient Data Structures for Indexing
4. Debouncing and Request Throttling

Chapter 24: Testing the Language Server

1. Unit Testing Parsers and Analyzers
2. Integration Testing LSP Requests
3. Protocol-Level Testing with Mock Clients
4. End-to-End Testing with Real Editors

Chapter 25: Logging, Debugging and Observability

1. LSP Logging Channels and Tracing
2. Structured Logging with tracing and tracing-subscriber
3. Debugging Common Language Server Bugs
4. Remote Debugging and Attach Strategies

Chapter 26: Packaging, Distribution and Editor Integration

1. Building and Cross-Compiling for Distribution
2. Publishing as a GitHub Release
3. Visual Studio Code Extension Integration
4. Neovim, Emacs and Other LSP Clients

Conclusion: The Road Ahead

1. From Educational to Production: What Is Missing
2. Advanced Topics: Inlay Hints, Inline Values, Type Hierarchies
3. Contributing to rust-analyzer and Other Projects
4. The Future of Language Servers

References