✨ (go-test): add graceful shutdown sample

Author: yuanyu90221

.github/workflows/go.yml

@@ -0,0 +1,24 @@
+name: Go
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+jobs:
+  build_and_test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: 'stable'
+          check-latest: true
+      - name: Setup dependency
+        run: go mod tidy
+      - name: Test
+        run: go test -v ./internal/...

.gitignore

@@ -0,0 +1,33 @@
+# If you prefer the allow list template instead of the deny list, see community template:
+# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
+#
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Code coverage profiles and other test artifacts
+*.out
+coverage.*
+*.coverprofile
+profile.cov
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+# Go workspace file
+go.work
+go.work.sum
+
+# env file
+.env
+
+# Editor/IDE
+# .idea/
+# .vscode/
+bin

Makefile

@@ -0,0 +1,11 @@
+build:
+	@CGO_ENABLED=0 GOOS=linux go build -o bin/main cmd/main.go
+
+run: build
+	@./bin/main
+
+coverage:
+	@go test -v -cover ./internal/...
+
+test:
+	@go test -v ./internal/...

README.md

@@ -0,0 +1,80 @@
+# golang-graceful-shutdown
+
+This repository is to demo how to implement graceful shutdown with golang
+
+# concept
+
+Why Graceful shutdwon ?
+
+1. Release Resource Properly
+2. Prevent Memory Leak for unexpected interrupt
+
+
+# technical design
+
+## seperate create http server struct and run server 
+
+1. Build
+```golang
+type Server struct {
+	server *http.Server
+}
+
+func NewServer() *Server {
+	mux := http.NewServeMux()
+
+	mux.HandleFunc("/slow", func(w http.ResponseWriter, r *http.Request) {
+		log.Println("Slow request started...")
+		time.Sleep(8 * time.Second)
+		fmt.Fprintf(w, "Slow request completed at %v\n", time.Now())
+	})
+	return &Server{
+		server: &http.Server{
+			Addr:    ":8080",
+			Handler: mux,
+		},
+	}
+}
+```
+
+2. Run
+```golang
+func (s *Server) Run(ctx context.Context,
+	shutdownTimeout time.Duration,
+) error {
+  // Run logic
+}
+```
+
+3. Setup channel for signal system interupt and SIGTERM
+
+```golang
+// just catch any signal below
+stop := make(chan os.Signal, 1)
+signal.Notify(stop, os.Interrupt, syscall.SIGTERM)
+
+select {
+case err := <-serverErr:
+  return err
+case <-stop:
+  log.Println("Shutdown signal received")
+case <-ctx.Done():
+  log.Println("Context cancelled")
+}
+```
+
+4. Shutdown with timeout
+```golang
+shutdownCtx, cancel := context.WithTimeout(
+  context.Background(), // prevent inheriant cancellation
+  shutdownTimeout,
+)
+defer cancel() // clear up resource
+
+if err := s.server.Shutdown(shutdownCtx); err != nil {
+  if closeErr := s.server.Close(); closeErr != nil {
+    return errors.Join(err, closeErr)
+  }
+  return err
+}
+```

cmd/main.go

@@ -0,0 +1,27 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/leetcode-golang-classroom/golang-graceful-shutdown-concept/internal"
+)
+
+func main() {
+	slowResponse := 8 * time.Second
+	slowRequestHandler := func(w http.ResponseWriter, r *http.Request) {
+		log.Println("Slow request started...")
+		time.Sleep(slowResponse)
+		fmt.Fprintf(w, "Slow request completed at %v\n", time.Now())
+	}
+	server := internal.NewServer(":8080", slowRequestHandler)
+	ctx := context.Background()
+	shutdownTimeout := 10 * time.Second
+	if err := server.Run(ctx, shutdownTimeout); err != nil {
+		log.Fatalf("Server error: %v\n", err)
+	}
+
+}

go.mod

@@ -0,0 +1,3 @@
+module github.com/leetcode-golang-classroom/golang-graceful-shutdown-concept
+
+go 1.24.0

internal/server.go

