From 7ed6294563f666ee7ba4df497f7571861a29caff Mon Sep 17 00:00:00 2001
From: Marvin Steadfast <marvin@xsteadfastx.org>
Date: Tue, 15 Jun 2021 10:48:12 +0200
Subject: [PATCH] Check gets Ready and readme

---
 Makefile         |  9 ++++++
 README.md        | 76 ++++++++++++++++++++++++++++++++++++++++++++++++
 cmd/cmds/root.go |  2 +-
 don.go           | 50 +++++++++++++++++++++++++++++--
 4 files changed, 134 insertions(+), 3 deletions(-)
 create mode 100644 README.md

diff --git a/Makefile b/Makefile
index 266967e..8acf0fd 100644
--- a/Makefile
+++ b/Makefile
@@ -22,3 +22,12 @@ test:
 tidy:
 	go mod tidy
 	go mod vendor
+
+.PHONY: readme
+readme:
+	goreadme \
+		-title don \
+		-credit=false \
+		-functions \
+		-types \
+		> README.md
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0f47c68
--- /dev/null
+++ b/README.md
@@ -0,0 +1,76 @@
+# don
+
+Package don is a little helper if you need to check for the readiness of something.
+This could be a command to run (like ssh) or a `db.Ping()` for check of the readiness
+of a database container.
+
+## Use as commandline tool
+
+Download the tool from the [download page](https://git.xsfx.dev/xsteadfastx/don/releases).
+
+```go
+don -t 15m -r 15s -c "ssh -o StrictHostKeyChecking=no -o ConnectTimeout=10 root@container"
+```
+
+This example checks every 15 seconds if the ssh container is ready. It would timeout with an
+error after 15 minutes.
+
+## Use as a library
+
+If you want to use don as a library, it just takes a `func() bool` in `don.Ready()`
+have a function that runs the readiness check and returns `true` or `false` if its
+ready or not. The second argument is the overall timeout and
+the third argument is the check interval. Import it like this:
+
+```go
+import go.xsfx.dev/don
+```
+
+Doing the readiness check like this:
+
+```go
+if err := don.Ready(
+	func() bool {
+		db, err := sql.Open("oracle", dbConn)
+		if err != nil {
+			log.Warn().Err(err).Str("dbConn", dbConn).Msg("could not open connection")
+
+			return false
+		}
+
+		if err := db.Ping(); err != nil {
+			log.Warn().Err(err).Str("dbConn", dbConn).Msg("could not ping")
+
+			return false
+		}
+
+		return true
+	},
+	10*time.Minute,
+	30*time.Second,
+); err != nil {
+	log.Error().Err(err).Msg("received error")
+	teardown(pool, resource, tmpState.Name())
+	os.Exit(1)
+}
+```
+
+## Functions
+
+### func [Cmd](/don.go#L65)
+
+`func Cmd(c string) func() bool`
+
+Cmd returns a `func() bool` for working with don.Check. It executes a command and
+returns a true if everything looks fine or a false if there was some kind of error.
+
+### func [Ready](/don.go#L83)
+
+`func Ready(f func() bool, timeout time.Duration, retry time.Duration) error`
+
+Ready takes a function that executes something and returns a bool to indicate if
+something is ready or not. It returns an error if it timeouts.
+
+## Sub Packages
+
+* [cmd](./cmd)
diff --git a/cmd/cmds/root.go b/cmd/cmds/root.go
index 2c96fba..ec099e5 100644
--- a/cmd/cmds/root.go
+++ b/cmd/cmds/root.go
@@ -30,7 +30,7 @@ var (
 var rootCmd = &cobra.Command{
 	Use: "don [command]",
 	Run: func(cmd *cobra.Command, args []string) {
-		if err := don.Check(don.Cmd(command), timeout, retry); err != nil {
+		if err := don.Ready(don.Cmd(command), timeout, retry); err != nil {
 			log.Fatal().Err(err).Msg("received error")
 		}
 
diff --git a/don.go b/don.go
index ad15583..b53d4a5 100644
--- a/don.go
+++ b/don.go
@@ -1,6 +1,52 @@
 // Package don is a little helper if you need to check for the readiness of something.
 // This could be a command to run (like ssh) or a `db.Ping()` for check of the readiness
 // of a database container.
+//
+// Use as commandline tool
+//
+// Download the tool from the (download page) https://git.xsfx.dev/xsteadfastx/don/releases.
+//
+// 	 don -t 15m -r 15s -c "ssh -o StrictHostKeyChecking=no -o ConnectTimeout=10 root@container"
+//
+// This example checks every 15 seconds if the ssh container is ready. It would timeout with an
+// error after 15 minutes.
+//
+// Use as a library
+//
+// If you want to use don as a library, it just takes a `func() bool` in `don.Ready()`
+// have a function that runs the readiness check and returns `true` or `false` if its
+// ready or not. The second argument is the overall timeout and
+// the third argument is the check interval. Import it like this:
+//
+//	import go.xsfx.dev/don
+//
+// Doing the readiness check like this:
+//
+//	if err := don.Ready(
+//		func() bool {
+//			db, err := sql.Open("oracle", dbConn)
+//			if err != nil {
+//				log.Warn().Err(err).Str("dbConn", dbConn).Msg("could not open connection")
+//
+//				return false
+//			}
+//
+//			if err := db.Ping(); err != nil {
+//				log.Warn().Err(err).Str("dbConn", dbConn).Msg("could not ping")
+//
+//				return false
+//			}
+//
+//			return true
+//		},
+//		10*time.Minute,
+//		30*time.Second,
+//	); err != nil {
+//		log.Error().Err(err).Msg("received error")
+//		teardown(pool, resource, tmpState.Name())
+//		os.Exit(1)
+//	}
+//
 package don
 
 import (
@@ -32,9 +78,9 @@ func Cmd(c string) func() bool {
 	}
 }
 
-// Check takes a function that executes something and returns a bool to indicate if
+// Ready takes a function that executes something and returns a bool to indicate if
 // something is ready or not. It returns an error if it timeouts.
-func Check(f func() bool, timeout time.Duration, retry time.Duration) error {
+func Ready(f func() bool, timeout time.Duration, retry time.Duration) error {
 	chReady := make(chan struct{})
 
 	go func() {