js: docs WIP

Author: Snawoot

README.md

@@ -24,6 +24,9 @@ Dumbest HTTP proxy ever.
 * Resilient to DPI (including active probing, see `hidden_domain` option for authentication providers)
 * Connecting via upstream HTTP(S)/SOCKS5 proxies (proxy chaining)
 * systemd socket activation
+* Scripting with JavaScript:
+  * Access filter by JS function
+  * Upstream proxy selection by JS function
 
 ## Installation
 
@@ -175,6 +178,35 @@ Authentication parameters are passed as URI via `-auth` parameter. Scheme of URI
   * `blacklist` - location of file with list of serial numbers of blocked certificates, one per each line in form of hex-encoded colon-separated bytes. Example: `ab:01:02:03`. Empty lines and comments starting with `#` are ignored.
   * `reload` - interval for certificate blacklist file reload, if it was modified since last load. Use negative duration to disable autoreload. Default: `15s`.
 
+## Scripting
+
+With the dumbproxy, it is possible to modify request processing behaviour using simple scripts written in the JavaScript programming language.
+
+### Access by JS script
+
+It is possible to filter (allow or deny) requests with simple `access` JS function. Such function can be loaded with the `-js-access-filter` option. Option value must specify location of script file where `access` function is defined.
+
+`access` function is invoked with following parameters:
+
+1. Request *(Object)*. It contains following properties:
+  * **method** *(string)* - HTTP method used in request (CONNECT, GET, POST, PUT, etc.).
+  * **url** *(string)* - URL parsed from the URI supplied on the Request-Line.
+  * **proto** *(string)* - the protocol version for incoming server requests.
+  * **protoMajor** *(Number)* - numeric major protocol version.
+  * **protoMinor** *(Number)* - numeric minor protocol version.
+  * **header** *(Object)* - mapping of *String* headers (except Host) in canonical form to *Array* of their *String* values.
+  * **contentLength** *(Number)* - length of request body, if known.
+  * **transferEncoding** *(Array)* - lists the request's transfer encodings from outermost to innermost.
+  * **host** *(String)* - specifies the host on which the URL is sought. For HTTP/1 (per RFC 7230, section 5.4), this is either the value of the "Host" header or the host name given in the URL itself. For HTTP/2, it is the value of the ":authority" pseudo-header field.
+  * **remoteAddr** *(String)* - client's IP:port.
+  * **requestURI** *(String)* - the unmodified request-target of the Request-Line (RFC 7230, Section 3.1.1) as sent by the client to a server.
+2. Destination address *(Object)*. It's an address where actual connection is about to be created. It contains following properties:
+  * **network** *(String)* - connection type. Should be `"tcp"` in most cases unless restricted to specific address family (`"tcp4"` or `"tcp6"`).
+  * **originalHost** *(String)* - original hostname or IP address parsed from request.
+  * **resolvedHost** *(String)* - resolved hostname from request.
+  * **port** *(Number)* - port number.
+* Username *(String)*. Name of the authenticated user or an empty string if there is no authentication.
+
 ## Synopsis
 
 ```
@@ -224,6 +256,14 @@ Usage of /home/user/go/bin/dumbproxy:
     	sign username with specified key for given validity period. Positional arguments are: hex-encoded HMAC key, username, validity duration.
   -ip-hints string
     	a comma-separated list of source addresses to use on dial attempts. "$lAddr" gets expanded to local address of connection. Example: "10.0.0.1,fe80::2,$lAddr,0.0.0.0,::"
+  -js-access-filter string
+    	path to JS script file with the "access" filter function
+  -js-access-filter-instances int
+    	number of JS VM instances to handle access filter requests (default 4)
+  -js-proxy-router value
+    	path to JS script file with the "getProxy" function
+  -js-proxy-router-instances int
+    	number of JS VM instances to handle proxy router requests (default 4)
   -key string
     	key for TLS certificate
   -list-ciphers

jsext/dto.go

@@ -21,10 +21,6 @@ type JSRequestInfo struct {
 	ContentLength    int64           `json:"contentLength"`
 	TransferEncoding []string        `json:"transferEncoding"`
 	Host             string          `json:"host"`
-	Form             url.Values      `json:"form"`
-	PostForm         url.Values      `json:"portForm"`
-	MultipartForm    *multipart.Form `json:"multipartForm"`
-	Trailer          http.Header     `json:"trailer"`
 	RemoteAddr       string          `json:"remoteAddr"`
 	RequestURI       string          `json:"requestURI"`
 }
@@ -40,10 +36,6 @@ func JSRequestInfoFromRequest(req *http.Request) *JSRequestInfo {
 		ContentLength:    req.ContentLength,
 		TransferEncoding: req.TransferEncoding,
 		Host:             req.Host,
-		Form:             req.Form,
-		PostForm:         req.PostForm,
-		MultipartForm:    req.MultipartForm,
-		Trailer:          req.Trailer,
 		RemoteAddr:       req.RemoteAddr,
 		RequestURI:       req.RequestURI,
 	}