Checkpoint Challenge Support

CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing to `lua_resty_netacea`
+
+## Before you start
+
+This repository is for developing the Lua package that is published
+through Luarocks. The Netacea team handles publishing.
+
+Use the existing Docker-based workflow unless you have a specific reason not to:
+
+1. Create `./.env` from `./.env.example`.
+2. Fill in the Netacea environment variables required for the mode you want to test.
+3. Update `./src/conf/nginx.conf` if you need a local server configuration.
+
+## Local development
+
+Start the development container with:
+
+```sh
+docker compose up --build resty
+```
+
+The module will be available on `http://localhost:8080`.
+
+## Testing
+
+Run unit tests in the dev container with:
+
+```sh
+./run_lua_tests.sh
+```
+
+To include coverage output:
+
+```sh
+export LUACOV_REPORT=1 && ./run_lua_tests.sh
+```
+
+You can also run tests through Docker Compose:
+
+```sh
+docker compose run --rm --build test
+```
+
+For coverage through Docker Compose:
+
+```sh
+docker compose run -e LUACOV_REPORT=1 --build test
+```
+
+## Linting
+
+Run the linter with:
+
+```sh
+docker compose run --rm --build lint
+```
+
+## Code style and changes
+
+- Keep changes focused and consistent with the existing Lua style in `src/` and `test/`.
+- Add or update tests when behavior changes.
+- Prefer small, reviewable changes over broad refactors unless a refactor is part of the task.
+
+## Updating the version number
+
+When releasing a new version, update all version references together:
+
+1. Update [`src/lua_resty_netacea.lua`](/home/user/github/lua_resty_netacea/src/lua_resty_netacea.lua) and change `_N._VERSION` to the new library version, for example `1.2.2`.
+2. Rename the rockspec file to match the new release, for example `lua_resty_netacea-1.2.2-0.rockspec`.
+3. Update the `version = "..."` field inside the rockspec to the same value.
+4. Update any build files that reference the rockspec filename:
+   - [`Dockerfile`](/home/user/github/lua_resty_netacea/Dockerfile)
+   - [`Dockerfile.nginx_lua`](/home/user/github/lua_resty_netacea/Dockerfile.nginx_lua)
+5. Update any other hardcoded version references you introduce in future changes.
+
+The package version and the rockspec version should stay in sync, with the rockspec using the `-0` release suffix.
+
+## Security issues
+
+Report security issues by email to [security@netacea.com](mailto:security@netacea.com).
+Include a description of the issue, the steps to reproduce it, affected versions, and any known mitigations.

Dockerfile

@@ -9,9 +9,9 @@ RUN apt-get install -y libssl-dev
 
 
 FROM base AS build
-COPY ./lua_resty_netacea-1.2.0-0.rockspec ./
+COPY ./lua_resty_netacea-1.3.0-0.rockspec ./
 COPY ./src ./src
-RUN /usr/local/openresty/luajit/bin/luarocks make ./lua_resty_netacea-1.2.0-0.rockspec
+RUN /usr/local/openresty/luajit/bin/luarocks make ./lua_resty_netacea-1.3.0-0.rockspec
 
 FROM build AS test
 

Dockerfile.nginx_lua

@@ -69,9 +69,9 @@ RUN cd /usr/src && \
     make install
 
 # Set up Netacea module
-COPY ./lua_resty_netacea-0.2-2.rockspec ./
+COPY ./lua_resty_netacea-1.3.0-0.rockspec ./
 COPY ./src ./src
-RUN luarocks make ./lua_resty_netacea-0.2-2.rockspec
+RUN luarocks make ./lua_resty_netacea-1.3.0-0.rockspec
 
 # Link CA certs so they match expected filename
 RUN ln -s /etc/ssl/certs/ca-bundle.crt /etc/ssl/certs/ca-certificates.crt

README.md

@@ -1,60 +1,52 @@
 # lua_resty_netacea
 
-An Openresty module for easy integration of Netacea services. This repo is for developing the package. The package can be accessed by the Luarocks package management platform. See the Netacea documentation for making use of the module.
+An Openresty module for easy integration of Netacea services. This repo is for
+developing the package. The package can be accessed by the Luarocks package
+management platform. See the Netacea documentation for making use of the module.
 
 ## Published package
 
-The Netacea package is available on the Luarocks package manager. Publishing is handled by the Netacea team.
+The Netacea package is available on the Luarocks package manager.
+Publishing is handled by the Netacea team.
+
+## Contributing to this Repository
+
+If you wish to make a contribution to this repository, please see
+[CONTRIBUTING.md](/home/user/github/lua_resty_netacea/CONTRIBUTING.md).
 
 ## Docker images
 
-The Dockerfile contains a multi-stage build, including:
+This repository includes Dockerfiles and Docker Compose services for running the
+existing code without making any changes.
 
