Documentation
¶
Overview ¶
Package config loads and creates Relayer interception configuration files. It deliberately owns YAML concerns so the interception engine remains independent from persistence and command-line conventions.
Index ¶
- Constants
- Variables
- func DefaultPatterns() []intercept.Pattern
- func FileRevision(path string) (string, error)
- type ConfigPattern
- type ExistingConfigReadError
- type FileSnapshot
- type FullConfigurationUpdate
- type Result
- func LoadExisting(path string) (Result, error)
- func LoadOrCreate(path string) (Result, error)
- func ReplaceAgents(path, expectedRevision string, specs []agent.Spec) (Result, string, error)
- func UpdateFullConfiguration(path, expectedRevision string, update FullConfigurationUpdate) (Result, string, error)
- type SessionPolicy
Constants ¶
const ( DefaultPath = "config.yaml" CurrentVersion = 1 )
Variables ¶
var ( ErrRevisionMismatch = errors.New("configuration modified since it was loaded") // ErrCommitUncertain means the atomic rename completed but a subsequent // durability or verification step failed. Callers must reload before any // retry so they never overwrite a publication that may already be visible. ErrCommitUncertain = errors.New("configuration publication completed with uncertain durability state") )
var ErrExistingConfigRead = errors.New("could not read existing configuration")
ErrExistingConfigRead identifies failures while reading the selected file in LoadExisting. Validation errors that happen after the bytes were read, including inaccessible agent working directories, never match this value.
Functions ¶
func DefaultPatterns ¶
DefaultPatterns returns an independent copy of the built-in patterns.
func FileRevision ¶
FileRevision returns a content-derived revision suitable for optimistic updates. It never includes file contents in errors or diagnostics.
Types ¶
type ConfigPattern ¶
type ConfigPattern struct {
Pattern string `yaml:"pattern"`
Description string `yaml:"description"`
// Sensitive marks a pattern as reading a secret, which masks the operator
// field and forces a human decision. Relayer also infers this from the
// pattern text, but that inference is a word list and cannot recognize
// every prompt; without this field a missed word means an unmasked
// credential entry with no way to correct it.
//
// It can only escalate. `sensitive: false` does not downgrade a pattern the
// inference already considers sensitive.
Sensitive *bool `yaml:"sensitive,omitempty"`
}
ConfigPattern is the strict YAML representation exposed to users.
type ExistingConfigReadError ¶
type ExistingConfigReadError struct {
// contains filtered or unexported fields
}
ExistingConfigReadError retains only a finite read-failure classification for errors.Is/errors.As while discarding the selected path and raw operating-system details.
func (*ExistingConfigReadError) Error ¶
func (err *ExistingConfigReadError) Error() string
func (*ExistingConfigReadError) Is ¶
func (err *ExistingConfigReadError) Is(target error) bool
func (*ExistingConfigReadError) Unwrap ¶
func (err *ExistingConfigReadError) Unwrap() error
type FileSnapshot ¶
type FileSnapshot struct {
// contains filtered or unexported fields
}
FileSnapshot is an opaque, in-memory copy of one regular configuration file. Its bytes may contain credentials and are therefore deliberately not exported. Desktop lifecycle code uses it only to restore an exact previous document after a failed restart.
func CaptureFileSnapshot ¶
func CaptureFileSnapshot(path string) (*FileSnapshot, error)
CaptureFileSnapshot reads a configuration under the same cooperative lock used by ReplaceAgents. The returned snapshot owns an independent byte copy.
func (*FileSnapshot) Discard ¶
func (snapshot *FileSnapshot) Discard()
Discard overwrites the retained bytes and makes the snapshot unusable.
func (*FileSnapshot) Restore ¶
func (snapshot *FileSnapshot) Restore(expectedRevision string) (Result, string, error)
Restore atomically republishes the exact captured bytes only while the current file still has expectedRevision. This prevents rollback from overwriting a newer edit made by another process.
func (*FileSnapshot) Revision ¶
func (snapshot *FileSnapshot) Revision() string
Revision returns the content revision captured with the snapshot without exposing any file bytes.
type FullConfigurationUpdate ¶ added in v0.3.0
type FullConfigurationUpdate struct {
Agents []agent.Spec
UpdateAgents bool // Explicit flag indicating Agents slice should replace current agents
Policies *policy.Config
// PolicyPreset is the preset the settings editor shows as chosen for
// Policies (policy.Settings.Profile). When the editor switched to it and
// the file names a profile, the file names this one, whether or not the
// fields were then adjusted.
PolicyPreset string
Notifications *notify.Config
}
FullConfigurationUpdate defines atomic updates to the configuration file. If a pointer/slice is nil, that section remains untouched.
type Result ¶
type Result struct {
Version int
Legacy bool
// Revision is a content hash used internally for optimistic file updates.
// It must not be exposed to an untrusted UI when the file may contain
// environment values; desktop bridges exchange an opaque random token.
Revision string
Backend string
Sessions SessionPolicy
Agents []agent.Spec
Patterns []intercept.Pattern
Policies policy.Config
Audit audit.Config
Notifications notify.Config
Telemetry telemetry.Config
Recording record.Config
Created bool
}
Result describes the effective interception configuration and whether the loader had to create the file during this call.
func LoadExisting ¶
LoadExisting reads and validates an existing configuration without ever creating, replacing or otherwise mutating the path. Everything except first-run bootstrap must use this entry point instead of LoadOrCreate, so a typo or a vanished file cannot materialize a new default configuration as a side effect.
func LoadOrCreate ¶
LoadOrCreate reads path before any PTY is started. It accepts both a direct list and the intercept_patterns wrapper documented in the README. A missing file is populated atomically with the built-in defaults.
Creating a file is a first-run bootstrap behaviour and belongs to the two application entry points alone. Everything else - validating a temporary file, re-reading after a commit, answering a desktop query - must use LoadExisting, so a path that vanished cannot be resurrected with defaults and published over the user's real configuration.
func ReplaceAgents ¶
ReplaceAgents atomically replaces only the version-one agents sequence. It preserves every other YAML node, refuses legacy documents, and verifies the caller's revision immediately before publication.
func UpdateFullConfiguration ¶ added in v0.3.0
func UpdateFullConfiguration(path, expectedRevision string, update FullConfigurationUpdate) (Result, string, error)
UpdateFullConfiguration atomically applies the requested updates to path, verifying expectedRevision first. It preserves unreferenced YAML blocks and comments.
type SessionPolicy ¶
type SessionPolicy struct {
PersistOnExit bool `yaml:"persist_on_exit"`
CleanupOnSuccess bool `yaml:"cleanup_on_success"`
}
SessionPolicy controls ownership of detached backend sessions. PTY sessions are always process-owned and therefore ignore persistence settings.