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 ¶
- Variables
- func MissingAdapterError(requirements []AdapterRequirement) error
- func ResolveConfigurationPaths(workspace, projectDir string, fields []ConfigurationPath, ...) (map[string]any, error)
- func ResolveWorkspaceDirectory(workspace, value string) (string, error)
- type AdapterConnector
- type AdapterDescriptor
- type AdapterInfo
- type AdapterPlanPreparer
- type AdapterRequirement
- type Breakpoint
- type Capabilities
- type ConfigurationPath
- type Evaluation
- type FunctionBreakpoint
- type IOMode
- type Manager
- func (m *Manager) ActiveSession() *Session
- func (m *Manager) Adapters(ctx context.Context) ([]AdapterInfo, error)
- func (m *Manager) Breakpoints(path string) []SourceBreakpoint
- func (m *Manager) Close()
- func (m *Manager) InvalidateDetection()
- func (m *Manager) MissingRequirements(ctx context.Context) ([]AdapterRequirement, error)
- func (m *Manager) Session(id string) (*Session, error)
- func (m *Manager) SetAdapterConnector(connector AdapterConnector)
- func (m *Manager) SetAdapters(adapters ...AdapterDescriptor)
- func (m *Manager) SetBreakpoints(ctx context.Context, path string, values []SourceBreakpoint) ([]Breakpoint, error)
- func (m *Manager) SetCommandResolver(resolve func(string) string)
- func (m *Manager) SetTerminalLauncher(launcher TerminalLauncher)
- func (m *Manager) Start(ctx context.Context, options StartOptions) (*Session, error)
- func (m *Manager) Stop(ctx context.Context, id string) error
- func (m *Manager) WorkingDir() string
- type Plan
- type ProcessLaunch
- type Scope
- type Session
- func (session *Session) Close()
- func (session *Session) Continue(ctx context.Context, threadID int) error
- func (session *Session) Disconnect(ctx context.Context, terminate bool) error
- func (session *Session) Evaluate(ctx context.Context, expression string, frameID int) (Evaluation, error)
- func (session *Session) EvaluateContext(ctx context.Context, expression string, frameID int, evaluationContext string) (Evaluation, error)
- func (session *Session) ID() string
- func (session *Session) Next(ctx context.Context, threadID int) error
- func (session *Session) Output() string
- func (session *Session) Pause(ctx context.Context, threadID int) error
- func (session *Session) Scopes(ctx context.Context, frameID int) ([]Scope, error)
- func (session *Session) SetBreakpoints(ctx context.Context, path string, values []SourceBreakpoint) ([]Breakpoint, error)
- func (session *Session) SetFunctionBreakpoints(ctx context.Context, values []FunctionBreakpoint) ([]Breakpoint, error)
- func (session *Session) StackTrace(ctx context.Context, threadID, start, levels int) ([]StackFrame, int, error)
- func (session *Session) StateEpoch() uint64
- func (session *Session) Status() Status
- func (session *Session) StepBack(ctx context.Context, threadID int) error
- func (session *Session) StepIn(ctx context.Context, threadID int) error
- func (session *Session) StepOut(ctx context.Context, threadID int) error
- func (session *Session) Threads(ctx context.Context) ([]Thread, error)
- func (session *Session) Variables(ctx context.Context, reference, start, count int) ([]Variable, error)
- func (session *Session) WaitForStop(ctx context.Context, after uint64) (Status, bool)
- type Source
- type SourceBreakpoint
- type StackFrame
- type StartOptions
- type State
- type Status
- type Stop
- type TerminalLaunch
- type TerminalLauncher
- type TerminalProcess
- type TerminalStrategy
- type Thread
- type Transport
- type Variable
Constants ¶
This section is empty.
Variables ¶
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.
Types ¶
type AdapterConnector ¶
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
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
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 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 FunctionBreakpoint ¶
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.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
func NewManager ¶
func NewManager(root string, adapters ...AdapterDescriptor) *Manager
func (*Manager) ActiveSession ¶
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) 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) 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) 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
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) WorkingDir ¶
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 Session ¶
type Session struct {
// contains filtered or unexported fields
}
func (*Session) Disconnect ¶
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) 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) StateEpoch ¶
type SourceBreakpoint ¶
type StackFrame ¶
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 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 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 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 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"`
}