jsonrpc-batch: Módulo de protocolo por lotes JSONRPC 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-jsonrpc-batch

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

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

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

Este documento describe lua-resty-jsonrpc-batch v0.0.1 lanzado el 15 de julio de 2015.

La implementación Lua-Openresty de JSON-RPC 2.0 Solicitud por Lotes (http://www.jsonrpc.org/specification#batch).

La solicitud por lotes es no bloqueante y se procesa en paralelo porque este módulo utiliza location.capture_multi de ngx_lua. Por lo tanto, el rendimiento es alto mientras que la implementación es simple.

Este módulo analiza una solicitud por lotes, la valida y realiza múltiples subsolicitudes a servidores ascendentes. Ten en cuenta que debes tener un servidor JSON-RPC ascendente como desees, pero los servidores ascendentes no necesitan aplicar para la solicitud por lotes JSON-RPC.

Sinopsis

Uso Básico

server {
    location /api {
        # punto final jsonrpc
    }
    location /api/batch {
        lua_need_request_body on;

        content_by_lua '
            local jsonrpc_batch = require "resty.jsonrpc.batch"
            client = jsonrpc_batch:new()
            local res, err = client:batch_request({
                path    = "/api",
                request = ngx.var.request_body,
            })
            if err then
                ngx.exit(500)
            end
            ngx.say(res)
        ';
    }
}

Uso Avanzado

http {

    init_by_lua '
        local jsonrpc_batch = require "resty.jsonrpc.batch"
        client = jsonrpc_batch.new({
            -- limitar el tamaño del arreglo de solicitudes por lotes
            max_batch_array_size = 10,
            -- para registrar el tiempo de respuesta del servidor ascendente
            before_subrequest = function(self, ctx, req)
                ctx.start_at = ngx.now()
            end,
            after_subrequest = function(self, ctx, resps, req)
                ngx.var.jsonrpc_upstream_response_time = ngx.now() - ctx.start_at
            end,
        })
    ';

    server {
        set $jsonrpc_upstream_response_time  -;

        location ~ /api/method/.* {
            # punto final jsonrpc
        }

        location /api/batch {
            lua_need_request_body on;

            content_by_lua '
                local res, err = client:batch_request({
                    -- puedes cambiar el punto final por solicitud
                    path = function(self, ctx, req)
                        return "/api/method/" .. req.method
                    end,
                    request  = ngx.var.request_body,
                });
                if err then
                    ngx.log(ngx.CRIT, err);
                    ngx.exit(500);
                end
                ngx.say(res);
            ';
        }
    }
}

Métodos

new

uso:client = jsonrpc_batch:new(options)

El argumento options es una tabla Lua que contiene las siguientes claves:

max_batch_array_size [Int]

Establece una limitación al tamaño del arreglo JSON de la solicitud por lotes.
Cuando llega una solicitud cuyo tamaño de arreglo JSON supera el límite, el método request devuelve un JSON de error inválido.

El valor predeterminado es nil (sin límite).

allow_single_request [Bool]

Este módulo puede aceptar no solo solicitudes por lotes, sino también solicitudes individuales (sin solicitudes por lotes). Por ejemplo, {"id":1, "jsonrpc": "2.0", "params": {}, "method": "hoge"} es una solicitud individual.

Si allow_single_request se establece en false, una solicitud individual resulta en un JSON de error inválido.

El valor predeterminado es true.

before_subrequest [Function function(self, ctx)]

Especifica la función de callback que se activa justo antes de lanzar subsolicitudes. El argumento ctx es un objeto Context.

Por ejemplo, puedes establecer una variable de nginx (ngx.var) para registrar subsolicitudes, y puedes manipular dinámicamente los parámetros de la solicitud.
after_subrequest [Function function(self, ctx)]

Especifica la función de callback que se activa justo después de lanzar subsolicitudes. El argumento ctx es un objeto Context.

Por ejemplo, podemos establecer una variable de nginx (ngx.var) para registrar los resultados de las subsolicitudes, y podemos manipular dinámicamente las respuestas de las subsolicitudes.

request

uso:
res, err = client:request({
    path = "/api",
    request = ###jsonrpc request json###,
})

Decodifica el JSON de la solicitud y lo separa, y realiza subsolicitudes en paralelo a la path especificada. Devuelve el JSON de respuesta (res) que se genera a partir de todas las respuestas de las subsolicitudes. err se establece como el mensaje de error cuando el script Lua ocurre un error.

Puede aceptar los siguientes parámetros.

request [String] (requerido)

Un JSON de solicitud.
path [String o Function function(self, ctx, req)] (requerido)

Ruta de subsolicitud como "/api".

El tipo puede ser una función que decide la ruta para cada subsolicitud dinámicamente.

El argumento ctx es un objeto Context.

El argumento req es un JSON de solicitud individual incluido en el arreglo JSON de la solicitud por lotes. como {"id":1, "jsonrpc": "2.0", "params": {"user_id": 1}, "method": "getUser"}.

Para dar un ejemplo, podemos usar esta función para separar los puntos finales de la API por método JSON-RPC, y podemos pasar la información de la ruta de la solicitud original a la subsolicitud.

El siguiente ejemplo de configuración muestra que hay dos puntos finales, y se distribuyen las solicitudes por lotes a los puntos finales por método jsonrpc. Además, los puntos finales tienen su propia versión de API como prefijo de ruta.

    location ~ ^/(\d+\.\d+)/getUser$ {
        # punto final jsonrpc 1
    }

    location ~ ^/(\d+\.\d+)/updateUser$ {
        # punto final jsonrpc 2
    }

    location ~ ^/(\d+\.\d+)/batch$ {
        set $version $1;
        lua_need_request_body on;
        content_by_lua {
            local res, err = client:batch_request({
                path = function(self, ctx, req)
                    return "/" .. ngx.var.version  .. "/" .. req.method
                end,
                request = ngx.var.request_body,
            });
            if err then
              ngx.log(ngx.CRIT, err);
              ngx.exit(500);
              return;
            end
        };
    }

method (string) opcional

Especifica el método HTTP utilizado por las subsolicitudes. El valor predeterminado es ngx.HTTP_POST.

Objeto

Context

Las funciones de callback before_subrequest, after_subrequest y path tienen el objeto Context en los argumentos. El objeto Context incluye información de las solicitudes y las respuestas de las subsolicitudes, por lo que los valores que tiene o no cambian según el proceso de solicitud.

El objeto Context es una tabla Lua y tiene las siguientes claves.

path [String o Function]

Especificado por el método request como path.

method [String]

Especificado por el método request como method.

raw_request [String]

JSON de solicitud especificado por el método request como request.

request [Table]

Tabla Lua generada al decodificar el JSON de raw_request.

is_batch [Bool]

El JSON de la solicitud es una solicitud individual o una solicitud por lotes.

subreq_reqs [Table]

El arreglo de parámetros de subsolicitudes. Este es el argumento de ngx.location.capture_multi.

subreq_resps [Table]

El arreglo de respuestas de subsolicitudes. Esta es la respuesta de ngx.location.capture_multi.

GitHub

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