niim - Node-Inspect IMproved
npm install --global niimAbout
This project is a fork of the node-inspect project. The goal is simple: to scratch my own itches with respect to debugging command-line apps on NodeJS, especially logged in via ssh.
Specifically, my work on DCP, a platform for doing massively-parallel computation in JavaScript, has been frustrated by the lack of a text-ui debugger which works with our library that unlocks Ethereum keystores. See Distributed.Computer for more information if you're curious about that.
Major Functional Differences From Node-Inspect
- Can debug processes that require input on stdin, including REPLs
- Avoid startup pause can be disabled by default via config on a per-target basis
- Use randomized inspect port by default
- REPL history is maintained; inner REPL history is per program name
Roadmap
- Most plans are laid out in the GitHub issue tracker. (Feel free to help out!)
- I will be tracking changes to node-inpsect; further divergence from node-inspect will be primarily centered on usability
- UX issues will help differentiate stdout from stderr, debugger text from debuggee text via colour, improve error messaging, reduce stack trace clutter, etc.
- The config file should be fairly stable, but will continue to grow settings, particularly those for helping to put niim into certain modes (like "break on uncaught") for specific programs.
- Version numbers no longer track node-inspect.
- Bugfixes related to core functionality will be implemented in feature branches that should be easy for the main project to merge.
Release Status
This fork is barely past the "proof of concept" stage. Please be aware that it is barely tested on my machines, let alone yours. I'm running Node 10.20 on Linux x86_64 at work and Node 14 on macOs Catalina at home. Please let me know if you're using niim and find it useful - and feel free to suggest ideas!
Launching Niim
niim [options] ‹filename to debug›
| Option | Behaviour |
|---|---|
| --config-file= | Specify an additional config file (overlays etc/config) |
| --port | Specify the port to use for the node-inspect protocol. Default: auto |
| --host | Specify the hostname to use for the node-inspect protocol. Default: localhost |
Debugging with niim
All of the commands from node-inspect work as usual. If you are on an older version
of NodeJS, you might find that they work better than usual. :)
| New Command | Behaviour |
|---|---|
| send(string) | Send the string to the attached process' stdin |
| sendFile(filename) | Send the named file to the attached process' stdin |
| pipe(fd or command) | Send the data on the pipeline to the attach process' stdin |
| ctty | Suspend the REPL and enter interactive termimal mode |
There is also a FAQ in this directory which goes into more detail.
Features
Interactive Terminal Mode
This feature is the raison d'être for this fork, as our team frequently finds itself needing to enter passphrases during our debugging sessions.
In this mode, the REPL is suspended and the debugger's stdin is fed to the attached process. If the attached
process is in raw mode, the debugger's terminal will also be set in raw mode. During interactive terminal
mode, the debugger will also not print ‹ symbols in front of the attached process' stdout.
The niim preloader communicates with niim using its own protocol, over the attached process' stdout. All messages are of the form NUL{json}NUL. If the attached process writes a NUL, it is escaped with a second NUL.
To facilitate this mode, the niim preloader monkey-patches and otherwise tries to virtualize APIs on process.stdin and process.stdout. Setting DEBUG_NIIM and/or DEBUG_NIIM_PRELOAD can yield insight into the under-the-hood behaviour if strange things are happening for you.
It is very important that a process under debugging only use the stdout Stream interface for writing to stdout if the data written can contain NUL characters.
niim module
The internal module require("niim") is supplied to the attached process via the niim preloader. This
library allows for niim-aware debug targets to interoperate with niim directly.
| Module export | Behaviour |
|---|---|
| itm(boolean) | true - enter interactive terminal mode. false - exit interactive terminal mode. |
Configuration
niim ships with a niim.config master configuration in the etc/ directory of the package to describe all of the configuration options and their defaults. The config files are read in the following order; the last file read that sets a given property has precedence:
- etc/niim.config
- etc/your-program-name.config
- ~/.niim/config
- ~/.niim/your-program-name.config
- filename passed with --config=
| Environment Variable | Behaviour |
|---|---|
| NIIM_CONFIG_FILE | Specify an additional config file (overlays etc/config) |
| NIIM_DEFAULT_PORT | Specify the default port to use for the node-inspect protocol. Default: auto |
| NIIM_REPL_HISTORY | Alternative history filename |
| NIIM_REPL_SIZE | Override history size |
Enabling Autostart
If your work flow does not involve setting breakpoints the moment niim launches, you might like to
enable autostart; this feature skips the first niim› prompt and starts running the attached process
right away.
To enable autostart globally, set niim.autostart=true in ~/.niim/config. To enable it only when
debugging a program named XYZ, set niim.autostart=true in ~/.niim/XYZ.config.
Other Debuggers
The fork root, node-inspect, is maintained by the NodeJS team. This is the
debugger you launch with node debug filename.js. The latest version of node-inspect
is available at https://github.com/nodejs/node-inspect. The principal author is
Jan Krems, jan.krems@gmail.com.
The V8 team maintain an excellent browser-based GUI debugger; it is available at https://github.com/node-inspector/node-inspector.