entities

package
v0.4.5-alpha Latest Latest
Warning

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

 Go to latest Published: Jan 29, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package entities contains domain entities for the Reglet domain model. These are pure domain types with NO infrastructure dependencies.

Package entities contains domain entities for the Reglet domain model. These are pure domain types with NO infrastructure dependencies.

Package entities contains domain entities for the Reglet domain model.

Package entities contains domain entities for the Reglet domain model. These are pure domain types with NO infrastructure dependencies.

Package entities contains domain entities for the Reglet domain model.

Package entities contains domain entities for the Reglet domain model.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrPluginNotFound is returned when a plugin cannot be found in any source.
	ErrPluginNotFound = errors.New("plugin not found")

	// ErrIntegrityCheckFailed is returned when digest verification fails.
	ErrIntegrityCheckFailed = errors.New("integrity check failed")
)

Sentinel errors for common error patterns. These allow both errors.Is() checks and errors.As() for detailed information.

Functions

This section is empty.

Types

type BackoffType 

type BackoffType string

BackoffType defines the strategy for retry delays. 

const (
	BackoffNone        BackoffType = "none"
	BackoffLinear      BackoffType = "linear"
	BackoffExponential BackoffType = "exponential"
)

type CacheState 

type CacheState int

CacheState represents the current state of a cache entry. 

const (
	CacheStateFresh   CacheState = iota // Entry is valid and fresh
	CacheStateStale                     // Entry is past TTL but usable
	CacheStateExpired                   // Entry should be re-fetched
)

type Control 

type Control struct {
	ID                     string
	Name                   string
	Description            string
	Severity               string
	Owner                  string
	RetryBackoff           BackoffType
	DependsOn              []string
	ObservationDefinitions []ObservationDefinition
	Tags                   []string
	Timeout                time.Duration
	Retries                int
	RetryDelay             time.Duration
	RetryMaxDelay          time.Duration
}

Control represents a specific compliance check or validation unit. It is uniquely identified by its ID.

func (*Control) ApplyDefaults 

func (c *Control) ApplyDefaults(defaults *ControlDefaults)

ApplyDefaults applies the given defaults to the control if values are missing.

func (*Control) GetEffectiveTimeout 

func (c *Control) GetEffectiveTimeout(defaultTimeout time.Duration) time.Duration

GetEffectiveTimeout returns the control's timeout with fallback to default.

func (*Control) HasAnyTag 

func (c *Control) HasAnyTag(tags []string) bool

HasAnyTag returns true if the control has any of the specified tags.

func (*Control) HasDependency 

func (c *Control) HasDependency(controlID string) bool

HasDependency returns true if the control depends on the specified control ID.

func (*Control) HasTag 

func (c *Control) HasTag(tag string) bool

HasTag returns true if the control has the specified tag.

func (*Control) IsEmpty 

func (c *Control) IsEmpty() bool

IsEmpty returns true if this is the zero value.

func (*Control) MatchesAnySeverity 

func (c *Control) MatchesAnySeverity(severities []string) bool

MatchesAnySeverity returns true if the control matches any of the severities.

func (*Control) MatchesSeverity 

func (c *Control) MatchesSeverity(severity string) bool

MatchesSeverity returns true if the control matches the specified severity.

func (*Control) ObservationCount 

func (c *Control) ObservationCount() int

ObservationCount returns the number of observations in this control.

func (*Control) Validate 

func (c *Control) Validate() error

Validate ensures the control is well-formed.

type ControlDefaults 

type ControlDefaults struct {
	Severity      string
	Owner         string
	RetryBackoff  BackoffType
	Tags          []string
	Timeout       time.Duration
	Retries       int
	RetryDelay    time.Duration
	RetryMaxDelay time.Duration
}

ControlDefaults specifies values inherited by controls when not explicitly set.

type ControlSet 

type ControlSet []Control

