Go Turnstile

https://pkg.go.dev/github.com/tordrt/go-turnstile
Admin
A simple, thread-safe Go client library for verifying Cloudflare Turnstile CAPTCHA tokens with...
Tokens:16,725
Snippets:176
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install go-turnstile

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Use `go get` to install the go-turnstile library.

```go
go get github.com/tordrt/go-turnstile

```

--------------------------------

### Quick Start: Verify CAPTCHA Tokens in Go

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

This example demonstrates how to set up a basic HTTP server that verifies Turnstile CAPTCHA tokens submitted from a client. It includes setting up the Turnstile client and handling verification requests.

```go
package main

import (
    "fmt"
    "log"
    "net/http"
    
    "github.com/tordrt/go-turnstile"
)

func main() {
    // Create a new Turnstile client
	tturnstileClient, err := turnstile.New("your-site-key", "your-secret-key")
    if err != nil {
        log.Fatal(err)
    }

    http.HandleFunc("/verify", func(w http.ResponseWriter, r *http.Request) {
        // Verify the token from the HTTP request
        response, err := turnstileClient.VerifyRequest(r.Context(), r)
        if err != nil {
            http.Error(w, "CAPTCHA verification failed", http.StatusBadRequest)
            return
        }
        
        fmt.Fprintf(w, "Verification successful! Hostname: %s", response.Hostname)
    })
    
    log.Println("Server starting on :8080")
    http.ListenAndServe(":8080", nil)
}

```

--------------------------------

### Example: Changing Mock Behavior Dynamically

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

This example demonstrates changing mock behavior dynamically.

```text
Output:
First call success: true
Second call failed: true

```

--------------------------------

### Complete Test Example with Multiple Client Configurations

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Demonstrates a comprehensive test suite using various `turnstile.Client` configurations, including a standard test client, one that always fails, and one simulating a token spent error. This allows for testing different verification outcomes.

```go
func TestTurnstileHandler(t *testing.T) {
    tests := []struct {
        name        string
        client      *turnstile.Client
        expectError bool
    }{
        {
            name:        "successful verification",
            client:      turnstile.NewTestClient(),
            expectError: false,
        },
        {
            name:        "failed verification",
            client:      turnstile.NewTestClientAlwaysFail(),
            expectError: true,
        },
        {
            name:        "duplicate token",
            client:      turnstile.NewTestClientTokenSpent(),
            expectError: true,
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            response, err := tt.client.VerifyToken(
                context.Background(),
                turnstile.TestToken,
            )

            if tt.expectError && err == nil {
                t.Error("Expected error but got none")
            }
            if !tt.expectError && err != nil {
                t.Errorf("Unexpected error: %v", err)
            }
        })
    }
}

```

--------------------------------

### HTML Form for Turnstile Integration

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Example HTML form demonstrating how to embed the Cloudflare Turnstile widget. Ensure the 'data-sitekey' attribute is set to your actual site key.

```html
<!DOCTYPE html>
<html>
<head>
    <title>Turnstile Demo</title>
    <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
</head>
<body>
    <form action="/verify" method="POST">
        <div class="cf-turnstile" data-sitekey="your-site-key"></div>
        <input type="submit" value="Submit">
    </form>
</body>
</html>

```

--------------------------------

### Get Mock RoundTripper Call Count

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

CallCount returns the number of times the mock was called.

```go
func (m *MockRoundTripper) CallCount() int
```

--------------------------------

### Get Last Request Body from Mock RoundTripper

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

LastRequestBody returns the body of the last HTTP request.

```go
func (m *MockRoundTripper) LastRequestBody() []byte
```

--------------------------------

### Get Last Request from Mock RoundTripper

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

LastRequest returns the last HTTP request made to the mock.

```go
func (m *MockRoundTripper) LastRequest() *http.Request
```

--------------------------------

### Add Test Token to Existing HTTP Request

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Use `AddTestToken` to append a test Turnstile token to an already constructed `http.Request` object. This is ideal when your test setup generates the request first and then needs to inject the token for verification.

```go
func TestHTTPHandler(t *testing.T) {
    client := turnstile.NewTestClient()

    // You already have a request from your test setup
    form := url.Values{}
    form.Set("username", "testuser")
    req := httptest.NewRequest(http.MethodPost, "/submit", strings.NewReader(form.Encode()))
    req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

    // Add the test token to the existing request
    err := turnstile.AddTestToken(req)
    if err != nil {
        t.Fatalf("Failed to add test token: %v", err)
    }

    // Verify the request
    response, err := client.VerifyRequest(context.Background(), req)
    if err != nil {
        t.Fatalf("Expected successful verification: %v", err)
    }

    // Test your handler logic...
}

```

--------------------------------

### AddTestToken

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Adds the Turnstile test token to an existing HTTP request. It automatically handles both GET and POST requests, adding the token to form data for POST requests.

```APIDOC
## func AddTestToken(req *http.Request) error

### Description
Adds the Turnstile test token to an existing HTTP request. This is useful when you already have a request object and just want to add the token. The function automatically handles both GET and POST requests. For POST requests with form data, it adds the token to the form. The request's form must be parseable (ParseForm must succeed).

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
// Example with httptest:
req := httptest.NewRequest(http.MethodPost, "/submit", strings.NewReader("username=test"))
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
turnstile.AddTestToken(req)

// Now req contains both username=test and cf-turnstile-response=XXXX.DUMMY.TOKEN.XXXX

// Example with existing form data:
form := url.Values{}
form.Set("username", "testuser")
req := httptest.NewRequest(http.MethodPost, "/", strings.NewReader(form.Encode()))
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
turnstile.AddTestToken(req)

// Now req includes the test token in addition to existing form data
```

