Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 148 lines (103 sloc) 7.316 kB
1289fb8 @greim forgot -a option last time
authored
1 Overview
2 ========
85a60d7 @greim initial commit
authored
3
3b741c8 @greim updated readme
authored
4 Hoxy is a web-hacking proxy for [node.js](http://nodejs.org/), intended for use by web developers. Using hoxy, you can act as a "man in the middle" and alter HTTP requests and responses as they flow through, based on a set of conditional rules. As a running process, hoxy otherwise behaves like a standalone proxy server. Hoxy was inspired as a way to complement debuggers like Firebug, which let you manipulate the client runtime but not the underlying HTTP conversation.
85a60d7 @greim initial commit
authored
5
a9c989c @greim even more different link to demo video
authored
6 [Video: Quick Introduction](http://www.youtube.com/watch?v=2YLfBTrVgZU)
786da69 @greim link to demo video
authored
7
9314151 @greim more architecture documentation
authored
8 Starting Hoxy
05bf1b3 @greim hoxy can now be launched from dirs other than the one where it lives.…
authored
9 -------------
501728e moved startup and sys req to top
Greg Reimer authored
10
89d0977 @greim 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 @greim updated readme of --port option
authored
13 node hoxy.js
501728e moved startup and sys req to top
Greg Reimer authored
14
ffc06b8 @greim updated readme
authored
15 This will start hoxy on port 8080. (For a different port, e.g. 8081, use `--port=8081`.) Next, configure your browser's proxy settings to point to hoxy.
89d0977 @greim 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 @greim 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 @greim added note about debug mode
authored
20
21 node hoxy.js --debug
22
ffc06b8 @greim updated readme
authored
23 Now hoxy will dump all errors to the console.
fa9fade @greim added note about debug mode
authored
24
05bf1b3 @greim hoxy can now be launched from dirs other than the one where it lives.…
authored
25 Starting Hoxy (Quickstart)
26 --------------------------
27
28 If you type:
29
30 quickstart-hoxy
31
32 You will be thrown into a `vi` session against a temp rules file. When you exit the `vi` session, hoxy will launch against that rules file. Every time you do this, that rules file starts over as blank. This is a convenience method to launch hoxy for quick experiments.
33
8452345 @greim added note about HTTP_PROXY env var
authored
34 Using Hoxy With Another Proxy
05bf1b3 @greim hoxy can now be launched from dirs other than the one where it lives.…
authored
35 -----------------------------
8452345 @greim added note about HTTP_PROXY env var
authored
36
81f4a32 @greim updated readme
authored
37 Hoxy looks for the optional `HTTP_PROXY` environment variable and, if found, uses it.
c2fe2c8 @greim added more info for http_proxy usage
authored
38
ffc06b8 @greim updated readme
authored
39 export HTTP_PROXY=proxy.example.edu:80
c2fe2c8 @greim added more info for http_proxy usage
authored
40 node hoxy.js
8452345 @greim added note about HTTP_PROXY env var
authored
41
9314151 @greim more architecture documentation
authored
42 How to Use Hoxy
43 ---------------
44
58147e7 @greim added notes about preemptive plugin responses
authored
45 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 @greim more architecture documentation
authored
46
47 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.
48
501728e moved startup and sys req to top
Greg Reimer authored
49 System Requirements
50 --------------------
51
81c3974 @greim fixes to the jquery plugin. switch to newer client-pooling methods. r…
authored
52 Hoxy requires [node.js](http://nodejs.org/) to run, version 0.4 or higher.
501728e moved startup and sys req to top
Greg Reimer authored
53
21f51b8 @greim added architectural overview
authored
54 Architectural Overview
9314151 @greim more architecture documentation
authored
55 ======================
85a60d7 @greim initial commit
authored
56
9314151 @greim more architecture documentation
authored
57 An HTTP conversation could be illustrated like this:
21f51b8 @greim added architectural overview
authored
58
59 HTTP TRANSACTION
60 -----------------------
61 server: 2
62 ------------/-\--------
63 client: 1 3
64 -----------------------
9314151 @greim more architecture documentation
authored
65 time -->
21f51b8 @greim added architectural overview
authored
66
9314151 @greim more architecture documentation
authored
67 * Phase 1: Client prepares to make request.
e599e4e @greim check content-length is undefined, to differentiate from 0
authored
68 * Hop: Client transmits request to server.
9314151 @greim more architecture documentation
authored
69 * Phase 2: Server processes request and prepares response.
e599e4e @greim check content-length is undefined, to differentiate from 0
authored
70 * Hop: Server transmits response to client.
9314151 @greim more architecture documentation
authored
71 * Phase 3: Client processes response.
21f51b8 @greim added architectural overview
authored
72
9314151 @greim more architecture documentation
authored
73 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 @greim added architectural overview
authored
74
75 USING A PROXY SERVER
76 -----------------------
77 server: 2
78 -------------/-\-------
79 proxy: / \
80 -----------/-----\-----
81 client: 1 3
82 -----------------------
83
9314151 @greim more architecture documentation
authored
84 * Phase 1: Client prepares to make request.
e599e4e @greim check content-length is undefined, to differentiate from 0
authored
85 * Hop: Client transmits request to server (through the proxy).
9314151 @greim more architecture documentation
authored
86 * Phase 2: Server processes request and prepares response.
e599e4e @greim check content-length is undefined, to differentiate from 0
authored
87 * Hop: Server transmits response to client (through the proxy).
9314151 @greim more architecture documentation
authored
88 * Phase 3: Client processes response.
89
21f51b8 @greim added architectural overview
authored
90 Hoxy differs from a normal HTTP proxy by adding two additional processing steps, one during the request phase, another during the response phase:
91
92 USING HOXY
93 -----------------------
94 server: 3
95 -------------/-\-------
96 hoxy: 2 4
97 -----------/-----\-----
98 client: 1 5
99 -----------------------
100
9314151 @greim more architecture documentation
authored
101 * Phase 1: Client prepares to make request.
102 * Hop: Client transmits to hoxy.
103 * Phase 2: Hoxy executes request-phase rules.
ffc06b8 @greim updated readme
authored
104 * Hop: Hoxy transmits (a potentially altered) request to (a potentially different) server.
9314151 @greim more architecture documentation
authored
105 * Phase 3: Server processes request and prepares response.
106 * Hop: Server transmits to hoxy.
107 * Phase 4: Hoxy executes response-phase rules.
e599e4e @greim check content-length is undefined, to differentiate from 0
authored
108 * Hop: Hoxy transmits (a potentially altered) response to client.
9314151 @greim more architecture documentation
authored
109 * Phase 5: Client processes response.
110
e599e4e @greim check content-length is undefined, to differentiate from 0
authored
111 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 @greim more architecture documentation
authored
112
e599e4e @greim check content-length is undefined, to differentiate from 0
authored
113 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 @greim more architecture documentation
authored
114
e599e4e @greim check content-length is undefined, to differentiate from 0
authored
115 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 @greim added architectural overview
authored
116
58147e7 @greim added notes about preemptive plugin responses
authored
117 A Twist in the Plot
118 -------------------
119
120 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:
121
122 ------------------------------
123 server: *blissful ignorance*
124 ------------------------------
125 hoxy: 2———3
126 --------------/-----\---------
127 client: 1 4
128 ------------------------------
129
130 * Phase 1: Client prepares to make request.
131 * Hop: Client transmits to hoxy.
132 * Phase 2: Hoxy executes request-phase rules, triggering a plugin that populates the response.
1120912 @greim fixed error in preemptive chart description
authored
133 * Hoxy notices that the response has already been written and skips the server hit.
134 * Phase 3: Hoxy executes response-phase rules.
58147e7 @greim added notes about preemptive plugin responses
authored
135 * Hop: Hoxy transmits to client.
136 * Phase 4: Client processes response.
137
e1ed5f9 @greim added staging server mode
authored
138 Staging Server Mode
139 ===================
58147e7 @greim added notes about preemptive plugin responses
authored
140
508a870 @greim added a startup version check
authored
141 Hoxy has an optional staging server mode, where in addition to functioning as a proxy, it can also serve as a mirror of another server. To start up hoxy in staging server mode:
e1ed5f9 @greim added staging server mode
authored
142
7b30586 @greim changed 'staging' to 'stage'
authored
143 node hoxy.js --port=83 --stage=www.example.com
e1ed5f9 @greim added staging server mode
authored
144
508a870 @greim added a startup version check
authored
145 Supposing you launched this instance of Hoxy on a machine called `dev.example.com`, you can still configure your browser to proxy through `dev.example.com:83`, but now you can also hit `http://dev.example.com:83/` directly from your browser, in which case it will mirror over to `http://www.example.com/` but still run your rules in the interim.
e1ed5f9 @greim added staging server mode
authored
146
147 This is useful in testing and QA scenarios where you're testing changes on a specific website. You can then pass out Hoxy links to various testers without needing them to configure their proxy settings.
Something went wrong with that request. Please try again.