lib/lsp-server/src/lib.rs

   1 //! A language server scaffold, exposing a synchronous crossbeam-channel based API.
   2 //! This crate handles protocol handshaking and parsing messages, while you
   3 //! control the message dispatch loop yourself.
   4 //!
   5 //! Run with `RUST_LOG=lsp_server=debug` to see all the messages.
   6 mod msg;
   7 mod stdio;
   8 mod error;
   9 mod socket;
  10 mod req_queue;
  11
  12 use std::{
  13     io,
  14     net::{TcpListener, TcpStream, ToSocketAddrs},
  15 };
  16
  17 use crossbeam_channel::{Receiver, Sender};
  18
  19 pub use crate::{
  20     error::{ExtractError, ProtocolError},
  21     msg::{ErrorCode, Message, Notification, Request, RequestId, Response, ResponseError},
  22     req_queue::{Incoming, Outgoing, ReqQueue},
  23     stdio::IoThreads,
  24 };
  25
  26 /// Connection is just a pair of channels of LSP messages.
  27 pub struct Connection {
  28     pub sender: Sender<Message>,
  29     pub receiver: Receiver<Message>,
  30 }
  31
  32 impl Connection {
  33     /// Create connection over standard in/standard out.
  34     ///
  35     /// Use this to create a real language server.
  36     pub fn stdio() -> (Connection, IoThreads) {
  37         let (sender, receiver, io_threads) = stdio::stdio_transport();
  38         (Connection { sender, receiver }, io_threads)
  39     }
  40
  41     /// Open a connection over tcp.
  42     /// This call blocks until a connection is established.
  43     ///
  44     /// Use this to create a real language server.
  45     pub fn connect<A: ToSocketAddrs>(addr: A) -> io::Result<(Connection, IoThreads)> {
  46         let stream = TcpStream::connect(addr)?;
  47         let (sender, receiver, io_threads) = socket::socket_transport(stream);
  48         Ok((Connection { sender, receiver }, io_threads))
  49     }
  50
  51     /// Listen for a connection over tcp.
  52     /// This call blocks until a connection is established.
  53     ///
  54     /// Use this to create a real language server.
  55     pub fn listen<A: ToSocketAddrs>(addr: A) -> io::Result<(Connection, IoThreads)> {
  56         let listener = TcpListener::bind(addr)?;
  57         let (stream, _) = listener.accept()?;
  58         let (sender, receiver, io_threads) = socket::socket_transport(stream);
  59         Ok((Connection { sender, receiver }, io_threads))
  60     }
  61
  62     /// Creates a pair of connected connections.
  63     ///
  64     /// Use this for testing.
  65     pub fn memory() -> (Connection, Connection) {
  66         let (s1, r1) = crossbeam_channel::unbounded();
  67         let (s2, r2) = crossbeam_channel::unbounded();
  68         (Connection { sender: s1, receiver: r2 }, Connection { sender: s2, receiver: r1 })
  69     }
  70
  71     /// Starts the initialization process by waiting for an initialize
  72     /// request from the client. Use this for more advanced customization than
  73     /// `initialize` can provide.
  74     ///
  75     /// Returns the request id and serialized `InitializeParams` from the client.
  76     ///
  77     /// # Example
  78     ///
  79     /// ```no_run
  80     /// use std::error::Error;
  81     /// use lsp_types::{ClientCapabilities, InitializeParams, ServerCapabilities};
  82     ///
  83     /// use lsp_server::{Connection, Message, Request, RequestId, Response};
  84     ///
  85     /// fn main() -> Result<(), Box<dyn Error + Sync + Send>> {
  86     ///    // Create the transport. Includes the stdio (stdin and stdout) versions but this could
  87     ///    // also be implemented to use sockets or HTTP.
  88     ///    let (connection, io_threads) = Connection::stdio();
  89     ///
  90     ///    // Run the server
  91     ///    let (id, params) = connection.initialize_start()?;
  92     ///
  93     ///    let init_params: InitializeParams = serde_json::from_value(params).unwrap();
  94     ///    let client_capabilities: ClientCapabilities = init_params.capabilities;
  95     ///    let server_capabilities = ServerCapabilities::default();
  96     ///
  97     ///    let initialize_data = serde_json::json!({
  98     ///        "capabilities": server_capabilities,
  99     ///        "serverInfo": {
 100     ///            "name": "lsp-server-test",
 101     ///            "version": "0.1"
 102     ///        }
 103     ///    });
 104     ///
 105     ///    connection.initialize_finish(id, initialize_data)?;
 106     ///
 107     ///    // ... Run main loop ...
 108     ///
 109     ///    Ok(())
 110     /// }
 111     /// ```
 112     pub fn initialize_start(&self) -> Result<(RequestId, serde_json::Value), ProtocolError> {
 113         loop {
 114             match self.receiver.recv() {
 115                 Ok(Message::Request(req)) if req.is_initialize() => {
 116                     return Ok((req.id, req.params))
 117                 }
 118                 // Respond to non-initialize requests with ServerNotInitialized
 119                 Ok(Message::Request(req)) => {
 120                     let resp = Response::new_err(
 121                         req.id.clone(),
 122                         ErrorCode::ServerNotInitialized as i32,
 123                         format!("expected initialize request, got {:?}", req),
 124                     );
 125                     self.sender.send(resp.into()).unwrap();
 126                 }
 127                 Ok(msg) => {
 128                     return Err(ProtocolError(format!(
 129                         "expected initialize request, got {:?}",
 130                         msg
 131                     )))
 132                 }
 133                 Err(e) => {
 134                     return Err(ProtocolError(format!(
 135                         "expected initialize request, got error: {}",
 136                         e
 137                     )))
 138                 }
 139             };
 140         }
 141     }
 142
 143     /// Finishes the initialization process by sending an `InitializeResult` to the client
 144     pub fn initialize_finish(
 145         &self,
 146         initialize_id: RequestId,
 147         initialize_result: serde_json::Value,
 148     ) -> Result<(), ProtocolError> {
 149         let resp = Response::new_ok(initialize_id, initialize_result);
 150         self.sender.send(resp.into()).unwrap();
 151         match &self.receiver.recv() {
 152             Ok(Message::Notification(n)) if n.is_initialized() => (),
 153             Ok(msg) => {
 154                 return Err(ProtocolError(format!(
 155                     "expected Message::Notification, got: {:?}",
 156                     msg,
 157                 )))
 158             }
 159             Err(e) => {
 160                 return Err(ProtocolError(format!(
 161                     "expected initialized notification, got error: {}",
 162                     e,
 163                 )))
 164             }
 165         }
 166         Ok(())
 167     }
 168
 169     /// Initialize the connection. Sends the server capabilities
 170     /// to the client and returns the serialized client capabilities
 171     /// on success. If more fine-grained initialization is required use
 172     /// `initialize_start`/`initialize_finish`.
 173     ///
 174     /// # Example
 175     ///
 176     /// ```no_run
 177     /// use std::error::Error;
 178     /// use lsp_types::ServerCapabilities;
 179     ///
 180     /// use lsp_server::{Connection, Message, Request, RequestId, Response};
 181     ///
 182     /// fn main() -> Result<(), Box<dyn Error + Sync + Send>> {
 183     ///    // Create the transport. Includes the stdio (stdin and stdout) versions but this could
 184     ///    // also be implemented to use sockets or HTTP.
 185     ///    let (connection, io_threads) = Connection::stdio();
 186     ///
 187     ///    // Run the server
 188     ///    let server_capabilities = serde_json::to_value(&ServerCapabilities::default()).unwrap();
 189     ///    let initialization_params = connection.initialize(server_capabilities)?;
 190     ///
 191     ///    // ... Run main loop ...
 192     ///
 193     ///    Ok(())
 194     /// }
 195     /// ```
 196     pub fn initialize(
 197         &self,
 198         server_capabilities: serde_json::Value,
 199     ) -> Result<serde_json::Value, ProtocolError> {
 200         let (id, params) = self.initialize_start()?;
 201
 202         let initialize_data = serde_json::json!({
 203             "capabilities": server_capabilities,
 204         });
 205
 206         self.initialize_finish(id, initialize_data)?;
 207
 208         Ok(params)
 209     }
 210
 211     /// If `req` is `Shutdown`, respond to it and return `true`, otherwise return `false`
 212     pub fn handle_shutdown(&self, req: &Request) -> Result<bool, ProtocolError> {
 213         if !req.is_shutdown() {
 214             return Ok(false);
 215         }
 216         let resp = Response::new_ok(req.id.clone(), ());
 217         let _ = self.sender.send(resp.into());
 218         match &self.receiver.recv_timeout(std::time::Duration::from_secs(30)) {
 219             Ok(Message::Notification(n)) if n.is_exit() => (),
 220             Ok(msg) => {
 221                 return Err(ProtocolError(format!("unexpected message during shutdown: {:?}", msg)))
 222             }
 223             Err(e) => {
 224                 return Err(ProtocolError(format!("unexpected error during shutdown: {}", e)))
 225             }
 226         }
 227         Ok(true)
 228     }
 229 }