### Response
#### Success Response (200)
None (function returns error)

#### Response Example
None
```

--------------------------------

### Add Test Token to HTTP Request

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Adds the Turnstile test token to an HTTP request, automatically handling both GET and POST requests. Ensure the request's form is parseable for POST requests.

```go
func AddTestToken(req *http.Request) error
```

```go
req := httptest.NewRequest(http.MethodPost, "/submit", strings.NewReader("username=test"))
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
turnstile.AddTestToken(req)

// Now req contains both username=test and cf-turnstile-response=XXXX.DUMMY.TOKEN.XXXX
```

```go
form := url.Values{}
form.Set("username", "testuser")
req := httptest.NewRequest(http.MethodPost, "/", strings.NewReader(form.Encode()))
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
turnstile.AddTestToken(req)

// Now req includes the test token in addition to existing form data
```

--------------------------------

### Create Mock Client with Custom Response

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Use NewMockClientWithResponse for complete control over mock responses. This allows testing various scenarios by defining success, challenge timestamps, hostnames, and actions.

```go
func NewMockClientWithResponse(resp MockResponse, opts ...MockClientOption) (*Client, *MockRoundTripper)
```

```go
func TestCustomScenario(t *testing.T) {
	client, mock := turnstile.NewMockClientWithResponse(turnstile.MockResponse{
		Success:     true,
		ChallengeTS: time.Now().Format(time.RFC3339),
		Hostname:    "myapp.example.com",
		Action:      "login",
	})

	response, err := client.VerifyToken(context.Background(), "token")
	if err != nil {
		t.Fatalf("Unexpected error: %v", err)
	}

	if response.Action != "login" {
		t.Errorf("Expected action 'login', got %q", response.Action)
	}
}
```

```text
Success: true
Hostname: myapp.example.com
Action: login
```

--------------------------------

### Create Test Client (Always Pass)

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Creates a Turnstile client for testing that always passes verification using dummy keys. Recommended for verifying correct handler processing of successful CAPTCHAs.

```go
func NewTestClient(opts ...ClientOption) *Client
```

```go
func TestMyHandler(t *testing.T) {
	client := turnstile.NewTestClient()
	response, err := client.VerifyToken(context.Background(), turnstile.TestToken)
	if err != nil {
		t.Fatalf("Expected successful verification: %v", err)
	}
	// Test your handler logic with a valid token
}
```

--------------------------------

### Basic Usage of Go Turnstile Client

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Demonstrates how to create a Turnstile client and verify a token from an HTTP request. Handles potential verification errors, including specific timeout or duplicate errors.

```go
client, err := turnstile.New("your-site-key", "your-secret-key")
if err != nil {
	// Handle client creation error
}

// Verify token from HTTP request
response, err := client.VerifyRequest(context.Background(), httpRequest)
if err != nil {
	// Handle verification error (specific error types available)
	var timeoutErr turnstile.ErrTimeoutOrDuplicate
	if errors.As(err, &timeoutErr) {
		// Handle timeout/duplicate specifically
	}
	return
}
// Token is valid, access response fields: response.ChallengeTS, response.Hostname, response.Action, etc.

```

--------------------------------

### Create Test Client (Always Fail)

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Creates a Turnstile client for testing that always fails verification using dummy keys. Use this to test error handling when CAPTCHA verification fails.

```go
func NewTestClientAlwaysFail(opts ...ClientOption) *Client
```

```go
func TestMyHandlerFailure(t *testing.T) {
	client := turnstile.NewTestClientAlwaysFail()
	_, err := client.VerifyToken(context.Background(), turnstile.TestToken)
	if err == nil {
		t.Fatal("Expected verification to fail")
	}
	// Test your error handling logic
}
```

--------------------------------

### New Client Initialization

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Creates a new Turnstile client with the provided site and secret keys. The client is safe for concurrent use.

```APIDOC
## func New

### Description
Creates a new Turnstile client with the provided site key and secret key. The client is safe for concurrent use by multiple goroutines.

### Parameters
- **siteKey** (string) - The public site key from your Cloudflare Turnstile configuration
- **secretKey** (string) - The secret key from your Cloudflare Turnstile configuration
- **opts** (...ClientOption) - Optional configuration functions to customize client behavior

### Returns
- (*Client) - A pointer to the initialized Client.
- (error) - An error if either key is empty or contains only whitespace.
```

--------------------------------

### Testing Request Verification with go-turnstile

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Demonstrates how to test handlers using `VerifyRequest()` with the go-turnstile test client. It includes setting up a test client and a mock request.

```go
import (
    "testing"
    "context"
    "github.com/tordrt/go-turnstile"
)

func TestMyHandler(t *testing.T) {
    // Create a test client that always passes verification
    client := turnstile.NewTestClient()

    // Create a test request with the Turnstile token already included
    req := turnstile.NewTestRequest(map[string]string{
        "username": "testuser",
    })

    // Verify the request
    response, err := client.VerifyRequest(context.Background(), req)
    if err != nil {
        t.Fatalf("Expected successful verification: %v", err)
    }

    // Test your handler logic with a valid token
    if !response.Success {
        t.Error("Expected successful response")
    }
}

