Initial commit

Author: vivangkumar

.gitignore

@@ -0,0 +1,2 @@
+.idea/
+.DS_STORE

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Vivan Kumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,11 @@
+.PHONY: fmt lint test
+
+lint:
+	go vet  ./...
+	golint ./...
+
+fmt:
+	go fmt -s -w .
+
+test:
+	go test ./... -v

README.md

@@ -0,0 +1,51 @@
+## signal
+
+Reduce OS signal handling boilerplate for Go programs.
+
+This is mostly written for my own use, really.
+Found myself reaching for this bit of code quite often across a few codebases.
+
+## Rationale
+
+This library is intended to be used with long running applications that often rely on OS signals being handled.
+
+It is built on the common Go idiom of propagating context through the function call chain.
+
+## Usage
+
+signal provides a single function that wraps the application with signal handling code, returning a context that is cancelled when a OS signal is sent.
+
+It allows all parts of an application relying on context cancellation to be cancelled together.
+
+It reduces code like this (assuming that a `Run` method is implemented)
+
+```go
+ctx, cancel := context.WithCancel(context.Background())
+go srv.Run(ctx)
+
+sigint := make(chan os.Signal, 1)
+signal.Notify(sigint, os.Interrupt)
+<-sigint
+
+cancel()
+
+// and so on..
+```
+
+into
+
+```go
+ctx := context.Background()
+err := signal.Wrap(ctx, srv, os.Interrupt)
+if err != nil {
+    fmt.Println(err.Error())
+}
+```
+
+## Linting, formatting & tests
+
+```
+make lint
+make fmt
+make test
+```

go.mod

@@ -0,0 +1,3 @@
+module github.com/vivangkumar/signal
+
+go 1.20

signal.go

@@ -0,0 +1,58 @@
+// Package signal provides context cancellation by handling OS signals.
+//
+// It provides a minimal interface to handle commonly occurring repeated
+// go code when building services.
+//
+// It uses the same package name as the go std lib in an effort to ensure
+// that callers don't have to rely on it to implement OS signal handling.
+package signal
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/signal"
+)
+
+// Runner represents a runnable entity.
+type Runner interface {
+	// Run runs the entity with the provided context.
+	Run(ctx context.Context) error
+}
+
+// Wrap provides context cancellation by gracefully handling OS signals.
+//
+// It accepts any type that implements the Runner interface.
+//
+// Typically, this should be used in conjunction with a long running
+// process that relies on contexts for cancellation, ensuring that the
+// chain of function calls that propagate the same context are also
+// cancelled.
+func Wrap(ctx context.Context, r Runner, sig ...os.Signal) error {
+	err := r.Run(signalCtx(ctx, sig...))
+	if err != nil {
+		return fmt.Errorf("signal: %w", err)
+	}
+
+	return nil
+}
+
+// signalCtx returns a context that is cancelled when encountering an OS signal.
+func signalCtx(ctx context.Context, sig ...os.Signal) context.Context {
+	ctx, cancel := context.WithCancel(ctx)
+
+	go func() {
+		c := make(chan os.Signal, len(sig))
+
+		signal.Notify(c, sig...)
+		defer signal.Stop(c)
+
+		select {
+		case <-ctx.Done():
+		case <-c:
+			cancel()
+		}
+	}()
+
+	return ctx
+}

signal_test.go

@@ -0,0 +1,36 @@
+package signal_test
+
+import (
+	"context"
+	"errors"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/vivangkumar/signal"
+)
+
+type app struct{}
+
+func (a app) Run(ctx context.Context) error {
+	// Wait on context to be cancelled.
+	<-ctx.Done()
+	return ctx.Err()
+}
+
+func TestWrap(t *testing.T) {
+	a := app{}
+	ctx := context.Background()
+
+	go func() {
+		// Kill the current process after a second.
+		<-time.After(1 * time.Second)
+		syscall.Kill(syscall.Getpid(), syscall.SIGINT)
+	}()
+
+	err := signal.Wrap(ctx, a, syscall.SIGINT)
+	if !errors.Is(err, context.Canceled) {
+		t.Errorf("expected context cancelled, but got %s", err.Error())
+		t.Fail()
+	}
+}