group

package
v0.8.4 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package group implements host groups: operator-curated SITES (manual membership) and OS CATEGORIES (auto membership derived from hosts.os_family, or manual workload groups). A host belongs to many groups. The service owns CRUD, membership, the maintenance flag, and the per-group rollups the Groups page renders.

Spec: api-groups v1.0.0.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrNotFound          = errors.New("group: not found")
	ErrInvalidKind       = errors.New("group: kind must be site or os_category")
	ErrInvalidMembership = errors.New("group: membership must be manual or auto")
	ErrAutoNeedsFamily   = errors.New("group: auto membership requires a match_family")
	ErrManualHasFamily   = errors.New("group: manual membership must not set match_family")
	ErrSiteMustBeManual  = errors.New("group: a site must use manual membership")
	ErrDuplicateFamily   = errors.New("group: an auto group already exists for that OS family")
	ErrEmptyName         = errors.New("group: name is required")
	ErrTargetOnlyOnSite  = errors.New("group: only a site group may carry a compliance target")
	ErrInvalidTarget     = errors.New("group: target_framework is too long or has invalid characters")
)

Sentinel errors. Handlers map these to HTTP status codes.

Functions

This section is empty.

Types

type CreateInput

type CreateInput struct {
	Name        string
	Kind        Kind
	Subtype     string
	Color       string
	Membership  Membership
	MatchFamily string
}

CreateInput is the payload to create a group.

type FleetSummary

type FleetSummary struct {
	Groups           int
	Sites            int
	OSCategories     int
	HostsMaintenance int
	// Score is GET /fleet/score's own answer, whole. The Groups page and the
	// fleet KPI cannot disagree because there is only one computation and one
	// mapping.
	Score     fleetrollup.Score
	Ungrouped int
}

FleetSummary backs the Groups-page KPI row.

type Group

type Group struct {
	ID          uuid.UUID
	Name        string
	Kind        Kind
	Subtype     string
	Color       string
	Membership  Membership
	MatchFamily string // "" for manual groups
	Maintenance bool
	// TargetFramework is the compliance TARGET family a member host is held to
	// (Phase 3). "" means no group target. Only a site group may carry one
	// (D1); the service rejects a target on an os_category group.
	TargetFramework string
	CreatedAt       time.Time
	UpdatedAt       time.Time
}

Group is one row of the groups table.

type GroupWithRollup

type GroupWithRollup struct {
	Group
	Rollup
}

GroupWithRollup is a group plus its computed metrics.

type Kind

type Kind string

Kind distinguishes a site (environment/topology) from an os_category (platform/workload).

const (
	KindSite       Kind = "site"
	KindOSCategory Kind = "os_category"
)

type MemberChip

type MemberChip struct {
	HostID   uuid.UUID
	Hostname string
	// Status is the host's monitoring band (online/degraded/critical/
	// down/...) or "unknown" when never probed.
	Status string
}

MemberChip is a compact member-host descriptor for the card preview.

type Membership

type Membership string

Membership is how a group's hosts are determined.

const (
	// MembershipManual: hosts are assigned explicitly (group_members).
	MembershipManual Membership = "manual"
	// MembershipAuto: hosts are every host whose os_family == MatchFamily,
	// computed live (no stored membership, no backfill).
	MembershipAuto Membership = "auto"
)

type Rollup

type Rollup struct {
	Hosts         int
	Online        int
	Down          int
	CriticalHosts int
	// Score is the group's compliance average in the SAME shape the fleet uses:
	// the number, the outcomes behind it, the coverage status, the population,
	// and the lens. Sharing the shape is what lets one wire mapper serve both,
	// so a group average cannot ship without the metadata a fleet average
	// carries.
	Score   fleetrollup.Score
	Members []MemberChip
}

Rollup is the computed member summary the list view shows per group.

type Service

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

Service owns group CRUD, membership, and the per-group rollups.

func NewService

func NewService(pool *pgxpool.Pool) *Service

func (*Service) AddMember

func (s *Service) AddMember(ctx context.Context, groupID, hostID uuid.UUID) error

AddMember assigns a host to a MANUAL group. Auto groups reject manual membership (their members are derived).

func (*Service) Create

func (s *Service) Create(ctx context.Context, in CreateInput) (Group, error)

Create validates and inserts a group.

func (*Service) Delete

func (s *Service) Delete(ctx context.Context, id uuid.UUID) error

Delete removes a group (group_members cascade).

func (*Service) Get

func (s *Service) Get(ctx context.Context, id uuid.UUID) (Group, error)

Get returns one group (without rollup).

func (*Service) List

func (s *Service) List(ctx context.Context, orgDefault string) ([]GroupWithRollup, error)

List returns every group with its computed rollup, sites first.

func (*Service) RemoveMember

func (s *Service) RemoveMember(ctx context.Context, groupID, hostID uuid.UUID) error

RemoveMember removes a host from a manual group.

func (*Service) ScopeGroup

func (s *Service) ScopeGroup(ctx context.Context, groupID uuid.UUID) (string, []uuid.UUID, error)

ScopeGroup resolves a group id to its display name and the set of active member host ids, for callers that scope a fleet computation to one group (e.g. a scoped Reports executive summary). Manual groups read group_members; auto groups derive from hosts.os_family == match_family. Returns ErrNotFound when the group does not exist. An empty group yields a non-nil, empty id slice (a valid "no hosts" scope), distinct from the unscoped all-hosts case the caller models as no group at all.

func (*Service) ScopeGroupIn added in v0.8.0

func (s *Service) ScopeGroupIn(ctx context.Context, q db.Queryer, groupID uuid.UUID) (string, []uuid.UUID, error)

ScopeGroupIn is ScopeGroup against a caller-supplied queryer, so the group name and its member set can be read inside the caller's transaction.

func (*Service) SetMaintenance

func (s *Service) SetMaintenance(ctx context.Context, id uuid.UUID, on bool) (Group, error)

SetMaintenance toggles a group's maintenance flag.

func (*Service) SetTarget added in v0.5.0

func (s *Service) SetTarget(ctx context.Context, id uuid.UUID, family string) (Group, error)

SetTarget sets (or clears, when family is "") the group's compliance target framework. Only a site group may carry a target (D1): an os_category group is an automatic OS grouping, not a statement of compliance intent, so a target on one is rejected with ErrTargetOnlyOnSite.

func (*Service) Summary

func (s *Service) Summary(ctx context.Context, orgDefault string) (FleetSummary, error)

Summary computes the Groups-page KPI row.

func (*Service) Update

func (s *Service) Update(ctx context.Context, id uuid.UUID, in UpdateInput) (Group, error)

Update patches a group's editable display fields (name/subtype/color). Kind and membership are immutable.

type UpdateInput

type UpdateInput struct {
	Name    string
	Subtype string
	Color   string
}

UpdateInput patches a group's editable fields.

Jump to

Keyboard shortcuts

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