| 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 |