dap

package
v0.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 2, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package dap provides workspace-scoped Debug Adapter Protocol sessions.

Adapter-specific launch semantics stay outside this package. This package discovers adapter processes, frames messages, and manages generic protocol state.

Index

Constants

This section is empty.

Variables

View Source
var ErrActiveSession = errors.New("a debug session is already active")

Functions

func MissingAdapterError added in v0.15.0

func MissingAdapterError(requirements []AdapterRequirement) error

func ResolveConfigurationPaths

func ResolveConfigurationPaths(workspace, projectDir string, fields []ConfigurationPath, configuration map[string]any) (map[string]any, error)

ResolveConfigurationPaths validates and resolves the path fields declared by an adapter descriptor. All other adapter configuration remains opaque.

func ResolveWorkspaceDirectory

func ResolveWorkspaceDirectory(workspace, value string) (string, error)

Types

type AdapterConnector

type AdapterConnector interface {
	ConnectAdapter(context.Context, Plan) (io.ReadWriteCloser, error)
}

type AdapterDescriptor

type AdapterDescriptor struct {
	Name               string
	Language           string
	AdapterID          string
	Command            string
	Args               []string
	Transport          Transport
	ReadyPrefix        string
	Markers            []string
	SourceExtensions   []string
	Defaults           map[string]any
	ConfigurationPaths []ConfigurationPath
	IOConfigKey        string
	IOValues           map[IOMode]string
	TargetConfigKey    string
	TerminalStrategy   TerminalStrategy
}

AdapterDescriptor describes how to start one debug adapter process. Command is resolved to an executable before a Plan reaches the session layer.

type AdapterInfo

type AdapterInfo struct {
	Name               string              `json:"name"`
	Language           string              `json:"language"`
	Command            string              `json:"command"`
	Projects           []string            `json:"projects"`
	ConfigurationPaths []ConfigurationPath `json:"configuration_paths,omitempty"`
	IOConfigKey        string              `json:"io_config_key,omitempty"`
	TerminalStrategy   TerminalStrategy    `json:"terminal_strategy,omitempty"`
}

AdapterInfo is the detection result exposed to callers and launch planners.

type AdapterPlanPreparer added in v0.15.3

type AdapterPlanPreparer interface {
	PrepareAdapter(context.Context, Plan) (Plan, error)
}

AdapterPlanPreparer optionally enriches a resolved plan before the adapter transport starts. It lets a host-created adapter obtain launch details from its owning service without putting language-specific behavior in Manager.

type AdapterRequirement added in v0.15.0

type AdapterRequirement struct {
	Name     string
	Language string
	Commands []string
	Projects []string
}

AdapterRequirement describes the commands capable of serving one detected debugger integration, in preference order.

func DetectRequirements added in v0.15.0

func DetectRequirements(ctx context.Context, workspace string, adapters []AdapterDescriptor) ([]AdapterRequirement, error)

DetectRequirements reports adapter needs independently of whether the adapter executable is installed.

type Breakpoint

type Breakpoint struct {
	ID       int    `json:"id,omitempty"`
	Verified bool   `json:"verified"`
	Message  string `json:"message,omitempty"`
	Line     int    `json:"line,omitempty"`
	Column   int    `json:"column,omitempty"`
}

type Capabilities

type Capabilities struct {
	SupportsStepBack bool `json:"supports_step_back"`
}

type ConfigurationPath

type ConfigurationPath struct {
	Key          string `json:"key"`
	Directory    bool   `json:"directory,omitempty"`
	AllowMissing bool   `json:"allow_missing,omitempty"`
}

ConfigurationPath identifies an adapter-owned configuration field whose value is a concrete path in the workspace. The generic launcher resolves relative values from ProjectDir before handing the configuration to the adapter. Fields that are commands, module names, or other opaque strings are deliberately not listed.

type Evaluation

type Evaluation struct {
	Result             string `json:"result"`
	Type               string `json:"type,omitempty"`
	VariablesReference int    `json:"variables_reference,omitempty"`
	NamedVariables     int    `json:"named_variables,omitempty"`
	IndexedVariables   int    `json:"indexed_variables,omitempty"`
}

type FunctionBreakpoint

type FunctionBreakpoint struct {
	Name         string `json:"name"`
	Condition    string `json:"condition,omitempty"`
	HitCondition string `json:"hit_condition,omitempty"`
}

type IOMode

type IOMode string

IOMode controls where the debuggee reads input and writes program output. Adapter-specific launch values are mapped at the descriptor boundary.

const (
	IOOutput   IOMode = "output"
	IOTerminal IOMode = "terminal"
)

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

func NewManager

func NewManager(root string, adapters ...AdapterDescriptor) *Manager

func (*Manager) ActiveSession

func (m *Manager) ActiveSession() *Session

ActiveSession returns the most recently started session, if any. The returned Session owns its own synchronization and remains valid until the manager is closed.

func (*Manager) Adapters

func (m *Manager) Adapters(ctx context.Context) ([]AdapterInfo, error)

func (*Manager) Breakpoints

func (m *Manager) Breakpoints(path string) []SourceBreakpoint

Breakpoints returns the editor-owned breakpoint set. These breakpoints are applied automatically to subsequently launched sessions.

func (*Manager) Close

func (m *Manager) Close()

func (*Manager) InvalidateDetection added in v0.15.0

func (m *Manager) InvalidateDetection()

InvalidateDetection makes newly installed or updated adapters visible on the next lookup without waiting for the detection cache TTL.

func (*Manager) MissingRequirements added in v0.15.0

func (m *Manager) MissingRequirements(ctx context.Context) ([]AdapterRequirement, error)

MissingRequirements reports debugger projects whose adapter command could not be resolved. It shares the normal discovery cache and workspace scan.

func (*Manager) Session

func (m *Manager) Session(id string) (*Session, error)

func (*Manager) SetAdapterConnector

func (m *Manager) SetAdapterConnector(connector AdapterConnector)

SetAdapterConnector installs the host bridge used by adapters such as Java, whose DAP socket is created by a language server rather than an executable.

func (*Manager) SetAdapters added in v0.15.0

func (m *Manager) SetAdapters(adapters ...AdapterDescriptor)

SetAdapters replaces descriptors used by future discovery and sessions. An already-running session is unaffected.

func (*Manager) SetBreakpoints

func (m *Manager) SetBreakpoints(ctx context.Context, path string, values []SourceBreakpoint) ([]Breakpoint, error)

func (*Manager) SetCommandResolver added in v0.15.0

func (m *Manager) SetCommandResolver(resolve func(string) string)

SetCommandResolver adds an application-managed candidate after project discovery and before the standard system fallback.

func (*Manager) SetTerminalLauncher

func (m *Manager) SetTerminalLauncher(launcher TerminalLauncher)

SetTerminalLauncher connects the protocol client to the editor's PTY host. Passing nil disables terminal launches while leaving captured-output sessions available.

func (*Manager) Start

func (m *Manager) Start(ctx context.Context, options StartOptions) (*Session, error)

func (*Manager) Stop

func (m *Manager) Stop(ctx context.Context, id string) error

func (*Manager) WorkingDir

func (m *Manager) WorkingDir() string

type Plan

type Plan struct {
	Adapter    AdapterDescriptor
	ProjectDir string
	Target     string
	Mode       string
	Request    string
	IO         IOMode
	Arguments  map[string]any
	PreLaunch  *ProcessLaunch
}

Plan is the resolved, internal form used to start an adapter process.

type ProcessLaunch added in v0.15.0

type ProcessLaunch struct {
	Title       string   `json:"title"`
	Command     string   `json:"command"`
	Args        []string `json:"args,omitempty"`
	ReadyURL    string   `json:"ready_url,omitempty"`
	WaitForExit bool     `json:"wait_for_exit,omitempty"`
}

ProcessLaunch is a process owned by the debug session and started before the adapter. ReadyURL, when set, must respond before the adapter launches. WaitForExit instead runs the process to successful completion, such as a build step.

type Scope

type Scope struct {
	Name               string `json:"name"`
	VariablesReference int    `json:"variables_reference"`
	NamedVariables     int    `json:"named_variables,omitempty"`
	IndexedVariables   int    `json:"indexed_variables,omitempty"`
	Expensive          bool   `json:"expensive,omitempty"`
}

type Session

type Session struct {
	// contains filtered or unexported fields
}

func (*Session) Close

func (session *Session) Close()

func (*Session) Continue

func (session *Session) Continue(ctx context.Context, threadID int) error

func (*Session) Disconnect

func (session *Session) Disconnect(ctx context.Context, terminate bool) error

func (*Session) Evaluate

func (session *Session) Evaluate(ctx context.Context, expression string, frameID int) (Evaluation, error)

func (*Session) EvaluateContext

func (session *Session) EvaluateContext(ctx context.Context, expression string, frameID int, evaluationContext string) (Evaluation, error)

EvaluateContext evaluates an expression using a standard DAP context such as "repl", "hover", or "watch". Adapters may format or restrict results differently for each context.

func (*Session) ID

func (session *Session) ID() string

func (*Session) Next

func (session *Session) Next(ctx context.Context, threadID int) error

func (*Session) Output

func (session *Session) Output() string

func (*Session) Pause

func (session *Session) Pause(ctx context.Context, threadID int) error

func (*Session) Scopes

func (session *Session) Scopes(ctx context.Context, frameID int) ([]Scope, error)

func (*Session) SetBreakpoints

func (session *Session) SetBreakpoints(ctx context.Context, path string, values []SourceBreakpoint) ([]Breakpoint, error)

func (*Session) SetFunctionBreakpoints

func (session *Session) SetFunctionBreakpoints(ctx context.Context, values []FunctionBreakpoint) ([]Breakpoint, error)

func (*Session) StackTrace

func (session *Session) StackTrace(ctx context.Context, threadID, start, levels int) ([]StackFrame, int, error)

