Data breakpoints proposal

[weinand]

Data breakpoints are only available if the supportsDataBreakpoints capability is true:

/** Information about the capabilities of a debug adapter. */
export interface Capabilities {

	// ...

	/** The debug adapter supports data breakpoints. */
	supportsDataBreakpoints?: boolean;
}

The dataBreakpointInfo request must be used to determine whether a data breakpoint is available for a specific variable or expression and returns a "data id" for it.

/** DataBreakpointInfo request; value of command field is 'dataBreakpointInfo'.
	Obtains information on a possible data breakpoint that could be set on an expression or variable.
*/
export interface DataBreakpointInfoRequest extends Request {
	// command: 'dataBreakpointInfo';
	arguments: DataBreakpointInfoArguments;
}

/** Arguments for 'dataBreakpointInfo' request. */
export interface DataBreakpointInfoArguments {
	/** Reference to the Variable container if the data breakpoint is requested for a child of the container. */
	variablesReference?: number;
	/** The name of the Variable's child to obtain data breakpoint information for. If variableReference isn’t provided, this can be an expression. */
	name: string;
}

/** Response to 'dataBreakpointInfo' request. */
export interface DataBreakpointInfoResponse extends Response {
	body: {
		/** An identifier for the data on which a data breakpoint can be registered with the setDataBreakpoints request or null if no data breakpoint is available. */
		dataId: string | null;
		/** UI string that describes on what data the breakpoint is set on or why a data breakpoint is not available. */
		description: string;
		/** Optional attribute listing the available access types for a potential data breakpoint. A UI frontend could surface this information. */
		accessTypes?: DataBreakpointAccessType[];
		/** Optional attribute indicating that a potential data breakpoint could be persisted across sessions. */
		canPersist?: boolean;
	};
}

The "data id" (and additional breakpoint options) can be used to create a DataBreakpoint:

/** Properties of a data breakpoint passed to the setDataBreakpoints request. */
export interface DataBreakpoint {
	/** An id representing the data. This id is returned from the dataBreakpointInfo request. */
	dataId: string;
	/** The access type of the data. */
	accessType?: DataBreakpointAccessType;
	/** An optional expression for conditional breakpoints. */
	condition?: string;
	/** An optional expression that controls how many hits of the breakpoint are ignored. The backend is expected to interpret the expression as needed. */
	hitCondition?: string;
}

/** This enumeration defines all possible access types for data breakpoints. */
export type DataBreakpointAccessType = 'read' | 'write' | 'readWrite';

Multiple data breakpoints are registered and deregistered for a debug session with the setDataBreakpoints request:

/** SetDataBreakpoints request; value of command field is 'setDataBreakpoints'.
	Replaces all existing data breakpoints with new data breakpoints.
	To clear all data breakpoints, specify an empty array.
	When a data breakpoint is hit, a 'stopped' event (with reason 'data breakpoint') is generated.
*/
export interface SetDataBreakpointsRequest extends Request {
	// command: 'setDataBreakpoints';
	arguments: SetDataBreakpointsArguments;
}

/** Arguments for 'setDataBreakpoints' request. */
export interface SetDataBreakpointsArguments {
	/** The contents of this array replaces all existing data breakpoints. An empty array clears all data breakpoints. */
	breakpoints: DataBreakpoint[];
}

/** Response to 'setDataBreakpoints' request.
	Returned is information about each breakpoint created by this request.
*/
export interface SetDataBreakpointsResponse extends Response {
	body: {
		/** Information about the data breakpoints. The array elements correspond to the elements of the input argument 'breakpoints' array. */
		breakpoints: Breakpoint[];
	};
}

And a new value dataBreakpoint for the VariablePresentationHint can be used to hint to the UI frontend that a data breakpoint is installed on a variable.

/** Optional properties of a variable that can be used to determine how to render the variable in the UI. */
export interface VariablePresentationHint {
	/** The kind of variable. Before introducing additional values, try to use the listed values.
		Values: 
                 // ...
		'dataBreakpoint': Indicates that a data breakpoint is registered for the object.
		etc.
	*/
	kind?: string;

	// ...
}

[weinand]

@gregg-miskelly @andrewcrawley @chuckries @DonJayamanne @pieandcakes

You can find a proposal for data breakpoints in the branch;

For your convenience I've added the corresponding TypeScript definitions above.

I'd appreciate any feedback.

[gregg-miskelly]

I made a fake PR into my own fork to make it easier to review: gregg-miskelly#1

Interfaces look good to me.

[weinand]

@gregg-miskelly @andrewcrawley @chuckries @DonJayamanne @pieandcakes
The data breakpoint protocol is now available in DAP 1.34 (and the corresponding node modules 1.34.0-pre.0).