ControlSet represents a collection of controls with domain logic for filtering, validation, and graph analysis.

func (ControlSet) Add 

func (cs ControlSet) Add(ctrl Control) (ControlSet, error)

Add adds a control to the set. It ensures uniqueness and no cycles. It returns a new ControlSet with the added control. Note: This returns a NEW slice, it does not mutate the receiver if it was passed by value, but since it's a slice type, we should be careful. To match the existing immutable-ish pattern or safe add pattern, we will append and return.

func (ControlSet) ApplyDefaults 

func (cs ControlSet) ApplyDefaults(defaults *ControlDefaults)

ApplyDefaults yields a new ControlSet with defaults applied to all controls. Note: Since ControlSet is a slice of values, modifying elements in place works if we are iterating by index, but it mutates the underlying array. To be safe and clean, we often mutate in place for "Apply" methods on the object itself.

func (ControlSet) CheckForControlDependencyCycles 

func (cs ControlSet) CheckForControlDependencyCycles() error

CheckForControlDependencyCycles checks if the control dependency graph contains any cycles.

func (ControlSet) Count 

func (cs ControlSet) Count() int

Count returns the number of controls.

func (ControlSet) Get 

func (cs ControlSet) Get(id string) *Control

Get returns a pointer to the control with the given ID, or nil if not found.

func (ControlSet) Has 

func (cs ControlSet) Has(id string) bool

Has returns true if the control exists in the set.

func (ControlSet) Select 

func (cs ControlSet) Select(opts ...FilterOption) ControlSet

Select returns a subset of controls that match the filtering criteria. Filters are applied as an intersection (AND) of valid conditions. Within a condition (e.g., Tags), it's a union (OR). If "Include" filters are empty, they are ignored (match all).

func (ControlSet) Validate 

func (cs ControlSet) Validate() error

Validate checks the integrity of all controls in the set and ensures unique IDs.

type ControlSummary 

type ControlSummary struct {
	ID           string
	Name         string
	Severity     string
	DependsOn    []string
	Tags         []string
	Observations int
	Expectations int
}

ControlSummary is a lightweight view of a control for planning purposes. It contains only the information needed to display an execution plan.

func ControlSummaryFromControl 

func ControlSummaryFromControl(ctrl Control) ControlSummary

ControlSummaryFromControl creates a ControlSummary from a Control entity.

type ControlsSection 

type ControlsSection struct {
	Defaults *ControlDefaults
	Items    ControlSet
}

ControlsSection groups validation controls and their default settings.

type ExecutionPlan 

type ExecutionPlan struct {
	ProfileName     string
	ProfileVersion  string
	Levels          []ExecutionPlanLevel
	TotalControls   int
	MaxParallelism  int
	HasDependencies bool
}

ExecutionPlan represents a dry-run execution plan showing which controls would run and in what order, without actually executing them.

func NewExecutionPlan 

func NewExecutionPlan(name, version string, levels []ExecutionPlanLevel) *ExecutionPlan

NewExecutionPlan creates an ExecutionPlan from profile metadata and control levels. It calculates statistics like total controls, max parallelism, and dependency presence.

func (*ExecutionPlan) IsEmpty 

func (p *ExecutionPlan) IsEmpty() bool

IsEmpty returns true if the plan contains no controls.

func (*ExecutionPlan) LevelCount 

func (p *ExecutionPlan) LevelCount() int

LevelCount returns the number of execution levels in the plan.

type ExecutionPlanLevel 

type ExecutionPlanLevel struct {
	Controls []ControlSummary
	Level    int
}

ExecutionPlanLevel represents controls that can execute in parallel at a given level. Controls within the same level have no dependencies on each other.

type FilterConfig 

type FilterConfig struct {
	IncludeTags       []string
	IncludeSeverities []string
	IncludeIDs        []string
	ExcludeTags       []string
	ExcludeIDs        []string
}

FilterConfig holds the configuration for filtering controls.