-| Stage name | Based on | Description |
-| -- | -- | -- |
-| base  |  openresty/openresty:noble | Base image of Openresty with updated packages around openSSL |
-| build | base | Working Openresty instance with Netacea plugin installed using luarocks and rockspec file |
-| test | build | Lua packages installed for testing and linting. Command overridden to run unit tests |
-| lint | test | Command overridden to run luacheck linter and output results |
+### Prerequisites
 
-The docker compose file is used to mount local files to the right place in the image to support development.
+- Docker Engine or Docker Desktop
+- Docker Compose
+- A local `.env` file if you want to supply Netacea runtime values
 
-### Environment variables
+### Build the image
 
-The Docker Compose services that run NGINX load Netacea configuration from a local `.env` file.
-Create it from the example file, then fill in the values provided by the Netacea Solutions Engineering team:
+To build the OpenResty image used by the `resty` service:
 
 ```sh
-cp .env.example .env
+docker compose build resty
 ```
 
-The `.env` file is ignored by git because it can contain sensitive values such as API keys, cookie encryption keys, and Kinesis credentials.
-Keep `.env.example` updated when adding or removing configuration variables.
-
-### Run development version
-
-1. Create `./.env` from `./.env.example` and set the Netacea environment variables.
-2. Update `./src/conf/nginx.conf` to include server configuration. See "Configuration" below.
-3. `docker compose up --build resty`
-4. Access [](http://localhost:8080)
-
-### Run tests
+This uses [`Dockerfile`](/home/user/github/lua_resty_netacea/Dockerfile) and
+builds the package from the checked-in rockspec and source files.
 
-#### Unit tests
+### Run the module locally
 
-##### In dev container
+The `resty` service starts OpenResty with the module loaded and exposes it on
+`http://localhost:8080`:
 
-Without coverage report: `./run_lua_tests.sh`
-With coverage report (sent to stdout) `export LUACOV_REPORT=1 && ./run_lua_tests.sh`
-
-##### Docker compose
-
-Without coverage report: `docker compose run --rm --build test`
-With coverage report (sent to stdout) `docker compose run -e LUACOV_REPORT=1 --build test [> output.html]`
-
-#### Linter
+```sh
+docker compose up --build resty
+```
 
-`docker compose run --rm --build lint`
+Before starting it, create a `.env` file from `.env.example` and set the
+runtime values required by your selected protection mode.
 
 ## Configuration
 
@@ -136,6 +128,7 @@ NETACEA_PROTECTOR_API_URL=https://your-protector-api-url
 | `NETACEA_CAPTCHA_COOKIE_ATTRIBUTES` | `Max-Age=86400; Path=/;` |
 | `NETACEA_REAL_IP_HEADER`            | `""`                     |
 | `NETACEA_REAL_IP_HEADER_INDEX`      | unset                    |
+| `NETACEA_CHECKPOINT_SIGNAL_PATH`    | unset                    |
 | `NETACEA_KINESIS_ACCESS_KEY`        | `""`                     |
 | `NETACEA_KINESIS_SECRET_KEY`        | `""`                     |
 | `NETACEA_KINESIS_STREAM_NAME`       | `""`                     |

docker-compose.yml

@@ -1,5 +1,3 @@
-version: '3.5'
-
 services:
   resty:
     build:

lua_resty_netacea-1.2.0-0.rockspec → lua_resty_netacea-1.3.0-0.rockspec

@@ -1,5 +1,5 @@
 package = "lua_resty_netacea"
-version = "1.2.0-0"
+version = "1.3.0-0"
 source = {
   url = "git://github.com/Netacea/lua_resty_netacea",
   branch = "master"

src/conf/nginx.conf

@@ -12,6 +12,7 @@ env NETACEA_SECRET_KEY;
 env NETACEA_INGEST_ENABLED;
 env NETACEA_REAL_IP_HEADER;
 env NETACEA_REAL_IP_HEADER_INDEX;
+env NETACEA_CHECKPOINT_SIGNAL_PATH;
 env NETACEA_KINESIS_ACCESS_KEY;
 env NETACEA_KINESIS_SECRET_KEY;
 env NETACEA_KINESIS_STREAM_NAME;
@@ -51,6 +52,7 @@ http {
       captchaCookieAttributes = env('NETACEA_CAPTCHA_COOKIE_ATTRIBUTES', ''),
       realIpHeader        = env('NETACEA_REAL_IP_HEADER', ''),
       realIpHeaderIndex   = tonumber(env('NETACEA_REAL_IP_HEADER_INDEX', '')),
+      checkpointSignalPath = env('NETACEA_CHECKPOINT_SIGNAL_PATH'),
       kinesisProperties   = {
         region         = env('NETACEA_KINESIS_REGION', 'eu-west-1'),
         stream_name    = env('NETACEA_KINESIS_STREAM_NAME', ''),