From 8a8683e6d97d17c1c1cd9259765341184c6daa3d Mon Sep 17 00:00:00 2001 From: Joshua Rich Date: Sun, 8 Dec 2024 18:11:01 +1000 Subject: [PATCH] style(preferences): :bulb: add more comments --- internal/preferences/context.go | 4 ++++ internal/preferences/device.go | 1 + internal/preferences/hass.go | 3 +++ internal/preferences/mqtt.go | 7 ++++++- internal/preferences/prefs.go | 10 ++++++---- internal/preferences/registration.go | 9 +++++++-- internal/preferences/worker.go | 4 +++- 7 files changed, 30 insertions(+), 8 deletions(-) diff --git a/internal/preferences/context.go b/internal/preferences/context.go index 5ba26920f..79a6aebe7 100644 --- a/internal/preferences/context.go +++ b/internal/preferences/context.go @@ -14,12 +14,14 @@ const ( restAPIURLContextKey contextKey = "restAPIURL" ) +// AppIDToContext will store the given App ID in the context. func AppIDToContext(ctx context.Context, appID string) context.Context { newCtx := context.WithValue(ctx, appIDContextKey, appID) return newCtx } +// AppIDFromContext retrieves the App ID from the context. func AppIDFromContext(ctx context.Context) string { appID, ok := ctx.Value(appIDContextKey).(string) if !ok { @@ -29,12 +31,14 @@ func AppIDFromContext(ctx context.Context) string { return appID } +// RestAPIURLToContext will store the given rest API URL in the context. func RestAPIURLToContext(ctx context.Context, url string) context.Context { newCtx := context.WithValue(ctx, restAPIURLContextKey, url) return newCtx } +// RestAPIURLFromContext will retrieve the rest API URL from the context. func RestAPIURLFromContext(ctx context.Context) string { url, ok := ctx.Value(appIDContextKey).(string) if !ok { diff --git a/internal/preferences/device.go b/internal/preferences/device.go index 77a270855..9e6539d3b 100644 --- a/internal/preferences/device.go +++ b/internal/preferences/device.go @@ -10,6 +10,7 @@ import ( "fmt" ) +// Device contains the device-specific preferences. type Device struct { ID string `toml:"id" validate:"required,ascii"` Name string `toml:"name" validate:"required,ascii"` diff --git a/internal/preferences/hass.go b/internal/preferences/hass.go index 871da8607..7ee95c851 100644 --- a/internal/preferences/hass.go +++ b/internal/preferences/hass.go @@ -17,6 +17,7 @@ const ( WebHookPath = "/api/webhook/" ) +// Hass contains preferences related to connectivity to Home Assistant. type Hass struct { CloudhookURL string `toml:"cloudhook_url,omitempty" json:"cloudhook_url" validate:"omitempty,http_url"` RemoteUIURL string `toml:"remote_ui_url,omitempty" json:"remote_ui_url" validate:"omitempty,http_url"` @@ -31,6 +32,8 @@ var ( ErrSetHassPreference = errors.New("could not set hass preference") ) +// SetHassPreferences will set the Hass preferences to the given values. +// //revive:disable:indent-error-flow func SetHassPreferences(hassPrefs *Hass, regPrefs *Registration) error { if err := prefsSrc.Set("hass.secret", hassPrefs.Secret); err != nil { diff --git a/internal/preferences/mqtt.go b/internal/preferences/mqtt.go index 25e4131d5..25195bc27 100644 --- a/internal/preferences/mqtt.go +++ b/internal/preferences/mqtt.go @@ -13,6 +13,7 @@ import ( "github.com/knadh/koanf/v2" ) +// MQTT contains preferences related to MQTT functionality in Go Hass Agent. type MQTT struct { MQTTServer string `toml:"server,omitempty" validate:"omitempty,uri" kong:"required,help='MQTT server URI. Required.',placeholder='scheme://some.host:port'"` //nolint:lll MQTTUser string `toml:"user,omitempty" validate:"omitempty" kong:"optional,help='MQTT username.'"` @@ -23,6 +24,8 @@ type MQTT struct { var ErrSetMQTTPreference = errors.New("could not set MQTT preference") +// SetMQTTPreferences will set Go Hass Agent's MQTT preferences to the given +// values. func SetMQTTPreferences(prefs *MQTT) error { if err := prefsSrc.Set("mqtt.server", prefs.MQTTServer); err != nil { return fmt.Errorf("%w: %w", ErrSetMQTTPreference, err) @@ -47,6 +50,7 @@ func SetMQTTPreferences(prefs *MQTT) error { return nil } +// GetMQTTPreferences retrieves the current MQTT preferences from file. func GetMQTTPreferences() (*MQTT, error) { var mqttPrefs MQTT // Unmarshal config, overwriting defaults. @@ -57,6 +61,7 @@ func GetMQTTPreferences() (*MQTT, error) { return &mqttPrefs, nil } +// MQTTEnabled will return whether Go Hass Agent will use MQTT. func MQTTEnabled() bool { return prefsSrc.Bool("mqtt.enabled") } @@ -98,7 +103,7 @@ func MQTTOrigin() *mqtthass.Origin { // IsMQTTEnabled is a conveinience function to determine whether MQTT // functionality has been enabled in the agent. -func (p *Preferences) IsMQTTEnabled() bool { +func (p *preferences) IsMQTTEnabled() bool { if p.MQTT != nil { return p.MQTT.MQTTEnabled } diff --git a/internal/preferences/prefs.go b/internal/preferences/prefs.go index 02c7fd2c4..66c163a92 100644 --- a/internal/preferences/prefs.go +++ b/internal/preferences/prefs.go @@ -54,7 +54,7 @@ var ( ) // Default agent preferences. -var defaultAgentPreferences = &Preferences{ +var defaultAgentPreferences = &preferences{ Version: AppVersion, Registered: false, MQTT: &MQTT{ @@ -78,8 +78,8 @@ var ( mu = sync.Mutex{} ) -//nolint:tagalign -type Preferences struct { +// preferences defines all preferences for Go Hass Agent. +type preferences struct { MQTT *MQTT `toml:"mqtt,omitempty"` Registration *Registration `toml:"registration"` Hass *Hass `toml:"hass"` @@ -139,7 +139,7 @@ func Reset(ctx context.Context) error { // Validate ensures the configuration is valid. func Validate() error { - currentPreferences := &Preferences{} + currentPreferences := &preferences{} // Unmarshal current preferences. if err := prefsSrc.UnmarshalWithConf("", currentPreferences, koanf.UnmarshalConf{Tag: "toml"}); err != nil { @@ -203,6 +203,8 @@ func Registered() bool { return prefsSrc.Bool("registered") } +// checkPath checks that the given directory exists. If it doesn't it will be +// created. func checkPath(path string) error { _, err := os.Stat(path) if os.IsNotExist(err) { diff --git a/internal/preferences/registration.go b/internal/preferences/registration.go index 6e56b7be0..39b78a66a 100644 --- a/internal/preferences/registration.go +++ b/internal/preferences/registration.go @@ -11,6 +11,8 @@ import ( "github.com/joshuar/go-hass-agent/internal/validation" ) +// Registration are the preferences that defines how Go Hass Agent registers +// with Home Assistant. type Registration struct { Server string `toml:"server" validate:"required,http_url"` Token string `toml:"token" validate:"required"` @@ -26,10 +28,13 @@ func (p *Registration) Validate() error { return nil } -func (p *Preferences) Server() string { +// Server returns the server that was used for registering Go Hass Agent. +func (p *preferences) Server() string { return p.Registration.Server } -func (p *Preferences) Token() string { +// Token returns the long-lived access token that was used by Go Hass Agent for +// registering with Home Assistant. +func (p *preferences) Token() string { return p.Registration.Token } diff --git a/internal/preferences/worker.go b/internal/preferences/worker.go index c0ea2f24b..b7195d15b 100644 --- a/internal/preferences/worker.go +++ b/internal/preferences/worker.go @@ -21,7 +21,7 @@ type CommonWorkerPrefs struct { // Worker represents a Worker from the point of the preferences package. A // worker has a set of default preferences returned by the DefaultPreferences // method and an ID that uniquely identifies the worker (and its preferences -// file on disk). +// on disk). type Worker[T any] interface { PreferencesID() string DefaultPreferences() T @@ -32,6 +32,7 @@ var ( ErrLoadWorkerPrefs = errors.New("error loading worker preferences") ) +// LoadWorker reads the given worker's preferences from file. func LoadWorker[T any](ctx context.Context, worker Worker[T]) (*T, error) { // Load default worker prefs. var prefs T @@ -64,6 +65,7 @@ func LoadWorker[T any](ctx context.Context, worker Worker[T]) (*T, error) { return &prefs, nil } +// SaveWorker saves the given worker's preferences to file. func SaveWorker[T any](ctx context.Context, worker Worker[T], prefs T) error { // We can't define the structure for every possible worker beforehand, so // use map[string]any as the structure for saving.