Release 0.1-1: Update Rockspec and Documentation

Author: esidate

.gitignore

@@ -1 +1,2 @@
-.vscode
+.vscode
+*.rock

README.md

@@ -1,20 +1,86 @@
 # Lua Resty Whitelist
 
-Dynamic whitelist in Lua based on ngx_lua for NGINX and OpenResty
+This module can be used to implement a dynamic whitelist in NGINX/OpenResty. This is especially useful to allow access only to some SaaS and Cloud services with dynamic IP addresses, such as Cloudflare, AWS, Azure, etc. For example, some of them may offer security features such as DDOS protection, WAF, etc. but can be bypassed if the origin IP is leaked and the server allows access from any IP address.  
+The module accepts any format of the whitelist (e.g JSON, YAML, plain text, etc.) as long as they contain IPs and/or CIDRs.
 
-:warning: Under construction
+:warning: This project is still in beta. Use at your own risk.
 
-## Publish to LuaRocks
+## How to use
 
-```sh
-# Upload to LuaRocks
-luarocks upload lua-resty-whitelist-*.rockspec
+Installation:
+
+```bash
+luarocks install lua-resty-whitelist
+```
+
+Use it in your nginx configuration:
+
+```nginx
+server {
+    listen 80;
+    server_name localhost;
+
+    # This is required for the module to make HTTP requests, you can use any DNS server
+    resolver 1.1.1.1 ipv6=off;
+
+    location / {
+        lua_code_cache on;
+        access_by_lua_block {
+            local whitelist = require "resty.whitelist"
+
+            local whitelist_urls = {
+                "https://www.cloudflare.com/ips-v4", "https://d7uri8nf7uskq.cloudfront.net/tools/list-cloudfront-ips"
+            }
+            whitelist.new(whitelist_urls)
+
+            -- Or sinlge URL
+
+            local whitelist_url = "https://www.cloudflare.com/ips-v4"
+            whitelist.new(whitelist_url)
+        }
+    }
+}
+```
 
-# Create a source rock
-luarocks pack lua-resty-whitelist-*.rockspec
+## What's missing
+
+- IPv6 support
+- Caching of the whitelist and sharing it between workers
+- Tests
+- Better error handling and logging
+- Better documentation
+
+## Contrubuting
+
+### Publish the package
+
+#### Publish to LuaRocks
+
+```bash
+mv lua-resty-whitelist-*.rockspec lua-resty-whitelist-X.Y-Z.rockspec
+sed -i -E 's/"([0-9]+\.[0-9]+-[0-9]+)"/"X.Y-Z"/g' lua-resty-whitelist-X.Y-Z.rockspec
+
+git add .
+git commit -m "Release X.Y-Z"
+git push
+
+git tag vX.Y-Z
+git push origin vX.Y-Z
+
+luarocks upload lua-resty-whitelist-X.Y-Z.rockspec
 ```
 
-## Running the demo
+#### Publish to GitHub
+
+- A `lua-resty-whitelist-X.Y-Z.src.rock` file will be created in the current directory after publishing to LuaRocks
+- Visit <https://github.com/esidate/lua-resty-whitelist/tags> and click on the tag `vX.Y-Z`
+- Click on "Create release from tag"
+- Click on "Generate release notes" and upload the `lua-resty-whitelist-X.Y-Z.src.rock` file
+- Publish the release
+
+### Running the demo
+
+The demo is also sort of the development environment.
 
 ```sh
 cd demo

demo/default.conf

@@ -4,6 +4,7 @@ server {
     listen 80;
     server_name localhost;
 
+    # This is required for the module to make HTTP requests, you can use any DNS server
     resolver 1.1.1.1 ipv6=off;
 
     location / {
@@ -14,7 +15,7 @@ server {
             local whitelist_urls = {
                 "http://172.18.0.1:9001/list-cloudfront-ips.json", "http://172.18.0.1:9001/list-cloudflare-ips.txt"
             }
-            local whitelist = whitelist.new(whitelist_urls)
+            whitelist.new(whitelist_urls)
         }
     }
 }

dist.ini

@@ -0,0 +1,29 @@
+package = "lua-resty-whitelist"
+version = "0.1-1"
+
+source = {
+  url = "git+https://github.com/esidate/lua-resty-whitelist",
+  tag = "v0.1-0",
+}
+
+description = {
+  summary = "Dynamic whitelist in Lua based on ngx_lua for NGINX and OpenResty",
+  detailed = "This module can be used to implement a dynamic whitelist in NGINX/OpenResty. This is especially useful to allow access only to some SaaS and Cloud services with dynamic IP addresses, such as Cloudflare, AWS, Azure, etc. For example, some of them may offer security features such as DDOS protection, WAF, etc. but can be bypassed if the origin IP is leaked and the server allows access from any IP address.",
+  homepage = "https://github.com/esidate/lua-resty-whitelist",
+  issues_url = "https://github.com/esidate/lua-resty-whitelist/issues",
+  maintainer = "https://www.linkedin.com/in/el-mahdi-sidate/",
+  license = "MIT",
+}
+
+dependencies = {
+  "lua >= 5.1",
+  "resty.iputils >= 0.3",
+  "resty.http >= 0.15",
+}
+
+build = {
+  type = "builtin",
+  modules = {
+    ["resty.whitelist"] = "lib/resty/whitelist.lua",
+  },
+}