dap: implement variable references

Implement variable references to inspect the state of a stack frame.

Variable reference ids are composed of two sections. A thread mask that
is the first 8 bytes and the remainder is an increasing number that gets
reset each time a thread is resumed. This allows the adapter to know
which thread to delegate the variables request to and allows the
variable references to still remain confined to each thread. An int32 is
used for this because variable references need to be in the range of
(0, 2^32).

At the moment, only the platform variables and some of the exec
operations for an operation. These are labeled as "arguments" to the
stack frame.

Signed-off-by: Jonathan A. Sternberg <[email protected]>

Author: jsternberg

dap/adapter.go

@@ -216,6 +216,7 @@ func (d *Adapter[C]) newThread(ctx Context, name string) (t *thread) {
 		sourceMap:     &d.sourceMap,
 		breakpointMap: d.breakpointMap,
 		idPool:        d.idPool,
+		variables:     newVariableReferences(),
 	}
 	d.threads[t.id] = t
 	d.nextThreadID++
@@ -240,6 +241,11 @@ func (d *Adapter[C]) getThread(id int) (t *thread) {
 
 func (d *Adapter[C]) deleteThread(ctx Context, t *thread) {
 	d.threadsMu.Lock()
+	if t := d.threads[t.id]; t != nil {
+		if t.variables != nil {
+			t.variables.Reset()
+		}
+	}
 	delete(d.threads, t.id)
 	d.threadsMu.Unlock()
 
@@ -252,6 +258,18 @@ func (d *Adapter[C]) deleteThread(ctx Context, t *thread) {
 	}
 }
 
+func (d *Adapter[T]) getThreadByFrameID(id int) (t *thread) {
+	d.threadsMu.RLock()
+	defer d.threadsMu.RUnlock()
+
+	for _, t := range d.threads {
+		if t.hasFrame(id) {
+			return t
+		}
+	}
+	return nil
+}
+
 type evaluateRequest struct {
 	name   string
 	c      gateway.Client
@@ -330,6 +348,35 @@ func (d *Adapter[C]) StackTrace(c Context, req *dap.StackTraceRequest, resp *dap
 	return nil
 }
 
+func (d *Adapter[C]) Scopes(c Context, req *dap.ScopesRequest, resp *dap.ScopesResponse) error {
+	t := d.getThreadByFrameID(req.Arguments.FrameId)
+	if t == nil {
+		return errors.Errorf("no such frame id: %d", req.Arguments.FrameId)
+	}
+
+	resp.Body.Scopes = t.Scopes(req.Arguments.FrameId)
+	for i, s := range resp.Body.Scopes {
+		resp.Body.Scopes[i].VariablesReference = (t.id << 24) | s.VariablesReference
+	}
+	return nil
+}
+
+func (d *Adapter[C]) Variables(c Context, req *dap.VariablesRequest, resp *dap.VariablesResponse) error {
+	tid := req.Arguments.VariablesReference >> 24
+
+	t := d.getThread(tid)
+	if t == nil {
+		return errors.Errorf("no such thread: %d", tid)
+	}
+
+	varRef := req.Arguments.VariablesReference & ((1 << 24) - 1)
+	resp.Body.Variables = t.Variables(varRef)
+	for i, ref := range resp.Body.Variables {
+		resp.Body.Variables[i].VariablesReference = (tid << 24) | ref.VariablesReference
+	}
+	return nil
+}
+
 func (d *Adapter[C]) Source(c Context, req *dap.SourceRequest, resp *dap.SourceResponse) error {
 	fname := req.Arguments.Source.Path
 
@@ -378,6 +425,8 @@ func (d *Adapter[C]) dapHandler() Handler {
 		Disconnect:        d.Disconnect,
 		Threads:           d.Threads,
 		StackTrace:        d.StackTrace,
+		Scopes:            d.Scopes,
+		Variables:         d.Variables,
 		Source:            d.Source,
 	}
 }

dap/handler.go

@@ -55,6 +55,8 @@ type Handler struct {
 	Restart           HandlerFunc[*dap.RestartRequest, *dap.RestartResponse]
 	Threads           HandlerFunc[*dap.ThreadsRequest, *dap.ThreadsResponse]
 	StackTrace        HandlerFunc[*dap.StackTraceRequest, *dap.StackTraceResponse]
+	Scopes            HandlerFunc[*dap.ScopesRequest, *dap.ScopesResponse]
+	Variables         HandlerFunc[*dap.VariablesRequest, *dap.VariablesResponse]
 	Evaluate          HandlerFunc[*dap.EvaluateRequest, *dap.EvaluateResponse]
 	Source            HandlerFunc[*dap.SourceRequest, *dap.SourceResponse]
 }

dap/server.go

@@ -125,6 +125,10 @@ func (s *Server) handleMessage(c Context, m dap.Message) (dap.ResponseMessage, e
 		return s.h.Threads.Do(c, req)
 	case *dap.StackTraceRequest:
 		return s.h.StackTrace.Do(c, req)
+	case *dap.ScopesRequest:
+		return s.h.Scopes.Do(c, req)
+	case *dap.VariablesRequest:
+		return s.h.Variables.Do(c, req)
 	case *dap.EvaluateRequest:
 		return s.h.Evaluate.Do(c, req)
 	case *dap.SourceRequest:

dap/thread.go

@@ -26,6 +26,7 @@ type thread struct {
 	idPool        *idPool
 	sourceMap     *sourceMap
 	breakpointMap *breakpointMap
+	variables     *variableReferences
 
 	// Inputs to the evaluate call.
 	c          gateway.Client
@@ -48,11 +49,10 @@ type thread struct {
 	mu     sync.Mutex
 
 	// Attributes set when a thread is paused.
-	rCtx   *build.ResultHandle
-	curPos digest.Digest
-
-	// Lazy attributes that are set when a thread is paused.
-	stackTrace []dap.StackFrame
+	rCtx       *build.ResultHandle
+	curPos     digest.Digest
+	stackTrace []int32
+	frames     map[int32]*frame
 }
 
 type region struct {
@@ -154,6 +154,7 @@ func (t *thread) pause(c Context, err error, event dap.StoppedEventBody) <-chan
 			}
 		}
 	}
+	t.collectStackTrace()
 
 	event.ThreadId = t.id
 	c.C() <- &dap.StoppedEvent{
@@ -178,18 +179,7 @@ func (t *thread) resume(step stepType) {
 	if t.paused == nil {
 		return
 	}
-
-	if t.rCtx != nil {
-		t.rCtx.Done()
-		t.rCtx = nil
-	}
-
-	if t.stackTrace != nil {
-		for _, frame := range t.stackTrace {
-			t.idPool.Put(int64(frame.Id))
-		}
-		t.stackTrace = nil
-	}
+	t.releaseState()
 
 	t.paused <- step
 	close(t.paused)
@@ -207,10 +197,23 @@ func (t *thread) StackTrace() []dap.StackFrame {
 		return []dap.StackFrame{}
 	}
 
-	if t.stackTrace == nil {
-		t.stackTrace = t.makeStackTrace()
+	frames := make([]dap.StackFrame, len(t.stackTrace))
+	for i, id := range t.stackTrace {
+		frames[i] = t.frames[id].StackFrame
 	}
-	return t.stackTrace
+	return frames
+}
+
+func (t *thread) Scopes(frameID int) []dap.Scope {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	frame := t.frames[int32(frameID)]
+	return frame.Scopes()
+}
+
+func (t *thread) Variables(id int) []dap.Variable {
+	return t.variables.Get(id)
 }
 
 func (t *thread) getLLBState(ctx Context) error {
@@ -502,15 +505,16 @@ func (t *thread) solve(ctx context.Context, target digest.Digest) (gateway.Refer
 	return res.SingleRef()
 }
 
-func (t *thread) newStackFrame() dap.StackFrame {
-	return dap.StackFrame{
-		Id: int(t.idPool.Get()),
+func (t *thread) releaseState() {
+	if t.rCtx != nil {
+		t.rCtx.Done()
+		t.rCtx = nil
 	}
+	t.stackTrace = nil
+	t.frames = nil
 }
 
-func (t *thread) makeStackTrace() []dap.StackFrame {
-	var frames []dap.StackFrame
-
+func (t *thread) collectStackTrace() {
 	region := t.regionsByDigest[t.curPos]
 	r := t.regions[region]
 
@@ -519,45 +523,38 @@ func (t *thread) makeStackTrace() []dap.StackFrame {
 		digests = digests[:index+1]
 	}
 
+	t.frames = make(map[int32]*frame)
 	for i := len(digests) - 1; i >= 0; i-- {
 		dgst := digests[i]
 
-		frame := t.newStackFrame()
+		frame := &frame{}
+		frame.Id = int(t.idPool.Get())
+
 		if meta, ok := t.def.Metadata[dgst]; ok {
-			fillStackFrameMetadata(&frame, meta)
+			frame.setNameFromMeta(meta)
 		}
 		if loc, ok := t.def.Source.Locations[string(dgst)]; ok {
-			t.fillStackFrameLocation(&frame, loc)
+			frame.fillLocation(t.def, loc, t.sourcePath)
 		}
-		frames = append(frames, frame)
-	}
-	return frames
-}
 
-func fillStackFrameMetadata(frame *dap.StackFrame, meta llb.OpMetadata) {
-	if name, ok := meta.Description["llb.customname"]; ok {
-		frame.Name = name
-	} else if cmd, ok := meta.Description["com.docker.dockerfile.v1.command"]; ok {
-		frame.Name = cmd
+		if op := t.ops[dgst]; op != nil {
+			frame.fillVarsFromOp(op, t.variables)
+		}
+		t.stackTrace = append(t.stackTrace, int32(frame.Id))
+		t.frames[int32(frame.Id)] = frame
 	}
-	// TODO: should we infer the name from somewhere else?
 }
 
-func (t *thread) fillStackFrameLocation(frame *dap.StackFrame, loc *pb.Locations) {
-	for _, l := range loc.Locations {
-		for _, r := range l.Ranges {
-			frame.Line = int(r.Start.Line)
-			frame.Column = int(r.Start.Character)
-			frame.EndLine = int(r.End.Line)
-			frame.EndColumn = int(r.End.Character)
-
-			info := t.def.Source.Infos[l.SourceIndex]
-			frame.Source = &dap.Source{
-				Path: filepath.Join(t.sourcePath, info.Filename),
-			}
-			return
-		}
+func (t *thread) hasFrame(id int) bool {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	if t.paused == nil {
+		return false
 	}
+
+	_, ok := t.frames[int32(id)]
+	return ok
 }
 
 func pop[S ~[]E, E any](s *S) E {