clang-tools-extra/clangd/Transport.h

   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