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
- Variables
- func Config(s Settings) ([]byte, error)
- func ConfigPath(dataDir string) string
- func FirewallExempt(a netip.Addr) bool
- func FirewallKey(s string) (string, error)
- func Load(ctx context.Context, adminSocket, dataDir string, cfg []byte) error
- func ParseAllow(s string) (netip.Prefix, error)
- func PublicHost(host string) bool
- func Run(ctx context.Context, dataDir string) error
- type Applier
- type AuthHandler
- type ClusterStorage
- func (ClusterStorage) CaddyModule() caddy.ModuleInfo
- func (s *ClusterStorage) CertMagicStorage() (certmagic.Storage, error)
- func (s *ClusterStorage) Delete(ctx context.Context, key string) error
- func (s *ClusterStorage) Exists(ctx context.Context, key string) bool
- func (s *ClusterStorage) List(ctx context.Context, prefix string, recursive bool) ([]string, error)
- func (s *ClusterStorage) Load(ctx context.Context, key string) ([]byte, error)
- func (s *ClusterStorage) Lock(ctx context.Context, name string) error
- func (s *ClusterStorage) Provision(caddy.Context) error
- func (s *ClusterStorage) Stat(ctx context.Context, key string) (certmagic.KeyInfo, error)
- func (s *ClusterStorage) Store(ctx context.Context, key string, value []byte) error
- func (s *ClusterStorage) Unlock(ctx context.Context, name string) error
- type Control
- type FirewallHandler
- type PortalHost
- type Route
- type Settings
- type StripIdentity
- type WakeHandler
- type WakeUpstreams
Constants ¶
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" )
const ( LogApp = "jokku_app" LogUpstream = "jokku_upstream" LogFirewall = "jokku_firewall" // what the firewall did: types.FirewallBanned or FirewallLimited )
Access log fields Jokku adds.
const RelayHeader = "X-Jokku-Upstream"
RelayHeader carries the instance that answered a relayed request back to the edge, which drops it.
const RelayPort = 80
RelayPort is where an edge reaches a node's proxy, over the mesh.
Variables ¶
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.
var FirewallReportEvery = 10 * time.Second
FirewallReportEvery is how often the firewall reports; a variable so tests can shorten it.
Functions ¶
func Config ¶
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 ¶
ConfigPath is where the last loaded config is saved.
func FirewallExempt ¶
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 ¶
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 ParseAllow ¶
ParseAllow reads an address or range the firewall lets alone.
func PublicHost ¶
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).
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.
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) 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) 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.
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) ServeHTTP ¶
func (h *FirewallHandler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
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 ¶
func (StripIdentity) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
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) ServeHTTP ¶
func (h *WakeHandler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
type WakeUpstreams ¶
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)