proxy

package
v0.8.22 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 17, 2026 License: MIT Imports: 43 Imported by: 0

Documentation

Overview

Package proxy is the HTTP(S) router in front of apps: Caddy, embedded in the jokku binary and run as its own service ("jokku proxy"), so restarting or updating the jokku daemon never interrupts traffic.

The daemon computes routes and loads them through Caddy's admin API on a unix socket. The last config is also saved to disk, so a restarted proxy serves the same routes immediately.

Index

Constants

View Source
const (
	// AdminSocket is Caddy's admin API, reachable only by root.
	AdminSocket = "/run/jokku-proxy/admin.sock"
	// Version changes when a release needs the proxy process restarted;
	// "jokku setup" compares it to the running one. 2: the jokku_auth and
	// jokku_strip_identity handlers, which configs from now on use. 3: the
	// jokku_wake handler and jokku upstreams, for apps that sleep. 4: the
	// layer4 app, for streams. 5: the jokku_firewall handler.
	Version = "5"
)
View Source
const (
	LogApp      = "jokku_app"
	LogUpstream = "jokku_upstream"
	LogFirewall = "jokku_firewall" // what the firewall did: types.FirewallBanned or FirewallLimited
)

Access log fields Jokku adds.

View Source
const RelayHeader = "X-Jokku-Upstream"

RelayHeader carries the instance that answered a relayed request back to the edge, which drops it.

View Source
const RelayPort = 80

RelayPort is where an edge reaches a node's proxy, over the mesh.

Variables

View Source
var (
	// WakeTimeout is how long a request waits for an app to wake before it
	// gets the unreachable page.
	WakeTimeout = 60 * time.Second
	// ActivityEvery is how often the apps used are reported.
	ActivityEvery = 10 * time.Second
)

Timings; variables so tests can shorten them.

View Source
var FirewallReportEvery = 10 * time.Second

FirewallReportEvery is how often the firewall reports; a variable so tests can shorten it.

Functions

func Config

func Config(s Settings) ([]byte, error)

Config renders the Caddy JSON config. TLS hosts get certificates automatically and their plain-HTTP requests are redirected; other hosts are served over plain HTTP. Unknown hosts get a 404.

func ConfigPath

func ConfigPath(dataDir string) string

ConfigPath is where the last loaded config is saved.

func FirewallExempt

func FirewallExempt(a netip.Addr) bool

FirewallExempt says whether the firewall leaves an address alone however many requests it makes: a private one (a home network, the mesh, a tailnet), or one that never reaches the internet.

func FirewallKey

func FirewallKey(s string) (string, error)

FirewallKey is the address a ban is for: an IPv4 address, or the /64 an IPv6 address is in, since anyone with one has the rest of it. It takes an address or such a /64.

func Load

func Load(ctx context.Context, adminSocket, dataDir string, cfg []byte) error

Load sends a config to the proxy listening on adminSocket and saves it for restarts.

func ParseAllow

func ParseAllow(s string) (netip.Prefix, error)

ParseAllow reads an address or range the firewall lets alone.

func PublicHost

func PublicHost(host string) bool

PublicHost reports whether Let's Encrypt can reach a host: not an IP address, not localhost, and not an sslip.io / nip.io name for a private address (such as myapp.192.168.1.10.sslip.io).

func Run

func Run(ctx context.Context, dataDir string) error

Run is the "jokku proxy" service: Caddy with the saved config (or none yet), until ctx is done.

Types

type Applier

type Applier struct {
	DataDir     string
	AdminSocket string
	Storage     *ClusterStorage
	// HTTPPort and HTTPSPort are RelayPort and 443 when 0 (tests set them).
	HTTPPort, HTTPSPort int
	// contains filtered or unexported fields
}

Applier loads routes from the control node into this node's proxy.

func (*Applier) Apply

func (a *Applier) Apply(ctx context.Context, ps *types.ProxyState) error

type AuthHandler

