Skip to content

Proxy

Jump to bottom
thiagobustamante edited this page Jul 5, 2017 · 30 revisions

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
interceptor Interceptors Configure request and response interceptors to be added to the request pipeline. 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
disableStats boolean If true, disable the statistical data recording for request accesses. false
statsConfig StatsConfig Configurations for this API stats. 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
parseReqBody boolean Allows you to control when to parse the request body. Just enable it if you need to access the request.body inside a proxy middleware, like a filter or interceptor. If disabled, the request is streamed to the target API, increasing performance. Defaults to 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

Interceptors

Configure request and response to the request pipeline.

It supports the following properties:

Property Type Description Required
request Interceptor[] A list of request interceptor names true
response Interceptor[] A list of response interceptor names true

Interceptor

Configure a request or response interceptor.

It supports the following properties:

Property Type Description Required
middleware MiddlewareConfig The Interceptor configuration. true
group string[] A list of group names that should be intercepted by this interceptor. If not provided, everything will be intercepted. false

Example:

{
    "proxy": {
        "target": {
            "host": "http://httpbin.org"
        },
        "interceptor": {
            "request": [
                {
                    "middleware": {
                        "name":"myRequestInterceptor"
                    }, 
                    "group": ["Group1"]
                },
                {
                    "middleware": {
                        "name":"mySecondRequestInterceptor"
                    }
                }
            ], 
            "response": [
                {
                    "middleware": {
                        "name":"myResponseInterceptor"}
                    }, 
                {
                    "middleware": {
                        "name":"SecondInterceptor"
                    }, "group": ["Group1"]
                }
            ] 
        },
        "timeout": 5000
    }
}

or

proxy:
  target:
    host: http://httpbin.org
  interceptor:
    request:
    - middleware:
        name: myRequestInterceptor
      group:
      - Group1
    - middleware:
        name: mySecondRequestInterceptor
    response:
    - middleware:
        name: myResponseInterceptor
    - middleware:
        name: SecondInterceptor
      group:
      - Group1
  timeout: 5000

Home

Install Gateway:

Configuring the Gateway:

APIs Configuration:

Gateway Configuration

Advanced Routing

Other Middlewares

Middlewares:

Clone this wiki locally