1 //===--- Transport.h - sending and receiving LSP messages -------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 // 9 // The language server protocol is usually implemented by writing messages as 10 // JSON-RPC over the stdin/stdout of a subprocess. However other communications 11 // mechanisms are possible, such as XPC on mac. 12 // 13 // The Transport interface allows the mechanism to be replaced, and the JSONRPC 14 // Transport is the standard implementation. 15 // 16 //===----------------------------------------------------------------------===// 17 18 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_TRANSPORT_H 19 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_TRANSPORT_H 20 21 #include "Feature.h" 22 #include "llvm/ADT/StringRef.h" 23 #include "llvm/Support/JSON.h" 24 #include "llvm/Support/raw_ostream.h" 25 26 namespace clang { 27 namespace clangd { 28 29 // A transport is responsible for maintaining the connection to a client 30 // application, and reading/writing structured messages to it. 31 // 32 // Transports have limited thread safety requirements: 33 // - messages will not be sent concurrently 34 // - messages MAY be sent while loop() is reading, or its callback is active 35 class Transport { 36 public: 37 virtual ~Transport() = default; 38 39 // Called by Clangd to send messages to the client. 40 virtual void notify(llvm::StringRef Method, llvm::json::Value Params) = 0; 41 virtual void call(llvm::StringRef Method, llvm::json::Value Params, 42 llvm::json::Value ID) = 0; 43 virtual void reply(llvm::json::Value ID, 44 llvm::Expected<llvm::json::Value> Result) = 0; 45 46 // Implemented by Clangd to handle incoming messages. (See loop() below). 47 class MessageHandler { 48 public: 49 virtual ~MessageHandler() = default; 50 // Handler returns true to keep processing messages, or false to shut down. 51 virtual bool onNotify(llvm::StringRef Method, llvm::json::Value) = 0; 52 virtual bool onCall(llvm::StringRef Method, llvm::json::Value Params, 53 llvm::json::Value ID) = 0; 54 virtual bool onReply(llvm::json::Value ID, 55 llvm::Expected<llvm::json::Value> Result) = 0; 56 }; 57 // Called by Clangd to receive messages from the client. 58 // The transport should in turn invoke the handler to process messages. 59 // If handler returns false, the transport should immediately exit the loop. 60 // (This is used to implement the `exit` notification). 61 // Otherwise, it returns an error when the transport becomes unusable. 62 virtual llvm::Error loop(MessageHandler &) = 0; 63 }; 64 65 // Controls the way JSON-RPC messages are encoded (both input and output). 66 enum JSONStreamStyle { 67 // Encoding per the LSP specification, with mandatory Content-Length header. 68 Standard, 69 // Messages are delimited by a '---' line. Comment lines start with #. 70 Delimited 71 }; 72 73 // Returns a Transport that speaks JSON-RPC over a pair of streams. 74 // The input stream must be opened in binary mode. 75 // If InMirror is set, data read will be echoed to it. 76 // 77 // The use of C-style std::FILE* input deserves some explanation. 78 // Previously, std::istream was used. When a debugger attached on MacOS, the 79 // process received EINTR, the stream went bad, and clangd exited. 80 // A retry-on-EINTR loop around reads solved this problem, but caused clangd to 81 // sometimes hang rather than exit on other OSes. The interaction between 82 // istreams and signals isn't well-specified, so it's hard to get this right. 83 // The C APIs seem to be clearer in this respect. 84 std::unique_ptr<Transport> 85 newJSONTransport(std::FILE *In, llvm::raw_ostream &Out, 86 llvm::raw_ostream *InMirror, bool Pretty, 87 JSONStreamStyle = JSONStreamStyle::Standard); 88 89 #if CLANGD_BUILD_XPC 90 // Returns a Transport for macOS based on XPC. 91 // Clangd with this transport is meant to be run as bundled XPC service. 92 std::unique_ptr<Transport> newXPCTransport(); 93 #endif 94 95 } // namespace clangd 96 } // namespace clang 97 98 #endif 99