### Request Passport Example

Source: https://github.com/netflix/zuul/wiki/Core-Features

An example of a Zuul request passport, showing the time-ordered states a request transitions through. This is a valuable tool for debugging.

```text
CurrentPassport {start_ms=1523578203359,
[+0=IN_REQ_HEADERS_RECEIVED,
+260335=FILTERS_INBOUND_START,
+310862=IN_REQ_LAST_CONTENT_RECEIVED,
+1053435=MISC_IO_START,
+2202112=MISC_IO_STOP,
+3917598=FILTERS_INBOUND_END,
+4157288=ORIGIN_CH_CONNECTING,
+4218319=ORIGIN_CONN_ACQUIRE_START,
+4443588=ORIGIN_CH_CONNECTED,
+4510115=ORIGIN_CONN_ACQUIRE_END,
+4765495=OUT_REQ_HEADERS_SENDING,
+4799545=OUT_REQ_LAST_CONTENT_SENDING,
+4820669=OUT_REQ_HEADERS_SENT,
+4822465=OUT_REQ_LAST_CONTENT_SENT,
+4830443=ORIGIN_CH_ACTIVE,
+20811792=IN_RESP_HEADERS_RECEIVED,
+20961148=FILTERS_OUTBOUND_START,
+21080107=IN_RESP_LAST_CONTENT_RECEIVED,
+21109342=ORIGIN_CH_POOL_RETURNED,
+21539032=FILTERS_OUTBOUND_END,
+21558317=OUT_RESP_HEADERS_SENDING,
+21575084=OUT_RESP_LAST_CONTENT_SENDING,
+21594236=OUT_RESP_HEADERS_SENT,
+21595122=OUT_RESP_LAST_CONTENT_SENT,
+21659271=NOW]}
```

--------------------------------

### Run Zuul Benchmark Mode

Source: https://github.com/netflix/zuul/wiki/Benchmarking

Execute the Gradle task to start the Zuul sample application in benchmark mode. This command is used to initiate performance testing.

```bash
./gradlew run -Pbench
```

--------------------------------

### Example of Successful Request Attempt

Source: https://github.com/netflix/zuul/wiki/Core-Features

This JSON represents a successful request attempt to an origin. It includes status, duration, attempt number, and origin details.

```json
[{"status":200,"duration":192,"attempt":1,"region":"us-east-1","asg":"simulator-v154","instanceId":"i-061db2c67b2b3820c","vip":"simulator.netflix.net:7001"}]
```

--------------------------------

### Example of Failed Request Attempts

Source: https://github.com/netflix/zuul/wiki/Core-Features

This JSON shows multiple failed request attempts to an origin, including error codes and exception types. It's useful for diagnosing persistent origin issues.

```json
[{"status":503,"duration":142,"attempt":1,"error":"ORIGIN_SERVICE_UNAVAILABLE","exceptionType":"OutboundException","region":"us-east-1","asg":"simulator-v154","instanceId":"i-061db2c67b2b3820c","vip":"simulator.netflix.net:7001"},
{"status":503,"duration":147,"attempt":2,"error":"ORIGIN_SERVICE_UNAVAILABLE","exceptionType":"OutboundException","region":"us-east-1","asg":"simulator-v154","instanceId":"i-061db2c67b2b3820c","vip":"simulator.netflix.net:7001"}]
```

--------------------------------

### Get CurrentPassport from Session Context

Source: https://github.com/netflix/zuul/wiki/Core-Features

Retrieves the CurrentPassport object from the session context. This method is an alternative to getting it from the channel.

```java
CurrentPassport passport = CurrentPassport.fromSessionContext(context);
```

--------------------------------

### Get Zuul Status Category

Source: https://github.com/netflix/zuul/wiki/Core-Features

Use StatusCategoryUtils to retrieve the status category from a response object. This is useful for analyzing the outcome of a proxied request.

```java
StatusCategoryUtils.getStatusCategory(response)
```

--------------------------------

### Get CurrentPassport from Channel

Source: https://github.com/netflix/zuul/wiki/Core-Features

Retrieves the CurrentPassport object from the channel context. This is useful for accessing request-specific information within filters.

```java
CurrentPassport passport = CurrentPassport.fromChannel(channel);
```

--------------------------------

### Get Request Attempts from Session Context

Source: https://github.com/netflix/zuul/wiki/Core-Features

