proxy

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: 36 Imported by: 0

Documentation

Overview

Package proxy is shinyctl's built-in load balancer: the settings shinyctl-api renders for it, the hidden process that runs it, and the supervision that keeps that process up.

It embeds an HTTP server library as the engine and configures it only through JSON documents (see Render), so nothing outside this package needs to know which engine it is.

Index

Constants

View Source
const DefaultTryDuration = 15 * time.Second

DefaultTryDuration is long enough to cover an R process starting up, and short enough that a visitor to an app that is not coming back sees the restarting page rather than a hung tab.

Variables

View Source
var (
	// ErrNotRunning is what reaching for a load balancer that isn't
	// listening on its control socket comes to.
	ErrNotRunning = errors.New("the load balancer is not running; shinyctl-api is restarting it (see shinyctl logs --api)")
)

Functions

func BuildID

func BuildID() string

BuildID identifies the executable this process runs from: its size and modification time. A proxy records it in its lock, and shinyctl-api replaces a proxy whose build differs from its own, so an upgraded shinyctl doesn't leave the previous release's load balancer running.

func CanonicalHost

func CanonicalHost(host string) string

CanonicalHost writes an IP address the way the OS and the load balancer name it: "::ffff:127.0.0.1" is "127.0.0.1" and "0:0:0:0:0:0:0:1" is "::1". A bind error names the canonical form, so addresses are compared and printed in it. Anything that isn't an IP address is returned as is.

func CookieName

func CookieName(port int) string

CookieName is the name of the cookie that keeps a visitor on one copy of the app on port. It is unique per port, so apps on one host don't overwrite each other's, and says nothing about what sets it.

func HandoverWait

func HandoverWait() time.Duration

HandoverWait is how long a handover may take, for callers that wait for it.

func LoadSecret

func LoadSecret(dir string) (string, error)

LoadSecret returns the key of the cookies that keep visitors on their copy: the contents of dir/secret, created with 32 random bytes (64 hex characters, mode 0600) when the file is missing. One key serves the whole installation. A file that can't be read, or doesn't hold a key, is not a reason for shinyctl-api to stay down: it is replaced, atomically, and the only cost is that every visitor is placed on a copy once more.

func LockPath

func LockPath(configPath string) string

LockPath is the proxy.lock beside configPath. The proxy holds an exclusive flock on it for as long as it runs, so the lock is also the answer to "is a load balancer running": the kernel drops it on any exit, kill -9 included, so it can't go stale the way a pid file does.

It is what keeps a second proxy out. The engine unlinks a stale control socket by itself and shares listening ports through SO_REUSEPORT, so without the lock a second instance would start, take the socket over and split the traffic. Deleting ~/.shinyctl/proxy under a running proxy defeats it, and isn't supported.

func PortUsedBy

func PortUsedBy(app, holder App) error

PortUsedBy is the error for an app whose address overlaps the one holder already has.

func Render

func Render(s Settings, apps []App) ([]byte, error)

Render returns the load balancer's whole config for apps: one server per app, listening on the app's own port and forwarding to its copies. It is pure and deterministic, so a changed config is a changed document and an unchanged one can be told apart from it. With no apps it returns the bootstrap, which has no "apps" key at all.

What each part is for:

  • stream_close_delay keeps open WebSockets (the Shiny sessions) alive across a config reload, which would otherwise close them.
  • the copies come from the copies table (dynamic_upstreams), not from the settings, so a copy that dies, a spare that takes over and a scale change take effect without a reload; a reload binds every listener again and drops the connections that arrive meanwhile.
  • the selection policy keeps each visitor on one copy with a cookie (see CookieName), and sends new visitors to the active copies; a warm copy takes visitors only as the stand-in for an active copy that is down, and a visitor of a copy that has just left the table goes to the copy that took its place.
  • try_duration and try_interval make a request wait for an app that is restarting.
  • passive health checks are a backstop for a copy that died before the table says so: one failed dial marks it down for two seconds and the visitor moves on within a try_interval. The policy dials a copy that is marked down when nothing else is up, so a lone copy that restarts is not held back for those two seconds.
  • trusted_proxies makes the load balancer extend the X-Forwarded-* headers of a front proxy on this machine (nginx terminating TLS, say) instead of replacing them, so the app still sees the visitor's address and scheme. Only loopback is trusted: anyone else's are overwritten, as before.
  • the deferred headers handler removes Server and Via from the response (the engine sets both after the route's own header operations have run, and again on a WebSocket's 101), and the request-side delete keeps Via from reaching the app.
  • the errors routes strip the same headers, which the errors chain doesn't pass through the deferred handler for, and turn 502 and 503 into a restarting page that reloads itself.

