decodo

Documentation

Overview

Package decodo provides helpers for building Decodo residential proxy credentials, generating proxy URLs, and managing keyed sticky-session pools that can be reused by Go HTTP clients.

Credential Configuration

Create an Auth from your Decodo user credentials:

auth, err := decodo.NewAuth("my-proxy-user", "my-proxy-password")
// NewAuth validates the raw proxy username early and rejects escaped
// or unsupported characters before a request reaches the proxy.

Build a Config describing your desired proxy session and endpoint:

config := decodo.Config{
    Auth: auth,
    Session: decodo.Session{
        Type:             decodo.SessionTypeSticky,
        DurationMinutes:  10,
        Country:           "us",
        State:             "ny",  // optional US state filter
        City:              "new-york", // optional city filter
    },
}

Generating Proxy URLs

Produce a proxy URL string suitable for httpcloak or a SOCKS5 dialer:

proxyURL, err := config.ProxyURL()

Sticky Session Pool

For applications handling multiple business keys (e.g., per-user or per-order), use a Pool to manage sticky sessions with automatic rotation:

pool, err := decodo.NewPool(decodo.PoolOptions{Config: config})

lease, err := pool.Get("user-123")  // returns same proxy for this key
// ... use lease.ProxyURL with your HTTP client

When a proxy fails, report it and the pool will rotate automatically:

pool.ReportFailure("user-123", decodo.FailureCause{Err: err})

See https://pkg.go.dev/github.com/VectorSprint/go-proxy-pool/pkg/decodo/adapter/httpcloak and https://pkg.go.dev/github.com/VectorSprint/go-proxy-pool/pkg/decodo/adapter/nethttp for adapter packages that convert Config or Lease into proxy strings compatible with popular Go HTTP libraries.

Index

• type Auth
  • func NewAuth(username, password string) (Auth, error)
  • func (a Auth) Validate() error
• type Config
  • func (c *Config) ApplyPreset()
  • func (c Config) Normalized() (Config, error)
  • func (c Config) Preset() (EndpointPreset, bool)
  • func (c Config) ProxyURL() (*url.URL, error)
  • func (c Config) ProxyUsername() (string, error)
  • func (c Config) Validate() error
  • func (c Config) ValidateShallow() error
• type EndpointPreset
• type EndpointSpec
  • func NewEndpointSpec(host string, rotatingPort int, stickyPortRange PortRange) (EndpointSpec, error)
  • func (e EndpointSpec) IsZero() bool
  • func (e EndpointSpec) Validate() error
• type FailureCause
• type Lease
• type Pool
  • func NewPool(options PoolOptions) (*Pool, error)
  • func (p *Pool) CleanupExpired() int
  • func (p *Pool) Get(key string) (Lease, error)
  • func (p *Pool) ReportFailure(key string, _ FailureCause) error
  • func (p *Pool) Rotate(key string) error
• type PoolOptions
• type PortRange
  • func (r PortRange) Contains(port int) bool
  • func (r PortRange) IsZero() bool
  • func (r PortRange) Validate() error
• type Session
  • func (s Session) TTL() time.Duration
• type SessionType
• type Targeting

Examples

• NewAuth
• NewAuth (InvalidUsername)
• Pool.Get

Types

type Auth

type Auth struct {
	Username string
	Password string
}

Auth stores the raw Decodo proxy username and password from the dashboard.

func NewAuth

func NewAuth(username, password string) (Auth, error)

NewAuth validates and normalizes raw Decodo dashboard credentials.

Example

package main

import (
	"fmt"

	"github.com/VectorSprint/go-proxy-pool/pkg/decodo"
)

func main() {
	auth, err := decodo.NewAuth("my-proxy-user", "my-proxy-password")
	if err != nil {
		panic(err)
	}

	cfg := decodo.Config{
		Auth: auth,
		Targeting: decodo.Targeting{
			Country: "us",
			City:    "new_york",
		},
		Session: decodo.Session{
			Type:            decodo.SessionTypeSticky,
			ID:              "account-1",
			DurationMinutes: 30,
		},
	}

	proxyURL, err := cfg.ProxyURL()
	if err != nil {
		panic(err)
	}

	fmt.Println(proxyURL.String())
}

