Aller au contenu

memcached: pilote client Lua memcached pour nginx-module-lua basé sur l'API cosocket

Installation

Si vous n'avez pas configuré l'abonnement au dépôt RPM, inscrivez-vous. Ensuite, vous pouvez procéder avec les étapes suivantes.

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

Pour utiliser cette bibliothèque Lua avec NGINX, assurez-vous que nginx-module-lua est installé.

Ce document décrit lua-resty-memcached v0.17 publié le 19 janvier 2023.

Cette bibliothèque Lua est un pilote client memcached pour le module ngx_lua de nginx :

http://wiki.nginx.org/HttpLuaModule

Cette bibliothèque Lua tire parti de l'API cosocket de ngx_lua, qui garantit un comportement 100 % non-bloquant.

Notez qu'au moins ngx_lua 0.5.0rc29 ou OpenResty 1.0.15.7 est requis.

Synopsis

    server {
        location /test {
            content_by_lua '
                local memcached = require "resty.memcached"
                local memc, err = memcached:new()
                if not memc then
                    ngx.say("échec de l'instanciation de memc : ", err)
                    return
                end

                memc:set_timeout(1000) -- 1 sec

                -- ou connectez-vous à un fichier de socket de domaine unix écouté
                -- par un serveur memcached :
                --     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("échec de la connexion : ", err)
                    return
                end

                local ok, err = memc:flush_all()
                if not ok then
                    ngx.say("échec de la vidange : ", err)
                    return
                end

                local ok, err = memc:set("dog", 32)
                if not ok then
                    ngx.say("échec de la définition de dog : ", err)
                    return
                end

                local res, flags, err = memc:get("dog")
                if err then
                    ngx.say("échec de la récupération de dog : ", err)
                    return
                end

                if not res then
                    ngx.say("dog non trouvé")
                    return
                end

                ngx.say("dog : ", res)

                -- mettez-le dans le pool de connexions de taille 100,
                -- avec un délai d'inactivité maximal de 10 secondes
                local ok, err = memc:set_keepalive(10000, 100)
                if not ok then
                    ngx.say("impossible de définir keepalive : ", err)
                    return
                end

                -- ou fermez simplement la connexion tout de suite :
                -- local ok, err = memc:close()
                -- if not ok then
                --     ngx.say("échec de la fermeture : ", err)
                --     return
                -- end
            ';
        }
    }

Méthodes

L'argument key fourni dans les méthodes suivantes sera automatiquement échappé selon les règles d'échappement URI avant d'être envoyé au serveur memcached.

new

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

Crée un objet memcached. En cas d'échec, renvoie nil et une chaîne décrivant l'erreur.

Il accepte un argument de table opts optionnel. Les options suivantes sont prises en charge :

  • key_transform

    une table de tableau contenant deux fonctions pour échapper et déséchapper les clés memcached, respectivement. Par défaut, les clés memcached seront échappées et déséchappées en tant que composants URI, c'est-à-dire

    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")

Tente de se connecter à l'hôte distant et au port que le serveur memcached écoute ou à un fichier de socket de domaine unix local écouté par le serveur memcached.

Avant de résoudre réellement le nom d'hôte et de se connecter au backend distant, cette méthode recherchera toujours dans le pool de connexions des connexions inactives correspondantes créées par les appels précédents de cette méthode.

sslhandshake

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

Effectue la poignée de main SSL/TLS sur la connexion actuellement établie. Voir l'API tcpsock.sslhandshake d'OpenResty pour plus de détails.

set

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

Insère une entrée dans memcached sans condition. Si la clé existe déjà, elle la remplace.

L'argument value peut également être une table Lua contenant plusieurs chaînes Lua qui doivent être concaténées dans leur ensemble (sans aucun délimiteur). Par exemple,

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

est fonctionnellement équivalent à

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

Le paramètre exptime est optionnel et par défaut à 0 (ce qui signifie qu'il n'expire jamais). Le temps d'expiration est en secondes.

Le paramètre flags est optionnel et par défaut à 0.

set_timeout

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

Définit le délai d'expiration (en ms) pour les opérations suivantes, y compris la méthode connect.

Renvoie 1 en cas de succès et nil plus une chaîne décrivant l'erreur sinon.

set_timeouts

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

Définit les délais d'expiration (en ms) pour les opérations de connexion, d'envoi et de lecture respectivement.

Renvoie 1 en cas de succès et nil plus une chaîne décrivant l'erreur sinon.

set_keepalive

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

Met la connexion memcached actuelle immédiatement dans le pool de connexions cosocket ngx_lua.

Vous pouvez spécifier le délai d'inactivité maximal (en ms) lorsque la connexion est dans le pool et la taille maximale du pool pour chaque processus de travail nginx.

En cas de succès, renvoie 1. En cas d'erreurs, renvoie nil avec une chaîne décrivant l'erreur.

N'appelez cette méthode que là où vous auriez appelé la méthode close à la place. Appeler cette méthode mettra immédiatement l'objet memcached actuel dans l'état closed. Toute opération ultérieure autre que connect() sur l'objet actuel renverra l'erreur closed.