func Run

func Run(configPath string, after int) error

Run is the proxy process: it takes the lock, loads the config at configPath, and serves until SIGTERM or SIGINT. It never touches HOME: the engine's own autosave is off, its TLS app is told not to keep housekeeping files, and its storage root is inside the proxy directory (all in the rendered config).

The copies table is read from copies.json next to the config before anything is loaded.

With after set to the pid of the load balancer that holds the lock, this one is replacing it: it loads its settings and serves every port next to it (both listen with SO_REUSEPORT), says so on the control socket (lb.MarkServing), waits handoverGrace, and then stops the old one itself: SIGTERM, and SIGKILL if it still holds the lock after the usual grace period, but only while it is the lock holder and a load balancer for this same config. Then it takes the lock. shinyctl-api only starts it and watches, so the handover finishes even if shinyctl-api dies in the middle. If it can't load, it exits and leaves the old one serving, instead of serving nothing next to it; if the lock never comes, or another load balancer took the old one's place first, it stops serving and exits.

If configPath can't be used (a port taken since it was written, invalid JSON, paths that name another directory after the home directory moved) it serves with no apps instead of exiting, so the control socket still answers and shinyctl-api can push a working config. That fallback is built from the proxy's own directory, never from the file, and so are the control socket, logging and storage of a file that does load: a config.json copied from another directory (or left by a home that was renamed) must not move the control socket somewhere the supervisor doesn't look, or onto another instance's.

func Validate

func Validate(cfg []byte) error

Validate checks cfg the way the load balancer would when loading it — every module found and provisioned — without starting anything or touching the running one. It catches a config shinyctl rendered wrongly before it is sent. The engine says in JSON, on standard error, that it has redirected its log when it provisions the logging of cfg; plainStderr makes that a plain line (or nothing) in api.log.

Types

type Admin

type Admin struct {
	Socket string
}

Admin talks to the load balancer's control socket.

func (Admin) Config

func (a Admin) Config() ([]byte, error)

Config returns the settings the load balancer is serving, exactly as they were last loaded.

func (Admin) Copies

func (a Admin) Copies() (Table, error)

Copies returns the copies table the load balancer is serving from.

func (Admin) Load

func (a Admin) Load(cfg []byte) error

Load replaces the load balancer's settings with cfg. The old settings keep serving if the new ones are rejected. A port that can't be bound comes back as a *BindError; any other rejection is logged in full and returned as errRejected.

func (Admin) Ping

func (a Admin) Ping() error

Ping reports whether the load balancer answers on its control socket.

func (Admin) PutCopies

func (a Admin) PutCopies(t Table) error

PutCopies replaces the load balancer's copies table with t. Nothing is reloaded: the next request sees the new roles.

func (Admin) ServingPID

func (a Admin) ServingPID() (int, error)

ServingPID is the process that answers on the control socket, once it serves its settings; 0 from one that doesn't say.

func (Admin) Upstreams

func (a Admin) Upstreams() (map[string]int, error)

Upstreams returns, for each copy address the load balancer has dialled, the number of requests open to it now. The engine lists an address with requests in flight twice, once from its in-flight counts and once from its host table, so the largest count per address is taken, not the sum.

type App

type App struct {
	Key      string // the app's state file; also the server's name in the config
	Name     string // app-name, for messages
	Group    string // app-group, for messages
	Host     string // EffectiveHost
	Port     int    // the manifest's port
	LBPolicy string // the manifest's lb-policy: how a new visitor picks a copy; "" means least-conn
}

App is one app as the load balancer serves it.

func Parse

func Parse(cfg []byte) ([]App, error)

