GoCaptcha: A high-performance, interactive behavior captcha library for Go. Supporting click, slide, drag-drop, and rotation modes to secure your application
> English | [中文](README_zh.md)
GoCaptcha is a powerful, modular, and highly customizable behavioral CAPTCHA library that supports multiple interactive CAPTCHA types: Click, Slide, Drag-Drop, and Rotate.
⭐️ If it helps you, please give a star.
## Ecosystem
| Project | Desc |
|----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [document](http://gocaptcha.wencodes.com) | GoCaptcha Documentation |
| [online demo](http://gocaptcha.wencodes.com/demo/) | GoCaptcha Online Demo |
| [go-captcha-example](https://github.com/wenlng/go-captcha-example) | Golang + Web + APP Example |
| [go-captcha-assets](https://github.com/wenlng/go-captcha-assets) | Embedded Resource Assets for Golang |
| [go-captcha](https://github.com/wenlng/go-captcha) | Golang CAPTCHA Library |
| [go-captcha-jslib](https://github.com/wenlng/go-captcha-jslib) | JavaScript CAPTCHA Library |
| [go-captcha-vue](https://github.com/wenlng/go-captcha-vue) | Vue CAPTCHA Library |
| [go-captcha-react](https://github.com/wenlng/go-captcha-react) | React CAPTCHA Library |
| [go-captcha-angular](https://github.com/wenlng/go-captcha-angular) | Angular CAPTCHA Library |
| [go-captcha-svelte](https://github.com/wenlng/go-captcha-svelte) | Svelte CAPTCHA Library |
| [go-captcha-solid](https://github.com/wenlng/go-captcha-solid) | Solid CAPTCHA Library |
| [go-captcha-uni](https://github.com/wenlng/go-captcha-uni) | UniApp CAPTCHA, compatible with Apps, Mini-Programs, and Fast Apps |
| [go-captcha-service](https://github.com/wenlng/go-captcha-service) | GoCaptcha Service, supports binary and Docker image deployment,
provides HTTP/gRPC interfaces,
supports standalone and distributed modes (service discovery, load balancing, dynamic configuration) |
| [go-captcha-service-sdk](https://github.com/wenlng/go-captcha-service-sdk) | GoCaptcha Service SDK Toolkit, includes HTTP/gRPC request interfaces,
supports static mode, service discovery, and load balancing. |
| ... | |
## Core Features
- **Diverse CAPTCHA Types**: Supports Click, Slide, Rotate, and Drag behavioral CAPTCHAs, suitable for various interaction scenarios.
- **Highly Customizable**: Flexible configuration of images, fonts, colors, angles, sizes, etc., through Options and Resources.
- **Advanced Image Processing**: Built-in dynamic image generation and processing, supporting main images, thumbnails, puzzle pieces, and shadow effects.
- **Modular Architecture**: Clear code structure, adhering to Go best practices, making it easy to extend and maintain.
- **High-Performance Design**: Optimized resource management and image generation, suitable for high-concurrency scenarios.
- **Cross-Platform Compatibility**: Generated CAPTCHA images can be seamlessly integrated into web applications, mobile apps, or other systems requiring CAPTCHAs.
## CAPTCHA Types
`go-captcha` supports the following four CAPTCHA types, each with unique interaction methods, generation logic, and application scenarios:
1. **Click CAPTCHA**: Users click specified points or characters on the main image, supporting text and graphic modes.
2. **Slide CAPTCHA**: Users slide a puzzle piece to the correct position on the main image, supporting basic and drag-drop modes.
3. **Drag-Drop CAPTCHA**: A variant of the Slide CAPTCHA, allowing users to drag-drop a puzzle piece to a target position within a larger range.
4. **Rotate CAPTCHA**: Users rotate a thumbnail to align with the main image’s angle.
## Install
```shell
$ go get -u github.com/wenlng/go-captcha/v2@latest
```
## Import Module
```go
package main
// Import modules on demand
import "github.com/wenlng/go-captcha/v2/${click|slide|rotate}"
func main(){
// ...
}
```
## Click CAPTCHA
The Click CAPTCHA requires users to click specified points or characters on the main image, ideal for quick verification scenarios. It supports two modes:
- **Text Mode**：Displays characters (e.g., letters, numbers, or Chinese characters), and users click the corresponding characters.
- **Graphic Mode**：Displays graphics (e.g., icons or shapes), and users click the corresponding graphics.
### How It Works
1. **Generate Main Image** (`masterImage`): Contains randomly distributed points or characters, typically in JPEG format.
2. **Generate Thumbnail** (`thumbImage`): Displays the target points or characters to be clicked, typically in PNG format.
3. **User Interaction**: Users click coordinates on the main image, and the frontend captures and sends the coordinates to the backend.
4. **Verification Logic**: The backend compares the clicked coordinates with the target points (`dots`) to verify a match.
### Code Example
```
…
```
### Make Instance
- builder.Make()
- builder.MakeShape()
### Configuration Options
> click.NewBuilder(click.WithXxx(), ...) OR builder.SetOptions(click.WithXxx(), ...)
| Options | Desc |
|--------------------------------------------|------------------------------------------------------------------------------------|
| **Main Image** | |
| click.WithImageSize(option.Size) | Set main image size, default 300x220 |
| click.WithRangeLen(option.RangeVal) | Set range for random content length |
| click.WithRangeAnglePos([]option.RangeVal) | Set range for random angles |
| click.WithRangeSize(option.RangeVal) | Set range for random content size |
| click.WithRangeColors([]string) | Set random colors |
| click.WithDisplayShadow(bool) | Enable/disable shadow display |
| click.WithShadowColor(string) | Set shadow color |
| click.WithShadowPoint(option.Point) | Set shadow offset position |
| click.WithImageAlpha(float32) | Set main image transparency |
| click.WithUseShapeOriginalColor(bool) | Use original graphic color (valid for graphic mode) |
| **Thumbnail** | |
| click.WithThumbImageSize(option.Size) | Set thumbnail size, default 150x40 |
| click.WithRangeVerifyLen(option.RangeVal) | Set range for random verification content length |
| click.WithDisabledRangeVerifyLen(bool) | Disable random verification length, matches main content |
| click.WithRangeThumbSize(option.RangeVal) | Set range for random thumbnail content size |
| click.WithRangeThumbColors([]string) | Set range for random thumbnail colors |
| click.WithRangeThumbBgColors([]string) | Set range for random thumbnail background colors |
| click.WithIsThumbNonDeformAbility(bool) | Prevent thumbnail content deformation |
| click.WithThumbBgDistort(int) | Set thumbnail background distortion (option.DistortLevel1 to option.DistortLevel5) |
| click.WithThumbBgCirclesNum(int) | Set number of small circles in thumbnail background |
| click.WithThumbBgSlimLineNum(int) | Set number of lines in thumbnail background |
### Set Resources
> builder.SetResources(click.WithXxx(), ...)
| Options | Desc |
|-------------------------------------------|----------------------------|
| click.WithChars([]string) | Set text seed |
| click.WithShapes(map[string]image.Image) | Set graphic seed |
| click.WithFonts([]*truetype.Font) | Set fonts |
| click.WithBackgrounds([]image.Image) | Set main image backgrounds |
| click.WithThumbBackgrounds([]image.Image) | Set thumbnail backgrounds |
### Captcha Data
> captData, err := capt.Generate()
| Method | Desc |
|----------