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)