```

--------------------------------

### Advanced Configuration for Go Turnstile Client

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Illustrates how to configure the Turnstile client with advanced options such as maximum retries, retry delay, and a custom HTTP client with a specific timeout.

```go
client, err := turnstile.New(
	"your-site-key",
	"your-secret-key",
	turnstile.WithMaxRetries(3),
	turnstile.WithRetryDelay(200*time.Millisecond),
	turnstile.WithHTTPClient(&http.Client{Timeout: 5*time.Second}),
)

```

--------------------------------

### Create New Turnstile Client

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Initializes a new Turnstile client with site and secret keys. The client is safe for concurrent use. Returns an error if keys are empty.

```go
func New(siteKey, secretKey string, opts ...ClientOption) (*Client, error)
```

--------------------------------

### Client Initialization

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Provides functions to create a new Turnstile client, either with actual keys or for testing purposes.

```APIDOC
## Client Initialization

### New

Creates a new Turnstile client with the provided site key and secret key.

### `New(siteKey string, secretKey string, opts ...ClientOption) (*Client, error)`

### `NewTestClient(opts ...ClientOption) *Client`

Creates a new test client, useful for mocking and testing scenarios.

### `NewTestClientAlwaysFail(opts ...ClientOption) *Client`

Creates a test client configured to always fail verification.

### `NewTestClientTokenSpent(opts ...ClientOption) *Client`

Creates a test client configured to simulate a 'token already spent' error.
```

--------------------------------

### Create Test Client (Token Spent)

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Creates a Turnstile client for testing that simulates a replay attack by returning a timeout-or-duplicate error. Use this to test handling of duplicate token submissions.

```go
func NewTestClientTokenSpent(opts ...ClientOption) *Client
```

```go
func TestMyHandlerDuplicateToken(t *testing.T) {
	client := turnstile.NewTestClientTokenSpent()
	_, err := client.VerifyToken(context.Background(), turnstile.TestToken)
	var timeoutErr turnstile.ErrTimeoutOrDuplicate
	if !errors.As(err, &timeoutErr) {
		t.Fatal("Expected timeout-or-duplicate error")
	}
	// Test your duplicate submission handling
}
```

--------------------------------

### Testing Direct Token Verification with go-turnstile

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Shows how to test direct token verification using the `VerifyToken` method with the go-turnstile test client and a predefined test token.

```go
func TestTokenVerification(t *testing.T) {
    client := turnstile.NewTestClient()
    response, err := client.VerifyToken(context.Background(), turnstile.TestToken)
    if err != nil {
        t.Fatalf("Expected successful verification: %v", err)
    }
}

```

--------------------------------

### Create Mock Turnstile Client

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Creates a mock Turnstile client that bypasses actual network requests, returning configurable mock responses. Useful for unit testing.

```go
func NewMockClient(opts ...MockClientOption) (*Client, *MockRoundTripper)
```

```go
func TestMyHandler(t *testing.T) {
	client, mock := turnstile.NewMockClient()

	response, err := client.VerifyToken(context.Background(), "any-token")
	if err != nil {
		t.Fatalf("Expected successful verification: %v", err)
	}

	// Verify the mock was called
	if mock.CallCount() != 1 {
		t.Errorf("Expected 1 call, got %d", mock.CallCount())
	}
}
```

```text
Mock verification successful: true
Mock was called 1 time(s)
```

--------------------------------

### Testing Success Case with NewTestClient()

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Utilizes `NewTestClient()` to create a mock client that always passes verification. This is useful for testing the 'happy path' of your integration.

```go
func TestHandlerSuccess(t *testing.T) {
    client := turnstile.NewTestClient()
    response, err := client.VerifyToken(context.Background(), turnstile.TestToken)
    // err will be nil, response.Success will be true
}

```

--------------------------------

### NewMockClientWithResponse

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Creates a mock client with a fully customizable response, offering complete control over mock return values for various scenarios.

```APIDOC
## NewMockClientWithResponse

### Description
Creates a mock client with a fully custom response. This gives you complete control over what the mock returns.

### Signature
```go
func NewMockClientWithResponse(resp MockResponse, opts ...MockClientOption) (*Client, *MockRoundTripper)
```

### Example
```go
func TestCustomScenario(t *testing.T) {
	client, mock := turnstile.NewMockClientWithResponse(turnstile.MockResponse{
		Success:     true,
		ChallengeTS: time.Now().Format(time.RFC3339),
		Hostname:    "myapp.example.com",
		Action:      "login",
	})

	response, err := client.VerifyToken(context.Background(), "token")
	if err != nil {
		t.Fatalf("Unexpected error: %v", err)
	}

	if response.Action != "login" {
		t.Errorf("Expected action 'login', got %q", response.Action)
	}
}
```
```

--------------------------------

### Configure Go Turnstile Client Options

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

ClientOption is a function type for configuring a Client during creation. Options allow customization of HTTP client, endpoints, and retry behavior.

```go
type ClientOption func(*Client)
```

--------------------------------

### Mock Client Utilities

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Functions and types for creating mock clients to facilitate testing.

```APIDOC
## Mock Client Utilities

### `NewMockClient(opts ...MockClientOption) (*Client, *MockRoundTripper)`

Creates a mock client with a configurable mock round tripper.

### `NewMockClientAlwaysFail(opts ...ClientOption) (*Client, *MockRoundTripper)`

Creates a mock client that is configured to always fail.

