Merge pull request #241 from Tantalor93/failflag

introduce a fail flag controlling when dnspyre exits with non-zero code

cmd/root.go

@@ -28,6 +28,15 @@ var (
 	benchmark = dnsbench.Benchmark{
 		Writer: os.Stdout,
 	}
+
+	failConditions []string
+)
+
+const (
+	ioerrorFailCondition    = "ioerror"
+	negativeFailCondition   = "negative"
+	errorFailCondition      = "error"
+	idmismatchFailCondition = "idmismatch"
 )
 
 func init() {
@@ -130,6 +139,12 @@ func init() {
 	pApp.Flag("progress", "Controls whether the progress bar is shown. Enabled by default.").
 		Default("true").BoolVar(&benchmark.ProgressBar)
 
+	pApp.Flag("fail", "Controls conditions upon which the dnspyre will exit with a non-zero exit code. Repeatable flag. "+
+		"Supported options are 'ioerror' (fail if there is at least 1 IO error), 'negative' (fail if there is at least 1 negative DNS answer), "+
+		"'error' (fail if there is at least 1 error DNS response), 'idmismatch' (fail there is at least 1 ID mismatch between DNS request and response).").
+		PlaceHolder(ioerrorFailCondition).
+		EnumsVar(&failConditions, ioerrorFailCondition, negativeFailCondition, errorFailCondition, idmismatchFailCondition)
+
 	pApp.Arg("queries", "Queries to issue. It can be a local file referenced using @<file-path>, for example @data/2-domains. "+
 		"It can also be resource accessible using HTTP, like https://raw.githubusercontent.com/Tantalor93/dnspyre/master/data/1000-domains, in that "+
 		"case, the file will be downloaded and saved in-memory. "+
@@ -183,6 +198,30 @@ func Execute() {
 	}
 
 	close(sigsInt)
+
+	if len(failConditions) > 0 {
+		stats := reporter.Merge(&benchmark, res)
+		for _, f := range failConditions {
+			switch f {
+			case ioerrorFailCondition:
+				if stats.Counters.IOError > 0 {
+					os.Exit(1)
+				}
+			case negativeFailCondition:
+				if stats.Counters.Negative > 0 {
+					os.Exit(1)
+				}
+			case errorFailCondition:
+				if stats.Counters.Error > 0 {
+					os.Exit(1)
+				}
+			case idmismatchFailCondition:
+				if stats.Counters.IDmismatch > 0 {
+					os.Exit(1)
+				}
+			}
+		}
+	}
 }
 
 func getSupportedDNSTypes() []string {

docs/failoncondition.md

@@ -0,0 +1,29 @@
+---
+title: Fail on condition
+layout: default
+parent: Examples
+---
+
+
+
+# Fail on condition
+v3.1.0
+{: .label .label-yellow }
+*dnspyre* by default always returns a zero exit code, but this behaviour can be adjusted by using `--fail <condition>` flag, 
+which can be used to specify predefined conditions that will cause a *dnspyre* to return a non-zero exit code.
+
+Currently, the dnspyre supports these fail conditions:
+* `ioerror` = *dnspyre* exits with a non-zero status code if there is at least 1 IO error (*dnspyre* failed to send DNS request or receive DNS response)
+* `negative` = *dnspyre* exits with a non-zero status code if there is at least 1 negative DNS answer (`NXDOMAIN` or `NODATA` response)
+* `error` = *dnspyre* exits with a non-zero status code if there is at least 1 error DNS response (`SERVFAIL`, `FORMERR`, `REFUSED`, etc.)
+* `idmismatch` = *dnspyre* exits with a non-zero status code if there is at least 1 ID mismatch between DNS request and response
+
+So for example to return a non-zero exit code, when benchmark fails to send request or receive response you would specify `--fail ioerror` flag
+```
+dnspyre --server 1.2.3.4 google.com --fail ioerror
+```
+
+These fail conditions can be combined, this is achieved by repeating the `--flag` flag multiple times with different conditions.
+```
+dnspyre --server 8.8.8.8 nxdomain.cz  --fail ioerror --fail error --fail negative
+```

docs/index.md

@@ -82,6 +82,10 @@ Flags:
                                duration, the benchmark is canceled. This option is exclusive with --number option. The duration is
                                specified in GO duration format e.g. 10s, 15m, 1h.
       --[no-]progress          Controls whether the progress bar is shown. Enabled by default.
+      --fail=ioerror ...       Controls conditions upon which the dnspyre will exit with a non-zero exit code. Repeatable flag.
+                               Supported options are 'ioerror' (fail if there is at least 1 IO error), 'negative' (fail if there is at
+                               least 1 negative DNS answer), 'error' (fail if there is at least 1 error DNS response), 'idmismatch'
+                               (fail there is at least 1 ID mismatch between DNS request and response).
       --[no-]version           Show application version.
 
 Args: