Prepare repo to be public

Author: SaiedKazemi

COOKBOOK.txt

@@ -1,4 +1,4 @@
-IRIS COOKBOOK
+IRISCTL COOKBOOK
 
 1. Analyze Command (irisctl analyze)
    1.1. Measurements

DEV.md

@@ -1,51 +1,5 @@
-# CLI
-
-irisctl [--brief] [--curl] [--no-delete] [--no-auto-login] [--verbose] <command>
-
-agents [--tag]
-agents [<agent>...]
-
-analyze [--before] [--after] [--state <state>] [--tag <tag>] [--tags-and] [--links-file <file>]
-analyze hours [--chart]
-analyze tags
-analyze states
-
-auth <subcommand>
-auth login [--cookie]
-auth logout [--cookie]
-auth register <user-details>...
-
-check <subcommand>
-check agents [--uptime] [--net]
-check containers [--errors] [--logs]
-
-maint <subcommand>
-maint dq <queue-name>...
-maint dq --upload <queue-name> <actor-string>
-maint dq --delete <queue-name> <redis-message-id>
-maint delete <meas-uuid>
-
-meas [--state <state>] [--tag <tag>] [--all] [--public]
-meas --uuid <meas-uuid>...
-meas --target-list <meas-uuid> <agent-uuid>
-meas request <meas-md-file>...
-meas delete <meas-uuid>...
-meas edit <meas-uuid> <meas-md-file>
-
-status (has no flags)
-
-targets <subcommand>
-targets all
-targets [--with-conent] key <key>...
-targets upload [--probe] <file>
-targets delete <key>
-
-users <subcommand>
-users me
-users all [--verified]
-users delete [--dry-run] <user-id>...
-users patch <user-id> <user-details>
-users services <meas-uuid>
+The source code for `irisctl` follows specific conventions.
+If you'd like to contribute, please adhere to these guidelines. 
 
 # Naming Conventions
 
@@ -58,7 +12,7 @@ users services <meas-uuid>
 	f<subcmd><flag> // irisctl monitor agents --status => fAgentStatus
 
 
-## cobra.Command Initialization
+# cobra.Command Initialization
 
 ## Usage() and Help() functions should be set where the command is defined.  For example:
 
@@ -86,6 +40,10 @@ users services <meas-uuid>
 		return nil
 	}
 
-## Fatal Functions
-- cliFatal()
-- fatal()
+# Fatal Functions
+	cliFatal() // invalid command line
+	fatal() // errors that should terminate execution
+
+# Annotations
+	// TODO: mark incomplete work or improvements to be made
+	// XXX: mark hacky code that needs a better solution but is left as-is for now

Makefile

@@ -17,12 +17,8 @@ SRC=cmd/irisctl/main.go \
 CMD=irisctl
 
 .PHONY: $(CMD)
-build: $(CMD)
-	@echo cp ./$(CMD) "$(HOME)/Google\\ Drive/My\ Drive/irisctl/$(CMD)"
-
 $(CMD): $(SRC)
 	go build -o $(CMD) ./cmd/irisctl/...
-	@ls -l $(CMD)
 
 .PHONY: tags
 tags:
@@ -32,37 +28,5 @@ good:
 	for i in $(SRC); do echo $$i; gofmt -w -s $$i; done
 	golangci-lint run ./...
 
-wc:
-	wc -l $(SRC)
-
-allmd:
-	./$(CMD) meas all -a allmd
-	jq . allmd | more
-
 users: $(CMD)
-	./$(CMD) users all > /tmp/__
-	jq -r '.results[]|"\(.firstname) \(.lastname) \(.is_active) \(.is_superuser) \(.is_verified)"' /tmp/__
-	rm -f /tmp/__
-
-agents:
-	./$(CMD).good agent all | tee /tmp/__
-	jq -r '.results[] | "\(.uuid) \(.state) \(.parameters.hostname) \(.parameters.version)"' /tmp/__ | awk '{ printf("%s  %s  %-24s %s\n", $$1, $$2, $$3, $$4) }'
-	#rm -f /tmp/__
-
-whatis:
-	-./$(CMD) users all | grep "${UUID}"
-	-./$(CMD) agent all | grep "${UUID}"
-	-./$(CMD) meaas all | grep "${UUID}"
-
-examples:
-	@echo ./$(CMD) analyze runs allmd
-	@echo ./$(CMD) analyze -v runs allmd
-	@echo ./$(CMD) analyze --after 2024-01-01 --state finished -t zeph runs allmd
-	@echo ./$(CMD) analyze -v --after 2024-01-01 --state finished -t zeph runs allmd
-	@echo ./$(CMD) analyze --before 2024-01-01 --state finished -t zeph runs allmd
-	@echo ./$(CMD) analyze -v --after 2024-01-01 --state finished -t zeph runs allmd
-	@echo ./$(CMD) analyze -v --after 2024-01-01 --state finished tags allmd
-	@echo ./$(CMD) analyze -v --after 2024-01-01 --state finished hours allmd
-	@echo ./$(CMD) analyze -v --after 2024-01-01 -t ipv6-hitlist.json runs allmd
-	@echo ./$(CMD) analyze -v --after 2023-09-01 -t ipv6-hitlist.json hours allmd
-	@echo ./$(CMD) analyze -v --after 2023-09-01 -t exhaustive-lip6.json hours allmd
+	./$(CMD) users all | jq -r '.results[]|"\(.firstname) \(.lastname) \(.is_active) \(.is_superuser) \(.is_verified)"'

README.md