### `NewMockClientTokenSpent(opts ...ClientOption) (*Client, *MockRoundTripper)`

Creates a mock client that simulates a 'token already spent' error.

### `NewMockClientWithHTTPError(statusCode int, status string) (*Client, *MockRoundTripperWithError)`

Creates a mock client that returns a specific HTTP error.

### `NewMockClientWithResponse(resp MockResponse, opts ...MockClientOption) (*Client, *MockRoundTripper)`

Creates a mock client that returns a predefined mock response.

### `MockRoundTripper`

Represents a mock HTTP round tripper for testing.

#### Methods:
- `CallCount() int`: Returns the number of times `RoundTrip` has been called.
- `LastRequest() *http.Request`: Returns the last HTTP request made.
- `LastRequestBody() []byte`: Returns the body of the last HTTP request.
- `Reset()`: Resets the mock round tripper's state.
- `RoundTrip(req *http.Request) (*http.Response, error)`: Simulates an HTTP round trip.
- `SetResponse(resp MockResponse)`: Sets the response to be returned by `RoundTrip`.

### `MockRoundTripperWithError`

Represents a mock HTTP round tripper that can return errors.

#### Methods:
- `RoundTrip(req *http.Request) (*http.Response, error)`: Simulates an HTTP round trip, potentially returning an error.
```

--------------------------------

### Define Package-Level Errors

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Defines common errors for client configuration and validation, such as invalid site keys or empty tokens.

```go
var (
	ErrInvalidSiteKey   = errors.New("site key cannot be empty")
	ErrInvalidSecretKey = errors.New("secret key cannot be empty")
	ErrEmptyToken       = &VerificationError{Message: "turnstile response token cannot be empty"}
)
```

--------------------------------

### Direct Token Verification with Go Turnstile

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Shows how to directly verify a Turnstile token using the client, typically obtained from a form submission. Assumes successful client creation and handles verification errors.

```go
client, _ := turnstile.New("your-site-key", "your-secret-key")
response, err := client.VerifyToken(context.Background(), tokenFromForm, "192.168.1.1")
if err != nil {
	// Handle verification error
	return
}
// Token is valid, proceed with business logic

```

--------------------------------

### Test Utilities

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Helper functions for creating test requests and adding test tokens.

```APIDOC
## Test Utilities

### `NewTestRequest(formData ...map[string]string) *http.Request`

Creates a new HTTP request suitable for testing, optionally with form data.

### `AddTestToken(req *http.Request) error`

Adds a test token to an HTTP request, useful for simulating verified requests in tests.
```

--------------------------------

### Constants

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Provides constants for dummy site keys, secret keys, tokens, and default client configurations.

```APIDOC
## Constants

### Testing Constants

- `TestSiteKeyAlwaysPass`
- `TestSiteKeyAlwaysBlock`
- `TestSiteKeyAlwaysPassInvisible`
- `TestSiteKeyAlwaysBlockInvisible`
- `TestSiteKeyForceChallenge`
- `TestSecretKeyAlwaysPass`
- `TestSecretKeyAlwaysFail`
- `TestSecretKeyTokenSpent`
- `TestToken`

These constants provide dummy values for site keys, secret keys, and tokens, enabling comprehensive testing of Turnstile integrations without requiring actual credentials.

### Default Configuration Constants

- `DefaultVerifyEndpoint`: The official Cloudflare Turnstile verification endpoint.
- `DefaultTimeout`: The default HTTP client timeout for verification requests.
- `DefaultMaxRetries`: The default maximum number of retry attempts for network failures.
- `DefaultRetryDelay`: The default initial delay between retry attempts (exponential backoff).
```

--------------------------------

### Create Mock Client That Always Fails

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Creates a mock Turnstile client that consistently returns a verification failure. Ideal for testing error handling paths in your application.

```go
func NewMockClientAlwaysFail(opts ...MockClientOption) (*Client, *MockRoundTripper)
```

```go
func TestMyHandlerFailure(t *testing.T) {
	client, _ := turnstile.NewMockClientAlwaysFail()

	_, err := client.VerifyToken(context.Background(), "any-token")
	if err == nil {
		t.Fatal("Expected verification to fail")
	}

	var invalidErr turnstile.ErrInvalidInputResponse
	if !errors.As(err, &invalidErr) {
		t.Fatalf("Expected ErrInvalidInputResponse, got %T", err)
	}
}
```

```text
Mock verification failed as expected
Error type: ErrInvalidInputResponse
```

--------------------------------

### Unit Test with Mock Client (No Network Calls)

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Utilizes `turnstile.NewMockClient` for true unit testing without any network interaction. This mock client allows you to fully control responses and verify that your handler interacts correctly with the Turnstile client interface.

```go
func TestMyHandler(t *testing.T) {
    // Create a mock client - NO HTTP requests are made
    client, mock := turnstile.NewMockClient()

    // Any token works - responses are fully mocked
    response, err := client.VerifyToken(context.Background(), "any-token")
    if err != nil {
        t.Fatalf("Unexpected error: %v", err)
    }

    // Verify the mock was called
    if mock.CallCount() != 1 {
        t.Errorf("Expected 1 call, got %d", mock.CallCount())
    }

    // Inspect the request that was made
    body := mock.LastRequestBody()
    // ... assertions on the request
}

```

--------------------------------

### Mock Client - Unit Testing Without Network Calls

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Provides a mock client for true unit testing with zero network calls. Responses are fully mocked, and you can inspect the requests made.

```APIDOC
## Mock Client