Retrieves the RequestAttempts object from the session context. This is typically used in outbound filters to inspect the history of origin requests.

```java
// from context
RequestAttempts attempts = RequestAttempts.getFromSessionContext(context);
```

--------------------------------

### Run the Zuul Sample Application

Source: https://github.com/netflix/zuul/wiki/Getting-Started-3.0

Use this Gradle command to run the sample application included in the Zuul repository.

```bash
$ ./gradlew run
```

--------------------------------

### Build Zuul from Source

Source: https://github.com/netflix/zuul/wiki/Getting-Started-3.0

Clone the Zuul repository and use Gradle to build the project. This command checks out the source and compiles it.

```bash
$ git clone git@github.com:Netflix/zuul.git
$ cd zuul/
$ ./gradlew build
```

--------------------------------

### Perform a Clean Build of Zuul

Source: https://github.com/netflix/zuul/wiki/Getting-Started-3.0

Execute this command to clean the build artifacts and then build the Zuul project using Gradle.

```bash
$ ./gradlew clean build
```

--------------------------------

### Configure Ribbon Client Buffer Sizes

Source: https://github.com/netflix/zuul/wiki/Core-Features

Set the receive and send buffer sizes for Ribbon clients. These properties control the amount of data that can be buffered during network communication.

```properties
<originName>.ribbon.ReceiveBufferSize                // default: 32 * 1024
<originName>.ribbon.SendBufferSize                   // default: 32 * 1024
```

--------------------------------

### Configure Ribbon Client Max Connections

Source: https://github.com/netflix/zuul/wiki/Core-Features

Configure the maximum number of connections per host and idle connection eviction time for Ribbon clients. These settings help manage resource usage and prevent stale connections.

```properties
<originName>.ribbon.MaxConnectionsPerHost            // default: 50
<originName>.ribbon.ConnIdleEvictTimeMilliSeconds    // default: 60000 (ms)
```

--------------------------------

### Configure Static Server List in Zuul

Source: https://github.com/netflix/zuul/wiki/Core-Features

Configure Zuul to use a static list of servers for load balancing when not using Eureka. This requires specifying the server list directly and using a different server list class.

```properties
eureka.shouldFetchRegistry=false

api.ribbon.listOfServers=100.66.23.88:7001,100.65.155.22:7001
api.ribbon.client.NIWSServerListClassName=com.netflix.loadbalancer.ConfigurationBasedServerList
api.ribbon.DeploymentContextBasedVipAddresses=api-test.netflix.net:7001
```

--------------------------------

### Update javax.inject to jakarta.inject

Source: https://github.com/netflix/zuul/wiki/Upgrade-Guide-3.0

Update your dependency references from javax.inject to jakarta.inject. This is a necessary change due to the migration from javax to jakarta namespaces.

```text
javax.inject:javax.inject:1
to
jakarta.inject:jakarta.inject-api:2.0.1
```

--------------------------------

### Configure Per Server Concurrency

Source: https://github.com/netflix/zuul/wiki/Core-Features

Ribbon configuration property for setting the maximum number of concurrent connections allowed per host for a given origin.

```properties
<originName>.ribbon.MaxConnectionsPerHost                // default: 50
```

--------------------------------

### Configure Overall Origin Concurrency

Source: https://github.com/netflix/zuul/wiki/Core-Features

Configuration properties for setting the maximum number of concurrent requests allowed for an origin and enabling concurrency protection.

```properties
zuul.origin.<originName>.concurrency.max.requests        // default: 200
zuul.origin.<originName>.concurrency.protect.enabled     // default: true
```

--------------------------------

### Configure Eureka Service Discovery in Zuul

Source: https://github.com/netflix/zuul/wiki/Core-Features

Configure Zuul to use Eureka for service discovery by specifying Eureka server details and context. This allows Zuul to dynamically discover backend services.

```properties
eureka.shouldUseDns=true
eureka.eurekaServer.context=discovery/v2
eureka.eurekaServer.domainName=discovery${environment}.netflix.net
eureka.eurekaServer.gzipContent=true

api.ribbon.NIWSServerListClassName=com.netflix.niws.loadbalancer.DiscoveryEnabledNIWSServerList
api.ribbon.DeploymentContextBasedVipAddresses=api-test.netflix.net:7001
```

--------------------------------

### Configure Ribbon Client Connection Timeouts

