examples

Documentation

Overview

proxy is a martian.Proxy configurable via HTTP.

It can be dynamically configured/queried at runtime by issuing requests to proxy specific paths using JSON.

Supported configuration endpoints:

POST host:port/martian/modifiers

sets the request and response modifier of the proxy; modifiers adhere to the following top-level JSON structure:

{
	"package.Modifier": {
		"scope": ["request", "response"],
		"attribute 1": "value",
		"attribute 2": "value"
	}
}

modifiers may be "stacked" to provide support for additional behaviors; for example, to add a "Martian-Test" header with the value "true" for requests with the domain "www.example.com" the JSON message would be:

{
	"url.Filter": {
		"scope": ["request"],
		"host": "www.example.com",
		"modifier": {
			"header.Modifier": {
				"name": "Martian-Test",
				"value": "true"
			}
		}
	}
}

url.Filter parses the JSON object in the value of the "url.Filter" attribute; the "host" key tells the url.Filter to filter requests if the host explicitly matches "www.example.com"

the "modifier" key within the "url.Filter" JSON object contains another modifier message of the type header.Modifier to run iff the filter passes

GET host:port/martian/verify

retrieves the verifications errors as JSON with the following structure:

{
	"errors": [
		{
			"message": "request(url) verification failure"
		},
		{
			"message": "response(url) verification failure"
		}
	]
}

verifiers also adhere to the modifier interface and thus can be included in the modifier configuration request; for example, to verify that all requests to "www.example.com" are sent over HTTPS send the following JSON to the configuration endpoint:

{
	"url.Filter": {
		"scope": ["request"],
		"host": "www.example.com",
		"modifier": {
			"url.Verifier": {
				"scope": ["request"],
				"scheme": "https"
			}
		}
	}
}

sending a request to "host:port/martian/verify" will then return errors from the url.Verifier

POST host:port/martian/verify/reset

resets the verifiers to their initial state; note some verifiers may start in a failure state (e.g., pingback.Verifier is failed if no requests have been seen by the proxy)

passing the -cors flag will enable CORS support for the endpoints so that they may be called via AJAX

The flags are:

-addr=":8080"
	host:port of the proxy
-cert=""
	PEM encoded X509 CA certificate; if set, it will be set as the
	issuer for dynamically-generated certificates during man-in-the-middle
-key=""
	PEM encoded private key of cert (RSA or ECDSA); if set, the key will be used
	to sign dynamically-generated certificates during man-in-the-middle
-organization="Martian Proxy"
	organization name set on the dynamically-generated certificates during
	man-in-the-middle
-validity="1h"
	window of time around the time of request that the dynamically-generated
	certificate is valid for; the duration is set such that the total valid
	timeframe is double the value of validity (1h before & 1h after)
-cors=false
	allow the proxy to be configured via CORS requests; such as when
	configuring the proxy via AJAX