type FilterOption 

type FilterOption func(*FilterConfig)

FilterOption is a functional option for configuring the filter.

func ExcludeIDs 

func ExcludeIDs(ids ...string) FilterOption

ExcludeIDs filters controls to exclude those with the specified IDs.

func ExcludeTags 

func ExcludeTags(tags ...string) FilterOption

ExcludeTags filters controls to exclude those with any of the specified tags.

func WithIDs 

func WithIDs(ids ...string) FilterOption

WithIDs filters controls to include only those with the specified IDs.

func WithSeverities 

func WithSeverities(severities ...string) FilterOption

WithSeverities filters controls to include only those with any of the specified severities.

func WithTags 

func WithTags(tags ...string) FilterOption

WithTags filters controls to include only those with any of the specified tags.

type IntegrityError 

type IntegrityError struct {
	Expected values.Digest
	Actual   values.Digest
}

IntegrityError indicates digest mismatch. Provides detailed information about expected vs actual digest.

func (*IntegrityError) Error 

func (e *IntegrityError) Error() string

func (*IntegrityError) Is 

func (e *IntegrityError) Is(target error) bool

Is implements error matching for errors.Is() checks. This allows: errors.Is(err, entities.ErrIntegrityCheckFailed)

type Lockfile 

type Lockfile struct {
	Generated time.Time
	Plugins   map[string]PluginLock
	Profiles  map[string]ProfileLock
	Version   int
}

Lockfile is an aggregate root for reproducible plugin and profile resolution. It guarantees that plugin and profile versions are pinned for consistent builds.

Invariants: - Each plugin entry must have a digest - Each profile entry must have a digest - Generated timestamp must be set

func NewLockfile 

func NewLockfile() *Lockfile

NewLockfile creates a new lockfile with the current version.

func (*Lockfile) AddPlugin 

func (l *Lockfile) AddPlugin(name string, lock PluginLock) error

AddPlugin adds a plugin lock entry. Returns error if digest is empty (invariant enforcement).

func (*Lockfile) AddProfile 

func (l *Lockfile) AddProfile(url string, lock ProfileLock) error

AddProfile adds a profile lock entry. Returns error if digest is empty (invariant enforcement).

func (*Lockfile) GetPlugin 

func (l *Lockfile) GetPlugin(name string) *PluginLock

GetPlugin retrieves a plugin lock entry by name. Returns nil if not found.

func (*Lockfile) GetProfile 

func (l *Lockfile) GetProfile(url string) *ProfileLock

GetProfile retrieves a profile lock entry by URL. Returns nil if not found.

func (*Lockfile) PluginCount 

func (l *Lockfile) PluginCount() int

PluginCount returns the number of locked plugins.

func (*Lockfile) ProfileCount 

func (l *Lockfile) ProfileCount() int

ProfileCount returns the number of locked profiles.

func (*Lockfile) Validate 

func (l *Lockfile) Validate() error

Validate checks lockfile invariants.

type LoopConfig 

type LoopConfig struct {
	Items string // Template expression for list, e.g., "{{ .vars.services }}"
	As    string // Optional variable name (default: uses .loop.item)
}

LoopConfig defines iteration settings for an observation. When specified, the observation will be executed once per item in the list.

type ObservationDefinition 

type ObservationDefinition struct {
	Config map[string]interface{}
	Loop   *LoopConfig
	Plugin string
	Expect []string
}

ObservationDefinition configuration for a specific plugin execution. It is an immutable value object.

type Plugin 

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

Plugin is the aggregate root for the Plugin Management bounded context. Represents a WASM plugin with verified integrity and metadata.

func NewPlugin 

func NewPlugin(
	ref values.PluginReference,
	digest values.Digest,
	metadata values.PluginMetadata,
) *Plugin

NewPlugin creates a new plugin entity.

func (*Plugin) Digest 

func (p *Plugin) Digest() values.Digest