Source: https://github.com/netflix/zuul/wiki/Core-Features

Set connection and read timeouts for Ribbon clients. These properties control how long Zuul will wait for a connection to be established and for a response to be received from a backend server.

```properties
<originName>.ribbon.ConnectTimeout                   // default: 500 (ms)
<originName>.ribbon.ReadTimeout                      // default: 90000 (ms)
```

--------------------------------

### Configure Zuul Proxy Protocol Settings

Source: https://github.com/netflix/zuul/wiki/Core-Features

Configure Zuul to use Proxy Protocol for client IP identification. This is useful when running behind a TCP listener.

```java
channelConfig.set(CommonChannelConfigKeys.allowProxyHeadersWhen, StripUntrustedProxyHeadersHandler.AllowWhen.NEVER);
```

```java
channelConfig.set(CommonChannelConfigKeys.preferProxyProtocolForClientIp, true);
```

```java
channelConfig.set(CommonChannelConfigKeys.withProxyProtocol, true);
```

--------------------------------

### Configure Netty Client Connections Per Server

Source: https://github.com/netflix/zuul/wiki/Core-Features

Configure the maximum number of connections Zuul's Netty client will maintain to a single server, per event loop. This setting impacts concurrency and resource utilization.

```properties
# Max amount of connection per server, per event loop
<originName>.netty.client.perServerWaterline          // default: 4
```

--------------------------------

### Configure Ribbon Client IP Address Usage

Source: https://github.com/netflix/zuul/wiki/Core-Features

Determine whether to use the IP address for identifying backend servers in Ribbon clients. This can affect how Zuul resolves and connects to services.

```properties
<originName>.ribbon.UseIPAddrForServer               // default: true
```

--------------------------------

### Log Timeout Event in CurrentPassport

Source: https://github.com/netflix/zuul/wiki/Core-Features

This log shows a CurrentPassport with a read timeout event on the origin channel. It details the sequence of events leading up to and following the timeout.

```plaintext
CurrentPassport {start_ms=1523578490446,
[+0=IN_REQ_HEADERS_RECEIVED,
+139712=FILTERS_INBOUND_START,
+1364667=MISC_IO_START,
+2235393=MISC_IO_STOP,
+3686560=FILTERS_INBOUND_END,
+3823010=ORIGIN_CH_CONNECTING,
+3891023=ORIGIN_CONN_ACQUIRE_START,
+4242502=ORIGIN_CH_CONNECTED,
+4311756=ORIGIN_CONN_ACQUIRE_END,
+4401724=OUT_REQ_HEADERS_SENDING,
+4453035=OUT_REQ_HEADERS_SENT,
+4461546=ORIGIN_CH_ACTIVE,
+45004599181=ORIGIN_CH_READ_TIMEOUT,
+45004813647=FILTERS_OUTBOUND_START,
+45004920343=ORIGIN_CH_CLOSE,
+45004945985=ORIGIN_CH_CLOSE,
+45005052026=ORIGIN_CH_INACTIVE,
+45005246081=FILTERS_OUTBOUND_END,
+45005359480=OUT_RESP_HEADERS_SENDING,
+45005379978=OUT_RESP_LAST_CONTENT_SENDING,
+45005399999=OUT_RESP_HEADERS_SENT,
+45005401335=OUT_RESP_LAST_CONTENT_SENT,
+45005486729=NOW]}
```

--------------------------------

### Add Zuul Core Dependency for Gradle

Source: https://github.com/netflix/zuul/wiki/Getting-Started-3.0

Use this line in your Gradle project's build script to include the Zuul core library.

```gradle
compile "com.netflix.zuul:zuul-core:3.0.0"
```

--------------------------------

### Configure Proxy Headers in Zuul HTTP Mode

Source: https://github.com/netflix/zuul/wiki/Server-Configuration

Use this setting to strip untrusted proxy headers when running Zuul in plaintext HTTP mode without an ELB. This enhances security by preventing the acceptance of potentially malicious headers.

```java
channelConfig.set(CommonChannelConfigKeys.allowProxyHeadersWhen, StripUntrustedProxyHeadersHandler.AllowWhen.NEVER);
```

--------------------------------

### Log Failed Request with Retries in CurrentPassport

Source: https://github.com/netflix/zuul/wiki/Core-Features

This log shows a CurrentPassport for a failed request, including multiple origin connection attempts, retries, and eventual exceptions. It's useful for debugging request failures and understanding retry behavior.

