0.5.2 • Published 9 years ago

rewriting-proxy v0.5.2

Weekly downloads
21
License
EPL-1.0
Repository
github
Last release
9 years ago

rewriting-proxy

Simple proxy library for rewriting JavaScript on-the-fly.

Installation

npm install rewriting-proxy

Usage

From proxy-example.js:

var proxy = require("rewriting-proxy");

var options = {
    rewriter: function (src, metadata) {
        console.log("instrumenting " + metadata.url);
        return src;		
    },
    rewriteOptions: {
        onNodeVisited: function (node) {
            // Tag every element in the HTML with its source location
            if (node.tagName) {
                var location = node.__location;
                node.attrs.push({ name: "data-loc", value: location.line + ":" + location.col })
            }
        },
        locationInfo: true
    },
    headerHTML: "<script>alert(\"hi\");</script>",
    port: 8080
};

proxy.start(options);

The start(options) function starts the proxy server on localhost. Possible options are:

  • rewriter: A function that takes JavaScript code as its first parameter and returns the instrumented version of the code. Any response with a MIME type suggesting JavaScript content is passed to rewriter. The metadata object passed as the second parameter includes properties:
    • type: the type of the script, either 'script' for inline scripts or script files, 'event-handler' for event handlers, or 'javascript-url' for JavaScript URLs.
    • inline: For scripts of type 'script', indicates whether the script was inline.
    • url: A URL for the script; these are auto-generated for inline scripts, event handlers, etc.
  • rewriteOptions: An object that allows instrumenting the HTML. The object includes properties:
    • onBeforeNodeVisited: A function that is called with a HTML node when the entire subtree rooted at the node has been visited. The function return value is ignored; instead the function should mutate the subtree rooted at the node argument. Is unlike onNodeVisited invoked prior to any JavaScript instrumentation performed by rewriter.
    • onNodeVisited: A function that is called with a HTML node when the entire subtree rooted at the node has been visited. The function return value is ignored; instead the function should mutate the subtree rooted at the node argument.
    • locationInfo: A boolean that is parsed to the parse5 HTML parser, indicating whether node locations should be made available. (Disabled by default for performance.)
  • headerHTML: HTML string to be injected at the beginning of any requested HTML file.
  • headerURLs: an Array of script URLs. These URLs will be loaded via <script> tags at the beginning of any HTML file.
  • port: The port on which the proxy server should listen, default 8080.

The library also exposes a rewriteHTML(html, url, rewriter, headerHTML, headerURLs, options) function that rewrites the inline scripts (and HTML) in a given html string with URL url, using the rewriter function, headerHTML string and headerURLs array as described above.

To see a real-world use of the library, look at jalangi_proxy.js from the Jalangi framework.

Example

Input:

<!DOCTYPE html>
<html>
  <head>
    <title>Proxy test</title>
  </head>
  <body>
    <h1>Proxy test</h1>
  </body>
</html>

Output using proxy-example.js (modulo indentation):

<!DOCTYPE html>
<html data-loc="2:1">
  <head data-loc="3:3">
    <script>alert("hi");</script>
    <title data-loc="4:5">Proxy test</title>
  </head>
  <body data-loc="6:3">
    <h1 data-loc="7:5">Proxy test</h1>
  </body>
</html>

Limitations

  • Can't rewrite scripts requested via HTTPS.
  • Can't rewrite inline scripts inserted by other scripts, e.g.:

    	    var x = "<script>" + ... + "</script>";
    	    node.innerHTML = x;

License

This software is distributed under the Eclipse Public License.

0.5.2

9 years ago

0.5.1

9 years ago

0.5.0

9 years ago

0.4.3

10 years ago

0.4.2

11 years ago

0.4.1

11 years ago

0.4.0

11 years ago

0.3.2

11 years ago

0.3.1

11 years ago

0.3.0

11 years ago

0.2.1

11 years ago

0.2.0

12 years ago