proxykit

README

proxykit-go

Fast, allocation-aware tools for validating, parsing, and iterating over HTTP and SOCKS proxies.

[!NOTE] Parsers and pools are safe for concurrent use. ParseInto and NextBytes support zero-allocation hot paths when caller-owned storage is reused.

Install

go get github.com/colduction/proxykit-go@latest

Requires Go 1.26.4 or later.

Packages

Package	Purpose
proxykit	Proxy model, URL export, and validation
proxyparser	Compiled custom-format parser
proxypool	Concurrent iteration over newline-delimited proxy files

Proxy

package main

import (
	"fmt"

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

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

	if proxy.IsValid() {
		fmt.Println(proxy.ExportURL())
	}
}

Supported schemes are http, https, socks5, and socks5h.

Validation is available through both Proxy methods and standalone helpers:

proxykit.IsValidScheme(proxykit.SOCKS5)
proxykit.IsValidHostnamePort("proxy.example.com:1080")
proxykit.IsValidCredentials("user", "pass")

Parser

Compile a format once and reuse it across goroutines:

package main

import (
	"fmt"
	"log"

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

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

	var proxy proxykit.Proxy
	if err := parser.ParseInto(
		"socks5://user:pass@proxy.example.com:1080",
		&proxy,
	); err != nil {
		log.Fatal(err)
	}

	fmt.Println(proxy.ExportURL())
}

Verb	Field
%t	Scheme
%h	Host
%d	Port
%u	Username
%p	Password
%%	Literal percent sign

strict=true requires an exact match. Lenient mode tolerates missing optional credentials or ports after a scheme and host are parsed.

Use errors.Is for sentinel errors such as ErrInvalidProxyFormat, and errors.As for typed errors such as ErrInvalidFormatVerb.

Pool

Each input line is returned without its trailing CR or LF:

package main

import (
	"fmt"
	"log"

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

func main() {
	pool, err := proxypool.New(
		"proxies.txt",
		proxypool.ModeSequential,
		false,
	)
	if err != nil {
		log.Fatal(err)
	}
	defer pool.Close()

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

Mode	Behavior
ModeSequential	Streams proxies in file order without an index
ModeShuffled	Uses a <path>.idx sidecar and returns one permutation per cycle

Set reuse=true to begin another cycle after the final proxy. For an allocation-free read path, reuse a byte slice with NextBytes:

buf := make([]byte, 0, 128)
for {
	var ok bool
	buf, ok = pool.NextBytes(buf[:0])
	if !ok {
		break
	}
	consume(buf)
}

[!IMPORTANT] Close releases the file and removes the shuffled sidecar index.

License

Licensed under the MIT License.

Documentation

Overview

Package proxykit defines proxy addresses, schemes, credentials, and validation helpers.

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) IsValidCredentials() bool
  • func (p *Proxy) IsValidHostnamePort() bool
  • func (p *Proxy) IsValidScheme() 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(s ProxyScheme)
  • func (p *Proxy) SetUsername(s string)
• type ProxyGetter
• type ProxyProvider
• type ProxyResetter
• type ProxyScheme
  • func (s ProxyScheme) String() string
• type ProxySetter
• type ProxyValidator

Functions

func IsValidCredentials

func IsValidCredentials(username, password string) bool

IsValidCredentials reports whether username and password form valid proxy credentials. Each value may contain at most 255 bytes and no ASCII control bytes. A non-empty password requires a non-empty username.

func IsValidHostnamePort

func IsValidHostnamePort(hnp string) bool

IsValidHostnamePort reports whether hnp is a valid host-port pair. The port must be between 1 and 65535. A non-empty host must contain only letters, decimal digits, hyphens, and dot-separated labels of at most 63 bytes.

func IsValidScheme

func IsValidScheme(s ProxyScheme) bool

IsValidScheme reports whether s is a supported proxy scheme. It returns true for HTTP, HTTPS, SOCKS5, and SOCKS5H.

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"`
}

Proxy represents a proxy endpoint and its optional credentials.

func (*Proxy) ExportURL

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

ExportURL returns a url.URL containing p's scheme, host, and credentials. It returns nil when p is nil.

func (*Proxy) GetHost

func (p *Proxy) GetHost() string

GetHost returns p's host and port. It returns an empty string when p is nil.

func (*Proxy) GetPassword

func (p *Proxy) GetPassword() string

GetPassword returns p's password. It returns an empty string when p is nil.

func (*Proxy) GetScheme

func (p *Proxy) GetScheme() ProxyScheme

GetScheme returns p's ProxyScheme. It returns the zero scheme when p is nil.

