README
¶
Proxy / Gateway Middleware
What it does
Forwards requests to upstream services or implements simple gateway routing by path/prefix.
How to implement
package main
import (
"github.com/oarkflow/fh"
"github.com/oarkflow/fh/mw/proxy"
)
func main() {
app := fh.New()
app.Use(proxy.New(proxy.Config{Target: "http://localhost:8081"}))
app.Get("/", func(c fh.Ctx) error {
return c.Status(fh.StatusOK).SendString("ok")
})
}
Impact
Adds network I/O and upstream dependency risk. Enables gateway composition and service migration.
Ordering guidance
Run after security middleware when proxying protected routes. Run after real IP/correlation/tracing so headers can be forwarded.
Production considerations
Set timeouts, max body size, header allow/deny lists, upstream health checks, circuit breakers, and retry budgets. Avoid blindly forwarding sensitive internal headers.
SSRF protection
By default this middleware refuses to dial well-known cloud metadata endpoints (169.254.169.254, 169.254.170.2, fd00:ec2::254) even if Target or a custom Director ever resolves there — this closes the metadata-credential-theft class of SSRF. The check happens at dial time against the resolved IP (not just the configured hostname), so DNS rebinding cannot bypass it. Set DisableSSRFGuard: true only if this proxy intentionally targets a metadata endpoint. Use DeniedCIDRs to additionally block private ranges (e.g. 10.0.0.0/8) if Target/Director could ever be influenced by request data.
Forward CONNECT
Use proxy.Connect for explicitly authorized HTTP/1.1 tunnels:
app.All("/", proxy.Connect(proxy.ConnectConfig{
AllowTarget: func(target string) bool { return target == "api.example.com:443" },
Timeout: 10 * time.Second,
}))
The handler rejects non-CONNECT requests and denies all targets unless an allowlist function is provided.
Documentation
¶
Index ¶
- Variables
- func Connect(cfg ConnectConfig) fh.HandlerFunc
- func Gateway(routes map[string]Config) fh.HandlerFunc
- func New(cfg Config) fh.HandlerFunc
- func VerifyIntegrity(resp *http.Response, expectedHash string, maxBody int64) error
- func WithSRI(cfg SRIConfig) func(fh.Ctx, *http.Response) error
- type Config
- type ConnectConfig
- type SRIConfig
Constants ¶
This section is empty.
Variables ¶
var ErrBodyTooLarge = errors.New("proxy: response body exceeds SRI verification limit")
var ErrIntegrityMismatch = errors.New("proxy: subresource integrity check failed")
Functions ¶
func Connect ¶
func Connect(cfg ConnectConfig) fh.HandlerFunc
Connect returns a handler for HTTP/1.1 CONNECT requests. It establishes a raw TCP tunnel only after AllowTarget approves the authority.
func New ¶
func New(cfg Config) fh.HandlerFunc
func VerifyIntegrity ¶
Types ¶
type Config ¶
type Config struct {
Target string
StripPrefix string
AddPrefix string
Timeout time.Duration
Director func(*http.Request)
ErrorHandler func(fh.Ctx, error) error
// DisableSSRFGuard turns off the default block on proxying to well-known
// cloud metadata endpoints (169.254.169.254, 169.254.170.2,
// fd00:ec2::254). No legitimate reverse-proxy target is ever a metadata
// endpoint, so this guard is on by default; disable only if this proxy
// is intentionally used as a metadata sidecar.
DisableSSRFGuard bool
// DeniedCIDRs additionally blocks proxying to targets whose resolved IP
// falls within any of these networks (e.g. "127.0.0.0/8", "10.0.0.0/8").
// Opt-in: many legitimate proxy targets are private-network services, so
// nothing beyond the metadata guard is blocked unless configured here.
DeniedCIDRs []string
}
type ConnectConfig ¶
type ConnectConfig struct {
// AllowTarget authorizes the requested host:port. A nil function rejects all
// targets so applications must opt in to outbound tunneling explicitly.
AllowTarget func(string) bool
Timeout time.Duration
}
ConnectConfig controls a forward HTTP CONNECT tunnel.
Source Files