Documentation
¶
Overview ¶
Package lb is the copies table of shinyctl's load balancer: which copies of each app exist, by role, kept in the load balancer's own memory and changed through a control-socket route. The upstream source and the sticky selection policy read it for every request, so a copy that dies, a spare that takes over or a scale-up changes where visitors go without a reload of the settings. A reload rebinds every listener and drops the connections that arrive while it runs; a table update touches none.
The table is a package global: the engine builds new module instances on every reload, and the table must outlive them. Tests in this package and in internal/proxy share it, so they must never call t.Parallel, and they reset it with Set(nil) when they are done.
Index ¶
Constants ¶
const AdminPath = "/shinyctl/copies"
AdminPath is the control-socket route the table is read and replaced through.
const PIDHeader = "X-Shinyctl-Pid"
PIDHeader names, on the table's route, the process that answers, once it serves its settings (see MarkServing).
Variables ¶
This section is empty.
Functions ¶
func InFlight ¶
func InFlight() int
InFlight is the number of requests being answered now, WebSockets not counted. A load balancer that is stopping waits for it to reach zero: the engine closes its listeners at once on a stop, but answers the requests in flight in goroutines that nothing waits for before the process exits.
func LoadFile ¶
LoadFile sets the table from the file at path, which the daemon writes after each update so a load balancer that restarts serves at once. A missing file is an empty table. A file that cannot be used also sets an empty table, and the error says so.
func MarkServing ¶
func MarkServing(pid int)
MarkServing records that this process, pid, has loaded its settings and serves every app's port.
func Set ¶
func Set(t Table)
Set replaces the whole table. Readers see either the old table or the new one, never a mix.
It also remembers who took whose place. A visitor's cookie names a copy; when that copy dies the daemon's update can land while the visitor's request is still waiting to retry, and the table no longer lists the dead copy, so nothing says which copy the visitor belonged to. For each app the active copies that have left the table altogether are paired, in order, with the warm copies that became active in the same update, and a cookie that names a dead copy goes to its partner (see Sticky.Select). A pairing is kept until the dead copy is listed again, its app is gone, or successorTTL has passed. It lives in the snapshot, so it is replaced with the table and read with it; a load balancer that restarts starts with none.
Types ¶
type Copies ¶
type Copies struct {
App string `json:"app,omitempty"`
}
Copies is the upstream source: the copies listed for an app, read from the table for every request.
func (Copies) CaddyModule ¶
func (Copies) CaddyModule() caddy.ModuleInfo
func (*Copies) GetUpstreams ¶
GetUpstreams returns a fresh Upstream for each listed copy, in the table's order. The handler fills in each one's shared state before using it, so values must not be reused between requests. It never fails: an app with no copies gets an empty list, which the handler waits out and then answers with the restarting page.
type InFlightCounter ¶
type InFlightCounter struct{}
InFlightCounter is the handler that counts: the first one of every route.
func (InFlightCounter) CaddyModule ¶
func (InFlightCounter) CaddyModule() caddy.ModuleInfo
func (InFlightCounter) ServeHTTP ¶
func (InFlightCounter) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
type Pool ¶
type Pool struct {
Active []string `json:"active,omitempty"` // take new visitors
Warm []string `json:"warm,omitempty"` // ready spares: take no new visitors while every active copy is up; one stands in for each active copy that is down
// Draining copies keep the visitors pinned to them and get no new ones; a
// visitor who loads the page again is placed anew (see pageLoad).
// shinyctl-api lists here the copies a redeploy or a scale-down retires.
Draining []string `json:"draining,omitempty"`
}
Pool is one app's copies by role, as "127.0.0.1:<port>" dial addresses, each list in the order the daemon ranks them.
type Sticky ¶
type Sticky struct {
// App is the table key whose copies this policy may choose from.
App string `json:"app,omitempty"`
// Cookie names the cookie. It is unique per app port, so two apps on one
// host never overwrite each other's.
Cookie string `json:"cookie,omitempty"`
// Secret is the HMAC key of the cookie's value, which names a copy
// without giving its address away.
Secret string `json:"secret,omitempty"`
// FallbackRaw chooses among the copies of one role for a new visitor;
// least_conn when absent.
FallbackRaw json.RawMessage `json:"fallback,omitempty" caddy:"namespace=http.reverse_proxy.selection_policies inline_key=policy"`
// contains filtered or unexported fields
}
Sticky is the selection policy: it keeps a visitor on one copy with a cookie, and picks a copy for a visitor who has none (or whose copy is gone). Which copies exist, and their roles, come from the table.
func (*Sticky) CaddyModule ¶
func (*Sticky) CaddyModule() caddy.ModuleInfo
func (*Sticky) Select ¶
func (s *Sticky) Select(pool reverseproxy.UpstreamPool, req *http.Request, w http.ResponseWriter) *reverseproxy.Upstream
Select chooses the copy for req from pool, which is the table's list for the app. A copy is listed when it has a role, and up when the passive health checks have not marked it down. Four rules, tried in this order.
Own copy. The visitor stays on the copy its cookie names while that copy is listed and up, with no new cookie. The one exception is a page load (see pageLoad) of a copy that is draining: a visitor who reloads during a redeploy gets the new version, by the rules below.
Successor. If the cookie names a copy that has left the table, the copy that took its place serves the visitor while that is listed and up (see Set).
Candidates. Any other visitor gets a copy chosen now, and a cookie for it.
- Who is a candidate: the active copies that are up.
- Who stands in: for each active copy that is down, one warm copy that is up, in pool order. A visitor whose own copy is an active one that is down gets the spare standing in for it.
- How the fallback picks: its policy chooses among the candidates and the stand-ins. Only when none is up does it choose among the other warm copies, then among the draining ones; a draining copy gets no new visitor otherwise.
Last resort. Nothing is up: the visitor's own copy if it is listed, else the first listed one. A copy marked down is dialled anyway, so a lone copy that restarts is served as soon as R is back, not after the marks expire.