refactor: standardize Go error handling with error chain support

server/api/refresh/index.go

@@ -1,9 +1,11 @@
 package handler
 
 import (
+	"errors"
 	"net/http"
 
 	"github-project-status-viewer-server/pkg/crypto"
+	pkgerrors "github-project-status-viewer-server/pkg/errors"
 	"github-project-status-viewer-server/pkg/httputil"
 	"github-project-status-viewer-server/pkg/jwt"
 	"github-project-status-viewer-server/pkg/oauth"
@@ -43,7 +45,7 @@ func Handler(w http.ResponseWriter, r *http.Request) {
 
 	storedSessionID, err := redisClient.Get(redis.RefreshTokenKeyPrefix + claims.RefreshTokenID)
 	if err != nil {
-		if err == redis.ErrKeyNotFound {
+		if errors.Is(err, pkgerrors.ErrKeyNotFound) {
 			httputil.WriteError(w, http.StatusUnauthorized, "refresh_token_revoked", "Refresh token has been revoked or expired")
 		} else {
 			httputil.WriteError(w, http.StatusInternalServerError, "server_error", "Failed to verify refresh token")

server/api/verify/index.go

@@ -4,6 +4,7 @@ import (
 	"errors"
 	"net/http"
 
+	pkgerrors "github-project-status-viewer-server/pkg/errors"
 	"github-project-status-viewer-server/pkg/httputil"
 	"github-project-status-viewer-server/pkg/jwt"
 	"github-project-status-viewer-server/pkg/oauth"
@@ -42,7 +43,7 @@ func Handler(w http.ResponseWriter, r *http.Request) {
 
 	githubAccessToken, err := redisClient.Get(redis.SessionKeyPrefix + claims.SessionID)
 	if err != nil {
-		if errors.Is(err, redis.ErrKeyNotFound) {
+		if errors.Is(err, pkgerrors.ErrKeyNotFound) {
 			httputil.WriteError(w, http.StatusUnauthorized, "session_not_found", "Session expired or invalid")
 		} else {
 			httputil.WriteError(w, http.StatusInternalServerError, "redis_error", "Failed to retrieve session")

server/pkg/auth/errors.go

@@ -1,7 +1,7 @@
 package auth
 
-import "errors"
+import pkgerrors "github-project-status-viewer-server/pkg/errors"
 
 var (
-	ErrInvalidAuthHeader = errors.New("authorization header must be 'Bearer <token>'")
+	ErrInvalidAuthHeader = pkgerrors.ErrInvalidAuthHeader
 )

server/pkg/crypto/random.go

@@ -3,6 +3,9 @@ package crypto
 import (
 	"crypto/rand"
 	"encoding/hex"
+	"fmt"
+
+	pkgerrors "github-project-status-viewer-server/pkg/errors"
 )
 
 const (
@@ -13,7 +16,7 @@ const (
 func generateRandomHex(byteLength int) (string, error) {
 	bytes := make([]byte, byteLength)
 	if _, err := rand.Read(bytes); err != nil {
-		return "", err
+		return "", fmt.Errorf("%w: %w", pkgerrors.ErrRandomGeneration, err)
 	}
 	return hex.EncodeToString(bytes), nil
 }

server/pkg/errors/types.go

@@ -0,0 +1,51 @@
+package errors
+
+import "errors"
+
+// Configuration errors
+var (
+	ErrJWTSecretMissing    = errors.New("JWT_SECRET not configured")
+	ErrOAuthConfigMissing  = errors.New("OAuth configuration missing")
+	ErrRedisConfigMissing  = errors.New("upstash redis configuration missing")
+	ErrInvalidAuthHeader   = errors.New("authorization header must be 'Bearer <token>'")
+	ErrMissingAuthCode     = errors.New("authorization code is required")
+	ErrMissingStateParam   = errors.New("state parameter is required for CSRF protection")
+	ErrBearerTokenRequired = errors.New("bearer token required")
+)
+
+// Token errors
+var (
+	ErrInvalidTokenFormat        = errors.New("invalid token format")
+	ErrTokenExpired              = errors.New("token expired")
+	ErrInvalidSigningMethod      = errors.New("unexpected signing method")
+	ErrInvalidAccessTokenClaims  = errors.New("invalid access token claims type")
+	ErrInvalidRefreshTokenClaims = errors.New("invalid refresh token claims type")
+	ErrSessionNotFound           = errors.New("session not found")
+	ErrSessionExpired            = errors.New("session expired or invalid")
+	ErrSessionMismatch           = errors.New("session mismatch detected")
+	ErrRefreshTokenRevoked       = errors.New("refresh token has been revoked or expired")
+)
+
+// OAuth errors
+var (
+	ErrOAuthExchangeFailed  = errors.New("failed to exchange authorization code")
+	ErrOAuthRequestFailed   = errors.New("OAuth request failed")
+	ErrAuthenticationFailed = errors.New("authentication failed")
+)
+
+// Redis errors
+var (
+	ErrKeyNotFound        = errors.New("key not found")
+	ErrRedisRequestFailed = errors.New("redis request failed")
+	ErrUnexpectedResponse = errors.New("unexpected response type")
+)
+
+// Crypto errors
+var (
+	ErrRandomGeneration = errors.New("failed to generate random bytes")
+)
+
+// HTTP errors
+var (
+	ErrMethodNotAllowed = errors.New("method not allowed")
+)

server/pkg/errors/types_test.go

@@ -0,0 +1,263 @@
+package errors
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+)
+
+func TestErrorWrapping(t *testing.T) {
+	tests := []struct {
+		baseErr     error
+		name        string
+		wrapContext string
+	}{
+		{
+			name:        "wrap JWT secret error",
+			baseErr:     ErrJWTSecretMissing,
+			wrapContext: "manager initialization",
+		},
+		{
+			name:        "wrap OAuth config error",
+			baseErr:     ErrOAuthConfigMissing,
+			wrapContext: "client initialization",
+		},
+		{
+			name:        "wrap session not found error",
+			baseErr:     ErrSessionNotFound,
+			wrapContext: "verify access token",
+		},
+		{
+			name:        "wrap token expired error",
+			baseErr:     ErrTokenExpired,
+			wrapContext: "validate refresh token",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			wrappedErr := fmt.Errorf("%s: %w", tt.wrapContext, tt.baseErr)
+
+			if !errors.Is(wrappedErr, tt.baseErr) {
+				t.Errorf("errors.Is() failed: wrapped error does not match base error")
+			}
+
+			if wrappedErr.Error() == tt.baseErr.Error() {
+				t.Errorf("wrapped error message should include context, got %q", wrappedErr.Error())
+			}
+		})
+	}
+}
+
+func TestErrorChains(t *testing.T) {
+	tests := []struct {
+		buildChain  func() error
+		name        string
+		targetError error
+	}{
+		{
+			name:        "multi-level JWT error chain",
+			targetError: ErrJWTSecretMissing,
+			buildChain: func() error {
+				err := ErrJWTSecretMissing
+				err = fmt.Errorf("NewManager failed: %w", err)
+				err = fmt.Errorf("GetManager failed: %w", err)
+				return err
+			},
+		},
+		{
+			name:        "multi-level session error chain",
+			targetError: ErrSessionNotFound,
+			buildChain: func() error {
+				err := ErrSessionNotFound
+				err = fmt.Errorf("redis.Get failed: %w", err)
+				err = fmt.Errorf("verify handler failed: %w", err)
+				return err
+			},
+		},
+		{
+			name:        "OAuth error chain",
+			targetError: ErrOAuthExchangeFailed,
+			buildChain: func() error {
+				err := ErrOAuthExchangeFailed
+				err = fmt.Errorf("requestToken failed: %w", err)
+				err = fmt.Errorf("callback handler failed: %w", err)
+				return err
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			chainedErr := tt.buildChain()
+
+			if !errors.Is(chainedErr, tt.targetError) {
+				t.Errorf("errors.Is() failed: error chain does not contain target error %v", tt.targetError)
+			}
+		})
+	}
+}
+
+func TestErrorUnwrap(t *testing.T) {
+	baseErr := ErrSessionNotFound
+	wrappedErr := fmt.Errorf("context: %w", baseErr)
+
+	unwrapped := errors.Unwrap(wrappedErr)
+	if unwrapped != baseErr {
+		t.Errorf("errors.Unwrap() = %v, want %v", unwrapped, baseErr)
+	}
+}
+
+func TestErrorEquality(t *testing.T) {
+	tests := []struct {
+		err1   error
+		err2   error
+		name   string
+		wantEq bool
+	}{
+		{
+			name:   "same error instance",
+			err1:   ErrSessionNotFound,
+			err2:   ErrSessionNotFound,
+			wantEq: true,
+		},
+		{
+			name:   "different error instances",
+			err1:   ErrSessionNotFound,
+			err2:   ErrSessionExpired,
+			wantEq: false,
+		},
+		{
+			name:   "wrapped vs unwrapped same error",
+			err1:   fmt.Errorf("context: %w", ErrSessionNotFound),
+			err2:   ErrSessionNotFound,
+			wantEq: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			equal := (tt.err1 == tt.err2)
+			if equal != tt.wantEq {
+				t.Errorf("error equality = %v, want %v", equal, tt.wantEq)
+			}
+		})
+	}
+}
+
+func TestErrorIsComparison(t *testing.T) {
+	tests := []struct {
+		err    error
+		name   string
+		target error
+		want   bool
+	}{
+		{
+			name:   "exact match",
+			err:    ErrSessionNotFound,
+			target: ErrSessionNotFound,
+			want:   true,
+		},
+		{
+			name:   "wrapped error matches",
+			err:    fmt.Errorf("context: %w", ErrSessionNotFound),
+			target: ErrSessionNotFound,
+			want:   true,
+		},
+		{
+			name:   "different errors",
+			err:    ErrSessionNotFound,
+			target: ErrSessionExpired,
+			want:   false,
+		},
+		{
+			name:   "double wrapped error matches",
+			err:    fmt.Errorf("outer: %w", fmt.Errorf("inner: %w", ErrSessionNotFound)),
+			target: ErrSessionNotFound,
+			want:   true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := errors.Is(tt.err, tt.target)
+			if got != tt.want {
+				t.Errorf("errors.Is() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestDefinedErrors(t *testing.T) {
+	errorGroups := []struct {
+		name   string
+		errors []error
+	}{
+		{
+			name: "Configuration Errors",
+			errors: []error{
+				ErrJWTSecretMissing,
+				ErrOAuthConfigMissing,
+				ErrRedisConfigMissing,
+			},
+		},
+		{
+			name: "Token Errors",
+			errors: []error{
+				ErrInvalidTokenFormat,
+				ErrTokenExpired,
+				ErrInvalidSigningMethod,
+				ErrInvalidAccessTokenClaims,
+				ErrInvalidRefreshTokenClaims,
+				ErrSessionNotFound,
+				ErrSessionExpired,
+				ErrSessionMismatch,
+				ErrRefreshTokenRevoked,
+			},
+		},
+		{
+			name: "Redis Errors",
+			errors: []error{
+				ErrKeyNotFound,
+				ErrRedisRequestFailed,
+				ErrUnexpectedResponse,
+			},
+		},
+		{
+			name: "OAuth Errors",
+			errors: []error{
+				ErrOAuthExchangeFailed,
+				ErrOAuthRequestFailed,
+				ErrAuthenticationFailed,
+			},
+		},
+		{
+			name: "Crypto Errors",
+			errors: []error{
+				ErrRandomGeneration,
+			},
+		},
+		{
+			name: "HTTP Errors",
+			errors: []error{
+				ErrInvalidAuthHeader,
+				ErrMissingAuthCode,
+				ErrMissingStateParam,
+				ErrBearerTokenRequired,
+			},
+		},
+	}
+
+	for _, group := range errorGroups {
+		t.Run(group.name, func(t *testing.T) {
+			for _, err := range group.errors {
+				if err == nil {
+					t.Errorf("error in group %q should not be nil", group.name)
+				}
+				if err.Error() == "" {
+					t.Errorf("error message for %v in group %q should not be empty", err, group.name)
+				}
+			}
+		})
+	}
+}