captcha

README

go captcha

🧩 go captcha is a simple, lightweight library for generating and verifying image-based CAPTCHA codes written in Go.

---

✨ Features

• 🖼️ Generate CAPTCHA images with customizable size and font
• 🔐 Built-in encryption for secure token handling
• 🧠 Optional cache drivers: in-memory or Redis
• ⚙️ Flexible configuration using options pattern
• 💨 Zero external dependencies (except freetype and go-redis/v9)

---

🚀 Installation

go get github.com/kal72/go-captcha@latest

---

🧱 Usage Example

Basic Example

package main

import (
    "fmt"
    "github.com/kal72/go-captcha"
)

func main() {
    cap := captcha.New("secret-key")

    base64Image, text, token, err := cap.Generate()
	if err != nil {
		panic(err)
	}

	fmt.Println("text: " + text)
	fmt.Println("token: " + token)
	fmt.Println("image: " + base64Image)

    // Verify
    err = cap.Verify(text, token)
	if err != nil {
		panic("verify failed: " + err.Error())
	} else {
        fmt.Println("verify success ")
    }
}

Using Redis Driver

import (
    "github.com/kal72/go-captcha"
    "github.com/kal72/go-captcha/driver/redisstore"
)

cap := captcha.New("secret-key",
    captcha.WithStore(redisstore.New(redisstore.Config{
        Addr: "localhost:6379",
        Password: "pass",
        DB: 0,
        Prefix: "captcha",
    })),
)

---

📸 Example CAPTCHA Image

Example output image generated:

CAPTCHA Example

---

⚙️ Configuration Options

Option	Description
WithLength(n int)	Number of characters in the CAPTCHA code
WithSize(width, height int)	CAPTCHA image size in pixels
WithFontSize(size int)	Font size in pixels
WithExpire(seconds int)	Expiration time in seconds
WithStore(store Store)	Use custom store driver (memory, Redis, or your own)

---

🧩 Custom Driver

To create a custom driver, implement the Store interface:

type Store interface {
    Set(key, value string, ttl time.Duration) error
    Get(key string) (string, error)
    Delete(key string) error
}

Then register it via:

captcha.WithStore(myCustomDriver)

---

🖋️ Example Directory

See full runnable examples in the examples/ folder:

examples/
 ├── basic/
 ├── redis/

Run an example:

go run ./examples/basic

---

📦 Project Structure

gocaptcha/
├── captcha.go
├── config.go
├── store.go
├── driver/
│   ├── memorystore/
│   └── redisstore/
├── internal/
│   ├── image/
│   ├── random/
│   └── assets/
│       └── fonts/
│           └── DejaVuSans-Bold.ttf
└── examples/

Documentation

Index

• func New(secret string, opts ...Option) *captcha
• type Config
• type Option
  • func WithExpire(seconds int) Option
  • func WithFontSize(fontSize float64) Option
  • func WithLength(n int) Option
  • func WithSize(width, height int) Option
  • func WithStore(store Store) Option
• type Store

Functions

func New

func New(secret string, opts ...Option) *captcha

Defaut config

Width:     200
Height:    80
Length:    6
Expire:    60 //seconds
FontSize:  38
Store:     memorystore.New()

Use New(secret string, opts ...Option) with option to manual config

Types

type Config

type Config struct {
	SecretKey string
	Width     int
	Height    int
	Length    int
	Expire    int
	FontSize  float64
	Store     Store
}

type Option

type Option func(*Config)

func WithExpire

func WithExpire(seconds int) Option

Expire the captcha code.

Expire defines the CAPTCHA expiration time in seconds.

func WithFontSize

func WithFontSize(fontSize float64) Option

FontSize defines the font size used to render the CAPTCHA text in pixels.

func WithLength

func WithLength(n int) Option

Length defines the number of characters in the CAPTCHA code.

func WithSize

func WithSize(width, height int) Option

Width and Height define the image size of the generated CAPTCHA in pixels.

func WithStore

func WithStore(store Store) Option

Available: memorystore or redisstore.

To create a custom driver, implement the `Store` interface to define your own storage backend for CAPTCHA data.

type Store

type Store interface {
	Set(key string, value string, ttl time.Duration) error
	Get(key string) (string, error)
	Delete(key string) error
}

Store defines the interface for CAPTCHA data storage. To create a custom driver, implement this interface.