Home

Development and Testing

The information here is mostly of interest to Curity developers who code the plugin.
If you are interested in extending the plugin, the same instructions can be followed.

Prerequisites

A Perl test framework is used that runs against NGINX with the LUA module enabled.
See the Test::Nginx and OpenResty Testing docs to understand syntax.
On macOS, the easiest setup is to install OpenResty, the plugin dependencies and the test framework.
Also ensure that Docker is installed, since it is used for deployment and testing:

brew install openresty/brew/openresty
opm install ledgetech/lua-resty-http
opm install SkyLothar/lua-resty-jwt
sudo cpan Test::Nginx

OpenResty will then point to an nginx instance at a path such as this.

/usr/local/Cellar/openresty/1.25.3.1_1/nginx/sbin

Run Unit Tests

The prove utility can then be run to execute tests in the project's t folder.
Ensure that the root test.sh points to your OpenResty root location, then run the script.
This triggers a Docker deployment of the Curity Identity Server, so a license file is also needed.
Detailed tests are then run against the plugin, with different configurations:

export LICENSE_FILE_PATH=~/Desktop/license.json
./test.sh

Understand Test Behavior

Each test spins up an instance of NGINX under the t/servroot folder which runs on the default test port of 1984.
Tests that are expected to succeed use proxy_pass to route to a target that runs after the module and simply returns.
This example returns the JWT access token as a target API response header, to support assertions.

location /t {
    rewrite_by_lua_block {

        local config = {
            introspection_endpoint = 'https://login.example.com/oauth/v2/oauth-introspect',
            client_id = 'introspection-client',
            client_secret = 'Password1',
            token_cache_seconds = 900
        }

        local phantomTokenPlugin = require 'resty.phantom-token'
        phantomTokenPlugin.execute(config)
    }
    
    proxy_pass http://localhost:1984/target;
}
location /target {
    add_header 'authorization' $http_authorization;
    return 200;
}

Troubleshoot Failed Tests

If one test out of many is failing, then edit the Makefile to run a single file instead of *.t:

prove -v -f t/api_requests.t

Then add the ONLY directive to limit test execution to the single test that is failing:

--- config
location /t {
    ...
}

--- request
GET /t

--- ONLY

View the t/servroot/conf/nginx.conf file to see the deployed configuration for a test.
If required, add ngx_log_error statements to LUA code, then look at logs at t/servroot/logs/error.log.
If you get cryptic permission errors or locked files, delete the t/servroot folder.

Deploy the Plugin

Use Docker to deploy OpenResty and the plugin:

./docker/deploy.sh openresty

Or use Docker to deploy Kong and the plugin:

./docker/deploy.sh kong

In both cases the Curity Identity Server and a minimal API are also deployed, for end-to-end testing.
Call the API via the gateway at http://localhost:3000:

OPAQUE_ACCESS_TOKEN='42665300-efe8-419d-be52-07b53e208f46'
curl -i -X GET http://localhost:3000/api \
-H "Authorization: Bearer $OPAQUE_ACCESS_TOKEN"

This will return an unauthorized error with a response similar to this.
The gateway logs will be visible in the terminal window for troubleshooting.

HTTP/1.1 401 Unauthorized
Content-Type: application/json
WWW-Authenticate: Bearer

{"code":"unauthorized","message":"Missing, invalid or expired access token"}

Run HTTP Smoke Tests

Next run some curl based tests in another terminal window.
Only a handful of sanity tests are run against the deployed system:

./docker/test.sh

To troubleshoot failures, see the docker/response.txt file and the gateway logs.

Publishing

Search for instances of the current version in the rockspec file, READMEs and the Kong handler class.
Update them to the new version, eg 2.0.0, then rename the rockspec files.
Then check changes into GitHub, and create a new tag matching that in the rockspec files:

git tag v2.0.0 -m "A message containing details for this release"
git push --tags

Login to luarocks.org with the curity luarocks account and upload the latest rockspec files.
These commands will then work for customers:

luarocks install kong-phantom-token 2.0.0
luarocks install lua-resty-phantom-token 2.0.0