pear-inspect
v1.1.3
Published
Debug Pear applications using DevTools
Downloads
1,096
Readme
pear-inspect
Enable debugging of Pear apps. This is especially useful when running terminal
or mobile
Pear apps. The apps can be running on a fully remote system, making it easier helping others debug their apps.
It's essentially a link between hyperdht and bare-inspector.
This is a part of how to debug Pear apps using Chrome Devtools Protocol (CDP).
Installation
npm install pear-inspect
Usage with pear://runtime
One of the reasons for using pear-inspect
is to be able to debug with the pear://runtime application. To do so, all that's needed is to do this, in the app you want to inspect:
import nodeInspector from 'inspector'
import { Inspector } from 'pear-inspect'
const inspector = new Inspector({ inspector: nodeInspector })
const inspectorKey = await inspector.enable()
console.log(`Add this key to Pear Runtime: ${inspectorKey.toString('hex')}`)
Usage
The main thing to understand is that:
- On the app which that needs to be debuggged, use the
Inspector
class. - On the other side (where you e.g. run your DevTools), use the
Session
class. This interface is similar to how Node's Inspector works with connect/disconnect/post methods.
On the app where inspection is needed:
import nodeInspector from 'inspector'
import { Inspector } from 'pear-inspect'
const inspector = new Inspector({ inspector: nodeInspector })
const inspectorKey = await inspector.enable() // Pass the public key to the Session
// When inspection is no longer needed:
// await inspector.disable()
On the side where you want to debug the remote app:
import { Session } from 'pear-inspect'
const session = new Session({ inspectorKey }) // The inspectorKey that was return from the Inspector
session.on('info', ({ filename }) => {
console.log('This is the main entrypoint', filename)
})
session.on('message', ({ id, result, error }) => {
console.log(result)
/*
{
result: {
type: 'number',
value: 3,
description: '3'
}
}
*/
})
session.connect()
session.post({
id: 1, // The id is optional, but is used by DevTools as it runs on jsonrpc
method: 'Runtime.evaluate',
params: { expression: '1 + 2' }
})
// When the session is no longer required (e.g. when the DevTools window is closed)
// session.disconnect()
// If the hyperdht connection should be completely stopped:
// await session.destroy()
Methods
new Inspector({ inspector, dhtServer = null, inspectorKey = null, filename = null })
Creates new Inspector that will be able to inspect the process it's currently running.
If filename
is omitted then it will be set to require.main.filename
.
async .enable()
Enables inspection, creates a hyperdht
server and returns inspectorKey
.
If a dhtServer
was passed, then it just attaches a 'connection' handler. If inspectorKey
was passed, then this is used as a seed to generate a key pair which is then used for creating the hyperdht
server.
async .disable()
Stops inspection and removes any hypderdht
server.
If a dhtServer
was passed, then it just detaches the 'connection' handler.
new Session({ inspectorKey = null, publicKey = null })
Creates new Session that can inspect a remote app.
Either inspectorKey
or publicKey
has to be used. Generally you will use inspectorKey
, but you can use publicKey
if you want to have more control.
.connect()
Start the remote inspection. disconnect()
can be called when inspection is no longer needed.
.disconnect()
Close the remote inspection. .connect()
can be called again if more inspection is needed.
.post({ id, method, params })
Send a CDP method to the remote app. id
is optional, but if passed, then it will be returned with the corresponding event.
Throws an error if .connect()
has not been called
event .on('info', ({ filename }) => { ... })
When connected to the Inspector on the remote side, this event is emitted where it's possible to see which filename is the main entrypoint for the Pear app.
event .on('message', msg => { ... })
Messages from the remote app's inspector. Will contain id
if that was passed to the corresponding method.