### Description
Use the mock client for unit testing without making any actual HTTP requests. This client uses Cloudflare's test keys but simulates responses entirely in memory.

### Usage
```go
// Create a mock client - NO HTTP requests are made
client, mock := turnstile.NewMockClient()

// Any token works - responses are fully mocked
response, err := client.VerifyToken(context.Background(), "any-token")
if err != nil {
    // Handle error
}

// Verify the mock was called
if mock.CallCount() != 1 {
    // Handle error: Expected 1 call, got X
}

// Inspect the request that was made
body := mock.LastRequestBody()
// ... assertions on the request body
```
```

--------------------------------

### NewMockClientTokenSpent

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Creates a mock client that simulates a 'token already spent' error, useful for testing replay attack scenarios.

```APIDOC
## NewMockClientTokenSpent

### Description
Creates a mock client that returns a "token already spent" error. This simulates a replay attack scenario where a token has already been used.

### Signature
```go
func NewMockClientTokenSpent(opts ...MockClientOption) (*Client, *MockRoundTripper)
```

### Example
```go
func TestMyHandlerDuplicateToken(t *testing.T) {
	client, _ := turnstile.NewMockClientTokenSpent()

	_, err := client.VerifyToken(context.Background(), "any-token")
	var timeoutErr turnstile.ErrTimeoutOrDuplicate
	if !errors.As(err, &timeoutErr) {
		t.Fatal("Expected timeout-or-duplicate error")
	}
}
```
```

--------------------------------

### ClientOption

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

ClientOption is a function type used to configure a Client during creation. Options allow customization of HTTP client, endpoints, retry behavior, and other settings.

```APIDOC
## ClientOption

### Description
ClientOption is a function type used to configure a Client during creation. Options allow customization of HTTP client, endpoints, retry behavior, and other settings.

### Type Definition
```go
type ClientOption func(*Client)
```
```

--------------------------------

### WithRetryDelay

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Configures the initial delay between retry attempts. The delay is doubled after each retry (exponential backoff). Default is 100ms.

```APIDOC
## WithRetryDelay

### Description
Configures the initial delay between retry attempts. The delay is doubled after each retry (exponential backoff). Default is 100ms.

### Method Signature
```go
func WithRetryDelay(delay time.Duration) ClientOption
```
```

--------------------------------

### Client Options

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Options to customize the behavior of the Turnstile client.

```APIDOC
## Client Options

### `ClientOption`

Type for client configuration options.

### `WithHTTPClient(client *http.Client) ClientOption`

Allows specifying a custom HTTP client.

### `WithMaxRetries(maxRetries int) ClientOption`

Sets the maximum number of retry attempts for network requests.

### `WithRetryDelay(delay time.Duration) ClientOption`

Configures the initial delay between retry attempts.

### `WithVerifyEndpoint(endpoint string) ClientOption`

Specifies a custom endpoint for Turnstile verification.
```

--------------------------------

### Implement RoundTrip for MockRoundTripper

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

RoundTrip implements http.RoundTripper and returns a mock response.

```go
func (m *MockRoundTripper) RoundTrip(req *http.Request) (*http.Response, error)
```

--------------------------------

### Client Verification Methods

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Methods for verifying user challenges using either an HTTP request or a token.

```APIDOC
## Client Verification Methods

### `VerifyRequest(ctx context.Context, req *http.Request) (*Response, error)`

Verifies a Turnstile challenge presented within an HTTP request.

### `VerifyToken(ctx context.Context, token string, remoteIP ...string) (*Response, error)`

Verifies a Turnstile token directly. Optionally, a remote IP address can be provided.
```

--------------------------------

### Configure Mock Client Options in Go

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

MockClientOption is a function type used to configure a mock client. Allows setting specific mock responses.

```go
type MockClientOption func(*MockRoundTripper)
```

--------------------------------

### WithHTTPClient

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Configures the client to use a custom HTTP client. This is useful for setting custom timeouts, transport configurations, or proxy settings.

```APIDOC
## WithHTTPClient

### Description
Configures the client to use a custom HTTP client. This is useful for setting custom timeouts, transport configurations, or proxy settings.

### Method Signature
```go
func WithHTTPClient(client *http.Client) ClientOption
```
```

--------------------------------

### Testing HTTP Server Errors with Go Turnstile Mock

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Simulates an HTTP 500 Internal Server Error using a mock client. Verifies that the `VerifyToken` call returns an error when such an HTTP error is simulated.

```go
func TestServerError(t *testing.T) {
    client, _ := turnstile.NewMockClientWithHTTPError(500, "500 Internal Server Error")

    _, err := client.VerifyToken(context.Background(), "token")
    if err == nil {
        t.Fatal("Expected error for 500 response")
    }
}


```

--------------------------------

### Custom Mock Response in Go Turnstile Tests

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Configures a mock client to return a specific successful response with custom challenge timestamp, hostname, and action. Verifies that the response action matches the expected value.

```go
func TestCustomScenario(t *testing.T) {
    client, _ := turnstile.NewMockClientWithResponse(turnstile.MockResponse{
        Success:     true,
        ChallengeTS: "2024-01-01T00:00:00Z",
        Hostname:    "myapp.example.com",
        Action:      "login",
    })

    response, _ := client.VerifyToken(context.Background(), "token")
    if response.Action != "login" {
        t.Errorf("Expected action 'login', got %q", response.Action)
    }
}