@@ -0,0 +1,81 @@
+package internal
+
+import (
+	"context"
+	"errors"
+	"log"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+)
+
+type Server struct {
+	AppServer *http.Server
+}
+
+/*
+*
+
+	func(w http.ResponseWriter, r *http.Request) {
+			log.Println("Slow request started...")
+			time.Sleep(slowResponse)
+			fmt.Fprintf(w, "Slow request completed at %v\n", time.Now())
+		}
+*/
+func NewServer(addr string, slowHandler func(w http.ResponseWriter, r *http.Request)) *Server {
+	mux := http.NewServeMux()
+
+	mux.HandleFunc("/slow", slowHandler)
+	srv := &Server{
+		AppServer: &http.Server{
+			Addr:    addr,
+			Handler: mux,
+		},
+	}
+	return srv
+}
+
+func (s *Server) Run(ctx context.Context,
+	shutdownTimeout time.Duration,
+) error {
+	// buffer channel for not block for receive signal
+	serverErr := make(chan error, 1)
+	go func() {
+		log.Println("Starting server...")
+		if err := s.AppServer.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
+			serverErr <- err
+		}
+		close(serverErr)
+	}()
+
+	// just catch any signal below
+	stop := make(chan os.Signal, 1)
+	signal.Notify(stop, os.Interrupt, syscall.SIGTERM)
+
+	select {
+	case err := <-serverErr:
+		return err
+	case <-stop:
+		log.Println("Shutdown signal received")
+	case <-ctx.Done():
+		log.Println("Context cancelled")
+	}
+
+	shutdownCtx, cancel := context.WithTimeout(
+		context.Background(), // prevent inheriant cancellation
+		shutdownTimeout,
+	)
+	defer cancel() // clear up resource
+
+	if err := s.AppServer.Shutdown(shutdownCtx); err != nil {
+		if closeErr := s.AppServer.Close(); closeErr != nil {
+			return errors.Join(err, closeErr)
+		}
+		return err
+	}
+
+	log.Println("Server exited gracefully")
+	return nil
+}

internal/server_test.go

@@ -0,0 +1,82 @@
+package internal_test
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"syscall"
+	"testing"
+	"time"
+
+	"github.com/leetcode-golang-classroom/golang-graceful-shutdown-concept/internal"
+)
+
+func TestServerGracefulShutdown(t *testing.T) {
+	slowResponse := 2 * time.Second
+	server := internal.NewServer(":3000", func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(slowResponse)
+		w.Write([]byte("completed"))
+	})
+
+	serverErrorCh := make(chan error)
+	go func() {
+		serverErrorCh <- server.Run(context.Background(), 5*time.Second)
+	}()
+	time.Sleep(1 * time.Millisecond)
+	resp, err := http.Get("http://localhost" + server.AppServer.Addr + "/slow")
+
+	syscall.Kill(syscall.Getpid(), syscall.SIGINT)
+
+	if err != nil {
+		t.Fatalf("unable to send request to server: %v", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		t.Errorf("expected 200 StatusOK, got %d", resp.StatusCode)
+	}
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("unable to read body: %v\n", err)
+	}
+
+	if string(body) != "completed" {
+		t.Errorf("expected body 'completed', got %s", string(body))
+	}
+
+	serverErr := <-serverErrorCh
+	if serverErr != nil {
+		t.Fatalf("expected no server error, got %v", serverErr)
+	}
+}
+
+func TestServerTimeoutDuringShutdown(t *testing.T) {
+	slowResponse := 10 * time.Second
+	server := internal.NewServer(":3001", func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(slowResponse)
+		w.Write([]byte("completed"))
+	})
+
+	serverErrorCh := make(chan error)
+	go func() {
+		serverErrorCh <- server.Run(context.Background(), 5*time.Millisecond)
+	}()
+	requestErrorCh := make(chan error)
+	go func() {
+		_, err := http.Get("http://localhost" + server.AppServer.Addr + "/slow")
+		requestErrorCh <- err
+	}()
+
+	time.Sleep(1 * time.Second)
+	syscall.Kill(syscall.Getpid(), syscall.SIGINT)
+
+	if <-requestErrorCh == nil {
+		t.Errorf("expected client request to fail, but it successded")
+	}
+
+	serverErr := <-serverErrorCh
+	if !errors.Is(serverErr, context.DeadlineExceeded) {
+		t.Errorf("expected 'context.DeadlineExceeded' error, got %v", serverErr)
+	}
+}