Zalgo is a RESTful app capable to generate and validate Captcha Images embracing twelve factors and cutting edge performances
- Full stricted Typescript code
- Ultra fast image (captcha) generation thanks to Rust native code
- Fine granular configuration of Eslint, Prettier and Tsc
- ✨ 100% coverage ✨
- Provide two distincted API for captcha generation and validation
- Client submission are constrained in time and number
- Api doc yaml following 3.0 spec
- A full-fledged Dockerfile take care of any aspect of building and shipping
The entire lifecycle of request-response is handled by the Nodejs app. Image generation (CPU-bounded sync task) is executed by calling Rust native code and Node Napi interface thanks to Neon project.
A new captcha image is issued when invoking a PUT request. This request return a Json that consists of an unique
idand abase64string image field constrained by anExpireheader. Following requests to Captcha validation are now performed by calling a POST api with a previous uniqueidand asolutiontext-based field that solves the previous base64 string image.
Zalgo uses a number of open source projects to work properly:
- PolkaJS - A micro web server so fast, it'll make you dance! 👯
- Nanoid - A tiny, secure, URL-friendly, unique string ID generator for JavaScript.
- Node.js - evented I/O for the backend
- Rust - A language empowering everyone to build reliable and efficient software
- Neon - Electrify your Node with the power of Rust!
- Pino - 🌲 super fast, all natural json logger 🌲
And of course Zalgo Captcha itself is open source with a public repository on GitHub.
Zalgo requires Node.js v12+ to run and Rust to compile captcha package.
Install the Nodejs runtime and Rust language following respective documentations. Then to start Rust code compilation, install Neon Cli:
npm install --global neon-cli
# OR
yarn global add neon-cliNow compile Rust code with Nodejs bindings:
cd zalgo-captcha/pkg/zalgo-captcha
npm run compileInstall dependencies and start the server.
cd zalgo-captcha
npm i
LOG_LEVEL=info node run startFor production environments (ie: without logging):
npm install --production
NODE_ENV=production node appWhat follows is a table of principal variables and some examples
| Env Name | Example |
|---|---|
| NODE_ENV | production |
| LOG_LEVEL | info, warn, error or debug, default silent |
| PORT | default 3000 |
| CAPTCHA_TTL | default 120 secs |
| CAPTCHA_ATTEMPTS | default 5 secs |
Once dependencies were installed, execute
npm run test
For coverage:
npm run test:coverage
Zalgo is very easy to install and deploy in a Docker container.
By default, the Docker container will expose port 3000, so change this within the Dockerfile if necessary. When ready, simply use the Dockerfile to build the image.
cd zalgo-captcha
docker build -t <youruser>/zalgo:${package.json.version} .This will create the zalgo image and pull in the necessary dependencies.
Once done, run the Docker image and map the port to whatever you wish on your host. In this example, we simply map port 3000 of the host to port 3000 of the Docker (or whatever port was exposed in the Dockerfile):
docker run -d -p 3000:3000 --restart=always --name=zalgo <youruser>/zalgo:${package.json.version}Verify the server execution by issuing the following command.
curl -H "Content-Type: application/json" http://localhost:3000/healthcheckThen ask for a new captcha with
curl -H "Content-Type: application/json" -X PUT http://localhost:3000/v1/captchaSubmit a solution through:
curl -H "Content-Type: application/json" -vX POST http://localhost:3000/v1/captcha/PupuNxYWZOYrw8ftnoCBu -d '{"solution":"xyz"}'
Note: default captcha liveness is about
2minutes. After that a new captcha must be generated.
Among this repository is available an example of integration. You can run this example from browser tab after spawned a static server, ie:
cd example
npx static-server
MIT