Updates to comments and CONTRIBUTING.md

CONTRIBUTING.md

@@ -58,16 +58,22 @@ make test
 
 ```bash
 make ops
+
+# build development version that detects race conditions
+make dev
 ```
 
 ## Run
 
 ```bash
 ./build/ops
+
+# run development build
+./build/ops-dev
 ```
 
 - clear database file and log file
 
 ```bash
-./build/ops clean
+./build/ops clear
 ```

cli/commands/clear.go

@@ -8,6 +8,9 @@ import (
 	"github.com/spf13/viper"
 )
 
+/**
+ * Command to remove database and log files
+ */
 func clear() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "clear",

cli/commands/root.go

@@ -6,12 +6,11 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// CommandProps injected props that can be made available to all commands
 type CommandProps struct {
 	UI *ui.UI
 }
 
-// flag var to set verbose logging
-
 // Root builds and returns our root command
 func Root(props *CommandProps) *cobra.Command {
 	var verbose bool

cli/main.go

@@ -13,6 +13,11 @@ import (
 	"github.com/spf13/viper"
 )
 
+/**
+ * Main entry point for all commands
+ * Here we setup environment config via viper
+ */
+
 func setRuntTimeConfig() error {
 	userHomeDir, err := os.UserHomeDir()
 
@@ -57,7 +62,7 @@ func setRuntTimeConfig() error {
 	return nil
 }
 
-// Entry point for the cli.
+// Entry point for the cli
 func main() {
 	log := logger.New()
 

internal/config/interface.go

@@ -48,6 +48,7 @@ type ConfigModel struct {
 	Loaded  time.Time `gorm:"index:,sort:desc"`
 }
 
+// Repo interface representing access to stored configs
 type Repo interface {
 	Get(id int) (*Config, error)
 	GetAll() ([]*Config, error)
@@ -58,6 +59,7 @@ type Repo interface {
 	LastLoaded() (*Config, error)
 }
 
+// Service interface for manipulating configurations
 type Service interface {
 	Get(id int) (*Config, error)
 	GetAll() ([]*Config, error)

internal/config/repo.go

@@ -122,6 +122,7 @@ func (r *SqliteRepo) Delete(id int) error {
 	return r.db.Delete(&ConfigModel{ID: id}).Error
 }
 
+// SetLastLoaded updates a configs "loaded" field to the current timestamp
 func (r *SqliteRepo) SetLastLoaded(id int) error {
 	confModel := ConfigModel{ID: id}
 

internal/config/service.go

@@ -1,37 +1,46 @@
 package config
 
+// ConfigService is an implementation of the config.Service interface
 type ConfigService struct {
 	repo Repo
 }
 
+// NewConfigService returns a new instance of ConfigService
 func NewConfigService(repo Repo) *ConfigService {
 	return &ConfigService{repo: repo}
 }
 
+// Get returns a config by id
 func (s *ConfigService) Get(id int) (*Config, error) {
 	return s.repo.Get(id)
 }
 
+// GetAll returns all stored configs
 func (s *ConfigService) GetAll() ([]*Config, error) {
 	return s.repo.GetAll()
 }
 
+// Create creates a new config
 func (s *ConfigService) Create(conf *Config) (*Config, error) {
 	return s.repo.Create(conf)
 }
 
+// Update updates an existing config
 func (s *ConfigService) Update(conf *Config) (*Config, error) {
 	return s.repo.Update(conf)
 }
 
+// Delete deletes a config
 func (s *ConfigService) Delete(id int) error {
 	return s.repo.Delete(id)
 }
 
+// SetLasLoaded sets the "loaded" field for a config to current timestamp
 func (s *ConfigService) SetLastLoaded(id int) error {
 	return s.repo.SetLastLoaded(id)
 }
 
+// LastLoaded retrieves the most recently loaded config
 func (s *ConfigService) LastLoaded() (*Config, error) {
 	return s.repo.LastLoaded()
 }

internal/core/core.go

@@ -11,17 +11,21 @@ import (
 	"github.com/robgonnella/ops/internal/server"
 )
 
+// EventListener represents a registered listener for database events
 type EventListener struct {
 	id      int
 	channel chan *event.Event
 }
 
+// ServerPollListener represents a registered listener for
+// database server polling
 type ServerPollListener struct {
 	id      int
 	channel chan []*server.Server
 }
 
-// Core represents our core data structure
+// Core represents our core data structure through which the ui can interact
+// with the backend
 type Core struct {
 	ctx                 context.Context
 	cancel              context.CancelFunc
@@ -63,6 +67,9 @@ func New(
 	}
 }
 
+// Stop stops all processes managed by Core
+// The core will be useless after calling stop, a new one must be
+// instantiated to continue.
 func (c *Core) Stop() error {
 	c.discovery.Stop()
 	if c.eventSubscription != 0 {
@@ -72,10 +79,12 @@ func (c *Core) Stop() error {
 	return c.ctx.Err()
 }
 
+// Conf return the currently loaded configuration
 func (c *Core) Conf() config.Config {
 	return *c.conf
 }
 
+// CreateConfig creates a new config in the database
 func (c *Core) CreateConfig(conf config.Config) error {
 	_, err := c.configService.Create(&conf)
 
@@ -86,6 +95,7 @@ func (c *Core) CreateConfig(conf config.Config) error {
 	return nil
 }
 
+// UpdateConfig updates an existing config in the database
 func (c *Core) UpdateConfig(conf config.Config) error {
 	updated, err := c.configService.Update(&conf)
 
@@ -102,6 +112,7 @@ func (c *Core) UpdateConfig(conf config.Config) error {
 	return nil
 }
 
+// SetConfig sets the current active configuration
 func (c *Core) SetConfig(id int) error {
 	conf, err := c.configService.Get(id)
 
@@ -118,18 +129,22 @@ func (c *Core) SetConfig(id int) error {
 	return nil
 }
 
+// DeleteConfig deletes a configuration
 func (c *Core) DeleteConfig(id int) error {
 	return c.configService.Delete(id)
 }
 
+// GetConfigs returns all stored configs
 func (c *Core) GetConfigs() ([]*config.Config, error) {
 	return c.configService.GetAll()
 }
 
+// StartDaemon starts the network monitoring processes in a goroutine
 func (c *Core) StartDaemon() {
 	go c.Monitor()
 }
 
+// RegisterEventListener registers a channel as a listener for database events
 func (c *Core) RegisterEventListener(channel chan *event.Event) int {
 	c.mux.Lock()
 	defer c.mux.Unlock()
@@ -144,6 +159,8 @@ func (c *Core) RegisterEventListener(channel chan *event.Event) int {
 	return listener.id
 }
 
+// RemoveEventListener removes and closes a channel previously
+// registered as a listener
 func (c *Core) RemoveEventListener(id int) {
 	c.mux.Lock()
 	defer c.mux.Unlock()
@@ -161,6 +178,8 @@ func (c *Core) RemoveEventListener(id int) {
 	c.evtListeners = listeners
 }
 
+// RegisterServerPollListener registers a channel as a
+// listener for server polling results
 func (c *Core) RegisterServerPollListener(channel chan []*server.Server) int {
 	c.mux.Lock()
 	defer c.mux.Unlock()
@@ -176,6 +195,8 @@ func (c *Core) RegisterServerPollListener(channel chan []*server.Server) int {
 	return listener.id
 }
 
+// RemoveServerPollListener removes and closes a channel previously
+// registered to listen for server polling results
 func (c *Core) RemoveServerPollListener(id int) {
 	c.mux.Lock()
 	defer c.mux.Unlock()

internal/core/monitor.go

@@ -8,7 +8,8 @@ import (
 	"github.com/robgonnella/ops/internal/server"
 )
 
-// Run runs the sequence driver for the HostInstallStage
+// Monitor starts the processes for monitoring and tracking
+// devices on the configured network
 func (c *Core) Monitor() error {
 	evtReceiveChan := make(chan *event.Event)
 
@@ -35,6 +36,7 @@ func (c *Core) Monitor() error {
 	}
 }
 
+// handles server events from the database
 func (c *Core) handleServerEvent(evt *event.Event) {
 	payload := evt.Payload.(*server.Server)
 
@@ -57,6 +59,7 @@ func (c *Core) handleServerEvent(evt *event.Event) {
 	}
 }
 
+// polls database for all servers within configured network targets
 func (c *Core) pollForDatabaseUpdates() error {
 	pollTime := time.Second * 2
 	errCount := 0

internal/discovery/ansible.go

@@ -15,14 +15,17 @@ import (
 	"github.com/robgonnella/ops/internal/config"
 )
 
+// AnsibleIpScanner is an implementation of the DetailScanner interface
 type AnsibleIpScanner struct {
 	conf config.Config
 }
 
+// NewAnsibleIpScanner returns a new instance of AnsibleIpScanner
 func NewAnsibleIpScanner(conf config.Config) *AnsibleIpScanner {
 	return &AnsibleIpScanner{conf: conf}
 }
 
+// GetServerDetails returns server details using ansible's get-facts module
 func (s *AnsibleIpScanner) GetServerDetails(ctx context.Context, ip string) (*Details, error) {
 	if err := os.Setenv(options.AnsibleHostKeyCheckingEnv, "False"); err != nil {
 		return nil, err

internal/discovery/interface.go

@@ -4,15 +4,18 @@ import "context"
 
 //go:generate mockgen -destination=../mock/discovery/mock_discovery.go -package=mock_discovery . DetailScanner,Scanner
 
+// DetailScanner interface for gathering more details about a device
 type DetailScanner interface {
 	GetServerDetails(ctx context.Context, ip string) (*Details, error)
 }
 
+// Scanner interface for scanning a network for devices
 type Scanner interface {
 	Scan() ([]*DiscoveryResult, error)
 	Stop()
 }
 
+// Service interface for monitoring a network
 type Service interface {
 	MonitorNetwork()
 	Stop()

internal/discovery/nmap.go

@@ -11,15 +11,15 @@ import (
 	"github.com/robgonnella/ops/internal/server"
 )
 
-// NmapScanner implements our discovery service using nmap
+// NmapScanner is an implementation of the Scanner interface
 type NmapScanner struct {
 	ctx     context.Context
 	cancel  context.CancelFunc
 	scanner *nmap.Scanner
 	log     logger.Logger
 }
 
-// NewNmapScanner returns a new intance of nmap network discovery NmapScanner
+// NewNmapScanner returns a new instance of NmapScanner
 func NewNmapScanner(targets []string) (*NmapScanner, error) {
 	log := logger.New()
 
@@ -48,7 +48,8 @@ func NewNmapScanner(targets []string) (*NmapScanner, error) {
 	}, nil
 }
 
-// Stop stop network discover
+// Stop stops network scanning. Once called this scanner will be useless,
+// a new one will need to be instantiated to continue scanning.
 func (s *NmapScanner) Stop() {
 	s.cancel()
 }

internal/discovery/result.go

@@ -11,13 +11,17 @@ const (
 	UnknownDevice
 )
 
+// PortStatus represents possible port statuses
 type PortStatus string
 
 const (
-	PortOpen   PortStatus = "open"
+	// PortOpen status used when a port is marked open
+	PortOpen PortStatus = "open"
+	// PortClosed status used when a port is marked closed
 	PortClosed PortStatus = "closed"
 )
 
+// Port data structure representing a server port
 type Port struct {
 	ID     uint16
 	Status PortStatus
@@ -33,6 +37,7 @@ type DiscoveryResult struct {
 	Ports    []Port
 }
 
+// Details represents the details returned by DetailScanner
 type Details struct {
 	Hostname string
 	OS       string