@@ -1,11 +1,20 @@
 
 
-`irisctl` is a command line tool to make it easier to work Iris.  It has two main command groups:
+`irisctl` is a command line tool to make it easier for Iris developers
+and users to work Iris.
+
+**IMPORTANT:** Since Iris is not available as a public service at
+this time, `irisctl` unit tests and code coverage are still under
+development.  We will bring `irisctl` up to production-quality
+standards as development continues.
+
+`irisctl` has two main command groups:
+
   - Iris API commands
   - Non-API commands for checking and analyzing Iris data
 
 To build `irisctl` from source, you need the standard developments
-tools (make, git) and also the Go language compiler on your machine.
+tools (`make`, `git`) and also the Go language compiler on your machine.
 ```
 $ cd /to/your/work/directory
 $ git clone https://github.com/dioptra-io/irisctl.git
@@ -20,6 +29,3 @@ for your password (unless the `IRIS_PASSWORD` environment variable
 is set to your password).
 
 There are usage examples in `COOKBOOK.txt`.
-
-Please note that `irisctl` is work-in-progress and currently does
-not meet production-quality requirements (e.g., it lacks unit tests).

cmd/irisctl/main.go

@@ -66,7 +66,7 @@ func main() {
 	irisctlCmd.PersistentFlags().BoolVarP(&fRootVerbose, "verbose", "v", false, "enable verbose mode (more output)")
 	irisctlCmd.PersistentFlags().StringVarP(&fRootJqFilter, "jq-filter", "j", ".", "jq filter")
 	irisctlCmd.PersistentFlags().StringVarP(&fIrisAPIUrl, "iris-api-url", "u", "https://api.iris.dioptra.io", "specify the iris api url")
-    // XXX Instead of hard-coding a default value, we should find a measurement UUID of the user.
+	// TODO: Instead of hard-coding a default value, we should find a measurement UUID of the user.
 	irisctlCmd.PersistentFlags().StringVarP(&fMeasurementUUID, "meas-uuid", "m", "a75482d1-8c5c-4d56-845e-fc3861047992", "specify the measurement uuid for the gusethosue credentials")
 	irisctlCmd.SetUsageFunc(common.Usage)
 	irisctlCmd.SetHelpFunc(common.Help)

internal/analyze/analyze.go

@@ -778,7 +778,7 @@ func measDuration(measurement common.Measurement) int {
 	}
 	durationCS = append(durationCS, float64(s.Sub(c).Seconds()))
 	durationSE = append(durationSE, float64(e.Sub(s).Seconds()))
-	expectedDuration := []time.Duration{5, 24} // XXX Provide command line flags to specify these
+	expectedDuration := []time.Duration{5, 24} // TODO: Provide command line flags to specify these
 	for i, t := range []string{"zeph-gcp-daily.json", "collection:exhaustive"} {
 		if common.MatchTag(measurement.Tags, []string{t}, fAnalyzeTagsAnd) && e.Sub(s) > expectedDuration[i]*time.Hour {
 			return DurationTooLong

internal/list/list.go

@@ -106,7 +106,7 @@ func listArgs(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
-// XXX This function is pretty ugly and needs to be refactored.
+// TODO: This function is pretty ugly and needs to be refactored.
 func list(cmd *cobra.Command, args []string) {
 	if fListUUID {
 		for _, arg := range args {
@@ -218,8 +218,8 @@ func printMeasDetailsBQ(measurement common.Measurement) {
 	}
 
 	fmt.Printf("%s,", measurement.Tool) // tool
-	// XXX We need to parse the target list to determine ipv4 and ipv6 values.
-	//     This is a dirty hack for now and should be cleaned up.
+	// XXX: We need to parse the target list to determine ipv4 and ipv6 values.
+	//      This is a dirty hack for now and should be cleaned up.
 	ipv4 := false
 	ipv6 := false
 	if len(measurement.Agents) > 0 {

internal/maint/maint.go

@@ -15,7 +15,7 @@ import (
 var (
 	// Command, its flags, subcommands, and their flags.
 	//      maint dq <queue-name>...
-	//      maint dq --post <queue-name> [<actor-string>]  (XXX actor-string: watch_measurement_agent)
+	//      maint dq --post <queue-name> [<actor-string>]  (actor-string: watch_measurement_agent)
 	//      maint dq --delete <queue-name> <redis-message-id>
 	//      maint meas delete <meas-uuid>
 	cmdName     = "maint"

internal/users/users.go

@@ -108,18 +108,12 @@ func UsersCmd() *cobra.Command {
 // GetUserPass returns username and password obtained from
 // users/me/services of Iris API.
 //
-// XXX For now, this function receives the measurement UUID from flags
-//
-//	but going forward it might use find a measurement UUID of the user
-//	running this instance of irisctl.
-//
-// XXX We wait one second before returning because we have noticed that
-//
-//	sometimes Iris hasn't fully read the user file that includes the
-//	newly created username and password.
+// TODO: For now, this function receives the measurement UUID from
+//       flags but going forward it might find a measurement UUID of
+//       the user running this instance of irisctl.
 func GetUserPass() (string, error) {
 	if meServices.ClickHouse.Username == "" {
-		uuid := common.RootFlagString("meas-uuid") // it is slightly better than hardcoding the measurement but for now it's adequate
+		uuid := common.RootFlagString("meas-uuid")
 		url := fmt.Sprintf("%s/me/services?measurement_uuid=%v", common.APIEndpoint(common.UsersAPISuffix), uuid)
 		jsonData, err := common.Curl(auth.GetAccessToken(), false, "GET", url)
 		if err != nil {
@@ -129,6 +123,9 @@ func GetUserPass() (string, error) {
 			return "", err
 		}
 	}
+	// We wait one second before returning because we have noticed that
+	// sometimes Iris hasn't fully read the user file that includes the
+	// newly created username and password.
 	time.Sleep(1 * time.Second)
 	return meServices.ClickHouse.Username + ":" + meServices.ClickHouse.Password, nil
 }