type AuthHandler struct {
	App    string           `json:"app,omitempty"`
	Auth   *types.RouteAuth `json:"auth,omitempty"` // nil for the portal
	Global *types.ProxyAuth `json:"global"`
	// PortalURL is the login domain, https://auth.example.com; empty
	// without one.
	PortalURL string `json:"portal_url,omitempty"`
	// Portal makes this handler the login domain's. Hosts are then the
	// domains it may log in to.
	Portal bool                  `json:"portal,omitempty"`
	Hosts  map[string]PortalHost `json:"hosts,omitempty"`
	// contains filtered or unexported fields
}

AuthHandler puts a login in front of an app (http-auth), or, as the portal, serves the login domain: one login page for every app whose login is the cluster's users, which hands each app's domain a session of its own.

Everything it needs is in its config and the session key, so any ingress node, an edge included, checks logins on its own. Its pages live under /.jokku/ on the app's domains:

/.jokku/login          the login form (users get a second step for a TOTP code)
/.jokku/callback       where the portal hands a login to an app's domain
/.jokku/logout         ends the session
/.jokku/share/<token>  a share link: lets its holder in until it expires

Requests that pass get X-Jokku-User (the user's name, for users logins) and lose the session cookie on the way to the app.

func (AuthHandler) CaddyModule

func (AuthHandler) CaddyModule() caddy.ModuleInfo

func (*AuthHandler) Provision

func (h *AuthHandler) Provision(caddy.Context) error

func (*AuthHandler) ServeHTTP

func (h *AuthHandler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

type ClusterStorage

type ClusterStorage struct {
	URL    string `json:"url"`    // the control node's API, https://host:7443
	Token  string `json:"token"`  // this node's token
	Pin    string `json:"pin"`    // the control node's TLS key pin
	Cache  string `json:"cache"`  // local mirror directory
	Legacy string `json:"legacy"` // pre-cluster local storage, optional
	// contains filtered or unexported fields
}

ClusterStorage is a Caddy storage module that keeps certificates, ACME accounts and challenge tokens on the control node, so every ingress node shares them: any node can answer an HTTP-01 challenge for a certificate another node asked for, and each certificate is issued once.

Everything read or written is mirrored to a local directory. If the control node is unreachable, reads fall back to that copy, so a restarted proxy keeps serving the certificates it had. The control node stays the truth: a key it doesn't have is dropped from the mirror, never served from it.

Legacy is the file storage a single server used before it joined a cluster; certificates found only there are moved to the control node.

func (ClusterStorage) CaddyModule

func (ClusterStorage) CaddyModule() caddy.ModuleInfo

func (*ClusterStorage) CertMagicStorage

func (s *ClusterStorage) CertMagicStorage() (certmagic.Storage, error)

func (*ClusterStorage) Delete

func (s *ClusterStorage) Delete(ctx context.Context, key string) error

func (*ClusterStorage) Exists

func (s *ClusterStorage) Exists(ctx context.Context, key string) bool

func (*ClusterStorage) List

func (s *ClusterStorage) List(ctx context.Context, prefix string, recursive bool) ([]string, error)

func (*ClusterStorage) Load

func (s *ClusterStorage) Load(ctx context.Context, key string) ([]byte, error)

func (*ClusterStorage) Lock

func (s *ClusterStorage) Lock(ctx context.Context, name string) error

Lock waits for a cluster-wide lock, so only one node at a time obtains or renews a given certificate.

func (*ClusterStorage) Provision

func (s *ClusterStorage) Provision(caddy.Context) error

func (*ClusterStorage) Stat

func (*ClusterStorage) Store

func (s *ClusterStorage) Store(ctx context.Context, key string, value []byte) error

func (*ClusterStorage) Unlock

func (s *ClusterStorage) Unlock(ctx context.Context, name string) error

type Control

type Control struct {
	URL   string `json:"url"`
	Token string `json:"token"`
	Pin   string `json:"pin"`
}

Control is the control node's API, reached as this node.

type FirewallHandler

type FirewallHandler struct {
	App     string              `json:"app,omitempty"`
	Rules   types.ProxyFirewall `json:"rules"`
	Control *Control            `json:"control,omitempty"` // where reports go; nil for nowhere
}

FirewallHandler is the firewall in front of one app's routes (App "" for hosts no app serves).

func (FirewallHandler) CaddyModule

func (FirewallHandler) CaddyModule() caddy.ModuleInfo

func (*FirewallHandler) Provision

func (h *FirewallHandler) Provision(caddy.Context) error

func (*FirewallHandler) ServeHTTP

type PortalHost

type PortalHost struct {
	Users []string `json:"users"` // empty: every user
	TLS   bool     `json:"tls,omitempty"`
}

PortalHost is a domain the portal logs in to: who may, and whether it is served over HTTPS (its login is then only ever handed over HTTPS).

type Route

type Route struct {
	App       string
	Hosts     []string
	Upstreams []string
	TLS       bool
	// UpstreamTLS: the upstreams speak HTTPS, with any certificate if
	// Insecure.
	UpstreamTLS, Insecure bool
	// Auth puts a login in front of the route (with Settings.Auth).
	Auth *types.RouteAuth
	// Sleeps: the app sleeps when idle, and a request wakes it (after the
	// login, if it has one).
	Sleeps bool
	// NoCompress: the app opted out of compression, and NoFirewall of the
	// firewall.
	NoCompress, NoFirewall bool
	// Relayed, on an edge: the upstreams are nodes' proxies (RelayPort),
	// which pass requests on to the app's instances.
	Relayed bool
}

Route sends requests for Hosts to Upstreams (IP:port of healthy web instances, or an external app's target). An empty Upstreams answers 502.

type Settings

type Settings struct {
	Routes      []Route
	Email       string // ACME account email; optional
	DataDir     string // certificates and the saved config
	HTTPPort    int
	HTTPSPort   int
	AdminSocket string // default AdminSocket
	// Storage keeps certificates on the control node (shared by every
	// ingress node); nil keeps them on local disk.
	Storage *ClusterStorage
	// Auth is what routes with a login need; with a login domain, that
	// domain gets the login page every users login shares.
	Auth *types.ProxyAuth
	// Edges are the subnets of the edges that send requests through this
	// node (see relayRoute).
	Edges []string
	// Streams are the TCP routes (see streamServers).
	Streams []types.ProxyStream
	// Firewall is the firewall's rules (see FirewallHandler); nil for none.
	Firewall *types.ProxyFirewall
}

type StripIdentity

type StripIdentity struct{}

StripIdentity removes X-Jokku-User from requests, in every spelling an app's server might read as it (X_Jokku_User becomes HTTP_X_JOKKU_USER in CGI, Rack and WSGI): on every route, so no app ever trusts one a visitor sent, login or not. (Relay routes, which only edges reach, pass on what the edge's own route left.)

func (StripIdentity) CaddyModule

func (StripIdentity) CaddyModule() caddy.ModuleInfo

func (StripIdentity) ServeHTTP

type WakeHandler

type WakeHandler struct {
	App     string   `json:"app"`
	Control *Control `json:"control,omitempty"` // nil: no one to wake it
}

WakeHandler wakes a sleeping app for a request, and reports its use.

func (WakeHandler) CaddyModule

func (WakeHandler) CaddyModule() caddy.ModuleInfo

func (*WakeHandler) Provision

func (h *WakeHandler) Provision(caddy.Context) error

func (*WakeHandler) ServeHTTP

func (h *WakeHandler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

type WakeUpstreams

type WakeUpstreams struct {
	App       string   `json:"app"`
	Upstreams []string `json:"upstreams"`
}

WakeUpstreams is a sleeping app's reverse proxy's upstream source: its instances in the newest config.

func (WakeUpstreams) CaddyModule

func (WakeUpstreams) CaddyModule() caddy.ModuleInfo

func (*WakeUpstreams) GetUpstreams

func (u *WakeUpstreams) GetUpstreams(*http.Request) ([]*reverseproxy.Upstream, error)

func (*WakeUpstreams) Provision

func (u *WakeUpstreams) Provision(caddy.Context) error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL