devtools-timeline-model - npm Package Compare versions

Comparing version 1.0.17 to 1.0.18

index.js

@@ -12,7 +12,11 @@ /* global WebInspector TimelineModelTreeView */
     // Everything happens in a sandboxed vm context, to keep globals and natives separate.
+    // First, sandboxed contexts don't have any globals from node, so we whitelist a few we'll provide for it.
     var glob = { require: require, global: global, console: console, process, process, __dirname: __dirname }
+    // We read in our script to run, and create a vm.Script object 
     var script  = new vm.Script(fs.readFileSync(__dirname + "/lib/timeline-model.js", 'utf8'))
+    // We create a new V8 context with our globals
     var ctx = vm.createContext(glob)
+    // We evaluate the `vm.Script` in the new context
     var output = script.runInContext(ctx)
-
+    // We pull the local `instance` variable out, to use as our proxy object
     this.sandbox = ctx.instance;
@@ -19,0 +23,0 @@ this.sandbox.init(events);

lib/timeline-model.js

 'use strict'
 
-var fs = require('fs');
+const fs = require('fs');
+const path = require('path');
+const resolve = require('resolve');
 
@@ -9,6 +11,8 @@ // In order to maintain consistent global scope across the files,
 function requireval(path){
-  var filesrc = fs.readFileSync(__dirname + '/node_modules/' + path, 'utf8');
+  var res = resolve.sync(path, { basedir: __dirname })
+  var filesrc = fs.readFileSync(res, 'utf8');
   eval(filesrc + '\n\n//# sourceURL=' + path);
 }
 
+
 // establish our sandboxed globals
@@ -23,3 +27,3 @@ this.window = this.self = this.global = this
 // polyfills
-requireval('../lib/api-stubs.js')
+requireval('./lib/api-stubs.js')
 
@@ -46,5 +50,5 @@ // chrome devtools frontend
 // minor configurations
-requireval('../lib/devtools-monkeypatches.js')
+requireval('./lib/devtools-monkeypatches.js')
 // polyfill the bottom-up and topdown tree sorting
-requireval('../lib/timeline-model-treeview.js')
+requireval('./lib/timeline-model-treeview.js')
 
@@ -51,0 +55,0 @@ class SandboxedModel {

package.json

 {
   "name": "devtools-timeline-model",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "description": "Parse raw trace data into the Chrome DevTools' structured profiling data models",
@@ -29,3 +29,4 @@ "license": "Apache-2.0",
   "dependencies": {
-    "chrome-devtools-frontend": "1.0.382117"
+    "chrome-devtools-frontend": "1.0.382117",
+    "resolve": "1.1.7"
   },
@@ -32,0 +33,0 @@ "devDependencies": {

readme.md

@@ -42,4 +42,5 @@ # devtools-timeline-model [![Build Status](https://travis-ci.org/paulirish/devtools-timeline-model.svg?branch=master)](https://travis-ci.org/paulirish/devtools-timeline-model)
 // bottom up tree, grouped by URL
-model.bottomUpGroupBy('URL') // accepts: None Category Subdomain Domain URL
+model.bottomUpGroupBy('URL') // accepts: None Category Subdomain Domain URL EventName
 
+// see example.js for API examples.
 ```
@@ -61,7 +62,53 @@
 
+## Sandboxing WebInspector for Node
 
+Requiring the DevTools frontend looks rather straightforward at first. (`global.WebInspector = {}`, then start `require()`ing the files, in dependency order). However, there are two problems that crop up:
 
+1. The frontend requires ~five globals and they currently must be added to the global context to work. 
+2. `utilities.js` adds a number of methods to native object prototypes, such as Array, Object, and typed arrays.
 
+`devtools-timeline-model` addresses that by sandboxing the WebInspector into it's own context. Here's how it works:
+
+##### index.js
+```js
+// First, sandboxed contexts don't have any globals from node, so we whitelist a few we'll provide for it.
+var glob = { require: require, global: global, console: console, process, process, __dirname: __dirname }
+// We read in our script to run, and create a vm.Script object 
+var script  = new vm.Script(fs.readFileSync(__dirname + "/lib/timeline-model.js", 'utf8'))
+// We create a new V8 context with our globals
+var ctx = vm.createContext(glob)
+// We evaluate the `vm.Script` in the new context
+var output = script.runInContext(ctx)
+```
+##### (sandboxed) timeline-model.js
+```js
+// establish our sandboxed globals
+this.window = this.self = this.global = this
+
+// We locally eval, as the node module scope isn't appropriate for the browser-centric DevTools frontend
+function requireval(path){
+  var filesrc = fs.readFileSync(__dirname + '/node_modules/' + path, 'utf8');
+  eval(filesrc + '\n\n//# sourceURL=' + path);
+}
+
+// polyfills, then the real chrome devtools frontend
+requireval('../lib/api-stubs.js')
+requireval('chrome-devtools-frontend/front_end/common/Object.js')
+requireval('chrome-devtools-frontend/front_end/common/SegmentedRange.js')
+requireval('chrome-devtools-frontend/front_end/platform/utilities.js')
+requireval('chrome-devtools-frontend/front_end/sdk/Target.js')
+// ...
+```
+##### index.js
+```
+// After that's all done, we pull the local `instance` variable out, to use as our proxy object
+this.sandbox = ctx.instance;
+```
+
+Debugging is harder, as most tools aren't used to this setup. While `devtool` doesn't work well, you can have it run `lib/devtools-timeline-model.js` directly, which is fairly succesful. The classic `node-inspector` does work pretty well with the sandboxed script, though the workflow is a little worse than `devtool`'s. 
+
+
+
 ## License
 
 Apache © [Paul Irish](https://github.com/paulirish/)

No alert changes

Improved metrics

Total package byte prevSize

21921

increased by15.15%

Lines of code

387

increased by2.11%

Number of lines in readme file

113

increased by71.21%

Worsened metrics

Dependency count

2

increased by100%

Dependency changes

• + Addedresolve@1.1.7

• + Addedresolve@1.1.7(transitive)