So far we've managed to take a look at how we can perform execution of other commands and processes, as well as how we can manage cancellation when it comes to both using signals and context.context. In this lesson we're going to be applying everything we've learned through this module in building a brand new application called pguard. The inspiration for this application is based on the timeout command found in Unix systems. The timeout command is a command that allows you to timeout applications after a given amount of time. For example here I'm specifying timeout 5, which means any command I pass into this command I want to be timed out after 5 seconds.

For example if we go ahead and call the sleep command for 10 seconds with the timeout command of 5 seconds you'll see even though the command sleep will sleep for 10 seconds it actually shuts down after 5. As you can see the timeout command will kill the subprocess after the specified amount of time has passed. This makes it very useful to constrain the amount of time a process has to execute and complete, preventing it from hanging indefinitely or consuming more resources over a long period of time. This can be rather useful on more resource constrained systems, or just when processing data from an untrusted external source. Therefore we're going to go ahead and implement a very similar feature when it comes to our own code.

In any case let's go about setting up our application. First creating the pguard directory as follows and then cd-ing in. Then we can go ahead and use the go mod init command passing in the name of the application we want to create. In this case github.com/dreamsOfCode-io and we'll call this pguard. Then with the go mod init command ran and our project initialized let's go ahead and create a main.go function and go ahead and define a package called main as well as a main function. With that we now have our basic application stub up and running.

The next thing to do is to go ahead and pull out our arguments. To do so if we quickly look at the design of our app we basically want to call pguard with a timeout variable and then the actual command that we want to run followed by all of the arguments. Therefore in order to capture these variables we can go ahead and define the timeout as being os.args[1] which is going to be the first argument which is this is zero this is one then this will be two the command will be two and the arguments will be three. So we can go ahead and capture these as well. os.args[2] and the args will be os.args[3]. So far so good. Let's just go ahead and print these out to make sure we're actually on the right step.

So timeout will equal timeout, command will equal cmd and args will equal args. Now if I go ahead and run this code and let's go ahead and pass in say 5, then sleep 10 we'll see that the timeout is five the command is sleep and the arguments are 10. So far so good. Next with both our command and arguments defined the next thing we can do is go about setting up our exec command to actually execute them. To do so let's go ahead and import the os.exec package and create a new command using the command function. We could and should use the command context function but we'll take a look at that shortly.

For the meantime let's just make it so that we can actually call our sub command which we can do by parsing in the command and parsing in the args. One thing I've made a mistake on is the args themselves actually need to be a variadic parameter or a slice of parameter. So rather than selecting the third value we actually want to go ahead and select the third onwards which we can do as follows. Then we can go ahead and use the three dots or the ellipsis to expand the arguments slice into our exec command's variadic parameters. Next we then want to go ahead and capture our command which I'm attempting to do so using the cmd let's go ahead and actually change this to cmd.name and we can do that as follows and we'll get rid of the print line statement as well as we don't need it anymore.

Okay now that we've captured our command in a variable called cmd let's go ahead and just run it as follows and for the meantime to squash the timeout error we can just go ahead and assign it to the blank identifier. Also we can leave up these comments actually. Okay with that if we go ahead and run this code passing in 5 sleep 7 we should see that our application will just sleep for seven seconds which it does. Next up we then need to go about adding in the timeout functionality. Currently because we're pulling the timeout variable from the os.args then it currently has a string type. Instead however we're going to need to turn it into a time.Duration and this is our chance to have a little bit more functionality when it comes to our own pguard application instead of using the standard timeout.

In order to turn our timeout from a string to a duration we can use the parseDuration method of the time package which accepts a string and will return a time.Duration or an error in the event that the string can't be parsed. So let's go ahead and use this to capture a duration and we'll also capture the error value here as well and we can go ahead and pass in our timeout string. Then if there's an error let's do a simple log.Fatal line failed to parseDuration and here we're going to go ahead and set the log.SetFlags to be 0 just so that we're not printing out the time or the date.

Okay with our duration defined we can now go about actually using it. To do so we have a couple of different approaches whether it's using a channel or a context.Context. In this case I think the context.Context is going to be more preferable. Therefore let's go ahead and define one as context.WithCancel function which we can go ahead and set to be context.WithTimeout with timeout sorry and we'll pass in our parent context which is going to be the background context as we don't have any parent as well as the duration which is the time duration that we passed from the timeout passed in as an argument. Then let's go ahead and defer a call to cancel for the meantime just to make sure that we are cancelling at the end of our function and we can go ahead and replace the call to exec.Command with a call to exec.CommandContext passing in the context as the first argument.

Now if we go ahead and run this code passing in say 5 seconds as the argument and we'll sleep for 10 we should see the application exit after only 5 seconds which it does. So far so good. Our pguard or timeout function is starting to look very similar to the original behavior. However if I go ahead and run the timeout function and let's say we pass in the five seconds but also pass in echo hello world you'll see that hello world is printed to the console. Therefore we need to go ahead and make sure that we're also printing this out to standard output and standard error. The simplest way to achieve this is to go ahead and just pass this into the actual command as follows: Stdout is equal to the process's standard output so we can get that from the os package and we'll go ahead and set the Stderr to be the os.Stderr as well.

Now if we go ahead and call our command go run with five seconds and we'll do echo hello world we should see this printed to the console as well which it is. But what about standard in? Well if we take a look at the timeout commands and we'll again do five seconds and this might be a bit difficult let's do say wc or w yeah the wc command and you can see it does accept standard input and if I manage to close it in time it will actually print out the values. However if I don't print out in time hello one two three four five you'll see it gets cancelled just beforehand.

Okay so let's go ahead and achieve the same thing when it comes to our code. To do so I believe we can just go ahead and pass in the standard input stream as follows and if we go ahead and run our code again say let's say five seconds and we'll pass in just the wc command this time we can go ahead and type in hello world and if I close it down well the five seconds has passed I'm going to change this to 10. Okay so that definitely works this time let's go ahead and run this with the 10 seconds just to make sure that this works and we'll pass it into wc then hello world and we'll do a control and d as you can see it works six seconds so I definitely needed a little more time so far so good our application is starting to run very similar to the timeout command.

So what next well let's see what happens if we run the timeout command and we pass in a SIGINT. Let's say we go ahead and do 10 seconds and we'll sleep for 30 and if we pass control and c you'll see it instantly shuts down currently our command also does that as well if I go ahead and build this just so that we don't get the output and we use pguard and we'll do 10 seconds sleep for 30. If I go ahead and press control and c you'll see it also shuts down so we don't need to add a signal handler there however there may be some situations where we want to do some graceful termination rather than shutting down straight away this is a feature we could actually add to the pguard function in order to separate it from the timeout command we've been using.

As a reference to show what I mean here would be a really simple example of how this looks like so we call our pguard application as follows but rather than using say timeouts which is what we would specify our current flag to be where it will timeout an application after a period of time instead we'll define a flag called graceful which will let the application run as long as it needs to but instead of defining the amount of time that an application has to run we'll define the amount of time an application has after the control+c has been added in order for it to shut down.

In order to do so we're going to need to change our application a little bit further so we can specify either both timeout and graceful shutdown which we can define as the shutdown as follows so in order to achieve this we need to first define a couple of flags let's go ahead and add in the flag package first we'll define a timeout variable which will assign to the value of flag.Duration() which if we take a quick look at the documentation for within the flag package duration file defines a time.Duration flag with a specified name default value and usage string. The argument p points to a time.Duration variable in which to store that's the duration flag this one we want the flag accepts a value acceptable to a parse.Duration in this case I'm going to go ahead and set this to be the duration far and I'll set the timeout as a variable above it this is so we don't have to deal with any pointer dereferencing that's personally I don't like to deal with.

Okay we can pass this in as a reference or as a pointer and we need to set the name which is going to be timeout and we also need to set the default value in this case I'm going to set it to be -1 zero could also work as well although -1 to me just feels a little bit easier to deal with if this is -1 then we know we haven't set this flag lastly let's go ahead and set a usage used to specify a timeout on the actual command.

Okay perfect with that we don't need to use the timeout argument anymore we can just go ahead and get rid of this and let's replace our call to duration with a call to timeout next with our timeout variable defined the next thing we want to do is make sure we actually parse these flags which we can do as follows using the parse function of the flag package now with our flags being passed the next thing we need to do is to make use of the flag arguments instead of the flag arguments which will now be variable depending on whether or not we pass any flags in therefore for the command name let's go ahead and use flag.Arg(0) passing in the nth arg we want in this case I believe it's going to be the 0th arg which is correct because these will all be flags and flag values so therefore we want to take the first argument then for the actual remaining args we can just go ahead and use the flag.Args() function and we'll just take from the subscript and we'll take from the first argument onwards using the following syntax with that our code should now work as expected.

So let's go ahead and quickly test it using the go run command this time passing in the timeout flag of five seconds and we'll do a sleep command of 10 and our code should time out after five seconds which it does so far so good however our code currently doesn't work if we don't pass a timeout argument this is because by default we're setting it to be -1 so as soon as the context is created it's been expired therefore in order to solve this we're going to need to extract our actual context creation so let's go ahead and create a new function called createContext and we'll go ahead and pass in a parent context which we can do as context.Context and we'll return a context.Context and a context.CancelFunc as follows this needs to be a capital C it's my bad.

Okay then we can go ahead and pass in say the timeout which will be a time.Duration. Now we can go ahead and check if timeout is greater than I guess zero that would do greater than or equal to zero I guess then we can go ahead and return a context.WithTimeout and we'll pass in the parent and we'll pass in the timeout otherwise we'll just return a context.WithCancel passing in our context as follows.

Okay with that we can now just go ahead and replace the context.WithTimeout function to a call to createContext passing in our context and passing in the timeout we need to pass in context.Background my mistake now if we go ahead and run this code it should just sleep for 10 seconds before exiting which means our timeout function has now been migrated over to using a command which if we go ahead and test using timeout 3 seconds should work as expected which it does perfect next up let's go ahead and define a time.Duration to store our graceful shutdown which we'll call as graceful and we'll set to be a time.Duration then we can do flag.DurationVar passing in our graceful timeout and we'll set the name of this flag to be graceful as well we'll also go ahead and set this to be -1 by default and used to specify a graceful shutdown time.

Let's say with that we now have our graceful time.Duration defined the next thing to do is to go ahead and make use of it to do so we need to go ahead and intercept the interrupt signal of which we have a couple of ways we can do so the first approach we have is to use the signal.NotifyContext which takes in a parent's context and will allow us to close the context whenever we see the signal come through whilst this approach could work I don't think it's going to be the best approach when it comes to performing cancellation as we don't really want to cancel the timeout as soon as we see a signal interrupt instead we want to send a signal to the process and give it some time to shut down before we call the actual cancel function so instead I think it's going to be better to make use of the signal.Notify function making use of a channel instead.

Therefore let's go ahead and create one using a ch is make(chan os.Signal, 1) and making sure to pass the buffer size of one then we can go ahead and call the signal.Notify passing in our channel and we're capturing the os.Interrupt signal next in order to be able to listen to the interrupt signal as well as being able to start our application at the same time let's go ahead and replace the call to command.Run() with a call to command.Start() as follows this if you'll remember will start the application asynchronously.

Next we then need an approach to be able to listen to both the channel and the completion event of the actual command itself therefore we're going to need to make use of the done channel strategy we saw before so that we're able to listen to both when the application exits but also when we receive a SIGINT therefore let's go ahead and create a new done channel however rather than it being a type of empty struct let's instead make it a type of error that way we can go ahead and report any errors that may take place on the actual command and we can propagate them through to our main application so that we can let other processes know that something went wrong with our subcommand.

So with the done channel defined let's go ahead and actually run a go function or a go routine and we'll go ahead and call the command.Wait() but we'll just pipe the result to the done channel as follows we can also go ahead and close this channel as well afterwards just to be safe okay with that we can now go ahead and add in a select statement to select on both the done channel so case doneCh and if an error occurred we can call the os.Exit(1) function and we'll just do a one let's say we could also write well std.Error in fact actually std.out should be std.error should be written with this following line so we don't need to write to standard error in this case it may be a good idea to do so but for the sake of time I'm not going to.

