[Lldb-commits] [lldb] [lldb-dap] Updating RequestHandler to encode/decode arguments and response. (PR #130090)
Adrian Vogelsgesang via lldb-commits
lldb-commits at lists.llvm.org
Fri Mar 14 06:29:50 PDT 2025
================
@@ -30,216 +30,197 @@ namespace lldb_dap::protocol {
// MARK: Base Protocol
-// "Request": {
-// "allOf": [ { "$ref": "#/definitions/ProtocolMessage" }, {
-// "type": "object",
-// "description": "A client or debug adapter initiated request.",
-// "properties": {
-// "type": {
-// "type": "string",
-// "enum": [ "request" ]
-// },
-// "command": {
-// "type": "string",
-// "description": "The command to execute."
-// },
-// "arguments": {
-// "type": [ "array", "boolean", "integer", "null", "number" , "object",
-// "string" ], "description": "Object containing arguments for the
-// command."
-// }
-// },
-// "required": [ "type", "command" ]
-// }]
-// },
+/// A client or debug adapter initiated request.
struct Request {
+ /// Sequence number of the message (also known as message ID). The `seq` for
+ /// the first message sent by a client or debug adapter is 1, and for each
+ /// subsequent message is 1 greater than the previous message sent by that
+ /// actor. `seq` can be used to order requests, responses, and events, and to
+ /// associate requests with their corresponding responses. For protocol
+ /// messages of type `request` the sequence number can be used to cancel the
+ /// request.
int64_t seq;
+
+ /// The command to execute.
std::string command;
+
+ /// Object containing arguments for the command.
std::optional<llvm::json::Value> rawArguments;
};
llvm::json::Value toJSON(const Request &);
bool fromJSON(const llvm::json::Value &, Request &, llvm::json::Path);
-// "Event": {
-// "allOf": [ { "$ref": "#/definitions/ProtocolMessage" }, {
-// "type": "object",
-// "description": "A debug adapter initiated event.",
-// "properties": {
-// "type": {
-// "type": "string",
-// "enum": [ "event" ]
-// },
-// "event": {
-// "type": "string",
-// "description": "Type of event."
-// },
-// "body": {
-// "type": [ "array", "boolean", "integer", "null", "number" , "object",
-// "string" ], "description": "Event-specific information."
-// }
-// },
-// "required": [ "type", "event" ]
-// }]
-// },
+/// A debug adapter initiated event.
struct Event {
+ /// Type of event.
std::string event;
+
+ /// Event-specific information.
std::optional<llvm::json::Value> rawBody;
};
llvm::json::Value toJSON(const Event &);
bool fromJSON(const llvm::json::Value &, Event &, llvm::json::Path);
-// "Response" : {
-// "allOf" : [
-// {"$ref" : "#/definitions/ProtocolMessage"}, {
-// "type" : "object",
-// "description" : "Response for a request.",
-// "properties" : {
-// "type" : {"type" : "string", "enum" : ["response"]},
-// "request_seq" : {
-// "type" : "integer",
-// "description" : "Sequence number of the corresponding request."
-// },
-// "success" : {
-// "type" : "boolean",
-// "description" :
-// "Outcome of the request.\nIf true, the request was successful "
-// "and the `body` attribute may contain the result of the "
-// "request.\nIf the value is false, the attribute `message` "
-// "contains the error in short form and the `body` may contain "
-// "additional information (see `ErrorResponse.body.error`)."
-// },
-// "command" :
-// {"type" : "string", "description" : "The command requested."},
-// "message" : {
-// "type" : "string",
-// "description" :
-// "Contains the raw error in short form if `success` is "
-// "false.\nThis raw error might be interpreted by the client and
-// " "is not shown in the UI.\nSome predefined values exist.",
-// "_enum" : [ "cancelled", "notStopped" ],
-// "enumDescriptions" : [
-// "the request was cancelled.",
-// "the request may be retried once the adapter is in a 'stopped'"
-// "state."
-// ]
-// },
-// "body" : {
-// "type" : [
-// "array", "boolean", "integer", "null", "number", "object",
-// "string"
-// ],
-// "description" : "Contains request result if success is true and "
-// "error details if success is false."
-// }
-// },
-// "required" : [ "type", "request_seq", "success", "command" ]
-// }
-// ]
-// }
+/// Response for a request.
struct Response {
enum class Message {
+ /// The request was cancelled
cancelled,
+ /// The request may be retried once the adapter is in a 'stopped' state
notStopped,
};
+ /// Sequence number of the corresponding request.
int64_t request_seq;
+
+ /// The command requested.
std::string command;
+
+ /// Outcome of the request. If true, the request was successful and the `body`
+ /// attribute may contain the result of the request. If the value is false,
+ /// the attribute `message` contains the error in short form and the `body`
+ /// may contain additional information (see `ErrorMessage`).
bool success;
+
// FIXME: Migrate usage of fallback string to ErrorMessage
+
+ /// Contains the raw error in short form if `success` is false. This raw error
+ /// might be interpreted by the client and is not shown in the UI. Some
+ /// predefined values exist.
std::optional<std::variant<Message, std::string>> message;
+
+ /// Contains request result if success is true and error details if success is
+ /// false.
std::optional<llvm::json::Value> rawBody;
};
bool fromJSON(const llvm::json::Value &, Response &, llvm::json::Path);
llvm::json::Value toJSON(const Response &);
-// "Message": {
-// "type": "object",
-// "description": "A structured message object. Used to return errors from
-// requests.", "properties": {
-// "id": {
-// "type": "integer",
-// "description": "Unique (within a debug adapter implementation)
-// identifier for the message. The purpose of these error IDs is to help
-// extension authors that have the requirement that every user visible
-// error message needs a corresponding error number, so that users or
-// customer support can find information about the specific error more
-// easily."
-// },
-// "format": {
-// "type": "string",
-// "description": "A format string for the message. Embedded variables
-// have the form `{name}`.\nIf variable name starts with an underscore
-// character, the variable does not contain user data (PII) and can be
-// safely used for telemetry purposes."
-// },
-// "variables": {
-// "type": "object",
-// "description": "An object used as a dictionary for looking up the
-// variables in the format string.", "additionalProperties": {
-// "type": "string",
-// "description": "All dictionary values must be strings."
-// }
-// },
-// "sendTelemetry": {
-// "type": "boolean",
-// "description": "If true send to telemetry."
-// },
-// "showUser": {
-// "type": "boolean",
-// "description": "If true show user."
-// },
-// "url": {
-// "type": "string",
-// "description": "A url where additional information about this message
-// can be found."
-// },
-// "urlLabel": {
-// "type": "string",
-// "description": "A label that is presented to the user as the UI for
-// opening the url."
-// }
-// },
-// "required": [ "id", "format" ]
-// },
+/// A structured message object. Used to return errors from requests.
struct ErrorMessage {
+ /// Unique (within a debug adapter implementation) identifier for the message.
+ /// The purpose of these error IDs is to help extension authors that have the
+ /// requirement that every user visible error message needs a corresponding
+ /// error number, so that users or customer support can find information about
+ /// the specific error more easily.
uint64_t id;
+
+ /// A format string for the message. Embedded variables have the form
+ /// `{name}`. If variable name starts with an underscore character, the
+ /// variable does not contain user data (PII) and can be safely used for
+ /// telemetry purposes.
std::string format;
+
+ /// An object used as a dictionary for looking up the variables in the format
+ /// string.
std::optional<std::map<std::string, std::string>> variables;
+
+ /// If true send to telemetry.
bool sendTelemetry;
+
+ /// If true show user.
bool showUser;
+
+ /// A url where additional information about this message can be found.
std::optional<std::string> url;
+
+ /// A label that is presented to the user as the UI for opening the url.
std::optional<std::string> urlLabel;
};
bool fromJSON(const llvm::json::Value &, ErrorMessage &, llvm::json::Path);
llvm::json::Value toJSON(const ErrorMessage &);
-// "ProtocolMessage": {
-// "type": "object",
-// "title": "Base Protocol",
-// "description": "Base class of requests, responses, and events.",
-// "properties": {
-// "seq": {
-// "type": "integer",
-// "description": "Sequence number of the message (also known as
-// message ID). The `seq` for the first message sent by a client or
-// debug adapter is 1, and for each subsequent message is 1 greater
-// than the previous message sent by that actor. `seq` can be used to
-// order requests, responses, and events, and to associate requests
-// with their corresponding responses. For protocol messages of type
-// `request` the sequence number can be used to cancel the request."
-// },
-// "type": {
-// "type": "string",
-// "description": "Message type.",
-// "_enum": [ "request", "response", "event" ]
-// }
-// },
-// "required": [ "seq", "type" ]
-// },
+/// An individual protocol message of requests, responses, and events.
using Message = std::variant<Request, Response, Event>;
bool fromJSON(const llvm::json::Value &, Message &, llvm::json::Path);
llvm::json::Value toJSON(const Message &);
+// MARK: Types
+
+/// A `Source` is a descriptor for source code. It is returned from the debug
+/// adapter as part of a `StackFrame` and it is used by clients when specifying
+/// breakpoints.
+struct Source {
+ enum class PresentationHint { normal, emphasize, deemphasize };
+
+ /// The short name of the source. Every source returned from the debug adapter
+ /// has a name. When sending a source to the debug adapter this name is
+ /// optional.
+ std::optional<std::string> name;
+
+ /// The path of the source to be shown in the UI. It is only used to locate
+ /// and load the content of the source if no `sourceReference` is specified
+ /// (or its value is 0).
+ std::optional<std::string> path;
+
+ /// If the value > 0 the contents of the source must be retrieved through the
+ /// `source` request (even if a path is specified). Since a `sourceReference`
+ /// is only valid for a session, it can not be used to persist a source. The
+ /// value should be less than or equal to 2147483647 (2^31-1).
+ std::optional<int64_t> sourceReference;
+
+ /// A hint for how to present the source in the UI. A value of `deemphasize`
+ /// can be used to indicate that the source is not available or that it is
+ /// skipped on stepping.
+ std::optional<PresentationHint> presentationHint;
+
+ // unsupported keys origin, sources, adapterData, checksums
----------------
vogelsgesang wrote:
```suggestion
// unsupported keys: origin, sources, adapterData, checksums
```
https://github.com/llvm/llvm-project/pull/130090
More information about the lldb-commits
mailing list