Repository navigation
feat(shell): let shell() take an AbortSignal - #590
Merged
Merged
Conversation
device.shell(command, { signal }) aborts the command. Before shell()
resolves, the abort goes through the same abortable() path as the wait
methods: the promise rejects with signal.reason and the connection is
closed, and an already aborted signal rejects without connecting.
After shell() resolves, the abort destroys the output stream with
signal.reason, so readers such as adb.util.readAll() reject with it,
and closing the connection stops the command on the device. The abort
listener is removed once the stream closes, so a signal reused across
calls doesn't collect listeners. Calls without options are unchanged.
Fixes #461
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Karol Wrótniak <karol.wrotniak@droidsonroids.pl>
…s early Review fixes for the AbortSignal support: - shell() and waitBootComplete() passed transport() to abortable(), so abortable() only got the connection once the server had answered host:transport. A server that stalled before answering kept the socket open after an abort. They now pass the bare connection() and select the transport inside run, so an abort can close the socket at any point after the TCP connect. - The abort teardown destroys the socket (new Connection.destroy()) instead of half-closing it with end(), which a remote that never closes its side would ignore. - shell()'s abort listener is released on 'end', 'finish' or 'close', whichever comes first, instead of only on 'close'. A half-open socket that has ended doesn't keep it any more, so a signal shared by many calls doesn't collect listeners. - waitBootComplete() and waitForDevice() read options?.signal, like shell(), so a null or a 2.x callback as options no longer throws. Signed-off-by: Karol Wrótniak <karol.wrotniak@droidsonroids.pl> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Say that the stream shell() resolves with must be read to the end or destroyed, or its socket (and with a signal, the abort listener) stays open, as the socket already did before signal existed. - The timeout example no longer reads err.name off an unknown catch variable. - List shell()'s signal in the 4.x cancellation notes. Signed-off-by: Karol Wrótniak <karol.wrotniak@droidsonroids.pl> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #461
device.shell(command, { signal })now takes anAbortSignal, along the lines @pimterry proposed in #461 back in 2023 (and offered to implement; sorry that offer never got a reply). Thanks for the idea and the API sketch, which this follows.Behaviour
signal.reasonwithout opening a connection.OKAY): goes through the sameabortable()helper thatwaitBootComplete()andwaitForDevice()use. The promise rejects withsignal.reasonand the connection is torn down.shell()resolved (the command is running): the output stream is destroyed withsignal.reason. It emits'error'and then'close', so readers such asadb.util.readAll(conn),pipeline()orfor awaitreject with the reason. Closing the connection stops the command on the device.shell(command)keeps working.Client'error'event.Connectionforwards socket errors there when nobody else listens on the socket, and without this an abort with no reader attached would crash a process that has noclient.on('error')handler. Real socket errors are still forwarded, because the no-op listener is only added once the abort fires.ShellOptionsis exported next toWaitOptions. There are no Client-level shell helpers (shell exists only onDeviceClient), so nothing else needed the option.Review follow-ups
shell()andwaitBootComplete()used to handtransport()toabortable(), which therefore only owned the connection after the server answeredhost:transport. They now connect first and select the transport inside the abortable part. An abort while the server stalls onhost:transportnow closes the socket.Connection.destroy(), instead of half-closing it withend().waitBootComplete()andwaitForDevice()now readoptions?.signal, likeshell(), so passingnullor a 2.x callback as the options no longer throws.shell(),waitBootComplete()andwaitForDevice()shell()calls sharing one signal leave no listeners and noMaxListenersExceededWarning'end'and on'finish'null/callback optionsDocs
shell()andShellOptions.device.shell(command[, options]): documentssignaland adds a short timeout example. It also drops the stalecallback(err, conn)bullet from this section, sinceshell()hasn't taken a callback since 4.0.Testing
npm run lint,npm run compileandnpm testpass (333 passing).New unit tests in
test/adb/DeviceClient.mts:transport()not calledOKAY: rejects with the reason, connection ended, no listener leftreadAllrejects with the reason, stream destroyed, no listener leftI checked that the tests fail when the stream isn't destroyed or the error isn't swallowed.
Manual check against a local emulator (API 36), using the built
dist/:sleep 202mid-run makesreadAllreject with the reason, andpson the device shows the process gone within 1 swhile true; do echo …; sleep 1; doneis gone after the abort tooAbortSignal.timeout(500)onsleep 30with no reader closes the stream without crashingshell(['echo', 'hello'])is unchangedFor a compound command like
sleep N; echo done,sleepdies at once and the parentsh -cexits a few seconds later.🤖 Generated with Claude Code