Zum Inhalt

memcached: Lua memcached-Clienttreiber für nginx-module-lua basierend auf der cosocket-API

Installation

Wenn Sie das RPM-Repository-Abonnement noch nicht eingerichtet haben, melden Sie sich an. Danach 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-memcached

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

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

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

Dieses Dokument beschreibt lua-resty-memcached v0.17, das am 19. Januar 2023 veröffentlicht wurde.

Diese Lua-Bibliothek ist ein memcached-Clienttreiber für das ngx_lua-nginx-Modul:

http://wiki.nginx.org/HttpLuaModule

Diese Lua-Bibliothek nutzt die cosocket-API von ngx_lua, die ein 100% nicht blockierendes Verhalten gewährleistet.

Beachten Sie, dass mindestens ngx_lua 0.5.0rc29 oder OpenResty 1.0.15.7 erforderlich ist.

Synopsis

    server {
        location /test {
            content_by_lua '
                local memcached = require "resty.memcached"
                local memc, err = memcached:new()
                if not memc then
                    ngx.say("failed to instantiate memc: ", err)
                    return
                end

                memc:set_timeout(1000) -- 1 sec

                -- oder verbinden Sie sich mit einer Unix-Domain-Socket-Datei, die von einem memcached-Server gehört:
                --     local ok, err = memc:connect("unix:/path/to/memc.sock")

                local ok, err = memc:connect("127.0.0.1", 11211)
                if not ok then
                    ngx.say("failed to connect: ", err)
                    return
                end

                local ok, err = memc:flush_all()
                if not ok then
                    ngx.say("failed to flush all: ", err)
                    return
                end

                local ok, err = memc:set("dog", 32)
                if not ok then
                    ngx.say("failed to set dog: ", err)
                    return
                end

                local res, flags, err = memc:get("dog")
                if err then
                    ngx.say("failed to get dog: ", err)
                    return
                end

                if not res then
                    ngx.say("dog not found")
                    return
                end

                ngx.say("dog: ", res)

                -- legen Sie es in den Verbindungspool mit einer Größe von 100,
                -- mit einer maximalen Leerlaufzeit von 10 Sekunden
                local ok, err = memc:set_keepalive(10000, 100)
                if not ok then
                    ngx.say("cannot set keepalive: ", err)
                    return
                end

                -- oder schließen Sie die Verbindung sofort:
                -- local ok, err = memc:close()
                -- if not ok then
                --     ngx.say("failed to close: ", err)
                --     return
                -- end
            ';
        }
    }

Methoden

Das key-Argument, das in den folgenden Methoden bereitgestellt wird, wird automatisch gemäß den URI-Escaping-Regeln vor dem Senden an den memcached-Server escaped.

new

syntax: memc, err = memcached:new(opts?)

Erstellt ein memcached-Objekt. Im Falle von Fehlern gibt es nil und eine Zeichenfolge zurück, die den Fehler beschreibt.

Es akzeptiert ein optionales opts-Tabellenargument. Die folgenden Optionen werden unterstützt:

  • key_transform

    eine Array-Tabelle, die zwei Funktionen zum Escapen und Unescapen der memcached-Schlüssel enthält. Standardmäßig werden die memcached-Schlüssel als URI-Komponenten escaped und unescaped, das heißt

    memached:new{
        key_transform = { ngx.escape_uri, ngx.unescape_uri }
    }

connect

syntax: ok, err = memc:connect(host, port)

syntax: ok, err = memc:connect("unix:/path/to/unix.sock")

Versucht, eine Verbindung zum Remote-Host und -Port herzustellen, auf dem der memcached-Server hört, oder zu einer lokalen Unix-Domain-Socket-Datei, die vom memcached-Server gehört.

Bevor der Hostname tatsächlich aufgelöst und eine Verbindung zum Remote-Backend hergestellt wird, sucht diese Methode immer im Verbindungspool nach passenden Leerlaufverbindungen, die durch vorherige Aufrufe dieser Methode erstellt wurden.

sslhandshake

