Documentation
¶
Overview ¶
Package capability is the draft data model for what an agent machine does (its capabilities) and what it may reach or use (its permissions), with the defaults of each preset (compute, backup, gateway, development) and the rules for overriding them per machine. Issues #169 (capabilities), #170 (permissions) and #168 (the development preset) design it; the intended use is described in docs/node-types.md once that page is merged.
It does not touch the database, the protocol, the HTTP API or any running code: nothing calls it yet, and no decision recorded in docs/decisions.md depends on it. These are not the user permissions of internal/auth (what a person may do on the hub). Names are provisional.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrUnknownPreset is returned for a preset that does not exist. ErrUnknownPreset = errors.New("unknown preset") // ErrFixed is returned when an override tries to remove a capability or // permission that is always on (Report, ReachHub). ErrFixed = errors.New("always on, cannot be removed") // ErrNeedsGrant is returned when an override tries to give a development // machine a permission that is only available through a delayed grant // (#168), never as a setting. ErrNeedsGrant = errors.New("only available through a grant") // ErrNotAllowed is returned when a preset may never have a capability or // permission, whatever the override says. ErrNotAllowed = errors.New("not allowed for this preset") )
Functions ¶
func NeedsConsent ¶
func NeedsConsent(c Capability) bool
NeedsConsent reports whether turning c on also needs the machine's own consent (a local, default-off setting), because it changes what the machine exposes. The hub alone must not be able to make a server open a port (#160, #164).
Types ¶
type Assignment ¶
type Assignment struct {
Capabilities []Capability
Permissions []Permission
}
Assignment is what a machine ends up with. Both lists are sorted and contain no duplicates, so two equal assignments compare equal.
func Defaults ¶
func Defaults(p Preset) (Assignment, error)
Defaults returns the capabilities and permissions a preset starts with. The result is a copy; changing it does not change the defaults.
func Resolve ¶
func Resolve(p Preset, o Override) (Assignment, error)
Resolve applies an override to a preset's defaults and returns the result. It refuses an override that removes what is always on (ErrFixed), gives a development machine a grant-only permission (ErrNeedsGrant) or a forbidden one (ErrNotAllowed).
func (Assignment) Allows ¶
func (a Assignment) Allows(p Permission) bool
Allows reports whether the assignment includes p.
func (Assignment) Has ¶
func (a Assignment) Has(c Capability) bool
Has reports whether the assignment includes c.
type Capability ¶
type Capability string
Capability is a function a machine does.
const ( Report Capability = "report" // system information, heartbeat, metrics: always on SelfUpdate Capability = "self-update" // #18 Inventory Capability = "inventory" // read-only machine information, #62 Workloads Capability = "workloads" // #113 PrivilegedActions Capability = "privileged-actions" // #60 PluginRuntime Capability = "plugin-runtime" // #19 BackupStorage Capability = "backup-storage" // #166 Relay Capability = "relay" // access gateway, #161 Notifications Capability = "notifications" // access gateway, #161 Authentication Capability = "authentication" // access gateway, #161 )
The capabilities listed in #169. Exposure-changing ones need the machine's own consent as well as the hub's grant (see NeedsConsent).
type Override ¶
type Override struct {
Enable []Capability
Disable []Capability
Allow []Permission
Deny []Permission
}
Override changes a preset's defaults for one machine. Deny and Disable are applied after Allow and Enable, so removing wins over adding.
type Permission ¶
type Permission string
Permission is something a machine may reach or use.
const ( ReachHub Permission = "reach-hub" // always allowed ReachPeers Permission = "reach-peers" // direct links to other machines, #113; none exist today EgressNetwork Permission = "egress-network" // reaching the network outside the group InboundListener Permission = "inbound-listener" // accepting connections ReceiveBackups Permission = "receive-backups" // #166 UsePrivilegedActs Permission = "privileged-actions" // #60 )
The permissions listed in #170.
Source Files