Runner

Introduction

The Runner is a component written in Go and part of the gocomponents repository. It's designed to simplify the orchestration of system calls and the execution of binaries or bash commands in Go. This component encapsulates a system call, binary, or bash command, and offers various methods to manipulate the object.

Prerequisite

• cd into a empty folder

• execute go mod init demo

• create a file called main.go

• download gocomponents package from github, by execuiting go get -u github.com/tuhin37/gocomponents. Alternatively, you can specify a required version number of this repo by execuiting go get -u github.com/tuhin37/[email protected]

Now you're set to experiment with the runner component. Check out the examples below for more details.

Concepts with exmaples

1. Simple example
2. Console log
3. Timeout
4. Waiting period
5. Logfile
6. Success criteria & callback
7. Newline callback
8. Complete and fail callback
9. Config & status
10. Logs
11. Kill
12. Advanced overrides

Execution architecture

Properties

Parameters	Datatype	Access	spec	R/W methods	Sample value	Default value	Usage	Mehtods associated
id	string	private	autogenerated	R	"20ad0fe445e0fd6e597b7a1ac102a35e"	n/a	uniqie id of each runner instance	.GetConfig()
isConsoleLog	bool	private	user-configurable	RW	false	false	if set ture, system commands output will be printed on console. default=false (disabled	.EnableConsole(), .DisableConsole), .GetConfig()
timeout	int	private	user-configurable	RW	9	0	runner will force terminate the system command execution if it exceeds seconds. ddefault=0 (no-timeout)	.SetTimeout(), .GetConfig()
waitingPeriod	int	private	user-configurable	RW	3	0	runner will wait seconds before executing. default=0 (no delay)	.SetWaitingPeriod(), .GetConfig()
logFile	string	private	user-configurable	RW	"log.md"	""	running will write STDOUT of the system call in this file. default="" (file logging disabled)	.SetLogFile(), .GetConfig()
execuitedAt	int64	private	system-generated	R	1693137765180789285	n/a	the timestamp of the beginning of the command execution (epoch nanosecond). default=0	.GetConfig()
executionTimeNano	int64	private	system-generated	R	10001158509	n/a	execution time / duration of the system call (in nanoseconds). default=0	.GetConfig()
successCriteria	string	private	user-configurable	RW	"icmp"	""	user can provide a phrase/string. the runner will match this string in the output of the system call. if found then state=SUCCESSFUL. default="" (no verification)	.SetSuccessCriteria(), .GetConfig()
status	string	private	system-managed	R	"PENDING"	PENDING	the current state of the runner. possible states: PENDING | RUNNING | COMPLETED | FAILED | TIMEDOUT | SUCCEEDED | KILLED	.GetStatus(), .GetConfig()
sysCmd	string	private	user-configurable	RW	"ping google.com -c 4"	n/a	the system command the user must provide to run	.NewRunner(), .GetConfig()
logBuffer	[]byte	private	system-managed	R	""	""	the STDOUT content of the system call is stored here.	.Logs()
exitCode	int	private	system-managed,	R	0	0	the exit code of the system command after execution	.GetConfig()
cmd	*exec.Cmd	private	system-managed	n/a	n/a	n/a		n/a
onNewLogLineCallback	func([]byte)	private	user-configurable	W	func onNewLineCallback(line []byte) {}	n/a	if attached, an user-defined callback function will be called every time the system call generates a new line in STDOUT. the new line will be injected into the callback function	.SetOnNewLineCallback()
onSuccessCallback	func(*Runner)	private	user-configurable	W	func onSuccessCallback(r *runner.Runner) {}	n/a	if attached, an user-defined callback function will be called if the user-provided verification phrase is found in the output of the system call.	.SetSuccessCriteria()
onCompleteCallback	func(*Runner)	private	user-configurable	W	func onCompleteCallback(r *runner.Runner) {}	n/a	if attached, an user-defined callback function will be called if and when the system call exits with exit-code=0 and verification is disabled	.SetOnCompleteCallback()
onFailCallback	func(*Runner)	private	user-configurable	W	func onFailCallback(r *runner.Runner) {}	n/a	if attached, an user-defined callback function will be called if and when the system call exits with a non-zero status-code	.SetOnFailCallback()
onTimeoutCallback	func(*Runner)	private	user-configurable	W	func timeoutCallback(r *runner.Runner) {}	n/a	if attached an user-defined callback function will be called if and when the system call times out	.SetTimeout()

Execution flow

The execution flow of a runner instance is shown in the diagram bellow. Please note that, even though the execution of a runner instance uses multipel go routines and async function executio, in this diagram the runner instance itself is executed as a synchronous blocking function. However, the user may choose to execute the runner instance as a go routine (async, non-blocking call). In such cases, user will have to manage execution flow using either wait groups, or by using channels.

• Open flowchart live on draw.io

• Open flowchart in actual size

• Download the draw.io file from Google Drive

• Download the local draw.io file from this repository