question around ngx_http_get_flushed_variable()

[Maxim Dounin]

Hello!

On Mon, Apr 04, 2022 at 12:44:38PM -0700, Chris Newton via nginx-devel wrote:

> I'm a little unclear as to when ngx_http_get_flushed_variable() should be
> used rather than ngx_http_get_indexed_variable(). The dev guide is a little
> sparse, so I'm hoping someone could help.

[...]

> Are there any guidelines on when ngx_http_get_flushed_variable() should be
> used instead of ngx_http_get_indexed_variable()?

The ngx_http_get_indexed_variable() does not flush non-cacheable 
variables by itself, and should be used when flushes are not 
needed and/or handled separately.  For example, it is used by the 
script codes, and this makes it possible to evaluate multiple 
variables with a single cache flush, such as by 
ngx_http_script_flush_no_cacheable_variables().

The ngx_http_get_flushed_variable() does a flush automatically 
when needed, that is, it does not use cache for non-cacheable 
variables.  This is to be used when flushes are not handled 
separately and might be important.

Unless you have some explanation on why using 
ngx_http_get_indexed_variable() in the particular place is safe, 
you probably should use ngx_http_get_flushed_variable() instead, 
or you are risking to end up with incorrect behaviour if you'll 
try to lookup non-cacheable variables.

Just in case, looking through all uses of the 
ngx_http_get_indexed_variable() function in nginx:

- ngx_http_charset_filter_module.c: not sure it is safe, might be 
  a bug;

- ngx_http_log_module.c: used with a separate flush by 
  ngx_http_script_flush_no_cacheable_variables();

- ngx_http_memcached_module.c: the $memcached_key variable is 
  expected to be set by "set", so the code assumes no flushes are 
  needed;

- ngx_http_userid_filter_module.c: the $uid_reset variables is 
  expected to be set by "set", so the code assumes no flushes are 
  needed.

- ngx_http_variables.c: in the ngx_http_get_flushed_variable() 
  function, with automatic flush when needed;

- ngx_http_script.c: used when a flush is handled separately.

> It seems like it is 'practically never', but why for example does
> ngx_http_get_variable() use
> 
> ngx_http_get_flushed_variable()?

The ngx_http_get_variable() is to be used for dynamic variables 
lookup, when you don't know the variable name in advance, notably 
in SSI and embedded Perl.  It is expected to be used without 
external flushes and so uses ngx_http_get_flushed_variable() to 
ensure automatic flushes when needed.

Hope this helps.

-- 
Maxim Dounin
http://mdounin.ru/