Saltar a contenido

rack: Un marco de servidor HTTP simple y extensible para nginx-module-lua

Instalación

Si no has configurado la suscripción al repositorio RPM, regístrate. Luego puedes proceder con los siguientes pasos.

CentOS/RHEL 7 o Amazon Linux 2

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install lua-resty-rack

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-rack

Para usar esta biblioteca Lua con NGINX, asegúrate de que nginx-module-lua esté instalado.

Este documento describe lua-resty-rack v0.3 lanzado el 12 de julio de 2012.

Un marco de servidor HTTP simple y extensible para OpenResty, que proporciona un método limpio para cargar aplicaciones HTTP en Lua ("módulos resty") en Nginx.

Inspirándose en Rack y también en Connect, lua-resty-rack te permite cargar tu aplicación como una pieza de middleware, junto a otros middleware. Tu aplicación puede; ignorar la solicitud actual, modificar la solicitud o respuesta de alguna manera y pasar a otros middleware, o hacerse responsable de la solicitud generando una respuesta.

Usando Middleware

Para instalar middleware para una location dada, simplemente llama a rack.use(middleware) en el orden en que deseas que se ejecuten los módulos, y luego finalmente llama a rack.run().

server {
    location / {
        content_by_lua '
            local rack = require "resty.rack"

            rack.use(rack.middleware.method_override)
            rack.use(require "my.module")
            rack.run()
        ';
    }
}

rack.use(...)

Sintaxis: rack.use(route?, middleware, options?)

Si se proporciona route, el middleware solo se ejecutará para solicitudes donde route esté en la ruta (ngx.var.uri). Si el middleware requiere que se seleccionen opciones, se pueden proporcionar, generalmente como una tabla, como el tercer parámetro.

rack.use('/some/path', app, { foo = 'bar' })

Para casos simples, el parámetro middleware también puede ser una función simple en lugar de un módulo Lua. Tu función debe aceptar req, res y next como parámetros. Consulta a continuación las instrucciones sobre cómo escribir middleware.

rack.use(function(req, res, next)
    res.header["X-Homer"] = "Doh!"
    next()
end)

rack.run()

Sintaxis: rack.run()

Ejecuta cada uno de los middleware en orden, hasta que uno elija manejar la respuesta. Por lo tanto, el orden en el que llamas a rack.use() es importante.

Middleware Agrupado

method_override

rack.use(rack.middleware.method_override, { key = "METHOD" })

Sobrescribe el método HTTP utilizando un valor de cadena de consulta. El nombre de argumento predeterminado es "_method", pero esto se puede sobrescribir configurando la opción "key".

read_request_headers

rack.use(rack.middleware.read_request_headers, { max = 50 })

Esto solo es necesario si deseas iterar sobre los encabezados de la solicitud HTTP. Se cargarán de manera perezosa cuando se acceda a través de req.header.

Puedes especificar un límite en el número de encabezados de solicitud a leer, que por defecto es 100. El límite se puede eliminar especificando un máximo de 0, pero se desaconseja encarecidamente.

read_body

rack.use(rack.middleware.read_body)

Lee explícitamente el cuerpo de la solicitud (en bruto).

Creando Middleware

Las aplicaciones de middleware son simplemente módulos Lua que utilizan la solicitud y respuesta HTTP como una interfaz mínima. Deben implementar la función call(options) que devuelve una función. Los parámetros (req, res, next) se definen a continuación.

module("resty.rack.method_override", package.seeall)

_VERSION = '0.01'

function call(options)
    return function(req, res, next)
        local key = options['key'] or '_method'
        req.method = string.upper(req.args[key] or req.method)
        next()
    end
end

API

req.method

El método HTTP, por ejemplo, GET, establecido desde ngx.var.request_method.

req.scheme

El esquema del protocolo http|https, establecido desde ngx.var.scheme.

req.uri

por ejemplo, /my/uri, establecido desde ngx.var.uri.

req.host

El nombre de host, por ejemplo, example.com, establecido desde ngx.var.host.

req.query

La cadena de consulta, por ejemplo, var1=1&var2=2, establecida desde ngx.var.query_string.

req.args

Los argumentos de consulta, como una table, establecidos desde ngx.req.get_uri_args().

req.header

Una tabla que contiene los encabezados de la solicitud. Las claves se comparan sin distinción entre mayúsculas y minúsculas, y opcionalmente con guiones bajos en lugar de guiones. por ejemplo.

req.header["X-Foo"] = "bar"
res.body = req.header.x_foo
    --> "bar"

Los encabezados de la solicitud HTTP se leen bajo demanda y, por lo tanto, no se pueden iterar a menos que el middleware read_request_headers esté en uso).

req.body

Una cadena vacía hasta que se lea con el middleware read_body.

res.status

El código de estado HTTP a devolver. Hay constantes definidas para estados comunes.

res.header

Una tabla de encabezados de respuesta, que se pueden comparar sin distinción entre mayúsculas y minúsculas y opcionalmente con guiones bajos en lugar de guiones (ver req.header arriba).

res.body

El cuerpo de la respuesta.

next

Este parámetro es una función proporcionada al middleware, que puede ser llamada para indicar que rack debería intentar el siguiente middleware. Si tu aplicación no tiene la intención de enviar la respuesta al navegador, debe llamar a esta función. Sin embargo, si tu aplicación se está haciendo responsable de la respuesta, simplemente devuelve sin llamar a next.

Ejemplo que modifica puramente la solicitud. 

function call(options)
    return function(req, res, next)
        local key = options['key'] or '_method'
        req.method = string.upper(req.args[key] or req.method)
        next()
    end
end

Ejemplo generando una respuesta. 

function call(options)
    return function(req, res)
        res.status = 200
        res.header['Content-Type'] = "text/plain"
        res.body = "Hello World"
    end
end

Mejorando req / res

Tu aplicación puede agregar nuevos campos o incluso funciones a las tablas req / res donde sea apropiado, que podrían ser utilizados por otros middleware siempre que las dependencias estén claras (y se llame a use() en el orden correcto).

GitHub

Puedes encontrar consejos adicionales de configuración y documentación para este módulo en el repositorio de GitHub para nginx-module-rack.