[major] Prefer multi-layer routing for v2

Breaking changes:

- Requires Traefik v3.6 or newer so deployments can use multi-layer routing parentRefs.

- Removes `ipv4subnetMask`, `ipv6subnetMask`, and `rateLimit`. Given the distributed nature of bots these config values have become additional config/logic that adds no real value. Most crawlers at this point are issuing a small amount of requests per IP across a wide range of subnets.

- Removes `enableStateReconciliation` and all state reconciliation code. `persistentStateFile` is now restart persistence only, not multi-instance coordination.

- Makes Traefik multi-layer routing the preferred multi-service protection model: attach captcha-protect to one parent router and route accepted traffic through child routers.

Implementation notes:

- Adds first-class CI coverage for the documented file-provider multi-layer routing config across Traefik v3.6, v3.7, and latest.

- Drops older Traefik integration targets below v3.6.

- Keeps Docker label smoke coverage for single-router provider configuration.

- Updates README and plugin metadata for the v2 behavior and Traefik baseline.

Closes #95

Author: joecorall

.github/workflows/lint-test.yml

@@ -53,43 +53,59 @@ jobs:
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
-  integration-test-latest:
+  integration-test-labels:
     needs: [run]
     permissions:
       contents: read
     runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        traefik: [v3.6, v3.7, latest]
+    env:
+      TRAEFIK_TAG: ${{ matrix.traefik }}
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
 
       - name: run
         run: go run test.go
         working-directory: ./ci
-        env:
-          TRAEFIK_TAG: latest
+
+      - name: capture logs
+        if: ${{ always() }}
+        run: docker compose logs --tail 100 nginx nginx2 traefik
+        working-directory: ./ci
 
       - name: cleanup
         if: ${{ always() }}
-        run: docker compose logs --tail 100 nginx nginx2 traefik && docker compose down
+        run: docker compose down
         working-directory: ./ci
 
-  integration-test:
-    needs: [integration-test-latest]
+  integration-test-multilayer-routing:
+    needs: [run]
     permissions:
       contents: read
     runs-on: ubuntu-24.04
     strategy:
+      fail-fast: false
       matrix:
-        traefik: [v2.11, v3.0, v3.1, v3.2, v3.3, v3.4, v3.5, v3.6, v3.7]
+        traefik: [v3.6, v3.7, latest]
+    env:
+      COMPOSE_FILE: docker-compose.multilayer.yml
+      TRAEFIK_TAG: ${{ matrix.traefik }}
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
 
       - name: run
         run: go run test.go
         working-directory: ./ci
-        env:
-          TRAEFIK_TAG: ${{ matrix.traefik }}
+
+      - name: capture logs
+        if: ${{ always() }}
+        run: docker compose logs --tail 100 nginx nginx2 traefik
+        working-directory: ./ci
 
       - name: cleanup
         if: ${{ always() }}
-        run: docker compose logs --tail 100 nginx nginx2 traefik && docker compose down
+        run: docker compose down
         working-directory: ./ci

.traefik.yml

@@ -1,14 +1,12 @@
 displayName: Captcha Protect
-summary: Add an anti-bot challenge to individual IPs in a subnet when traffic spikes are detected from that subnet
+summary: Add an anti-bot challenge to protected routes
 type: middleware
 import: github.com/libops/captcha-protect
 testData:
   ProtectRoutes: /
   ChallengeTmpl: challenge.tmpl.html
   Window: 86400
-  RateLimit: 20
   IPForwardedHeader: "X-Forwarded-For"
   CaptchaProvider: turnstile
   SiteKey: 1x00000000000000000000AA
   SecretKey: 1x0000000000000000000000000000000AA
-  EnableStateReconciliation: "false"

README.md

@@ -1,4 +1,4 @@
-TRAEFIK_TAG=v3.5
+TRAEFIK_TAG=v3.6
 NGINX_TAG=1.27.4-alpine3.21
 TURNSTILE_SITE_KEY=1x00000000000000000000AA
 TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA

ci/.env

@@ -0,0 +1,54 @@
+http:
+  routers:
+    protected-parent:
+      entryPoints:
+        - http
+      rule: "Host(`localhost`)"
+      middlewares:
+        - captcha-protect
+
+    nginx:
+      rule: "PathPrefix(`/`)"
+      priority: 1
+      service: nginx
+      parentRefs:
+        - protected-parent
+
+    nginx2:
+      rule: "PathPrefix(`/app2`)"
+      priority: 100
+      service: nginx2
+      parentRefs:
+        - protected-parent
+
+  services:
+    nginx:
+      loadBalancer:
+        servers:
+          - url: "http://nginx:80"
+    nginx2:
+      loadBalancer:
+        servers:
+          - url: "http://nginx2:80"
+
+  middlewares:
+    captcha-protect:
+      plugin:
+        captcha-protect:
+          captchaProvider: turnstile
+          window: 120
+          siteKey: 1x00000000000000000000AA
+          secretKey: 1x0000000000000000000000000000000AA
+          enableStatsPage: "true"
+          ipForwardedHeader: X-Forwarded-For
+          logLevel: DEBUG
+          protectParameters: "false"
+          goodBots: []
+          enableGooglebotIPCheck: "false"
+          enableUptimeRobotBypass: "false"
+          mode: regex
+          protectRoutes:
+            - "^/"
+          excludeRoutes:
+            - "\\/oai\\/request"
+            - "\\/node\\/\\d+\\/(book-)?manifest"

ci/conf/traefik/multilayer.yml

