justcaptcha/README.md

justcaptcha
===========

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. E.g. `style=dark`.

#### 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
- `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.

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 solved
- `403` 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 {
        ... // do something if there was no image returned
    }

    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
    ...