README.md

proxykit-go

ProxyKit Go provides a lightweight toolkit for working with proxy definitions inside Go programs. It ships with:

1. A Proxy model that encapsulates the protocol, host, and optional credentials with validation helpers.
2. A configurable parser that can decode custom proxy-format strings into that model.
3. A file-backed proxypool that lets you iterate proxies stored in a text file without loading everything into memory.

Install

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

Proxy model

The proxykit.Proxy struct keeps the scheme, host (in host:port format), username, and password. Helper methods cover the common operations:

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

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

Validation helpers such as IsValidCredentials, IsValidScheme, and IsValidHostnamePort keep proxy data sane, while Reset, getters, and setters make it easy to reuse the struct safely.

Proxy Parser

proxyparser.New lets you build a reusable parser from a format string using verbs like %t (scheme), %h (host), %d (port), %u (username), and %p (password). Strict mode enforces an exact match, and lenient mode tolerates missing credentials or trailing data.

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")

The parser returns detailed errors (such as ErrMismatchDelim or ErrInvalidProxyFormat) so callers can react appropriately.

Proxy Pool

proxypool.New provides concurrent, read-only access to newline-delimited proxy files. It automatically builds a .idx sidecar to allow O(1) seeks without loading the file into RAM. Use ModeSequential to iterate in file order or ModeShuffled for a deterministic shuffle. Set reuse to true for cycling through proxies repeatedly.

pool, err := proxypool.New("proxies.txt", proxypool.ModeShuffled, true)
defer pool.Close()

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

ProxyPool is safe for concurrent goroutines, and Close cleans up the opened files and index.