proxykit

README

proxykit-go

A lightweight Go toolkit for working with HTTP/SOCKS proxies. It provides three packages that work independently or together:

Package	Purpose
proxykit	Core Proxy model with validation, getters, setters, and URL export
proxyparser	Parse custom proxy-format strings into Proxy structs
proxypool	Iterate over large proxy files without loading them into memory

Requirements

• Go 1.26 or later

Install

go get -u github.com/colduction/proxykit-go

---

Proxy Model

The proxykit.Proxy struct holds a scheme, a host:port pair, and optional credentials.

Supported Schemes

Constant	Value
proxykit.HTTP	"http"
proxykit.HTTPS	"https"
proxykit.SOCKS5	"socks5"
proxykit.SOCKS5H	"socks5h"

Basic Usage

package main

import (
    "fmt"
    "github.com/colduction/proxykit-go"
)

func main() {
    p := &proxykit.Proxy{
        Scheme:   proxykit.HTTP,
        Host:     "example.com:8080",
        Username: "user",
        Password: "pass",
    }

    if p.IsValid() {
        fmt.Println(p.ExportURL().String())
        // Output: http://user:pass@example.com:8080
    }
}

Proxy Methods

Method	Description
IsValid() bool	Returns true if scheme, host, and credentials are all valid
IsZero() bool	Returns true if the struct is its zero value
IsCredentialFilled() bool	Returns true if a username has been set
ExportURL() *url.URL	Returns the proxy as a *url.URL
Reset()	Clears all fields back to their zero values
GetScheme() / SetScheme()	Read or write the scheme
GetHost() / SetHost()	Read or write the host
GetUsername() / SetUsername()	Read or write the username (max 255 bytes)
GetPassword() / SetPassword()	Read or write the password (max 255 bytes)

Standalone Validation Helpers

These package-level functions can be used without a Proxy instance:

proxykit.IsValidScheme("socks5")               // true
proxykit.IsValidHostnamePort("example.com:8080") // true
proxykit.IsValidCredentials("user", "pass")     // true

Function	Description
IsValidScheme(s ProxyScheme) bool	Checks that the scheme is one of the four supported values
IsValidHostnamePort(s string) bool	Validates host:port — port must be 1–65535, host must be RFC 1123
IsValidCredentials(username, password string) bool	A non-empty password requires a username; both must be ≤255 printable ASCII bytes

---

Proxy Parser

proxyparser.New compiles a format string into a reusable, goroutine-safe parser.

Format Verbs

Verb	Captures
%t	Scheme (e.g. http, socks5)
%h	Hostname
%d	Port
%u	Username
%p	Password
%%	Literal % character

Any characters between verbs are treated as literal delimiters.

Strict vs Lenient Mode

Mode	Behavior
strict = true	Input must match the format exactly; any mismatch or trailing data returns an error
strict = false	Missing credentials (%u, %p) and trailing characters are tolerated as long as the scheme and host are parsed successfully

Usage

package main

import (
    "fmt"
    "log"
    "github.com/colduction/proxykit-go/proxyparser"
)

func main() {
    // Standard format: scheme://host:port@username:password
    parser, err := proxyparser.New("%t://%h:%d@%u:%p", true)
    if err != nil {
        log.Fatal(err)
    }

    proxy, err := parser.Parse("http://example.com:8080@user:pass")
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(proxy.ExportURL().String())
    // Output: http://user:pass@example.com:8080
}

Custom delimiters work too:

// Format: (scheme)host:port:username:password
parser, err := proxyparser.New("(%t)%h:%d:%u:%p", false)
proxy, err := parser.Parse("(http)res-us.example.net:9999:admin:pass")

Parser Errors

Error Type	Meaning
ErrInvalidFormatVerb	Unknown verb character after %
ErrInvalidFormatEndStr	Format string ends with a bare %
ErrMismatchDelim	A literal delimiter in the format did not match at the given position
ErrSubseqDelimNotFound	A following delimiter was expected but not found
ErrUnexpectedTrail	Trailing characters in strict mode
ErrInvalidProxyFormat	The parsed result is not a valid proxy
ErrHostNotParsed	Host could not be extracted
ErrSchemeNotParsed	Scheme could not be extracted

---

Proxy Pool

proxypool.New opens a proxy file and returns a ProxyPool that streams proxies without loading the whole file into RAM. It is safe for concurrent use from multiple goroutines.

Modes

Constant	Behavior
proxypool.ModeSequential	Returns proxies in file order; no sidecar index is built
proxypool.ModeShuffled	Returns proxies in a random permuted order; builds a <file>.idx sidecar for O(1) seeks

Usage

package main

import (
    "fmt"
    "log"
    "github.com/colduction/proxykit-go/proxypool"
)

func main() {
    // ModeShuffled — random order, cycle forever
    pool, err := proxypool.New("proxies.txt", proxypool.ModeShuffled, true)
    if err != nil {
        log.Fatal(err)
    }
    defer pool.Close()

    for proxy, ok := pool.Next(); ok; proxy, ok = pool.Next() {
        fmt.Println(proxy)
    }
}

Pool Options

Parameter	Type	Description
path	string	Path to the newline-delimited proxy file
mode	proxypool.Mode	ModeSequential or ModeShuffled
reuse	bool	If true, iteration restarts from the beginning after the last proxy is returned

Sidecar Index (.idx)

When using ModeShuffled, a <path>.idx binary file is created next to the proxy file on the first run. Subsequent runs reuse it, making startup instant for large files. The index stores 8-byte offsets for every line, enabling O(1) random access.

ProxyPool Interface

type ProxyPool interface {
    Next() (string, bool)
    Close() error
}

• Next() returns the next proxy string. The boolean is false when the pool is exhausted (and reuse is false).
• Close() releases the open file handles and sidecar index.

---

Full Example

package main

import (
    "fmt"
    "log"

    "github.com/colduction/proxykit-go"
    "github.com/colduction/proxykit-go/proxyparser"
    "github.com/colduction/proxykit-go/proxypool"
)

func main() {
    // 1. Build a parser for a custom proxy format
    parser, err := proxyparser.New("%t://%h:%d@%u:%p", false)
    if err != nil {
        log.Fatal(err)
    }

    // 2. Parse a single proxy string
    proxy, err := parser.Parse("http://proxy.example.com:8080@alice:secret")
    if err != nil {
        log.Fatal(err)
    }
    if proxy.IsValid() {
        fmt.Println(proxy.ExportURL().String())
        // http://alice:secret@proxy.example.com:8080
    }

    // 3. Stream proxies from a file
    pool, err := proxypool.New("proxies.txt", proxypool.ModeSequential, false)
    if err != nil {
        log.Fatal(err)
    }
    defer pool.Close()

    for line, ok := pool.Next(); ok; line, ok = pool.Next() {
        p, err := parser.Parse(line)
        if err != nil || !p.IsValid() {
            continue
        }
        _ = proxykit.IsValidScheme(p.GetScheme())
        fmt.Println(p.ExportURL().String())
    }
}

License

See LICENSE for details.

Documentation

Index

• func IsValidCredentials(username, password string) bool
• func IsValidHostnamePort(hnp string) bool
• func IsValidScheme(s ProxyScheme) bool
• type Proxy
  • func (p *Proxy) ExportURL() *url.URL
  • func (p *Proxy) GetHost() string
  • func (p *Proxy) GetPassword() string
  • func (p *Proxy) GetScheme() ProxyScheme
  • func (p *Proxy) GetUsername() string
  • func (p *Proxy) IsCredentialFilled() bool
  • func (p *Proxy) IsValid() bool
  • func (p Proxy) IsZero() bool
  • func (p *Proxy) Reset()
  • func (p *Proxy) SetHost(s string)
  • func (p *Proxy) SetPassword(s string)
  • func (p *Proxy) SetScheme(pt ProxyScheme)
  • func (p *Proxy) SetUsername(s string)
