Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 125 lines (90 sloc) 6.181 kb
1289fb8 Greg Reimer forgot -a option last time
authored
1 Overview
2 ========
85a60d7 Greg Reimer initial commit
authored
3
31b14a0 Greg Reimer updated readme of --port option
authored
4 Hoxy is a web-hacking proxy for [node.js](http://nodejs.org/), intended for use by web developers. Hoxy is similar in concept to [Firebug](http://getfirebug.com/), or perhaps [Greasemonkey](http://www.greasespot.net/), but it operates within the HTTP transport layer rather than within the client runtime. As such, hoxy runs as a standalone proxy server, not as an add-on for any specific browser.
85a60d7 Greg Reimer initial commit
authored
5
786da69 Greg Reimer link to demo video
authored
6 [Video: Quick Introduction](http://www.youtube.com/watch?v=_V0x-khzCXo)
7
9314151 Greg Reimer more architecture documentation
authored
8 Starting Hoxy
501728e moved startup and sys req to top
Greg Reimer authored
9 ---------------
10
89d0977 Greg Reimer shortened startup directions
authored
11 Stand in the hoxy project dir and type:
501728e moved startup and sys req to top
Greg Reimer authored
12
31b14a0 Greg Reimer updated readme of --port option
authored
13 node hoxy.js
501728e moved startup and sys req to top
Greg Reimer authored
14
93541d7 Greg Reimer blacklist req headers function
authored
15 This will start hoxy on port 8080. (For a different port, use `--port=port`.) Next, configure your browser's proxy settings to point to hoxy.
89d0977 Greg Reimer shortened startup directions
authored
16
17 If it doesn't already exist, upon startup hoxy will create a file in the `rules` dir called `rules.txt`. Open this file in your text editor and edit/add rules as needed. There's no need to restart hoxy each time you save the rules file.
501728e moved startup and sys req to top
Greg Reimer authored
18
31b14a0 Greg Reimer updated readme of --port option
authored
19 Note: hoxy catches as many errors as possible in an effort to stay running. By default, error messages are suppressed. If you're writing rules or developing plugins (or developing hoxy itself), you should run in debug mode so you can see syntax or runtime errors as they occur:
fa9fade Greg Reimer added note about debug mode
authored
20
21 node hoxy.js --debug
22
23 Now hoxy will print out all errors to the console.
24
9314151 Greg Reimer more architecture documentation
authored
25 How to Use Hoxy
26 ---------------
27
58147e7 Greg Reimer added notes about preemptive plugin responses
authored
28 If you have a good grasp of HTTP basics, hoxy itself isn't wildly complicated, and reading the architectural overview below should give you a basic idea of how it works. From there, the readme file in the `rules` dir should give you enough info to get on your way writing rules.
9314151 Greg Reimer more architecture documentation
authored
29
30 If you're comfortable writing JavaScript for node.js, you can also write plugins for hoxy. See the readme file in the `plugins` dir for more info.
31
501728e moved startup and sys req to top
Greg Reimer authored
32 System Requirements
33 --------------------
34
2189c4b Greg Reimer changed expires to expiry, more docs
authored
35 Hoxy requires [node.js](http://nodejs.org/) to run, version 0.3 or higher. (Anecdotal evidence suggests it *may* work on earlier versions, YMMV.) Any browser can be used that can be configured to use a proxy, and that can see your hoxy instance on the network.
501728e moved startup and sys req to top
Greg Reimer authored
36
21f51b8 Greg Reimer added architectural overview
authored
37 Architectural Overview
9314151 Greg Reimer more architecture documentation
authored
38 ======================
85a60d7 Greg Reimer initial commit
authored
39
9314151 Greg Reimer more architecture documentation
authored
40 An HTTP conversation could be illustrated like this:
21f51b8 Greg Reimer added architectural overview
authored
41
42 HTTP TRANSACTION
43 -----------------------
44 server: 2
45 ------------/-\--------
46 client: 1 3
47 -----------------------
9314151 Greg Reimer more architecture documentation
authored
48 time -->
21f51b8 Greg Reimer added architectural overview
authored
49
9314151 Greg Reimer more architecture documentation
authored
50 * Phase 1: Client prepares to make request.
e599e4e Greg Reimer check content-length is undefined, to differentiate from 0
authored
51 * Hop: Client transmits request to server.
9314151 Greg Reimer more architecture documentation
authored
52 * Phase 2: Server processes request and prepares response.
e599e4e Greg Reimer check content-length is undefined, to differentiate from 0
authored
53 * Hop: Server transmits response to client.
9314151 Greg Reimer more architecture documentation
authored
54 * Phase 3: Client processes response.
21f51b8 Greg Reimer added architectural overview
authored
55
9314151 Greg Reimer more architecture documentation
authored
56 For our purposes, we can say that an HTTP proxy represents no additional processing phases. It just passes through the data transparently. A proxy just introduces a slight complication to the transport layer:
21f51b8 Greg Reimer added architectural overview
authored
57
58 USING A PROXY SERVER
59 -----------------------
60 server: 2
61 -------------/-\-------
62 proxy: / \
63 -----------/-----\-----
64 client: 1 3
65 -----------------------
66
9314151 Greg Reimer more architecture documentation
authored
67 * Phase 1: Client prepares to make request.
e599e4e Greg Reimer check content-length is undefined, to differentiate from 0
authored
68 * Hop: Client transmits request to server (through the proxy).
9314151 Greg Reimer more architecture documentation
authored
69 * Phase 2: Server processes request and prepares response.
e599e4e Greg Reimer check content-length is undefined, to differentiate from 0
authored
70 * Hop: Server transmits response to client (through the proxy).
9314151 Greg Reimer more architecture documentation
authored
71 * Phase 3: Client processes response.
72
21f51b8 Greg Reimer added architectural overview
authored
73 Hoxy differs from a normal HTTP proxy by adding two additional processing steps, one during the request phase, another during the response phase:
74
75 USING HOXY
76 -----------------------
77 server: 3
78 -------------/-\-------
79 hoxy: 2 4
80 -----------/-----\-----
81 client: 1 5
82 -----------------------
83
9314151 Greg Reimer more architecture documentation
authored
84 * Phase 1: Client prepares to make request.
85 * Hop: Client transmits to hoxy.
86 * Phase 2: Hoxy executes request-phase rules.
e599e4e Greg Reimer check content-length is undefined, to differentiate from 0
authored
87 * Hop: Hoxy transmits (a potentially altered) request to server.
9314151 Greg Reimer more architecture documentation
authored
88 * Phase 3: Server processes request and prepares response.
89 * Hop: Server transmits to hoxy.
90 * Phase 4: Hoxy executes response-phase rules.
e599e4e Greg Reimer check content-length is undefined, to differentiate from 0
authored
91 * Hop: Hoxy transmits (a potentially altered) response to client.
9314151 Greg Reimer more architecture documentation
authored
92 * Phase 5: Client processes response.
93
e599e4e Greg Reimer check content-length is undefined, to differentiate from 0
authored
94 Request-phase rules (2) and response-phase rules (4) are written by you, and can alter any aspect of a request or response, in a way that's undetectable by either client or server. This includes (but isn't limited to) method, url, hostname, port, status, headers, cookies, params, and even the content body. For example, if you change the hostname, hoxy will send the request to a *different* server, unbeknownst to the client!
9314151 Greg Reimer more architecture documentation
authored
95
e599e4e Greg Reimer check content-length is undefined, to differentiate from 0
authored
96 Furthermore, a rule will fire only when certain conditions are met. For example, you can say, IF the url ends with ".min.js", THEN run js-beautify against the content of the response body. Or, IF the hostname equals "www.example.com", THEN change it to "www-stage.example.com". Just as any aspect of a request or response can be altered, any aspect of a request or response can be used in a conditional.
9314151 Greg Reimer more architecture documentation
authored
97
e599e4e Greg Reimer check content-length is undefined, to differentiate from 0
authored
98 Finally, while hoxy has a broad set of out-of-the-box capabilities, its plugin API allows developers to extend it in arbitrary ways. Plugins are written in JavaScript and invoked using the same conditional logic described above. For example, IF the content type is "text/html", THEN run the foo plugin.
21f51b8 Greg Reimer added architectural overview
authored
99
58147e7 Greg Reimer added notes about preemptive plugin responses
authored
100 A Twist in the Plot
101 -------------------
102
103 Plugins running in the request phase have the option to write the response themselves, which effectively preempts the hit to the server. In such cases, hoxy's behavior would look like this:
104
105 ------------------------------
106 server: *blissful ignorance*
107 ------------------------------
108 hoxy: 2———3
109 --------------/-----\---------
110 client: 1 4
111 ------------------------------
112
113 * Phase 1: Client prepares to make request.
114 * Hop: Client transmits to hoxy.
115 * Phase 2: Hoxy executes request-phase rules, triggering a plugin that populates the response.
1120912 Greg Reimer fixed error in preemptive chart description
authored
116 * Hoxy notices that the response has already been written and skips the server hit.
117 * Phase 3: Hoxy executes response-phase rules.
58147e7 Greg Reimer added notes about preemptive plugin responses
authored
118 * Hop: Hoxy transmits to client.
119 * Phase 4: Client processes response.
120
121 Fin
122 ---
123
124 Hoxy opens the door for all kinds of testing, debugging and prototyping (and maybe some mischief) that might not otherwise be possible. Please use hoxy responsibly.
Something went wrong with that request. Please try again.