func (*Proxy) GetUsername

func (p *Proxy) GetUsername() string

GetUsername returns p's username. It returns an empty string when p is nil.

func (*Proxy) IsCredentialFilled

func (p *Proxy) IsCredentialFilled() bool

IsCredentialFilled reports whether p has a username. It reports false when p is nil.

func (*Proxy) IsValid

func (p *Proxy) IsValid() bool

IsValid reports whether p passes Proxy.IsValidScheme, Proxy.IsValidHostnamePort, and Proxy.IsValidCredentials.

func (*Proxy) IsValidCredentials

func (p *Proxy) IsValidCredentials() bool

IsValidCredentials reports whether p's credentials pass IsValidCredentials.

func (*Proxy) IsValidHostnamePort

func (p *Proxy) IsValidHostnamePort() bool

IsValidHostnamePort reports whether p's host passes IsValidHostnamePort.

func (*Proxy) IsValidScheme

func (p *Proxy) IsValidScheme() bool

IsValidScheme reports whether p's scheme passes IsValidScheme.

func (Proxy) IsZero

func (p Proxy) IsZero() bool

IsZero reports whether every field in p is empty.

func (*Proxy) Reset

func (p *Proxy) Reset()

Reset clears every field in p. It has no effect when p is nil.

func (*Proxy) SetHost

func (p *Proxy) SetHost(s string)

SetHost sets p's host and port. It has no effect when p is nil.

func (*Proxy) SetPassword

func (p *Proxy) SetPassword(s string)

SetPassword sets p's password when s is at most 255 bytes. It has no effect when p is nil or s is longer than 255 bytes.

func (*Proxy) SetScheme

func (p *Proxy) SetScheme(s ProxyScheme)

SetScheme sets p's ProxyScheme. It has no effect when p is nil.

func (*Proxy) SetUsername

func (p *Proxy) SetUsername(s string)

SetUsername sets p's username when s is at most 255 bytes. It has no effect when p is nil or s is longer than 255 bytes.

type ProxyGetter

type ProxyGetter interface {
	// ExportURL returns the proxy as a [url.URL].
	ExportURL() *url.URL

	// GetHost returns the proxy host and port.
	GetHost() string

	// GetPassword returns the proxy password.
	GetPassword() string

	// GetScheme returns the proxy scheme.
	GetScheme() ProxyScheme

	// GetUsername returns the proxy username.
	GetUsername() string
	ProxyValidator
}

ProxyGetter describes read access to proxy fields and validation.

type ProxyProvider

type ProxyProvider interface {
	ProxyGetter
	ProxySetter
}

ProxyProvider combines ProxyGetter and ProxySetter.

type ProxyResetter

type ProxyResetter interface {
	// Reset clears every proxy field.
	Reset()
}

ProxyResetter describes a proxy reset operation.

type ProxyScheme

type ProxyScheme string

ProxyScheme identifies a proxy protocol accepted by IsValidScheme.

const (
	// HTTP is the [ProxyScheme] for an HTTP proxy.
	HTTP ProxyScheme = "http"
	// HTTPS is the [ProxyScheme] for an HTTPS proxy.
	HTTPS ProxyScheme = "https"
	// SOCKS5 is the [ProxyScheme] for a SOCKS5 proxy.
	SOCKS5 ProxyScheme = "socks5"
	// SOCKS5H is the [ProxyScheme] for a SOCKS5 proxy that resolves hostnames remotely.
	SOCKS5H ProxyScheme = "socks5h"
)

func (ProxyScheme) String

func (s ProxyScheme) String() string

String returns the string representation of s.

type ProxySetter

type ProxySetter interface {
	// SetHost sets the proxy host and port.
	SetHost(s string)

	// SetPassword sets the proxy password.
	SetPassword(s string)

	// SetScheme sets the proxy scheme.
	SetScheme(s string)

	// SetUsername sets the proxy username.
	SetUsername(s string)
	ProxyResetter
}

ProxySetter describes write access to proxy fields.

type ProxyValidator

type ProxyValidator interface {
	// IsCredentialFilled reports whether the proxy has a username.
	IsCredentialFilled() bool

	// IsValidCredentials reports whether the proxy credentials are valid.
	IsValidCredentials() bool

	// IsValidHostnamePort reports whether the proxy host and port are valid.
	IsValidHostnamePort() bool

	// IsValidScheme reports whether the proxy scheme is supported.
	IsValidScheme() bool

	// IsValid reports whether the proxy fields are valid.
	IsValid() bool

	// IsZero reports whether every proxy field is empty.
	IsZero() bool
}

ProxyValidator describes proxy state and validation methods.