comment and doc cleanup

micromdm · Aug 23, 2024 · 4c2f0ed · 4c2f0ed
1 parent 1999a46
commit 4c2f0ed
Show file tree

Hide file tree

Showing 11 changed files with 49 additions and 51 deletions.
diff --git a/client/client.go b/client/client.go
@@ -21,7 +21,7 @@ type Config struct {
 }
 
 type ConfigRetriever interface {
-	// RetrieveConfig reads the DEP name config of name.
+	// RetrieveConfig retrieves config of name (DEP name).
 	// If the DEP name or config does not exist then a nil config and
 	// nil error should be returned.
 	RetrieveConfig(ctx context.Context, name string) (*Config, error)

diff --git a/client/transport.go b/client/transport.go
@@ -41,7 +41,7 @@ func GetName(ctx context.Context) string {
 }
 
 type AuthTokensRetriever interface {
-	// RetrieveAuthTokens reads the OAuth tokens from storage for name (DEP name).
+	// RetrieveAuthTokens retrieves the OAuth tokens from storage for name (DEP name).
 	// If the name or tokens do not exist storage.ErrNotFound should be returned.
 	RetrieveAuthTokens(ctx context.Context, name string) (*OAuth1Tokens, error)
 }

diff --git a/docs/operations-guide.md b/docs/operations-guide.md
@@ -57,12 +57,12 @@ Configure the `file` storage backend. This backend manages DEP authentication an
 * `-storage file.deprecated`
 
 > [!WARNING]
-> The `file.deprecated` (formerly the default `file` backend) will be removed from a future NanoDEP release.
+> The `file.deprecated` (formerly the default `file` backend) will be removed in a future NanoDEP release.
 
 Configure the `file.deprecated` storage backend. This backend manages DEP authentication and configuration data within plain filesystem files and directories. It has zero dependencies and should run out of the box. The `-storage-dsn` flag specifies the filesystem directory for the database. If no `storage-dsn` is specified then `db` is used as a default.
 
 > [!NOTE]
-> This was previously the default `file` storage backend in NanoDEP v0.4 and below. 
+> This was previously the default `file` storage backend in NanoDEP v0.4 and below.
 
 *Example:* `-storage file.deprecated -storage-dsn /path/to/my/db`
 

diff --git a/http/api/config.go b/http/api/config.go
@@ -43,7 +43,7 @@ func RetrieveConfigHandler(store client.ConfigRetriever, logger log.Logger) http
 }
 
 type ConfigStorer interface {
-	// StoreConfig stores the DEP name config for name.
+	// StoreConfig stores config for name (DEP name).
 	StoreConfig(ctx context.Context, name string, config *client.Config) error
 }
 

