supervisor

Documentation

Overview

Package supervisor defines the capability boundary between reconciliation and target-provided process supervisors. Capabilities are explicit; an adapter never infers safe control from observation alone.

Index

• Variables
• type Adapter
• type Capabilities
• type CommandRunner
  • func (CommandRunner) Run(ctx context.Context, name string, args ...string) ([]byte, error)
• type FiveMHTTPPlayerCount
  • func (o FiveMHTTPPlayerCount) ObservePlayerCount(ctx context.Context) (int, error)
• type Manual
  • func (m Manual) Capabilities() Capabilities
  • func (Manual) Name() string
  • func (m Manual) Observe(ctx context.Context) (Observation, error)
  • func (Manual) ReloadResources(context.Context, []string) error
  • func (Manual) Restart(context.Context) error
• type Observation
• type PlayerCountObserver
• type Runner
• type Systemd
  • func (Systemd) Capabilities() Capabilities
  • func (Systemd) Name() string
  • func (s Systemd) Observe(ctx context.Context) (Observation, error)
  • func (Systemd) ReloadResources(context.Context, []string) error
  • func (s Systemd) Restart(ctx context.Context) error
• type TxAdmin
  • func NewTxAdmin(evidence TxAdminEvidence, transport TxAdminTransport) (*TxAdmin, error)
  • func (t *TxAdmin) Capabilities() Capabilities
  • func (*TxAdmin) Name() string
  • func (t *TxAdmin) Observe(ctx context.Context) (Observation, error)
  • func (t *TxAdmin) ReloadResources(ctx context.Context, names []string) error
  • func (t *TxAdmin) Restart(ctx context.Context) error
• type TxAdminEvidence
  • func (e TxAdminEvidence) Missing() []string
• type TxAdminTransport

Variables

var (
	ErrUnsupported = errors.New("supervisor: capability unsupported")
	ErrLabGate     = errors.New("supervisor: txadmin lab evidence incomplete")
)

var RequiredTxAdminExperiments = []string{"E1", "E2", "E3", "E4", "E5", "E6", "E7", "E8", "E9", "E10", "E11", "E13", "E14"}

RequiredTxAdminExperiments are the binary live-lab gates from the Stage 4 compatibility matrix. An adapter cannot be constructed until every enabled mechanism has affirmative evidence.

Types

type Adapter

type Adapter interface {
	Name() string
	Capabilities() Capabilities
	Observe(context.Context) (Observation, error)
	Restart(context.Context) error
	ReloadResources(context.Context, []string) error
}

type Capabilities

type Capabilities struct {
	Observe         bool
	Restart         bool
	HotReload       bool
	PlayerCount     bool
	ProcessIdentity bool
}

type CommandRunner

type CommandRunner struct{}

CommandRunner executes an exact argv without a shell. It is the production process boundary used by the systemd adapter; tests can replace Runner with a deterministic fake.

func (CommandRunner) Run

func (CommandRunner) Run(ctx context.Context, name string, args ...string) ([]byte, error)

type FiveMHTTPPlayerCount

type FiveMHTTPPlayerCount struct {
	Endpoint     *domain.RCONEndpointRef
	Client       *http.Client
	MaxBodyBytes int64
}

FiveMHTTPPlayerCount reads the non-credentialed /dynamic.json endpoint bound by the target administrator. It neither discovers nor follows another host.

func (FiveMHTTPPlayerCount) ObservePlayerCount

func (o FiveMHTTPPlayerCount) ObservePlayerCount(ctx context.Context) (int, error)

type Manual

type Manual struct {
	ObserveFunc func(context.Context) (Observation, error)
}

Manual is observe-only when ObserveFunc is supplied and otherwise has no capabilities. It never pretends an operator-managed process can be safely restarted by FXVCS.

func (Manual) Capabilities

func (m Manual) Capabilities() Capabilities

func (Manual) Name

func (Manual) Name() string

func (Manual) Observe

func (m Manual) Observe(ctx context.Context) (Observation, error)

func (Manual) ReloadResources

func (Manual) ReloadResources(context.Context, []string) error

func (Manual) Restart

func (Manual) Restart(context.Context) error

type Observation

type Observation struct {
	Running           bool
	ProcessGeneration string
	PlayerCount       *int
	SupervisorVersion string
	EvidenceSource    string
}

type PlayerCountObserver

type PlayerCountObserver interface {
	ObservePlayerCount(context.Context) (int, error)
}

PlayerCountObserver obtains a live player count without lifecycle authority.

type Runner

type Runner interface {
	Run(context.Context, string, ...string) ([]byte, error)
}

Runner is an argv-based process boundary; implementations must not invoke a shell. Tests and SDK hosts can inject it without parsing human CLI output in the reconciliation engine.

type Systemd

type Systemd struct {
	Unit   string
	Runner Runner
}

func (Systemd) Capabilities

func (Systemd) Capabilities() Capabilities

func (Systemd) Name

func (Systemd) Name() string

func (Systemd) Observe

func (s Systemd) Observe(ctx context.Context) (Observation, error)

func (Systemd) ReloadResources

func (Systemd) ReloadResources(context.Context, []string) error

func (Systemd) Restart

func (s Systemd) Restart(ctx context.Context) error

type TxAdmin

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

func NewTxAdmin

func NewTxAdmin(evidence TxAdminEvidence, transport TxAdminTransport) (*TxAdmin, error)

func (*TxAdmin) Capabilities

func (t *TxAdmin) Capabilities() Capabilities

func (*TxAdmin) Name

func (*TxAdmin) Name() string

func (*TxAdmin) Observe

func (t *TxAdmin) Observe(ctx context.Context) (Observation, error)

func (*TxAdmin) ReloadResources

func (t *TxAdmin) ReloadResources(ctx context.Context, names []string) error

func (*TxAdmin) Restart

func (t *TxAdmin) Restart(ctx context.Context) error

type TxAdminEvidence

type TxAdminEvidence struct {
	Passed map[string]bool
}

func (TxAdminEvidence) Missing

func (e TxAdminEvidence) Missing() []string

type TxAdminTransport

type TxAdminTransport interface {
	Observe(context.Context) (Observation, error)
	Restart(context.Context) error
	ReloadResources(context.Context, []string) error
	Capabilities() Capabilities
}

TxAdminTransport is intentionally typed rather than an HTTP/browser API. The eventual implementation must be backed only by mechanisms proven in the lab matrix; browser sessions and CSRF automation are outside this boundary.