Skip to content

fix(js-debug): read the child session so Node.js commands stop hanging - #21

Open
Ayushsinha2004 wants to merge 1 commit into
AlmogBaku:masterfrom
Ayushsinha2004:fix/js-debug-child-session
Open

Ayushsinha2004 wants to merge 1 commit into
AlmogBaku:masterfrom
Ayushsinha2004:fix/js-debug-child-session

Conversation

@Ayushsinha2004

Copy link
Copy Markdown

Title: fix(js-debug): read the child session so Node.js commands stop hanging

Problem

With the js-debug backend, every execution command hangs: dap debug app.js --break app.js:3 never returns. On current master, the existing TestE2E_DebugNode times out whenever js-debug is installed:

panic: test timed out after 1m30s
    running tests:
        TestE2E_DebugNode (1m30s)

CI doesn't catch it because the workflow only installs debugpy, so the Node tests skip.

Cause

js-debug is multi-session. The connection dap launches on is only a session manager, and the debuggee runs in a child session on a second connection that js-debug requests through startDebugging. setupChildSession swaps d.client to the child but never starts a reader on it, while readLoop stays pinned to the parent connection. The child's StoppedEvent and TerminatedEvent never reach expectCh, so debug, step and continue block forever.

Fix (daemon.go)

  • readLoop now takes the connection and the channel it serves explicitly. setupChildSession starts a second loop on the child connection and hands it the same channel, so exactly one live loop closes it.
  • The parent loop keeps draining its socket so the adapter never blocks on a full send buffer. After the hand-off the parent only ever sends a duplicate terminated event (checked by logging), which is discarded. A further startDebugging on the parent (js-debug's child-process attach) is declined with an error response and a log line instead of being left unanswered; supporting more than one child session is out of scope here.
  • The startDebugging response is sent on the loop's own connection rather than d.client, which may already point at the child.

No behaviour change for debugpy, dlv or lldb-dap, which never hand off to a child session.

Tests

  • New TestReadLoop_ChildSessionHandoff (daemon_test.go) drives the daemon against a fake multi-session adapter: the parent connection sends startDebugging, the StoppedEvent arrives on a second connection, and the test checks it reaches the channel, that the acknowledgement went back on the parent, and that the channel closes exactly once when both connections end. It needs no js-debug, so it runs in CI; without the child reader it times out.
  • TestE2E_DebugNode: times out on master, passes with this change (~3.5s).
  • New TestE2E_DebugTypeScript debugs compiled JS with a breakpoint in the .ts source (committed greet.js + source map, no compiler needed). Times out on master, passes here.
  • Locally: go test ./..., gofmt, go vet and golangci-lint v2.11.1 are clean (macOS arm64, Go 1.26, Node 20, js-debug, debugpy); the Node and unit tests are also clean under -race over repeated runs. The dlv tests couldn't run here because macOS developer mode is disabled; they fail the same way on master in this environment.

Known limitation (not changed here)

A .ts breakpoint passed with --break at launch can be missed by a script that exits in under ~1s, because the program finishes before the breakpoint binds. Longer-running programs, and breakpoints added after --stop-on-entry, bind normally. Happy to look at this separately.

Possible follow-up: install js-debug in CI so the Node e2e tests run.

js-debug is multi-session: the connection dap launches on is only a session
manager, and the debuggee runs in a child session on a second connection.
setupChildSession swapped d.client to the child but never started a reader on
it, while readLoop stayed pinned to the parent. The child's StoppedEvent and
TerminatedEvent therefore never reached expectCh, and every execution command
(debug, step, continue) blocked forever.

- readLoop takes its connection and channel explicitly; setupChildSession
  starts a second loop on the child connection with the same channel, so
  exactly one live loop closes it.
- The parent keeps draining its socket after the hand-off (it only mirrors
  the child's terminated event) and declines a further startDebugging
  instead of leaving it unanswered.
- Answer startDebugging on the loop's own connection instead of d.client,
  which may already point at the child.

Adds TestReadLoop_ChildSessionHandoff, which drives the daemon against a
fake multi-session adapter and needs no js-debug, so it runs in CI where the
Node e2e tests skip. TestE2E_DebugNode timed out on master and now passes in
~3.5s. Adds TestE2E_DebugTypeScript (compiled JS + source map, breakpoint in
the .ts source).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@qodo-free-for-open-source-projects

Copy link
Copy Markdown

PR Summary by Qodo

Fix js-debug hangs by reading the child DAP session

🐞 Bug fix 🧪 Tests 🕐 20-40 Minutes

Grey Divider

AI Description

• Read js-debug child-session events so Node.js debug, step, and continue commands complete.
• Keep the parent connection draining and decline additional child-session requests.
• Add adapter-independent handoff coverage and a TypeScript source-map end-to-end test.
Diagram

sequenceDiagram
    participant CLI
    participant Daemon
    participant Parent as Parent adapter
    participant ParentReader as Parent reader
    participant Child as Child adapter
    participant ChildReader as Child reader
    participant Events as Expected events
    CLI->>Daemon: Debug command
    Daemon->>Parent: Launch session
    Parent->>ParentReader: startDebugging request
    ParentReader->>Parent: Success response
    ParentReader->>Child: Connect and configure
    ParentReader->>ChildReader: Hand off event channel
    Child->>ChildReader: Stopped or terminated
    ChildReader->>Events: Forward event
    Events->>Daemon: Deliver event
    Daemon->>CLI: Complete command
    Note over ParentReader,Parent: Parent remains draining after handoff
Loading
High-Level Assessment

Use the separate child reader and explicit channel handoff. A multiplexed multi-child session manager would add substantial coordination for child-process debugging that this PR does not aim to support.

Files changed (6) +276 / -23

Bug fix (1) +49 / -23
daemon.goHand event reading from the parent to the child session +49/-23

Hand event reading from the parent to the child session

• Starts a reader on js-debug’s child connection so its stop and termination events reach waiting commands. The parent reader continues draining, responds on its own connection, and declines further child-session requests; channel ownership prevents both readers from closing it.

daemon.go

Tests (5) +227 / -0
daemon_test.goCover multi-session reader handoff without js-debug +141/-0

Cover multi-session reader handoff without js-debug

• Adds a fake two-connection adapter test that checks parent acknowledgement, delivery of a child StoppedEvent, and channel closure after both connections end.

daemon_test.go

e2e_test.goExercise TypeScript debugging through source maps +60/-0

Exercise TypeScript debugging through source maps

• Adds an optional js-debug end-to-end test that stops on entry, sets a breakpoint in TypeScript source, checks the mapped stop and local value, then continues to termination.

e2e_test.go

greet.jsAdd compiled JavaScript debugging fixture +7/-0

Add compiled JavaScript debugging fixture

• Provides the executable greeting script and a reference to its source map, allowing the TypeScript end-to-end test to run without a compiler.

testdata/node/ts/greet.js

greet.tsAdd TypeScript breakpoint source fixture +12/-0

Add TypeScript breakpoint source fixture

• Provides the original typed greeting source, including the return line used for the mapped breakpoint.

testdata/node/ts/greet.ts

greet.js.mapMap the JavaScript fixture back to TypeScript +7/-0

Map the JavaScript fixture back to TypeScript

• Adds the committed source map and embedded TypeScript content used to verify source locations during debugging.

testdata/node/ts/greet.js.map

@qodo-free-for-open-source-projects

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (2) 📜 Skill insights (0)

Grey Divider


Action required

1. Child failure can crash the daemon 📘 Rule violation ☼ Reliability
Description
setupChildSession starts a child readLoop before the parent loop sets handedOff, while both
loops defer closing the same ch. If the child reaches EOF or fails during that window, it closes
ch; a subsequent parent event reaches ch <- msg and panics.
Code

daemon.go[1448]

+	go d.readLoop(childClient, ch)
Evidence
The child reader is launched at daemon.go:1448, while the parent sets handedOff only after
setupChildSession returns at daemon.go:324. Both readers have a deferred close(ch) at
daemon.go:266-270, and the parent still sends dispatchable messages to ch at
daemon.go:302-307, so a fast child EOF can close the channel before the parent handoff completes.

CLAUDE.md: Return Contextual Errors Instead of Panicking
daemon.go[266-270]
daemon.go[302-307]
daemon.go[320-324]
daemon.go[1445-1448]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

Issue description
The child reader starts before the parent reader marks the handoff complete, so both readers can close the shared channel. A fast child failure can close the channel first, after which the parent may send an event to the closed channel and panic.

Fix Focus Areas
- daemon.go[266-270]
- daemon.go[320-324]
- daemon.go[1445-1448]

Recommended Fix
Transfer channel-closure ownership atomically before starting the child reader, or centralize closure behind a synchronization primitive such as sync.Once. Ensure a child initialization failure leaves the parent as the sole channel owner and that no reader can send after closure.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools



Remediation recommended

2. Handoff has no isolated client test 📘 Rule violation ⚙ Maintainability
Description
TestReadLoop_ChildSessionHandoff drives a concrete DAPClient over TCP instead of mocking the DAP
client through an interface. The test therefore exercises the fake network adapter and reader
together, so client-level failures are not isolated at the unit-test boundary required for this
handoff.
Code

daemon_test.go[R580-587]

+	parentClient, err := newDAPClient(ln.Addr().String())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer parentClient.Close()
+	d.setClient(parentClient)
+	ch := make(chan godap.Message, 64)
+	go d.readLoop(parentClient, ch)
Evidence
The added test creates a TCP listener, constructs newDAPClient, and passes the concrete client
directly to readLoop; it does not use an interface-backed DAP client mock. The test consequently
covers the handoff through a network fake rather than the specified isolated unit-test setup.

CLAUDE.md: Cover Debugging Behavior at Unit, Integration, and End-to-End Levels
daemon_test.go[542-587]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

Issue description
The new child-session handoff test constructs a real network-backed `DAPClient` and fake TCP adapter rather than testing the reader against an interface-backed mock. This does not provide the isolated DAP-client unit coverage required for the new behavior.

Fix Focus Areas
- daemon_test.go[542-587]
- daemon.go[265-324]

Recommended Fix
Introduce or use a narrow DAP client interface for the reader's required operations, provide a mock implementation in the unit test, and keep the TCP fake as an integration test. Assert the parent acknowledgement, child event delivery, and single channel closure through the isolated mock test.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


Grey Divider

Context sources
Review mode: Auto: ⚖️ Balanced: Downgraded extended -> standard: change is below the extended eligibility bar (hunks 12/18, lines 292/200; both must reach the floor). Router rationale: Concurrency and session handoff logic span multiple paths with subtle lifecycle risks.

Grey Divider

Tip of the day
💡 Did you know, you can show, collapse, or hide each part of a finding: code, evidence, and all

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

Comment thread daemon.go
// Without a loop of its own, the child's StoppedEvent/TerminatedEvent would
// never reach ch and every execution command would block forever.
d.setClient(childClient)
go d.readLoop(childClient, ch)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

1. Child failure can crash the daemon 📘 Rule violation ☼ Reliability

setupChildSession starts a child readLoop before the parent loop sets handedOff, while both
loops defer closing the same ch. If the child reaches EOF or fails during that window, it closes
ch; a subsequent parent event reaches ch <- msg and panics.
Agent Prompt
Issue description
The child reader starts before the parent reader marks the handoff complete, so both readers can close the shared channel. A fast child failure can close the channel first, after which the parent may send an event to the closed channel and panic.

Fix Focus Areas
- daemon.go[266-270]
- daemon.go[320-324]
- daemon.go[1445-1448]

Recommended Fix
Transfer channel-closure ownership atomically before starting the child reader, or centralize closure behind a synchronization primitive such as sync.Once. Ensure a child initialization failure leaves the parent as the sole channel owner and that no reader can send after closure.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Comment thread daemon_test.go
Comment on lines +580 to +587
parentClient, err := newDAPClient(ln.Addr().String())
if err != nil {
t.Fatal(err)
}
defer parentClient.Close()
d.setClient(parentClient)
ch := make(chan godap.Message, 64)
go d.readLoop(parentClient, ch)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remediation recommended

2. Handoff has no isolated client test 📘 Rule violation ⚙ Maintainability

TestReadLoop_ChildSessionHandoff drives a concrete DAPClient over TCP instead of mocking the DAP
client through an interface. The test therefore exercises the fake network adapter and reader
together, so client-level failures are not isolated at the unit-test boundary required for this
handoff.
Agent Prompt
Issue description
The new child-session handoff test constructs a real network-backed `DAPClient` and fake TCP adapter rather than testing the reader against an interface-backed mock. This does not provide the isolated DAP-client unit coverage required for the new behavior.

Fix Focus Areas
- daemon_test.go[542-587]
- daemon.go[265-324]

Recommended Fix
Introduce or use a narrow DAP client interface for the reader's required operations, provide a mock implementation in the unit test, and keep the TCP fake as an integration test. Assert the parent acknowledgement, child event delivery, and single channel closure through the isolated mock test.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant