Core Concepts

The fundamental building blocks of Nolxy: how requests flow through the gateway, how routes are matched, and how each layer of protection and optimization works.

Request Lifecycle

Client → ProxyShield → Auth → Rate Limit → Early Cache → Transform → Proxy → Circuit Breaker → Response Cache → Client

Each request passes through every layer in order. Short-circuit exits (cache hit, rate limit exceeded, circuit open) skip downstream layers entirely.

Routes & Proxying

A Route maps a public path on Nolxy to an upstream backend URL. All traffic matching the path and method is forwarded upstream with the original headers, body, and query string intact.

Path

Public endpoint pattern. Supports wildcards (*) and named params (:id). Matched against the incoming request path.

Target URL

Upstream backend URL. The matched path suffix is appended automatically (e.g. /api/* → https://backend.com/api/users).

Methods

Allowed HTTP methods. Requests using other methods receive 405 Method Not Allowed.

Timeout

Maximum upstream response time in milliseconds. Requests exceeding this receive 504 Gateway Timeout.

Backend Secret

Optional header injected on every upstream request (e.g. X-Internal-Secret: …). Lets your backend verify traffic comes from Nolxy.

Circuit Breaker

The circuit breaker prevents cascading failures by stopping requests to an unhealthy upstream. State is stored in Redis so all workers share the same view. Three states: CLOSED (normal), OPEN (blocking), HALF-OPEN (probing).

Failure Threshold

Number of consecutive failures before the circuit opens. Counts 5xx responses and timeouts.

Monitoring Window

Time window (seconds) over which failures are counted. Resets on successful response.

Success Threshold

Number of consecutive successes in HALF-OPEN state required to close the circuit.

Open Timeout

How long (seconds) the circuit stays OPEN before transitioning to HALF-OPEN for a probe request.

When the circuit is OPEN, Nolxy returns 503 Service Unavailable immediately without hitting the upstream. A webhook notification is sent when the circuit opens and when it recovers.

Response Caching

Two-tier response cache: L1 in-memory LRU (per worker) and L2 Redis (shared across workers). Cache is checked before the proxy — a HIT never reaches the upstream.

Cacheable Methods

Only GET and HEAD requests are cached by default.

TTL

Cache entry lifetime in seconds. Configurable per route. Expired entries are evicted lazily.

Cacheable Status Codes

Only 200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501 are cached.

Cache Key Headers

Optional list of request headers included in the cache key (e.g. Accept-Language). Enables per-locale caching.

Max Body Size

Responses larger than the configured limit are not cached. Prevents memory exhaustion from large payloads.

The X-Cache response header indicates HIT, MISS, or BYPASS. Cache is invalidated automatically when the route configuration changes.

Automatic Retries

Nolxy can automatically retry failed upstream requests with exponential backoff. Only safe, idempotent methods are retried by default.

Retry Count

Maximum number of retry attempts. Each retry uses exponential backoff: delay × 2^attempt.

Initial Delay

Base delay in milliseconds before the first retry. Subsequent retries double this value.

Retry On

Conditions that trigger a retry: 5xx responses, connection errors, and timeouts. 4xx errors are never retried.

CORS

Nolxy handles CORS preflight requests and injects the appropriate headers on every response. Configure per route.

Allowed Origins

List of allowed origins. Use * to allow all. Requests from unlisted origins receive no CORS headers.

Allowed Methods

HTTP methods allowed in CORS requests. Sent in Access-Control-Allow-Methods.

Allowed Headers

Request headers the browser is allowed to send. Sent in Access-Control-Allow-Headers.

Allow Credentials

Whether cookies and auth headers are allowed. Sets Access-Control-Allow-Credentials: true. Cannot be combined with origin: *.

Max Age

How long (seconds) the browser can cache preflight results. Reduces OPTIONS requests.

Preflight (OPTIONS) requests are handled entirely by Nolxy and never forwarded to the upstream backend.

Request/Response Transformations

Pipelines apply a sequence of transformation actions to the request before it is proxied, or to the response before it is returned. Actions run in order and can be conditional on method or path.

Available Actions

stringTrim Trim whitespace from a string field

stringToLower Convert a string field to lowercase

stringToUpper Convert a string field to uppercase

removeFields Remove fields from the body

addFields Add or overwrite fields in the body

renameFields Rename fields in the body

Additional actions include maskFields (PII redaction), injectHeader, removeHeader, jwtClaimToHeader, and securityHeaders. See the Pipelines guide for the full list.