syntax: session, err = memc:sslhandshake(reused_session?, server_name?, ssl_verify?, send_status_req?)

Führt den SSL/TLS-Handshake über die derzeit etablierte Verbindung durch. Weitere Informationen finden Sie in der tcpsock.sslhandshake API von OpenResty.

set

syntax: ok, err = memc:set(key, value, exptime, flags)

Fügt einen Eintrag in memcached bedingungslos ein. Wenn der Schlüssel bereits existiert, wird er überschrieben.

Das value-Argument kann auch eine Lua-Tabelle sein, die mehrere Lua-Strings enthält, die als Ganzes (ohne Trennzeichen) zusammengefügt werden sollen. Zum Beispiel,

    memc:set("dog", {"a ", {"kind of"}, " animal"})

ist funktional äquivalent zu

    memc:set("dog", "a kind of animal")

Der Parameter exptime ist optional und hat standardmäßig den Wert 0 (was bedeutet, dass es nie abläuft). Die Ablaufzeit ist in Sekunden.

Der Parameter flags ist optional und hat standardmäßig den Wert 0.

set_timeout

syntax: ok, err = memc:set_timeout(timeout)

Setzt den Timeout (in ms) für nachfolgende Operationen, einschließlich der connect-Methode.

Gibt 1 bei Erfolg und nil plus eine Zeichenfolge zurück, die den Fehler beschreibt, andernfalls.

set_timeouts

syntax: ok, err = memc:set_timeouts(connect_timeout, send_timeout, read_timeout)

Setzt die Timeouts (in ms) für Verbindungs-, Sende- und Leseoperationen.

Gibt 1 bei Erfolg und nil plus eine Zeichenfolge zurück, die den Fehler beschreibt, andernfalls.

set_keepalive

syntax: ok, err = memc:set_keepalive(max_idle_timeout, pool_size)

Legt die aktuelle memcached-Verbindung sofort in den ngx_lua cosocket-Verbindungspool.

Sie können die maximale Leerlaufzeit (in ms) angeben, wenn die Verbindung im Pool ist, und die maximale Größe des Pools für jeden nginx-Arbeiterprozess.

Im Erfolgsfall gibt es 1 zurück. Bei Fehlern gibt es nil mit einer Zeichenfolge zurück, die den Fehler beschreibt.

Rufen Sie diese Methode nur an der Stelle auf, an der Sie die close-Methode stattdessen aufgerufen hätten. Das Aufrufen dieser Methode versetzt das aktuelle memcached-Objekt sofort in den Zustand closed. Alle nachfolgenden Operationen, die nicht connect() auf dem aktuellen Objekt betreffen, geben den closed-Fehler zurück.

get_reused_times

syntax: times, err = memc:get_reused_times()

Diese Methode gibt die (erfolgreich) wiederverwendeten Zeiten für die aktuelle Verbindung zurück. Im Fehlerfall gibt es nil und eine Zeichenfolge zurück, die den Fehler beschreibt.

Wenn die aktuelle Verbindung nicht aus dem integrierten Verbindungspool stammt, gibt diese Methode immer 0 zurück, das heißt, die Verbindung wurde (noch) nie wiederverwendet. Wenn die Verbindung aus dem Verbindungspool stammt, ist der Rückgabewert immer ungleich null. Diese Methode kann also auch verwendet werden, um zu bestimmen, ob die aktuelle Verbindung aus dem Pool stammt.

close

syntax: ok, err = memc:close()

Schließt die aktuelle memcached-Verbindung und gibt den Status zurück.

Im Erfolgsfall gibt es 1 zurück. Bei Fehlern gibt es nil mit einer Zeichenfolge zurück, die den Fehler beschreibt.

add

syntax: ok, err = memc:add(key, value, exptime, flags)

Fügt einen Eintrag in memcached ein, wenn und nur wenn der Schlüssel nicht existiert.

Das value-Argument kann auch eine Lua-Tabelle sein, die mehrere Lua-Strings enthält, die als Ganzes (ohne Trennzeichen) zusammengefügt werden sollen. Zum Beispiel,

    memc:add("dog", {"a ", {"kind of"}, " animal"})

