bin | ||
build/archlinux | ||
cmd/justcaptchad | ||
init | ||
internal/http | ||
pkg | ||
.gitignore | ||
go.mod | ||
go.sum | ||
LICENSE | ||
Makefile | ||
README.md |
justcaptcha ver. 2.0.1
A simple CAPTCHA service implementation.
Service usage
justcaptchad -expiry 10m -listen /var/run/justcaptcha/sock
-expiry
takes time for CAPTCHA to be valid for in format X{s,m,h}.
-listen
is ip:port
or /path/to/unix.sock
to listen on.
Service HTTP API
Errors
All error codes are returned with an error message in text/plain
.
Create a new CAPTCHA
POST /
It will return an ID of a new CAPTCHA in text/plain
.
HTTP codes
201
if created (always being created)
Get an image for a CAPTCHA
GET /:captcha_id/image?style=
Responds with an image in JPEG format (image/jpeg
).
An optional URL parameter style=
set a name of a CAPTCHA style if it is
supported by CAPTCHA implementation.
HTTP codes
200
if exists404
if doesn't exist500
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
202
if solved403
if not solved
Check if captcha is solved
GET /:captcha_id?remove
Responds with an empty body and one of the HTTP codes.
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.
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 to be expired. E.g. when a visitor requests for a new CAPTCHA or leaving a page.
HTTP codes
204
if solved403
if not solved
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
...