diff --git a/docs/developer-guide/plugins-scenarios.md b/docs/developer-guide/plugins-scenarios.md index 1fd323cd6d..80d73fde30 100644 --- a/docs/developer-guide/plugins-scenarios.md +++ b/docs/developer-guide/plugins-scenarios.md @@ -97,7 +97,7 @@ chain.proceed(request). Otherwise a FORBIDDEN response is returned. } } -###Asynchronously transform response object +### Asynchronously transform response object Processing a HTTP response asynchronously is very similar to processing response synchronously. Instead of Rx map() operator, you'll use a flatMap(). In this example, we assume asyncOperation() makes a network call, performs I/O, diff --git a/docs/user-guide.md b/docs/user-guide.md index faa629ff5d..14806e40dc 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -2,12 +2,17 @@ # User Manual Welcome to Styx user manual. - - [Reverse Proxying](user-guide/reverse-proxying.md) - Overview of Styx proxy functionality. - + - [Basic Usage](user-guide/basic-usage.md) - Installing, Starting, and basic configuration of Styx. - + + - [Styx Reverse Proxy and Routing](user-guide/reverse-proxying.md) - Overview of Styx proxy functionality. + + - [Styx response codes](user-guide/response-codes.md) - List of possible response codes. + - [Configuration Overview](user-guide/configure-overview.md) - Overview of Styx configuration. + - [Backend services and origins](user-guide/configure-origins.md) - Configuration of a backend service and its origins. + - [Transport Layer Security](user-guide/configure-tls.md) - Configure TLS for Styx proxying. - [Load Balancing](user-guide/configure-load-balancing.md) - Configure load balancing. diff --git a/docs/user-guide/admin-interface.md b/docs/user-guide/admin-interface.md index 2bdf15d42c..750e888c17 100644 --- a/docs/user-guide/admin-interface.md +++ b/docs/user-guide/admin-interface.md @@ -2,6 +2,7 @@ One of main features of the Styx server available for users is an admin interface available "out of the box". It provides an HTTP interface with functionality that ease quick adaptation of the library. +Note that this endpoint must be externally secured. ## Endpoints available in the admin module * POST interface with set of predefined admin commands (see [section below](#postinterface)). @@ -33,19 +34,20 @@ All endpoints are available from the admin menu: `http:///admin/` ##### NOTE: -Endpoints that return `JSON` documents are compressed by default. To display documents prettified +Endpoints that return `JSON` documents are compressed by default. To display documents prettified, the `?pretty` option as an additional query parameter should be used: * `http:///admin/metrics?pretty` ## POST interface -Following commands can be sent to the Styx admin interface with HTTP POST requests. +The following commands can be sent to the Styx admin interface with HTTP POST requests. ### Reload Origins -This command will cause Styx to reload the origins if the file has meaningfully changed. If the file has not changed, - or the changes are purely cosmetic (such as adding comments), no action will be taken. +This command will cause Styx to reload the origins if the file has meaningfully changed. +If the file has not changed,or the changes are purely cosmetic (such as adding comments), +no action will be taken. #### Syntax: @@ -63,7 +65,6 @@ So if Styx was on port 8080 on localhost: `curl -X POST http://localhost:8080/admin/tasks/origins/reload` - ### Origin Toggle #### Enable Origin @@ -79,14 +80,14 @@ active immediately. ##### Parameters: * `STYX_SERVER_URL`: The host and port of the Styx Admin Interface -* `APP_ID`: The application the origin belongs to +* `APP_ID`: The backend service the origin belongs to * `ORIGIN_ID`: An origin to enable ##### How to execute command using curl: `curl -X POST http:///admin/tasks/origins?cmd=enable_origin&appId=&originId=` -So if Styx was on port 8080 on localhost and you wanted to enable an origin called "hwa1" for an app called "hwa": +So if Styx was on port 8080 on localhost and you wanted to enable an origin called "hwa1" for a backend service called "hwa": `curl -X POST http://localhost:8080/admin/tasks/origins?cmd=enable_origin&appId=hwa&originId=hwa1` @@ -101,14 +102,14 @@ The `disable_origin` command will disable an enabled origin. ##### Parameters: * `STYX_SERVER_URL`: The host and port of the Styx Admin Interface -* `APP_ID`: The application the origin belongs to +* `APP_ID`: The backend service the origin belongs to * `ORIGIN_ID`: An origin to disable ##### How to execute command using curl: `curl -X POST http:///admin/tasks/origins?cmd=disable_origin&appId=&originId=` -So if Styx was on port 8080 on localhost and you wanted to disable an origin called "hwa1" for an app called "hwa": +So if Styx was on port 8080 on localhost and you wanted to disable an origin called "hwa1" for a backend service called "hwa": `curl -X POST http://localhost:8080/admin/tasks/origins?cmd=disable_origin&appId=hwa&originId=hwa1` @@ -146,9 +147,9 @@ refer to [Plugins](../developer-guide/plugins.md) #### Syntax `http:///admin/dashboard/index.html` -Dashboard provides a visual representation of origins health. It lists all configured origins providing +Dashboard provides a visual representation of the origins health. It lists all configured origins providing information about the status of the underlying connection to each origin. Using this dashboard you can quickly -observe whether the origin is reachable, what is a quality of a connection etc. +observe whether the origin is reachable, what is the quality of a connection, etc. It also provides summarized information about error codes in current server uptime, both for the response from origins and from Styx. @@ -159,8 +160,9 @@ from origins and from Styx. `http:///admin/metrics` -Returns JSON document with server codahale metrics gathered in-memory by server instance. For more information on the concrete -metrics, please refer to [Metrics](metrics.md) and [Metrics Reference](metrics-reference.md) documents. +Returns JSON document with server metrics (from Dropwizard Metrics) gathered in-memory by server instance. +For more information on the concrete metrics, please refer to [Metrics](metrics.md) + and [Metrics Reference](metrics-reference.md) documents. ## JVM metrics @@ -175,8 +177,8 @@ Subset of metrics exposed by JVM that is running the Styx server instance. `http:///admin/configuration` -Provides settings document that presents what exact values are used to configure the running server instance. -For more details about content of this document please refer to [Configure overview](configure-overview.md). +This endpoint returns a textual representation of the settings configured in the running server instance. +For more details about the content of this document please refer to [Configure overview](configure-overview.md). ## Origin services configuration @@ -190,9 +192,9 @@ For more details about content of this document please refer to [Configure overv `http:///admin/origins/status` -This endpoint provides a similar information about as a GUI dashboard in a document form. It contains -a list of configured origin services and a status of underlying servers, which one are inactive and which ones were -disabled. +This endpoint provides similar information to the GUI dashboard but in document form. It contains +a list of configured backend services and the status of their underlying servers, stating which one are inactive +and which ones are disabled. ## Logging configuration @@ -208,20 +210,20 @@ The document returned by this endpoint presents the configuration used to setup `http:///admin/healthcheck` -Easy to query endpoint that returns a document with the health status of origins based on `500` errors rate. +Easy to query endpoint that returns a document with the health status of origins based on the rate of `500` errors. #### Syntax `http:///admin/status` -Deprecated endpoint, it returns short `OK` / `NOT_OK` based on an information that is also returned -by previous health-check endpoint. +Deprecated endpoint, it returns a short `OK` / `NOT_OK` based on the information returned +by the health-check endpoint. #### Syntax `http:///admin/ping` -This endpoint doesn't perform any checks, it only returns `pong` when the server is running. +This endpoint returns `pong` when the server is running, without performing any checks regarding the status. ## Running threads @@ -229,4 +231,4 @@ This endpoint doesn't perform any checks, it only returns `pong` when the server `http:///admin/threads` -For detailed monitoring this endpoint reports threads and their statuses running on the server. +This endpoint reports threads and their statuses running on the server. diff --git a/docs/user-guide/basic-usage.md b/docs/user-guide/basic-usage.md index a0405fcd50..728484df68 100644 --- a/docs/user-guide/basic-usage.md +++ b/docs/user-guide/basic-usage.md @@ -1,35 +1,46 @@ # Starting Styx +## Building Styx from source code + + In order to build styx from source code, Java 8 (1.8.0_45 or later) is required. + The build system requires Apache Maven. The Styx CI pipeline uses Maven version 3.2.1 + for the automated continuous integration builds. On Mac OSX, a version installed + by HomeBrew is satisfactory. + + The instructions are: + 1. Download the code from github + 2. Generate the artifact using maven. +``` +git clone https://github.com/HotelsDotCom/styx.git +cd styx && mvn package +``` + ## System Requirements -Building Styx requires Java 1.8. It can be built with 1.8.0_45. Earlier maintenance -releases may work, but are not guaranteed to. - -The build system requires Apache Maven. The Styx team uses Maven version 3.2.1 -for automated continuous integration builds. On Mac OSX, a version installed -by HomeBrew is satisfactory. +Running Styx requires Java 1.8. It can be run with 1.8.0_45 or later versions. Earlier maintenance +releases or Java 1.9 may work, but are not guaranteed to. ## Step 1: Installing Styx: Styx comes pre-packaged in a zip file. Extract the zip file to a directory of choice: - $ unzip styx.zip + $ unzip styx---.zip -This creates a subdirectory called `styx` that contains Styx binaries and a set - of configuration examples. Example configuration files can be found in `styx/conf` +This creates a subdirectory called `styx-` that contains Styx binaries and a set + of configuration examples. Example configuration files can be found in `styx-/conf` subdirectory. There are some files worth noticing: * `default.yml` - A Styx server configuration file. It specifies the Styx server port numbers and other application configuration. -* `styx/conf/origins` subdirectory containing examples of Styx origins configuration +* `conf/origins` subdirectory containing examples of Styx origins configuration files. A styx origins configuration file specifies the backend services for Styx. Especially, have a look at `origins-configuration-documentation.yml`. It explains - all aspects of origins configuration settings. + all aspects of origins configuration settings (you can see more details in [Backend services and origins](configure-origins.md)). -* `logback.xml` - Logging configuration file. There are more examples in the `styx/conf/logback` +* `logback.xml` - Logging configuration file. There are more examples in the `conf/logback` subdirectory. * `styx-env.sh` - JVM settings file. See section below. @@ -41,17 +52,17 @@ This creates a subdirectory called `styx` that contains Styx binaries and a set To start Styx, run the startup script from *bin/* directory, passing in the configuration file as an argument: - $ ./styx/bin/startup ~/configs/staging.yml + $ ./bin/startup conf/env-development/styx-config.yml -This starts Styx according to a configuration specified in *staging.yml* file. +This starts Styx according to the configuration specified in *staging.yml* file. -You also can specify the configuration via *STYX_CONFIG* environment +You also can specify the configuration via the `STYX_CONFIG` environment variable. For example: - STYX_CONFIG=~/configs/production.yml ./styx/bin/startup + STYX_CONFIG=conf/env-development/styx-config.yml ./bin/startup If the configuration file is not specified as a command line argument or as an environment -variable, Styx by default attempts to load configuration from *$STYX_HOME/conf/default.yaml*. +variable, Styx by default attempts to load its configuration from *$STYX_HOME/conf/default.yaml*. Once Styx has started up, it displays the Styx logo banner, followed by information about the port numbers it is listening on. @@ -74,12 +85,12 @@ script runs. Use this file as a "startup hook" to initialise Styx before it gets You can configure JVM settings, system properties, and any other installation that may be necessary before startup. -The styx startup script accepts an {-e} or {--env} command line option for specifying an alternative +The styx startup script accepts an `-e` or `--env` command line option for specifying an alternative Styx environment file: - $ ./bin/startup -e ~/configs/custom-env.sh + $ ./bin/startup -e conf/env-development/styx-env.sh -The custom environment file can also be specified via *STYX_ENV_FILE* environment variable. +The custom environment file can also be specified via the *STYX_ENV_FILE* environment variable. # Configuring Logging @@ -88,9 +99,9 @@ Styx uses [Logback style](https://logback.qos.ch/manual/index.html) configuratio configuration. By default, the logback file is loaded from *$STYX_HOME/conf/logback.xml*. You can specify an alternative -logging configuration file using {-l} or {--logback} command line options: +logging configuration file using `-l` or `--logback` command line options: - $ ./bin/startup --logback ~/configs/logback-custom.xml + $ ./bin/startup --logback conf/env-development/logback.xml You can also specify this via environment: *STYX_LOG_CONFIG*. @@ -152,7 +163,7 @@ Command line options are: Any environment variable starting with declares a command line option for the underlying Java Virtual Machine. The startup throws away the JVM_ part, and passes the - , verbatim, for the JVM as a command line option. + , verbatim, as a command line option for the JVM. diff --git a/docs/user-guide/configure-advanced-routing.md b/docs/user-guide/configure-advanced-routing.md index c0366feb57..19c5e8a519 100644 --- a/docs/user-guide/configure-advanced-routing.md +++ b/docs/user-guide/configure-advanced-routing.md @@ -54,9 +54,9 @@ two interceptors, in this case plugins: - *redirect-old-domain* - *bad-cookie-fixer* before -After this pipeline the traffic is handled by a *ConditionRouter* which -sends all traffic satisfying the condition *protocol() == "https" to -BackendServiceProxy called *secure-backends*, and all other traffic to +After this pipeline, the traffic is handled by a *ConditionRouter* which +sends all traffic satisfying the condition *protocol() == "https" to a +BackendServiceProxy called *secure-backends*, and all the other traffic to another BackendServiceProxy called *insecure-backends*. Graphically the object model can be represented as: @@ -82,21 +82,21 @@ Graphically the object model can be represented as: ## Concepts -Routing object model consist of *Http Handler* and *Interceptor* objects. +The routing object model consist of *Http Handler* and *Interceptor* objects. The *Http Handler* objects consume and handle HTTP requests in some -non-trivial ways, such as proxy the traffic to backend services, etc. +non-trivial ways, such as proxying the traffic to backend services, etc. The *InterceptorPipeline*, *ConditionRouter*, and a *BackendServiceProxy* in above example are all HTTP handlers. Some handlers like *InterceptorPipeline* or *ConditionRouter* can pass the traffic for other handlers to consume. -HTTP *Interceptor* objects are intended for performing simple actions +HTTP *Interceptor* objects are intended to perform simple actions (eg logging) or transforming requests and/or responses along the way (Rewrite). List of built-in handlers: - - BackendServiceProxy. It proxies to configured backends based on URL path prefix. + - BackendServiceProxy. It proxies to configured backends based on the URL path prefix. - HttpInterceptorPipeline. It runs the request through the interceptor pipeline before passing on to the next handler. - ProxyToBackend. It proxies to an individual configured backend service. - StaticResponseHandler. Responds with specified response. @@ -116,11 +116,11 @@ main styx configuration file. ### Routing Config Objects -Routing object model is configured in Yaml with *Routing Config Noders*. -It is either a *ROUTING-CONFIG-REF* which is a reference to another named -object, or a *ROUTING-CONFIG-DEF* that is block of of configuration. +Routing object model is configured in Yaml with *Routing Config Nodes*. +It is either a `ROUTING-CONFIG-REF` which is a reference to another named +object, or a `ROUTING-CONFIG-DEF` that is block of of configuration. -A *ROUTNG-CONFIG-DEF* has a common format of: +A `ROUTNG-CONFIG-DEF` has a common format of: ROUTING-CONFIG-DEF: name: @@ -130,7 +130,7 @@ A *ROUTNG-CONFIG-DEF* has a common format of: The list of types and their configuration layouts are specified below. -A *ROUTING-CONFIG-REF* is just a string that is supposed to reference +A `ROUTING-CONFIG-REF` is just a string that is supposed to reference to another routing config object, styx service, or plugin. @@ -139,7 +139,7 @@ to another routing config object, styx service, or plugin. Runs the configured interceptors (or plugins) before passing on to the next handler in the processing chain. -Configuration: +*Configuration*: name: type: InterceptorPipeline @@ -149,7 +149,7 @@ Configuration: handler: -Pipeline: +*Pipeline*: Routing config node list can have both routing config references and definitions mixed together. A routing config reference must always @@ -157,17 +157,17 @@ refer to a valid plugin name that has been declared in the Styx *plugins* section. A routing config definition can be used to insert styx built-in interceptors. -Handler: +*Handler*: This is a routing config definition block that defines the handler used. ### ConditionRouter -Subjects HTTP request to a set of tests, or *conditions*, that determine -which handler to pass the request next. +The Condition router subjects the HTTP request to a set of tests, or *conditions*, that determine +which handler to pass the request to next. -Configuration: +*Configuration*: name: type: ConditionRouter @@ -177,20 +177,20 @@ Configuration: fallback: -routes: +*Routes*: -This is a list of "routes" that activate based on the outcome of the conditions. +This block contains a list of destinations that are activated depending on the outcome of the conditions. CONDITION-DESTINATION: condition: destination: -Conditions are evaluated in order they appear in the routes list. +Conditions are evaluated in the order in which they appear in the routes list. The request is sent to the first destination that results in a positive match from the condition. -fallback: +*Fallback*: An optional field that specifies a handler which the request is sent when none of the configured routes match with the request. When fallback @@ -201,7 +201,7 @@ is absent, a *502 Bad Gateway* is returned by default. Proxies a request to a backend service. -Configuration: +*Configuration*: name: type: ProxyToBackend @@ -209,8 +209,8 @@ Configuration: backend: -The Styx HTTP backend definition follows the syntax of syntax -of backends in the origins file, but without the path attribute. +The Styx HTTP backend definition follows the syntax of backends in the origins file, + but without the path attribute. backend: id: "ba" @@ -224,7 +224,7 @@ of backends in the origins file, but without the path attribute. ### StaticResponseHandler -Responds with configured response. +Responds with a preconfigured response. name: type: StaticResponseHandler @@ -235,14 +235,14 @@ Responds with configured response. ### BackendServiceProxy -Standard path-prefix based backend service router/proxy. +Standard path-prefix based router/proxy to backend services. name: type: BackendServiceProxy config: backendProvider: -The backendProvider attribute must refer to a named backend service +The `backendProvider` attribute must refer to a named backend service in the `services` section. For example, to proxy between HTTP and HTTPS origins based on the incoming protocol: @@ -282,17 +282,17 @@ And in the services: ## Routing DSL -Routing DSL supports following functions: +The routing DSL supports the following functions: - method() - returns HTTP method name as a string - path() - returns URL path as a string - userAgent() - returns user agent header as a tring - protocol() - returns protocol (http, or https) as a string + method() - returns the HTTP method name as a string + path() - returns the URL path as a string + userAgent() - returns the user agent header as a tring + protocol() - returns the protocol (http, or https) as a string header(NAME) - returns a given header value cookie(NAME) - returns a given cookie name -The functions are always used in as a part of equivalency tests, +These functions are always used as a part of equivalency tests, so that the `ConditionRouter` predicate always evaluates to either true or false. @@ -330,7 +330,3 @@ User agent: userAgent() == "Mozilla Firefox 1.1.2" OR userAgent() =~ "Safari.*" - -## Example Configuration - -TBD diff --git a/docs/user-guide/configure-connection-pooling.md b/docs/user-guide/configure-connection-pooling.md index 353b7b7934..6919e3afb3 100644 --- a/docs/user-guide/configure-connection-pooling.md +++ b/docs/user-guide/configure-connection-pooling.md @@ -5,7 +5,7 @@ is created for each origin server. Connection pool settings are configured at the backend service level, and they are applied individually to each member origin server. -Conceptually Styx connection pool has two components: +Conceptually, a Styx connection pool has two components: * A pool of TCP connections * A queue of waiting subscribers. These are called *pending connections*. @@ -21,38 +21,42 @@ An example configuration block looks like this: connectionExpirationSeconds: 1000 # default value 0 -Connection pool size is given by *maxConnectionsPerHost* setting. -The pool initially has no established TCP connections. +## General settings. +* *maxConnectionsPerHost* : size of the connection pool for each origin server. +It is important to notice that, initially, the pool has no established TCP connections. They are created lazily when needed. -The two other parameters, *connectTimeoutMillis* and *socketTimeoutMillis* describe - * maximum allowed time for TCP connection establishment (*connectTimeoutMillis*) - * maximum amount of inactivity over the TCP connection before it should be closed - (*socketTimeoutMillis*). +* *connectTimeoutMillis*: maximum allowed time for TCP connection establishment. +* *socketTimeoutMillis*: maximum length of time a TCP connection can remain idle before being closed. +*Warning:* this property is reserved for future usage and not currently honoured by Styx. -The *connectionExpirationSeconds* setting allows connections to be terminated after a configured period of time has elapsed since the connection was created. +* *connectionExpirationSeconds*: allows connections to be terminated after the configured number of seconds has elapsed since the connection was created. This is useful when an origin host is specified as a DNS domain name, and you want to ensure that domain names are re-resolved periodically. If the value of the setting is non-positive, connections will not expire. Connection age is checked on each incoming request, so connections may live longer than their expiration time if they do not serve any requests. +## Connection pending settings. + When the connection pool gets full, any additional requests for the connections are queued. These requests are called *pending connections*. -The pending connection queue size is given by *maxPendingConnectionsPerHost* attribute. -The maximum time a connection can be "pending" is limited by the -*pendingConnectionTimeoutMillis* attribute. When this time expires, a connection -request is removed from the queue, resulting in a *503 Service Unavailable* response (1). + +* *maxPendingConnectionsPerHost*: maximum number of pending connections for an origin. + +* *pendingConnectionTimeoutMillis*: maximum time a connection can be "pending". +When this timeout expires, a connection request is removed from the queue, + resulting in a *503 Service Unavailable* response (1). # Metrics -Connection pool metrics are prefixed with `com.hotels.styx.$APPLICATION.$ORIGIN.connectionspool`. +Connection pool metrics are prefixed with `com.hotels.styx.$BACKEND_SERVICE.$ORIGIN.connectionspool`. - `busy-connections` - Number of currently borrowed connections. - `pending-connections` - Number of subscribers waiting in the pending connections queue. - `available-connections` - - Number of primed TCP connections readily available for consumers to borrow. + - Number of TCP connections readily available for consumers to borrow. - `connection-attempts` - Number of connection establishment attempts that have been initiated from the connection pool. This metric is incremented every time a new TCP connection @@ -64,10 +68,10 @@ Connection pool metrics are prefixed with `com.hotels.styx.$APPLICATION.$ORIGIN. - Number of connections closed by Styx, for whatever reason. - `connections-terminated` - Number of terminated connections, for whatever reason, including the connection - closures initiated by the remote peer. The number of connections terminated by + closures initiated by the remote peer. The number of connections terminated by a remote origin can be calculated as `terminated-connections` minus `closed-connections`. # Footnotes Footnote (1) Note however a [retry mechanism](configure-health-checks.md) kicks in -in this case, and the request will be re-attempted as per configured retry policy. +in this case, and the request will be re-attempted as per the configured retry policy. diff --git a/docs/user-guide/configure-health-checks.md b/docs/user-guide/configure-health-checks.md index 43b428a69b..2e12d9f21d 100644 --- a/docs/user-guide/configure-health-checks.md +++ b/docs/user-guide/configure-health-checks.md @@ -2,17 +2,17 @@ ## Introduction -Styx automatically monitors connectivity and health of configured +Styx automatically monitors the connectivity and health of configured backend services. This feature is called "health checking", and can be enabled or disabled by including a `healthCheck` attribute in a backend service configuration block. -Health checking is configured for a specific URI endpoint on a -backend service. Styx polls this endpoint, for every backend -service origin, at configured intervals. +Health checking is configured for a specific backend service, using the `uri` attribute +to indicate the URI of the health check endpoint. + Styx polls this endpoint, for every backend service origin, at configured intervals. -When an origin fails to respond to the poll from Styx `unhealthyThreshold` -times, Styx will mark the origin as *INACTIVE* and remove it from +When an origin fails to respond to the poll from Styx for `unhealthyThreshold` +times, Styx will mark the origin as *INACTIVE* and remove it from the load balancer rotation. Conversely, when an *INACTIVE* origin starts responding to the polls, it must respond at least `healthyThreshold` times before Styx moves it back into the *ACTIVE* state and puts it back into @@ -38,7 +38,7 @@ Styx from sending traffic to a potentially broken origin, the origin is initially enabled in an *INACTIVE* state. It gets activated only after health checks have confirmed the origin is healthy. -However, if the health checks are disabled, the origin will be activated +However, if health checks for the backend service are disabled, the origin will be activated straight away. @@ -79,7 +79,7 @@ into `BackendService`. ## Metrics -A meter of failed health check attempts per backend application: +A meter of failed health check attempts per backend service: origins.healthcheck.failure..count origins.healthcheck.failure..m1_rate diff --git a/docs/user-guide/configure-load-balancing.md b/docs/user-guide/configure-load-balancing.md index becc26983f..4f7607f045 100644 --- a/docs/user-guide/configure-load-balancing.md +++ b/docs/user-guide/configure-load-balancing.md @@ -9,25 +9,26 @@ Styx supports three load balancing strategies: Styx also provides a mechanism to bypass the load balancer and force the origin at source. +## Load balancing strategies -## Round Robin +### Round Robin -Cycles through available origins, choosing the next in sequence on each use, - skipping over the origins with saturated connection pools. +This mode cycles through available origins, choosing the next in sequence on each use, +while skipping over the origins with saturated connection pools. -## Busy +### Busy -This load balancing algorithm attempts to find a best origin -for serving the request, based on various instantaneous metrics like -number of readily available TCP connections, current pool usage, and +This load balancing algorithm attempts to find the best origin +to serve the request, based on various real-time metrics such as the number +of readily available TCP connections, current pool usage, and the observed 5xx response rate from the origins. -## Adaptive +### Adaptive Adaptive load balancing strategy is a combination of *Round Robin* and *Busy* strategies. It always starts off with *Round Robin*, and after a while it switches over to *Busy* strategy. It remains in *Busy* strategy until -a new origin is added to rotation. It then reverts to *Round Robin* adapts +a new origin is added to rotation. It then reverts to *Round Robin*, and adapts as described. ## Origins Restriction @@ -39,8 +40,8 @@ For example, to force a request to be forwarded to an origin called *landing-03*, you would add the origins restriction cookie to the request with a value of "landing-03". -The value can be set to a comma-separated list of regular expressions too. -In this case Styx proxies the request to any one of the origins matching +The value can also be set to a comma-separated list of regular expressions. +In that case, Styx proxies the request to any of the origins matching the specified regular expressions. To enable this feature, add `originRestrictionCookie` configuration @@ -49,13 +50,20 @@ attribute to the Styx proxy configuration file as follows: originRestrictionCookie: The *restriction-cookie-name* is a string value of your choice. It is -names the cookie Styx considers as an origins restriction cookie. +the name of the cookie that should contain the origins restriction information. ## Configuration Load balancing strategies and the origin restriction feature are configured in the Styx proxy configuration file. + +To enable Round Robin load balancing strategy: + + loadBalancing: + strategy: + factory: {class: "com.hotels.styx.client.loadbalancing.strategies.RoundRobinStrategy$Factory"} + To enable Busy load balancing strategy: loadBalancing: @@ -73,12 +81,6 @@ To enable Adaptive load balancing strategy: The *requestCount* attribute determines how long the adaptive strategy -remains in the Round Robin phase before switching over to *Busy* strategy. +remains in the Round Robin phase before switching over to the *Busy* strategy. Its value is the number of requests proxied *per origin*. -To enable Round Robin load balancing strategy: - - loadBalancing: - strategy: - factory: {class: "com.hotels.styx.client.loadbalancing.strategies.RoundRobinStrategy$Factory"} - diff --git a/docs/user-guide/configure-origins.md b/docs/user-guide/configure-origins.md new file mode 100644 index 0000000000..129d0bf5c8 --- /dev/null +++ b/docs/user-guide/configure-origins.md @@ -0,0 +1,179 @@ +# Configuring Backend Services and Origins + +## Configuration file + +Backend services and origins known to Styx are configured in their own YAML file, which is referenced by the main +configuration via the `originsFile` property in the services block. + +The value for this `originsFile` property accepts including environment variables (with the ${ENV_VAR} format) and can reference: + - A path in the filesystem by default. + - A resource in the classpath by using the prefix *classpath:*. + +### Examples: +Using the absolute path of the file: +```yaml +services: + factories: + backendServiceRegistry: + class: "com.hotels.styx.proxy.backends.file.FileBackedBackendServicesRegistry$Factory" + config: {originsFile: "${STYX_HOME}/conf/env-development/origins.yaml"} + ``` +Using a file in the classpath: +```yaml +services: + factories: + backendServiceRegistry: + class: "com.hotels.styx.proxy.backends.file.FileBackedBackendServicesRegistry$Factory" + config: {originsFile: "classpath:/conf/origins.yaml"} + ``` + +## Backend services + +Each service has the following properties: + +* **id**: a unique name used to identify backend services + +* **path**: the beginning of a (relative) URI used by Styx to determine which backend service to route a request to. + +* **healthCheck**: a group of parameters a relative URI for Styx to contact to determine whether an origin is "alive". + +* **origins**: a list of origins (instances of the backend service) + +* **stickySession**: a group of parameters enabling Styx to pin down an HTTP session to a specific origin. + Styx achieves this by inserting a session cookie in HTTP responses. + +* **connectionPool**: configuration for the connection pools used to communicate with this backend service. + +* **responseTimeoutMillis**: amount of time, in milliseconds, Styx waits for a response from origin. +Defaults to 60000 milliseconds. + +* **sslSettings**: Enables HTTPS for backend. + +## Health check +See [Health Checks](configure-health-checks.md) for details. + +The health check block has the following properties: + +* **uri**: a URI that Styx will attempt to connect to in order to make a health check + +* **intervalMillis**: the interval in between health checks in milliseconds + +* **healthyThreshold**: the number of times the health check must pass for an inactive origin to be declared active + +* **unhealthyThreshold**: the number of times the health check must pass for an active origin to be declared inactive + +## Sticky Session +See [Session Affinity](configure-session-affinity.md) for details. + +The sticky session block has the following properties: + +* **enabled**: Enables (true) or disables (false) sticky sessions. When absent, defaults to false. + +* **timeoutSeconds**: Styx pins an HTTP session to an origin by inserting a special cookie in HTTP responses. + TimeoutSeconds can be set to adjust the cookie expiry time, and it is the number of seconds since the most recent HTTP request. + If absent defaults to 43200 seconds, which is 12 hours. + +## Connection Pool +See [Connection Pooling](configure-connection-pooling.md) for details. + +The connection pool block has the following properties: + +* **maxConnectionsPerHost**: the maximum number of connections that may be established to a single origin + +* **maxPendingConnectionsPerHost**: the maximum number of connections that may be waiting to be established at the same time + +* **socketTimeoutMillis**: the maximum time Styx should wait to read from an origin + +* **connectTimeoutMillis**: the maximum time Styx should wait for a connection to be established + +* **pendingConnectionTimeoutMillis**: the maximum time to wait for a connection from the connection pool + +## Rewrites + +For the list of rewrites, each rewrite has two properties: **urlPattern** and **replacement**. An URL from the response is matched against configured urlPatterns, in the order they appear in the **rewrites** list. The first matching entry will be used to substitute existing URL with a new one according to the **replacement** template. + +* **urlPattern** - a regular expression, in Java syntax, that specifies the URL to be matched. This typically contains one or more capture groups. + +* **replacement** - specifies a template that describes how the URL is substituted. It may contain any literal text, together with special $1, $2, ... symbols. Any literal text will appear in the new URL as is, and any $1, $2, ... symbol will be substituted with a text captured by corresponding capture group from the **urlPattern**. + +If the request URL does not match any of the **urlPattern**s, the request retains its original URL. + +Because **urlPattern**s are matched in order they appear in the **rewrites** list, one needs to add the most specific pattern to the top of the list, and the least specific (i.e. most generic) pattern to the bottom of the list. + +## SSL Settings +See [Transport Layer Security](configure-tls.md) for details. + +The `sslSettings` is an optional configuration block. If present, it enables an HTTPS protocol between Styx and the + backend application. If absent, insecure HTTP protocol is used. The `sslSettings` has following attributes: + +* **trustAllCerts** - when `false` Styx authenticates the backend origin with configured certificates. + When `true` Styx doesn't authenticate the remote end. + +* **sslProvider** - Sets the SSL provider implementation. Defaults to `JDK`. + +* **addlCerts** - A list of additional certificates that are used to authenticate remote origins. Each certificate has two attributes: + + * **alias** - a descriptive name to identify the certificate. + + * **path** - a path to the certificate file. + +* **trustStorePath** - A path to Java truststore file containing trusted certificates for authenticating origins. + +* **trustStorePassword** - Password for keystore referred by **trustStorePath** attribute. + +Styx considers incoming traffic and outgoing traffic separately. It will convert between the HTTP and HTTPS protocols +when the incoming server side protocol differs from the outgoing origin side protocol. + +Limitations: + +* Styx does not support client side authentication for backend origins. Therefore the backend origins are unable to authenticate styx. + +## Origins + +For the list of origins, each origin has the following properties: + +* **id**: a unique name used to identify origins. + +* **host**: the hostname and port number that requests will be routed to. + +## + +## Example + +Here is the configuration for an example backend service: +```yaml + - id: "hwa" + path: "/" + healthCheck: + uri: "/version.txt" + intervalMillis: 10000 + healthyThreshold: 2 + unhealthyThreshold: 2 + stickySession: + enabled: true + timeoutSeconds: 14321 + connectionPool: + maxConnectionsPerHost: 300 + maxPendingConnectionsPerHost: 50 + socketTimeoutMillis: 11000 + connectTimeoutMillis: 12000 + pendingConnectionTimeoutMillis: 10000 + rewrites: + - urlPattern: "/hwa/(.*)/foobar/(.*)" + replacement: "/$1/barfoo/$2" + - urlPattern: "/hwa/(.*)" + replacement: "/$1" + sslSettings: + trustAllCerts: false + sslProvider: JDK + addlCerts: + - alias: "my certificate" + path: /path/to/mycert + - alias: "alt certificatfe" + path: /path/to/altcert + trustStorePath: /path/to/truststore + trustStorePassword: truststore-123 + origins: + - id: "hwa1" + host: "chhlapputle2e63.karmalab.net:7401" +``` \ No newline at end of file diff --git a/docs/user-guide/configure-overview.md b/docs/user-guide/configure-overview.md index 7b395e1d52..acef919afc 100644 --- a/docs/user-guide/configure-overview.md +++ b/docs/user-guide/configure-overview.md @@ -1,14 +1,17 @@ -## Configuring Styx environment +## Configuring Styx -Styx supports a YAML-based configuration. A yaml file can be specified using a system property `YAML_CONFIG_LOCATION=your/file/path`. -By default a file is taken from the classpath at `classpath:conf/environment/styx-config.yaml`. -Regardless of file location, these properties can all be overwritten using system properties by the same name. +Styx supports a YAML file-based configuration. The path to the YAML file can be passed +as a parameter to the startup script (`startup `) +or configured via the environment variable `STYX_CONFIG`. +By default, the file is read from `conf/default.yaml`. -### Example styx-config +Additionally, all these properties can be overwritten +using environment variables with the same name as the property. - --- +### Example styx-config +```yaml # A string uniquely identifying the host running the application, must be different for all running instances of the application # the default value is suitable only for non clustered environments jvmRouteName: "${jvm.route:noJvmRouteSet}" @@ -73,8 +76,9 @@ Regardless of file location, these properties can all be overwritten using syste expirationMillis: 10000 loadBalancing: - # Load balancer strategy type. Allowed values: "LEAST\_RESPONSE\_TIME", "ROUND\_ROBIN", and "ADAPTIVE". Defaults to "ROUND_ROBIN". - strategy: "ADAPTIVE" + strategy: #Check load balancing documentation for all the possible strategies + factory: {class: "com.hotels.styx.client.loadbalancing.strategies.BusyConnectionsStrategy$Factory"} + adaptive: @@ -122,14 +126,11 @@ Regardless of file location, these properties can all be overwritten using syste name: "X-Styx-Origin-Id" requestId: name: "X-Styx-Request-Id" - + ``` Without the comments, it looks like this: - - --- - - jvmRouteName: "${jvm.route:noJvmRouteSet}" - +```yaml + jvmRouteName: "${jvm.route:noJvmRouteSet}" proxy: connectors: - type: http @@ -188,4 +189,4 @@ Without the comments, it looks like this: name: "X-Styx-Origin-Id" requestId: name: "X-Styx-Request-Id" - +``` \ No newline at end of file diff --git a/docs/user-guide/configure-retry-mechanism.md b/docs/user-guide/configure-retry-mechanism.md index a84c856333..0307c164e9 100644 --- a/docs/user-guide/configure-retry-mechanism.md +++ b/docs/user-guide/configure-retry-mechanism.md @@ -1,23 +1,29 @@ # Retry Policy Configuration -Styx has a configurable retry policy. It attempts to re-send requests -under certain failure conditions, specifically when: +Styx has a configurable retry policy that is configured globally for the Styx server. +It attempts to re-send requests under certain failure conditions, +specifically when: - A TCP connection establishment for the chosen origin fails. - A connection has been pending (waiting at the connection pool) for the maximum allowed time (`pendingConnectionTimeoutMillis`). - - A connection pool's pending connection queue is full. However this is + - A connection pool's pending connection queue is full. However, this is unlikely unless Round Robin load balancing strategy is being used. The number of times Styx will retry a request is determined by the value of `count` in the configuration below. The default count is 1. -# Configuration +Styx provides a pluggable mechanism for retry policy implementations, so +a different implementation can be chosen with the `class` attribute, +but the only implementation bundled with Styx is + `com.hotels.styx.client.retry.RetryPolicyFactory` +# Configuration example +```yaml retrypolicy: policy: factory: class: "com.hotels.styx.client.retry.RetryPolicyFactory" config: {count: 2} - +``` \ No newline at end of file diff --git a/docs/user-guide/configure-session-affinity.md b/docs/user-guide/configure-session-affinity.md index d8608bb21b..4b551b06b8 100644 --- a/docs/user-guide/configure-session-affinity.md +++ b/docs/user-guide/configure-session-affinity.md @@ -1,11 +1,12 @@ # Session Affinity (aka Sticky Sessions) -Session affinity is configured on an application-by-application basis. It -allows requests by a client to an application to always be routed to the +Session affinity is configured at the backend service level. It +allows requests by a client to a backend service to always be routed to the same origin. This is also known as "sticky sessions" and is useful in -situations where sessions are not shared between instances. +situations where some state is stored server-side (i.e., with stateful services) + and sessions are not shared between instances (origins). -Our current implementation is cookie-based. For each application configured +Session affinity in Styx is cookie-based: for each backend service configured to use sticky sessions, the client receives a cookie. The value of the cookie tells Styx which origin to route to. If the client has no cookie, an origin will be assigned by the load balancer. Once they have a cookie, @@ -15,8 +16,8 @@ If Styx is unable to route to the specified origin, the load balancer will choose a new origin, and the client's cookie will be overwritten with the new value. -The *Session Affinity* is configured per application basis by including -the `stickySession` block into the Backend Service block. +The *Session Affinity* is configured per backend service via the + `stickySession` block inside the Backend Service block. # Configuration diff --git a/docs/user-guide/configure-tls.md b/docs/user-guide/configure-tls.md index 207fa201cc..cc0b6a2d9a 100644 --- a/docs/user-guide/configure-tls.md +++ b/docs/user-guide/configure-tls.md @@ -1,20 +1,19 @@ # Configuring Transport Layer Security -Transport Layer Security (TLS) can be enabled on Styx network -interfaces. You can enable it on the proxy server port, and also for -each of the backend services, where necessary. +Transport Layer Security (TLS) can be enabled on Styx both for the incoming interface +(connections from clients) and the connections with the backend services. -TLS can be enabled independently for each network interface. You can -enable it independently for proxy server port, and for each of the -back-end services. Styx will convert between the protocols where +TLS can be enabled independently for each port of the proxy server, +and for each of the backend services. +Styx will convert between the protocols where necessary. For example, if you have insecure HTTP traffic coming in, it will be converted to secure HTTPS if necessary. ## Server Side TLS Configuration -An example configuration block for enabling TLS security on Styx server +An example configuration block to enable TLS security on a Styx server port is shown below. Note that you can enable both HTTP and -TLS-protected HTTPS ports simultaneously. +TLS-protected HTTPS ports simultaneously (on different ports). ```yaml proxy: @@ -40,7 +39,7 @@ TLS-protected HTTPS ports simultaneously. - *port* - Server port number. Mandatory. - *sslProvider* - Specifies a Java service provider implementation for the TLS protocol. - Supported values are `JDK` and `OPENSSL`. Note that `OPENSSL` is a platform dependent + Supported values are `JDK` and `OPENSSL`. Note that `OPENSSL` is platform dependent (Linux/Mac/Windows) implementation and you must use an appropriate Styx build for your deployment target. @@ -48,17 +47,17 @@ TLS-protected HTTPS ports simultaneously. - *keyFile* - A PKCS#8 private key file in PEM format. - - *sessionCacheSize* - Sets the cache size for storing SSL session objects. + - *sessionCacheSize* - Sets the cache size for the storage of SSL session objects. Set `0` to use the default value. This is an optional attribute. When absent, it reverts to a default value. - *sessionTimeoutMillis* - Sets the timeout for the cached SSL session - objects, in seconds. Set `0` to use the default value. + objects, in milliseconds. Set `0` to use the default value. This is an optional attribute. When absent, it reverts to a default value. - *cipherSuites* - A list of enabled cipher suites, in order of preference. Leave absent to use the SSL provider defaults. - Note that the cipher suite names are specific to a SSL provider. + Note that the cipher suite names are specific to the SSL provider. - *protocols* - A list of TLS protocol versions to use. Use this attribute to enforce a more secure version like `TLSv1.2`. @@ -71,7 +70,7 @@ The accepted protocol names and cipher suite names for `JDK` provider are listed in [Oracle Java Cryptography Architecture documentation](https://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html). -## Backend Applications Configuration +## Backend Services Configuration HTTPS protocol is enabled by inserting a *tlsSettings* attribute in the backend services configuration, as follows: @@ -106,9 +105,12 @@ If your backend application exposes both HTTP and HTTPS endpoints, they must be specified as separate backends. -### Backend Application Attributes: +### Backend Service Attributes: + - - trustAllCerts - Whether (true) or not (false) to authenticate server side. + - *trustAllCerts* - When `trustAllCerts` is false, origin servers need to provide a + trusted certificate or the connection will be rejected. If true, all the server certificates + will be allowed. - *sslProvider* - Specifies a Java service provider implementation for the TLS protocol. Supported values are `JDK` and `OPENSSL`. Note that `OPENSSL` is a platform dependent @@ -116,42 +118,43 @@ be specified as separate backends. deployment target. - *addlCerts* - A list of additional certificates that can be specified - in addition to the certificates available in Trust Store. When Styx starts - up it creates an in-memory keystore and loads these certificates there. + in addition to the certificates available in the Trust Store. When Styx starts + up, it creates an in-memory keystore and loads these certificates there. Each specified certificate entry must have these two attributes: - - *alias* - A symbolic name for the certificate. Used as an alias for keystore. + - *alias* - A symbolic name for the certificate. Used as an alias in the keystore. - *path* - A path to the certificate file. - - *trustStorePath* - Styx can load the relevant secure material from Java truststore. - This attribute specifies a path to the keystore file containing relevant trust material. + - *trustStorePath* - Styx can load the list of trusted certificates from a Java truststore. This attribute specifies a path to the truststore. - *trustStorePassword* - A password for the keystore file specified in *trustStorePath* attribute. - *cipherSuites* - A list of enabled cipher suites, in order - of preference. Leave absent to use the SSL provider defaults. + of preference. Omit this property to use the SSL provider defaults. Note that the cipher suite names are specific to a SSL provider. - *protocols* - A list of TLS protocol versions to use. Use this attribute to enforce a more secure version like `TLSv1.2`. - When absent, enables all default protocols depending on the `sslProvider`. + When absent, enables all default protocols for the `sslProvider`. Possible protocol names are: `TLS`, `TLSv1`, `TLSv1.1`, and `TLSv1.2`. +Attributes that accept lists can be defined with the following format: ['ITEM1', 'ITEM2'] ## Troubleshooting TLS Configuration ### Failing SSL Handshake attempts on Styx server Unsuccessful SSL handshake attempts from remote clients to Styx server are logged by *HttpErrorStatusCauseLogger* -on *ERROR* level. The message contains a stack trace with keyword *SSLHandshakeException*. Content of the message -will vary depending on the configured SSL provider and the exact cause. To get an idea of failed handshake attempts -look for *SSLHandshakeException* in the logs. +at *ERROR* level. This error message contains a stack trace with the keyword *SSLHandshakeException*. +The content of this message will vary depending on the configured SSL provider and the exact cause. +To discover failed handshake attempts, look for *SSLHandshakeException* in the logs. -In addition to log, `styx.exception.io_netty_handler_codec_DecoderException` counter is also incremented. +Additionally, the`styx.exception.io_netty_handler_codec_DecoderException` counter is also incremented when a SSL + handshake error occurs. -An example stack trace might look like: +An example stack trace looks like: ``` ERROR 2018-01-22 08:59:49 [c.h.s.a.m.HttpErrorStatusCauseLogger] [Proxy-Worker-0-Thread] - Failure status="500 Internal Server Error" diff --git a/docs/user-guide/metrics-reference.md b/docs/user-guide/metrics-reference.md index 587deeedc2..c3b83ac216 100644 --- a/docs/user-guide/metrics-reference.md +++ b/docs/user-guide/metrics-reference.md @@ -1,3 +1,4 @@ +# Metrics Reference ## Server Side Metrics diff --git a/docs/user-guide/response-codes.md b/docs/user-guide/response-codes.md new file mode 100644 index 0000000000..5be9cee340 --- /dev/null +++ b/docs/user-guide/response-codes.md @@ -0,0 +1,41 @@ +# Styx Response Codes + +Styx responds with specific error codes when things don't go according to plan. + This refers only to responses generated by Styx itself, + not responses being proxied from downstream. + For a general explanation of 5xx (Server Error) codes, please see the HTTP Spec. + + Here is a summary of those codes: +![Styx 5xx Response Codes Diagram](../assets/styx-server-errors-diagram.png) + + +## 502 Bad Gateway + +* No route configured to backend service. An unexpected path prefix is received, + and no default backend has been configured. A default backend is one associated + with the "/" (root path) prefix. + +* There are no origin servers available for the backend service. For example, + all the origins for that service are marked as inactive. + +* Styx is unable to establish a TCP connection to an origin. + +* An invalid HTTP response is received from the backend origin server. + +* Origin does an *abortive TCP connection release* by setting the *RST* + bit on the TCP response segment. + + +## 503 Service Unavailable + +* The connection pool for the origin is full. That is, the maximum number of both busy connections + and pending (waiting) connections has been reached. + +* The connection pool for the origin is full and the connection has been pending + (waiting) for the maximum amount of time allowed by `pendingConnectionTimeoutMillis`. + + +## 504 Gateway Timeout + +* Styx has been waiting for a backend service origin to send data, but has not received anything + for `responseTimeout` milliseconds. \ No newline at end of file diff --git a/docs/user-guide/reverse-proxying.md b/docs/user-guide/reverse-proxying.md index bcb67b4f96..ea98ab129c 100644 --- a/docs/user-guide/reverse-proxying.md +++ b/docs/user-guide/reverse-proxying.md @@ -6,26 +6,27 @@ Styx is a reverse proxy server with a powerful, programmable *interceptor pipeline*. All received traffic is exposed to the interceptor pipeline before being proxied to the *Backend Services*. -The interceptor pipeline can extended with *plugins*. +The interceptor pipeline can be extended with *plugins*. The interceptor pipeline alters the way Styx handles the received traffic. The -pluggable nature with intuitive APIs makes it easy to implement custom HTTP proxy +pluggable nature with an intuitive API makes it easy to implement custom HTTP proxy applications on top of Styx. -At the end of the interceptors pipeline is a *Backend Services Router*. Using -a set of configurable rules it determines which backend service a received HTTP -request is proxied to. +At the end of the interceptors pipeline, there is a *Backend Services Router*. Using +a set of configurable rules, this router determines which backend service a received HTTP +request is proxied to. In this model, an *origin* server is each of the hosts implementing +a backend service. Some things to note about this model: * Request propagates through the pipeline in the order the interceptors (plugins) are configured in the pipeline. The response is intercepted in the reverse order. - * An interceptor may *modify*, *respond* or *drop* the request. A technical + * An interceptor may *modify*, *respond* or *drop* a request. A technical detail: *Typically interceptors wouldn't have to drop the request. They can simply respond with a relevant status code instead. However if a request is dropped, - Styx automatically responds on plugin's behalf.* + Styx automatically responds on the plugin's behalf.* * If the request makes it to the end of the interceptors pipeline, it is proxied to the relevant backend service. @@ -34,7 +35,7 @@ Some things to note about this model: ## Protocols Conversion Styx server can consume HTTP, HTTPS, or both protocols at the same time -(though on different ports). It terminates these protocols before passing the +(but on different ports). It terminates these protocols before passing the traffic to the interceptors pipeline. When Styx proxies a request to backend services, it sends the request over the @@ -53,51 +54,14 @@ full request before it can make a forwarding decision. The rest of the request ( body) will stream through Styx. However, the interceptor plugins can change this behaviour. They are able to store -and forward the request/response should it be necessary for the business requirements. +and forward the full request/response should it be necessary for the business requirements. Styx uses flow control to adapt the relative speeds of upstream and downstream -when proxying, protecting Styx from being overwhelmed when the sender +when proxying, and thus protecting Styx from being overwhelmed when the sender is sending faster than the receiver can consume. -## Styx Response Codes - -Styx responds with specific error codes when things don't go according to plan. -This refers only to responses generated by Styx itself, not responses being proxied from downstream. -For a general explanation of `5xx` (Server Error) codes, please see the [HTTP Spec](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html). -Here is a summary of those codes: - -![Styx 5xx Response Codes Diagram](../assets/styx-server-errors-diagram.png) - -#### 502 Bad Gateway - -* No route configured to backend service. An unexpected path prefix is received, - and no default backend has been configured. A default backend is one associated - with "/" (root path) prefix. - -* There are no origin servers available for the backend service. For example, - the origins are marked as inactive. - -* Styx is unable to establish a TCP connection to an origin. - -* Invalid HTTP response is received from the backend origin server. - -* Origin does an *abortive TCP connection release* by setting the *RST* - bit on the TCP response segment. - - -#### 503 Service Unavailable - -* The connection pool for the origin is full. That is, the maximum number of both busy connections - and pending (waiting) connections has been reached. - -* The connection pool for the origin is full and the connection has been pending - (waiting) for maximum amount of time allowed `pendingConnectionTimeoutMillis`. - - -#### 504 Gateway Timeout - -* Styx has been waiting for a backend service origin to send data, but has not received anything - for `responseTimeout` milliseconds. +## Response codes +For the list of possible response codes, see [Response codes](response-codes.md) \ No newline at end of file