Merge branch 'main' of github.com:bitechdev/ResolveSpec into server

Co-authored-by: IvanX006 <ivan@bitechsystems.co.za>
Co-authored-by: Warkanum <HEIN.PUTH@GMAIL.COM>
Co-authored-by: Hein <hein@bitechsystems.co.za>

Makefile

@@ -16,7 +16,7 @@ test: test-unit test-integration
 # Start PostgreSQL for integration tests
 docker-up:
 	@echo "Starting PostgreSQL container..."
-	@docker-compose up -d postgres-test
+	@podman compose up -d postgres-test
 	@echo "Waiting for PostgreSQL to be ready..."
 	@sleep 5
 	@echo "PostgreSQL is ready!"
@@ -24,12 +24,12 @@ docker-up:
 # Stop PostgreSQL container
 docker-down:
 	@echo "Stopping PostgreSQL container..."
-	@docker-compose down
+	@podman compose down
 
 # Clean up Docker volumes and test data
 clean:
 	@echo "Cleaning up..."
-	@docker-compose down -v
+	@podman compose down -v
 	@echo "Cleanup complete!"
 
 # Run integration tests with Docker (full workflow)

pkg/common/sql_helpers.go

@@ -208,21 +208,9 @@ func SanitizeWhereClause(where string, tableName string, options ...*RequestOpti
 					}
 				}
 			}
-		} else if tableName != "" && !hasTablePrefix(condToCheck) {
-			// If tableName is provided and the condition DOESN'T have a table prefix,
-			// qualify unambiguous column references to prevent "ambiguous column" errors
-			// when there are multiple joins on the same table (e.g., recursive preloads)
-			columnName := extractUnqualifiedColumnName(condToCheck)
-			if columnName != "" && (validColumns == nil || isValidColumn(columnName, validColumns)) {
-				// Qualify the column with the table name
-				// Be careful to only replace the column name, not other occurrences of the string
-				oldRef := columnName
-				newRef := tableName + "." + columnName
-				// Use word boundary matching to avoid replacing partial matches
-				cond = qualifyColumnInCondition(cond, oldRef, newRef)
-				logger.Debug("Qualified unqualified column in condition: '%s' added table prefix '%s'", oldRef, tableName)
-			}
 		}
+		// Note: We no longer add prefixes to unqualified columns here.
+		// Use AddTablePrefixToColumns() separately if you need to add prefixes.
 
 		validConditions = append(validConditions, cond)
 	}
@@ -633,3 +621,145 @@ func isValidColumn(columnName string, validColumns map[string]bool) bool {
 	}
 	return validColumns[strings.ToLower(columnName)]
 }
+
+// AddTablePrefixToColumns adds table prefix to unqualified column references in a WHERE clause.
+// This function only prefixes simple column references and skips:
+//   - Columns already having a table prefix (containing a dot)
+//   - Columns inside function calls or expressions (inside parentheses)
+//   - Columns inside subqueries
+//   - Columns that don't exist in the table (validation via model registry)
+//
+// Examples:
+//   - "status = 'active'" -> "users.status = 'active'" (if status exists in users table)
+//   - "COALESCE(status, 'default') = 'active'" -> unchanged (status inside function)
+//   - "users.status = 'active'" -> unchanged (already has prefix)
+//   - "(status = 'active')" -> "(users.status = 'active')" (grouping parens are OK)
+//   - "invalid_col = 'value'" -> unchanged (if invalid_col doesn't exist in table)
+//
+// Parameters:
+//   - where: The WHERE clause to process
+//   - tableName: The table name to use as prefix
+//
+// Returns:
+//   - The WHERE clause with table prefixes added to appropriate and valid columns
+func AddTablePrefixToColumns(where string, tableName string) string {
+	if where == "" || tableName == "" {
+		return where
+	}
+
+	where = strings.TrimSpace(where)
+
+	// Get valid columns from the model registry for validation
+	validColumns := getValidColumnsForTable(tableName)
+
+	// Split by AND to handle multiple conditions (parenthesis-aware)
+	conditions := splitByAND(where)
+	prefixedConditions := make([]string, 0, len(conditions))
+
+	for _, cond := range conditions {
+		cond = strings.TrimSpace(cond)
+		if cond == "" {
+			continue
+		}
+
+		// Process this condition to add table prefix if appropriate
+		processedCond := addPrefixToSingleCondition(cond, tableName, validColumns)
+		prefixedConditions = append(prefixedConditions, processedCond)
+	}
+
+	if len(prefixedConditions) == 0 {
+		return ""
+	}
+
+	return strings.Join(prefixedConditions, " AND ")
+}
+
+// addPrefixToSingleCondition adds table prefix to a single condition if appropriate
+// Returns the condition unchanged if:
+//   - The condition is a SQL literal/expression (true, false, null, 1=1, etc.)
+//   - The column reference is inside a function call
+//   - The column already has a table prefix
+//   - No valid column reference is found
+//   - The column doesn't exist in the table (when validColumns is provided)
+func addPrefixToSingleCondition(cond string, tableName string, validColumns map[string]bool) string {
+	// Strip outer grouping parentheses to get to the actual condition
+	strippedCond := stripOuterParentheses(cond)
+
+	// Skip SQL literals and trivial conditions (true, false, null, 1=1, etc.)
+	if IsSQLExpression(strippedCond) || IsTrivialCondition(strippedCond) {
+		logger.Debug("Skipping SQL literal/trivial condition: '%s'", strippedCond)
+		return cond
+	}
+
+	// Extract the left side of the comparison (before the operator)
+	columnRef := extractLeftSideOfComparison(strippedCond)
+	if columnRef == "" {
+		return cond
+	}
+
+	// Skip if it already has a prefix (contains a dot)
+	if strings.Contains(columnRef, ".") {
+		logger.Debug("Skipping column '%s' - already has table prefix", columnRef)
+		return cond
+	}
+
+	// Skip if it's a function call or expression (contains parentheses)
+	if strings.Contains(columnRef, "(") {
+		logger.Debug("Skipping column reference '%s' - inside function or expression", columnRef)
+		return cond
+	}
+
+	// Validate that the column exists in the table (if we have column info)
+	if !isValidColumn(columnRef, validColumns) {
+		logger.Debug("Skipping column '%s' - not found in table '%s'", columnRef, tableName)
+		return cond
+	}
+
+	// It's a simple unqualified column reference that exists in the table - add the table prefix
+	newRef := tableName + "." + columnRef
+	result := qualifyColumnInCondition(cond, columnRef, newRef)
+	logger.Debug("Added table prefix to column: '%s' -> '%s'", columnRef, newRef)
+
+	return result
+}
+
+// extractLeftSideOfComparison extracts the left side of a comparison operator from a condition.
+// This is used to identify the column reference that may need a table prefix.
+//
+// Examples:
+//   - "status = 'active'" returns "status"
+//   - "COALESCE(status, 'default') = 'active'" returns "COALESCE(status, 'default')"
+//   - "priority > 5" returns "priority"
+//
+// Returns empty string if no operator is found.
+func extractLeftSideOfComparison(cond string) string {
+	operators := []string{" = ", " != ", " <> ", " > ", " >= ", " < ", " <= ", " LIKE ", " like ", " IN ", " in ", " IS ", " is ", " NOT ", " not "}
+
+	// Find the first operator outside of parentheses and quotes
+	minIdx := -1
+	for _, op := range operators {
+		idx := findOperatorOutsideParentheses(cond, op)
+		if idx > 0 && (minIdx == -1 || idx < minIdx) {
+			minIdx = idx
+		}
+	}
+
+	if minIdx > 0 {
+		leftSide := strings.TrimSpace(cond[:minIdx])
+		// Remove any surrounding quotes
+		leftSide = strings.Trim(leftSide, "`\"'")
+		return leftSide
+	}
+
+	// No operator found - might be a boolean column
+	parts := strings.Fields(cond)
+	if len(parts) > 0 {
+		columnRef := strings.Trim(parts[0], "`\"'")
+		// Make sure it's not a SQL keyword
+		if !IsSQLKeyword(strings.ToLower(columnRef)) {
+			return columnRef
+		}
+	}
+
+	return ""
+}

pkg/logger/logger.go

@@ -75,6 +75,25 @@ func CloseErrorTracking() error {
 	return nil
 }
 
