proxygun

README

ProxyGun

Go library providing an HTTP RoundTripper with automatic proxy server pool management.

Features

• Automatic proxy downloading from known sources
• Proxy validation through google.com requests
• Proxy rotation for each request
• Proxy statistics and automatic Bad Pool placement
• HTTP and SOCKS5 proxy support
• Automatic pool replenishment when needed

Usage

Option 1: Using ProxyClient (Recommended)

package main

import (
    "fmt"
    "log"
    "time"

    "github.com/aredoff/proxygun"
)

func main() {
    config := proxygun.DefaultConfig()
    config.PoolSize = 20
    config.MaxRetries = 5

    client := proxygun.NewProxyClient(config)
    defer client.Close()

    // Wait for proxy loading
    time.Sleep(5 * time.Second)

    resp, err := client.Get("https://httpbin.org/ip")
    if err != nil {
        log.Printf("Error: %v", err)
        return
    }
    defer resp.Body.Close()

    fmt.Printf("Status: %s\n", resp.Status)
    fmt.Printf("Stats: %+v\n", client.Stats())
}

Option 2: Using ProxyRoundTripper with Custom Client

package main

import (
    "net/http"
    "time"

    "github.com/aredoff/proxygun"
)

func main() {
    config := proxygun.DefaultConfig()
    
    // Create ProxyRoundTripper
    rt := proxygun.NewProxyRoundTripper(config)
    defer rt.Close()

    // Use with custom http.Client
    client := &http.Client{
        Transport: rt,
        Timeout:   45 * time.Second,
    }

    resp, err := client.Get("https://httpbin.org/ip")
    // Handle response...
}

Configuration

type Config struct {
    PoolSize          int           // Proxy pool size (default 50)
    MaxRetries        int           // Maximum retry attempts (default 3)
    RefreshInterval   time.Duration // Proxy refresh interval (default 10 seconds)
    ValidationWorkers int           // Number of validation workers (default 30, max 50)
    BadProxyMaxAge    time.Duration // Bad proxy retention time (default 24 hours)
}

Architecture

The library consists of the following components:

• client.go - main HTTP RoundTripper with proxy rotation
• internal/proxy/ - structures for proxy representation and statistics
• internal/pool/ - proxy pool management (main, free, bad)
• internal/parser/ - parsers for proxy websites
• internal/validator/ - proxy validator through test requests

API

ProxyRoundTripper (Core)

• NewProxyRoundTripper(config *Config) *ProxyRoundTripper - Creates a new RoundTripper
• RoundTrip(req *http.Request) (*http.Response, error) - Implements http.RoundTripper interface
• Stats() map[string]interface{} - Returns proxy pool statistics
• Close() error - Stops background workers

ProxyClient (Convenience Wrapper)

• NewProxyClient(config *Config) *ProxyClient - Creates a wrapped http.Client
• All standard http.Client methods (Get, Post, Do, etc.)
• Stats() map[string]interface{} - Returns proxy pool statistics
• Close() error - Stops background workers

Legacy Compatibility

• NewClient(config *Config) *http.Client - Returns standard http.Client with ProxyRoundTripper

Proxy Sources

• https://www.sslproxies.org
• https://www.us-proxy.org
• https://free-proxy-list.net/uk-proxy.html
• https://free-proxy-list.net

License

MIT

Documentation

Index

• func NewClient(config *Config) *http.Client
• type Config
  • func DefaultConfig() *Config
• type ProxyClient
  • func NewProxyClient(config *Config) *ProxyClient
  • func (pc *ProxyClient) Close() error
  • func (pc *ProxyClient) Stats() map[string]interface{}
• type ProxyRoundTripper
  • func NewProxyRoundTripper(config *Config) *ProxyRoundTripper
  • func (rt *ProxyRoundTripper) Close() error
  • func (rt *ProxyRoundTripper) RoundTrip(req *http.Request) (*http.Response, error)
  • func (rt *ProxyRoundTripper) Stats() map[string]interface{}

Functions

func NewClient

func NewClient(config *Config) *http.Client

NewClient creates an http.Client with ProxyRoundTripper

Types

type Config

type Config struct {
	PoolSize          int
	MaxRetries        int
	RefreshInterval   time.Duration
	ValidationWorkers int
	BadProxyMaxAge    time.Duration
}

func DefaultConfig

func DefaultConfig() *Config

type ProxyClient

type ProxyClient struct {
	*http.Client
	// contains filtered or unexported fields
}

ProxyClient wraps http.Client with ProxyRoundTripper for convenience

func NewProxyClient

func NewProxyClient(config *Config) *ProxyClient

NewProxyClient creates a ProxyClient with stats and close methods

func (*ProxyClient) Close

func (pc *ProxyClient) Close() error

Close stops background workers and cleans up resources

func (*ProxyClient) Stats

func (pc *ProxyClient) Stats() map[string]interface{}

Stats returns current proxy pool statistics

type ProxyRoundTripper

type ProxyRoundTripper struct {
	// contains filtered or unexported fields
}

func NewProxyRoundTripper

func NewProxyRoundTripper(config *Config) *ProxyRoundTripper

func (*ProxyRoundTripper) Close

func (rt *ProxyRoundTripper) Close() error

Close stops background workers and cleans up resources

func (*ProxyRoundTripper) RoundTrip

func (rt *ProxyRoundTripper) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements the http.RoundTripper interface

func (*ProxyRoundTripper) Stats

func (rt *ProxyRoundTripper) Stats() map[string]interface{}

Stats returns current proxy pool statistics