httpfx

README

httpfx

Uber Fx module for net/http.Client with SOCKS5, HTTP proxy, and environment-based proxy support.

Report Bug · Request Feature

Table of Contents

• Table of Contents
• About The Project
  • Built With
• Getting Started
  • Prerequisites
  • Installation
• Usage
  • Module Setup
  • Configuration Reference
  • Factory & Per-Client Options
    • Available Options
  • Proxy Examples
• Roadmap
• Contributing
• License
• Acknowledgments

---

About The Project

httpfx is an Uber Fx module that provides a configured *http.Client and a Factory for creating additional client instances. It supports:

• SOCKS5 proxy via golang.org/x/net/proxy (socks5://user:pass@host:port)
• HTTP-level proxy via net/http.Transport.Proxy (http://proxy:8080)
• Environment-based proxy via ALL_PROXY env var
• Per-host proxy bypass for hosts that should connect directly
• Per-client overrides via functional options on the Factory
• Transport tuning — idle connections, timeouts, pool sizes

Built With

• 
• 
• 

(back to top)

---

Getting Started

Prerequisites

• Go 1.25+
• An application using Uber Fx for dependency injection

Installation

go get github.com/go-core-fx/httpfx@latest

(back to top)

---

Usage

Module Setup

import (
    "time"

    "github.com/go-core-fx/httpfx"
    "go.uber.org/fx"
)

func main() {
    fx.New(
        fx.Provide(func() httpfx.Config {
            return httpfx.Config{
                ProxyURL: "socks5://127.0.0.1:1080",
                Bypass:   "localhost,127.0.0.1",
                Timeout:  30 * time.Second,
            }
        }),
        httpfx.Module(),
        // ... other modules
    ).Run()
}

The module provides both a default *http.Client and a Factory for creating additional clients.

Configuration Reference

Field	Type	Default	Description
ProxyURL	string	""	SOCKS5 proxy URL (e.g. socks5://user:pass@host:port). Takes highest precedence.
ProxyFromEnv	bool	false	Read proxy from ALL_PROXY env var when ProxyURL is empty.
Bypass	string	""	Comma-separated hosts to bypass the SOCKS proxy (e.g. localhost,127.0.0.1).
Timeout	time.Duration	0	Client-level request timeout. Zero means no timeout.
MaxIdleConns	int	0	Maximum idle (keep-alive) connections. Zero means no limit.
MaxIdleConnsPerHost	int	0	Maximum idle connections per host. Zero means Go default (2).
IdleConnTimeout	time.Duration	0	Maximum time a connection stays idle. Zero means no timeout.

Proxy precedence: ProxyURL → ProxyFromEnv. To disable all proxying, clear ProxyURL and set ProxyFromEnv: false.

Factory & Per-Client Options

Inject httpfx.Factory to create additional clients with shared base config but per-client overrides:

func Handler(f httpfx.Factory) {
    // Default client — uses factory base config
    defaultClient := f.NewClient()

    // Override timeout for a fast endpoint
    apiClient := f.NewClient(httpfx.WithTimeout(5 * time.Second))

    // Disable proxy for internal service calls
    internalClient := f.NewClient(httpfx.WithProxyURL(""))

    // Custom transport for a specific module
    uploadClient := f.NewClient(
        httpfx.WithTimeout(5 * time.Minute),
        httpfx.WithMaxIdleConns(10),
    )
}

Available Options

Option	Description
WithProxyURL(url)	Override SOCKS5 proxy URL
WithProxyFromEnv(v)	Override env-based proxy flag
WithBypass(bypass)	Override proxy bypass list
WithTimeout(d)	Override client timeout
WithMaxIdleConns(n)	Override max idle connections
WithMaxIdleConnsPerHost(n)	Override max idle connections per host
WithIdleConnTimeout(d)	Override idle connection timeout

Proxy Examples

SOCKS5 with authentication:

httpfx.Config{
    ProxyURL: "socks5://user:pass@127.0.0.1:1080",
}

Environment-based (reads ALL_PROXY):

httpfx.Config{
    ProxyFromEnv: true,
}

export ALL_PROXY="socks5://127.0.0.1:1080"

SOCKS5 with bypass for local addresses and CIDR ranges:

httpfx.Config{
    ProxyURL: "socks5://127.0.0.1:1080",
    Bypass:   "localhost,127.0.0.1,192.168.0.0/16",
}

(back to top)

---

Roadmap

• SOCKS5 proxy support via golang.org/x/net/proxy
• Environment-based proxy (ALL_PROXY)
• Per-host proxy bypass
• Factory with per-client functional options
• Transport tuning (idle connections, timeouts)
• TLS configuration options
• Proxy authentication header support

See the open issues for a full list of proposed features.

(back to top)

---

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

---

License

Distributed under the Apache License 2.0. See LICENSE for more information.

(back to top)

---

Acknowledgments

• Uber Fx — dependency injection framework
• golang.org/x/net/proxy — SOCKS5 and environment-based proxy dialers
• Best-README-Template — README structure

(back to top)

Documentation

Index

• Constants
• Variables
• func Module() fx.Option
• type Config
• type Factory
  • func NewFactory(config Config, logger *zap.Logger) Factory
• type Option
  • func WithBypass(bypass string) Option
  • func WithIdleConnTimeout(t time.Duration) Option
  • func WithMaxIdleConns(n int) Option
  • func WithMaxIdleConnsPerHost(n int) Option
  • func WithProxyFromEnv(v bool) Option
  • func WithProxyURL(rawURL string) Option
  • func WithTimeout(t time.Duration) Option

Constants

const ModuleName = "httpfx"

Variables

var (
	// ErrInvalidConfig is returned when the HTTP client configuration is invalid.
	ErrInvalidConfig = errors.New("invalid config")

	// ErrInvalidProxyURL is returned when the proxy URL cannot be parsed.
	ErrInvalidProxyURL = errors.New("invalid proxy URL")

	// ErrProxyDialFailed is returned when the proxy dialer cannot be created.
	ErrProxyDialFailed = errors.New("proxy dialer creation failed")
)

Functions

func Module

func Module() fx.Option

Types

type Config

type Config struct {
	// ProxyURL is an explicit SOCKS5 proxy URL (e.g., "socks5://user:pass@host:port").
	// Empty means no proxy. Takes precedence over ProxyFromEnv.
	ProxyURL string

	// ProxyFromEnv enables reading the proxy from the ALL_PROXY environment variable.
	// Used only when ProxyURL is empty.
	ProxyFromEnv bool

	// Bypass is a comma-separated list of hosts that bypass the proxy
	// (e.g., "localhost,127.0.0.1").
	Bypass string

	// Timeout is the HTTP client-level timeout. Zero means no timeout.
	Timeout time.Duration

	// MaxIdleConns is the maximum number of idle (keep-alive) connections.
	// Zero means no limit.
	MaxIdleConns int

	// MaxIdleConnsPerHost is the maximum idle connections per host.
	// Zero means DefaultMaxIdleConnsPerHost (2).
	MaxIdleConnsPerHost int

	// IdleConnTimeout is the maximum time an idle connection is kept alive.
	// Zero means no timeout.
	IdleConnTimeout time.Duration
}

Config holds the HTTP client configuration.

type Factory

type Factory interface {
	// NewClient creates a new [http.Client] using the factory's base configuration,
	// with optional per-client overrides via [Option].
	NewClient(opts ...Option) *http.Client
}

Factory creates http.Client instances with shared proxy and transport configuration.

func NewFactory

func NewFactory(config Config, logger *zap.Logger) Factory

NewFactory creates a new Factory from the provided configuration.

type Option

type Option func(*clientOptions)

Option configures per-client overrides on Factory.NewClient.

func WithBypass

func WithBypass(bypass string) Option

WithBypass overrides the proxy bypass list for this client.

func WithIdleConnTimeout

func WithIdleConnTimeout(t time.Duration) Option

WithIdleConnTimeout overrides the idle connection timeout for this client.

func WithMaxIdleConns

func WithMaxIdleConns(n int) Option

WithMaxIdleConns overrides the maximum idle connections for this client.

func WithMaxIdleConnsPerHost

func WithMaxIdleConnsPerHost(n int) Option

WithMaxIdleConnsPerHost overrides the maximum idle connections per host for this client.

func WithProxyFromEnv

func WithProxyFromEnv(v bool) Option

WithProxyFromEnv overrides the ProxyFromEnv flag for this client.

func WithProxyURL

func WithProxyURL(rawURL string) Option

WithProxyURL overrides the SOCKS5 proxy URL for this client.

func WithTimeout

func WithTimeout(t time.Duration) Option

WithTimeout overrides the client-level timeout for this client.