feat: graceful shutdown and context helpers (#9)

* feat: graceful shutdown

* docs: add context helpers guide

* test: skip SIGTERM on windows

Author: aryeko

README.md

@@ -136,6 +136,7 @@ See [Architecture Guide](docs/architecture.md) for details.
 - [Error Handling](docs/guides/error-handling.md) — Error patterns and Problem Details
 - [Validation](docs/guides/validation.md) — Input validation patterns
 - [Authentication](docs/guides/authentication.md) — Auth middleware and guards
+- [Context Helpers](docs/guides/context-helpers.md) — Typed context keys and helper functions
 - [Testing](docs/guides/testing.md) — Testing patterns
 - [Comparison](docs/guides/comparison.md) — vs Wire, Fx, and others
 

docs/guides/context-helpers.md

@@ -0,0 +1,128 @@
+# Context Helpers
+
+Go doesn't use decorators. The idiomatic pattern is to attach request-scoped data to `context.Context` using typed keys, then provide small helper functions for setting and retrieving values.
+
+This guide shows the pattern modkit recommends for context helpers, which you can use anywhere in your middleware or handlers.
+
+## Typed Context Keys
+
+Use an unexported key type to avoid collisions with other packages.
+
+```go
+package auth
+
+type userKey struct{}
+
+var userKeyInstance = userKey{}
+```
+
+Keeping the key type and value unexported prevents accidental use from other packages and makes collisions impossible.
+
+## Helper Functions
+
+Wrap `context.WithValue` and `ctx.Value` in helpers so your handlers stay type-safe and readable.
+
+```go
+package auth
+
+import "context"
+
+type User struct {
+    ID    string
+    Email string
+    Role  string
+}
+
+func WithUser(ctx context.Context, user *User) context.Context {
+    return context.WithValue(ctx, userKeyInstance, user)
+}
+
+func UserFromContext(ctx context.Context) (*User, bool) {
+    user, ok := ctx.Value(userKeyInstance).(*User)
+    return user, ok
+}
+```
+
+### Using in Middleware
+
+```go
+func AuthMiddleware(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        user, err := authenticate(r)
+        if err != nil {
+            http.Error(w, "unauthorized", http.StatusUnauthorized)
+            return
+        }
+
+        ctx := auth.WithUser(r.Context(), user)
+        next.ServeHTTP(w, r.WithContext(ctx))
+    })
+}
+```
+
+### Using in Handlers
+
+```go
+func (c *UsersController) Me(w http.ResponseWriter, r *http.Request) {
+    user, ok := auth.UserFromContext(r.Context())
+    if !ok {
+        http.Error(w, "unauthorized", http.StatusUnauthorized)
+        return
+    }
+
+    json.NewEncoder(w).Encode(user)
+}
+```
+
+## Best Practices
+
+- Keep context keys unexported in the package that defines them.
+- Prefer helper functions instead of calling `ctx.Value` directly.
+- Return `nil`/`false` when the value is missing rather than panicking.
+- Treat `context.Context` as request-scoped data only, not as a general dependency container.
+
+Note: some existing modkit docs use exported context keys for brevity. In production code, unexported key types are the recommended practice to avoid collisions.
+
+## Multiple Values
+
+Use a separate key type and helpers for each value you need to store.
+
+```go
+package requestid
+
+import "context"
+
+type requestIDKey struct{}
+
+var requestIDKeyInstance = requestIDKey{}
+
+func WithRequestID(ctx context.Context, id string) context.Context {
+    return context.WithValue(ctx, requestIDKeyInstance, id)
+}
+
+func RequestIDFromContext(ctx context.Context) (string, bool) {
+    id, ok := ctx.Value(requestIDKeyInstance).(string)
+    return id, ok
+}
+```
+
+```go
+package tenant
+
+import "context"
+
+type tenantKey struct{}
+
+var tenantKeyInstance = tenantKey{}
+
+func WithTenant(ctx context.Context, id string) context.Context {
+    return context.WithValue(ctx, tenantKeyInstance, id)
+}
+
+func TenantFromContext(ctx context.Context) (string, bool) {
+    id, ok := ctx.Value(tenantKeyInstance).(string)
+    return id, ok
+}
+```
+
+This keeps each value isolated and avoids type assertions scattered throughout your handlers.

modkit/http/server.go

@@ -1,10 +1,64 @@
 package http
 
-import "net/http"
+import (
+	"context"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+)
 
-var listenAndServe = http.ListenAndServe
+// ShutdownTimeout controls how long the server will wait for in-flight requests
+// to finish after receiving a shutdown signal.
+var ShutdownTimeout = 30 * time.Second
+
+var listenAndServe = func(server *http.Server) error {
+	return server.ListenAndServe()
+}
+
+var shutdownServer = func(ctx context.Context, server *http.Server) error {
+	return server.Shutdown(ctx)
+}
 
 // Serve starts an HTTP server on the given address using the provided handler.
+// It handles SIGINT and SIGTERM for graceful shutdown.
 func Serve(addr string, handler http.Handler) error {
-	return listenAndServe(addr, handler)
+	server := &http.Server{
+		Addr:    addr,
+		Handler: handler,
+	}
+
+	sigCh := make(chan os.Signal, 1)
+	signal.Notify(sigCh, os.Interrupt, syscall.SIGTERM)
+	defer func() {
+		signal.Stop(sigCh)
+		close(sigCh)
+	}()
+
+	errCh := make(chan error, 1)
+	go func() {
+		errCh <- listenAndServe(server)
+	}()
+
+	select {
+	case err := <-errCh:
+		if err == http.ErrServerClosed {
+			return nil
+		}
+		return err
+	case <-sigCh:
+		ctx, cancel := context.WithTimeout(context.Background(), ShutdownTimeout)
+		defer cancel()
+
+		shutdownErr := shutdownServer(ctx, server)
+		err := <-errCh
+		if err == http.ErrServerClosed {
+			err = nil
+		}
+		if shutdownErr != nil {
+			return shutdownErr
+		}
+		return err
+	}
 }

modkit/http/server_test.go

@@ -1,24 +1,36 @@
 package http
 
 import (
+	"context"
 	"errors"
+	"io"
+	"net"
 	"net/http"
+	"os"
+	"runtime"
+	"syscall"
 	"testing"
+	"time"
 )
 
-func TestServe_UsesHTTPServer(t *testing.T) {
+func TestServe_ReturnsErrorWhenServerFailsToStart(t *testing.T) {
 	originalListen := listenAndServe
+	originalShutdown := shutdownServer
 	defer func() {
 		listenAndServe = originalListen
+		shutdownServer = originalShutdown
 	}()
 
 	var gotAddr string
 	var gotHandler http.Handler
-	listenAndServe = func(addr string, handler http.Handler) error {
-		gotAddr = addr
-		gotHandler = handler
+	listenAndServe = func(server *http.Server) error {
+		gotAddr = server.Addr
+		gotHandler = server.Handler
 		return errors.New("boom")
 	}
+	shutdownServer = func(ctx context.Context, server *http.Server) error {
+		return nil
+	}
 
 	router := NewRouter()
 	err := Serve("127.0.0.1:12345", router)
@@ -33,3 +45,133 @@ func TestServe_UsesHTTPServer(t *testing.T) {
 		t.Fatalf("expected error from listenAndServe, got %v", err)
 	}
 }
+
+func TestServe_HandlesSignals_ReturnsNil(t *testing.T) {
+	for _, tt := range []struct {
+		name string
+		sig  os.Signal
+	}{
+		{name: "SIGINT", sig: os.Interrupt},
+		{name: "SIGTERM", sig: syscall.SIGTERM},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			originalListen := listenAndServe
+			originalShutdown := shutdownServer
+			defer func() {
+				listenAndServe = originalListen
+				shutdownServer = originalShutdown
+			}()
+
+			serveStarted := make(chan struct{})
+			shutdownRequested := make(chan struct{})
+
+			listenAndServe = func(server *http.Server) error {
+				close(serveStarted)
+				<-shutdownRequested
+				return http.ErrServerClosed
+			}
+			shutdownServer = func(ctx context.Context, server *http.Server) error {
+				close(shutdownRequested)
+				return nil
+			}
+
+			errCh := make(chan error, 1)
+			go func() {
+				errCh <- Serve("127.0.0.1:12345", NewRouter())
+			}()
+
+			<-serveStarted
+			if tt.sig == syscall.SIGTERM && runtime.GOOS == "windows" {
+				t.Skip("SIGTERM not supported on Windows")
+			}
+			proc, err := os.FindProcess(os.Getpid())
+			if err != nil {
+				t.Fatalf("failed to find process: %v", err)
+			}
+			if err := proc.Signal(tt.sig); err != nil {
+				t.Fatalf("failed to send signal: %v", err)
+			}
+
+			if err := <-errCh; err != nil {
+				t.Fatalf("expected nil on clean shutdown, got %v", err)
+			}
+		})
+	}
+}
+
+func TestServe_ShutdownWaitsForInFlightRequest(t *testing.T) {
+	originalListen := listenAndServe
+	originalShutdown := shutdownServer
+	originalTimeout := ShutdownTimeout
+	defer func() {
+		listenAndServe = originalListen
+		shutdownServer = originalShutdown
+		ShutdownTimeout = originalTimeout
+	}()
+
+	ShutdownTimeout = 2 * time.Second
+
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("failed to listen: %v", err)
+	}
+	addr := ln.Addr().String()
+
+	requestStarted := make(chan struct{})
+	releaseRequest := make(chan struct{})
+
+	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		close(requestStarted)
+		<-releaseRequest
+		w.WriteHeader(http.StatusOK)
+	})
+
+	listenAndServe = func(server *http.Server) error {
+		return server.Serve(ln)
+	}
+	shutdownServer = func(ctx context.Context, server *http.Server) error {
+		return server.Shutdown(ctx)
+	}
+
+	serveErrCh := make(chan error, 1)
+	go func() {
+		serveErrCh <- Serve(addr, handler)
+	}()
+
+	clientErrCh := make(chan error, 1)
+	go func() {
+		resp, err := http.Get("http://" + addr)
+		if err != nil {
+			clientErrCh <- err
+			return
+		}
+		_, _ = io.Copy(io.Discard, resp.Body)
+		_ = resp.Body.Close()
+		clientErrCh <- nil
+	}()
+
+	<-requestStarted
+
+	proc, err := os.FindProcess(os.Getpid())
+	if err != nil {
+		t.Fatalf("failed to find process: %v", err)
+	}
+	if err := proc.Signal(os.Interrupt); err != nil {
+		t.Fatalf("failed to send signal: %v", err)
+	}
+
+	select {
+	case err := <-serveErrCh:
+		t.Fatalf("expected Serve to wait for in-flight request, got %v", err)
+	case <-time.After(200 * time.Millisecond):
+	}
+
+	close(releaseRequest)
+
+	if err := <-serveErrCh; err != nil {
+		t.Fatalf("expected nil on clean shutdown, got %v", err)
+	}
+	if err := <-clientErrCh; err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+}