supervisor

package
v0.45.2 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package supervisor runs a candidate and reference service behind the SPECTRE proxies, sandboxing the candidate's egress and splitting host resources with cgroups.

Index

Constants

View Source
const SandboxArg = "__spectre_sandbox__"

SandboxArg is the first argument that re-execs the supervisor as the egress sandbox launcher for a child command.

Variables

This section is empty.

Functions

func ExecSandbox

func ExecSandbox(command []string) error

ExecSandbox installs the egress seccomp filter then replaces the process with command, so the filter guards it. It returns only when the filter or exec fails.

Types

type Config

type Config struct {
	// Candidate is the shell command for the sandboxed candidate service.
	Candidate string `required:"" help:"Shell command for the candidate service. $SPECTRE_LISTEN and $SPECTRE_EGRESS are exported to it."`
	// Reference is the shell command for the authoritative reference service.
	Reference string `required:"" help:"Shell command for the reference service. $SPECTRE_LISTEN and $SPECTRE_EGRESS are exported to it."`
	// CandidateProtocol is the protocol the ingress uses to reach the candidate.
	CandidateProtocol string `` /* 157-byte string literal not displayed */
	// ReferenceProtocol is the protocol the ingress uses to reach the reference.
	ReferenceProtocol string `` /* 157-byte string literal not displayed */
	// Reflection loads and compares both backends' descriptors via gRPC reflection.
	Reflection bool `` /* 179-byte string literal not displayed */
	// Listen is the public ingress address that clients send traffic to.
	Listen string `default:"127.0.0.1:50050" help:"Public ingress address: host:port, or unix:<path|@abstract> for a unix socket."`
	// SocketDir holds the unix sockets wiring the proxies to the services.
	SocketDir string `default:"dist/sockets" help:"Directory for the unix sockets wiring the proxies to the services."`
	// Destinations maps each request host to its upstream URL for egress.
	Destinations map[string]string `` /* 178-byte string literal not displayed */
	// ScriptsDir holds the comparison scripts passed to both proxies.
	ScriptsDir string `type:"existingdir" placeholder:"DIR" help:"Directory of comparison scripts passed to both proxies."`
	// StateFile is the migration state that decides which routes ingress mirrors.
	StateFile string `` /* 214-byte string literal not displayed */
	// SchemaDir holds the TypeScript schema passed to both proxies.
	SchemaDir string `type:"existingdir" placeholder:"DIR" help:"Directory of TypeScript schema passed to both proxies."`
	// MatchWindow bounds how long a candidate call waits for a matching reference call.
	MatchWindow time.Duration `default:"5s" help:"Maximum time a candidate egress call waits for an equivalent reference call before a 502."`
	// Descriptors supplies protobuf descriptors to both proxies.
	Descriptors descriptors.Config `embed:""`
	// Limits configures the cgroup resource split between the services.
	Limits LimitConfig `embed:""`
	// SeccompEgress blocks the candidate from opening IP sockets with seccomp,
	// so it can only reach dependencies through the egress proxy.
	SeccompEgress bool `` /* 179-byte string literal not displayed */
	// Server reports the mirror's quarantines to the SPECTRE server.
	Server reporter.Config `embed:""`
	// StartupTimeout bounds how long each process has to start listening.
	StartupTimeout time.Duration `default:"30s" help:"Maximum time for each process to begin accepting connections."`
	// ShutdownTimeout bounds graceful shutdown before processes are killed.
	ShutdownTimeout time.Duration `default:"10s" help:"Maximum time for processes to exit after a termination signal."`
}

Config contains the command-line configuration for the supervisor.

func NewConfig

func NewConfig() Config

NewConfig returns the default supervisor configuration.

func (Config) Validate

func (c Config) Validate() error

Validate checks that the ratios and timeouts are usable. The candidate and reference commands are enforced as required flags by Kong.

type LimitConfig

type LimitConfig struct {
	// Enabled applies the cgroup split; disable it where cgroups are unavailable.
	Enabled bool `name:"limits" negatable:"" default:"true" help:"Apply a cgroup v2 CPU and memory split to the services."`
	// Parent is the cgroup v2 path hosting the service cgroups.
	Parent string `` /* 167-byte string literal not displayed */
	// MemoryMax is the total memory in bytes split between the services.
	MemoryMax int64 `name:"memory-max" default:"0" help:"Total memory in bytes split between the services. 0 detects the system memory."`
	// CandidateCPUWeight is the candidate cpu.weight, 1-10000.
	CandidateCPUWeight uint `` /* 143-byte string literal not displayed */
	// ReferenceCPUWeight is the reference cpu.weight, 1-10000.
	ReferenceCPUWeight uint `name:"reference-cpu-weight" default:"100" help:"Reference cpu.weight (1-10000)."`
	// CandidateMemoryShare is the candidate share of the memory budget.
	CandidateMemoryShare uint `name:"candidate-memory-share" default:"1" help:"Candidate share of the memory budget, relative to the reference share."`
	// ReferenceMemoryShare is the reference share of the memory budget.
	ReferenceMemoryShare uint `name:"reference-memory-share" default:"1" help:"Reference share of the memory budget."`
}

LimitConfig contains the cgroup v2 resource split between the services.

func (LimitConfig) Validate

func (c LimitConfig) Validate() error

Validate checks that the cgroup weights and shares are usable.

type Supervisor

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

Supervisor runs the candidate and reference services behind the SPECTRE proxies, with the candidate's egress sandboxed and host resources split.

func New

func New(ctx context.Context, config Config, catalog *state.Catalog) (*Supervisor, error)

New validates config and returns a supervisor that logs to ctx's logger. The catalog checks the migration state, if config names one.

func (*Supervisor) Run

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

Run starts the proxies and services, then runs until the context is cancelled or a component exits, after which it stops the rest.

Jump to

Keyboard shortcuts

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