jsonrpc-batch: JSONRPC-Batch-Protokollmodul für nginx-module-lua

Installation

Wenn Sie das RPM-Repository-Abonnement noch nicht eingerichtet haben, melden Sie sich an. Dann können Sie mit den folgenden Schritten fortfahren.

CentOS/RHEL 7 oder 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

Um diese Lua-Bibliothek mit NGINX zu verwenden, stellen Sie sicher, dass nginx-module-lua installiert ist.

Dieses Dokument beschreibt lua-resty-jsonrpc-batch v0.0.1, veröffentlicht am 15. Juli 2015.

Die Lua-Openresty-Implementierung von JSON-RPC 2.0 Batch-Anfrage (http://www.jsonrpc.org/specification#batch).

Die Batch-Anfrage ist nicht blockierend und wird parallel verarbeitet, da dieses Modul location.capture_multi von ngx_lua verwendet. Daher ist die Leistung hoch, während die Implementierung einfach ist.

Dieses Modul analysiert eine Batch-Anfrage, validiert sie und führt mehrere Subanfragen an Upstream-Server durch. Beachten Sie, dass Sie einen Upstream-JSON-RPC-Server Ihrer Wahl haben müssen, aber Upstream-Server müssen nicht für die JSON-RPC-Batch-Anfrage gelten.

Synopsis

Grundlegende Verwendung

server {
    location /api {
        # jsonrpc endpoint
    }
    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)
        ';
    }
}

Erweiterte Verwendung

http {

    init_by_lua '
        local jsonrpc_batch = require "resty.jsonrpc.batch"
        client = jsonrpc_batch.new({
            -- Begrenzung der Größe des Batch-Anforderungsarrays
            max_batch_array_size = 10,
            -- für das Protokollieren der Antwortzeit des Upstreams
            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/.* {
            # jsonrpc endpoint
        }

        location /api/batch {
            lua_need_request_body on;

            content_by_lua '
                local res, err = client:batch_request({
                    -- Sie können den Endpunkt pro Anfrage ändern
                    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);
            ';
        }
    }
}

Methoden

new

usage:client = jsonrpc_batch:new(options)

Das options-Argument ist eine Lua-Tabelle, die die folgenden Schlüssel enthält:

max_batch_array_size [Int]

Setzt eine Begrenzung für die JSON-Array-Größe der Batch-Anfrage.
Wenn eine Anfrage, deren JSON-Array-Größe über dem Limit liegt, eingeht, gibt die request-Methode ein ungültiges Fehler-JSON zurück.

Der Standardwert ist nil (keine Begrenzung).

allow_single_request [Bool]

Dieses Modul kann nicht nur Batch-Anfragen, sondern auch Einzelanfragen (keine Batch-Anfragen) akzeptieren. Zum Beispiel, {"id":1, "jsonrpc": "2.0", "params": {}, "method": "hoge"} ist eine Einzelanfrage.

Wenn allow_single_request auf false gesetzt ist, führt eine Einzelanfrage zu einem ungültigen Fehler-JSON.

Der Standardwert ist true.

before_subrequest [Funktion function(self, ctx)]

Gibt die Callback-Funktion an, die unmittelbar vor dem Auslösen von Subanfragen aufgerufen wird. Das ctx-Argument ist ein Context-Objekt.

Zum Beispiel können Sie eine NGINX-Variable (ngx.var) für das Protokollieren von Subanfragen festlegen, und Sie können die Anfrageparameter dynamisch manipulieren.
after_subrequest [Funktion function(self, ctx)]

Gibt die Callback-Funktion an, die unmittelbar nach dem Auslösen von Subanfragen aufgerufen wird. Das ctx-Argument ist ein Context-Objekt.

Zum Beispiel können wir eine NGINX-Variable (ngx.var) für das Protokollieren der Ergebnisse von Subanfragen festlegen, und wir können die Antworten von Subanfragen dynamisch manipulieren.

request

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

Dekodiert die Anfrage-JSON und trennt sie und führt Subanfragen parallel zum angegebenen path aus. Es gibt die Antwort-JSON (res) zurück, die aus den Antworten aller Subanfragen generiert wird. err wird mit einer Fehlermeldung gesetzt, wenn im Lua-Skript ein Fehler auftritt.

Es können folgende Parameter akzeptiert werden.

request [String] (erforderlich)

Eine Anfrage-JSON.
path [String oder Funktion function(self, ctx, req)] (erforderlich)

Subanfrage-Pfad wie "/api".

Der Typ kann eine Funktion sein, die den Pfad für jede Subanfrage dynamisch bestimmt.

Das ctx-Argument ist ein Context-Objekt.

Das req-Argument ist eine Einzelanfrage-JSON, die im Batch-Anfrage-JSON-Array enthalten ist, z. B. {"id":1, "jsonrpc": "2.0", "params": {"user_id": 1}, "method": "getUser"}.

Um ein Beispiel zu geben, können wir diese Funktion verwenden, um API-Endpunkte nach JSON-RPC-Methode zu trennen, und wir können die ursprünglichen Anfragepfadinformationen an die Subanfrage weitergeben.

Folgendes Konfigurationsbeispiel zeigt, dass es zwei Endpunkte gibt, und Batch-Anfragen an die Endpunkte nach JSON-RPC-Methode verteilt werden. Darüber hinaus haben die Endpunkte ihre eigene API-Version als Pfadpräfix.

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

    location ~ ^/(\d+\.\d+)/updateUser$ {
        # jsonrpc endpoint 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) optional

Geben Sie die HTTP-Methode an, die von Subanfragen verwendet wird. Der Standardwert ist ngx.HTTP_POST.

Objekt

Context

Die Callback-Funktionen before_subrequest, after_subrequest und path haben das Context-Objekt in den Argumenten. Das Context-Objekt enthält Informationen zu Anfragen und Antworten von Subanfragen, sodass sich die Werte je nach Anfrageprozess ändern.

Das Context-Objekt ist eine Lua-Tabelle und hat folgende Schlüssel.

path [String oder Funktion]

Von der request-Methode als path angegeben.

method [String]

Von der request-Methode als method angegeben.

raw_request [String]

Anfrage-JSON, die von der request-Methode als request angegeben wird.

request [Tabelle]

Lua-Tabelle, die durch Dekodierung der raw_request-JSON generiert wird.

is_batch [Bool]

Die Anfrage-JSON ist eine Einzelanfrage oder eine Batch-Anfrage.

subreq_reqs [Tabelle]

Das Array der Parameter für Subanfragen. Dies sind die Argumente von ngx.location.capture_multi.

subreq_resps [Tabelle]

Das Array der Antworten von Subanfragen. Dies ist die Antwort von ngx.location.capture_multi.

GitHub

Sie finden möglicherweise zusätzliche Konfigurationstipps und Dokumentationen für dieses Modul im GitHub-Repository für nginx-module-jsonrpc-batch.