Output:
http://user-my-proxy-user-country-us-city-new_york-session-account-1-sessionduration-30:my-proxy-password@gate.decodo.com:7000

Example (InvalidUsername)

package main

import (
	"fmt"

	"github.com/VectorSprint/go-proxy-pool/pkg/decodo"
)

func main() {
	_, err := decodo.NewAuth("my%2Fproxy%2Fuser", "my-proxy-password")
	fmt.Println(err)
}

Output:
username contains invalid characters; only letters, digits, dot, underscore, and hyphen are allowed

func (Auth) Validate

func (a Auth) Validate() error

Validate checks whether the credentials can be used to build a Decodo proxy username.

type Config

type Config struct {
	Auth         Auth
	EndpointSpec EndpointSpec
	Endpoint     string
	Port         int
	Targeting    Targeting
	Session      Session
}

Config describes a Decodo user:pass backconnect proxy configuration.

func (*Config) ApplyPreset

func (c *Config) ApplyPreset()

ApplyPreset updates the EndpointSpec to match the targeting configuration using well-known Decodo endpoint presets. If no matching preset is found, no changes are made. This allows targeting to automatically select the correct endpoint, port, and sticky port range.

func (Config) Normalized

func (c Config) Normalized() (Config, error)

Normalized returns a copy of the configuration with defaults and normalized tokens applied.

func (Config) Preset

func (c Config) Preset() (EndpointPreset, bool)

Preset returns the endpoint preset for the configured targeting, or a false ok return if none match.

func (Config) ProxyURL

func (c Config) ProxyURL() (*url.URL, error)

ProxyURL builds an authenticated Decodo proxy URL suitable for HTTP proxy clients.

func (Config) ProxyUsername

func (c Config) ProxyUsername() (string, error)

ProxyUsername builds the Decodo proxy username, including targeting and session parameters.

func (Config) Validate

func (c Config) Validate() error

Validate checks whether the configuration satisfies Decodo parameter constraints.

func (Config) ValidateShallow

func (c Config) ValidateShallow() error

ValidateShallow checks lightweight structural constraints before full validation.

type EndpointPreset

type EndpointPreset struct {
	Host            string
	RotatingPort    int
	StickyPortRange PortRange
}

EndpointPreset describes a known Decodo endpoint with its rotating port and sticky port range.

type EndpointSpec

type EndpointSpec struct {
	Host            string
	RotatingPort    int
	StickyPortRange PortRange
}

EndpointSpec describes a Decodo endpoint together with its rotating port and sticky port range.

func NewEndpointSpec

func NewEndpointSpec(host string, rotatingPort int, stickyPortRange PortRange) (EndpointSpec, error)

NewEndpointSpec validates and returns a Decodo endpoint specification.

func (EndpointSpec) IsZero

func (e EndpointSpec) IsZero() bool

IsZero reports whether the endpoint specification is unset.

func (EndpointSpec) Validate

func (e EndpointSpec) Validate() error

Validate checks whether the endpoint specification is structurally valid.

type FailureCause

type FailureCause struct {
	Err        error
	StatusCode int
}

FailureCause represents a proxy failure reported by the caller to Pool.ReportFailure.

type Lease

type Lease struct {
	Key       string
	SessionID string
	Port      int
	ProxyURL  string
	ExpiresAt time.Time
}

Lease represents a resolved sticky-session proxy assignment for a business key. Obtain a lease by calling Pool.Get. The lease remains valid until its ExpiresAt time has passed, unless explicitly rotated via Pool.Rotate.

type Pool

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

Pool manages sticky-session proxy leases, each keyed by a caller-defined business identifier (e.g., user ID, order ID). The Pool ensures that each key consistently uses the same residential proxy for the session duration, then rotates automatically.

