feat!: implement gracegroup (#2)

Author: dro-sh

.github/workflows/main.yaml

@@ -24,5 +24,5 @@ jobs:
       - name: lint
         uses: golangci/golangci-lint-action@v8
         with:
-          version: v2.1
+          version: v2.2
 

.golangci.yaml

@@ -0,0 +1,95 @@
+version: "2"
+linters:
+  default: none
+  enable:
+    - errcheck
+    - ineffassign
+    - unused
+    - asasalint
+    - asciicheck
+    - bidichk
+    - containedctx
+    - decorder
+    - errname
+    - errorlint
+    - exhaustive
+    - copyloopvar
+    - forcetypeassert
+    - gochecknoinits
+    - gocognit
+    - goconst
+    - godot
+    - mnd
+    - lll
+    - makezero
+    - nakedret
+    - nestif
+    - nilerr
+    - nilnil
+    - nlreturn
+    - nolintlint
+    - paralleltest
+    - reassign
+    - revive
+    - staticcheck
+    - gosec
+    - unconvert
+    - unparam
+    - whitespace
+    - wsl_v5
+    - wastedassign
+    - dupl
+
+  settings:
+    errcheck:
+      check-type-assertions: true
+      check-blank: true
+    goconst:
+      min-len: 2
+      min-occurrences: 2
+    nakedret:
+      max-func-lines: 30
+    nlreturn:
+      block-size: 4
+    nolintlint:
+      require-explanation: true
+      require-specific: true
+    wsl_v5:
+      allow-first-in-block: true
+      allow-whole-block: false
+      branch-max-lines: 2
+      enable:
+        - err
+      disable:
+        - assign
+        - decl
+    gocognit:
+      min-complexity: 20
+    revive:
+      rules:
+        - name: use-any
+        - name: unexported-naming
+        - name: comment-spacings
+        - name: enforce-repeated-arg-type-style
+          arguments:
+            - funcArgStyle: "full"
+            - funcRetValStyle: "short"
+  exclusions:
+    paths-except:
+      - example/
+
+formatters:
+  enable:
+    - gofumpt
+    - gci
+    - golines
+  settings:
+    gci:
+      sections:
+        - standard
+        - default
+        - localmodule
+    golines:
+      max-len: 120
+      chain-split-dots: true
+

CODEOWNERS

@@ -0,0 +1 @@
+* @dro-sh

README.md

@@ -0,0 +1,56 @@
+# Gracegroup
+
+Gracegroup is a package to execute processes and gracefully shutdown them. API is simple:
+
+1. Add functions to start process and shutdown functions to stop process.
+2. Wait for shutdown.
+
+## Quickstart
+
+Install **gracegroup**:
+
+```bash
+go get -u github.com/dro-sh/gracegroup
+```
+
+Simple example with http server with start and graceful shutdown:
+
+```go
+package main
+
+import (
+	"context"
+	"net/http"
+	"os/signal"
+	"syscall"
+
+	"github.com/dro-sh/gracegroup"
+)
+
+func main() {
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
+	defer stop()
+
+	srv := http.Server{}
+
+	group, err := gracegroup.New(gracegroup.DefaultConfig)
+	if err != nil {
+		panic(err)
+	}
+
+	group.Add(srv.ListenAndServe, srv.Shutdown)
+
+	if err := group.Wait(ctx); err != nil {
+		panic(err)
+	}
+}
+```
+
+## Motivation
+
+Almost all services contain a few executable processes and some of them need to be stopped gracefully, e.g, http server. So there is a need start and gracefully shutdown them. But each process should be start on its own goroutine and each shutdown must meet timeout for shutdown, and each process could initiate shutdown (on error, for example) and shutdown function should not affect to other shutdown functions. And this package indents to make it easy.
+
+How it works:
+
+- Add start and shutdown functions to `gracegroup.Group`.
+- Wait while some of start function returns error on passed context will be canceled.

config.go

@@ -0,0 +1,15 @@
+package gracegroup
+
+import "time"
+
+var DefaultShutdownTimeout = 5 * time.Second
+
+type Config struct {
+	// ShutdownTimeout is the maximum amount of time to wait for execution of all shutdown functions.
+	// After this period, the shutdown process wont be waiting to finish.
+	ShutdownTimeout time.Duration
+}
+
+var DefaultConfig = Config{
+	ShutdownTimeout: DefaultShutdownTimeout,
+}

example/servers.go

@@ -0,0 +1,42 @@
+package main
+
+import (
+	"context"
+	"log"
+	"net/http"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"github.com/dro-sh/gracegroup"
+)
+
+func main() {
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
+	defer stop()
+
+	// some initialization code with db, logger, etc
+	// that has defer functions to close connections, flush buffers, etc
+
+	http.HandleFunc("/ping", func(w http.ResponseWriter, r *http.Request) {
+		if _, err := w.Write([]byte("pong")); err != nil {
+			log.Printf("failed to write response: %v", err)
+		}
+	})
+
+	srv := http.Server{
+		Addr:              ":8080",
+		Handler:           http.DefaultServeMux,
+		ReadHeaderTimeout: 1 * time.Second,
+	}
+
+	group := gracegroup.New(gracegroup.DefaultConfig)
+
+	group.Add(srv.ListenAndServe, srv.Shutdown)
+
+	if err := group.Wait(ctx); err != nil {
+		panic(err) // dont fatal because upper could be defer functions
+	}
+
+	log.Println("server stopped")
+}

go.mod

@@ -0,0 +1,5 @@
+module github.com/dro-sh/gracegroup
+
+go 1.23
+
+require golang.org/x/sync v0.11.0

go.sum

@@ -0,0 +1,2 @@
+golang.org/x/sync v0.11.0 h1:GGz8+XQP4FvTTrjZPzNKTMFtSXH80RAzG+5ghFPgK9w=
+golang.org/x/sync v0.11.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=

group.go

@@ -0,0 +1,122 @@
+package gracegroup
+
+import (
+	"context"
+	"errors"
+	"sync"
+
+	"golang.org/x/sync/errgroup"
+)
+
+type (
+	// StartFn does not accept context as argument because most of start functions do not need it
+	// because then context canceled shutdown functions should be called.
+	// If start fn returns error then group will be shutdown, otherwise it won't.
+	StartFn func() error
+	// ShutdownFn accepts context as argument to handle shutdown timeout and must
+	// support handling timed out context.
+	// If function returns error it wont affect to other shutdown functions.
+	ShutdownFn func(ctx context.Context) error
+)
+
+// Gracegroup is a managare to execute processes and functions to shutdown processes.
+type Group struct {
+	mu sync.Mutex
+
+	cfg         Config
+	startFns    []StartFn
+	shutdownFns []ShutdownFn
+}
+
+func New(cfg Config) *Group {
+	return &Group{
+		cfg:         cfg,
+		startFns:    make([]StartFn, 0),
+		shutdownFns: make([]ShutdownFn, 0),
+	}
+}
+
+// Add adds a start function and a shutdown function to the group.
+// Func does not invoke start func immediately, it will wait for Wait method.
+func (r *Group) Add(start StartFn, shutdown ShutdownFn) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	r.startFns = append(r.startFns, start)
+	r.shutdownFns = append(r.shutdownFns, shutdown)
+}
+
+// Wait does next things:
+//  1. invokes all start functions concurrently,
+//  2. waits one of next condition:
+//     a. passed to Wait context is canceled,
+//     b. one of start functions returns error,
+//  3. invokes all shutdown functions concurrently and waiting while all of them will be finished.
+//
+// If any of start functions return nil then group won't initiate shutdown.
+// If any of shutdown functions returns error it wont stop shutdown process. Shutdown function
+// must support context DeadlineExceeded error and exit on it. Group does not forcelly stop shutdown
+// then context deadline exceeded.
+//
+// Wait could return error from:
+//  1. one of start functions,
+//  2. one of shutdown functions,
+//  3. error from Wait context if it is not context.Calceled error,
+//  4. context.DeadlineExceeded if cfg.ShutdownTimeout is exceeded on shutdown.
+func (r *Group) Wait(ctx context.Context) error {
+	g, ctx := errgroup.WithContext(ctx)
+
+	for _, start := range r.startFns {
+		g.Go(start)
+	}
+
+	err := r.wait(ctx, g)
+
+	shutdownError := r.shutdown()
+
+	return errors.Join(shutdownError, err)
+}
+
+func (r *Group) wait(ctx context.Context, g *errgroup.Group) error {
+	done := make(chan struct{})
+
+	go func() {
+		//nolint:errcheck,gosec // err will be set on errgroup context cause
+		g.Wait()
+
+		close(done)
+	}()
+
+	// no needs set error from ctx or errgroup
+	// because errgroup set error cause to context on wait method
+	// or argument context has error cause
+	select {
+	case <-done:
+	case <-ctx.Done():
+	}
+
+	if err := context.Cause(ctx); !errors.Is(err, context.Canceled) {
+		return err
+	}
+
+	return nil
+}
+
+func (r *Group) shutdown() error {
+	ctx, cancel := context.WithCancel(context.Background())
+
+	if r.cfg.ShutdownTimeout > 0 {
+		ctx, cancel = context.WithTimeout(ctx, r.cfg.ShutdownTimeout)
+	}
+	defer cancel()
+
+	g := &errgroup.Group{}
+
+	for _, shutdownFn := range r.shutdownFns {
+		g.Go(func() error {
+			return shutdownFn(ctx)
+		})
+	}
+
+	return g.Wait()
+}