Next we then want to go ahead and add in a case statement for the ch to read off the signal channel which in this case is as follows next if we do receive an event on the signal we just want to break out of this select statement as follows next we can then go about implementing if I scroll up a little bit next up we can then go about implementing our graceful shutdown which will only occur if we received an interrupt signal on the actual channel to begin we want to make sure we send a signal to the underlying process of our sub command in this case we'll go ahead and send the interrupt signal as follows then the next thing we want to do is make sure we wait for either the command to exit or a timeout to take place unfortunately we've already seen how we can do this we just need to add in another select statement this time selecting on the done channel in this case we're not actually going to capture the return value because if we're shutting down gracefully we don't care too much about the application exiting or though in some cases you may want to just os.Exit(1) in any case if we receive an event on the done channel let's go ahead and just return early we also don't need this return here if we're os.Exiting(1).

Next we then need to implement our actual timeout which we can do as follows making use of the After() function of the time package passing in our graceful shutdown as a time.Duration in this case we don't need to worry too much about if we happen to set a time duration that's in the past as we will just end up shutting down forcefully in either case in this case if we do happen to exceed our graceful shutdown we can go ahead and break out of this and begin sending a kill signal to our underlying process which we can do using the command.Process.Kill() which will cause the application to ultimately exit with that our code should almost be working let's go ahead and run this and we'll do a timeout of say let's do a graceful of 2 and a timeout of 5 and we'll do a sleep of 10 let's also make sure to set these to be seconds as well then if I go ahead and press cancel you can see the graceful shutdown took place pretty much immediately.

So far this is looking like it's working however in order to test this we're going to need to run it against a process that doesn't actually respect the signal interrupt fortunately I've already created an application that will do this for us called stubborn. Here is the code as you can see it's rather simple it will just sleep for an entire minute so you can go ahead and just write this yourself or if you want to you can go ahead and install it using the following go install command of github.com/dreamsOfCode-io/stubborn@latest and this will install it onto your path provided you have go set up correctly.

Now if I go ahead and run this code using the stubborn command you can see I can't actually kill it and I can't do anything instead I need to use pkill and pass in stubborn as follows and it gets terminated so this will basically lock your terminal for a full minute. Now if I go ahead and build the pguard commands using the following go build command which creates the pguard directory then I can go ahead and call it or you can just use the go run command if you want and we can go ahead and set the graceful flag setting it to five seconds which is generous for the stubborn command then we can call our stubborn command as follows.

Now as you can see our terminal is locked and if I press ctrl and c we should see after 5 seconds the graceful shutdown take place which it does with that we've managed to create a brand new application called pguard which has a couple of features associated with it for starters we can use it to time out an application that may be running for a long time as you can see if we run the stubborn commands for five seconds it will shut down after five seconds despite how long it's running and this command and flag are influenced by the timeout function available in unix but we also added in the ability to perform graceful shutdown which will intercept the SIGINTs say ctrl and c and will shut down the application after the allotted time when it comes to pguard.

This is actually a very useful tool to have in certain situations especially when it comes to devops and infrastructure where you want to be able to constrain applications from being shut down so that they have time to do so gracefully but at the same time you do want to kill them after a period of time. This is where we're starting to get into some more systems level interfacing or interaction when it comes to working with go and is what tools such as kubernetes or docker do under the hood when it comes to working with docker containers and other processes.

In any case that wraps up the end of this module where we've taken a look at how to do many different concepts such as executing commands performing cancellation and listening to signals through the use of channels in the next module we're going to be taking a deeper look at the file system and moving on to networking before we move on to module number eight which is where we're going to start creating more powerful command line applications like the one we built in this lesson. In any case now's a good time to reflect on the pguard application and add in some other features that you may feel will be useful for your own situations or just to tinker around with and play a little more. Once you're ready to move on, I'll see you in the next lesson.