{"id":13776667,"url":"https://github.com/api7/lua-resty-ipmatcher","last_synced_at":"2025-04-06T02:19:45.939Z","repository":{"id":47736993,"uuid":"207127034","full_name":"api7/lua-resty-ipmatcher","owner":"api7","description":"High-performance match IP address for Nginx + Lua","archived":false,"fork":false,"pushed_at":"2023-06-19T05:42:04.000Z","size":35,"stargazers_count":125,"open_issues_count":7,"forks_count":46,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-02T03:51:39.956Z","etag":null,"topics":["cidr-format","ipv4","ipv6-address","lua","openresty","parse"],"latest_commit_sha":null,"homepage":"https://www.apiseven.com/","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/api7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2019-09-08T14:46:33.000Z","updated_at":"2025-03-22T10:17:05.000Z","dependencies_parsed_at":"2024-08-03T18:10:36.027Z","dependency_job_id":"640b47a3-9ee7-4c98-b268-6cade90691ee","html_url":"https://github.com/api7/lua-resty-ipmatcher","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/api7%2Flua-resty-ipmatcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/api7%2Flua-resty-ipmatcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/api7%2Flua-resty-ipmatcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/api7%2Flua-resty-ipmatcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/api7","download_url":"https://codeload.github.com/api7/lua-resty-ipmatcher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247423915,"owners_count":20936688,"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":["cidr-format","ipv4","ipv6-address","lua","openresty","parse"],"created_at":"2024-08-03T18:00:31.315Z","updated_at":"2025-04-06T02:19:45.920Z","avatar_url":"https://github.com/api7.png","language":"Lua","readme":"# Name\n\nHigh-performance IP address matching for OpenResty Lua.\n\n# Table of Contents\n\n- [Name](#name)\n- [Table of Contents](#table-of-contents)\n- [Synopsis](#synopsis)\n- [Methods](#methods)\n  - [ipmatcher.new](#ipmatchernew)\n    - [Usage](#usage)\n    - [Example](#example)\n  - [ipmatcher.new\\_with\\_value](#ipmatchernew_with_value)\n    - [Usage](#usage-1)\n    - [Example](#example-1)\n  - [ip:match](#ipmatch)\n    - [Usage](#usage-2)\n    - [Example](#example-2)\n  - [ip:match\\_bin](#ipmatch_bin)\n    - [Usage](#usage-3)\n    - [Example](#example-3)\n  - [ipmatcher.parse\\_ipv4](#ipmatcherparse_ipv4)\n  - [ipmatcher.parse\\_ipv6](#ipmatcherparse_ipv6)\n- [Installation](#installation)\n  - [From LuaRocks](#from-luarocks)\n  - [From Source](#from-source)\n\n# Synopsis\n\n```lua\nlocation / {\n    content_by_lua_block {\n      local ipmatcher = require(\"resty.ipmatcher\")\n      local ip = ipmatcher.new({\n          \"127.0.0.1\",\n          \"192.168.0.0/16\",\n          \"::1\",\n          \"fe80::/32\",\n      })\n\n      ngx.say(ip:match(\"127.0.0.1\"))\n      ngx.say(ip:match(\"192.168.1.100\"))\n      ngx.say(ip:match(\"::1\"))\n    }\n}\n```\n\n[Back to TOC](#table-of-contents)\n\n# Methods\n\n## ipmatcher.new\n\nCreates a new hash table to store IP addresses.\n\n### Usage\n\n`ips` is a list of IPv4 or IPv6 IP addresses in a CIDR format (`{ip1, ip2, ip3, ...}`). \n\n```lua\nok, err = ipmatcher.new(ips)\n```\n\nReturns `nil` and the error if it fails to create a new `ipmatcher` instance. \n\n### Example\n\n```lua\nlocal ip, err = ipmatcher.new({\n        \"127.0.0.1\", \"192.168.0.0/16\", \"::1\", \"fe80::/16\",\n    })\n```\n\n[Back to TOC](#table-of-contents)\n\n## ipmatcher.new_with_value\n\nCreates a new hash table to store IP addresses and corresponding values.\n\n### Usage\n\n`ips` is a list of key-value pairs (`{[ip1] = val1, [ip2] = val2, ...}`), where each key is an IP address string (CIDR format for IPv4 and IPv6).\n\n```lua\nmatcher, err = ipmatcher.new_with_value(ips)\n```\n\nReturns `nil` and the error if it fails to create a new `ipmatcher` instance. \n\n### Example\n\n```lua\nlocal ip, err = ipmatcher.new_with_value({\n    [\"127.0.0.1\"] = {info = \"a\"},\n    [\"192.168.0.0/16\"] = {info = \"b\"},\n})\nlocal data, err = ip:match(\"192.168.0.1\")\nprint(data.info) -- \"b\"\n```\n\nIf the IP address matches multiple values, the returned value can be either one of the values:\n\n```lua\nlocal ip, err = ipmatcher.new_with_value({\n    [\"192.168.0.1\"] = {info = \"a\"},\n    [\"192.168.0.0/16\"] = {info = \"b\"},\n})\nlocal data, err = ip:match(\"192.168.0.1\")\nprint(data.info) -- \"a\" or \"b\"\n```\n\n[Back to TOC](#table-of-contents)\n\n## ip:match\n\nChecks if an IP address exists in the specified IP list.\n\n### Usage\n\n`ip` is an IP address string.\n\n```lua\nok, err = ip:match(ip)\n```\n\nReturns `true` or `value` if the specified `ip` exists in the list. Returns `false` if the `ip` does not exist in the list. And returns `false` and an error message if the IP address is invalid.\n\n### Example\n\n```lua\nlocal ip, err = ipmatcher.new({\n        \"127.0.0.1\", \"192.168.0.0/16\", \"::1\", \"fe80::/16\",\n    })\n\nlocal ok, err = ip:match(\"127.0.0.1\") -- true\n```\n\n[Back to TOC](#table-of-contents)\n\n## ip:match_bin\n\nChecks if an IP address in binary format exists in the specified IP list.\n\n### Usage\n\n`bin_ip` is an IP address in binary format.\n\n```lua\nok, err = ip:match_bin(bin_ip)\n```\n\nReturns `true` if the specified `bin_ip` exists in the list. Returns `false` if it does not exist. Returns `nil` and an error message if `bin_ip` is invalid.\n\n### Example\n\n```lua\nlocal ok, err = ip:match_bin(ngx.var.binary_remote_addr)\n```\n\n[Back to TOC](#table-of-contents)\n\n## ipmatcher.parse_ipv4\n\nTries to parse an IPv4 address to a host byte order FFI `uint32_t` type integer.\n\n```lua\nipmatcher.parse_ipv4(ip)\n```\n\nReturns `false` if the IP address is invalid.\n\n[Back to TOC](#table-of-contents)\n\n## ipmatcher.parse_ipv6\n\nTries to parse an IPv6 address to a table with four host byte order FF1 `uint32_t` type integer. The IP address can be wrapped in square brackets like `[::1]`.\n\n```lua\nipmatcher.parse_ipv6(ip)\n```\n\nReturns a `false` if the ip is not a valid IPv6 address.\n\n[Back to TOC](#table-of-contents)\n\n# Installation\n\n## From LuaRocks\n\n```shell\nluarocks install lua-resty-ipmatcher\n```\n\n## From Source\n\n```shell\nmake install\n```\n\n[Back to TOC](#table-of-contents)\n","funding_links":[],"categories":["Libraries"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapi7%2Flua-resty-ipmatcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapi7%2Flua-resty-ipmatcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapi7%2Flua-resty-ipmatcher/lists"}