func (*Session) StateEpoch

func (session *Session) StateEpoch() uint64

func (*Session) Status

func (session *Session) Status() Status

func (*Session) StepBack

func (session *Session) StepBack(ctx context.Context, threadID int) error

func (*Session) StepIn

func (session *Session) StepIn(ctx context.Context, threadID int) error

func (*Session) StepOut

func (session *Session) StepOut(ctx context.Context, threadID int) error

func (*Session) Threads

func (session *Session) Threads(ctx context.Context) ([]Thread, error)

func (*Session) Variables

func (session *Session) Variables(ctx context.Context, reference, start, count int) ([]Variable, error)

func (*Session) WaitForStop

func (session *Session) WaitForStop(ctx context.Context, after uint64) (Status, bool)

type Source

type Source struct {
	Name string `json:"name,omitempty"`
	Path string `json:"path,omitempty"`
}

type SourceBreakpoint

type SourceBreakpoint struct {
	Line         int    `json:"line"`
	Column       int    `json:"column,omitempty"`
	Condition    string `json:"condition,omitempty"`
	HitCondition string `json:"hit_condition,omitempty"`
	LogMessage   string `json:"log_message,omitempty"`
}

type StackFrame

type StackFrame struct {
	ID     int     `json:"id"`
	Name   string  `json:"name"`
	Source *Source `json:"source,omitempty"`
	Line   int     `json:"line"`
	Column int     `json:"column"`
}

type StartOptions

type StartOptions struct {
	Adapter             string
	ProjectDir          string
	Request             string
	Configuration       map[string]any
	Breakpoints         map[string][]SourceBreakpoint
	FunctionBreakpoints []FunctionBreakpoint
	IO                  IOMode
	PreLaunch           *ProcessLaunch
	// contains filtered or unexported fields
}

StartOptions carries a reviewed DAP launch or attach configuration. Configuration is intentionally open-ended because DAP delegates these arguments to each adapter.

type State

type State string
const (
	StateStarting    State = "starting"
	StateConfiguring State = "configuring"
	StateRunning     State = "running"
	StateStopped     State = "stopped"
	StateTerminated  State = "terminated"
)

type Status

type Status struct {
	SessionID    string       `json:"session_id"`
	Adapter      string       `json:"adapter"`
	Language     string       `json:"language"`
	Target       string       `json:"target,omitempty"`
	Mode         string       `json:"mode,omitempty"`
	Request      string       `json:"request"`
	IO           IOMode       `json:"io"`
	TerminalID   string       `json:"terminal_id,omitempty"`
	Capabilities Capabilities `json:"capabilities"`
	StateVersion uint64       `json:"state_version"`
	State        State        `json:"state"`
	Stop         *Stop        `json:"stop,omitempty"`
	ExitCode     *int         `json:"exit_code,omitempty"`
	StartedAt    time.Time    `json:"started_at"`
	Error        string       `json:"error,omitempty"`
}

type Stop

type Stop struct {
	Reason            string `json:"reason"`
	Description       string `json:"description,omitempty"`
	ThreadID          int    `json:"thread_id,omitempty"`
	AllThreadsStopped bool   `json:"all_threads_stopped,omitempty"`
	HitBreakpointIDs  []int  `json:"hit_breakpoint_ids,omitempty"`
}

type TerminalLaunch

type TerminalLaunch struct {
	Title string
	Path  string
	Args  []string
	Dir   string
	Env   map[string]*string
}

TerminalLaunch is a direct, argument-preserving command requested by the DAP host or by an adapter through the standard runInTerminal request.

type TerminalLauncher

type TerminalLauncher interface {
	LaunchTerminal(context.Context, TerminalLaunch) (TerminalProcess, error)
}

type TerminalProcess

type TerminalProcess interface {
	io.Closer
	ID() string
	ProcessID() int
	Done() <-chan struct{}
	Subscribe() (snapshot []byte, output <-chan []byte, cancel func())
}

type TerminalStrategy

type TerminalStrategy string

TerminalStrategy declares how an adapter integrates with an interactive terminal. It is adapter metadata, not language-specific launcher logic.

const (
	TerminalUnsupported    TerminalStrategy = ""
	TerminalAdapterProcess TerminalStrategy = "adapterProcess"
	TerminalRunInTerminal  TerminalStrategy = "runInTerminal"
)

type Thread

type Thread struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

type Transport

type Transport string
const (
	TransportStdio   Transport = "stdio"
	TransportTCP     Transport = "tcp"
	TransportConnect Transport = "connect"
)

type Variable

type Variable struct {
	Name               string `json:"name"`
	Value              string `json:"value"`
	Type               string `json:"type,omitempty"`
	EvaluateName       string `json:"evaluate_name,omitempty"`
	VariablesReference int    `json:"variables_reference,omitempty"`
	NamedVariables     int    `json:"named_variables,omitempty"`
	IndexedVariables   int    `json:"indexed_variables,omitempty"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL