lb

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 29, 2026 License: MIT Imports: 19 Imported by: 0

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

View Source
const AdminPath = "/shinyctl/copies"

AdminPath is the control-socket route the table is read and replaced through.

View Source
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

func LoadFile(path string) error

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.

func Validate

func Validate(t Table) error

Validate checks a table that comes from outside: every dial must be a host:port, and none may be listed twice in one pool.

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

func (c *Copies) GetUpstreams(*http.Request) ([]*reverseproxy.Upstream, error)

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

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) Provision

func (s *Sticky) Provision(ctx caddy.Context) error

func (*Sticky) Select

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.

type Table

type Table map[string]Pool

Table is every app's pool, keyed by the app's key: its state file, which is also the server's name in the settings.

func Current

func Current() Table

Current returns a copy of the table.

func (Table) Clone

func (t Table) Clone() Table

Clone returns a copy of t that shares nothing with it.

func (Table) Equal

func (t Table) Equal(u Table) bool

Equal reports whether t and u have the same apps with the same lists in the same order. A nil list and an empty one are equal.

Jump to

Keyboard shortcuts

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