ist funktional äquivalent zu

    memc:add("dog", "a kind of animal")

Der Parameter exptime ist optional und hat standardmäßig den Wert 0 (was bedeutet, dass es nie abläuft). Die Ablaufzeit ist in Sekunden.

Der Parameter flags ist optional und hat standardmäßig den Wert 0.

Im Erfolgsfall gibt es 1 zurück. Bei Fehlern gibt es nil mit einer Zeichenfolge zurück, die den Fehler beschreibt.

replace

syntax: ok, err = memc:replace(key, value, exptime, flags)

Fügt einen Eintrag in memcached ein, wenn und nur wenn der Schlüssel existiert.

Das value-Argument kann auch eine Lua-Tabelle sein, die mehrere Lua-Strings enthält, die als Ganzes (ohne Trennzeichen) zusammengefügt werden sollen. Zum Beispiel,

    memc:replace("dog", {"a ", {"kind of"}, " animal"})

ist funktional äquivalent zu

    memc:replace("dog", "a kind of animal")

Der Parameter exptime ist optional und hat standardmäßig den Wert 0 (was bedeutet, dass es nie abläuft). Die Ablaufzeit ist in Sekunden.

Der Parameter flags ist optional und hat standardmäßig den Wert 0.

Im Erfolgsfall gibt es 1 zurück. Bei Fehlern gibt es nil mit einer Zeichenfolge zurück, die den Fehler beschreibt.

append

syntax: ok, err = memc:append(key, value, exptime, flags)

Hängt den Wert an einen Eintrag mit dem gleichen Schlüssel an, der bereits in memcached existiert.

Das value-Argument kann auch eine Lua-Tabelle sein, die mehrere Lua-Strings enthält, die als Ganzes (ohne Trennzeichen) zusammengefügt werden sollen. Zum Beispiel,

    memc:append("dog", {"a ", {"kind of"}, " animal"})

ist funktional äquivalent zu

    memc:append("dog", "a kind of animal")

Der Parameter exptime ist optional und hat standardmäßig den Wert 0 (was bedeutet, dass es nie abläuft). Die Ablaufzeit ist in Sekunden.

Der Parameter flags ist optional und hat standardmäßig den Wert 0.

Im Erfolgsfall gibt es 1 zurück. Bei Fehlern gibt es nil mit einer Zeichenfolge zurück, die den Fehler beschreibt.

prepend

syntax: ok, err = memc:prepend(key, value, exptime, flags)

Fügt den Wert an einen Eintrag mit dem gleichen Schlüssel an, der bereits in memcached existiert.

Das value-Argument kann auch eine Lua-Tabelle sein, die mehrere Lua-Strings enthält, die als Ganzes (ohne Trennzeichen) zusammengefügt werden sollen. Zum Beispiel,

    memc:prepend("dog", {"a ", {"kind of"}, " animal"})

ist funktional äquivalent zu

    memc:prepend("dog", "a kind of animal")

Der Parameter exptime ist optional und hat standardmäßig den Wert 0 (was bedeutet, dass es nie abläuft). Die Ablaufzeit ist in Sekunden.

Der Parameter flags ist optional und hat standardmäßig den Wert 0.

Im Erfolgsfall gibt es 1 zurück. Bei Fehlern gibt es nil mit einer Zeichenfolge zurück, die den Fehler beschreibt.

get

syntax: value, flags, err = memc:get(key) syntax: results, err = memc:get(keys)

Holt einen einzelnen Eintrag oder mehrere Einträge im memcached-Server über einen einzelnen Schlüssel oder eine Tabelle von Schlüsseln.

Lassen Sie uns zunächst den Fall besprechen, wenn der Schlüssel ein einzelner String ist.

Der Wert des Schlüssels und der zugehörige Flags-Wert werden zurückgegeben, wenn der Eintrag gefunden wird und kein Fehler auftritt.

Im Falle von Fehlern werden nil-Werte für value und flags zurückgegeben, und ein dritter (String-)Wert wird ebenfalls zurückgegeben, um den Fehler zu beschreiben.

