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