get_reused_times

syntax: times, err = memc:get_reused_times()

Cette méthode renvoie le nombre de fois (avec succès) réutilisées pour la connexion actuelle. En cas d'erreur, elle renvoie nil et une chaîne décrivant l'erreur.

Si la connexion actuelle ne provient pas du pool de connexions intégré, alors cette méthode renvoie toujours 0, c'est-à-dire que la connexion n'a jamais été réutilisée (jusqu'à présent). Si la connexion provient du pool de connexions, alors la valeur de retour est toujours non nulle. Donc, cette méthode peut également être utilisée pour déterminer si la connexion actuelle provient du pool.

close

syntax: ok, err = memc:close()

Ferme la connexion memcached actuelle et renvoie le statut.

En cas de succès, renvoie 1. En cas d'erreurs, renvoie nil avec une chaîne décrivant l'erreur.

add

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

Insère une entrée dans memcached si et seulement si la clé n'existe pas.

L'argument value peut également être une table Lua contenant plusieurs chaînes Lua qui doivent être concaténées dans leur ensemble (sans aucun délimiteur). Par exemple,

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

est fonctionnellement équivalent à

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

Le paramètre exptime est optionnel et par défaut à 0 (ce qui signifie qu'il n'expire jamais). Le temps d'expiration est en secondes.

Le paramètre flags est optionnel, par défaut à 0.

En cas de succès, renvoie 1. En cas d'erreurs, renvoie nil avec une chaîne décrivant l'erreur.

replace

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

Insère une entrée dans memcached si et seulement si la clé existe.

L'argument value peut également être une table Lua contenant plusieurs chaînes Lua qui doivent être concaténées dans leur ensemble (sans aucun délimiteur). Par exemple,

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

est fonctionnellement équivalent à

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

Le paramètre exptime est optionnel et par défaut à 0 (ce qui signifie qu'il n'expire jamais). Le temps d'expiration est en secondes.

Le paramètre flags est optionnel, par défaut à 0.

En cas de succès, renvoie 1. En cas d'erreurs, renvoie nil avec une chaîne décrivant l'erreur.

append

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

Ajoute la valeur à une entrée avec la même clé qui existe déjà dans memcached.

L'argument value peut également être une table Lua contenant plusieurs chaînes Lua qui doivent être concaténées dans leur ensemble (sans aucun délimiteur). Par exemple,

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

est fonctionnellement équivalent à

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

Le paramètre exptime est optionnel et par défaut à 0 (ce qui signifie qu'il n'expire jamais). Le temps d'expiration est en secondes.

Le paramètre flags est optionnel, par défaut à 0.

En cas de succès, renvoie 1. En cas d'erreurs, renvoie nil avec une chaîne décrivant l'erreur.

prepend

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

Ajoute la valeur au début d'une entrée avec la même clé qui existe déjà dans memcached.

L'argument value peut également être une table Lua contenant plusieurs chaînes Lua qui doivent être concaténées dans leur ensemble (sans aucun délimiteur). Par exemple,

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

est fonctionnellement équivalent à

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

Le paramètre exptime est optionnel et par défaut à 0 (ce qui signifie qu'il n'expire jamais). Le temps d'expiration est en secondes.

Le paramètre flags est optionnel et par défaut à 0.

En cas de succès, renvoie 1. En cas d'erreurs, renvoie nil avec une chaîne décrivant l'erreur.

get

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

Récupère une seule entrée ou plusieurs entrées dans le serveur memcached via une seule clé ou une table de clés.

Discutons d'abord du cas où la clé est une seule chaîne.

La valeur de la clé et la valeur des drapeaux associés seront renvoyées si l'entrée est trouvée et qu'aucune erreur ne se produit.

En cas d'erreurs, les valeurs nil seront retournées pour value et flags et une 3ème valeur (chaîne) sera également renvoyée pour décrire l'erreur.

Si l'entrée n'est pas trouvée, alors trois valeurs nil seront retournées.

Ensuite, discutons du cas où une table Lua de plusieurs clés est fournie.

Dans ce cas, une table Lua contenant les paires clé-résultat sera toujours renvoyée en cas de succès. Chaque valeur correspondant à chaque clé dans la table est également une table contenant deux valeurs, la valeur de la clé et les drapeaux de la clé. Si une clé n'existe pas, alors il n'y a pas d'entrées correspondantes dans la table results.

En cas d'erreurs, nil sera retourné, et la deuxième valeur de retour sera une chaîne décrivant l'erreur.

gets

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

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

Tout comme la méthode get, mais renverra également la valeur CAS unique associée à l'entrée en plus de la valeur de la clé et des drapeaux.

Cette méthode est généralement utilisée avec la méthode cas.

cas

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

Tout comme la méthode set, mais effectue une opération de vérification et de définition, ce qui signifie "stockez ces données mais seulement si personne d'autre ne les a mises à jour depuis que je les ai récupérées pour la dernière fois."

L'argument cas_unique peut être obtenu à partir de la méthode gets.

touch

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

Met à jour le temps d'expiration d'une clé existante.

Renvoie 1 en cas de succès ou nil avec une chaîne décrivant l'erreur sinon.

Cette méthode a été introduite pour la première fois dans la version v0.11.

flush_all

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

Vidange (ou invalide) toutes les entrées existantes dans le serveur memcached immédiatement (par défaut) ou après l'expiration spécifiée par l'argument time (en secondes).

En cas de succès, renvoie 1. En cas d'erreurs, renvoie nil avec une chaîne décrivant l'erreur.

delete

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

Supprime la clé de memcached immédiatement.

La clé à supprimer doit déjà exister dans memcached.

En cas de succès, renvoie 1. En cas d'erreurs, renvoie nil avec une chaîne décrivant l'erreur.

incr

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

Incrémente la valeur de la clé spécifiée par la valeur entière spécifiée dans l'argument delta.

Renvoie la nouvelle valeur après incrémentation en cas de succès, et nil avec une chaîne décrivant l'erreur en cas d'échecs.

decr

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

Décrémente la valeur de la clé spécifiée par la valeur entière spécifiée dans l'argument delta.

Renvoie la nouvelle valeur après décrémentation en cas de succès, et nil avec une chaîne décrivant l'erreur en cas d'échecs.

stats

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

Renvoie des informations statistiques sur le serveur memcached avec un argument optionnel args.

En cas de succès, cette méthode renvoie une table lua contenant toutes les lignes de la sortie ; en cas d'échecs, elle renvoie nil avec une chaîne décrivant l'erreur.

Si l'argument args est omis, des statistiques générales du serveur sont renvoyées. Les valeurs possibles pour l'argument args sont items, sizes, slabs, entre autres.

quit

syntax: ok, err = memc:quit()

Indique au serveur de fermer la connexion memcached actuelle.

Renvoie 1 en cas de succès et nil sinon. En cas d'échecs, une autre valeur de chaîne sera également renvoyée pour décrire l'erreur.

En général, vous pouvez simplement appeler directement la méthode close pour obtenir le même effet.

verbosity

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

Définit le niveau de verbosité utilisé par le serveur memcached. L'argument level doit être donné uniquement sous forme d'entiers.

Renvoie 1 en cas de succès et nil sinon. En cas d'échecs, une autre valeur de chaîne sera également renvoyée pour décrire l'erreur.

init_pipeline

syntax: err = memc:init_pipeline(n?)

Active le mode de pipeline Memcache. Tous les appels suivants aux méthodes de commande Memcache seront automatiquement mis en mémoire tampon et envoyés au serveur en une seule exécution lorsque la méthode commit_pipeline est appelée ou annulés en appelant la méthode cancel_pipeline.

Le paramètre optionnel n est la taille des tables de tampon. valeur par défaut 4

commit_pipeline

syntax: results, err = memc:commit_pipeline()

Quitte le mode de pipeline en engageant toutes les requêtes Memcache mises en cache vers le serveur distant en une seule exécution. Toutes les réponses à ces requêtes seront collectées automatiquement et renvoyées comme si c'était une grande réponse multi-bulk au niveau le plus élevé.

Cette méthode renvoie une table lua en cas de succès. échoue en renvoyant une chaîne lua décrivant l'erreur en cas d'échecs.

cancel_pipeline

syntax: memc:cancel_pipeline()

Quitte le mode de pipeline en abandonnant toutes les commandes Memcache mises en mémoire tampon existantes depuis le dernier appel à la méthode init_pipeline.

la méthode ne renvoie rien. réussit toujours.

Journalisation automatique des erreurs

Par défaut, le module sous-jacent ngx_lua effectue une journalisation des erreurs lorsque des erreurs de socket se produisent. Si vous gérez déjà correctement les erreurs dans votre propre code Lua, il est recommandé de désactiver cette journalisation automatique des erreurs en désactivant la directive lua_socket_log_errors de ngx_lua, c'est-à-dire,

    lua_socket_log_errors off;

Limitations

  • Cette bibliothèque ne peut pas être utilisée dans des contextes de code comme set_by_lua*, log_by_lua*, et header_filter_by_lua* où l'API cosocket ngx_lua n'est pas disponible.
  • L'instance d'objet resty.memcached ne peut pas être stockée dans une variable Lua au niveau du module Lua, car elle sera alors partagée par toutes les requêtes concurrentes traitées par le même processus de travail nginx (voir http://wiki.nginx.org/HttpLuaModule#Data_Sharing_within_an_Nginx_Worker) et entraînera de mauvaises conditions de concurrence lorsque des requêtes concurrentes essaient d'utiliser la même instance resty.memcached. Vous devez toujours initier des objets resty.memcached dans des variables locales de fonction ou dans la table ngx.ctx. Ces endroits ont tous leurs propres copies de données pour chaque requête.

Voir aussi

GitHub

Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-memcached.