```

--------------------------------

### Default Successful Mock Response

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Provides a default mock response for simulating a successful Turnstile verification, useful for testing.

```go
var DefaultMockResponseSuccess = MockResponse{
	Success:     true,
	ChallengeTS: "2024-01-01T00:00:00Z",
	Hostname:    "example.com",
}
```

--------------------------------

### NewTestClient

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Creates a new Turnstile client configured for testing with Cloudflare's "always pass" dummy keys. This client will accept the TestToken and always return success.

```APIDOC
## func NewTestClient

### Description
Creates a new Turnstile client configured for testing with Cloudflare's "always pass" dummy keys. This client will accept the TestToken and always return success. This is the recommended client for most testing scenarios where you want to verify that your handler correctly processes successful CAPTCHA verifications.

### Parameters
- **opts** (...ClientOption) - Optional configuration functions to customize client behavior

### Returns
- (*Client) - A pointer to the initialized test Client.
```

--------------------------------

### Create Mock Client for HTTP Errors

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Use NewMockClientWithHTTPError to simulate HTTP-level errors (e.g., 500 Internal Server Error, rate limiting). This helps test application resilience to server-side issues.

```go
func NewMockClientWithHTTPError(statusCode int, status string) (*Client, *MockRoundTripperWithError)
```

```go
func TestServerError(t *testing.T) {
	client, _ := turnstile.NewMockClientWithHTTPError(500, "500 Internal Server Error")

	_, err := client.VerifyToken(context.Background(), "token")
	if err == nil {
		t.Fatal("Expected error for 500 response")
	}

	if !strings.Contains(err.Error(), "500") {
		t.Errorf("Expected error to mention 500, got: %v", err)
	}
}
```

```text
HTTP error simulated successfully
```

--------------------------------

### Advanced Client Configuration

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Customize the Turnstile client's behavior by providing options such as maximum retries, retry delay, and a custom HTTP client with specific timeouts and transport settings.

```go
turnstileClient, err := turnstile.New(
    "your-site-key",
    "your-secret-key",
    turnstile.WithMaxRetries(3),
    turnstile.WithRetryDelay(200*time.Millisecond),
    turnstile.WithHTTPClient(&http.Client{
        Timeout: 5 * time.Second,
        Transport: &http.Transport{
            MaxIdleConns: 10,
        },
    }),
)

```

--------------------------------

### NewMockClientAlwaysFail

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Creates a mock client that always returns a verification failure. This is useful for testing error handling in your application.

```APIDOC
## func NewMockClientAlwaysFail(opts ...MockClientOption) (*Client, *MockRoundTripper)

### Description
Creates a mock client that always returns a verification failure. This is useful for testing error handling in your application.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
func TestMyHandlerFailure(t *testing.T) {
	client, _ := turnstile.NewMockClientAlwaysFail()

	_, err := client.VerifyToken(context.Background(), "any-token")
	if err == nil {
		t.Fatal("Expected verification to fail")
	}

	var invalidErr turnstile.ErrInvalidInputResponse
	if !errors.As(err, &invalidErr) {
		t.Fatalf("Expected ErrInvalidInputResponse, got %T", err)
	}
}
```

### Response
#### Success Response (200)
Returns a pointer to a `Client` and a `MockRoundTripper`.

#### Response Example
```
// Example output from the test:
// Mock verification failed as expected
// Error type: ErrInvalidInputResponse
```
```

--------------------------------

### Testing Duplicate Token with NewTestClientTokenSpent()

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Uses `NewTestClientTokenSpent()` to simulate a 'token already spent' error, allowing you to test your application's protection against replay attacks.

```go
import "errors"

func TestHandlerDuplicateToken(t *testing.T) {
    client := turnstile.NewTestClientTokenSpent()
    _, err := client.VerifyToken(context.Background(), turnstile.TestToken)

    var timeoutErr turnstile.ErrTimeoutOrDuplicate
    if !errors.As(err, &timeoutErr) {
        t.Fatal("Expected timeout-or-duplicate error")
    }
    // Test your duplicate submission handling
}

```

--------------------------------

### Verify Token from HTTP Request

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

The `VerifyRequest` method simplifies verification by automatically extracting the token from the `cf-turnstile-response` form field and determining the client's IP address from the incoming HTTP request.

```go
func handlerFunction(w http.ResponseWriter, r *http.Request) {
    response, err := turnstileClient.VerifyRequest(r.Context(), r)
    if err != nil {
        // Handle verification failure
        return
    }
    
    // Verification successful
}

```

--------------------------------

### Set Mock Response for Go Turnstile Client

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Configures the mock client to return a specific predefined response during testing.

```go
func WithMockResponse(resp MockResponse) MockClientOption
```

--------------------------------

### WithMockResponse

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Configures the mock client to return a specific response.

```APIDOC
## WithMockResponse

### Description
Configures the mock client to return a specific response.

### Method Signature
```go
func WithMockResponse(resp MockResponse) MockClientOption
```
```

--------------------------------

### Create Basic Test Request

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

A simplified version of `NewTestRequest` that creates a request containing only the Turnstile test token, without any additional form data.

```go
req := turnstile.NewTestRequest()  // Just includes the Turnstile token

```

--------------------------------

### Testing Failure Case with NewTestClientAlwaysFail()

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Employs `NewTestClientAlwaysFail()` to simulate verification failures. This helps in testing how your application handles invalid or failed Turnstile challenges.

