Help us shape the future of Go! Take the 2026 Go Developer Survey

inventory

package
v0.38.1 Latest Latest
Warning

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

 Go to latest Published: Sep 27, 2026 License: Apache-2.0, Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package inventory owns host facts and static loading. The static loader also implements the independent directory.Directory user lookup interface.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrStorage  = errors.New("managed inventory storage unavailable")
	ErrConflict = errors.New("inventory conflict")
	ErrNotFound = errors.New("inventory record not found")
	ErrToken    = errors.New("invalid, expired, revoked, or used enrollment token")
	ErrRevision = errors.New("record changed; reload before retrying")
)

Functions

func DecodeYAML added in v0.31.0 

func DecodeYAML(data []byte, dst any) error

func RandomSecret added in v0.31.0 

func RandomSecret() (string, error)

Types

type AuditEvent added in v0.31.0 

type AuditEvent struct {
	At       time.Time `yaml:"at"`
	Actor    string    `yaml:"actor"`
	Action   string    `yaml:"action"`
	Resource string    `yaml:"resource"`
}

func (AuditEvent) ControlEvent added in v0.35.0 

func (e AuditEvent) ControlEvent() inventoryapi.HostAuditEvent

ControlEvent projects the audit event onto the control API.

type EnrollmentToken added in v0.31.0 

type EnrollmentToken struct {
	ID        string    `yaml:"id"`
	ExpiresAt time.Time `yaml:"expires-at"`
	UsedBy    string    `yaml:"used-by,omitempty"`
	Revoked   bool      `yaml:"revoked"`
}

func (EnrollmentToken) ControlToken added in v0.35.0 

func (t EnrollmentToken) ControlToken() inventoryapi.EnrollmentToken

ControlToken projects the token onto the control API.

type Host 

type Host struct {
	Names    []string
	Labels   map[string]string
	Accounts []string
}

Host contains authorization attributes, separate from principal metadata.

type HostRecord added in v0.31.0 

type HostRecord struct {
	SourceFile string `yaml:"-"`
	Pattern    string `yaml:"-"`

	ID            string    `yaml:"id"`
	Revision      uint64    `yaml:"revision"`
	Status        string    `yaml:"status"`
	Proposal      Proposal  `yaml:"host,omitempty"`
	CreatedAt     time.Time `yaml:"created-at"`
	UpdatedAt     time.Time `yaml:"updated-at"`
	Source        string    `yaml:"-"`
	ShadowedNames []string  `yaml:"-"`
}

func (HostRecord) ControlRecord added in v0.35.0 

func (r HostRecord) ControlRecord() inventoryapi.HostRecord

ControlRecord projects the record onto the control API.

type Hosts 

type Hosts interface {
	LookupHost(context.Context, string) (*ResolvedHost, string, error)
}

Hosts resolves machines independently of the user directory. LookupHost returns the host and the revision of the inventory used to resolve it from one coherent read. A missing host returns nil with a nonempty revision; lookup failures return an error.

type Managed added in v0.31.0 

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

Managed loads item files once, then resolves names entirely through indexes. Mutations persist one item before updating its indexes under the write lock. Files are the source of truth; edit them only while the service is stopped.

func OpenManaged added in v0.31.0 

func OpenManaged(dir string, static *Static) (*Managed, error)

OpenManaged loads the configured dynamic store. Any storage or validation error fails startup; exact static records take precedence after a successful load.

func (*Managed) Audit added in v0.31.0 

func (m *Managed) Audit() ([]AuditEvent, error)

func (*Managed) Change added in v0.31.0 

func (m *Managed) Change(actor, action, id string, revision uint64, p *Proposal) (*HostRecord, error)

func (*Managed) Close added in v0.31.0 

func (m *Managed) Close() error

func (*Managed) CreateToken added in v0.31.0 

func (m *Managed) CreateToken(actor string, lifetime time.Duration) (EnrollmentToken, error)

func (*Managed) Enroll added in v0.31.0 

func (m *Managed) Enroll(p Proposal, token string) (*HostRecord, error)

func (*Managed) Get added in v0.31.0 

func (m *Managed) Get(id string) (*HostRecord, error)

Indexed get is useful to API callers that already have a stable record ID.

func (*Managed) Health added in v0.31.0 

func (m *Managed) Health() error

func (*Managed) List added in v0.31.0 

func (m *Managed) List() ([]HostRecord, error)

func (*Managed) LookupHost added in v0.31.0 

func (m *Managed) LookupHost(ctx context.Context, name string) (*ResolvedHost, string, error)

LookupHost resolves the host and its revision under the same read lock.

func (*Managed) RevokeToken added in v0.31.0 

func (m *Managed) RevokeToken(actor, id string) error

func (*Managed) Tokens added in v0.31.0 

func (m *Managed) Tokens() ([]EnrollmentToken, error)

type PrincipalMode 

type PrincipalMode string

PrincipalMode selects how an allowed account@host tuple is represented in an issued SSH certificate. 

const (
	// AccountNamePrincipals places the literal requested account name in the
	// certificate. It is compatible with ordinary OpenSSH CA configuration but
	// is not destination-bound.
	AccountNamePrincipals PrincipalMode = "account-name"

	// EpithetPrincipalV1 derives a destination-bound v1 principal from the
	// principal domain and requested account name.
	EpithetPrincipalV1 PrincipalMode = principal.SchemeV1
)

func (PrincipalMode) Effective 

func (m PrincipalMode) Effective() PrincipalMode

Effective returns the concrete mode represented by m.

func (PrincipalMode) Validate 

func (m PrincipalMode) Validate() error

Validate rejects unknown non-empty principal modes. Empty is the zero-value spelling of AccountNamePrincipals for compatibility with custom inventory implementations constructed in Go.

type Proposal added in v0.31.0 

type Proposal struct {
	Names         []string          `yaml:"names"`
	Labels        map[string]string `yaml:"labels"`
	Accounts      []string          `yaml:"accounts"`
	PrincipalMode PrincipalMode     `yaml:"principal-mode"`
	Domain        string            `yaml:"domain,omitempty"`
}

Proposal is the entire editable authorization record. Admission and ownership are server-owned metadata, never fields a host can approve for itself.

func ParseProposal added in v0.31.0 

func ParseProposal(data []byte) (Proposal, error)

ParseProposal distinguishes an explicit null (ungrounded) account set from a missing field, and refuses trailing YAML documents and unknown fields.

func ProposalFromControl added in v0.35.0 

func ProposalFromControl(p inventoryapi.Proposal) Proposal

ProposalFromControl adopts a control API proposal without validating it; callers validate through Validate or the store operation that consumes it.

func (Proposal) ControlProposal added in v0.35.0 

func (p Proposal) ControlProposal() inventoryapi.Proposal

ControlProposal projects the proposal onto the control API. Slices and maps are shared, not cloned, so nil (unrestricted accounts) and empty (no accounts) survive.

func (Proposal) MarshalYAML added in v0.31.0 

func (p Proposal) MarshalYAML() (any, error)

MarshalYAML preserves the distinction between unrestricted accounts (null) and an explicit empty account set ([]), both on disk and in the editor.

func (*Proposal) UnmarshalYAML added in v0.31.0 

func (p *Proposal) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML applies the same field-presence contract to on-disk snapshots and editor proposals. Accidentally deleting accounts must not broaden access.

func (*Proposal) Validate added in v0.31.0 

func (p *Proposal) Validate() error

type ResolvedHost 

type ResolvedHost struct {
	Policy        Host
	PrincipalMode PrincipalMode
	Domain        principal.Domain
}

ResolvedHost carries both the authorization resource consumed by Writ and issuance metadata that must remain outside the pure policy model. Policy.Names always contains the host's names, independent of its principal mode or domain.

type Static 

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

Static is a file-backed inventory: directory users and hosts loaded once at startup. Reload is a process restart, like the policy itself.

Host entries come in two forms. An exact entry (`names:`) is one registered host. A pattern entry (`pattern:`) uses the same DNS-label-aware hostname patterns as Writ host selectors. Exact entries expose all their names; pattern entries adopt the requested name. Principal domains are separate issuance metadata and never replace host names. Patterns are the escape hatch for fleets of short-lived hosts (VM pools, CI runners) that follow a naming pattern but cannot be enumerated in a file.

func NewStatic 

func NewStatic(paths []string, options ...StaticOption) (*Static, error)

NewStatic loads an inventory from one or more YAML files. Files concatenate; a missing id, duplicate id/userName, or duplicate exact host name across the set is a load error. All IDs belong to the inventory service's single configured provider/tenant. Decoding is strict — an unknown field is an error, not a silently ignored typo.

func (*Static) DirectoryRevision 

func (s *Static) DirectoryRevision() string

func (*Static) InventoryRevision 

func (s *Static) InventoryRevision() string

func (*Static) ListUserFacts added in v0.36.0 

func (s *Static) ListUserFacts(_ context.Context) ([]directory.User, directory.Revision, error)

func (*Static) LookupHost 

func (s *Static) LookupHost(_ context.Context, name string) (*ResolvedHost, string, error)

LookupHost implements Hosts: exact entries first, then pattern entries in file order, first match wins.

func (*Static) LookupUser 

func (s *Static) LookupUser(_ context.Context, id string) (*directory.User, directory.Revision, error)

LookupUser implements directory.Directory.

func (*Static) Records added in v0.31.0 

func (s *Static) Records() []HostRecord

Records provides read-only source information for inventory administration.

type StaticOption 

type StaticOption func(*staticOptions) error

StaticOption configures static inventory loading.

func WithDefaultPrincipalMode 

func WithDefaultPrincipalMode(mode PrincipalMode) StaticOption

WithDefaultPrincipalMode sets the mode inherited by host entries that omit principal-mode. The default is AccountNamePrincipals.

func WithoutHosts added in v0.38.0 

func WithoutHosts() StaticOption

WithoutHosts loads only directory facts, independently of host configuration.

func WithoutUsers added in v0.35.0 

func WithoutUsers() StaticOption

WithoutUsers loads only host facts; user records cannot become a fallback.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.