Nginx & OpenResty Development

Core Guidance

When writing or reviewing Nginx configuration:

1. Always consider the directive inheritance model. Child blocks inherit from parent unless they redefine the directive. For example, adding one proxy_set_header in a location block wipes all inherited proxy_set_header directives from the server block.
2. Prefer map over if for conditional logic. if in location context is dangerous and only reliably supports return and rewrite. See references/nginx-gotchas.md for the full list.
3. Always clarify proxy_pass trailing-slash behavior — it is the single most common source of subtle bugs.
4. When writing upstream blocks, always include keepalive configuration and explain connection pooling implications.
5. When writing Nginx directives, always check docs, specifically module references, to verify that a directive actually exists, and what values it accepts (on/off, variable, fixed values, etc).

When writing OpenResty/Lua code:

1. Always check phase restrictions before using cosocket or subrequest APIs. See references/openresty-api.md.
2. Prefer ngx.ctx over ngx.var for passing data between phases because it's more performant.
3. Avoid using ngx.var multiple times for the same variable, as it's less performant than accessing Lua variable.
4. Use ngx.timer.at for background/async work, never block the event loop.