feat: create syscall wrapper for termination signals

Author: josestg

.gitignore

@@ -23,3 +23,6 @@ go.work.sum
 
 # env file
 .env
+
+# Editor
+.idea

README.md

@@ -1 +1,17 @@
-# sigterm
+# sigterm
+
+A subset of the `syscall` package for terminating processes. This package provides a `Signal` type that implements
+the `encoding.TextMarshaller` and `encoding.TextUnmarshaler` interfaces for text-based serialization and deserialization.
+It can be used for configuration management using environment variables[^env_caarlos0] or flags [^flag].
+
+List of termination signals can be found in the GNU libc manual [^gnu_manual].
+
+## Installation
+
+```bash
+go get -u github.com/josestg/sigterm
+```
+
+[^flag]: https://golang.org/pkg/flag/#TextVar
+[^env_caarlos0]: https://github.com/caarlos0/env
+[^gnu_manual]: https://www.gnu.org/software/libc/manual/html_node/Termination-Signals.html

go.mod

@@ -0,0 +1,3 @@
+module github.com/josestg/sigterm
+
+go 1.23.0

sigterm.go

@@ -0,0 +1,90 @@
+package sigterm
+
+import (
+	"encoding"
+	"fmt"
+	"strings"
+	"syscall"
+)
+
+// Signal is a termination signal that is used for initiating the shutdown procedure.
+// This type implements the encoding.TextMarshaller and encoding.TextUnmarshaler interfaces
+// for text-based serialization and deserialization. So, it can be used for configuration
+// management using environment variables or flag.TextVar().
+//
+// List of termination signals can be found in the GNU libc manual:
+// - https://www.gnu.org/software/libc/manual/html_node/Termination-Signals.html
+type Signal syscall.Signal
+
+// Supported shutdown signals.
+const (
+	SIGINT  = Signal(syscall.SIGINT)
+	SIGHUP  = Signal(syscall.SIGHUP)
+	SIGTERM = Signal(syscall.SIGTERM)
+	SIGQUIT = Signal(syscall.SIGQUIT)
+	SIGKILL = Signal(syscall.SIGKILL)
+)
+
+var _signalNames = map[Signal]string{
+	SIGINT:  "SIGINT",
+	SIGHUP:  "SIGHUP",
+	SIGTERM: "SIGTERM",
+	SIGQUIT: "SIGQUIT",
+	SIGKILL: "SIGKILL",
+}
+
+var (
+	_ encoding.TextMarshaler   = (*Signal)(nil)
+	_ encoding.TextUnmarshaler = (*Signal)(nil)
+)
+
+// Unwrap returns the syscall.Signal value of the sigterm.Signal.
+func (s Signal) Unwrap() syscall.Signal {
+	return syscall.Signal(s)
+}
+
+// String returns the string representation of the signal.
+func (s Signal) String() string {
+	if name, ok := _signalNames[s]; ok {
+		return name
+	}
+	return fmt.Sprintf("sigterm.Signal(%d): unknown signal", s)
+}
+
+func (s Signal) MarshalText() ([]byte, error) {
+	return []byte(s.String()), nil
+}
+
+func (s *Signal) UnmarshalText(b []byte) error {
+	text := string(b)
+	for sig, name := range _signalNames {
+		if strings.EqualFold(text, name) {
+			*s = sig
+			return nil
+		}
+	}
+	return fmt.Errorf("unknown termination signal: %s", text)
+}
+
+type signalValue interface {
+	syscall.Signal | Signal
+}
+
+// IsTermination returns true if the given sigterm.Signal or syscall.Signal is a termination signal.
+func IsTermination[T signalValue](sig T) bool {
+	switch t := any(sig).(type) {
+	case Signal:
+		return IsTermination(t.Unwrap())
+	case syscall.Signal:
+		switch t {
+		case
+			syscall.SIGINT,
+			syscall.SIGHUP,
+			syscall.SIGTERM,
+			syscall.SIGQUIT,
+			syscall.SIGKILL:
+			return true
+		}
+	}
+	return false
+}

sigterm_test.go

