Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/noamt/stop
A halting mechanism for Go
https://github.com/noamt/stop
go golang infrastructure
Last synced: 16 days ago
JSON representation
A halting mechanism for Go
- Host: GitHub
- URL: https://github.com/noamt/stop
- Owner: noamt
- License: apache-2.0
- Created: 2018-08-06T06:08:57.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2019-06-25T19:12:36.000Z (over 5 years ago)
- Last Synced: 2024-06-20T12:38:25.542Z (5 months ago)
- Topics: go, golang, infrastructure
- Language: Go
- Homepage:
- Size: 12.7 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.asciidoc
- License: LICENSE
Awesome Lists containing this project
README
= Stop
A `go` library that helps you implement a halting mechanism.
== Use cases
=== Kubernetes pods
Kubernetes provides a way to gracefully shutdown pods using a https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#hook-details[pre-stop hook]; `stop` can be used to communicate the hook to any `go` application.
== Methods
=== OS Signal
This library allows you to handle OS halting signals with either a channel or a callback.
==== Channel
[source,go]
----
import "github.com/noamt/stop"
signalChannel := stop.OnOSSignal()
_ = <-signalChannel
// Do stuff
----
==== Callback
[source,go]
----
import "github.com/noamt/stop"
onSignal := func() {
// Do stuff
}
onPanic := func(r interface{}) {
// Panic handler
}
stop.OnOSSignalCall(onSignal, onPanic)
----
=== HTTP
This library allows you to handle halting signals sent over HTTP.
You can either register a handler on your own server, or start a background server on a separate port.
==== Handler
[source,go]
----
import (
"net/http"
"github.com/noamt/stop"
)
m := http.NewServeMux()
s := http.Server{Addr: ":80", Handler: m}
stop.OnHttpCall(m, func(writer http.ResponseWriter, request *http.Request) {
// Do stuff
})
s.ListenAndServe()
----
==== Background Server
[source,go]
----
import (
"net/http"
"github.com/noamt/stop"
)
stop.OnHttpServerCall("localhost", 1337, func(writer http.ResponseWriter, request *http.Request) {
// Do stuff
})
----
=== Customized command
This library uses 2 files as signals - `process.stop` to signal that an application needs to stop and `process.stopped` to signal that the application has successfully stopped.
The `go` application watches for the stop signal file.
When executed, the `stop` command creates the stop signal file, and then watches for the stopped signal with a timeout. This timeout can be set using the `STOP_TIMEOUT_SECONDS` environment variable, and is by default 30 seconds.
Once the `go` application finds the stop signal, it performs all shutdown operations and creates the stopped signal.
The `stop` command finds the stopped signal and returns a successful exit code.
```
------------------
Watch for /tmp/process.stop <--- | go application |
| ------------------
|
------------ \|/
| stop cmd | ---> Create /tmp/process.stop
------------ |
|
------------ \|/
| stop cmd | ---> Watch for /tmp/process.stopped
------------ |
|
\|/ ------------------
Find /tmp/process.stop ---> | go application |
| ------------------
|
\|/ ------------------
Create /tmp/process.stopped <--- | go application |
| ------------------
|
------------ \|/
| stop cmd | <--- Find /tmp/process.stopped
------------
```
==== Usage
===== Application
[source,go]
----
import "github.com/noamt/stop"
stopChannel := stop.ListenForStopSignal()
_ = <-stopChannel
// Do stuff
stop.SignalThatProcessHasStopped()
----
===== Stop command
```
./stop
```