Wenn der Eintrag nicht gefunden wird, werden drei nil-Werte zurückgegeben.

Dann lassen Sie uns den Fall besprechen, wenn eine Lua-Tabelle mit mehreren Schlüsseln bereitgestellt wird.

In diesem Fall wird immer eine Lua-Tabelle mit den Schlüssel-Ergebnis-Paaren im Erfolgsfall zurückgegeben. Jeder Wert, der jedem Schlüssel in der Tabelle entspricht, ist ebenfalls eine Tabelle, die zwei Werte enthält: den Wert des Schlüssels und die Flags des Schlüssels. Wenn ein Schlüssel nicht existiert, gibt es keine entsprechenden Einträge in der results-Tabelle.

Im Fehlerfall wird nil zurückgegeben, und der zweite Rückgabewert ist eine Zeichenfolge, die den Fehler beschreibt.

gets

syntax: value, flags, cas_unique, err = memc:gets(key)

syntax: results, err = memc:gets(keys)

Genau wie die get-Methode, aber gibt auch den CAS-eindeutigen Wert zurück, der mit dem Eintrag verbunden ist, zusätzlich zum Wert und den Flags des Schlüssels.

Diese Methode wird normalerweise zusammen mit der cas-Methode verwendet.

cas

syntax: ok, err = memc:cas(key, value, cas_unique, exptime?, flags?)

Genau wie die set-Methode, aber führt eine Überprüfung und Setzoperation durch, was bedeutet: "Speichern Sie diese Daten, aber nur, wenn niemand anderes seit meinem letzten Abruf aktualisiert hat."

Das cas_unique-Argument kann von der gets-Methode abgerufen werden.

touch

syntax: ok, err = memc:touch(key, exptime)

Aktualisiert die Ablaufzeit eines vorhandenen Schlüssels.

Gibt 1 bei Erfolg oder nil mit einer Zeichenfolge zurück, die den Fehler beschreibt, andernfalls.

Diese Methode wurde erstmals in der Version v0.11 eingeführt.

flush_all

syntax: ok, err = memc:flush_all(time?)

Flushed (oder invalidiert) alle vorhandenen Einträge im memcached-Server sofort (standardmäßig) oder nach der Ablaufzeit, die durch das time-Argument (in Sekunden) angegeben ist.

Im Erfolgsfall gibt es 1 zurück. Bei Fehlern gibt es nil mit einer Zeichenfolge zurück, die den Fehler beschreibt.

delete

syntax: ok, err = memc:delete(key)

Löscht den Schlüssel sofort aus memcached.

Der zu löschende Schlüssel muss bereits in memcached existieren.

Im Erfolgsfall gibt es 1 zurück. Bei Fehlern gibt es nil mit einer Zeichenfolge zurück, die den Fehler beschreibt.

incr

syntax: new_value, err = memc:incr(key, delta)

Erhöht den Wert des angegebenen Schlüssels um den ganzzahligen Wert, der im delta-Argument angegeben ist.

Gibt den neuen Wert nach der Erhöhung bei Erfolg zurück und nil mit einer Zeichenfolge, die den Fehler beschreibt, im Fehlerfall.

decr

syntax: new_value, err = memc:decr(key, value)

Verringert den Wert des angegebenen Schlüssels um den ganzzahligen Wert, der im delta-Argument angegeben ist.

Gibt den neuen Wert nach der Verringerung bei Erfolg zurück und nil mit einer Zeichenfolge, die den Fehler beschreibt, im Fehlerfall.

stats

syntax: lines, err = memc:stats(args?)

Gibt Informationen zu den Statistiken des memcached-Servers mit einem optionalen args-Argument zurück.

Im Erfolgsfall gibt diese Methode eine Lua-Tabelle zurück, die alle Zeilen der Ausgabe enthält; im Fehlerfall gibt sie nil mit einer Zeichenfolge zurück, die den Fehler beschreibt.