Digest returns the plugin's content hash.

func (*Plugin) Metadata 

func (p *Plugin) Metadata() values.PluginMetadata

Metadata returns the plugin's descriptive information.

func (*Plugin) Reference 

func (p *Plugin) Reference() values.PluginReference

Reference returns the plugin's unique identifier.

func (*Plugin) VerifyIntegrity 

func (p *Plugin) VerifyIntegrity(expected values.Digest) error

VerifyIntegrity checks if the plugin's digest matches expected value.

type PluginLock 

type PluginLock struct {
	Fetched   time.Time
	Modified  time.Time
	Requested string
	Resolved  string
	Source    string
	Digest    string
}

PluginLock is a value object representing a pinned plugin version. Immutable after creation.

type PluginNotFoundError 

type PluginNotFoundError struct {
	Reference values.PluginReference
}

PluginNotFoundError indicates plugin doesn't exist in source. Provides detailed information about which plugin was not found.

func (*PluginNotFoundError) Error 

func (e *PluginNotFoundError) Error() string

func (*PluginNotFoundError) Is 

func (e *PluginNotFoundError) Is(target error) bool

Is implements error matching for errors.Is() checks. This allows: errors.Is(err, entities.ErrPluginNotFound)

type PluginRegistry 

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

PluginRegistry maps plugin aliases to their specifications. This allows observations to reference plugins by alias while the runtime resolves them to their actual sources.

func NewPluginRegistry 

func NewPluginRegistry() *PluginRegistry

NewPluginRegistry creates a new empty plugin registry.

func (*PluginRegistry) AllSpecs 

func (pr *PluginRegistry) AllSpecs() []*PluginSpec

AllSpecs returns all registered plugin specifications.

func (*PluginRegistry) HasPlugin 

func (pr *PluginRegistry) HasPlugin(name string) bool

HasPlugin reports whether a plugin with the given name is registered.

func (*PluginRegistry) Register 

func (pr *PluginRegistry) Register(spec *PluginSpec) error

Register adds a plugin specification to the registry.

func (*PluginRegistry) Resolve 

func (pr *PluginRegistry) Resolve(alias string) *PluginSpec

Resolve looks up a plugin by alias and returns its specification. If the alias is not registered, it returns a default spec where name=source.

type PluginSpec 

type PluginSpec struct {
	// Name is the alias used in observations (e.g., "file", "file-legacy")
	Name string

	// Source is the plugin source (e.g., "file", "ghcr.io/reglet-dev/reglet-plugins/file:1.0.0")
	Source string

	// Version is the explicit version constraint (e.g., "1.2.0")
	Version string

	// Digest is the optional content hash for pinning (e.g., "sha256:abc123...")
	Digest string

	// Verify indicates whether signature verification is required
	Verify bool
}

PluginSpec represents a plugin declaration with optional version and source.

func ParsePluginDeclaration 

func ParsePluginDeclaration(declaration string) (*PluginSpec, error)

ParsePluginDeclaration parses a single plugin declaration string. Supported formats:

  • "file" -> name=file, source=file
  • "file@1.2.0" -> name=file, source=file, version=1.2.0
  • "ghcr.io/.../file:1.2.0" -> name=file, source=full path
  • "ghcr.io/.../file@sha256:abc..." -> name=file, source=path, digest=sha256:abc...

func ParsePluginDeclarationWithAlias 

func ParsePluginDeclarationWithAlias(alias string, source interface{}) (*PluginSpec, error)

ParsePluginDeclarationWithAlias parses a plugin declaration with an explicit alias. Format: "alias: source" or expanded map format.

func (*PluginSpec) IsBuiltIn 

func (ps *PluginSpec) IsBuiltIn() bool

IsBuiltIn returns true if this plugin references a built-in plugin.

func (*PluginSpec) PluginName 

func (ps *PluginSpec) PluginName() string

