99 lines · c
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-exception6//7//===----------------------------------------------------------------------===//8//9// The language server protocol is usually implemented by writing messages as10// JSON-RPC over the stdin/stdout of a subprocess. However other communications11// mechanisms are possible, such as XPC on mac.12//13// The Transport interface allows the mechanism to be replaced, and the JSONRPC14// Transport is the standard implementation.15//16//===----------------------------------------------------------------------===//17 18#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_TRANSPORT_H19#define LLVM_CLANG_TOOLS_EXTRA_CLANGD_TRANSPORT_H20 21#include "Feature.h"22#include "llvm/ADT/StringRef.h"23#include "llvm/Support/JSON.h"24#include "llvm/Support/raw_ostream.h"25 26namespace clang {27namespace clangd {28 29// A transport is responsible for maintaining the connection to a client30// application, and reading/writing structured messages to it.31//32// Transports have limited thread safety requirements:33// - messages will not be sent concurrently34// - messages MAY be sent while loop() is reading, or its callback is active35class Transport {36public: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).66enum 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 Delimited71};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, the79// process received EINTR, the stream went bad, and clangd exited.80// A retry-on-EINTR loop around reads solved this problem, but caused clangd to81// sometimes hang rather than exit on other OSes. The interaction between82// 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.84std::unique_ptr<Transport>85newJSONTransport(std::FILE *In, llvm::raw_ostream &Out,86 llvm::raw_ostream *InMirror, bool Pretty,87 JSONStreamStyle = JSONStreamStyle::Standard);88 89#if CLANGD_BUILD_XPC90// Returns a Transport for macOS based on XPC.91// Clangd with this transport is meant to be run as bundled XPC service.92std::unique_ptr<Transport> newXPCTransport();93#endif94 95} // namespace clangd96} // namespace clang97 98#endif99