Wenn das args-Argument weggelassen wird, werden allgemeine Serverstatistiken zurückgegeben. Mögliche Werte für das args-Argument sind items, sizes, slabs und andere.

quit

syntax: ok, err = memc:quit()

Teilt dem Server mit, die aktuelle memcached-Verbindung zu schließen.

Gibt 1 im Erfolgsfall und nil andernfalls zurück. Im Fehlerfall wird ein weiterer Stringwert zurückgegeben, um den Fehler zu beschreiben.

Im Allgemeinen können Sie einfach direkt die close-Methode aufrufen, um denselben Effekt zu erzielen.

verbosity

syntax: ok, err = memc:verbosity(level)

Setzt das Verbositätsniveau, das vom memcached-Server verwendet wird. Das level-Argument sollte nur ganze Zahlen enthalten.

Gibt 1 im Erfolgsfall und nil andernfalls zurück. Im Fehlerfall wird ein weiterer Stringwert zurückgegeben, um den Fehler zu beschreiben.

init_pipeline

syntax: err = memc:init_pipeline(n?)

Aktiviert den Memcache-Pipelining-Modus. Alle nachfolgenden Aufrufe von Memcache-Befehlsmethoden werden automatisch gepuffert und beim Aufruf der Methode commit_pipeline in einem Durchgang an den Server gesendet oder durch Aufrufen der Methode cancel_pipeline abgebrochen.

Der optionale Parameter n ist die Größe der Puffertabellen. Standardwert ist 4.

commit_pipeline

syntax: results, err = memc:commit_pipeline()

Beendet den Pipelining-Modus, indem alle zwischengespeicherten Memcache-Abfragen in einem einzigen Durchgang an den Remote-Server übermittelt werden. Alle Antworten auf diese Abfragen werden automatisch gesammelt und werden so zurückgegeben, als ob es sich um eine große Mehrfachantwort auf der höchsten Ebene handelt.

Diese Methode gibt bei Erfolg eine Lua-Tabelle zurück. Bei Fehlern gibt sie eine Lua-Zeichenfolge zurück, die den Fehler beschreibt.

cancel_pipeline

syntax: memc:cancel_pipeline()

Beendet den Pipelining-Modus, indem alle vorhandenen gepufferten Memcache-Befehle seit dem letzten Aufruf der Methode init_pipeline verworfen werden.

Die Methode gibt keinen Wert zurück. Sie hat immer Erfolg.

Automatische Fehlerprotokollierung

Standardmäßig protokolliert das zugrunde liegende ngx_lua Modul Fehler, wenn Socket-Fehler auftreten. Wenn Sie bereits eine ordnungsgemäße Fehlerbehandlung in Ihrem eigenen Lua-Code durchführen, wird empfohlen, diese automatische Fehlerprotokollierung zu deaktivieren, indem Sie die lua_socket_log_errors Direktive von ngx_lua ausschalten, das heißt,

    lua_socket_log_errors off;

Einschränkungen

  • Diese Bibliothek kann nicht in Codekontexten wie set_by_lua*, log_by_lua* und header_filter_by_lua* verwendet werden, in denen die ngx_lua cosocket-API nicht verfügbar ist.
  • Die resty.memcached-Objektinstanz kann nicht auf Modulebene in einer Lua-Variablen gespeichert werden, da sie dann von allen gleichzeitigen Anfragen, die vom selben nginx-Arbeiterprozess bearbeitet werden, geteilt wird (siehe http://wiki.nginx.org/HttpLuaModule#Data_Sharing_within_an_Nginx_Worker) und zu schlechten Race Conditions führt, wenn gleichzeitige Anfragen versuchen, dieselbe resty.memcached-Instanz zu verwenden. Sie sollten immer resty.memcached-Objekte in lokalen Funktionsvariablen oder in der ngx.ctx-Tabelle initiieren. Diese Orte haben alle ihre eigenen Datenkopien für jede Anfrage.

Siehe auch

GitHub

Sie finden zusätzliche Konfigurationstipps und Dokumentationen für dieses Modul im GitHub-Repository für nginx-module-memcached.