+// extractContext attempts to find a context.Context in the given arguments.
+// It returns the found context (or context.Background() if not found) and
+// the remaining arguments without the context.
+func extractContext(args ...interface{}) (context.Context, []interface{}) {
+	ctx := context.Background()
+	var newArgs []interface{}
+	found := false
+
+	for _, arg := range args {
+		if c, ok := arg.(context.Context); ok && !found {
+			ctx = c
+			found = true
+		} else {
+			newArgs = append(newArgs, arg)
+		}
+	}
+	return ctx, newArgs
+}
+
 func Info(template string, args ...interface{}) {
 	if Logger == nil {
 		log.Printf(template, args...)
@@ -84,7 +103,8 @@ func Info(template string, args ...interface{}) {
 }
 
 func Warn(template string, args ...interface{}) {
-	message := fmt.Sprintf(template, args...)
+	ctx, remainingArgs := extractContext(args...)
+	message := fmt.Sprintf(template, remainingArgs...)
 	if Logger == nil {
 		log.Printf("%s", message)
 	} else {
@@ -93,14 +113,15 @@ func Warn(template string, args ...interface{}) {
 
 	// Send to error tracker
 	if errorTracker != nil {
-		errorTracker.CaptureMessage(context.Background(), message, errortracking.SeverityWarning, map[string]interface{}{
+		errorTracker.CaptureMessage(ctx, message, errortracking.SeverityWarning, map[string]interface{}{
 			"process_id": os.Getpid(),
 		})
 	}
 }
 
 func Error(template string, args ...interface{}) {
-	message := fmt.Sprintf(template, args...)
+	ctx, remainingArgs := extractContext(args...)
+	message := fmt.Sprintf(template, remainingArgs...)
 	if Logger == nil {
 		log.Printf("%s", message)
 	} else {
@@ -109,7 +130,7 @@ func Error(template string, args ...interface{}) {
 
 	// Send to error tracker
 	if errorTracker != nil {
-		errorTracker.CaptureMessage(context.Background(), message, errortracking.SeverityError, map[string]interface{}{
+		errorTracker.CaptureMessage(ctx, message, errortracking.SeverityError, map[string]interface{}{
 			"process_id": os.Getpid(),
 		})
 	}
@@ -124,12 +145,13 @@ func Debug(template string, args ...interface{}) {
 }
 
 // CatchPanic - Handle panic
-func CatchPanicCallback(location string, cb func(err any)) {
+func CatchPanicCallback(location string, cb func(err any), args ...interface{}) {
+	ctx, _ := extractContext(args...)
 	if err := recover(); err != nil {
 		callstack := debug.Stack()
 
 		if Logger != nil {
-			Error("Panic in %s : %v", location, err)
+			Error("Panic in %s : %v", location, err, ctx) // Pass context implicitly
 		} else {
 			fmt.Printf("%s:PANIC->%+v", location, err)
 			debug.PrintStack()
@@ -137,7 +159,7 @@ func CatchPanicCallback(location string, cb func(err any)) {
 
 		// Send to error tracker
 		if errorTracker != nil {
-			errorTracker.CapturePanic(context.Background(), err, callstack, map[string]interface{}{
+			errorTracker.CapturePanic(ctx, err, callstack, map[string]interface{}{
 				"location":   location,
 				"process_id": os.Getpid(),
 			})
@@ -150,8 +172,8 @@ func CatchPanicCallback(location string, cb func(err any)) {
 }
 
 // CatchPanic - Handle panic
-func CatchPanic(location string) {
-	CatchPanicCallback(location, nil)
+func CatchPanic(location string, args ...interface{}) {
+	CatchPanicCallback(location, nil, args...)
 }
 
 // HandlePanic logs a panic and returns it as an error
@@ -163,13 +185,14 @@ func CatchPanic(location string) {
 //	        err = logger.HandlePanic("MethodName", r)
 //	    }
 //	}()
-func HandlePanic(methodName string, r any) error {
+func HandlePanic(methodName string, r any, args ...interface{}) error {
+	ctx, _ := extractContext(args...)
 	stack := debug.Stack()
-	Error("Panic in %s: %v\nStack trace:\n%s", methodName, r, string(stack))
+	Error("Panic in %s: %v\nStack trace:\n%s", methodName, r, string(stack), ctx) // Pass context implicitly
 
 	// Send to error tracker
 	if errorTracker != nil {
-		errorTracker.CapturePanic(context.Background(), r, stack, map[string]interface{}{
+		errorTracker.CapturePanic(ctx, r, stack, map[string]interface{}{
 			"method":     methodName,
 			"process_id": os.Getpid(),
 		})

pkg/metrics/interfaces.go

@@ -39,6 +39,9 @@ type Provider interface {
 	// UpdateEventQueueSize updates the event queue size metric
 	UpdateEventQueueSize(size int64)
 
+	// RecordPanic records a panic event
+	RecordPanic(methodName string)
+
 	// Handler returns an HTTP handler for exposing metrics (e.g., /metrics endpoint)
 	Handler() http.Handler
 }
@@ -75,6 +78,7 @@ func (n *NoOpProvider) RecordEventPublished(source, eventType string) {}
 func (n *NoOpProvider) RecordEventProcessed(source, eventType, status string, duration time.Duration) {
 }
 func (n *NoOpProvider) UpdateEventQueueSize(size int64) {}
+func (n *NoOpProvider) RecordPanic(methodName string)   {}
 func (n *NoOpProvider) Handler() http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusNotFound)

pkg/metrics/prometheus.go

@@ -20,6 +20,7 @@ type PrometheusProvider struct {
 	cacheHits        *prometheus.CounterVec
 	cacheMisses      *prometheus.CounterVec
 	cacheSize        *prometheus.GaugeVec
+	panicsTotal      *prometheus.CounterVec
 }
 
 // NewPrometheusProvider creates a new Prometheus metrics provider
@@ -83,6 +84,13 @@ func NewPrometheusProvider() *PrometheusProvider {
 			},
 			[]string{"provider"},
 		),
+		panicsTotal: promauto.NewCounterVec(
+			prometheus.CounterOpts{
+				Name: "panics_total",
+				Help: "Total number of panics",
+			},
+			[]string{"method"},
+		),
 	}
 }
 
@@ -145,6 +153,11 @@ func (p *PrometheusProvider) UpdateCacheSize(provider string, size int64) {
 	p.cacheSize.WithLabelValues(provider).Set(float64(size))
 }
 
+// RecordPanic implements the Provider interface
+func (p *PrometheusProvider) RecordPanic(methodName string) {
+	p.panicsTotal.WithLabelValues(methodName).Inc()
+}
+
 // Handler implements Provider interface
 func (p *PrometheusProvider) Handler() http.Handler {
 	return promhttp.Handler()

pkg/middleware/panic.go

@@ -0,0 +1,33 @@
+package middleware
+
+import (
+	"net/http"
+
+	"github.com/bitechdev/ResolveSpec/pkg/logger"
+	"github.com/bitechdev/ResolveSpec/pkg/metrics"
+)
+
+const panicMiddlewareMethodName = "PanicMiddleware"
+
+// PanicRecovery is a middleware that recovers from panics, logs the error,
+// sends it to an error tracker, records a metric, and returns a 500 Internal Server Error.
+func PanicRecovery(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		defer func() {
+			if rcv := recover(); rcv != nil {
+				// Record the panic metric
+				metrics.GetProvider().RecordPanic(panicMiddlewareMethodName)
+
+				// Log the panic and send to error tracker
+				// We pass the request context so the error tracker can potentially
+				// link the panic to the request trace.
+				ctx := r.Context()
+				err := logger.HandlePanic(panicMiddlewareMethodName, rcv, ctx)
+
+				// Respond with a 500 error
+				http.Error(w, err.Error(), http.StatusInternalServerError)
+			}
+		}()
+		next.ServeHTTP(w, r)
+	})
+}

pkg/middleware/panic_test.go

@@ -0,0 +1,86 @@
+package middleware
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/bitechdev/ResolveSpec/pkg/logger"
+	"github.com/bitechdev/ResolveSpec/pkg/metrics"
+	"github.com/stretchr/testify/assert"
+)
+
+// mockMetricsProvider is a mock for the metrics provider to check if methods are called.
+type mockMetricsProvider struct {
+	metrics.NoOpProvider // Embed NoOpProvider to avoid implementing all methods
+	panicRecorded bool
+	methodName    string
+}
+
+func (m *mockMetricsProvider) RecordPanic(methodName string) {
+	m.panicRecorded = true
+	m.methodName = methodName
+}
+
+func TestPanicRecovery(t *testing.T) {
+	// Initialize a mock logger to avoid actual logging output during tests
+	logger.Init(true)
+
+	// Setup mock metrics provider
+	mockProvider := &mockMetricsProvider{}
+	originalProvider := metrics.GetProvider()
+	metrics.SetProvider(mockProvider)
+	defer metrics.SetProvider(originalProvider) // Restore original provider after test
+
+	// 1. Test case: A handler that panics
+	t.Run("recovers from panic and returns 500", func(t *testing.T) {
+		// Reset mock state for this sub-test
+		mockProvider.panicRecorded = false
+		mockProvider.methodName = ""
+
+		panicHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			panic("something went terribly wrong")
+		})
+
+		// Create the middleware wrapping the panicking handler
+		testHandler := PanicRecovery(panicHandler)
+
+		// Create a test request and response recorder
+		req := httptest.NewRequest("GET", "http://example.com/foo", nil)
+		rr := httptest.NewRecorder()
+
+		// Serve the request
+		testHandler.ServeHTTP(rr, req)
+
+		// Assertions
+		assert.Equal(t, http.StatusInternalServerError, rr.Code, "expected status code to be 500")
+		assert.Contains(t, rr.Body.String(), "panic in PanicMiddleware: something went terribly wrong", "expected error message in response body")
+
+		// Assert that the metric was recorded
+		assert.True(t, mockProvider.panicRecorded, "expected RecordPanic to be called on metrics provider")
+		assert.Equal(t, panicMiddlewareMethodName, mockProvider.methodName, "expected panic to be recorded with the correct method name")
+	})
+
+	// 2. Test case: A handler that does NOT panic
+	t.Run("does not interfere with a non-panicking handler", func(t *testing.T) {
+		// Reset mock state for this sub-test
+		mockProvider.panicRecorded = false
+
+		successHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte("OK"))
+		})
+
+		testHandler := PanicRecovery(successHandler)
+
+		req := httptest.NewRequest("GET", "http://example.com/foo", nil)
+		rr := httptest.NewRecorder()
+
+		testHandler.ServeHTTP(rr, req)
+
+		// Assertions
+		assert.Equal(t, http.StatusOK, rr.Code, "expected status code to be 200")
+		assert.Equal(t, "OK", rr.Body.String(), "expected 'OK' response body")
+		assert.False(t, mockProvider.panicRecorded, "expected RecordPanic to not be called when there is no panic")
+	})
+}

pkg/openapi/README.md

@@ -273,25 +273,151 @@ handler.SetOpenAPIGenerator(func() (string, error) {
 })
 ```
 
-## Using with Swagger UI
+## Using the Built-in UI Handler
 
-You can serve the generated OpenAPI spec with Swagger UI:
+The package includes a built-in UI handler that serves popular OpenAPI visualization tools. No need to download or manage static files - everything is served from CDN.
+
+### Quick Start
+
+```go
+import (
+    "github.com/bitechdev/ResolveSpec/pkg/openapi"
+    "github.com/gorilla/mux"
+)
+
+func main() {
+    router := mux.NewRouter()
+
+    // Setup your API routes and OpenAPI generator...
+    // (see examples above)
+
+    // Add the UI handler - defaults to Swagger UI
+    openapi.SetupUIRoute(router, "/docs", openapi.UIConfig{
+        UIType:  openapi.SwaggerUI,
+        SpecURL: "/openapi",
+        Title:   "My API Documentation",
+    })
+
+    // Now visit http://localhost:8080/docs
+    http.ListenAndServe(":8080", router)
+}
+```
+
+### Supported UI Frameworks
+
+The handler supports four popular OpenAPI UI frameworks:
+
+#### 1. Swagger UI (Default)
+The most widely used OpenAPI UI with excellent compatibility and features.
+
+```go
+openapi.SetupUIRoute(router, "/docs", openapi.UIConfig{
+    UIType: openapi.SwaggerUI,
+    Theme:  "dark", // optional: "light" or "dark"
+})
+```
+
+#### 2. RapiDoc
+Modern, customizable, and feature-rich OpenAPI UI.
+
+```go
+openapi.SetupUIRoute(router, "/docs", openapi.UIConfig{
+    UIType: openapi.RapiDoc,
+    Theme:  "dark",
+})
+```
+
+#### 3. Redoc
+Clean, responsive documentation with great UX.
+
+```go
+openapi.SetupUIRoute(router, "/docs", openapi.UIConfig{
+    UIType: openapi.Redoc,
+})
+```
+
+#### 4. Scalar
+Modern and sleek OpenAPI documentation.
+
+```go
+openapi.SetupUIRoute(router, "/docs", openapi.UIConfig{
+    UIType: openapi.Scalar,
+    Theme:  "dark",
+})
+```
+
+### Configuration Options
+
+```go
+type UIConfig struct {
+    UIType     UIType // SwaggerUI, RapiDoc, Redoc, or Scalar
+    SpecURL    string // URL to OpenAPI spec (default: "/openapi")
+    Title      string // Page title (default: "API Documentation")
+    FaviconURL string // Custom favicon URL (optional)
+    CustomCSS  string // Custom CSS to inject (optional)
+    Theme      string // "light" or "dark" (support varies by UI)
+}
+```
+
+### Custom Styling Example
+
+```go
+openapi.SetupUIRoute(router, "/docs", openapi.UIConfig{
+    UIType: openapi.SwaggerUI,
+    Title:  "Acme Corp API",
+    CustomCSS: `
+        .swagger-ui .topbar {
+            background-color: #1976d2;
+        }
+        .swagger-ui .info .title {
+            color: #1976d2;
+        }
+    `,
+})
+```
+
+### Using Multiple UIs
+
+You can serve different UIs at different paths:
+
+```go
+// Swagger UI at /docs
+openapi.SetupUIRoute(router, "/docs", openapi.UIConfig{
+    UIType: openapi.SwaggerUI,
+})
+
+// Redoc at /redoc
+openapi.SetupUIRoute(router, "/redoc", openapi.UIConfig{
+    UIType: openapi.Redoc,
+})
+
+// RapiDoc at /api-docs
+openapi.SetupUIRoute(router, "/api-docs", openapi.UIConfig{
+    UIType: openapi.RapiDoc,
+})
+```
+
+### Manual Handler Usage
+
+If you need more control, use the handler directly:
+
+```go
+handler := openapi.UIHandler(openapi.UIConfig{
+    UIType:  openapi.SwaggerUI,
+    SpecURL: "/api/openapi.json",
+})
+
+router.Handle("/documentation", handler)
+```
+
+## Using with External Swagger UI
+
+Alternatively, you can use an external Swagger UI instance:
 
 1. Get the spec from `/openapi`
 2. Load it in Swagger UI at `https://petstore.swagger.io/`
 3. Or self-host Swagger UI and point it to your `/openapi` endpoint
 
-Example with self-hosted Swagger UI:
-
-```go
-// Serve Swagger UI static files
-router.PathPrefix("/swagger/").Handler(
-    http.StripPrefix("/swagger/", http.FileServer(http.Dir("./swagger-ui"))),
-)
-
-// Configure Swagger UI to use /openapi
-```
-
 ## Testing
 
 You can test the OpenAPI endpoint:

pkg/openapi/example.go

@@ -183,6 +183,69 @@ func ExampleWithFuncSpec() {
 	_ = generatorFunc
 }
 
+// ExampleWithUIHandler shows how to serve OpenAPI documentation with a web UI
+func ExampleWithUIHandler(db *gorm.DB) {
+	// Create handler and configure OpenAPI generator
+	handler := restheadspec.NewHandlerWithGORM(db)
+	registry := modelregistry.NewModelRegistry()
+
+	handler.SetOpenAPIGenerator(func() (string, error) {
+		generator := NewGenerator(GeneratorConfig{
+			Title:               "My API",
+			Description:         "API documentation with interactive UI",
+			Version:             "1.0.0",
+			BaseURL:             "http://localhost:8080",
+			Registry:            registry,
+			IncludeRestheadSpec: true,
+		})
+		return generator.GenerateJSON()
+	})
+
+	// Setup routes
+	router := mux.NewRouter()
+	restheadspec.SetupMuxRoutes(router, handler, nil)
+
+	// Add UI handlers for different frameworks
+	// Swagger UI at /docs (most popular)
+	SetupUIRoute(router, "/docs", UIConfig{
+		UIType:  SwaggerUI,
+		SpecURL: "/openapi",
+		Title:   "My API - Swagger UI",
+		Theme:   "light",
+	})
+
+	// RapiDoc at /rapidoc (modern alternative)
+	SetupUIRoute(router, "/rapidoc", UIConfig{
+		UIType:  RapiDoc,
+		SpecURL: "/openapi",
+		Title:   "My API - RapiDoc",
+	})
+
+	// Redoc at /redoc (clean and responsive)
+	SetupUIRoute(router, "/redoc", UIConfig{
+		UIType:  Redoc,
+		SpecURL: "/openapi",
+		Title:   "My API - Redoc",
+	})
+
+	// Scalar at /scalar (modern and sleek)
+	SetupUIRoute(router, "/scalar", UIConfig{
+		UIType:  Scalar,
+		SpecURL: "/openapi",
+		Title:   "My API - Scalar",
+		Theme:   "dark",
+	})
+
+	// Now you can access:
+	// http://localhost:8080/docs      - Swagger UI
+	// http://localhost:8080/rapidoc   - RapiDoc
+	// http://localhost:8080/redoc     - Redoc
+	// http://localhost:8080/scalar    - Scalar
+	// http://localhost:8080/openapi   - Raw OpenAPI JSON
+
+	_ = router
+}
+
 // ExampleCustomization shows advanced customization options
 func ExampleCustomization() {
 	// Create registry and register models with descriptions using struct tags

pkg/openapi/ui_handler.go

@@ -0,0 +1,294 @@
+package openapi
+
+import (
+	"fmt"
+	"html/template"
+	"net/http"
+	"strings"
+
+	"github.com/gorilla/mux"
+)
+
+// UIType represents the type of OpenAPI UI to serve
+type UIType string
+
+const (
+	// SwaggerUI is the most popular OpenAPI UI
+	SwaggerUI UIType = "swagger-ui"
+	// RapiDoc is a modern, customizable OpenAPI UI
+	RapiDoc UIType = "rapidoc"
+	// Redoc is a clean, responsive OpenAPI UI
+	Redoc UIType = "redoc"
+	// Scalar is a modern and sleek OpenAPI UI
+	Scalar UIType = "scalar"
+)
+
+// UIConfig holds configuration for the OpenAPI UI handler
+type UIConfig struct {
+	// UIType specifies which UI framework to use (default: SwaggerUI)
+	UIType UIType
+	// SpecURL is the URL to the OpenAPI spec JSON (default: "/openapi")
+	SpecURL string
+	// Title is the page title (default: "API Documentation")
+	Title string
+	// FaviconURL is the URL to the favicon (optional)
+	FaviconURL string
+	// CustomCSS allows injecting custom CSS (optional)
+	CustomCSS string
+	// Theme for the UI (light/dark, depends on UI type)
+	Theme string
+}
+
+// UIHandler creates an HTTP handler that serves an OpenAPI UI
+func UIHandler(config UIConfig) http.HandlerFunc {
+	// Set defaults
+	if config.UIType == "" {
+		config.UIType = SwaggerUI
+	}
+	if config.SpecURL == "" {
+		config.SpecURL = "/openapi"
+	}
+	if config.Title == "" {
+		config.Title = "API Documentation"
+	}
+	if config.Theme == "" {
+		config.Theme = "light"
+	}
+
+	return func(w http.ResponseWriter, r *http.Request) {
+		var htmlContent string
+		var err error
+
+		switch config.UIType {
+		case SwaggerUI:
+			htmlContent, err = generateSwaggerUI(config)
+		case RapiDoc:
+			htmlContent, err = generateRapiDoc(config)
+		case Redoc:
+			htmlContent, err = generateRedoc(config)
+		case Scalar:
+			htmlContent, err = generateScalar(config)
+		default:
+			http.Error(w, "Unsupported UI type", http.StatusBadRequest)
+			return
+		}
+
+		if err != nil {
+			http.Error(w, fmt.Sprintf("Failed to generate UI: %v", err), http.StatusInternalServerError)
+			return
+		}
+
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		w.WriteHeader(http.StatusOK)
+		_, err = w.Write([]byte(htmlContent))
+		if err != nil {
+			http.Error(w, fmt.Sprintf("Failed to write response: %v", err), http.StatusInternalServerError)
+			return
+		}
+	}
+}
+
+// templateData wraps UIConfig to properly handle CSS in templates
+type templateData struct {
+	UIConfig
+	SafeCustomCSS template.CSS
+}
+
+// generateSwaggerUI generates the HTML for Swagger UI
+func generateSwaggerUI(config UIConfig) (string, error) {
+	tmpl := `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{.Title}}</title>
+    {{if .FaviconURL}}<link rel="icon" type="image/png" href="{{.FaviconURL}}">{{end}}
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css">
+    {{if .SafeCustomCSS}}<style>{{.SafeCustomCSS}}</style>{{end}}
+    <style>
+        html { box-sizing: border-box; overflow: -moz-scrollbars-vertical; overflow-y: scroll; }
+        *, *:before, *:after { box-sizing: inherit; }
+        body { margin: 0; padding: 0; }
+    </style>
+</head>
+<body>
+    <div id="swagger-ui"></div>
+    <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-standalone-preset.js"></script>
+    <script>
+        window.onload = function() {
+            const ui = SwaggerUIBundle({
+                url: "{{.SpecURL}}",
+                dom_id: '#swagger-ui',
+                deepLinking: true,
+                presets: [
+                    SwaggerUIBundle.presets.apis,
+                    SwaggerUIStandalonePreset
+                ],
+                plugins: [
+                    SwaggerUIBundle.plugins.DownloadUrl
+                ],
+                layout: "StandaloneLayout",
+                {{if eq .Theme "dark"}}
+                syntaxHighlight: {
+                    activate: true,
+                    theme: "monokai"
+                }
+                {{end}}
+            });
+            window.ui = ui;
+        };
+    </script>
+</body>
+</html>`
+
+	t, err := template.New("swagger").Parse(tmpl)
+	if err != nil {
+		return "", err
+	}
+
+	data := templateData{
+		UIConfig:      config,
+		SafeCustomCSS: template.CSS(config.CustomCSS),
+	}
+
+	var buf strings.Builder
+	if err := t.Execute(&buf, data); err != nil {
+		return "", err
+	}
+
+	return buf.String(), nil
+}
+
+// generateRapiDoc generates the HTML for RapiDoc
+func generateRapiDoc(config UIConfig) (string, error) {
+	theme := "light"
+	if config.Theme == "dark" {
+		theme = "dark"
+	}
+
+	tmpl := `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{.Title}}</title>
+    {{if .FaviconURL}}<link rel="icon" type="image/png" href="{{.FaviconURL}}">{{end}}
+    <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
+    {{if .SafeCustomCSS}}<style>{{.SafeCustomCSS}}</style>{{end}}
+</head>
+<body>
+    <rapi-doc
+        spec-url="{{.SpecURL}}"
+        theme="` + theme + `"
+        render-style="read"
+        show-header="true"
+        show-info="true"
+        allow-try="true"
+        allow-server-selection="true"
+        allow-authentication="true"
+        api-key-name="Authorization"
+        api-key-location="header"
+    ></rapi-doc>
+</body>
+</html>`
+
+	t, err := template.New("rapidoc").Parse(tmpl)
+	if err != nil {
+		return "", err
+	}
+
+	data := templateData{
+		UIConfig:      config,
+		SafeCustomCSS: template.CSS(config.CustomCSS),
+	}
+
+	var buf strings.Builder
+	if err := t.Execute(&buf, data); err != nil {
+		return "", err
+	}
+
+	return buf.String(), nil
+}
+
+// generateRedoc generates the HTML for Redoc
+func generateRedoc(config UIConfig) (string, error) {
+	tmpl := `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{.Title}}</title>
+    {{if .FaviconURL}}<link rel="icon" type="image/png" href="{{.FaviconURL}}">{{end}}
+    {{if .SafeCustomCSS}}<style>{{.SafeCustomCSS}}</style>{{end}}
+    <style>
+        body { margin: 0; padding: 0; }
+    </style>
+</head>
+<body>
+    <redoc spec-url="{{.SpecURL}}" {{if eq .Theme "dark"}}theme='{"colors": {"primary": {"main": "#dd5522"}}}'{{end}}></redoc>
+    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
+</body>
+</html>`
+
+	t, err := template.New("redoc").Parse(tmpl)
+	if err != nil {
+		return "", err
+	}
+
+	data := templateData{
+		UIConfig:      config,
+		SafeCustomCSS: template.CSS(config.CustomCSS),
+	}
+
+	var buf strings.Builder
+	if err := t.Execute(&buf, data); err != nil {
+		return "", err
+	}
+
+	return buf.String(), nil
+}
+
+// generateScalar generates the HTML for Scalar
+func generateScalar(config UIConfig) (string, error) {
+	tmpl := `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{.Title}}</title>
+    {{if .FaviconURL}}<link rel="icon" type="image/png" href="{{.FaviconURL}}">{{end}}
+    {{if .SafeCustomCSS}}<style>{{.SafeCustomCSS}}</style>{{end}}
+    <style>
+        body { margin: 0; padding: 0; }
+    </style>
+</head>
+<body>
+    <script id="api-reference" data-url="{{.SpecURL}}" {{if eq .Theme "dark"}}data-theme="dark"{{end}}></script>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+</body>
+</html>`
+
+	t, err := template.New("scalar").Parse(tmpl)
+	if err != nil {
+		return "", err
+	}
+
+	data := templateData{
+		UIConfig:      config,
+		SafeCustomCSS: template.CSS(config.CustomCSS),
+	}
+
+	var buf strings.Builder
+	if err := t.Execute(&buf, data); err != nil {
+		return "", err
+	}
+
+	return buf.String(), nil
+}
+
+// SetupUIRoute adds the OpenAPI UI route to a mux router
+// This is a convenience function for the most common use case
+func SetupUIRoute(router *mux.Router, path string, config UIConfig) {
+	router.Handle(path, UIHandler(config))
+}

pkg/openapi/ui_handler_test.go

@@ -0,0 +1,308 @@
+package openapi
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gorilla/mux"
+)
+
+func TestUIHandler_SwaggerUI(t *testing.T) {
+	config := UIConfig{
+		UIType:  SwaggerUI,
+		SpecURL: "/openapi",
+		Title:   "Test API Docs",
+	}
+
+	handler := UIHandler(config)
+	req := httptest.NewRequest("GET", "/docs", nil)
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	resp := w.Result()
+	if resp.StatusCode != http.StatusOK {
+		t.Errorf("Expected status 200, got %d", resp.StatusCode)
+	}
+
+	body := w.Body.String()
+
+	// Check for Swagger UI specific content
+	if !strings.Contains(body, "swagger-ui") {
+		t.Error("Expected Swagger UI content")
+	}
+	if !strings.Contains(body, "SwaggerUIBundle") {
+		t.Error("Expected SwaggerUIBundle script")
+	}
+	if !strings.Contains(body, config.Title) {
+		t.Errorf("Expected title '%s' in HTML", config.Title)
+	}
+	if !strings.Contains(body, config.SpecURL) {
+		t.Errorf("Expected spec URL '%s' in HTML", config.SpecURL)
+	}
+	if !strings.Contains(body, "swagger-ui-dist") {
+		t.Error("Expected Swagger UI CDN link")
+	}
+}
+
+func TestUIHandler_RapiDoc(t *testing.T) {
+	config := UIConfig{
+		UIType:  RapiDoc,
+		SpecURL: "/api/spec",
+		Title:   "RapiDoc Test",
+	}
+
+	handler := UIHandler(config)
+	req := httptest.NewRequest("GET", "/docs", nil)
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	resp := w.Result()
+	if resp.StatusCode != http.StatusOK {
+		t.Errorf("Expected status 200, got %d", resp.StatusCode)
+	}
+
+	body := w.Body.String()
+
+	// Check for RapiDoc specific content
+	if !strings.Contains(body, "rapi-doc") {
+		t.Error("Expected rapi-doc element")
+	}
+	if !strings.Contains(body, "rapidoc-min.js") {
+		t.Error("Expected RapiDoc script")
+	}
+	if !strings.Contains(body, config.Title) {
+		t.Errorf("Expected title '%s' in HTML", config.Title)
+	}
+	if !strings.Contains(body, config.SpecURL) {
+		t.Errorf("Expected spec URL '%s' in HTML", config.SpecURL)
+	}
+}
+
+func TestUIHandler_Redoc(t *testing.T) {
+	config := UIConfig{
+		UIType:  Redoc,
+		SpecURL: "/spec.json",
+		Title:   "Redoc Test",
+	}
+
+	handler := UIHandler(config)
+	req := httptest.NewRequest("GET", "/docs", nil)
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	resp := w.Result()
+	if resp.StatusCode != http.StatusOK {
+		t.Errorf("Expected status 200, got %d", resp.StatusCode)
+	}
+
+	body := w.Body.String()
+
+	// Check for Redoc specific content
+	if !strings.Contains(body, "<redoc") {
+		t.Error("Expected redoc element")
+	}
+	if !strings.Contains(body, "redoc.standalone.js") {
+		t.Error("Expected Redoc script")
+	}
+	if !strings.Contains(body, config.Title) {
+		t.Errorf("Expected title '%s' in HTML", config.Title)
+	}
+	if !strings.Contains(body, config.SpecURL) {
+		t.Errorf("Expected spec URL '%s' in HTML", config.SpecURL)
+	}
+}
+
+func TestUIHandler_Scalar(t *testing.T) {
+	config := UIConfig{
+		UIType:  Scalar,
+		SpecURL: "/openapi.json",
+		Title:   "Scalar Test",
+	}
+
+	handler := UIHandler(config)
+	req := httptest.NewRequest("GET", "/docs", nil)
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	resp := w.Result()
+	if resp.StatusCode != http.StatusOK {
+		t.Errorf("Expected status 200, got %d", resp.StatusCode)
+	}
+
+	body := w.Body.String()
+
+	// Check for Scalar specific content
+	if !strings.Contains(body, "api-reference") {
+		t.Error("Expected api-reference element")
+	}
+	if !strings.Contains(body, "@scalar/api-reference") {
+		t.Error("Expected Scalar script")
+	}
+	if !strings.Contains(body, config.Title) {
+		t.Errorf("Expected title '%s' in HTML", config.Title)
+	}
+	if !strings.Contains(body, config.SpecURL) {
+		t.Errorf("Expected spec URL '%s' in HTML", config.SpecURL)
+	}
+}
+
+func TestUIHandler_DefaultValues(t *testing.T) {
+	// Test with empty config to check defaults
+	config := UIConfig{}
+
+	handler := UIHandler(config)
+	req := httptest.NewRequest("GET", "/docs", nil)
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	resp := w.Result()
+	if resp.StatusCode != http.StatusOK {
+		t.Errorf("Expected status 200, got %d", resp.StatusCode)
+	}
+
+	body := w.Body.String()
+
+	// Should default to Swagger UI
+	if !strings.Contains(body, "swagger-ui") {
+		t.Error("Expected default to Swagger UI")
+	}
+
+	// Should default to /openapi spec URL
+	if !strings.Contains(body, "/openapi") {
+		t.Error("Expected default spec URL '/openapi'")
+	}
+
+	// Should default to "API Documentation" title
+	if !strings.Contains(body, "API Documentation") {
+		t.Error("Expected default title 'API Documentation'")
+	}
+}
+
+func TestUIHandler_CustomCSS(t *testing.T) {
+	customCSS := ".custom-class { color: red; }"
+	config := UIConfig{
+		UIType:    SwaggerUI,
+		CustomCSS: customCSS,
+	}
+
+	handler := UIHandler(config)
+	req := httptest.NewRequest("GET", "/docs", nil)
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	body := w.Body.String()
+
+	if !strings.Contains(body, customCSS) {
+		t.Errorf("Expected custom CSS to be included. Body:\n%s", body)
+	}
+}
+
+func TestUIHandler_Favicon(t *testing.T) {
+	faviconURL := "https://example.com/favicon.ico"
+	config := UIConfig{
+		UIType:     SwaggerUI,
+		FaviconURL: faviconURL,
+	}
+
+	handler := UIHandler(config)
+	req := httptest.NewRequest("GET", "/docs", nil)
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	body := w.Body.String()
+
+	if !strings.Contains(body, faviconURL) {
+		t.Error("Expected favicon URL to be included")
+	}
+}
+
+func TestUIHandler_DarkTheme(t *testing.T) {
+	config := UIConfig{
+		UIType: SwaggerUI,
+		Theme:  "dark",
+	}
+
+	handler := UIHandler(config)
+	req := httptest.NewRequest("GET", "/docs", nil)
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	body := w.Body.String()
+
+	// SwaggerUI uses monokai theme for dark mode
+	if !strings.Contains(body, "monokai") {
+		t.Error("Expected dark theme configuration for Swagger UI")
+	}
+}
+
+func TestUIHandler_InvalidUIType(t *testing.T) {
+	config := UIConfig{
+		UIType: "invalid-ui-type",
+	}
+
+	handler := UIHandler(config)
+	req := httptest.NewRequest("GET", "/docs", nil)
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	resp := w.Result()
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Errorf("Expected status 400 for invalid UI type, got %d", resp.StatusCode)
+	}
+}
+
+func TestUIHandler_ContentType(t *testing.T) {
+	config := UIConfig{
+		UIType: SwaggerUI,
+	}
+
+	handler := UIHandler(config)
+	req := httptest.NewRequest("GET", "/docs", nil)
+	w := httptest.NewRecorder()
+
+	handler(w, req)
+
+	contentType := w.Header().Get("Content-Type")
+	if !strings.Contains(contentType, "text/html") {
+		t.Errorf("Expected Content-Type to contain 'text/html', got '%s'", contentType)
+	}
+	if !strings.Contains(contentType, "charset=utf-8") {
+		t.Errorf("Expected Content-Type to contain 'charset=utf-8', got '%s'", contentType)
+	}
+}
+
+func TestSetupUIRoute(t *testing.T) {
+	router := mux.NewRouter()
+
+	config := UIConfig{
+		UIType: SwaggerUI,
+	}
+
+	SetupUIRoute(router, "/api-docs", config)
+
+	// Test that the route was added and works
+	req := httptest.NewRequest("GET", "/api-docs", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("Expected status 200, got %d", w.Code)
+	}
+
+	// Verify it returns HTML
+	body := w.Body.String()
+	if !strings.Contains(body, "swagger-ui") {
+		t.Error("Expected Swagger UI content")
+	}
+}

pkg/restheadspec/handler.go

@@ -482,8 +482,10 @@ func (h *Handler) handleRead(ctx context.Context, w common.ResponseWriter, id st
 	// Apply custom SQL WHERE clause (AND condition)
 	if options.CustomSQLWhere != "" {
 		logger.Debug("Applying custom SQL WHERE: %s", options.CustomSQLWhere)
-		// Sanitize and allow preload table prefixes since custom SQL may reference multiple tables
-		sanitizedWhere := common.SanitizeWhereClause(options.CustomSQLWhere, reflection.ExtractTableNameOnly(tableName), &options.RequestOptions)
+		// First add table prefixes to unqualified columns (but skip columns inside function calls)
+		prefixedWhere := common.AddTablePrefixToColumns(options.CustomSQLWhere, reflection.ExtractTableNameOnly(tableName))
+		// Then sanitize and allow preload table prefixes since custom SQL may reference multiple tables
+		sanitizedWhere := common.SanitizeWhereClause(prefixedWhere, reflection.ExtractTableNameOnly(tableName), &options.RequestOptions)
 		if sanitizedWhere != "" {
 			query = query.Where(sanitizedWhere)
 		}
@@ -492,8 +494,9 @@ func (h *Handler) handleRead(ctx context.Context, w common.ResponseWriter, id st
 	// Apply custom SQL WHERE clause (OR condition)
 	if options.CustomSQLOr != "" {
 		logger.Debug("Applying custom SQL OR: %s", options.CustomSQLOr)
+		customOr := common.AddTablePrefixToColumns(options.CustomSQLOr, reflection.ExtractTableNameOnly(tableName))
 		// Sanitize and allow preload table prefixes since custom SQL may reference multiple tables
-		sanitizedOr := common.SanitizeWhereClause(options.CustomSQLOr, reflection.ExtractTableNameOnly(tableName), &options.RequestOptions)
+		sanitizedOr := common.SanitizeWhereClause(customOr, reflection.ExtractTableNameOnly(tableName), &options.RequestOptions)
 		if sanitizedOr != "" {
 			query = query.WhereOr(sanitizedOr)
 		}

pkg/restheadspec/integration_test.go

@@ -1,3 +1,4 @@
+//go:build integration
 // +build integration
 
 package restheadspec
@@ -21,12 +22,12 @@ import (
 
 // Test models
 type TestUser struct {
-	ID        uint      `gorm:"primaryKey" json:"id"`
-	Name      string    `gorm:"not null" json:"name"`
-	Email     string    `gorm:"uniqueIndex;not null" json:"email"`
-	Age       int       `json:"age"`
-	Active    bool      `gorm:"default:true" json:"active"`
-	CreatedAt time.Time `json:"created_at"`
+	ID        uint       `gorm:"primaryKey" json:"id"`
+	Name      string     `gorm:"not null" json:"name"`
+	Email     string     `gorm:"uniqueIndex;not null" json:"email"`
+	Age       int        `json:"age"`
+	Active    bool       `gorm:"default:true" json:"active"`
+	CreatedAt time.Time  `json:"created_at"`
 	Posts     []TestPost `gorm:"foreignKey:UserID" json:"posts,omitempty"`
 }
 
@@ -35,13 +36,13 @@ func (TestUser) TableName() string {
 }
 
 type TestPost struct {
-	ID        uint      `gorm:"primaryKey" json:"id"`
-	UserID    uint      `gorm:"not null" json:"user_id"`
-	Title     string    `gorm:"not null" json:"title"`
-	Content   string    `json:"content"`
-	Published bool      `gorm:"default:false" json:"published"`
-	CreatedAt time.Time `json:"created_at"`
-	User      *TestUser  `gorm:"foreignKey:UserID" json:"user,omitempty"`
+	ID        uint          `gorm:"primaryKey" json:"id"`
+	UserID    uint          `gorm:"not null" json:"user_id"`
+	Title     string        `gorm:"not null" json:"title"`
+	Content   string        `json:"content"`
+	Published bool          `gorm:"default:false" json:"published"`
+	CreatedAt time.Time     `json:"created_at"`
+	User      *TestUser     `gorm:"foreignKey:UserID" json:"user,omitempty"`
 	Comments  []TestComment `gorm:"foreignKey:PostID" json:"comments,omitempty"`
 }
 
@@ -54,7 +55,7 @@ type TestComment struct {
 	PostID    uint      `gorm:"not null" json:"post_id"`
 	Content   string    `gorm:"not null" json:"content"`
 	CreatedAt time.Time `json:"created_at"`
-	Post      *TestPost  `gorm:"foreignKey:PostID" json:"post,omitempty"`
+	Post      *TestPost `gorm:"foreignKey:PostID" json:"post,omitempty"`
 }
 
 func (TestComment) TableName() string {
@@ -401,7 +402,7 @@ func TestIntegration_GetMetadata(t *testing.T) {
 
 	muxRouter.ServeHTTP(w, req)
 
-	if w.Code != http.StatusOK {
+	if !(w.Code == http.StatusOK || w.Code == http.StatusPartialContent) {
 		t.Errorf("Expected status 200, got %d. Body: %s", w.Code, w.Body.String())
 	}
 
@@ -492,7 +493,7 @@ func TestIntegration_QueryParamsOverHeaders(t *testing.T) {
 
 	muxRouter.ServeHTTP(w, req)
 
-	if w.Code != http.StatusOK {
+	if !(w.Code == http.StatusOK || w.Code == http.StatusPartialContent) {
 		t.Errorf("Expected status 200, got %d", w.Code)
 	}
 

pkg/server/interfaces.go

@@ -0,0 +1,52 @@
+package server
+
+import (
+	"context"
+	"net/http"
+)
+
+// Config holds the configuration for a single web server instance.
+type Config struct {
+	Name        string
+	Host        string
+	Port        int
+	Description string
+	SSLCert     string
+	SSLKey      string
+	GZIP        bool
+	// Handler is the http.Handler (e.g., a router) to be served.
+	Handler http.Handler
+}
+
+// Instance defines the interface for a single server instance.
+// It abstracts the underlying http.Server, allowing for easier management and testing.
+type Instance interface {
+	// Start begins serving requests. This method should be non-blocking and
+	// run the server in a separate goroutine.
+	Start() error
+	// Stop gracefully shuts down the server without interrupting any active connections.
+	// It accepts a context to allow for a timeout.
+	Stop(ctx context.Context) error
+	// Addr returns the network address the server is listening on.
+	Addr() string
+}
+
+// Manager defines the interface for a server manager.
+// It is responsible for managing the lifecycle of multiple server instances.
+type Manager interface {
+	// Add registers a new server instance based on the provided configuration.
+	// The server is not started until StartAll or Start is called on the instance.
+	Add(cfg Config) (Instance, error)
+	// Get returns a server instance by its name.
+	Get(name string) (Instance, error)
+	// Remove stops and removes a server instance by its name.
+	Remove(name string) error
+	// StartAll starts all registered server instances that are not already running.
+	StartAll() error
+	// StopAll gracefully shuts down all running server instances.
+	StopAll() error
+	// RestartAll gracefully restarts all running server instances.
+	RestartAll() error
+	// List returns all registered server instances.
+	List() []Instance
+}

pkg/server/manager.go

@@ -0,0 +1,282 @@
+package server
+
+import (
+	"context"
+	"crypto/tls"
+	"fmt"
+	"net/http"
+	"sync"
+	"time"
+
+	"github.com/bitechdev/ResolveSpec/pkg/logger"
+	"github.com/bitechdev/ResolveSpec/pkg/middleware"
+	"github.com/klauspost/compress/gzhttp"
+	"golang.org/x/net/http2"
+)
+
+// serverManager manages a collection of server instances.
+type serverManager struct {
+	instances map[string]Instance
+	mu        sync.RWMutex
+}
+
+// NewManager creates a new server manager.
+func NewManager() Manager {
+	return &serverManager{
+		instances: make(map[string]Instance),
+	}
+}
+
+// Add registers a new server instance.
+func (sm *serverManager) Add(cfg Config) (Instance, error) {
+	sm.mu.Lock()
+	defer sm.mu.Unlock()
+
+	if cfg.Name == "" {
+		return nil, fmt.Errorf("server name cannot be empty")
+	}
+	if _, exists := sm.instances[cfg.Name]; exists {
+		return nil, fmt.Errorf("server with name '%s' already exists", cfg.Name)
+	}
+
+	instance, err := newInstance(cfg)
+	if err != nil {
+		return nil, err
+	}
+
+	sm.instances[cfg.Name] = instance
+	return instance, nil
+}
+
+// Get returns a server instance by its name.
+func (sm *serverManager) Get(name string) (Instance, error) {
+	sm.mu.RLock()
+	defer sm.mu.RUnlock()
+
+	instance, exists := sm.instances[name]
+	if !exists {
+		return nil, fmt.Errorf("server with name '%s' not found", name)
+	}
+	return instance, nil
+}
+
+// Remove stops and removes a server instance by its name.
+func (sm *serverManager) Remove(name string) error {
+	sm.mu.Lock()
+	defer sm.mu.Unlock()
+
+	instance, exists := sm.instances[name]
+	if !exists {
+		return fmt.Errorf("server with name '%s' not found", name)
+	}
+
+	// Stop the server if it's running
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	if err := instance.Stop(ctx); err != nil {
+		logger.Warn("Failed to gracefully stop server '%s' on remove: %v", name, err, context.Background())
+	}
+
+	delete(sm.instances, name)
+	return nil
+}
+
+// StartAll starts all registered server instances.
+func (sm *serverManager) StartAll() error {
+	sm.mu.RLock()
+	defer sm.mu.RUnlock()
+
+	var startErrors []error
+	for name, instance := range sm.instances {
+		if err := instance.Start(); err != nil {
+			startErrors = append(startErrors, fmt.Errorf("failed to start server '%s': %w", name, err))
+		}
+	}
+
+	if len(startErrors) > 0 {
+		// In a real-world scenario, you might want a more sophisticated error handling strategy
+		return fmt.Errorf("encountered errors while starting servers: %v", startErrors)
+	}
+	return nil
+}
+
+// StopAll gracefully shuts down all running server instances.
+func (sm *serverManager) StopAll() error {
+	sm.mu.RLock()
+	instancesToStop := make([]Instance, 0, len(sm.instances))
+	for _, instance := range sm.instances {
+		instancesToStop = append(instancesToStop, instance)
+	}
+	sm.mu.RUnlock()
+
+	logger.Info("Shutting down all servers...", context.Background())
+
+	var shutdownErrors []error
+	var wg sync.WaitGroup
+
+	for _, instance := range instancesToStop {
+		wg.Add(1)
+		go func(inst Instance) {
+			defer wg.Done()
+			ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+			defer cancel()
+			if err := inst.Stop(ctx); err != nil {
+				shutdownErrors = append(shutdownErrors, fmt.Errorf("failed to stop server '%s': %w", inst.Addr(), err))
+			}
+		}(instance)
+	}
+
+	wg.Wait()
+
+	if len(shutdownErrors) > 0 {
+		return fmt.Errorf("encountered errors while stopping servers: %v", shutdownErrors)
+	}
+	logger.Info("All servers stopped gracefully.", context.Background())
+	return nil
+}
+
+// RestartAll gracefully restarts all running server instances.
+func (sm *serverManager) RestartAll() error {
+	logger.Info("Restarting all servers...", context.Background())
+	if err := sm.StopAll(); err != nil {
+		return fmt.Errorf("failed to stop servers during restart: %w", err)
+	}
+
+	// Give ports time to be released
+	time.Sleep(200 * time.Millisecond)
+
+	if err := sm.StartAll(); err != nil {
+		return fmt.Errorf("failed to start servers during restart: %w", err)
+	}
+	logger.Info("All servers restarted successfully.", context.Background())
+	return nil
+}
+
+// List returns all registered server instances.
+func (sm *serverManager) List() []Instance {
+	sm.mu.RLock()
+	defer sm.mu.RUnlock()
+
+	instances := make([]Instance, 0, len(sm.instances))
+	for _, instance := range sm.instances {
+		instances = append(instances, instance)
+	}
+	return instances
+}
+
+// serverInstance is a concrete implementation of the Instance interface.
+type serverInstance struct {
+	cfg        Config
+	httpServer *http.Server
+	mu         sync.RWMutex
+	running    bool
+	stopCh     chan struct{}
+}
+
+// newInstance creates a new, unstarted server instance from a config.
+func newInstance(cfg Config) (*serverInstance, error) {
+	if cfg.Handler == nil {
+		return nil, fmt.Errorf("handler cannot be nil")
+	}
+
+	addr := fmt.Sprintf("%s:%d", cfg.Host, cfg.Port)
+	var handler http.Handler = cfg.Handler
+
+	// Wrap with GZIP handler if enabled
+	if cfg.GZIP {
+		gz, err := gzhttp.NewWrapper(gzhttp.BestSpeed)
+		if err != nil {
+			return nil, fmt.Errorf("failed to create GZIP wrapper: %w", err)
+		}
+		handler = gz(handler)
+	}
+
+	// Wrap with the panic recovery middleware
+	handler = middleware.PanicRecovery(handler)
+
+	// Here you could add other default middleware like request logging, metrics, etc.
+
+	httpServer := &http.Server{
+		Addr:         addr,
+		Handler:      handler,
+		ReadTimeout:  15 * time.Second,
+		WriteTimeout: 15 * time.Second,
+		IdleTimeout:  60 * time.Second,
+	}
+
+	return &serverInstance{
+		cfg:        cfg,
+		httpServer: httpServer,
+		stopCh:     make(chan struct{}),
+	}, nil
+}
+
+// Start begins serving requests in a new goroutine.
+func (s *serverInstance) Start() error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if s.running {
+		return fmt.Errorf("server '%s' is already running", s.cfg.Name)
+	}
+
+	hasSSL := s.cfg.SSLCert != "" && s.cfg.SSLKey != ""
+
+	go func() {
+		defer func() {
+			s.mu.Lock()
+			s.running = false
+			s.mu.Unlock()
+			logger.Info("Server '%s' stopped.", s.cfg.Name, context.Background())
+		}()
+
+		var err error
+		protocol := "HTTP"
+
+		if hasSSL {
+			protocol = "HTTPS"
+			// Configure TLS + HTTP/2
+			s.httpServer.TLSConfig = &tls.Config{
+				MinVersion: tls.VersionTLS12,
+			}
+			            logger.Info("Starting %s server '%s' on %s", protocol, s.cfg.Name, s.Addr(), context.Background())			err = s.httpServer.ListenAndServeTLS(s.cfg.SSLCert, s.cfg.SSLKey)
+		} else {
+			logger.Info("Starting %s server '%s' on %s", protocol, s.cfg.Name, s.Addr(), context.Background())
+			err = s.httpServer.ListenAndServe()
+		}
+
+		// If the server stopped for a reason other than a graceful shutdown, log the error.
+		if err != nil && err != http.ErrServerClosed {
+			logger.Error("Server '%s' failed: %v", s.cfg.Name, err, context.Background())
+		}
+	}()
+
+	s.running = true
+	// A small delay to allow the goroutine to start and potentially fail on binding.
+	// A more robust solution might involve a channel signal.
+	time.Sleep(50 * time.Millisecond)
+
+	return nil
+}
+
+// Stop gracefully shuts down the server.
+func (s *serverInstance) Stop(ctx context.Context) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if !s.running {
+		return nil // Already stopped
+	}
+
+	logger.Info("Gracefully shutting down server '%s'...", s.cfg.Name)
+	err := s.httpServer.Shutdown(ctx)
+	if err == nil {
+		s.running = false
+	}
+	return err
+}
+
+// Addr returns the network address the server is listening on.
+func (s *serverInstance) Addr() string {
+	return s.httpServer.Addr
+}

pkg/server/manager_test.go

@@ -0,0 +1,125 @@
+package server
+
+import (
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/bitechdev/ResolveSpec/pkg/logger"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// getFreePort asks the kernel for a free open port that is ready to use.
+func getFreePort(t *testing.T) int {
+	t.Helper()
+	addr, err := net.ResolveTCPAddr("tcp", "localhost:0")
+	require.NoError(t, err)
+
+	l, err := net.ListenTCP("tcp", addr)
+	require.NoError(t, err)
+	defer l.Close()
+	return l.Addr().(*net.TCPAddr).Port
+}
+
+func TestServerManagerLifecycle(t *testing.T) {
+	// Initialize logger for test output
+	logger.Init(true)
+
+	// Create a new server manager
+	sm := NewManager()
+
+	// Define a simple test handler
+	testHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("Hello, World!"))
+	})
+
+	// Get a free port for the server to listen on to avoid conflicts
+	testPort := getFreePort(t)
+
+	// Add a new server configuration
+	serverConfig := Config{
+		Name:    "TestServer",
+		Host:    "localhost",
+		Port:    testPort,
+		Handler: testHandler,
+	}
+	instance, err := sm.Add(serverConfig)
+	require.NoError(t, err, "should be able to add a new server")
+	require.NotNil(t, instance, "added instance should not be nil")
+
+	// --- Test StartAll ---
+	err = sm.StartAll()
+	require.NoError(t, err, "StartAll should not return an error")
+
+	// Give the server a moment to start up
+	time.Sleep(100 * time.Millisecond)
+
+	// --- Verify Server is Running ---
+	client := &http.Client{Timeout: 2 * time.Second}
+	url := fmt.Sprintf("http://localhost:%d", testPort)
+	resp, err := client.Get(url)
+	require.NoError(t, err, "should be able to make a request to the running server")
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode, "expected status OK from the test server")
+	body, err := io.ReadAll(resp.Body)
+	require.NoError(t, err)
+	resp.Body.Close()
+	assert.Equal(t, "Hello, World!", string(body), "response body should match expected value")
+
+	// --- Test Get ---
+	retrievedInstance, err := sm.Get("TestServer")
+	require.NoError(t, err, "should be able to get server by name")
+	assert.Equal(t, instance.Addr(), retrievedInstance.Addr(), "retrieved instance should be the same")
+
+	// --- Test List ---
+	instanceList := sm.List()
+	require.Len(t, instanceList, 1, "list should contain one instance")
+	assert.Equal(t, instance.Addr(), instanceList[0].Addr(), "listed instance should be the same")
+
+	// --- Test StopAll ---
+	err = sm.StopAll()
+	require.NoError(t, err, "StopAll should not return an error")
+
+	// Give the server a moment to shut down
+	time.Sleep(100 * time.Millisecond)
+
+	// --- Verify Server is Stopped ---
+	_, err = client.Get(url)
+	require.Error(t, err, "should not be able to make a request to a stopped server")
+
+	// --- Test Remove ---
+	err = sm.Remove("TestServer")
+	require.NoError(t, err, "should be able to remove a server")
+
+	_, err = sm.Get("TestServer")
+	require.Error(t, err, "should not be able to get a removed server")
+}
+
+func TestManagerErrorCases(t *testing.T) {
+	logger.Init(true)
+	sm := NewManager()
+	testPort := getFreePort(t)
+
+	// --- Test Add Duplicate Name ---
+	config1 := Config{Name: "Duplicate", Host: "localhost", Port: testPort, Handler: http.NewServeMux()}
+	_, err := sm.Add(config1)
+	require.NoError(t, err)
+
+	config2 := Config{Name: "Duplicate", Host: "localhost", Port: getFreePort(t), Handler: http.NewServeMux()}
+	_, err = sm.Add(config2)
+	require.Error(t, err, "should not be able to add a server with a duplicate name")
+
+	// --- Test Get Non-existent ---
+	_, err = sm.Get("NonExistent")
+	require.Error(t, err, "should get an error for a non-existent server")
+
+	// --- Test Add with Nil Handler ---
+	config3 := Config{Name: "NilHandler", Host: "localhost", Port: getFreePort(t), Handler: nil}
+	_, err = sm.Add(config3)
+	require.Error(t, err, "should not be able to add a server with a nil handler")
+}

pkg/tracing/README.md

@@ -465,7 +465,7 @@ func processRequest(ctx context.Context) {
 
 1. **Check collector is running:**
    ```bash
-   docker-compose ps
+   podman compose ps
    ```
 
 2. **Verify endpoint:**
@@ -476,7 +476,7 @@ func processRequest(ctx context.Context) {
 
 3. **Check logs:**
    ```bash
-   docker-compose logs otel-collector
+   podman compose logs otel-collector
    ```
 
 ### Disable Tracing

scripts/run-integration-tests.sh

@@ -14,33 +14,33 @@ NC='\033[0m' # No Color
 
 echo -e "${GREEN}=== ResolveSpec Integration Tests ===${NC}\n"
 
-# Check if docker-compose is available
-if ! command -v docker-compose &> /dev/null; then
-    echo -e "${RED}Error: docker-compose is not installed${NC}"
-    echo "Please install docker-compose or run PostgreSQL manually"
+# Check if podman compose is available
+if ! command -v podman &> /dev/null; then
+    echo -e "${RED}Error: podman is not installed${NC}"
+    echo "Please install podman or run PostgreSQL manually"
     echo "See INTEGRATION_TESTS.md for details"
     exit 1
 fi
 
 # Clean up any existing containers and networks from previous runs
 echo -e "${YELLOW}Cleaning up existing containers and networks...${NC}"
-docker-compose down -v 2>/dev/null || true
+podman compose down -v 2>/dev/null || true
 
 # Start PostgreSQL
 echo -e "${YELLOW}Starting PostgreSQL...${NC}"
-docker-compose up -d postgres-test
+podman compose up -d postgres-test
 
 # Wait for PostgreSQL to be ready
 echo -e "${YELLOW}Waiting for PostgreSQL to be ready...${NC}"
 max_attempts=30
 attempt=0
 
-while ! docker-compose exec -T postgres-test pg_isready -U postgres > /dev/null 2>&1; do
+while ! podman compose exec -T postgres-test pg_isready -U postgres > /dev/null 2>&1; do
     attempt=$((attempt + 1))
     if [ $attempt -ge $max_attempts ]; then
         echo -e "${RED}Error: PostgreSQL failed to start after ${max_attempts} seconds${NC}"
-        docker-compose logs postgres-test
-        docker-compose down
+        podman compose logs postgres-test
+        podman compose down
         exit 1
     fi
     sleep 1
@@ -51,8 +51,8 @@ echo -e "\n${GREEN}PostgreSQL is ready!${NC}\n"
 
 # Create test databases
 echo -e "${YELLOW}Creating test databases...${NC}"
-docker-compose exec -T postgres-test psql -U postgres -c "CREATE DATABASE resolvespec_test;" 2>/dev/null || echo "  resolvespec_test already exists"
-docker-compose exec -T postgres-test psql -U postgres -c "CREATE DATABASE restheadspec_test;" 2>/dev/null || echo "  restheadspec_test already exists"
+podman compose exec -T postgres-test psql -U postgres -c "CREATE DATABASE resolvespec_test;" 2>/dev/null || echo "  resolvespec_test already exists"
+podman compose exec -T postgres-test psql -U postgres -c "CREATE DATABASE restheadspec_test;" 2>/dev/null || echo "  restheadspec_test already exists"
 echo -e "${GREEN}Test databases ready!${NC}\n"
 
 # Determine which tests to run
@@ -79,6 +79,6 @@ fi
 
 # Cleanup
 echo -e "\n${YELLOW}Stopping PostgreSQL...${NC}"
-docker-compose down
+podman compose down
 
 exit $EXIT_CODE

tests/INTEGRATION_TESTS.md

@@ -19,14 +19,14 @@ Integration tests validate the full functionality of both `pkg/resolvespec` and
 
 - Go 1.19 or later
 - PostgreSQL 12 or later
-- Docker and Docker Compose (optional, for easy setup)
+- Podman and Podman Compose (optional, for easy setup)
 
-## Quick Start with Docker
+## Quick Start with Podman
 
-### 1. Start PostgreSQL with Docker Compose
+### 1. Start PostgreSQL with Podman Compose
 
 ```bash
-docker-compose up -d postgres-test
+podman compose up -d postgres-test
 ```
 
 This starts a PostgreSQL container with the following default settings:
@@ -52,7 +52,7 @@ go test -tags=integration ./pkg/restheadspec -v
 ### 3. Stop PostgreSQL
 
 ```bash
-docker-compose down
+podman compose down
 ```
 
 ## Manual PostgreSQL Setup
@@ -161,7 +161,7 @@ If you see "connection refused" errors:
 
 1. Check that PostgreSQL is running:
    ```bash
-   docker-compose ps
+   podman compose ps
    ```
 
 2. Verify connection parameters:
@@ -194,10 +194,10 @@ Each test automatically cleans up its data using `TRUNCATE`. If you need a fresh
 
 ```bash
 # Stop and remove containers (removes data)
-docker-compose down -v
+podman compose down -v
 
 # Restart
-docker-compose up -d postgres-test
+podman compose up -d postgres-test
 ```
 
 ## CI/CD Integration

tests/README_TESTS.md

@@ -119,13 +119,13 @@ Integration tests require a PostgreSQL database and use the `// +build integrati
 - PostgreSQL 12+ installed and running
 - Create test databases manually (see below)
 
-### Setup with Docker
+### Setup with Podman
 
 1. **Start PostgreSQL**:
    ```bash
    make docker-up
    # or
-   docker-compose up -d postgres-test
+   podman compose up -d postgres-test
    ```
 
 2. **Run Tests**:
@@ -141,10 +141,10 @@ Integration tests require a PostgreSQL database and use the `// +build integrati
    ```bash
    make docker-down
    # or
-   docker-compose down
+   podman compose down
    ```
 
-### Setup without Docker
+### Setup without Podman
 
 1. **Create Databases**:
    ```sql
@@ -289,8 +289,8 @@ go test -tags=integration ./pkg/resolvespec -v
 **Problem**: "connection refused" or "database does not exist"
 
 **Solutions**:
-1. Check PostgreSQL is running: `docker-compose ps`
-2. Verify databases exist: `docker-compose exec postgres-test psql -U postgres -l`
+1. Check PostgreSQL is running: `podman compose ps`
+2. Verify databases exist: `podman compose exec postgres-test psql -U postgres -l`
 3. Check environment variable: `echo $TEST_DATABASE_URL`
 4. Recreate databases: `make clean && make docker-up`