• type ProxyGetter
• type ProxyProvider
• type ProxyResetter
• type ProxyScheme
  • func (pt ProxyScheme) String() string
• type ProxySetter
• type ProxyValidator

Functions

func IsValidCredentials

func IsValidCredentials(username, password string) bool

IsValidCredentials performs basic validation on username and password: a non-empty password requires a username, both must be <=255 bytes, contain no CTL bytes, and be printable ASCII. Returns true if all checks pass.

func IsValidHostnamePort

func IsValidHostnamePort(hnp string) bool

IsValidHostnamePort validates a <dns>:<port> combination for fields typically used for socket address.

func IsValidScheme

func IsValidScheme(s ProxyScheme) bool

IsValidScheme reports whether s is a supported proxy scheme. It returns true for the supported schemes: HTTP, HTTPS, SOCKS5 and SOCKS5H. For any other ProxyScheme value it returns false.

Types

type Proxy

type Proxy struct {
	Scheme   ProxyScheme `json:"scheme,omitempty" validate:"required_with=Host,omitempty,lowercase,oneof=http https socks5 socks5h"`
	Host     string      `json:"host,omitempty" validate:"required_with=Scheme,omitempty,hostname_port"`
	Username string      `json:"username,omitempty" validate:"required_with_all=Scheme Host Password,omitempty,printascii,max=255"`
	Password string      `json:"password,omitempty" validate:"omitempty,printascii,max=255"`
}

func (*Proxy) ExportURL

func (p *Proxy) ExportURL() *url.URL

Exports the proxy as *url.URL format

func (*Proxy) GetHost

func (p *Proxy) GetHost() string

Retrieves the host from the proxy struct.

func (*Proxy) GetPassword

func (p *Proxy) GetPassword() string

Retrieves the password from the proxy struct.

func (*Proxy) GetScheme

func (p *Proxy) GetScheme() ProxyScheme

Retrieves the scheme from the proxy struct.

func (*Proxy) GetUsername

func (p *Proxy) GetUsername() string

Retrieves the username from the proxy struct.

func (*Proxy) IsCredentialFilled

func (p *Proxy) IsCredentialFilled() bool

Checks if the proxy credential has been set.

func (*Proxy) IsValid

func (p *Proxy) IsValid() bool

Validates the proxy struct.

func (Proxy) IsZero

func (p Proxy) IsZero() bool

Checks whether the Proxy struct is empty or not

func (*Proxy) Reset

func (p *Proxy) Reset()

Resets the proxy struct to it's default values.

func (*Proxy) SetHost

func (p *Proxy) SetHost(s string)

Sets the host on the proxy struct.

func (*Proxy) SetPassword

func (p *Proxy) SetPassword(s string)

Sets the password on the proxy struct.

func (*Proxy) SetScheme

func (p *Proxy) SetScheme(pt ProxyScheme)

Sets the scheme on the proxy struct.

func (*Proxy) SetUsername

func (p *Proxy) SetUsername(s string)

Sets the username on the proxy struct.

type ProxyGetter

type ProxyGetter interface {
	ExportURL() *url.URL
	GetHost() string
	GetPassword() string
	GetScheme() ProxyScheme
	GetUsername() string
	ProxyValidator
}

type ProxyProvider

type ProxyProvider interface {
	ProxyGetter
	ProxySetter
}

type ProxyResetter

type ProxyResetter interface {
	Reset()
}

type ProxyScheme

type ProxyScheme string

const (
	HTTP    ProxyScheme = "http"
	HTTPS   ProxyScheme = "https"
	SOCKS5  ProxyScheme = "socks5"
	SOCKS5H ProxyScheme = "socks5h"
)

func (ProxyScheme) String

func (pt ProxyScheme) String() string

type ProxySetter

type ProxySetter interface {
	SetHost(s string)
	SetPassword(s string)
	SetScheme(s string)
	SetUsername(s string)
	ProxyResetter
}

type ProxyValidator

type ProxyValidator interface {
	IsCredentialFilled() bool
	IsValid() bool
	IsZero() bool
}