Line data    Source code

       1             : //===--- Transport.h - sending and receiving LSP messages -------*- C++ -*-===//
       2             : //
       3             : //                     The LLVM Compiler Infrastructure
       4             : //
       5             : // This file is distributed under the University of Illinois Open Source
       6             : // License. See LICENSE.TXT for details.
       7             : //
       8             : //===----------------------------------------------------------------------===//
       9             : //
      10             : // The language server protocol is usually implemented by writing messages as
      11             : // JSON-RPC over the stdin/stdout of a subprocess. However other communications
      12             : // mechanisms are possible, such as XPC on mac.
      13             : //
      14             : // The Transport interface allows the mechanism to be replaced, and the JSONRPC
      15             : // Transport is the standard implementation.
      16             : //
      17             : //===----------------------------------------------------------------------===//
      18             : 
      19             : #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_TRANSPORT_H_
      20             : #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_TRANSPORT_H_
      21             : 
      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           0 :     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 immedately 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             : } // namespace clangd
      90             : } // namespace clang
      91             : 
      92             : #endif