13#ifndef LLDB_HOST_JSONTRANSPORT_H
14#define LLDB_HOST_JSONTRANSPORT_H
21#include "llvm/ADT/FunctionExtras.h"
22#include "llvm/ADT/StringExtras.h"
23#include "llvm/ADT/StringRef.h"
24#include "llvm/Support/Error.h"
25#include "llvm/Support/ErrorHandling.h"
26#include "llvm/Support/FormatVariadic.h"
27#include "llvm/Support/JSON.h"
28#include "llvm/Support/raw_ostream.h"
34#include <system_error>
39#if __cplusplus >= 202002L
48 :
public llvm::ErrorInfo<TransportUnhandledContentsError> {
54 void log(llvm::raw_ostream &
OS)
const override;
74 void log(llvm::raw_ostream &
OS)
const override;
95 void log(llvm::raw_ostream &
OS)
const override;
102#if __cplusplus >= 202002L
106concept ProtocolDescriptor =
requires {
121#if __cplusplus >= 202002L
122template <ProtocolDescriptor Proto>
124template <
typename Proto>
128 using Req =
typename Proto::Req;
129 using Resp =
typename Proto::Resp;
130 using Evt =
typename Proto::Evt;
169 virtual llvm::Expected<MainLoop::ReadHandleUP>
173 template <
typename... Ts>
inline auto Logv(
const char *Fmt, Ts &&...Vals) {
174 Log(llvm::formatv(Fmt, std::forward<Ts>(Vals)...).str());
176 virtual void Log(llvm::StringRef message) = 0;
188 llvm::Error
Send(
const typename Proto::Evt &evt)
override {
191 llvm::Error
Send(
const typename Proto::Req &req)
override {
194 llvm::Error
Send(
const typename Proto::Resp &resp)
override {
198 llvm::Expected<MainLoop::ReadHandleUP>
217 llvm::Error
Write(
const llvm::json::Value &message) {
218 this->
Logv(
"<-- {0}", message);
219 std::string output =
Encode(message);
220 size_t bytes_written = output.size();
221 return m_out->Write(output.data(), bytes_written).takeError();
224 virtual llvm::Expected<std::vector<std::string>>
Parse() = 0;
225 virtual std::string
Encode(
const llvm::json::Value &message) = 0;
232 size_t num_bytes =
sizeof(buf);
233 if (
Status status =
m_in->Read(buf, num_bytes); status.Fail()) {
234 handler.OnError(status.takeError());
239 m_buffer.append(llvm::StringRef(buf, num_bytes));
243 llvm::Expected<std::vector<std::string>> raw_messages =
Parse();
244 if (llvm::Error
error = raw_messages.takeError()) {
245 handler.OnError(std::move(
error));
249 for (
const std::string &raw_message : *raw_messages) {
250 llvm::Expected<Message> message =
251 llvm::json::parse<Message>(raw_message);
253 handler.OnError(message.takeError());
257 std::visit([&handler](
auto &&msg) { handler.Received(msg); }, *message);
262 if (num_bytes == 0) {
265 handler.OnError(llvm::make_error<TransportUnhandledContentsError>(
276#if __cplusplus >= 202002L
277template <ProtocolDescriptor Proto>
279template <
typename Proto>
288 std::string
Encode(
const llvm::json::Value &message)
override {
290 std::string raw_message = llvm::formatv(
"{0}", message).str();
291 llvm::raw_string_ostream
OS(output);
293 << std::to_string(raw_message.size()) <<
kEndOfHeader << raw_message;
299 llvm::Expected<std::vector<std::string>>
Parse()
override {
300 std::vector<std::string> messages;
301 llvm::StringRef buffer = this->
m_buffer;
304 size_t content_length = 0;
306 for (
const llvm::StringRef &header :
314 value = value.trim();
315 if (!llvm::to_integer(value, content_length, 10)) {
318 return llvm::createStringError(std::errc::invalid_argument,
319 "invalid content length: %s",
320 value.str().c_str());
325 if (content_length > rest.size())
328 llvm::StringRef body = rest.take_front(content_length);
329 buffer = rest.drop_front(content_length);
330 messages.emplace_back(body.str());
331 this->
Logv(
"--> {0}", body);
337 return std::move(messages);
347#if __cplusplus >= 202002L
348template <ProtocolDescriptor Proto>
350template <
typename Proto>
357 std::string
Encode(
const llvm::json::Value &message)
override {
361 llvm::Expected<std::vector<std::string>>
Parse()
override {
362 std::vector<std::string> messages;
363 llvm::StringRef buf = this->
m_buffer;
367 messages.emplace_back(raw_json.str());
368 this->
Logv(
"--> {0}", raw_json);
383 std::conditional_t<std::is_void_v<T>,
384 llvm::unique_function<void(llvm::Error)>,
385 llvm::unique_function<void(llvm::Expected<T>)>>;
388template <
typename R,
typename P>
struct request_t final {
395 using type = llvm::unique_function<void(
const P &)>;
398 using type = llvm::unique_function<void()>;
402template <
typename R,
typename P>
408#if __cplusplus >= 202002L
412concept BindingBuilder =
413 ProtocolDescriptor<T> &&
414 requires(T::Id
id, T::Req req, T::Resp resp, T::Evt evt,
415 llvm::StringRef method, std::optional<llvm::json::Value> params,
416 std::optional<llvm::json::Value> result, llvm::Error err) {
418 { T::InitialId() } -> std::same_as<typename T::Id>;
420 {
id++ } -> std::same_as<typename T::Id>;
425 { T::Make(
id, method, params) } -> std::same_as<typename T::Req>;
427 { T::Make(req, std::move(err)) } -> std::same_as<typename T::Resp>;
429 { T::Make(req, result) } -> std::same_as<typename T::Resp>;
431 { T::Make(method, params) } -> std::same_as<typename T::Evt>;
437 { T::KeyFor(resp) } -> std::same_as<typename T::Id>;
439 { T::KeyFor(req) } -> std::same_as<std::string>;
441 { T::KeyFor(evt) } -> std::same_as<std::string>;
447 { T::Extract(req) } -> std::same_as<std::optional<llvm::json::Value>>;
449 { T::Extract(resp) } -> std::same_as<llvm::Expected<llvm::json::Value>>;
451 { T::Extract(evt) } -> std::same_as<std::optional<llvm::json::Value>>;
482#if __cplusplus >= 202002L
483template <BindingBuilder Proto>
485template <
typename Proto>
488 using Req =
typename Proto::Req;
489 using Resp =
typename Proto::Resp;
490 using Evt =
typename Proto::Evt;
491 using Id =
typename Proto::Id;
502 template <
typename Fn,
typename...
Args>
506 template <
typename Fn,
typename...
Args>
513 template <
typename Result,
typename Params,
typename Fn,
typename...
Args>
514 void Bind(llvm::StringLiteral method, Fn &&fn,
Args &&...args);
520 template <
typename Params,
typename Fn,
typename...
Args>
521 void Bind(llvm::StringLiteral method, Fn &&fn,
Args &&...args);
526 template <
typename Result,
typename Params>
532 template <
typename Params>
536 std::scoped_lock<std::recursive_mutex> guard(
m_mutex);
539 OnError(llvm::createStringError(
540 llvm::formatv(
"no handled for event {0}",
toJSON(evt))));
549 std::scoped_lock<std::recursive_mutex> guard(
m_mutex);
552 reply(Proto::Make(req, llvm::createStringError(
"method not found")));
556 it->second(req, std::move(reply));
560 std::scoped_lock<std::recursive_mutex> guard(
m_mutex);
562 Id id = Proto::KeyFor(resp);
565 OnError(llvm::createStringError(
566 llvm::formatv(
"no pending request for {0}",
toJSON(resp))));
575 std::scoped_lock<std::recursive_mutex> guard(
m_mutex);
581 std::scoped_lock<std::recursive_mutex> guard(
m_mutex);
587 template <
typename T>
588 llvm::Expected<T>
static Parse(
const llvm::json::Value &raw,
589 llvm::StringRef method);
591 template <
typename T>
using Callback = llvm::unique_function<T>;
622 other.transport =
nullptr;
623 other.handler =
nullptr;
631 assert(
false &&
"must reply to all calls!");
632 (*this)(Proto::Make(
req, llvm::createStringError(
"failed to reply")));
639 assert(
false &&
"must reply to each call only once!");
649#if __cplusplus >= 202002L
650template <BindingBuilder Proto>
652template <
typename Proto>
654template <
typename Fn,
typename...
Args>
657 std::invoke(std::forward<Fn>(fn), std::forward<Args>(args)...);
661#if __cplusplus >= 202002L
662template <BindingBuilder Proto>
664template <
typename Proto>
666template <
typename Fn,
typename...
Args>
669 std::invoke(std::forward<Fn>(fn), std::forward<Args>(args)...,
674#if __cplusplus >= 202002L
675template <BindingBuilder Proto>
677template <
typename Proto>
679template <
typename Result,
typename Params,
typename Fn,
typename...
Args>
682 "request already bound");
683 if constexpr (std::is_void_v<Result> && std::is_void_v<Params>) {
685 [fn, args...](
const Req &req,
686 llvm::unique_function<void(
const Resp &)> reply)
mutable {
688 std::invoke(std::forward<Fn>(fn), std::forward<Args>(args)...);
689 reply(Proto::Make(req, std::move(result)));
691 }
else if constexpr (std::is_void_v<Params>) {
693 [fn, args...](
const Req &req,
694 llvm::unique_function<void(
const Resp &)> reply)
mutable {
695 llvm::Expected<Result> result =
696 std::invoke(std::forward<Fn>(fn), std::forward<Args>(args)...);
698 return reply(Proto::Make(req, result.takeError()));
699 reply(Proto::Make(req,
toJSON(*result)));
701 }
else if constexpr (std::is_void_v<Result>) {
704 args...](
const Req &req,
705 llvm::unique_function<void(
const Resp &)> reply)
mutable {
706 llvm::Expected<Params> params =
709 return reply(Proto::Make(req, params.takeError()));
711 llvm::Error result = std::invoke(
712 std::forward<Fn>(fn), std::forward<Args>(args)..., *params);
713 reply(Proto::Make(req, std::move(result)));
718 args...](
const Req &req,
719 llvm::unique_function<void(
const Resp &)> reply)
mutable {
720 llvm::Expected<Params> params =
723 return reply(Proto::Make(req, params.takeError()));
725 llvm::Expected<Result> result = std::invoke(
726 std::forward<Fn>(fn), std::forward<Args>(args)..., *params);
728 return reply(Proto::Make(req, result.takeError()));
730 reply(Proto::Make(req,
toJSON(*result)));
735#if __cplusplus >= 202002L
736template <BindingBuilder Proto>
738template <
typename Proto>
740template <
typename Params,
typename Fn,
typename...
Args>
743 "event already bound");
744 if constexpr (std::is_void_v<Params>) {
746 std::invoke(std::forward<Fn>(fn), std::forward<Args>(args)...);
750 args...](
const Evt &evt)
mutable {
751 llvm::Expected<Params> params =
754 return OnError(params.takeError());
755 std::invoke(std::forward<Fn>(fn), std::forward<Args>(args)..., *params);
760#if __cplusplus >= 202002L
761template <BindingBuilder Proto>
763template <
typename Proto>
765template <
typename Result,
typename Params>
768 if constexpr (std::is_void_v<Result> && std::is_void_v<Params>) {
770 std::scoped_lock<std::recursive_mutex> guard(
m_mutex);
772 Req req = Proto::Make(
id, method, std::nullopt);
774 llvm::Expected<llvm::json::Value> result = Proto::Extract(resp);
776 return fn(result.takeError());
777 fn(llvm::Error::success());
782 }
else if constexpr (std::is_void_v<Params>) {
784 std::scoped_lock<std::recursive_mutex> guard(
m_mutex);
786 Req req = Proto::Make(
id, method, std::nullopt);
788 method](
const Resp &resp)
mutable {
789 llvm::Expected<llvm::json::Value> result = Proto::Extract(resp);
791 return fn(result.takeError());
797 }
else if constexpr (std::is_void_v<Result>) {
798 return [
this, method](
const Params ¶ms,
Reply<Result> fn) {
799 std::scoped_lock<std::recursive_mutex> guard(
m_mutex);
801 Req req = Proto::Make(
id, method, llvm::json::Value(params));
803 llvm::Expected<llvm::json::Value> result = Proto::Extract(resp);
805 return fn(result.takeError());
806 fn(llvm::Error::success());
812 return [
this, method](
const Params ¶ms,
Reply<Result> fn) {
813 std::scoped_lock<std::recursive_mutex> guard(
m_mutex);
815 Req req = Proto::Make(
id, method, llvm::json::Value(params));
817 method](
const Resp &resp)
mutable {
818 llvm::Expected<llvm::json::Value> result = Proto::Extract(resp);
819 if (llvm::Error err = result.takeError())
820 return fn(std::move(err));
829#if __cplusplus >= 202002L
830template <BindingBuilder Proto>
832template <
typename Proto>
834template <
typename Params>
836 if constexpr (std::is_void_v<Params>) {
837 return [
this, method]() {
838 if (llvm::Error
error =
839 m_transport.Send(Proto::Make(method, std::nullopt)))
843 return [
this, method](
const Params ¶ms) {
844 if (llvm::Error
error =
851#if __cplusplus >= 202002L
852template <BindingBuilder Proto>
854template <
typename Proto>
858 llvm::StringRef method) {
860 llvm::json::Path::Root root;
864 llvm::raw_string_ostream
OS(context);
865 root.printErrorContext(raw,
OS);
866 return llvm::make_error<InvalidParams>(method.str(), context);
868 return std::move(result);
static llvm::raw_ostream & error(Stream &strm)
A command line argument class.
std::unique_ptr< ReadHandle > ReadHandleUP
ReadHandleUP RegisterReadObject(const lldb::IOObjectSP &object_sp, const Callback &callback, Status &error) override
bool Fail() const
Test for error condition.
void operator()(const Resp &resp)
ReplyOnce & operator=(const ReplyOnce &)=delete
std::atomic< bool > replied
ReplyOnce(const Req req, Transport *transport, MessageHandler *handler)
ReplyOnce & operator=(ReplyOnce &&)=delete
ReplyOnce(ReplyOnce &&other)
ReplyOnce(const ReplyOnce &)=delete
void Received(const Resp &resp) override
Called when a response is received.
JSONTransport< Proto > Transport
typename Transport::MessageHandler MessageHandler
void OnDisconnect(Fn &&fn, Args &&...args)
Bind a handler on transport disconnect.
void Bind(llvm::StringLiteral method, Fn &&fn, Args &&...args)
Bind a handler for an incoming request.
void Bind(llvm::StringLiteral method, Fn &&fn, Args &&...args)
Bind a handler for an incoming event.
std::recursive_mutex m_mutex
llvm::StringMap< Callback< void(const Req &, Callback< void(const Resp &)>)> > m_request_handlers
void OnClosed() override
Called on EOF or client disconnect.
Callback< void(llvm::Error)> m_error_handler
void OnError(Fn &&fn, Args &&...args)
Bind a handler on error when communicating with the transport.
void Received(const Evt &evt) override
Called when an event is received.
OutgoingRequest< Result, Params > Bind(llvm::StringLiteral method)
Bind a function object to be used for outgoing requests.
std::map< Id, Callback< void(const Resp &)> > m_pending_responses
Binder & operator=(const Binder &)=delete
Binder(Transport &transport)
void Received(const Req &req) override
Called when a request is received.
static llvm::Expected< T > Parse(const llvm::json::Value &raw, llvm::StringRef method)
OutgoingEvent< Params > Bind(llvm::StringLiteral method)
Bind a function object to be used for outgoing events.
Binder(const Binder &)=delete
void OnError(llvm::Error err) override
Called when an error occurs while reading from the transport.
typename Proto::Resp Resp
llvm::unique_function< T > Callback
llvm::StringMap< Callback< void(const Evt &)> > m_event_handlers
Callback< void()> m_disconnect_handler
A transport class for JSON with a HTTP header.
static constexpr llvm::StringLiteral kHeaderFieldSeparator
static constexpr llvm::StringLiteral kEndOfHeader
static constexpr llvm::StringLiteral kHeaderSeparator
std::string Encode(const llvm::json::Value &message) override
Encodes messages based on https://microsoft.github.io/debug-adapter-protocol/overview#base-protocol.
llvm::Expected< std::vector< std::string > > Parse() override
Parses messages based on https://microsoft.github.io/debug-adapter-protocol/overview#base-protocol.
static constexpr llvm::StringLiteral kHeaderContentLength
void OnRead(MainLoopBase &loop, MessageHandler &handler)
static constexpr size_t kReadBufferSize
Public for testing purposes, otherwise this should be an implementation detail.
typename JSONTransport< Proto >::MessageHandler MessageHandler
llvm::Error Send(const typename Proto::Resp &resp) override
IOTransport(lldb::IOObjectSP in, lldb::IOObjectSP out)
typename JSONTransport< Proto >::Message Message
llvm::Error Send(const typename Proto::Evt &evt) override
virtual std::string Encode(const llvm::json::Value &message)=0
virtual llvm::Expected< std::vector< std::string > > Parse()=0
llvm::Error Write(const llvm::json::Value &message)
llvm::Error Send(const typename Proto::Req &req) override
llvm::Expected< MainLoop::ReadHandleUP > RegisterMessageHandler(MainLoop &loop, MessageHandler &handler) override
RegisterMessageHandler registers the Transport with the given MainLoop and handles any incoming messa...
llvm::SmallString< kReadBufferSize > m_buffer
std::error_code convertToErrorCode() const override
std::string m_context
Additional context from the parsing failure, e.g.
InvalidParams(std::string method, std::string context)
std::string m_method
The JSONRPC remote method call.
void log(llvm::raw_ostream &OS) const override
A transport class for JSON RPC.
llvm::Expected< std::vector< std::string > > Parse() override
static constexpr llvm::StringLiteral kMessageSeparator
std::string Encode(const llvm::json::Value &message) override
Implemented to handle incoming messages.
virtual void OnError(llvm::Error)=0
Called when an error occurs while reading from the transport.
virtual void OnClosed()=0
Called on EOF or client disconnect.
virtual ~MessageHandler()=default
virtual void Received(const Req &)=0
Called when a request is received.
virtual void Received(const Evt &)=0
Called when an event is received.
virtual void Received(const Resp &)=0
Called when a response is received.
A transport is responsible for maintaining the connection to a client application,...
virtual llvm::Expected< MainLoop::ReadHandleUP > RegisterMessageHandler(MainLoop &loop, MessageHandler &handler)=0
RegisterMessageHandler registers the Transport with the given MainLoop and handles any incoming messa...
virtual llvm::Error Send(const Resp &)=0
Sends a response to a specific request.
virtual ~JSONTransport()=default
std::variant< Req, Resp, Evt > Message
virtual llvm::Error Send(const Evt &)=0
Sends an event, a message that does not require a response.
auto Logv(const char *Fmt, Ts &&...Vals)
virtual llvm::Error Send(const Req &)=0
Sends a request, a message that expects a response.
virtual void Log(llvm::StringRef message)=0
typename Proto::Resp Resp
static constexpr int kErrorCode
std::error_code convertToErrorCode() const override
MethodNotFound(std::string method)
void log(llvm::raw_ostream &OS) const override
const std::string & getUnhandledContents() const
void log(llvm::raw_ostream &OS) const override
TransportUnhandledContentsError(std::string unhandled_contents)
std::error_code convertToErrorCode() const override
std::string m_unhandled_contents
std::conditional_t< std::is_void_v< T >, llvm::unique_function< void(llvm::Error)>, llvm::unique_function< void(llvm::Expected< T >)> > Reply
A handler for the response to an outgoing request.
typename detail::event_t< P >::type OutgoingEvent
A function to send an outgoing event.
typename detail::request_t< R, P >::type OutgoingRequest
bool fromJSON(const llvm::json::Value &value, TraceSupportedResponse &info, llvm::json::Path path)
llvm::json::Value toJSON(const TraceSupportedResponse &packet)
std::shared_ptr< lldb_private::IOObject > IOObjectSP
llvm::unique_function< void()> type
llvm::unique_function< void(const P &)> type
llvm::unique_function< void(Reply< R >)> type
llvm::unique_function< void(const P &, Reply< R >)> type