```go
func TestHandlerFailure(t *testing.T) {
    client := turnstile.NewTestClientAlwaysFail()
    _, err := client.VerifyToken(context.Background(), turnstile.TestToken)
    // err will not be nil - test your error handling here
    if err == nil {
        t.Fatal("Expected verification to fail")
    }
}

```

--------------------------------

### NewMockClient

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Creates a new Turnstile client that never makes actual HTTP requests. Instead, it returns a configurable mock response. By default, it returns a successful verification response. Useful for unit testing.

```APIDOC
## func NewMockClient(opts ...MockClientOption) (*Client, *MockRoundTripper)

### Description
Creates a new Turnstile client that never makes actual HTTP requests. Instead, it returns a configurable mock response. By default, it returns a successful verification response. This is useful for unit testing where you want no network calls, complete control over the response, and the ability to inspect what requests were made. The returned MockRoundTripper can be used to inspect calls and change responses.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
func TestMyHandler(t *testing.T) {
	client, mock := turnstile.NewMockClient()

	response, err := client.VerifyToken(context.Background(), "any-token")
	if err != nil {
		t.Fatalf("Expected successful verification: %v", err)
	}

	// Verify the mock was called
	if mock.CallCount() != 1 {
		t.Errorf("Expected 1 call, got %d", mock.CallCount())
	}
}
```

### Response
#### Success Response (200)
Returns a pointer to a `Client` and a `MockRoundTripper`.

#### Response Example
```
// Example output from the test:
// Mock verification successful: true
// Mock was called 1 time(s)
```
```

--------------------------------

### Use Custom HTTP Client in Go Turnstile

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Configures the client to use a custom HTTP client, useful for setting custom timeouts, transport configurations, or proxy settings.

```go
func WithHTTPClient(client *http.Client) ClientOption
```

--------------------------------

### NewMockClientWithHTTPError

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Creates a mock client that returns specified HTTP-level errors, useful for testing error handling like server errors or rate limiting.

```APIDOC
## NewMockClientWithHTTPError

### Description
Creates a mock client that returns HTTP-level errors. This is useful for testing how your application handles server errors, rate limiting, etc.

### Signature
```go
func NewMockClientWithHTTPError(statusCode int, status string) (*Client, *MockRoundTripperWithError)
```

### Example
```go
func TestServerError(t *testing.T) {
	client, _ := turnstile.NewMockClientWithHTTPError(500, "500 Internal Server Error")

	_, err := client.VerifyToken(context.Background(), "token")
	if err == nil {
		t.Fatal("Expected error for 500 response")
	}

	if !strings.Contains(err.Error(), "500") {
		t.Errorf("Expected error to mention 500, got: %v", err)
	}
}
```
```

--------------------------------

### Create Mock Client for Token Spent Error

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Use NewMockClientTokenSpent to simulate a token replay attack scenario where a token has already been used. This is useful for testing error handling of duplicate tokens.

```go
func NewMockClientTokenSpent(opts ...MockClientOption) (*Client, *MockRoundTripper)
```

```go
func TestMyHandlerDuplicateToken(t *testing.T) {
	client, _ := turnstile.NewMockClientTokenSpent()

	_, err := client.VerifyToken(context.Background(), "any-token")
	var timeoutErr turnstile.ErrTimeoutOrDuplicate
	if !errors.As(err, &timeoutErr) {
		t.Fatal("Expected timeout-or-duplicate error")
	}
}
```

```text
Detected duplicate token (mocked)
```

--------------------------------

### Create Test HTTP Request with Turnstile Token

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Use `NewTestRequest` to create an HTTP request pre-populated with a test Turnstile token. This is useful for simulating requests that include both the Turnstile token and additional form data.

```go
func TestHTTPHandler(t *testing.T) {
    client := turnstile.NewTestClient()

    // Create a test request with the Turnstile token and additional form data
    req := turnstile.NewTestRequest(map[string]string{
        "username": "testuser",
        "email":    "test@example.com",
    })

    // Verify using VerifyRequest - the test token is already in the request
    response, err := client.VerifyRequest(context.Background(), req)
    if err != nil {
        t.Fatalf("Expected successful verification: %v", err)
    }

    // Now test your handler logic
    // ...
}

```

--------------------------------

### NewTestClientAlwaysFail

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Creates a new Turnstile client configured for testing with Cloudflare's "always fail" dummy keys. This client will reject all tokens including TestToken.

```APIDOC
## func NewTestClientAlwaysFail

### Description
Creates a new Turnstile client configured for testing with Cloudflare's "always fail" dummy keys. This client will reject all tokens including TestToken. Use this client to test error handling in your application when CAPTCHA verification fails.

### Parameters
- **opts** (...ClientOption) - Optional configuration functions to customize client behavior

### Returns
- (*Client) - A pointer to the initialized test Client.
```

--------------------------------

### Verify Token Directly

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Use this method to verify a Turnstile token directly, providing the token string and the client's IP address. Ensure you have a valid client token and IP address.

```go
// Verify a token directly
response, err := turnstileClient.VerifyToken(context.TODO(), clientToken, clientIP)
if err != nil {
    // Handle verification error
    return
}
// Verification successful