PluginName returns the actual plugin name to load (without version suffix).

type Profile 

type Profile struct {
	Metadata ProfileMetadata
	Plugins  []string
	Vars     map[string]interface{}
	Controls ControlsSection

	// Extends specifies parent profiles to inherit from.
	// Multiple parents are merged left-to-right before applying current profile.
	// This field is NOT propagated after merge resolution.
	Extends []string
}

Profile represents the Reglet profile configuration. It serves as the aggregate root for the configuration context, defining the validation configuration and ruleset.

Invariants enforced: - Unique control IDs - All dependencies must exist - Name and version are mandatory - At least one observation per control

func (*Profile) AddControl 

func (p *Profile) AddControl(ctrl Control) error

AddControl safely adds a new control to the profile. It returns an error if the control is invalid or already exists.

func (*Profile) GetAllControls 

func (p *Profile) GetAllControls() []Control

GetAllControls returns all controls in the profile.

func (*Profile) GetControls 

func (p *Profile) GetControls() ControlSet

GetControls returns the set of controls in the profile.

func (*Profile) GetMetadata 

func (p *Profile) GetMetadata() ProfileMetadata

GetMetadata returns the profile metadata.

func (*Profile) GetPlugins 

func (p *Profile) GetPlugins() []string

GetPlugins returns the list of plugins required by this profile.

func (*Profile) GetVars 

func (p *Profile) GetVars() map[string]interface{}

GetVars returns the profile variables.

func (*Profile) Validate 

func (p *Profile) Validate() error

Validate checks the integrity of the profile configuration.

type ProfileCacheEntry 

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

ProfileCacheEntry is an aggregate root representing a cached remote profile. It contains the profile content along with metadata for cache management.

Invariants:

  • contentHash must match SHA256(content)
  • fetchedAt must not be zero
  • ttl must be positive
  • size must equal len(content)

func LoadProfileCacheEntry 

func LoadProfileCacheEntry(
	id string,
	ref values.ProfileReference,
	content []byte,
	contentHash values.Digest,
	fetchedAt time.Time,
	lastAccessedAt time.Time,
	ttl time.Duration,
	etag string,
) *ProfileCacheEntry

LoadProfileCacheEntry reconstructs an entry from stored data (e.g., from disk). Does not validate content hash (assumes already validated).

func NewProfileCacheEntry 

func NewProfileCacheEntry(
	ref values.ProfileReference,
	content []byte,
	contentHash values.Digest,
	ttl time.Duration,
) (*ProfileCacheEntry, error)

NewProfileCacheEntry creates a new cache entry with validated invariants.

func (*ProfileCacheEntry) Age 

func (e *ProfileCacheEntry) Age() time.Duration

Age returns how long since the entry was fetched.

func (*ProfileCacheEntry) Content 

func (e *ProfileCacheEntry) Content() []byte

Content returns the cached profile content.

func (*ProfileCacheEntry) ContentHash 

func (e *ProfileCacheEntry) ContentHash() values.Digest

ContentHash returns the content digest.

func (*ProfileCacheEntry) ETag 

func (e *ProfileCacheEntry) ETag() string

ETag returns the HTTP ETag if available.

func (*ProfileCacheEntry) ExpiresAt 

func (e *ProfileCacheEntry) ExpiresAt() time.Time

ExpiresAt returns when this entry will expire.

func (*ProfileCacheEntry) FetchedAt 

func (e *ProfileCacheEntry) FetchedAt() time.Time

FetchedAt returns when the profile was originally fetched.

func (*ProfileCacheEntry) ID 

func (e *ProfileCacheEntry) ID() string

ID returns the cache key.

func (*ProfileCacheEntry) IsExpired 

func (e *ProfileCacheEntry) IsExpired() bool

IsExpired returns true if the cache entry has exceeded its TTL. Expired entries should be re-fetched before use.

func (*ProfileCacheEntry) IsFresh 