```plaintext
CurrentPassport {start_ms=1523578533258,
[+0=IN_REQ_HEADERS_RECEIVED,
+161428=FILTERS_INBOUND_START,
+208805=IN_REQ_LAST_CONTENT_RECEIVED,
+934637=MISC_IO_START,
+1751747=MISC_IO_STOP,
+2606657=FILTERS_INBOUND_END,
+2734497=ORIGIN_CH_CONNECTING,
+2780877=ORIGIN_CONN_ACQUIRE_START,
+3181771=ORIGIN_CH_CONNECTED,
+3272876=ORIGIN_CONN_ACQUIRE_END,
+3376958=OUT_REQ_HEADERS_SENDING,
+3405924=OUT_REQ_LAST_CONTENT_SENDING,
+3557967=ORIGIN_RETRY_START,
+3590208=ORIGIN_CH_CONNECTING,
+3633635=ORIGIN_CONN_ACQUIRE_START,
+3663060=ORIGIN_CH_CLOSE,
+3664703=OUT_REQ_HEADERS_ERROR_SENDING,
+3674443=OUT_REQ_LAST_CONTENT_ERROR_SENDING,
+3681289=ORIGIN_CH_ACTIVE,
+3706176=ORIGIN_CH_INACTIVE,
+4022445=ORIGIN_CH_CONNECTED,
+4072050=ORIGIN_CONN_ACQUIRE_END,
+4144471=OUT_REQ_HEADERS_SENDING,
+4171228=OUT_REQ_LAST_CONTENT_SENDING,
+4186672=OUT_REQ_HEADERS_SENT,
+4187543=OUT_REQ_LAST_CONTENT_SENT,
+4192830=ORIGIN_CH_ACTIVE,
+4273401=ORIGIN_CH_EXCEPTION,
+4274124=ORIGIN_CH_EXCEPTION,
+4303020=ORIGIN_CH_IO_EX,
+4537569=FILTERS_OUTBOUND_START,
+4646348=ORIGIN_CH_CLOSE,
+4748074=ORIGIN_CH_INACTIVE,
+4957163=FILTERS_OUTBOUND_END,
+4968947=OUT_RESP_HEADERS_SENDING,
+4985532=OUT_RESP_LAST_CONTENT_SENDING,
+5003476=OUT_RESP_HEADERS_SENT,
+5004610=OUT_RESP_LAST_CONTENT_SENT,
+5062221=NOW]}
```

--------------------------------

### Add Zuul Core Dependency for Maven

Source: https://github.com/netflix/zuul/wiki/Getting-Started-3.0

Include this XML snippet in your Maven project's pom.xml to add the Zuul core library.

```xml
<dependency>
    <groupId>com.netflix.zuul</groupId>
    <artifactId>zuul-core</artifactId>
    <version>3.0.0</version>
</dependency>
```

--------------------------------

### Configure Netty Client Max Requests Per Connection

Source: https://github.com/netflix/zuul/wiki/Core-Features

Set the maximum number of requests that can be processed over a single persistent connection before it is closed. This is a Zuul-specific Netty client configuration.

```properties
# Max amount of requests any given connection will have before forcing a close
<originName>.netty.client.maxRequestsPerConnection    // default: 1000
```

--------------------------------

### Set Zuul Status Category

Source: https://github.com/netflix/zuul/wiki/Core-Features

Use StatusCategoryUtils to set the status category for a request context. This allows for more granular failure reporting than standard HTTP statuses.

```java
StatusCategoryUtils.setStatusCategory(request.getContext(), ZuulStatusCategory.SUCCESS)
```

--------------------------------

### Retrieve Client IP from Channel

Source: https://github.com/netflix/zuul/wiki/Core-Features

Retrieve the client IP address directly from the channel when Proxy Protocol is enabled.

```java
String clientIp = channel.attr(SourceAddressChannelHandler.ATTR_SOURCE_ADDRESS).get();
```

--------------------------------

### Buffer Request/Response Body in Zuul Filter

Source: https://github.com/netflix/zuul/wiki/Filters

Override `needsBodyBuffered()` to true to enable buffering of the request or response body within an inbound or outbound filter. This is necessary if your filter logic needs to access the body content.

```java
    @Override
    boolean needsBodyBuffered(HttpResponseMessage input) {
        return true
    }
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.