# railgun.ProxyServer

Railgun's proxy server is one of the centerpieces of the library. It is used to automate processing
and analyzing requests made, for example, by your web browser while navigating an application. It is
also possible to create plugin functionality for inspecting and modifying responses before they
are written to the source of the request.

Example:

```js
const railgun = require('railgun')

let proxy = new railgun.ProxyServer(8080)

proxy
.on('request', (request, next) => {
  // Spoof the User-Agent
  request.headers['User-Agent'] = 'Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.112 Safari/537.36'
  next()
})
.then((request, next) => {
  // We can chain middleware of the same type using `then`.
  console.log('Sending request', JSON.stringify(request, null, 4))
  next()
})

proxy.on('response', (response, next) => {
  console.log('Got response', JSON.stringify(response, null, 4))
  next()
})

// The `start` method accepts a function that will be invoked if an error occurs.
proxy.start(function (err, req, res) {
  console.error(err)
  res.writeHead(400)
  res.write(err.message)
  res.end()
})
```

## Methods

### railgun.ProxyServer#constructor

Create a proxy server to run on a specified address and port.

The constructor accepts either the port number (as an integer) to run the server on (and defaults to
listening on localhost) or both the IP to bind to and then the port as an integer.

### railgun.ProxyServer#start

Start the proxy server. Once started, the proxy server will asynchronously listen for requests until
stopped with `railgun.ProxyServer#stop`.

ProxyServer#start accepts an error handling function of the form

```js
function (error, request, response) {
  // Write whatever you want to the response based on the error.
}
```

So, for example, you could write the contents of the error for further inspection.

```js
let server = new railgun.ProxyServer(9001)
server.start((err, req, res) => {
  console.log('Got an error requesting', req.url)
  console.log(err.message)
  res.write(err.message)
  res.end()
})
```

### railgun.ProxyServer#stop

Stop the proxy server.

ProxyServer#stop accepts a callback function that will be passed directly to Node's `http.Server#close`
and thus be invoked once the server has indeed stopped running.

### railgun.ProxyServer#on

Register a middleware function to operate on requests or responses.

ProxyServer#on accepts a string- either "request" or "response"- and a middleware function that operates
on either a request builder or a response builder respectively, and invokes a `next` function when complete.
These functions take the form

```js
function (requestOrResponseBuilder, next) {
  // Do something to the builder, like set headers
  next()
}
```

For example a middleware function to set every request's User-Agent header to "Railgun Proxy" would look like

```js
let server = new railgun.ProxyServer(9001)
server.on('request', (request, next) => {
  request.headers['User-Agent'] = 'Railgun Proxy'
  next()
})
```

### railgun.ProxyServer#then

ProxyServer#then is used to register more middleware functions of the same type.

After calling ProxyServer#on, you can call ProxyServer#then on the former's return value (the Proxy Server)
to register another piece of middleware of the same type. This is really just a convenient shorthand.

```js
let server = new railgun.ProxyServer(9001)
server.on('response', (response, next) => {
  console.log('Got a response that is', response.body.length, 'bytes long!')
  next()
})
.then((response, next) => {
  doAnotherThing(response)
  next()
})
```