Parse reads back the apps a config serves: the inverse of Render for what shinyctl-api needs to know about a load balancer it didn't start, or has restarted: each server's key, host and port. Name, Group and LBPolicy are not read and stay empty. A config of any other shape is an error, so the caller reloads instead of trusting it. A config from a build before the copies table (its servers list their copies themselves) reads the same as a current one, and differs from what Render makes now, so the next sync replaces it.

func Plan

func Plan(apps, loaded []App) (keep []App, left map[string]error)

Plan decides which of apps the load balancer can serve at once. The engine rejects a whole config that listens twice on one address, and an overlap such as 0.0.0.0:P with 127.0.0.1:P would otherwise bind both through SO_REUSEPORT and split the traffic, so the later claimant is left out and told why. Apps already served at the same address (loaded) are considered first, so a new app never takes a port from a running one; within each group the lower Key wins. keep is sorted by Key.

func (App) Addr

func (a App) Addr() string

Addr is the address the load balancer listens on for a, in canonical form.

func (App) Overlaps

func (a App) Overlaps(b App) bool

Overlaps reports whether a and b would compete for the same port: the same port in the same family, on the same host or with either one on the family's wildcard address.

type BindError

type BindError struct {
	Addr string // host:port
	Err  string // the OS error, e.g. "listen tcp4 127.0.0.1:9000: bind: address already in use"
}

BindError is a rejected load because an address couldn't be listened on. Its text is process.PortAvailable's, so an app's port reads the same whichever check caught it.

func (*BindError) Error

func (e *BindError) Error() string

type Gateway

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

Gateway pushes the set of apps to the running load balancer, and knows what it is serving. Changes go through a check and a reload; a rejected reload leaves the previous settings serving. Which copies of each app serve is a separate matter, the pools: they change much more often, and are sent as a table that replaces the previous one without a reload.

func NewGateway

func NewGateway(s Settings, sup *Supervisor) *Gateway

NewGateway returns a Gateway for the load balancer sup supervises.

func (*Gateway) BalancerPID

func (g *Gateway) BalancerPID() int

BalancerPID is the load balancer's process ID, or 0.

func (*Gateway) Listed

func (g *Gateway) Listed() Table

Listed returns the copies table the load balancer itself holds, which for a load balancer adopted from an earlier shinyctl-api is what that one last sent; nil when it can't be asked.

func (*Gateway) NotServed

func (g *Gateway) NotServed(key string) string

NotServed says why the load balancer leaves the app at key out, from the last Sync, or "" when it doesn't.

func (*Gateway) Pool

func (g *Gateway) Pool(key string) (Pool, bool)

Pool returns the copies recorded for app key.

func (*Gateway) PoolSeq

func (g *Gateway) PoolSeq() uint64

PoolSeq numbers the latest SetPool; ReplacePools takes it as the moment its table was made.

func (*Gateway) Pushes

func (g *Gateway) Pushes() int

Pushes is the number of tables the load balancer has taken, for tests.

func (*Gateway) Reloads

func (g *Gateway) Reloads() int

Reloads is the number of successful reloads so far, for tests.

func (*Gateway) ReplacePools

func (g *Gateway) ReplacePools(t Table, since uint64) error

ReplacePools makes t the pools, for a table rebuilt from the state files: when the daemon starts, and when a load balancer comes up. Apps whose pool was set after since (a PoolSeq taken before t was built) keep it, because whoever set it saw something newer than t; apps not in t are dropped unless they are newer too.

func (*Gateway) Served

func (g *Gateway) Served() []App

Served returns the apps the load balancer serves right now.

func (*Gateway) Serves

func (g *Gateway) Serves(key, host string, port int) bool

Serves reports whether the load balancer is running and serves the app at key on host:port.

func (*Gateway) Sessions

func (g *Gateway) Sessions() map[string]int

Sessions returns the number of requests open to each copy, by its address, or nil when the load balancer can't say. It takes neither of the gateway's locks, so a status query never waits on a reload.

func (*Gateway) SetPool

func (g *Gateway) SetPool(key string, p Pool) error

SetPool records the copies that serve app key and sends the table to the load balancer at once. The error says the load balancer did not take it (it is not running, or refused it); the pool is kept and sent again with the next change or when the load balancer comes back, so callers log it and carry on.