diff --git a/storage/diskv/diskv.go b/storage/diskv/diskv.go
@@ -1,4 +1,4 @@
-// Package diskv implements an engine storage backend using the diskv key-value store.
+// Package diskv implements a NanoDEP storage backend using the diskv key-value store.
 package diskv
 
 import (
@@ -10,7 +10,7 @@ import (
 	"github.com/peterbourgon/diskv/v3"
 )
 
-// Diskv is a a diskv-backed engine storage backend.
+// Diskv is a storage backend that uses diskv.
 type Diskv struct {
 	*kv.KV
 }

diff --git a/storage/file/file.go b/storage/file/file.go
@@ -62,7 +62,7 @@ func (s *FileStorage) tokenpkiFilename(name, kind string) string {
 	return path.Join(s.path, name+".tokenpki."+kind+".txt")
 }
 
-// RetrieveAuthTokens reads the JSON DEP OAuth tokens from disk for name DEP name.
+// RetrieveAuthTokens reads the JSON DEP OAuth tokens from disk for name (DEP name).
 func (s *FileStorage) RetrieveAuthTokens(_ context.Context, name string) (*client.OAuth1Tokens, error) {
 	tokens := new(client.OAuth1Tokens)
 	err := decodeJSONfile(s.tokensFilename(name), tokens)
@@ -72,7 +72,7 @@ func (s *FileStorage) RetrieveAuthTokens(_ context.Context, name string) (*clien
 	return tokens, err
 }
 
-// StoreAuthTokens saves the DEP OAuth tokens to disk as JSON for name DEP name.
+// StoreAuthTokens saves the DEP OAuth tokens to disk as JSON for name (DEP name).
 func (s *FileStorage) StoreAuthTokens(_ context.Context, name string, tokens *client.OAuth1Tokens) error {
 	f, err := os.Create(s.tokensFilename(name))
 	if err != nil {
@@ -105,7 +105,7 @@ func (s *FileStorage) RetrieveConfig(_ context.Context, name string) (*client.Co
 	return config, err
 }
 
-// StoreConfig saves the DEP config to disk as JSON for name DEP name.
+// StoreConfig saves the DEP config to disk as JSON for name (DEP name).
 func (s *FileStorage) StoreConfig(_ context.Context, name string, config *client.Config) error {
 	f, err := os.Create(s.configFilename(name))
 	if err != nil {
@@ -116,7 +116,7 @@ func (s *FileStorage) StoreConfig(_ context.Context, name string, config *client
 }
 
 // RetrieveAssignerProfile reads the assigner profile UUID and its configured
-// timestamp from disk for name DEP name.
+// timestamp from disk for name (DEP name).
 //
 // Returns an empty profile if it does not exist.
 func (s *FileStorage) RetrieveAssignerProfile(_ context.Context, name string) (string, time.Time, error) {
@@ -136,13 +136,13 @@ func (s *FileStorage) RetrieveAssignerProfile(_ context.Context, name string) (s
 	return strings.TrimSpace(string(profileBytes)), modTime, err
 }
 
-// StoreAssignerProfile saves the assigner profile UUID to disk for name DEP name.
+// StoreAssignerProfile saves the assigner profile UUID to disk for name (DEP name).
 func (s *FileStorage) StoreAssignerProfile(_ context.Context, name string, profileUUID string) error {
 	return os.WriteFile(s.profileFilename(name), []byte(profileUUID+"\n"), defaultFileMode)
 }
 
 // RetrieveCursor reads the reads the DEP fetch and sync cursor from disk
-// for name DEP name. We return an empty cursor if the cursor does not exist
+// for name (DEP name). We return an empty cursor if the cursor does not exist
 // on disk.
 func (s *FileStorage) RetrieveCursor(_ context.Context, name string) (string, error) {
 	cursorBytes, err := os.ReadFile(s.cursorFilename(name))
@@ -153,12 +153,12 @@ func (s *FileStorage) RetrieveCursor(_ context.Context, name string) (string, er
 	return strings.TrimSpace(string(cursorBytes)), err
 }
 
-// StoreCursor saves the DEP fetch and sync cursor to disk for name DEP name.
+// StoreCursor saves the DEP fetch and sync cursor to disk for name (DEP name).
 func (s *FileStorage) StoreCursor(_ context.Context, name, cursor string) error {
 	return os.WriteFile(s.cursorFilename(name), []byte(cursor+"\n"), defaultFileMode)
 }
 
-// StoreTokenPKI stores the PEM bytes in pemCert and pemKey to disk for name DEP name.
+// StoreTokenPKI stores the PEM bytes in pemCert and pemKey to disk for name (DEP name).
 func (s *FileStorage) StoreTokenPKI(_ context.Context, name string, pemCert []byte, pemKey []byte) error {
 	if err := os.WriteFile(s.tokenpkiFilename(name, "staging.cert"), pemCert, 0664); err != nil {
 		return err
@@ -204,20 +204,20 @@ func (s *FileStorage) UpstageTokenPKI(ctx context.Context, name string) error {
 }
 
 // RetrieveStagingTokenPKI reads and returns the PEM bytes for the staged
-// DEP token exchange certificate and private key from disk using name DEP name.
+// DEP token exchange certificate and private key from disk using name (DEP name).
 func (s *FileStorage) RetrieveStagingTokenPKI(ctx context.Context, name string) ([]byte, []byte, error) {
 	return s.retrieveTokenPKIExtn(name, "staging.")
 }
 
 // RetrieveCurrentTokenPKI reads and returns the PEM bytes for the previously-
 // upstaged DEP token exchange certificate and private key from disk using
-// name DEP name.
+// name (DEP name).
 func (s *FileStorage) RetrieveCurrentTokenPKI(_ context.Context, name string) ([]byte, []byte, error) {
 	return s.retrieveTokenPKIExtn(name, "")
 }
 
 // retrieveTokenPKIExtn reads and returns the PEM bytes for the DEP token exchange
-// certificate and private key from disk using name DEP name and extn type.
+// certificate and private key from disk using name (DEP name) and extn type.
 func (s *FileStorage) retrieveTokenPKIExtn(name, extn string) ([]byte, []byte, error) {
 	certBytes, err := os.ReadFile(s.tokenpkiFilename(name, extn+"cert"))
 	if err != nil {

diff --git a/storage/inmem/inmem.go b/storage/inmem/inmem.go
@@ -1,4 +1,4 @@
-// Package inmem implements an in-memory storage backend.
+// Package inmem implements an in-memory NanoDEP storage backend.
 package inmem
 
 import (

diff --git a/storage/kv/kv.go b/storage/kv/kv.go
@@ -42,7 +42,7 @@ func New(b kv.Bucket) *KV {
 	return &KV{b: b}
 }
 
-// StoreAuthTokens saves the DEP OAuth tokens to disk as JSON for name DEP name.
+// StoreAuthTokens stores the DEP OAuth tokens for name (DEP name).
 func (s *KV) StoreAuthTokens(ctx context.Context, name string, tokens *client.OAuth1Tokens) error {
 	expiryText, err := tokens.AccessTokenExpiry.MarshalText()
 	if err != nil {
@@ -57,7 +57,7 @@ func (s *KV) StoreAuthTokens(ctx context.Context, name string, tokens *client.OA
 	})
 }
 
-// RetrieveAuthTokens reads the JSON DEP OAuth tokens from disk for name DEP name.
+// RetrieveAuthTokens retrieves the OAuth tokens for name (DEP name).
 func (s *KV) RetrieveAuthTokens(ctx context.Context, name string) (*client.OAuth1Tokens, error) {
 	tokenMap, err := kv.GetMap(ctx, s.b, []string{
 		name + keySfxConsumerKey,
@@ -80,7 +80,7 @@ func (s *KV) RetrieveAuthTokens(ctx context.Context, name string) (*client.OAuth
 	return tokens, tokens.AccessTokenExpiry.UnmarshalText(tokenMap[name+keySfxAccessTokenExpiry])
 }
 
-// StoreConfig saves the DEP config to disk as JSON for name DEP name.
+// StoreConfig stores the config for name (DEP name).
 func (s *KV) StoreConfig(ctx context.Context, name string, config *client.Config) error {
 	configJSON, err := json.Marshal(config)
 	if err != nil {
@@ -89,10 +89,9 @@ func (s *KV) StoreConfig(ctx context.Context, name string, config *client.Config
 	return s.b.Set(ctx, name+keySfxConfig, configJSON)
 }
 
-// RetrieveConfig reads the JSON DEP config of a DEP name.
-//
-// Returns (nil, nil) if the DEP name does not exist, or if the config
-// for the DEP name does not exist.
+// RetrieveConfig retrieves config of name (DEP name).
+// If the DEP name or config does not exist then a nil config and
+// nil error will be returned.
 func (s *KV) RetrieveConfig(ctx context.Context, name string) (*client.Config, error) {
 	configJSON, err := s.b.Get(ctx, name+keySfxConfig)
 	if errors.Is(err, kv.ErrKeyNotFound) {
@@ -104,7 +103,7 @@ func (s *KV) RetrieveConfig(ctx context.Context, name string) (*client.Config, e
 	return config, json.Unmarshal(configJSON, config)
 }
 
-// StoreAssignerProfile saves the assigner profile UUID to disk for name DEP name.
+// StoreAssignerProfile stores the assigner profile UUID for name (DEP name).
 func (s *KV) StoreAssignerProfile(ctx context.Context, name string, profileUUID string) error {
 	modTimeText, err := time.Now().UTC().MarshalText()
 	if err != nil {
@@ -116,9 +115,8 @@ func (s *KV) StoreAssignerProfile(ctx context.Context, name string, profileUUID
 	})
 }
 
-// RetrieveAssignerProfile reads the assigner profile UUID and its configured
-// timestamp from disk for name DEP name.
-//
+// RetrieveAssignerProfile retrieves the assigner profile UUID and its
+// configured timestamp name (DEP name).
 // Returns an empty profile if it does not exist.
 func (s *KV) RetrieveAssignerProfile(ctx context.Context, name string) (string, time.Time, error) {
 	profileMap, err := kv.GetMap(ctx, s.b, []string{
@@ -134,8 +132,8 @@ func (s *KV) RetrieveAssignerProfile(ctx context.Context, name string) (string,
 		modTime.UnmarshalText(profileMap[name+keySfxAssignerProfileModTime])
 }
 
-// RetrieveCursor retrieves the cursor from the key-value store for name DEP name.
-// If the DEP name or cursor does not exist an empty cursor and nil error is be returned.
+// RetrieveCursor retrieves the cursor for name (DEP name).
+// If the DEP name or cursor does not exist an empty cursor and nil error will be returned.
 func (s *KV) RetrieveCursor(ctx context.Context, name string) (string, error) {
 	cursor, err := s.b.Get(ctx, name+keySfxCursor)
 	if errors.Is(err, kv.ErrKeyNotFound) {
@@ -144,12 +142,12 @@ func (s *KV) RetrieveCursor(ctx context.Context, name string) (string, error) {
 	return string(cursor), err
 }
 
-// StoreCursor stores the cursor to disk for name DEP name.
+// StoreCursor stores the cursor for name (DEP name).
 func (s *KV) StoreCursor(ctx context.Context, name, cursor string) error {
 	return s.b.Set(ctx, name+keySfxCursor, []byte(cursor))
 }
 
-// StoreTokenPKI stores the PEM bytes in pemCert and pemKey to disk for name DEP name.
+// StoreTokenPKI stores the PEM bytes in pemCert and pemKey for name (DEP name).
 func (s *KV) StoreTokenPKI(ctx context.Context, name string, pemCert []byte, pemKey []byte) error {
 	return kv.SetMap(ctx, s.b, map[string][]byte{
 		name + keySfxCertStaging: pemCert,
@@ -173,8 +171,8 @@ func (s *KV) UpstageTokenPKI(ctx context.Context, name string) error {
 	})
 }
 
-// RetrieveStagingTokenPKI reads and returns the PEM bytes for the staged
-// DEP token exchange certificate and private key from disk using name DEP name.
+// RetrieveStagingTokenPKI retrieves and returns the PEM bytes for the staged
+// DEP token exchange certificate and private key using name (DEP name).
 func (s *KV) RetrieveStagingTokenPKI(ctx context.Context, name string) ([]byte, []byte, error) {
 	tokenPKIMap, err := kv.GetMap(ctx, s.b, []string{
 		name + keySfxCertStaging,
@@ -188,9 +186,9 @@ func (s *KV) RetrieveStagingTokenPKI(ctx context.Context, name string) ([]byte,
 	return tokenPKIMap[name+keySfxCertStaging], tokenPKIMap[name+keySfxKeyStaging], nil
 }
 
-// RetrieveCurrentTokenPKI reads and returns the PEM bytes for the previously-
-// upstaged DEP token exchange certificate and private key from disk using
-// name DEP name.
+// RetrieveCurrentTokenPKI reads and returns the PEM bytes for the
+// previously-upstaged DEP token exchange certificate and private key
+// using name (DEP name).
 func (s *KV) RetrieveCurrentTokenPKI(ctx context.Context, name string) ([]byte, []byte, error) {
 	tokenPKIMap, err := kv.GetMap(ctx, s.b, []string{
 		name + keySfxCert,

diff --git a/storage/mysql/mysql.go b/storage/mysql/mysql.go
@@ -80,7 +80,7 @@ func New(opts ...Option) (*MySQLStorage, error) {
 
 const timestampFormat = "2006-01-02 15:04:05"
 
-// RetrieveAuthTokens reads the DEP OAuth tokens for name DEP name.
+// RetrieveAuthTokens reads the DEP OAuth tokens for name (DEP name).
 func (s *MySQLStorage) RetrieveAuthTokens(ctx context.Context, name string) (*client.OAuth1Tokens, error) {
 	tokenRow, err := s.q.GetAuthTokens(ctx, name)
 	if err != nil {
@@ -151,7 +151,7 @@ func (s *MySQLStorage) RetrieveConfig(ctx context.Context, name string) (*client
 	}, nil
 }
 
-// StoreConfig saves the DEP config for name DEP name.
+// StoreConfig saves the DEP config for name (DEP name).
 func (s *MySQLStorage) StoreConfig(ctx context.Context, name string, config *client.Config) error {
 	_, err := s.db.ExecContext(
 		ctx, `
@@ -167,7 +167,7 @@ ON DUPLICATE KEY UPDATE
 	return err
 }
 
-// RetrieveAssignerProfile reads the assigner profile UUID and its timestamp for name DEP name.
+// RetrieveAssignerProfile reads the assigner profile UUID and its timestamp for name (DEP name).
 //
 // Returns an empty profile UUID if it does not exist.
 func (s *MySQLStorage) RetrieveAssignerProfile(ctx context.Context, name string) (profileUUID string, modTime time.Time, err error) {
@@ -188,7 +188,7 @@ func (s *MySQLStorage) RetrieveAssignerProfile(ctx context.Context, name string)
 	return
 }
 
-// StoreAssignerProfile saves the assigner profile UUID for name DEP name.
+// StoreAssignerProfile saves the assigner profile UUID for name (DEP name).
 func (s *MySQLStorage) StoreAssignerProfile(ctx context.Context, name string, profileUUID string) error {
 	_, err := s.db.ExecContext(
 		ctx, `
@@ -205,7 +205,7 @@ ON DUPLICATE KEY UPDATE
 	return err
 }
 
-// RetrieveCursor reads the reads the DEP fetch and sync cursor for name DEP name.
+// RetrieveCursor reads the reads the DEP fetch and sync cursor for name (DEP name).
 //
 // Returns an empty cursor if the cursor does not exist.
 func (s *MySQLStorage) RetrieveCursor(ctx context.Context, name string) (string, error) {
@@ -222,7 +222,7 @@ func (s *MySQLStorage) RetrieveCursor(ctx context.Context, name string) (string,
 	return cursor.String, nil
 }
 
-// StoreCursor saves the DEP fetch and sync cursor for name DEP name.
+// StoreCursor saves the DEP fetch and sync cursor for name (DEP name).
 func (s *MySQLStorage) StoreCursor(ctx context.Context, name, cursor string) error {
 	_, err := s.db.ExecContext(
 		ctx, `
@@ -238,7 +238,7 @@ ON DUPLICATE KEY UPDATE
 	return err
 }
 
-// StoreTokenPKI stores the staging PEM bytes in pemCert and pemKey for name DEP name.
+// StoreTokenPKI stores the staging PEM bytes in pemCert and pemKey for name (DEP name).
 func (s *MySQLStorage) StoreTokenPKI(ctx context.Context, name string, pemCert []byte, pemKey []byte) error {
 	_, err := s.db.ExecContext(
 		ctx, `
@@ -267,7 +267,7 @@ func (s *MySQLStorage) UpstageTokenPKI(ctx context.Context, name string) error {
 }
 
 // RetrieveStagingTokenPKI returns the PEM bytes for the staged DEP
-// token exchange certificate and private key using name DEP name.
+// token exchange certificate and private key using name (DEP name).
 func (s *MySQLStorage) RetrieveStagingTokenPKI(ctx context.Context, name string) ([]byte, []byte, error) {
 	keypair, err := s.q.GetStagingKeypair(ctx, name)
 	if err != nil {
@@ -283,7 +283,7 @@ func (s *MySQLStorage) RetrieveStagingTokenPKI(ctx context.Context, name string)
 }
 
 // RetrieveCurrentTokenPKI returns the PEM bytes for the previously-upstaged DEP
-// token exchange certificate and private key using name DEP name.
+// token exchange certificate and private key using name (DEP name).
 func (s *MySQLStorage) RetrieveCurrentTokenPKI(ctx context.Context, name string) (pemCert []byte, pemKey []byte, err error) {
 	keypair, err := s.q.GetCurrentKeypair(ctx, name)
 	if err != nil {

diff --git a/sync/assigner.go b/sync/assigner.go
@@ -13,7 +13,7 @@ import (
 )
 
 type AssignerProfileRetriever interface {
-	// RetrieveAssignerProfile retrieves the assigner profile UUID and timestamp for name DEP name.
+	// RetrieveAssignerProfile retrieves the assigner profile UUID and timestamp for name (DEP name).
 	// If name or assigner profile UUID do not exist returns an empty profile and nil error.
 	RetrieveAssignerProfile(ctx context.Context, name string) (profileUUID string, modTime time.Time, err error)
 }

diff --git a/sync/syncer.go b/sync/syncer.go
@@ -15,11 +15,11 @@ import (
 
 // CursorStorage stores and retrieves fetch and sync cursors.
 type CursorStorage interface {
-	// RetrieveCursor retrieves the cursor from storage for name DEP name.
+	// RetrieveCursor retrieves the cursor from storage for name (DEP name).
 	// If the DEP name or cursor does not exist an empty cursor and nil error should be returned.
 	RetrieveCursor(ctx context.Context, name string) (string, error)
 
-	// StoreCursor stores the cursor to disk for name DEP name.
+	// StoreCursor stores the cursor to disk for name (DEP name).
 	StoreCursor(ctx context.Context, name string, cursor string) error
 }