```

--------------------------------

### Dynamic Mock Behavior Change in Go Turnstile Tests

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Tests the ability to change the mock client's behavior dynamically. Initially, a call succeeds, then the mock is updated to simulate a failure (timeout or duplicate), and a subsequent call is expected to fail.

```go
func TestDynamicBehavior(t *testing.T) {
    client, mock := turnstile.NewMockClient()

    // First call succeeds
    _, err := client.VerifyToken(context.Background(), "token")
    if err != nil {
        t.Fatal("Expected success")
    }

    // Change to failure mode
    mock.SetResponse(turnstile.MockResponse{
        Success:    false,
        ErrorCodes: []string{"timeout-or-duplicate"},
    })

    // Second call fails
    _, err = client.VerifyToken(context.Background(), "token")
    if err == nil {
        t.Fatal("Expected failure")
    }
}


```

--------------------------------

### MockClientOption

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

MockClientOption is a function type used to configure a mock client.

```APIDOC
## MockClientOption

### Description
MockClientOption is a function type used to configure a mock client.

### Type Definition
```go
type MockClientOption func(*MockRoundTripper)
```
```

--------------------------------

### Implement RoundTrip for MockRoundTripperWithError

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

RoundTrip implements http.RoundTripper and returns an HTTP error response.

```go
func (m *MockRoundTripperWithError) RoundTrip(req *http.Request) (*http.Response, error)
```

--------------------------------

### WithVerifyEndpoint

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Configures the client to use a custom verification endpoint. This is typically only needed for testing or enterprise deployments.

```APIDOC
## WithVerifyEndpoint

### Description
Configures the client to use a custom verification endpoint. This is typically only needed for testing or enterprise deployments.

### Method Signature
```go
func WithVerifyEndpoint(endpoint string) ClientOption
```
```

--------------------------------

### Define MockResponse Structure

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

MockResponse represents a configurable response for the mock client. Use this to customize what the mock client returns during testing.

```go
type MockResponse struct {
	// Success indicates whether the verification should succeed
	Success bool
	// ChallengeTS is the timestamp of when the challenge was completed (ISO 8601 format)
	ChallengeTS string
	// Hostname is the hostname of the site where the challenge was completed
	Hostname string
	// ErrorCodes contains specific error codes when Success is false
	ErrorCodes []string
	// Action is the action name for this widget
	Action string
	// CData is the customer data passed to the widget
	CData string
}
```

--------------------------------

### NewTestClientTokenSpent

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Creates a new Turnstile client configured for testing with Cloudflare's "token already spent" dummy key. This client will return a timeout-or-duplicate error, simulating a replay attack scenario.

```APIDOC
## func NewTestClientTokenSpent

### Description
Creates a new Turnstile client configured for testing with Cloudflare's "token already spent" dummy key. This client will return a timeout-or-duplicate error, simulating a replay attack scenario. Use this client to test handling of duplicate token submissions in your application.

### Parameters
- **opts** (...ClientOption) - Optional configuration functions to customize client behavior

### Returns
- (*Client) - A pointer to the initialized test Client.
```

--------------------------------

### NewTestRequest() - Create a New Request

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Creates a complete HTTP request with a test Turnstile token already included. This can optionally include additional form data.

```APIDOC
## NewTestRequest()

### Description
Creates a complete HTTP request with the test token already included. This function can also accept additional form data.

### Usage
```go
// With additional form data
req := turnstile.NewTestRequest(map[string]string{
    "username": "testuser",
    "email":    "test@example.com",
})

// Without additional form data
req := turnstile.NewTestRequest()
```
```

--------------------------------

### Verify Turnstile Token with Go

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Directly verifies a Turnstile token. Supports optional remote IP validation and automatically handles idempotency keys and retries for network errors.

```go
func (c *Client) VerifyToken(ctx context.Context, token string, remoteIP ...string) (*Response, error)
```

--------------------------------

### Configure Retry Delay in Go Turnstile

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Configures the initial delay between retry attempts. The delay doubles after each retry using exponential backoff. Default is 100ms.

```go
func WithRetryDelay(delay time.Duration) ClientOption
```

--------------------------------

### Implement Error Method for VerificationError

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Implements the Error method for the VerificationError type, allowing it to be used as a standard Go error.

```go
func (e *VerificationError) Error() string
```

--------------------------------

### Default Failed Mock Response

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

Provides a default mock response for simulating a failed Turnstile verification, often used in testing.

```go
var DefaultMockResponseFail = MockResponse{
	Success:    false,
	ErrorCodes: []string{"invalid-input-response"},
}
```

--------------------------------

### Define MockRoundTripper Structure

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

MockRoundTripper implements http.RoundTripper and intercepts all HTTP requests, returning configurable mock responses without making actual network calls. This is useful for unit testing where you want complete control over responses and don't want any external dependencies.

```go
type MockRoundTripper struct {
	// Response is the mock response to return
	Response MockResponse
	// contains filtered or unexported fields
}
```

--------------------------------

### Default Configuration Values

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

These constants define the default values used by the go-turnstile client for verification endpoint, timeouts, maximum retries, and retry delay.

```go
const (
    DefaultVerifyEndpoint = "https://challenges.cloudflare.com/turnstile/v0/siteverify"
    DefaultTimeout        = 3 * time.Second
    DefaultMaxRetries     = 2
    DefaultRetryDelay     = 100 * time.Millisecond
)

```

--------------------------------

### Set Response for MockRoundTripper

Source: https://pkg.go.dev/github.com/tordrt/go-turnstile

SetResponse updates the mock response. This is safe for concurrent use.

```go
func (m *MockRoundTripper) SetResponse(resp MockResponse)
```
Tokens:
Raw