Documentation
¶
Overview ¶
Package hoststatus reads the state of the machine Core runs on: its network links, Bluetooth adapter, storage, displays and controllers, and asks the operating system to reboot, shut down or suspend it.
Every reader here is the generic one for its operating system. A platform that knows better supplies its own through the provider interfaces in the platforms package.
Index ¶
- Constants
- Variables
- func BatteryLevel(percent int) string
- func ConnectorName(entry string) (string, bool)
- func FilesystemID(path string) (id, mountPoint string, err error)
- func MountSource(mountInfo, path string) (source, mountPoint string, ok bool)
- func ParseDefaultRouteInterface(routes string) string
- func ParseHardwarePorts(output string) map[string]LinkType
- func ParseRouteDefaultInterface(output string) string
- type Availability
- type Bluetooth
- type Connector
- type Controller
- type ControllerBattery
- type DefaultOptions
- type DiskUsage
- type Display
- type ExecPowerControl
- type InputModalias
- type Interface
- type InternetState
- type LinkType
- type LinuxBluetooth
- type LinuxControllers
- type LinuxDisplay
- type LinuxNetwork
- type LinuxPowerControl
- type LinuxSystem
- type Network
- type NoPowerControl
- type PowerAction
- type PowerController
- type Prober
- type RawInterface
- type Readers
- type StorageReader
- type StorageRoot
- type System
- type Volume
Constants ¶
const ( RoleMedia = "media" RoleData = "data" )
const ( ConnectionUSB = "usb" ConnectionBluetooth = "bluetooth" ConnectionUnknown = "unknown" )
const ( BatteryLevelEmpty = "empty" BatteryLevelLow = "low" BatteryLevelMedium = "medium" BatteryLevelFull = "full" )
Variables ¶
var ( // ErrUnsupported means the platform has no way to answer at all. ErrUnsupported = errors.New("not supported on this platform") // ErrNotPermitted means the platform could act but the operating system // refuses this process. ErrNotPermitted = errors.New("not permitted by the operating system") )
var DefaultConnectivityURLs = []string{
"http://connectivitycheck.gstatic.com/generate_204",
"http://cp.cloudflare.com/generate_204",
"http://edge-http.microsoft.com/captiveportal/generate_204",
}
DefaultConnectivityURLs are plain-HTTP endpoints that answer 204 with no body. They are run by different operators so that one being blocked on a network does not read as the internet being down. Plain HTTP is deliberate: it is what lets a captive portal answer in the internet's place and be recognised.
var PowerActions = []PowerAction{PowerReboot, PowerShutdown, PowerSuspend}
PowerActions lists every action in a stable order.
Functions ¶
func BatteryLevel ¶
BatteryLevel names the coarse level a charge percentage falls in.
func ConnectorName ¶
ConnectorName returns the connector half of a /sys/class/drm entry named "card<N>-<connector>".
func FilesystemID ¶
FilesystemID identifies the filesystem holding path, so two directories on the same one are counted once, and reports where it is mounted.
The device number alone is not enough: every subvolume of a btrfs filesystem has its own, though they all share one pool of space. Where the mount is backed by a block device or a network share, that is the identity.
func MountSource ¶
MountSource returns what is mounted at the deepest mount point holding path, and that mount point, from the contents of /proc/self/mountinfo. The source is a block device or a network share for a mount that has one behind it; for a mount such as tmpfs it names a kind of filesystem and not one instance of it.
func ParseDefaultRouteInterface ¶
ParseDefaultRouteInterface returns the interface carrying the default route with the lowest metric from the contents of /proc/net/route, or "" when there is none.
func ParseHardwarePorts ¶
ParseHardwarePorts reads the kind of link behind each device from the output of `networksetup -listallhardwareports`.
func ParseRouteDefaultInterface ¶
ParseRouteDefaultInterface reads the interface from the output of `route -n get default`.
Types ¶
type Availability ¶
type Availability string
Availability is whether a section or an action can be used on this device.
const ( Unsupported Availability = "unsupported" Supported Availability = "supported" NotPermitted Availability = "notPermitted" )
type Bluetooth ¶
type Bluetooth struct {
// Powered is nil when the adapter's power state cannot be read.
Powered *bool
Present bool
}
Bluetooth is the adapter's state. Core only ever reads it.
type Controller ¶
type Controller struct {
Battery *ControllerBattery
// ID identifies the controller only for as long as it stays connected.
ID string
Name string
// VendorID and ProductID are four lowercase hex digits, or empty.
VendorID string
ProductID string
Connection string
}
Controller is one physical game controller.
type ControllerBattery ¶
type ControllerBattery struct {
// Percent is nil when the hardware reports only a coarse level.
Percent *int
Level string
}
ControllerBattery is a controller's own battery.
type DefaultOptions ¶
type DefaultOptions struct {
Executor command.Executor
// VirtualGamepadSlots returns the controller slots held by gamepads Core
// itself created, on systems that number controllers. May be nil.
VirtualGamepadSlots func() []int
// VirtualInputName is the name of the input device Core creates, which
// must never be reported as a controller.
VirtualInputName string
}
DefaultOptions is what the generic readers need to know about Core itself.
type DiskUsage ¶
type DiskUsage struct {
Total uint64
// Free is every unallocated byte; Available is the part of it the calling
// user may use.
Free uint64
Available uint64
}
DiskUsage is the size of a filesystem and how much of it is free.
func DiskUsageOf ¶
DiskUsageOf reports the size of the filesystem holding path.
type Display ¶
type Display struct {
// Docked is nil on a device with no built-in panel, where the question
// has no meaning.
Docked *bool
InternalPanel bool
InternalActive bool
ExternalConnected bool
ExternalActive bool
}
Display is what the device is showing its picture on.
func ClassifyDisplay ¶
ClassifyDisplay turns a set of connectors into the facts a client lays its interface out from. A device with a built-in panel is docked while an external display is being driven.
type ExecPowerControl ¶
type ExecPowerControl struct {
Executor command.Executor
// Commands maps each action the device supports to the program and
// arguments that perform it.
Commands map[PowerAction][]string
// Permitted reports whether this process may run the commands. Nil means
// it always may.
Permitted func() bool
}
ExecPowerControl carries out power actions by running a command, for systems where that is the interface the operating system offers.
func (*ExecPowerControl) PowerActions ¶
func (c *ExecPowerControl) PowerActions(context.Context) map[PowerAction]Availability
func (*ExecPowerControl) PreparePowerAction ¶
func (c *ExecPowerControl) PreparePowerAction(_ context.Context, action PowerAction) (func() error, error)
type InputModalias ¶
InputModalias is the identity an input device announces in its sysfs modalias.
func ParseInputModalias ¶
func ParseInputModalias(alias string) (InputModalias, bool)
ParseInputModalias reads an input device modalias of the form "input:b0005v054Cp0CE6e8100-e0,1,3,k130,131,ra0,1,mlsfw". The key list is read from here rather than from capabilities/key because that bitmap's word width depends on the architecture.
func (InputModalias) Connection ¶
func (m InputModalias) Connection() string
Connection names how the device is attached.
func (InputModalias) IsGamepad ¶
func (m InputModalias) IsGamepad() bool
IsGamepad reports whether the device has controller buttons and is not a keyboard that happens to expose a few of them.
type Interface ¶
type Interface struct {
Name string
Type LinkType
// Addresses excludes loopback and link-local addresses.
Addresses []string
Up bool
}
Interface is one network link.
type InternetState ¶
type InternetState string
InternetState is how far beyond the local network the device can reach. The empty value means it has not been determined.
const ( InternetFull InternetState = "full" // InternetPortal means something answered in place of the internet, as a // hotel or cafe sign-in page does. InternetPortal InternetState = "portal" InternetNone InternetState = "none" )
type LinuxBluetooth ¶
LinuxBluetooth reads the adapter's state. It never changes it.
func (*LinuxBluetooth) Read ¶
func (r *LinuxBluetooth) Read() (Bluetooth, error)
Read reports whether an adapter exists and, where that can be learned without disturbing it, whether it is powered.
type LinuxControllers ¶
type LinuxControllers struct {
Fs afero.Fs
// Resolve returns the real device path behind a sysfs class entry.
Resolve func(path string) (string, error)
InputRoot string
PowerRoot string
VirtualName string
}
LinuxControllers lists physical game controllers from the kernel's input class.
func (*LinuxControllers) Read ¶
func (r *LinuxControllers) Read() ([]Controller, error)
Read reports connected controllers. Devices created in software are left out, which covers Core's own virtual gamepad and the ones a game launcher presents in place of the real hardware.
type LinuxDisplay ¶
LinuxDisplay reads display outputs from the kernel's DRM class.
func (*LinuxDisplay) Read ¶
func (r *LinuxDisplay) Read() (Display, error)
Read reports which outputs are connected and driven.
type LinuxNetwork ¶
type LinuxNetwork struct {
Fs afero.Fs
Interfaces func() ([]RawInterface, error)
ProcRoute string
SysNet string
// contains filtered or unexported fields
}
LinuxNetwork reads links from sysfs and the routing table from procfs.
func (*LinuxNetwork) Read ¶
func (r *LinuxNetwork) Read() (Network, error)
Read reports the device's links and which one carries the default route.
type LinuxPowerControl ¶
type LinuxPowerControl struct {
Fallback PowerController
// contains filtered or unexported fields
}
LinuxPowerControl asks the login manager to change the machine's power state, which is what lets an unprivileged service do it where the distribution's policy allows. Systems without a login manager fall back to running the commands directly.
func NewLinuxPowerControl ¶
func NewLinuxPowerControl( executor command.Executor, lookPath func(string) (string, error), euid func() int, ) *LinuxPowerControl
NewLinuxPowerControl returns a controller that runs reboot and poweroff as the fallback. lookPath finds a program, and euid is the effective user ID.
func (*LinuxPowerControl) PowerActions ¶
func (c *LinuxPowerControl) PowerActions(ctx context.Context) map[PowerAction]Availability
func (*LinuxPowerControl) PreparePowerAction ¶
func (c *LinuxPowerControl) PreparePowerAction(ctx context.Context, action PowerAction) (func() error, error)
type LinuxSystem ¶
LinuxSystem reads what the machine calls itself.
func (*LinuxSystem) Read ¶
func (r *LinuxSystem) Read() (System, error)
Read reports the hostname and hardware model.
type Network ¶
type Network struct {
// Type and Interface describe the link holding the default route.
Type LinkType
Interface string
// Internet is filled in by the reader only when InternetAuthoritative is
// set; otherwise the caller decides it by probing.
Internet InternetState
Interfaces []Interface
// InternetAuthoritative means the operating system or the embedding host
// already checks reachability and Internet is its answer.
InternetAuthoritative bool
}
Network is the device's links and which of them carries its traffic.
type NoPowerControl ¶
type NoPowerControl struct{}
NoPowerControl is the controller for a device that supports no power action.
func (NoPowerControl) PowerActions ¶
func (NoPowerControl) PowerActions(context.Context) map[PowerAction]Availability
func (NoPowerControl) PreparePowerAction ¶
func (NoPowerControl) PreparePowerAction(context.Context, PowerAction) (func() error, error)
type PowerAction ¶
type PowerAction string
PowerAction is a request to change the machine's power state.
const ( PowerReboot PowerAction = "reboot" PowerShutdown PowerAction = "shutdown" PowerSuspend PowerAction = "suspend" )
type PowerController ¶
type PowerController interface {
// PowerActions reports which actions this device can carry out for this
// process. An action missing from the map is unsupported.
PowerActions(ctx context.Context) map[PowerAction]Availability
// PreparePowerAction checks that the action can go ahead and returns the
// function that performs it. Refusals are reported here, with
// ErrUnsupported or ErrNotPermitted, because by the time commit runs the
// caller has already been answered.
PreparePowerAction(ctx context.Context, action PowerAction) (commit func() error, err error)
}
PowerController carries out power actions.
type Prober ¶
type Prober struct {
// contains filtered or unexported fields
}
Prober decides whether the device can reach the internet by asking known endpoints for an answer nothing else would give.
type RawInterface ¶
RawInterface is a network interface as the operating system lists it, before Core decides what kind of link it is.
func ListRawInterfaces ¶
func ListRawInterfaces() ([]RawInterface, error)
ListRawInterfaces lists the machine's interfaces and their addresses.
type Readers ¶
type Readers struct {
Power func() (power.Detail, error)
Network func() (Network, error)
Bluetooth func() (Bluetooth, error)
Storage func(roots []StorageRoot) ([]Volume, error)
Display func() (Display, error)
Controllers func() ([]Controller, error)
System func() (System, error)
PowerControl PowerController
}
Readers is one reader per section. A nil reader, or one returning ErrUnsupported, means the device does not have that section.
func NewDefaults ¶
func NewDefaults(opts DefaultOptions) Readers
NewDefaults returns the generic readers for Linux.
type StorageReader ¶
type StorageReader struct {
Usage func(path string) (DiskUsage, error)
// FilesystemID returns the filesystem's identity and, where it is known,
// its mount point.
FilesystemID func(path string) (id, mountPoint string, err error)
// IsEmpty reports whether a directory holds nothing. It is optional.
IsEmpty func(path string) bool
// Resolve follows the symlinks in a path, as FilesystemID does before it
// names a mount point. It is optional.
Resolve func(path string) (string, error)
}
StorageReader reports the filesystems a set of directories live on.
func NewStorageReader ¶
func NewStorageReader() *StorageReader
NewStorageReader returns a reader over the real filesystem.
func (*StorageReader) Read ¶
func (r *StorageReader) Read(roots []StorageRoot) ([]Volume, error)
Read returns one volume per distinct filesystem, in the order its first root was given, named by its mount point where that is known. A root that cannot be read, such as a share that is not mounted, is left out.
type StorageRoot ¶
StorageRoot is a directory whose filesystem should be reported.
type Volume ¶
type Volume struct {
// Path is where the filesystem is mounted, or the first root found on it
// when that is not known.
Path string
Roles []string
Total uint64
// Free is the space available to the user Core runs as.
Free uint64
Used uint64
}
Volume is one filesystem holding at least one storage root.