Proxy

Configure how requests must be proxied to the target API.

The Proxy configuration object must be included in the API config and supports the following properties:

Property	Type	Description	Required
target	Target	The target of the proxied API.	true
httpAgent	HttpAgent	Configure the http.Agent used by proxy requests.	false
supressViaHeader	boolean	Tree Gateway adds a Via header on response by default. Yhis option can be used to disable it.	false
preserveHostHdr	boolean	If true, the gateway will copy the host HTTP header to the proxied express server.	false
timeout	string or number	Configure a specific timeout for requests. Timed-out requests will respond with 504 status code and a X-Timeout-Reason header. You can inform the amount of milisencods, or use a human-interval string	false
limit	string	This sets the body size limit (default: 1mb). If the body size is larger than the specified (or default) limit, a 413 Request Entity Too Large error will be returned. See bytes.js for a list of supported formats. This option is ignored if parseReqBody is false.	false

Target

Configure the target of the proxied API.

It supports the following properties:

Property	Type	Description	Required
host	string	The proxy target host.	false
router	ProxyRouter	A Router middleware to decide how to route the requests.	false
allow	string[]	A list of group names that is allowed to access the target API.	false
deny	string[]	A list of group names that is not allowed to access the target API.	false

Note that you must define one of host or route properties.

Example:

{
    "proxy": {
        "target": {
            "host": "httpbin.org",
            "allow": ["Group1"],
            "deny": ["Group2"]
        },
        "timeout": "five seconds"
    }    
}

or

proxy:
  target:
    host: httpbin.org
    allow:
    - Group1
    deny:
    - Group2
  timeout: five seconds

ProxyRouter

Defines dynamic routing for the proxy through a ProxyRouter and ServiceDiscovery middlewares.

Can have the following properties:

Property	Type	Description	Required
ssl	boolean	Inform if the targets returned by the middleware should be invoked using ssl (https).	fasle
middleware	MiddlewareConfig	The ProxyRouter middleware configuration.	false
serviceDiscovery	MiddlewareConfig	The ServiceDiscovery middleware configuration.	false

Note that you must define at least one of middleware and serviceDiscovery middleware for the proxy router.

Middleware Example:

{
    "proxy": {
        "target": {
            "router": {
                "middleware": {
                    "name": "trafficSplit",
                    "options": {
                        "destinations": [{
                            "target": "http://httpbin.org", 
                            "weight": 75
                        },
                        {
                            "target": "http://httpbin.org/anything", 
                            "weight": 25
                        }]
                    }
                }
            }
        },
        "timeout": "five seconds"
    }    
}

or

proxy:
  target:
    router:
      middleware:
        name: trafficSplit
        options:
          destinations: 
            - target: http://httpbin.org
              weight: 75
            - target: http://httpbin.org/anything
              weight: 25
  timeout: five seconds

Service Discovery:

Example:

{
    "proxy": {
        "target": {
            "router": {
                "serviceDiscovery": {
                    "name": "consul",
                    "options": {
                        "serviceName": "testService"
                    }
                }
            }
        },
        "timeout": "five seconds"
    }    
}

or

proxy:
  target:
    router:
      serviceDiscovery:
        name: consul
        options:
          serviceName: testService
  timeout: five seconds

You must ensure that a service discovery provider is configured for the serviceDiscovery name consul on GatewayConfig.

You can use, also, both a proxy router and a serviceDiscovery middlewares. In this situation, the destination resolved by the proxy router is passed as input to the serviceDiscovery middleware. For example:

{
    "proxy": {
        "target": {
            "router": {
                "middleware": {
                    "name": "trafficSplit",
                    "options": {
                        "destinations": [
                            {
                                "target": "testService_v1",
                                "weight": 97
                            },
                            {
                                "target": "testService_v2",
                                "weight": 3
                            }
                        ]
                    }
                },
                "serviceDiscovery": {
                    "name": "consul",
                    "options": {
                        "serviceName": "testService",
                        "loadBalancer": "round-robin"
                    }
                }
            }
        },
        "timeout": "five seconds"
    }
}

or

proxy:
  target:
    router:
      middleware:
        name: trafficSplit
        options:
          destinations: 
            - target: testService_v1
              weight: 97
            - target: testService_v2
              weight: 3
      serviceDiscovery:
        name: consul
        options:
          serviceName: testService
          loadBalancer: round-robin
  timeout: five seconds

This last example will route the requests sending 97% of the requests to the service testService_v1 and only 3% for the testService_v2. Then the service discovery middleware will find available nodes for the requested service and use a round-robin load balancer to choose one between these nodes.

Advanced Routing

Tree Gateway provide some middlewares to perform common tasks like request or response body transformations, traffic spliting, ip filtering and service discovery.

HttpAgent

Configure the http.Agent used by proxy requests.

Can have the following properties:

Property	Type	Description	Required
keepAlive	boolean	Keep sockets around in a pool to be used by other requests in the future. Defaults to true.	fasle
keepAliveTime	string or number	When using HTTP KeepAlive, how often to send TCP KeepAlive packets over sockets being kept alive. You can inform the amount of milisencods, or use a human-interval string. Default = 'one second'. Only relevant if keepAlive is set to true.	fasle
freeSocketKeepAliveTimeout	string or number	Sets the free socket to timeout after freeSocketKeepAliveTimeout milliseconds of inactivity on the free socket. You can inform the amount of milisencods, or use a human-interval string. Default is '15 seconds'. Only relevant if keepAlive is set to true.	fasle
timeout	string or number	Sets the working socket to timeout after timeout milliseconds of inactivity on the working socket. You can inform the amount of milisencods, or use a human-interval string. Default is freeSocketKeepAliveTimeout * 2.	fasle
maxSockets	number	Maximum number of sockets to allow per host. Default = Infinity.	fasle
maxFreeSockets	number	Maximum number of sockets to leave open in a free state. Only relevant if keepAlive is set to true. Default = 256.	fasle

Example:

{
    "proxy": {
        "target": {
            "host": "http://localhost:9000"
        },
        "httpAgent": {
            "keepAlive": true,
            "keepAliveTime": "one second",
            "freeSocketKeepAliveTimeout": "30 seconds",
            "maxFreeSockets": 10,
            "maxSockets": 200,
            "timeout": "one minute"
        }
    }
}

or

proxy:
  target:
    host: http://localhost:9000
  httpAgent:
    keepAlive: true
    keepAliveTime: one second
    freeSocketKeepAliveTimeout: 30 seconds
    maxFreeSockets: 10
    maxSockets: 200
    timeout: one minute