cloudflare / lua-upstream-cache-nginx-module

Name
    http_cache - Expose & modify the internal nginx cache metadata.

    *This module is not distributed with the Nginx source or in the lua-nginx
    module*
    Installation is similar to other nginx modules.

Status
    This module is under development and is used in production.

Version
    This document describes http_cache v0.1.1

Synopsis
        # set search paths for pure Lua external libraries (';;' is the default path):
        lua_package_path '/foo/bar/?.lua;/blah/?.lua;;';

        # set search paths for Lua external libraries written in C (can also use ';;'):
        lua_package_cpath '/bar/baz/?.so;/blah/blah/?.so;;';

        server {
            listen       8000 default_server;
            server_name  localhost;

        location / {
            proxy_cache pcache;
            proxy_pass http://127.0.0.1:8001/;

            # Force entries in cache to only be cached for 5 seconds
            # This is equivalent to:
            # proxy_ignore_headers "Expires" "Cache-Control;
            # proxy_cache_valid any 5s;
            header_filter_by_lua '
               local http_cache = require("http_cache")
               local cache_status = (ngx.var.upstream_cache_status or "")

               if cache_status == "MISS" or cache_status == "EXPIRED" then
                   local cache_data = http_cache.get_metadata()
                   local new_expire = ngx.time() + 5

                   if cache_data and cache_data["valid_sec"] then
                       http_cache.set_metadata({ valid_sec = new_expire,
                                                 fcn = { valid_sec = new_expire,
                                                     expire = new_expire } })
                   end
               end
            ';
        }

Description
    This module extends the lua-nginx Lua module. It adds the ability to read
    and set values from nginx's internal cache metadata.

API
    get_metadata() - returns a table with all cache metadata.
    The fields are:
    Resource specific fields
        key: Hexadecimal cache key for this resource
        crc32: Numeric crc32 calculated by nginx to check cache collisions
        valid_sec: Absolute time, in seconds since Epoch, when this entry expires.
        last_modified: Absolute time of last-modified header in seconds, if present.
        date: Absolute time of date header in seconds, if present.
	length: Length of contents
	fs_size: Size of resource, in disk blocks.
           NOTE: This can be converted to bytes by multiplying by bsize below.
	min_uses: Minimum number of uses required to cache this resource.
        valid_msec: millisecond component of valid_secs (?)

    Shared Cache information, under "sh"
        size

    Cache Data, under "fcn"
        max_size: maximum allowable cache size in 512B blocks
        bsize: size of disk block in bytes.
        inactive: inactive value for cache.
        files: currently open files used by loader
        loader_files: maximum number of files for the loader to open at once
        loader_sleep: time between file opens
        loader_threshold:
        aggressive_purge: Flag for whether cache manager will use aggressive
            purge policy

    set_metadat(tbl) - sets cache metadata from a table similar to the one 
    returned by get_metadata. Fields that will be written are:
    Resource specific fields
    valid_sec, last_modified, date, min_uses, valid_msec

    Cache Data, under "fcn"
    uses, valid_msec, expire, valid_sec