justcaptcha/README.md

132 lines
3.1 KiB
Markdown
Raw Normal View History

justcaptcha ver. 2.0.1
======================
A simple CAPTCHA service implementation.
2023-01-08 17:38:51 +04:00
## Service usage
2022-06-26 21:01:47 +04:00
2023-01-08 17:38:51 +04:00
justcaptchad -expiry 10m -listen /var/run/justcaptcha/sock
2022-06-26 21:01:47 +04:00
2022-08-19 21:37:51 +04:00
`-expiry` takes time for CAPTCHA to be valid for in format X{s,m,h}.
2022-06-26 21:01:47 +04:00
`-listen` is `ip:port` or `/path/to/unix.sock` to listen on.
2023-01-08 17:38:51 +04:00
## Service HTTP API
2022-10-20 22:49:08 +04:00
### Errors
2022-10-20 22:49:08 +04:00
All error codes are returned with an error message in `text/plain`.
2022-10-20 22:49:08 +04:00
### Create a new CAPTCHA
POST /
It will return an ID of a new CAPTCHA in `text/plain`.
#### HTTP codes
2022-10-20 22:49:08 +04:00
- `201` if created (always being created)
### Get an image for a CAPTCHA
GET /:captcha_id/image?style=
2022-10-20 22:49:08 +04:00
Responds with an image in JPEG format (`image/jpeg`).
2022-10-20 22:49:08 +04:00
An optional URL parameter `style=` set a name of a CAPTCHA style if it is
2023-01-08 17:38:51 +04:00
supported by CAPTCHA implementation.
#### HTTP codes
- `200` if exists
- `404` if doesn't exist
- `500` if for some reason an image wasn't created
### Submit an answer
POST /:captcha_id
Accepts `application/x-www-form-urlencoded` content type.
It takes one parameter `answer=123456`.
Responds with an empty body and one of the HTTP codes.
#### HTTP codes
2022-10-20 22:49:08 +04:00
- `202` if solved
- `403` if not solved
### Check if captcha is solved
GET /:captcha_id?remove
Responds with an empty body and one of the HTTP codes.
2022-10-20 22:49:08 +04:00
If an optional `remove` parameter without a value supplied CAPTCHA will be
removed without checking and a HTTP code `204` will be sent. Otherwise, a `403`
HTTP code will be sent if it is not solved.
2022-10-20 22:49:08 +04:00
A `remove` parameter was added because browsers will print an error in a console
if HTTP code is not within `2xx`, so to keep a console clean you can provide
this parameter.
This can be useful to remove an unused CAPTCHA from a DB without waiting for it
2022-10-20 22:49:08 +04:00
to be expired. E.g. when a visitor requests for a new CAPTCHA or leaving a page.
#### HTTP codes
2022-10-20 22:49:08 +04:00
- `204` if solved
- `403` if not solved
2022-10-20 22:49:08 +04:00
### Example of interaction
First a client makes a POST request with empty body to create a new CAPTCHA and obtains an ID for it.
POST /
As a result we get an ID `n60f2K9JiD5c4qX9MYe90A54nT0nnJrtgfhAjfaWtBg`.
Then a client requests an image for a new CAPTCHA. E.g. with a dark style.
GET /n60f2K9JiD5c4qX9MYe90A54nT0nnJrtgfhAjfaWtBg/image?style=dark
Then a client submits an answer for a CAPTCHA.
POST 'answer=198807' /n60f2K9JiD5c4qX9MYe90A54nT0nnJrtgfhAjfaWtBg
And if answer was correct a client gets a HTTP code 202. Or 403 otherwise.
Then a server checks if CAPTCHA was solved with following request.
GET /n60f2K9JiD5c4qX9MYe90A54nT0nnJrtgfhAjfaWtBg
## Library usage
A simple example using built-in dwelling CAPTCHA implementation.
Create a new CAPTCHA:
c := dwcaptcha.NewDwellingCaptcha(expiry)
_, id := inmemdb.New(someAdditionalDataUsedInIDGenerationUsuallyIPAddr, c)
Get an image for a CAPTCHA:
i := inmemdb.Image(captchaID, captchaStyle)
if i == nil {
... // error handling
}
jpeg.Encode(w, *i, &jpeg.Options{Quality: 20})
Solve a CAPTCHA:
if ok := inmemdb.Solve(captchaID, answer); !ok {
... // not solved
}
// solved
...
Check is CAPTCHA was solved:
if ok := inmemdb.IsSolved(captchaID); !ok {
... // not solved
}
// solved
...