@@ -0,0 +1,60 @@
+networks:
+    default:
+
+services:
+    nginx:
+        image: nginx:${NGINX_TAG}
+        healthcheck:
+            test: curl -fs http://localhost/healthz | grep -q OK || exit 1
+            start_period: 5s
+        volumes:
+            - ./conf/nginx/default.conf:/etc/nginx/conf.d/default.conf:r
+        networks:
+            default:
+                aliases:
+                    - nginx
+
+    nginx2:
+        image: nginx:${NGINX_TAG}
+        healthcheck:
+            test: curl -fs http://localhost/healthz | grep -q OK || exit 1
+            start_period: 5s
+        volumes:
+            - ./conf/nginx/default.conf:/etc/nginx/conf.d/default.conf:r
+        networks:
+            default:
+                aliases:
+                    - nginx2
+
+    traefik:
+        image: traefik:${TRAEFIK_TAG}
+        command: >-
+            --api.insecure=true
+            --api.dashboard=true
+            --api.debug=true
+            --ping=true
+            --entryPoints.http.address=:80
+            --entryPoints.http.forwardedHeaders.insecure=true
+            --entryPoints.http.forwardedHeaders.trustedIPs=127.0.0.1/32,::1/128,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
+            --providers.file.filename=/etc/traefik/dynamic/multilayer.yml
+            --experimental.localPlugins.captcha-protect.moduleName=github.com/libops/captcha-protect
+        volumes:
+            - ./conf/traefik/multilayer.yml:/etc/traefik/dynamic/multilayer.yml:r
+            - ./../:/plugins-local/src/github.com/libops/captcha-protect:r
+        ports:
+            - "80:80"
+            - "8080:8080"
+        mem_limit: 256m
+        mem_reservation: 128m
+        networks:
+            default:
+                aliases:
+                    - traefik
+        healthcheck:
+            test: traefik healthcheck --ping
+            start_period: 5s
+        depends_on:
+            nginx:
+                condition: service_healthy
+            nginx2:
+                condition: service_healthy

ci/docker-compose.multilayer.yml

@@ -12,7 +12,6 @@ services:
             traefik.http.routers.nginx.middlewares: captcha-protect@docker
             traefik.http.middlewares.captcha-protect.plugin.captcha-protect.captchaProvider: turnstile
             traefik.http.middlewares.captcha-protect.plugin.captcha-protect.window: 120
-            traefik.http.middlewares.captcha-protect.plugin.captcha-protect.rateLimit: ${RATE_LIMIT}
             traefik.http.middlewares.captcha-protect.plugin.captcha-protect.siteKey: ${TURNSTILE_SITE_KEY}
             traefik.http.middlewares.captcha-protect.plugin.captcha-protect.secretKey: ${TURNSTILE_SECRET_KEY}
             traefik.http.middlewares.captcha-protect.plugin.captcha-protect.enableStatsPage: "true"
@@ -25,8 +24,6 @@ services:
             traefik.http.middlewares.captcha-protect.plugin.captcha-protect.mode: "regex"
             traefik.http.middlewares.captcha-protect.plugin.captcha-protect.protectRoutes: "^/"
             traefik.http.middlewares.captcha-protect.plugin.captcha-protect.excludeRoutes: "\\/oai\\/request,\\/node\\/\\d+\\/(book-)?manifest"
-            traefik.http.middlewares.captcha-protect.plugin.captcha-protect.persistentStateFile: "/tmp/state.json"
-            traefik.http.middlewares.captcha-protect.plugin.captcha-protect.enableStateReconciliation: "true"
         healthcheck:
             test: curl -fs http://localhost/healthz | grep -q OK || exit 1
             start_period: 5s
@@ -47,7 +44,6 @@ services:
             traefik.http.routers.nginx2.middlewares: captcha-protect@docker
             traefik.http.middlewares.captcha-protect.plugin.captcha-protect.captchaProvider: turnstile
             traefik.http.middlewares.captcha-protect.plugin.captcha-protect.window: 120
-            traefik.http.middlewares.captcha-protect.plugin.captcha-protect.rateLimit: ${RATE_LIMIT}
             traefik.http.middlewares.captcha-protect.plugin.captcha-protect.siteKey: ${TURNSTILE_SITE_KEY}
             traefik.http.middlewares.captcha-protect.plugin.captcha-protect.secretKey: ${TURNSTILE_SECRET_KEY}
             traefik.http.middlewares.captcha-protect.plugin.captcha-protect.enableStatsPage: "true"
@@ -60,8 +56,6 @@ services:
             traefik.http.middlewares.captcha-protect.plugin.captcha-protect.mode: "regex"
             traefik.http.middlewares.captcha-protect.plugin.captcha-protect.protectRoutes: "^/"
             traefik.http.middlewares.captcha-protect.plugin.captcha-protect.excludeRoutes: "\\/oai\\/request,\\/node\\/\\d+\\/(book-)?manifest"
-            traefik.http.middlewares.captcha-protect.plugin.captcha-protect.persistentStateFile: "/tmp/state.json"
-            traefik.http.middlewares.captcha-protect.plugin.captcha-protect.enableStateReconciliation: "true"
         healthcheck:
             test: curl -fs http://localhost/healthz | grep -q OK || exit 1
             start_period: 5s
@@ -86,7 +80,6 @@ services:
             --experimental.localPlugins.captcha-protect.moduleName=github.com/libops/captcha-protect
         volumes:
             - /var/run/docker.sock:/var/run/docker.sock:z
-            - ./tmp:/tmp:rw
             - ./../:/plugins-local/src/github.com/libops/captcha-protect:r
         ports:
             - "80:80"