lua-resty-core

ngx.pipe allows you to spawn OS processes and communicate with them via stdin, stdout, and stderr in a non-blocking fashion. It is production-ready and designed for POSIX-compliant systems.

Key Characteristics

• Non-blocking: Uses Nginx's event mechanism and OpenResty's Lua coroutine scheduler to ensure communication does not block the OS thread.
• Safety: If a process instance is collected by the garbage collector while still alive, it is automatically killed via SIGKILL.
• Limitations:
  • Does not support non-POSIX systems (like Windows).
  • Communication APIs cannot be used in phases that do not support yielding (e.g., init_worker_by_lua* or log_by_lua*).
  • If not using the OpenResty bundle, you must apply the socket_cloexec patch to standard Nginx core.

location = /t {
    content_by_lua_block {
        local ngx_pipe = require "ngx.pipe"
        local select = select

        local function count_char(...) 
            -- Spawns 'wc -c' to count bytes from stdin
            local proc = ngx_pipe.spawn({'wc', '-c'})
            local n = select('#', ...)
            for i = 1, n do
                local arg = select(i, ...)
                local bytes, err = proc:write(arg)
                if not bytes then
                    ngx.say(err)
                    return
                end
            end

            -- Close stdin so 'wc' can finish processing and output
            local ok, err = proc:shutdown('stdin')
            if not ok then
                ngx.say(err)
                return
            end

            local data, err = proc:stdout_read_line()
            if not data then
                ngx.say(err)
                return
            end

            ngx.say(data)
        end

        count_char(("1234"):rep(2048))
    }
}

The ngx.balancer module allows you to define highly dynamic NGINX load balancers for existing upstream modules like ngx_http_proxy_module, ngx_http_fastcgi_module, and ngx_stream_proxy_module. It enables per-request selection of backend peers from a dynamic list.

Implementation Context

All methods must be called within the balancer_by_lua* phase (e.g., balancer_by_lua_block or balancer_by_lua_file).

http {
    upstream backend {
        server 0.0.0.1; # placeholder

        balancer_by_lua_block {
            local balancer = require "ngx.balancer"
            local host = "127.0.0.2"
            local port = 8080

            local ok, err = balancer.set_current_peer(host, port)
            if not ok then
                ngx.log(ngx.ERR, "failed to set the current peer: ", err)
                return ngx.exit(500)
            end
        }
    }

    server {
        listen 80;
        location / {
            proxy_pass http://backend/fake;
        }
    }
}

The ngx.ssl.session module allows you to implement distributed SSL session caching. By storing and retrieving serialized SSL session data in an external store (like Redis or Memcached), you can allow different NGINX workers or even different servers to resume SSL sessions. This avoids expensive full SSL handshakes, significantly reducing CPU usage.

To implement this, you must use two NGINX directives from the lua-nginx-module:

1. ssl_session_fetch_by_lua*: Used to look up a session by its ID from your cache.
2. ssl_session_store_by_lua*: Used to save the session data to your cache after a handshake completes.

Workflow:

• Fetch: Call get_session_id() to get the ID, look it up in your cache, and if found, call set_serialized_session(session) to resume the session.
• Store: Call get_session_id() and get_serialized_session() to retrieve the current session data, then save it to your cache (ideally using ngx.timer.at to avoid blocking the handshake process).

# Example pattern for distributed caching

ssl_session_fetch_by_lua_block {
    local ssl_sess = require "ngx.ssl.session"
    local sess_id, err = ssl_sess.get_session_id()
    if sess_id then
        local sess = my_lookup_ssl_session_by_id(sess_id) -- User implemented
        if sess then
            ssl_sess.set_serialized_session(sess)
        end
    end
}

ssl_session_store_by_lua_block {
    local ssl_sess = require "ngx.ssl.session"
    local sess_id, err = ssl_sess.get_session_id()
    local sess, err = ssl_sess.get_serialized_session()
    if sess_id and sess then
        -- Use a timer to save asynchronously
        ngx.timer.at(0, function(premature, sess_id, sess) 
            my_save_ssl_session_by_id(sess_id, sess) 
        end, sess_id, sess)
    end
}

The ngx.process module allows Lua code to interact with and manage Nginx process roles. It provides utilities to identify if the current context is a master, worker, or privileged agent, and allows for enabling privileged agents or signaling graceful exits.

Typical Workflow Example:

1. Use init_by_lua_block to enable the privileged agent.
2. Use init_worker_by_lua_block or content_by_lua_block to perform role-specific logic using type().
3. Retrieve the master PID for process management tasks.

# Example nginx.conf usage
init_by_lua_block {
    local process = require "ngx.process"
    process.enable_privileged_agent()
}

server {
    location = /status {
        content_by_lua_block {
            local process = require "ngx.process"
            ngx.say("type: ", process.type())
            ngx.say("master pid: ", process.get_master_pid() or "-")
        }
    }
}