func (*Gateway) Starting

func (g *Gateway) Starting() bool

Starting reports that the load balancer is being started or replaced and is not answering yet.

func (*Gateway) Sync

func (g *Gateway) Sync(apps []App) (left map[string]error, err error)

Sync makes the load balancer serve apps. Apps whose address overlaps another's, or can't be bound, are left out and returned in left with the reason; they don't hold up the others. Nothing is reloaded when the settings it would send equal the ones it already has.

func (*Gateway) WaitWhileStarting

func (g *Gateway) WaitWhileStarting(timeout time.Duration) bool

WaitWhileStarting waits while the load balancer is being started or replaced, up to timeout, and reports whether it is running when the wait ends. It ends when the supervisor's attempt does, whether that worked or failed: a load balancer that cannot start is not waited for to the end of the timeout.

type Pool

type Pool = lb.Pool

Pool and Table are the copies table's types (see package lb), so the rest of shinyctl names them without importing it.

type Settings

type Settings struct {
	ConfigPath  string // loaded by the proxy at start; written after each successful load
	AdminSocket string // the proxy's control socket
	StorageDir  string // the engine's storage root, kept here so nothing lands in its default directories
	CopiesPath  string // the copies table, written by shinyctl-api after each update and read by the proxy at start

	// Secret is the key of the cookies that keep a visitor on one copy. It
	// must not be empty when apps are rendered; LoadSecret supplies it.
	Secret string

	// TryDuration is how long a request waits for an app that isn't
	// answering before the visitor gets the restarting page. Zero means
	// DefaultTryDuration.
	TryDuration time.Duration
}

Settings says where the load balancer keeps its files and how patient it is with an app that is down.

func SettingsFor

func SettingsFor(dir string) Settings

SettingsFor returns the settings for a load balancer living in dir (~/.shinyctl/proxy).

type Supervisor

type Supervisor struct {
	Settings Settings
	Exe      string // the shinyctl binary to start as `proxy --config`
	Build    string // BuildID of Exe
	LogPath  string // the proxy's stdout and stderr (api.log)

	// OnReady is called, with no lock held, each time the load balancer
	// becomes available (started or adopted), so shinyctl-api can bring it
	// up to date.
	OnReady func()

	// OnHandedOver is called, with no lock held, when the load balancer that
	// has just become available took over from another that was running (a
	// handover between builds), so shinyctl-api can act on what it had to
	// wait for at once and not at its next tick.
	OnHandedOver func()
	// contains filtered or unexported fields
}

Supervisor keeps the load balancer's process running for shinyctl-api: it starts it, adopts one a previous shinyctl-api left running, and starts it again when it dies. It never stops it on its own shutdown: the apps stay reachable while shinyctl-api is down or restarting, and the next shinyctl-api adopts the process.

func (*Supervisor) Expect

func (s *Supervisor) Expect()

Expect says a load balancer is about to be started, before Run has got as far as saying so itself.

func (*Supervisor) Generation

func (s *Supervisor) Generation() int

Generation counts how many times the load balancer has become available, so a caller can tell that it is not the process it last talked to.

func (*Supervisor) PID

func (s *Supervisor) PID() int

PID is the running load balancer's pid, or 0.

func (*Supervisor) Run

func (s *Supervisor) Run(ctx context.Context)

Run supervises until ctx is done, which it does without touching the proxy.

func (*Supervisor) Running

func (s *Supervisor) Running() bool

Running reports whether the load balancer is up.

func (*Supervisor) Starting

func (s *Supervisor) Starting() bool

Starting reports that the load balancer is being started, or replaced by one of another build: not running yet, but on its way.

func (*Supervisor) Stop

func (s *Supervisor) Stop() error

Stop ends the current load balancer and waits until it is gone. shinyctl never calls it; tests do, after cancelling Run, so no process outlives them.

func (*Supervisor) WaitReady

func (s *Supervisor) WaitReady(timeout time.Duration) bool

WaitReady blocks until the load balancer is running, or timeout passes.

type Table

type Table = lb.Table

Pool and Table are the copies table's types (see package lb), so the rest of shinyctl names them without importing it.

Directories

Path Synopsis
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.
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.

Jump to

Keyboard shortcuts

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