diff --git a/config/config.go b/config/config.go index a8553a1..1058062 100644 --- a/config/config.go +++ b/config/config.go @@ -41,7 +41,7 @@ type Config struct { LocalVersion uint64 `json:"LocalVersion"` // (D) The local version of this program that is currently running. } -// COnfigJSONParametersExplained() returns a nicely formatted string which +// ConfigJSONParametersExplained() returns a nicely formatted string which // describes all the public variables available to the user for configuration. func ConfigJSONParametersExplained() string { return ` diff --git a/loader/loader.go b/loader/loader.go index 749a893..6ab3a20 100644 --- a/loader/loader.go +++ b/loader/loader.go @@ -48,7 +48,7 @@ func NewLoader(processesPath string) (*Loader, error) { return loader, nil } -// getProcessesFromJSONFile will read in a set of JSON values which define both +// processesFromJSONFile will read in a set of JSON values which define both // the canonical name of the process as well as the command and any associated // parameters to successfully execute that command. A slice containing a // LoaderProcess struct for each individual command to execute will be returned. @@ -185,6 +185,9 @@ func (ldr *Loader) StartSynchronous() []LoaderProcess { return ldr.Processes } +// Run will continuously execute this specific instance of Loader indefinitely. +// Should only be called externally when all configuration options have been +// correctly setup and you wish to execute a set number of processes forever. func (ldr *Loader) Run() { go func() { for 1 == 1 { diff --git a/logger/logger.go b/logger/logger.go index fe9fd0c..a9095e1 100644 --- a/logger/logger.go +++ b/logger/logger.go @@ -83,7 +83,8 @@ func StandardLogger(logBaseName string) error { // CurrentLogContents returns the contents of the current log file that's being // managed by the logger instance. The current log should be active thus -// multiple calls to CurrentLogContents() should give different results. +// multiple calls to CurrentLogContents() should give different results assuming +// the log is being actively written to. func (lgr *Logger) CurrentLogContents() ([]byte, error) { lgr.writer.Flush() @@ -145,6 +146,9 @@ func (lgr *Logger) initLogger(logBaseName string) error { return nil } +// Write satisfies the writer interface for golang. This allows an instance of +// Logger to be passed in to the os/exec library for capturing from both the +// stdout and stderr steams. func (lgr *Logger) Write(p []byte) (n int, err error) { lgr.LogMessage(string(p)) return len(p), nil diff --git a/network/network.go b/network/network.go index 587d6a1..b430d22 100644 --- a/network/network.go +++ b/network/network.go @@ -47,9 +47,11 @@ func NewNetwork() (*Network, error) { return netw, nil } -// this was multi-threaded at first but it had reduced reliability when 20+ -// network requests went out simultaneously. this will run in the background as -// it is so it won't really need to be multithreaded. +// IsInternetReachable will reach out to the internet and attempt to query a +// number of publicly reachable API endpoints or public websites. The list is +// quite extensive and the endpoints targeted should be extremely reliable. If +// a significant ratio of these sites can't be reached then AEN knows that the +// internet is currently unreachable and returns false. func (con *Network) IsInternetReachable() bool { numQueries := len(con.endpoints) diff --git a/profiler/profiler.go b/profiler/profiler.go index ac902ff..ba74230 100644 --- a/profiler/profiler.go +++ b/profiler/profiler.go @@ -108,11 +108,11 @@ func ProfileAsArchive() (*os.File, error) { return tarBall, nil } -// SendArchiveReportAsAttachment will generate each individual piece of the +// SendArchiveProfileAsAttachment will generate each individual piece of the // system profile inside its own file. It will then gzip and tarball the // resulting pieces into a single archive for compressing and convenience -// purposes. The original pieces will be automatically cleaned up the archive -// is generated. +// purposes. The original pieces will be automatically cleaned up when the +// archive is generated. func SendArchiveProfileAsAttachment() (*os.File, error) { filePtr, err := ProfileAsArchive() if err != nil { @@ -124,6 +124,8 @@ func SendArchiveProfileAsAttachment() (*os.File, error) { return filePtr, reporter.SendAttachment(generateEmailSubject(), generateEmailBody(), filePtr) } +// generateEmailSubject will create the necessary formatted and pretty email +// subject and return it for the current profile that was just generated. func generateEmailSubject() string { var buf bytes.Buffer buf.WriteString(PROFILE_EMAIL_SUBJECT) @@ -132,12 +134,16 @@ func generateEmailSubject() string { return string(buf.Bytes()) } +// generateEmailBody will create the necessary email body contents and return it +// for the current profile that was just generated. func generateEmailBody() []byte { var buf bytes.Buffer buf.WriteString("A full system profile is attached.") return buf.Bytes() } +// Run will ensure that the profiler is constantly active and sending out +// new profile updates at the interval defined by CheckInFrequencySeconds. func Run() { // kick off the system profiler loop to send out system profiles at the specified interval go func() { diff --git a/rest/rest.go b/rest/rest.go index 3dc1dcd..d0c143c 100644 --- a/rest/rest.go +++ b/rest/rest.go @@ -53,9 +53,6 @@ const LOG_REST_PATH = "logs" // The REST path name which calls the update handler const UPDATE_REST_PATH = "update" -// The REST path name which calls the config handler -const CONFIG_REST_PATH = "config" - // The REST path name which calls the check in handler const CHECKIN_REST_PATH = "checkin" @@ -107,6 +104,10 @@ func NewRestHandler() (*RestHandler, error) { return &rh, nil } +// buildGorillaPath will build a complete gorilla path argument for the given +// root endpoint and all of the given arguments. Each successive argument will +// be separated by a set of forward slashes to separate it from all the other +// arguments. E.G. root/arg1/arg2/arg3 etc. func buildGorillaPath(root string, arguments ...string) string { var routeBuf bytes.Buffer routeBuf.WriteString("/") @@ -121,6 +122,10 @@ func buildGorillaPath(root string, arguments ...string) string { return routeBuf.String() } +// buildRestPath will generate a full rest path give an endpoint and arguments. +// This is very useful for sending out fully qualified links to specific +// endpoints. This is used for documentation purposes when the REST server +// starts up so the end-user can get notified of all active rest endpoints. func buildRestPath(protocol, host, port, root string, arguments ...string) string { var routeBuf bytes.Buffer routeBuf.WriteString(protocol) @@ -139,10 +144,10 @@ func buildRestPath(protocol, host, port, root string, arguments ...string) strin return routeBuf.String() } -// startupRestServer will start up the local REST server where this remote +// StartupRestServer will start up the local REST server where this remote // machine will listen for incoming commands on. A free port on this local // machine will be automatically detected and used. The randomly chosen -// available port will be logged locally as well as emailed. +// available port will be logged locally as well as reported via email. func (rh *RestHandler) StartupRestServer() error { port, err := freeport.Get() if err != nil { @@ -229,10 +234,10 @@ func (rh *RestHandler) writeResponseAndLog(errorMessage string, httpStatusCode i logger.Lgr.LogMessage(statusBuffer.String()) } -// checkinHandler will handle receiving and verifying check-in commands via REST. -// Check-in commands will notify the remote machine that the remote user would -// like the machine to perform a check-in. A check-in will send all pertinent data -// regarding the current operating status of this remote machine. +// checkinHandler will handle receiving and verifying check-in commands via +// REST. Check-in commands will notify the remote machine that the remote user +// would like the machine to perform a check-in. A check-in will send all +// pertinent data regarding the current operating status of this remote machine. func (rh *RestHandler) checkinHandler(writer http.ResponseWriter, request *http.Request) { var err error @@ -272,9 +277,8 @@ func (rh *RestHandler) checkinHandler(writer http.ResponseWriter, request *http. // executeHandler will handle receiving and verifying execute commands via REST. // Execute commands will allow the local machine to execute the code contained -// at the remote location. Currently considering supporting executables and -// Python files. Should we do a JSON config instead to allow call command, -// parameters, and a location to the file to download all cleanly in one? +// in the body of the POST that is sent. Currently python, shell script, and +// raw binaries are supported. This is an EXTREMELY powerful function. func (rh *RestHandler) executeHandler(writer http.ResponseWriter, request *http.Request) { var err error @@ -334,6 +338,11 @@ func (rh *RestHandler) executeHandler(writer http.ResponseWriter, request *http. return } +// executeLoader will take the type of a file to execute as well as the bytes +// that represent that file. Currently supported file types are python, shell +// script, and raw binaries. executeLoader will create the appropriate loader +// instance based on the file type and then call StartSynchronous. When the +// code is finished the rest command will return the result. func (rh *RestHandler) executeLoader(fileType string, fileContents []byte) error { processMap := make(map[string]string) @@ -487,8 +496,8 @@ func (rh *RestHandler) rebootHandler(writer http.ResponseWriter, request *http.R return } -// logHandler will handle receiving and verifying log retrieval commands? via -// REST. +// logHandler will handle receiving and verifying log retrieval commands via +// REST. Still a work in progress. func (rh *RestHandler) logHandler(writer http.ResponseWriter, request *http.Request) { var err error @@ -524,6 +533,7 @@ func (rh *RestHandler) logHandler(writer http.ResponseWriter, request *http.Requ // updateHandler will handle receiving and verifying update commands via REST. // Update commands will allow the remote user to force a local update given a // specific remote URL - should probably be git for now. +// Still a work in progress. func (rh *RestHandler) updateHandler(writer http.ResponseWriter, request *http.Request) { var err error @@ -613,6 +623,9 @@ func (rh *RestHandler) assetHandler(writer http.ResponseWriter, request *http.Re return } +// actionAssetAndReturn will perform a specific function on the given asset. +// It will specifically empowers the basic CRUD operations described in +// assetHandler(). func (rh *RestHandler) actionAssetAndReturn(action string, assetPath string, writer http.ResponseWriter, request *http.Request) { switch action { diff --git a/updater/updater.go b/updater/updater.go index d23ee62..66be67f 100644 --- a/updater/updater.go +++ b/updater/updater.go @@ -42,6 +42,10 @@ func Run() { }() } +// UpdateNecessary will look at the remotely defined version number as well as +// the locally defined version number and compare the two. Based on the result +// it will recommend a course of action. It will return True is the remote +// version is higher (newer) than the local version. func UpdateNecessary() (bool, error) { localVersion := config.Cfg.LocalVersion @@ -67,7 +71,7 @@ func UpdateNecessary() (bool, error) { } -// getRemoteVersion will grab the version of this program from the remote given +// remoteVersion will grab the version of this program from the remote given // file path where the version number should reside as a whole integer number. // The default project structure is to have this file be named 'version.no' and // queried directly via the github.com API. @@ -97,6 +101,7 @@ func remoteVersion() (uint64, error) { return remoteVersion, nil } +// doUpdate will hopefully someday actually perform the update func doUpdate() error { logger.Lgr.LogMessage("performing an update") return nil diff --git a/utils/utils.go b/utils/utils.go index 00238ef..6aa3056 100644 --- a/utils/utils.go +++ b/utils/utils.go @@ -10,7 +10,6 @@ import ( "path" "path/filepath" "runtime" - "strconv" "strings" "time" ) @@ -18,7 +17,7 @@ import ( // the root asset directory where all the external files used are stored const ASSET_ROOT_DIR = "assets" -// GetAssetPath will return the relative path to the file represented by +// AssetPath will return the relative path to the file represented by // assetName otherwise it will return an error if the file doesn't exist. func AssetPath(assetName string) (string, error) { @@ -31,10 +30,13 @@ func AssetPath(assetName string) (string, error) { return relativePath, nil } -// GetSysAssetPath will return the relative path to the file represented by +// SysAssetPath will return the relative path to the file represented by // assetName but also add in the GOOS after the filename and before the // extension. This allows loading system-specific files with one command instead -// of a complicated switch statement every time. +// of a complicated switch statement every time. For instance if your GOOS == +// "linux" then you can open "config_linux.json" by just asking for +// "config.json". This is extremely powerful and a core component of loading +// system-specific shell commands based on the current GOOS. func SysAssetPath(assetName string) (string, error) { var relativeName bytes.Buffer @@ -75,11 +77,6 @@ func FullDateString() string { return time.Now().String() } -// UnixDateString will return the current time in unix time format as a string. -func UnixDateString() string { - return strconv.FormatInt(time.Now().Unix(), 10) -} - // FullDateStringSafe returns the current time as a string with only file-name // safe characters. Used to quickly and easily generate unique file names based // off of the current system time. @@ -125,6 +122,7 @@ func ReadLines(path string) ([]string, error) { return lines, scanner.Err() } +// ExternalIPAddress will get this current computer's external IP address. // credit to: https://gist.github.com/jniltinho/9788121 func ExternalIPAddress() (string, error) {