func NewPool

func NewPool(options PoolOptions) (*Pool, error)

NewPool creates a keyed sticky-session Pool from a Decodo Config. The Config must have Session.Type set to SessionTypeSticky. NewPool returns an error if the config validation fails or if a sticky session is not requested.

func (*Pool) CleanupExpired

func (p *Pool) CleanupExpired() int

CleanupExpired removes all expired leases from the pool and returns the number of entries deleted. Call this periodically (e.g., via a background goroutine) to prevent the pool from accumulating stale entries.

func (*Pool) Get

func (p *Pool) Get(key string) (Lease, error)

Get returns the active Lease for the given business key. If no active lease exists or the existing lease has expired, a new one is allocated automatically.

Example

package main

import (
	"fmt"

	"github.com/VectorSprint/go-proxy-pool/pkg/decodo"
	decodohttpcloak "github.com/VectorSprint/go-proxy-pool/pkg/decodo/adapter/httpcloak"
)

func main() {
	auth, err := decodo.NewAuth("my-proxy-user", "my-proxy-password")
	if err != nil {
		panic(err)
	}

	pool, err := decodo.NewPool(decodo.PoolOptions{
		Config: decodo.Config{
			Auth: auth,
			Session: decodo.Session{
				Type:            decodo.SessionTypeSticky,
				DurationMinutes: 30,
			},
		},
		NewSessionID: func(key string) string {
			return "session-" + key
		},
	})
	if err != nil {
		panic(err)
	}

	lease, err := pool.Get("account-1")
	if err != nil {
		panic(err)
	}

	fmt.Println(decodohttpcloak.ProxyStringFromLease(lease))
}

Output:
http://user-my-proxy-user-session-session-account-1-sessionduration-30:my-proxy-password@gate.decodo.com:7000

func (*Pool) ReportFailure

func (p *Pool) ReportFailure(key string, _ FailureCause) error

ReportFailure records a failure for the given key. When the number of recorded failures reaches FailureThreshold, the lease is rotated automatically.

func (*Pool) Rotate

func (p *Pool) Rotate(key string) error

Rotate immediately invalidates the current lease for the key so that the next call to Get allocates a fresh session.

type PoolOptions

type PoolOptions struct {
	Config           Config
	FailureThreshold int
	Now              func() time.Time
	NewSessionID     func(key string) string
	// RandomPort selects a random sticky port from the available range instead of
	// sequentially allocating ports. This reduces detection risk when using a single
	// endpoint with many sessions.
	RandomPort bool
	// Rand is the random source for port selection. If nil, math/rand is used.
	Rand *rand.Rand
}

PoolOptions configures how a keyed sticky-session Pool behaves.

type PortRange

type PortRange struct {
	Start int
	End   int
}

PortRange describes an inclusive port range.

func (PortRange) Contains

func (r PortRange) Contains(port int) bool

Contains reports whether the range includes the provided port.

func (PortRange) IsZero

func (r PortRange) IsZero() bool

IsZero reports whether the port range is unset.

func (PortRange) Validate

func (r PortRange) Validate() error

Validate checks whether the port range is structurally valid.

type Session

type Session struct {
	Type            SessionType
	ID              string
	DurationMinutes int
}

Session describes whether requests should rotate IPs or reuse a sticky session.

func (Session) TTL

func (s Session) TTL() time.Duration

TTL returns the sticky-session lifetime as a time.Duration.

type SessionType

type SessionType string

const (
	// SessionTypeRotating requests a new residential IP on each proxy request.
	SessionTypeRotating SessionType = "rotating"
	// SessionTypeSticky keeps the same residential IP for the configured session duration.
	SessionTypeSticky SessionType = "sticky"
)

type Targeting

type Targeting struct {
	Country   string
	City      string
	State     string
	ZIP       string
	Continent string
	ASN       int
}

Targeting describes optional Decodo location and carrier targeting parameters.