Nginx and Reverse Proxy Operations

Pathrule3 Rules • 2 Memories • 1 Skill

Nginx sits at a trust and backpressure boundary where a small directive can change client identity, request size, streaming latency, retry behavior, cacheability, or whether an upstream sees the original protocol and host. This pattern constrains forwarded headers, request and upstream limits, and safe retries; it records streaming and connection behavior and provides a configuration test and reload workflow. It differs from CDN caching and application API patterns by focusing on the reverse proxy's own connection pools, buffering, header normalization, upstream health, and zero-downtime configuration lifecycle.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

validate-nginx-change

deploy/

nginx/

Rebuild forwarding headers from trusted connection data

Set body, header, timeout, and connection limits by route

Retry only operations proven safe to repeat

Buffering is an endpoint-level latency decision

A WebSocket upgrade is a hop-by-hop contract

Rules

Rebuild forwarding headers from trusted connection data/deploy/nginxhighstrictOverwrite public forwarding headers and append only verified proxy hops so applications can reason about origin and client identity.

1	Headers such as Forwarded and X-Forwarded-For arrive from untrusted clients unless the edge proxy replaces them. Passing them through unchanged lets callers spoof scheme, host, or client address.
2
3	- Set the upstream Host and public scheme from approved server configuration or trusted connection variables instead of accepting arbitrary client forwarding values.
4	- Replace or construct the first forwarding hop at the public edge, then append only inside a documented trusted proxy chain.
5	- Configure real-client address processing with explicit trusted proxy networks; never trust every source merely because Nginx is behind another network layer.
6	- Test direct, edge, and internal ingress paths and confirm the application derives the same canonical origin and an attributable client chain.
7
8	See /tests/proxy for the adjacent decision or procedure that completes this constraint.

Set body, header, timeout, and connection limits by route/deploy/nginxhighstrictBound client input and upstream waiting according to endpoint behavior instead of using one permissive global timeout.

1	Proxy defaults and copied global values rarely match uploads, ordinary APIs, health checks, or long-lived streams. Overly small limits break valid traffic, while overly large ones tie up memory and connections under abuse or dependency failure.
2
3	- Set request-body limits for the endpoint and reject oversized uploads before proxying where possible; align the application and storage limits with the same contract.
4	- Separate connect, header, read, and send timeouts so a failed dial is not treated like a legitimate long-lived response.
5	- Apply request and response header limits that support required cookies and tracing without allowing unbounded metadata.
6	- Size upstream keep-alive connections and worker limits against application capacity and file descriptors; the proxy must not create more concurrency than the service can drain.
7
8	See /ops/runbooks for the adjacent decision or procedure that completes this constraint.

Retry only operations proven safe to repeat/deploy/nginxhighstrictLimit upstream retries by method and failure phase, and preserve a request identity when application-level idempotency is required.

1	A proxy can fail over after an upstream timeout or connection error, but it may not know whether the first service already committed a state change. Blind retry turns one client action into two effects.
2
3	- Allow automatic retry for idempotent reads only under explicitly chosen failure conditions and attempt limits.
4	- Do not retry a state-changing request unless the application contract uses an idempotency key and the body can be replayed safely.
5	- Distinguish failure before a connection or request write from failure after the upstream may have processed it; ambiguous outcomes need reconciliation, not optimistic success.
6	- Expose upstream address, status, response time, and retry count in structured access logs without recording secrets or full sensitive payloads.
7
8	See /ops/runbooks for the adjacent decision or procedure that completes this constraint.

Memories

Buffering is an endpoint-level latency decision/deploy/nginxKeep buffering for ordinary responses, disable or tune it for streams, and verify memory and disk behavior under slow clients.

1	Nginx buffering protects upstreams from slow clients and improves throughput for ordinary responses, but it can delay server-sent events, incremental rendering, and other streaming protocols until enough data accumulates.
2
3	- Classify endpoints as buffered request-response, large upload, download, server-sent stream, or upgraded connection and configure each location deliberately.
4	- For streaming responses, disable response buffering where required and ensure the upstream emits flushable chunks and anti-buffering headers understood by the deployment.
5	- For large request bodies, decide whether Nginx should spool before contacting the application or stream directly, accounting for retry and temporary-disk behavior.
6	- Load-test with slow clients because disabling buffering can transfer connection and backpressure cost from the proxy to the application.
7
8	See /tests/proxy for the rule or workflow that puts this decision into practice.

A WebSocket upgrade is a hop-by-hop contract/deploy/nginxForward upgrade intent explicitly, use a long-lived read policy, and make application-level reconnect and liveness visible.

1	Connection and Upgrade headers are hop-by-hop and are not forwarded like ordinary end-to-end headers. A successful HTTP route can therefore fail only when the client attempts a protocol upgrade.
2
3	- Set the upstream HTTP version and forward Upgrade and Connection values through a controlled mapping rather than copying arbitrary client connection tokens.
4	- Choose idle timeout and liveness behavior from the application's heartbeat contract so healthy quiet sessions are not closed unexpectedly.
5	- Preserve authentication and origin validation at the application handshake; the proxy upgrade does not make the browser connection trusted.
6	- Expose active upgraded connections, close codes where observable, upstream resets, and reconnect rates so connection churn is not hidden inside generic 5xx metrics.
7
8	See /ops/runbooks for the rule or workflow that puts this decision into practice.

Skills

validate-nginx-change/rootRender, syntax-test, probe, reload, and observe an Nginx change with a defined rollback before traffic depends on it.

1	---
2	name: validate-nginx-change
3	description: Validate an Nginx routing, header, timeout, TLS, buffering, or upstream change.
4	---
5
6	# Validate Nginx Change
7
8	Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result.
9
10	- [ ] Render the exact production configuration with secrets redacted, inspect included files, and run the Nginx configuration test in the target image or host environment.
11	- [ ] Probe ordinary, malformed, oversized, streaming, upgraded, and upstream-failure requests through the same ingress path clients use.
12	- [ ] Record active connections and baseline error and latency signals, then perform a graceful reload rather than terminating workers with live traffic.
13	- [ ] Verify new workers accepted the configuration and old workers drain; watch upstream status, retry count, connection errors, and response latency.
14	- [ ] If any acceptance signal regresses, restore the prior rendered configuration, test it, reload again, and preserve the failed config and evidence for diagnosis.
15
16	## Exit criteria
17
18	The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks.

Why this pattern

AI agents often copy proxy snippets that trust spoofed forwarding headers, buffer a streaming endpoint, retry non-idempotent requests, or reload invalid configuration into production.

Built for Platform teams operating Nginx in front of APIs, web applications, streaming endpoints, or internal services.

Keeps your assistant from:

Passing attacker-controlled client identity to the application
Buffering server-sent or streamed responses until they appear broken
Retrying a state-changing request against another upstream
Applying an invalid or partially rendered configuration

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25