@@ -0,0 +1,126 @@
+package sigterm
+
+import (
+	"syscall"
+	"testing"
+)
+
+func TestSignal_String(t *testing.T) {
+	tests := []struct {
+		name string
+		s    Signal
+		want string
+	}{
+		{name: "Interrupt signal", s: SIGINT, want: "SIGINT"},
+		{name: "Hangup signal", s: SIGHUP, want: "SIGHUP"},
+		{name: "Terminate signal", s: SIGTERM, want: "SIGTERM"},
+		{name: "Quit signal", s: SIGQUIT, want: "SIGQUIT"},
+		{name: "Kill signal", s: SIGKILL, want: "SIGKILL"},
+		{name: "Unknown signal", s: -1, want: "sigterm.Signal(-1): unknown signal"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := tt.s.String(); got != tt.want {
+				t.Errorf("String() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestSignal_Unwrap(t *testing.T) {
+	if SIGTERM.Unwrap() != syscall.SIGTERM {
+		t.Errorf("Unwrap() = %v, want %v", SIGTERM.Unwrap(), syscall.SIGTERM)
+	}
+}
+
+func TestSignal_UnmarshalText(t *testing.T) {
+	tests := []struct {
+		name    string
+		text    []byte
+		wantErr bool
+	}{
+		{name: "Interrupt signal", text: []byte("SIGINT"), wantErr: false},
+		{name: "Hangup signal", text: []byte("SIGHUP"), wantErr: false},
+		{name: "Terminate signal", text: []byte("SIGTERM"), wantErr: false},
+		{name: "Quit signal", text: []byte("SIGQUIT"), wantErr: false},
+		{name: "Kill signal", text: []byte("SIGKILL"), wantErr: false},
+		{name: "Empty signal", text: []byte(""), wantErr: true},
+		{name: "Invalid signal", text: []byte("SIG_UNKNOWN"), wantErr: true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var s Signal
+			if err := s.UnmarshalText(tt.text); (err != nil) != tt.wantErr {
+				t.Errorf("UnmarshalText() error = %v, wantErr %v", err, tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestSignal_MarshalText(t *testing.T) {
+	tests := []struct {
+		name    string
+		s       Signal
+		wantErr bool
+	}{
+		{name: "Interrupt signal", s: SIGINT, wantErr: false},
+		{name: "Hangup signal", s: SIGHUP, wantErr: false},
+		{name: "Terminate signal", s: SIGTERM, wantErr: false},
+		{name: "Quit signal", s: SIGQUIT, wantErr: false},
+		{name: "Kill signal", s: SIGKILL, wantErr: false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := tt.s.MarshalText()
+			if (err != nil) != tt.wantErr {
+				t.Errorf("MarshalText() error = %v, wantErr %v", err, tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestIsTermination(t *testing.T) {
+	t.Run("sigterm.Signal", func(t *testing.T) {
+		tests := []struct {
+			name string
+			sig  Signal
+			want bool
+		}{
+			{name: "Interrupt signal", sig: SIGINT, want: true},
+			{name: "Hangup signal", sig: SIGHUP, want: true},
+			{name: "Terminate signal", sig: SIGTERM, want: true},
+			{name: "Quit signal", sig: SIGQUIT, want: true},
+			{name: "Kill signal", sig: SIGKILL, want: true},
+			{name: "Unknown signal", sig: -1, want: false},
+		}
+		for _, tt := range tests {
+			t.Run(tt.name, func(t *testing.T) {
+				if got := IsTermination(tt.sig); got != tt.want {
+					t.Errorf("IsTermination() = %v, want %v", got, tt.want)
+				}
+			})
+		}
+	})
+
+	t.Run("syscall.Signal", func(t *testing.T) {
+		tests := []struct {
+			name string
+			sig  syscall.Signal
+			want bool
+		}{
+			{name: "Interrupt signal", sig: syscall.SIGINT, want: true},
+			{name: "Hangup signal", sig: syscall.SIGHUP, want: true},
+			{name: "Terminate signal", sig: syscall.SIGTERM, want: true},
+			{name: "Quit signal", sig: syscall.SIGQUIT, want: true},
+			{name: "Kill signal", sig: syscall.SIGKILL, want: true},
+			{name: "Unknown signal", sig: syscall.SIGSEGV, want: false},
+		}
+		for _, tt := range tests {
+			t.Run(tt.name, func(t *testing.T) {
+				if got := IsTermination(tt.sig); got != tt.want {
+					t.Errorf("IsTermination() = %v, want %v", got, tt.want)
+				}
+			})
+		}
+	})
+}