Skip to content

feat(shell): let shell() take an AbortSignal - #590

Merged
koral-- merged 3 commits into
masterfrom
feat/shell-abort-signal
Nov 20, 2026
Merged

koral-- merged 3 commits into
masterfrom
feat/shell-abort-signal

Conversation

@koral--

@koral-- koral-- commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Fixes #461

device.shell(command, { signal }) now takes an AbortSignal, 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

  • Already aborted signal: rejects with signal.reason without opening a connection.
  • Abort before ADB answers (connecting, or waiting for OKAY): goes through the same abortable() helper that waitBootComplete() and waitForDevice() use. The promise rejects with signal.reason and the connection is torn down.
  • Abort after shell() resolved (the command is running): the output stream is destroyed with signal.reason. It emits 'error' and then 'close', so readers such as adb.util.readAll(conn), pipeline() or for await reject with the reason. Closing the connection stops the command on the device.
  • No signal / no options: the call is the same as before. The second parameter is optional, so shell(command) keeps working.
  • The abort listener is removed as soon as the stream ends, finishes or closes, so one long-lived signal can be reused across many calls without collecting listeners. The returned stream has to be read to the end or destroyed, even for fire-and-forget commands. Otherwise its socket stays open, and with a signal the abort listener stays too. Unread streams already kept their socket open before this PR; the JSDoc and README now say so.
  • The error a mid-stream abort produces is the caller's own, so it doesn't fall through to the Client 'error' event. Connection forwards 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 no client.on('error') handler. Real socket errors are still forwarded, because the no-op listener is only added once the abort fires.

ShellOptions is exported next to WaitOptions. There are no Client-level shell helpers (shell exists only on DeviceClient), so nothing else needed the option.

Review follow-ups

  • shell() and waitBootComplete() used to hand transport() to abortable(), which therefore only owned the connection after the server answered host:transport. They now connect first and select the transport inside the abortable part. An abort while the server stalls on host:transport now closes the socket.
  • The abort teardown now destroys the socket through a new Connection.destroy(), instead of half-closing it with end().
  • waitBootComplete() and waitForDevice() now read options?.signal, like shell(), so passing null or a 2.x callback as the options no longer throws.
  • New tests:
    • a real-socket fake server that accepts but never answers, for shell(), waitBootComplete() and waitForDevice()
    • 25 shell() calls sharing one signal leave no listeners and no MaxListenersExceededWarning
    • the listener is released on 'end' and on 'finish'
    • null/callback options

Docs

  • JSDoc on shell() and ShellOptions.
  • README device.shell(command[, options]): documents signal and adds a short timeout example. It also drops the stale callback(err, conn) bullet from this section, since shell() hasn't taken a callback since 4.0.

Testing

  • npm run lint, npm run compile and npm test pass (333 passing).

  • New unit tests in test/adb/DeviceClient.mts:

    • aborted before start: rejects, transport() not called
    • aborted before OKAY: rejects with the reason, connection ended, no listener left
    • aborted mid-stream: readAll rejects with the reason, stream destroyed, no listener left
    • aborted mid-stream with nobody reading: no crash
    • never aborted: listener removed once the stream closes, output unchanged
    • no options: works as before

    I 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/:

    • a pre-aborted signal rejects
    • aborting sleep 202 mid-run makes readAll reject with the reason, and ps on the device shows the process gone within 1 s
    • while true; do echo …; sleep 1; done is gone after the abort too
    • AbortSignal.timeout(500) on sleep 30 with no reader closes the stream without crashing
    • a plain shell(['echo', 'hello']) is unchanged

    For a compound command like sleep N; echo done, sleep dies at once and the parent sh -c exits a few seconds later.

🤖 Generated with Claude Code

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>
@koral-- koral-- closed this Nov 20, 2026
@koral-- koral-- reopened this Nov 20, 2026
koral-- and others added 2 commits November 20, 2026 19:15
…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>
@koral--
koral-- merged commit 651f6b2 into master Nov 20, 2026
6 checks passed
@koral--
koral-- deleted the feat/shell-abort-signal branch November 20, 2026 18:17
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.

Allow aborting shell commands

1 participant