proxy

Documentation

Overview

Package proxy is an exact-host routing reverse proxy.

Requests are routed only when their normalized full Host header matches a hostname generated from the site's stored hostname identity. The registry is reloaded whenever sites.toml changes, so newly added sites route without a restart. Unknown or bare hosts get a landing page listing every site.

The Host header sent to the backend is rewritten to the backend's own address by default, so dev servers with host allowlists (Vite 5+, Next, Rails host authorization) accept proxied requests. Sites that need the original Host can set preserve_host = true. X-Forwarded-Host/Proto/For are always set from the inbound request.

httputil.ReverseProxy transparently handles HTTP/1.1 Upgrade (websockets), which jigyll live-reload and Vite/Next HMR depend on.

Index

• Constants
• func Accepting(settings config.Settings) bool
• func EffectiveSettings(settings config.Settings, st *state.State) config.Settings
• func ParseGroups(raw string) ([]uint32, error)
• func RunInheritedWorker(settings config.Settings, listenerFile, readyFile *os.File) error
• func RunPrivilegedBind(request BindRequest) (int, error)
• func Running(st *state.State) (bool, int)
• func StopBackground() error
• type BindRequest
• type Server
  • func New(settings config.Settings) *Server
  • func (s *Server) ListenAndServe() error
  • func (s *Server) Serve(listener net.Listener) error
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type StartResult
  • func StartBackground(settings config.Settings) (StartResult, error)

Constants

const Slug = "__proxy"

Slug is the reserved state key for the background proxy process.

Functions

func Accepting

func Accepting(settings config.Settings) bool

Accepting reports whether the active HTTP listener is accepting connections.

func EffectiveSettings

func EffectiveSettings(settings config.Settings, st *state.State) config.Settings

EffectiveSettings substitutes the live listener port while the proxy is running. The caller's settings remain the preferred settings for next start.

func ParseGroups

func ParseGroups(raw string) ([]uint32, error)

func RunInheritedWorker

func RunInheritedWorker(settings config.Settings, listenerFile, readyFile *os.File) error

func RunPrivilegedBind

func RunPrivilegedBind(request BindRequest) (int, error)

RunPrivilegedBind binds the requested port, starts the worker as the requesting user, waits for the worker's ready signal, and returns its PID.

func Running

func Running(st *state.State) (bool, int)

Running reports whether the background proxy process is alive, with its pid.

func StopBackground

func StopBackground() error

StopBackground signals the background proxy and clears its state entry.

Types

type BindRequest

type BindRequest struct {
	BindHost   string
	Worker     string
	Port       int
	EnableMDNS bool
	UID        uint32
	GID        uint32
	Groups     []uint32
	Home       string
	ConfigHome string
	StateHome  string
}

BindRequest is the complete, resolved handoff contract for the root helper. It contains no settings or registry data; the helper only binds and starts the regular-user worker.

type Server

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

Server is a running proxy instance.

func New

func New(settings config.Settings) *Server

New builds a proxy server and loads the initial routing table.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe() error

ListenAndServe starts the proxy on the active HTTP listener port.

func (*Server) Serve

func (s *Server) Serve(listener net.Listener) error

Serve starts the proxy on a listener acquired by the caller.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

type StartResult

type StartResult struct {
	Port         int
	UsedFallback bool
	PreferredErr error
}

StartResult describes the listener selected for a background proxy.

func StartBackground

func StartBackground(settings config.Settings) (StartResult, error)

StartBackground launches the proxy worker with a listener acquired by the invoking user or, only for a low port, the narrow bind helper.