{"id":24075505,"url":"https://github.com/carlosabalde/libvmod-valkey","last_synced_at":"2025-02-26T22:42:48.636Z","repository":{"id":268549508,"uuid":"904691427","full_name":"carlosabalde/libvmod-valkey","owner":"carlosabalde","description":"VMOD using the synchronous libvalkey library API to access Valkey servers from VCL","archived":false,"fork":false,"pushed_at":"2025-02-21T10:51:07.000Z","size":976,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-21T11:42:15.099Z","etag":null,"topics":["redis","valkey","varnish-cache","vmods"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carlosabalde.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-17T11:23:34.000Z","updated_at":"2025-02-21T10:50:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"f2a5a4d5-704f-41ea-9f44-e3f19ae15f4f","html_url":"https://github.com/carlosabalde/libvmod-valkey","commit_stats":null,"previous_names":["carlosabalde/libvmod-valkey"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosabalde%2Flibvmod-valkey","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosabalde%2Flibvmod-valkey/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosabalde%2Flibvmod-valkey/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosabalde%2Flibvmod-valkey/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carlosabalde","download_url":"https://codeload.github.com/carlosabalde/libvmod-valkey/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240947648,"owners_count":19883029,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["redis","valkey","varnish-cache","vmods"],"created_at":"2025-01-09T19:05:58.480Z","updated_at":"2025-02-26T22:42:48.597Z","avatar_url":"https://github.com/carlosabalde.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n.. image:: https://github.com/carlosabalde/libvmod-valkey/actions/workflows/main.yml/badge.svg?branch=master\n   :alt: GitHub Actions CI badge\n   :target: https://github.com/carlosabalde/libvmod-valkey/actions\n.. image:: https://codecov.io/gh/carlosabalde/libvmod-valkey/branch/master/graph/badge.svg\n   :alt: Codecov badge\n   :target: https://codecov.io/gh/carlosabalde/libvmod-valkey\n\nVMOD using the `synchronous libvalkey library API \u003chttps://github.com/valkey-io/libvalkey\u003e`_ to access Valkey servers from VCL. Based on the `libvmod-redis VMOD \u003chttps://github.com/carlosabalde/libvmod-redis\u003e`_ project.\n\nHighlights:\n\n* **Full support for execution of LUA scripts** (i.e. ``EVAL`` command), including optimistic automatic execution of ``EVALSHA`` commands.\n* **All Valkey reply data types are supported**, including partial support to access to components of simple (i.e. not nested) array replies.\n* **Valkey pipelines are not (and won't be) supported**. LUA scripting, which is fully supported by the VMOD, it's a much more flexible alternative to pipelines for atomic execution and minimizing latency. Pipelines are hard to use and error prone, specially when using the ``WATCH`` command.\n* **Support for classic Valkey deployments** using multiple replicated Valkey servers **and for clustered deployments based on Valkey Cluster**.\n* **Support for multiple databases and multiple Valkey connections**, local to each Varnish worker thread, or shared using one or more pools.\n* **Support for smart command execution**, selecting the destination server according with the preferred role (i.e. master or slave) and with distance and healthiness metrics collected during execution.\n* **Support for Valkey Sentinel**, allowing automatic discovery of sick / healthy servers and changes in their roles.\n\nLooking for official support for this VMOD? Please, contact `Allenta Consulting \u003chttps://www.allenta.com\u003e`_, a `Varnish Software Premium partner \u003chttps://www.varnish-software.com/partner/allenta-consulting\u003e`_.\n\nSYNOPSIS\n========\n\nimport valkey;\n\n::\n\n    ##\n    ## Subnets.\n    ##\n\n    Function subnets(STRING masks=\"\")\n\n    ##\n    ## Sentinels.\n    ##\n\n    Function sentinels(\n        STRING locations=\"\",\n        INT period=60,\n        INT connection_timeout=500,\n        INT command_timeout=0,\n        ENUM { RESP2, RESP3, default } protocol=\"default\",\n        BOOL tls=false,\n        STRING tls_cafile=\"\",\n        STRING tls_capath=\"\",\n        STRING tls_certfile=\"\",\n        STRING tls_keyfile=\"\",\n        STRING tls_sni=\"\",\n        STRING password=\"\")\n\n    ##\n    ## Proxy.\n    ##\n\n    # Instance selection.\n    Function VOID use(STRING db)\n\n    # Proxied methods.\n    Method VOID .add_server(..., STRING db=\"\")\n    Function VOID command(..., STRING db=\"\")\n    Function VOID timeout(..., STRING db=\"\")\n    Function VOID retries(..., STRING db=\"\")\n    ...\n    Method STRING .stats(..., STRING db=\"\")\n    Method INT .counter(..., STRING db=\"\")\n\n    ##\n    ## Databases.\n    ##\n\n    # Constructor.\n    Object db(\n        STRING location=\"\",\n        ENUM { master, slave, auto, cluster } type=\"auto\",\n        INT connection_timeout=1000,\n        INT connection_ttl=0,\n        INT command_timeout=0,\n        INT max_command_retries=0,\n        BOOL shared_connections=true,\n        INT max_connections=128,\n        ENUM { RESP2, RESP3, default } protocol=\"default\",\n        BOOL tls=false,\n        STRING tls_cafile=\"\",\n        STRING tls_capath=\"\",\n        STRING tls_certfile=\"\",\n        STRING tls_keyfile=\"\",\n        STRING tls_sni=\"\",\n        STRING user=\"\",\n        STRING password=\"\",\n        INT sickness_ttl=60,\n        BOOL ignore_slaves=false,\n        INT max_cluster_hops=32)\n    Method VOID .add_server(\n        STRING location,\n        ENUM { master, slave, auto, cluster } type)\n\n    # Command execution.\n    Method VOID .command(STRING name)\n    Method VOID .timeout(INT command_timeout)\n    Method VOID .retries(INT max_command_retries)\n    Method VOID .push(STRING arg)\n    Method VOID .execute(BOOL master=true)\n    Method VOID .easy_execute(STRING command, [STRING command_args...], BOOL master=true, INT command_timeout, INT max_command_retries)\n\n    # Access to replies.\n    Method BOOL .replied()\n\n    Method BOOL .reply_is_error()\n    Method BOOL .reply_is_nil()\n    Method BOOL .reply_is_status()\n    Method BOOL .reply_is_integer()\n    Method BOOL .reply_is_boolean()\n    Method BOOL .reply_is_double()\n    Method BOOL .reply_is_string()\n    Method BOOL .reply_is_array()\n\n    Method STRING .get_reply()\n\n    Method STRING .get_error_reply()\n    Method STRING .get_status_reply()\n    Method INT .get_integer_reply()\n    Method BOOL .get_boolean_reply()\n    Method REAL .get_double_reply()\n    Method STRING .get_string_reply()\n\n    Method INT .get_array_reply_length()\n    Method BOOL .array_reply_is_error(INT index)\n    Method BOOL .array_reply_is_nil(INT index)\n    Method BOOL .array_reply_is_status(INT index)\n    Method BOOL .array_reply_is_integer(INT index)\n    Method BOOL .array_reply_is_boolean(INT index)\n    Method BOOL .array_reply_is_double(INT index)\n    Method BOOL .array_reply_is_string(INT index)\n    Method BOOL .array_reply_is_array(INT index)\n    Method STRING .get_array_reply_value(INT index)\n\n    # Other.\n    Method VOID .free()\n    Method STRING .stats(\n        ENUM { json, prometheus } format=\"json\",\n        BOOL stream=0,\n        STRING prometheus_name_prefix=\"vmod_valkey_\",\n        BOOL prometheus_default_labels=1,\n        STRING prometheus_extra_labels=\"\")\n    Method INT .counter(STRING name)\n\nEXAMPLES\n========\n\nSingle server\n-------------\n\n::\n\n    sub vcl_init {\n        # VMOD configuration: simple case, keeping up to one Valkey connection\n        # per Varnish worker thread.\n        new db = valkey.db(\n            location=\"192.168.1.100:6379\",\n            type=master,\n            connection_timeout=500,\n            shared_connections=false,\n            max_connections=1);\n    }\n\n    sub vcl_deliver {\n        # Simple command execution.\n        db.command(\"SET\");\n        db.push(\"foo\");\n        db.push(\"Hello world!\");\n        db.execute();\n\n        # Alternatively, the same can be achieved with one single command\n        db.easy_execute(\"SET\", \"foo\", \"Hello world!\");\n\n        # LUA scripting.\n        db.command(\"EVAL\");\n        db.push({\"\n            server.call('SET', KEYS[1], ARGV[1])\n            server.call('SET', KEYS[2], ARGV[1])\n        \"});\n        db.push(\"2\");\n        db.push(\"foo\");\n        db.push(\"bar\");\n        db.push(\"Atomic hello world!\");\n        db.execute();\n\n        # Array replies, checking \u0026 accessing to reply.\n        db.command(\"MGET\");\n        db.push(\"foo\");\n        db.push(\"bar\");\n        db.execute();\n        if ((db.reply_is_array()) \u0026\u0026\n            (db.get_array_reply_length() == 2)) {\n            set resp.http.X-Foo = db.get_array_reply_value(0);\n            set resp.http.X-Bar = db.get_array_reply_value(1);\n        }\n    }\n\nMultiple servers\n----------------\n\n::\n\n    sub vcl_init {\n        # VMOD configuration: master-slave replication, keeping up to two\n        # Valkey connections per Varnish worker thread (up to one to the master\n        # server \u0026 up to one to the closest slave server).\n        valkey.subnets(\n            masks={\"\n                0 192.168.1.102/32,\n                1 192.168.1.103/32,\n                2 0.0.0.0/32\n            \"});\n        new db = valkey.db(\n            location=\"192.168.1.100:6379\",\n            type=master,\n            connection_timeout=500,\n            shared_connections=false,\n            max_connections=2);\n        db.add_server(\"192.168.1.101:6379\", slave);\n        db.add_server(\"192.168.1.102:6379\", slave);\n        db.add_server(\"192.168.1.103:6379\", slave);\n    }\n\n    sub vcl_deliver {\n        # SET submitted to the master server.\n        db.command(\"SET\");\n        db.push(\"foo\");\n        db.push(\"Hello world!\");\n        db.execute();\n\n        # GET submitted to one of the slave servers.\n        db.command(\"GET\");\n        db.push(\"foo\");\n        db.execute(false);\n        set req.http.X-Foo = db.get_string_reply();\n    }\n\nClustered setup\n---------------\n\n::\n\n    sub vcl_init {\n        # VMOD configuration: clustered setup, keeping up to 100 Valkey\n        # connections per server, all shared between all Varnish worker threads.\n        # Two initial cluster servers are provided; remaining servers are\n        # automatically discovered.\n        new db = valkey.db(\n            location=\"192.168.1.100:6379\",\n            type=cluster,\n            connection_timeout=500,\n            shared_connections=true,\n            max_connections=128,\n            max_cluster_hops=16);\n        db.add_server(\"192.168.1.101:6379\", cluster);\n    }\n\n    sub vcl_deliver {\n        # SET internally routed to the destination server.\n        db.command(\"SET\");\n        db.push(\"foo\");\n        db.push(\"Hello world!\");\n        db.execute();\n\n        # GET internally routed to the destination server.\n        db.command(\"GET\");\n        db.push(\"foo\");\n        db.execute(false);\n        set req.http.X-Foo = db.get_string_reply();\n    }\n\nINSTALLATION\n============\n\nThe source tree is based on autotools to configure the building, and does also have the necessary bits in place to do functional unit tests using the varnishtest tool.\n\n**Beware this project contains multiples branches (master, 6.0, 7.6, etc.). Please, select the branch to be used depending on your Varnish Cache version (Varnish trunk → master, Varnish 6.0.x → 6.0, Varnish 7.6.x → 7.6, etc.).**\n\nDependencies:\n\n* `libvalkey \u003chttps://github.com/valkey-io/libvalkey\u003e`_ - Valkey client library in C.\n* `libev \u003chttp://software.schmorp.de/pkg/libev.html\u003e`_ - full-featured and high-performance event loop.\n\nCOPYRIGHT\n=========\n\nSee LICENSE for details.\n\nPublic domain implementation of the SHA-1 cryptographic hash function by Steve Reid and embedded in this VMOD (required for the optimistic execution of ``EVALSHA`` commands) has been borrowed from `this project \u003chttps://github.com/clibs/sha1/\u003e`_:\n\n* https://github.com/clibs/sha1/blob/master/sha1.c\n* https://github.com/clibs/sha1/blob/master/sha1.h\n\nBSD's implementation of the CRC-16 cryptographic hash function by Georges Menie \u0026 Salvatore Sanfilippo and embedded in this VMOD (required for the Valkey Cluster slot calculation) has been borrowed from the `Redis project \u003chttps://redis.io\u003e`_:\n\n* http://download.redis.io/redis-stable/src/crc16.c\n\nCopyright (c) Carlos Abalde \u003ccarlos.abalde@gmail.com\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlosabalde%2Flibvmod-valkey","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarlosabalde%2Flibvmod-valkey","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlosabalde%2Flibvmod-valkey/lists"}