func (e *ProfileCacheEntry) IsFresh() bool

IsFresh returns true if the entry is within its TTL and valid for use.

func (*ProfileCacheEntry) IsStale 

func (e *ProfileCacheEntry) IsStale() bool

IsStale returns true if the entry is past its TTL but within the stale period. Stale entries can be used but should trigger an async update check. The stale period is 2x the TTL.

func (*ProfileCacheEntry) LastAccessedAt 

func (e *ProfileCacheEntry) LastAccessedAt() time.Time

LastAccessedAt returns when the entry was last accessed.

func (*ProfileCacheEntry) Reference 

func (e *ProfileCacheEntry) Reference() values.ProfileReference

Reference returns the original profile reference.

func (*ProfileCacheEntry) SetETag 

func (e *ProfileCacheEntry) SetETag(etag string)

SetETag sets the HTTP ETag for update checking.

func (*ProfileCacheEntry) Size 

func (e *ProfileCacheEntry) Size() int64

Size returns the content size in bytes.

func (*ProfileCacheEntry) State 

func (e *ProfileCacheEntry) State() CacheState

State returns the current cache state.

func (*ProfileCacheEntry) StateString 

func (e *ProfileCacheEntry) StateString() string

StateString returns a human-readable cache state.

func (*ProfileCacheEntry) TTL 

func (e *ProfileCacheEntry) TTL() time.Duration

TTL returns the cache validity period.

func (*ProfileCacheEntry) TimeUntilExpiry 

func (e *ProfileCacheEntry) TimeUntilExpiry() time.Duration

TimeUntilExpiry returns the duration until expiry (negative if expired).

func (*ProfileCacheEntry) Touch 

func (e *ProfileCacheEntry) Touch()

Touch updates the last accessed timestamp.

func (*ProfileCacheEntry) Validate 

func (e *ProfileCacheEntry) Validate() error

Validate checks all invariants.

func (*ProfileCacheEntry) ValidateContent 

func (e *ProfileCacheEntry) ValidateContent() error

ValidateContent verifies that the content matches the stored hash.

type ProfileLock 

type ProfileLock struct {
	Fetched   time.Time
	Modified  time.Time
	Requested string // Original URL with version (e.g., "url#v1.2.0")
	Resolved  string // Actual version fetched
	Source    string // Normalized source URL
	Digest    string // Content hash (sha256:...)
}

ProfileLock is a value object representing a pinned remote profile version. Immutable after creation.

type ProfileMetadata 

type ProfileMetadata struct {
	Name        string
	Version     string
	Description string
}

ProfileMetadata contains descriptive information about the profile.

type ProfileReader 

type ProfileReader interface {
	// Metadata access
	GetMetadata() ProfileMetadata
	GetPlugins() []string
	GetVars() map[string]interface{}

	// Access to controls
	GetControls() ControlSet
}

ProfileReader provides read-only access to profile data. This interface enforces immutability and prevents accidental mutations.

Both raw Profile and ValidatedProfile implement this interface, allowing consumers to work with either type through the same contract.

type ValidatedProfile 

type ValidatedProfile struct {
	*Profile // Embedded raw profile (provides ProfileReader interface)

}

ValidatedProfile represents a fully compiled and validated profile. This is an immutable value object created by the ProfileCompiler.

It embeds the raw Profile and adds compiled/enriched state: - Defaults have been applied to all controls - All validations have passed - Dependency graph has been verified (no cycles)

func NewValidatedProfile 

func NewValidatedProfile(profile *Profile) *ValidatedProfile

NewValidatedProfile creates a new ValidatedProfile from a raw profile. This is an internal constructor - use ProfileCompiler.Compile() instead.

func (*ValidatedProfile) IsValidated 

func (v *ValidatedProfile) IsValidated() bool

IsValidated always returns true for ValidatedProfile. This is a marker method to distinguish from raw Profile at runtime if needed.

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.