jeffotoni / quick / 260

Committed 19 Mar 2025 02:23PM UTC coverage: 52.974% (-0.03%) from 53.001%

Build # 260

Build Type

push

circleci

Committed by

jeffotoni

Commit Message

Commit Message

📌 Refactoring and improvements to the body limit middleware in Quick
• Implemented quick.MaxBytesReader to wrap http.MaxBytesReader.
• Fixed and improved ContentLength validation to avoid 413 errors.
• Adjustments to body reading to avoid inconsistencies in
MaxBytesReader.
• Fixed tests (q.Qtest) to ensure that Body is handled correctly.
• Improved documentation and test coverage for exact limit cases,
overflow, and empty body.

Run Details

20 of 24 new or added lines in 3 files covered. (83.33%)

3 existing lines in 1 file now uncovered.

2716 of 5127 relevant lines covered (52.97%)

1949.41 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

84.74

/quick.go

/*
🚀 Quick is a flexible and extensible route manager for the Go language.
It aims to be fast and performant, and 100% net/http compatible.
Quick is a project under constant development and is open for collaboration,
everyone is welcome to contribute. 😍
*/
package quick

import (
        "bytes"
        "context"
        "crypto/tls"
        "embed"
        "encoding/json"
        "encoding/xml"
        "fmt"
        "io"
        "log"
        "net"
        "net/http"
        "net/http/httptest"
        "os/signal"
        "regexp"
        "runtime"
        "runtime/debug"
        "strings"
        "sync"
        "syscall"
        "time"

        "github.com/jeffotoni/quick/internal/concat"
)

// SO_REUSEPORT is a constant manually defined for Linux systems
const SO_REUSEPORT = 0x0F

// Content-Type constants used for response headers
const (
        ContentTypeAppJSON = `application/json`
        ContentTypeAppXML  = `application/xml`
        ContentTypeTextXML = `text/xml`
)

// contextKey is a custom type used for storing values in context
type contextKey int

// myContextKey is a predefined key used for context storage
const myContextKey contextKey = 0

// HandleFunc represents a function signature for route handlers in Quick.
//
// This function type is used for defining request handlers within Quick's
// routing system. It receives a pointer to `Ctx`, which encapsulates
// request and response data.
//
// Example Usage:
//
//        q.Get("/example", func(c *quick.Ctx) error {
//            return c.Status(quick.StatusOK).SendString("Hello, Quick!")
//        })
type HandleFunc func(*Ctx) error

// HandlerFunc defines the function signature for request handlers in Quick.
//
// This type provides a way to implement request handlers as standalone
// functions while still conforming to the `Handler` interface. It allows
// functions of type `HandlerFunc` to be passed as middleware or endpoint handlers.
//
// Example Usage:
//
//        func myHandler(c *quick.Ctx) error {
//            return c.Status(quick.StatusOK).SendString("HandlerFunc example")
//        }
//
//        q.Use(quick.HandlerFunc(myHandler))
type HandlerFunc func(c *Ctx) error

// Handler defines an interface that wraps the ServeQuick method.
//
// Any type implementing `ServeQuick(*Ctx) error` can be used as a request
// handler in Quick. This abstraction allows for more flexible middleware
// and handler implementations, including struct-based handlers.
//
// Example Usage:
//
//        type MyHandler struct{}
//
//        func (h MyHandler) ServeQuick(c *quick.Ctx) error {
//            return c.Status(quick.StatusOK).SendString("Struct-based handler")
//        }
//
//        q.Use(MyHandler{})
type Handler interface {
        // ServeQuick processes an HTTP request in the Quick framework.
        //
        // Parameters:
        //   - c *Ctx: The request context containing request and response details.
        //
        // Returns:
        //   - error: Any error encountered while processing the request.
        ServeQuick(*Ctx) error
}

// ServeQuick allows a HandlerFunc to satisfy the Handler interface.
//
// This method enables `HandlerFunc` to be used wherever a `Handler`
// is required by implementing the `ServeQuick` method.
//
// Example Usage:
//
//        q.Use(quick.HandlerFunc(func(c *quick.Ctx) error {
//            return c.Status(quick.StatusOK).SendString("Hello from HandlerFunc!")
//        }))
func (h HandlerFunc) ServeQuick(c *Ctx) error {
        return h(c)
}

// MaxBytesReader is a thin wrapper around http.MaxBytesReader to limit the
// size of the request body in Quick applications.
//
// It returns an io.ReadCloser that reads from r but stops with an error
// after n bytes.  The sink just sees an io.EOF.
//
// This is useful to protect against large request bodies.
//
// Example usage:
//
//        c.Request.Body = quick.MaxBytesReader(c.Response, c.Request.Body, 10_000) // 10KB
func MaxBytesReader(w http.ResponseWriter, r io.ReadCloser, n int64) io.ReadCloser {
        // Internally, just call the standard library function.
        return http.MaxBytesReader(w, r, n)
}

// Route represents a registered HTTP route in the Quick framework
type Route struct {
        Group   string           // Route group for organization
        Pattern string           // URL pattern associated with the route
        Path    string           // The registered path for the route
        Params  string           // Parameters extracted from the URL
        Method  string           // HTTP method associated with the route (GET, POST, etc.)
        handler http.HandlerFunc // Handler function for processing the request
}

// ctxServeHttp represents the structure for handling HTTP requests
type ctxServeHttp struct {
        Path      string            // Requested URL path
        Params    string            // Query parameters from the request
        Method    string            // HTTP method of the request
        ParamsMap map[string]string // Parsed parameters mapped as key-value pairs
}

// Config defines various configuration options for the Quick server
type Config struct {
        BodyLimit      int64 // Deprecated: Use MaxBodySize instead
        MaxBodySize    int64 // Maximum request body size allowed.
        MaxHeaderBytes int   // Maximum number of bytes allowed in the HTTP headers.

        GOMAXPROCS      int   // defines the maximum number of CPU cores
        GCHeapThreshold int64 // GCHeapThreshold sets the memory threshold (in bytes)
        BufferPoolSize  int   // BufferPoolSize determines the size (in bytes)

        RouteCapacity     int           // Initial capacity of the route slice.
        MoreRequests      int           // Value to set GCPercent. influences the garbage collector performance. 0-1000
        ReadTimeout       time.Duration // Maximum duration for reading the entire request.
        WriteTimeout      time.Duration // Maximum duration before timing out writes of the response.
        IdleTimeout       time.Duration // Maximum amount of time to wait for the next request when keep-alives are enabled.
        ReadHeaderTimeout time.Duration // Amount of time allowed to read request headers.
        GCPercent         int           // Renamed to be more descriptive (0-1000) - influences the garbage collector performance.
        TLSConfig         *tls.Config   // Integrated TLS configuration
        CorsConfig        *CorsConfig   // Specific type for CORS

        NoBanner bool // Flag to disable the Quick startup Display.
}

// defaultConfig defines the default values for the Quick server configuration
var defaultConfig = Config{
        BodyLimit:      2 * 1024 * 1024, // Deprecated: Use MaxBodySize instead
        MaxBodySize:    2 * 1024 * 1024, // 2MB max request body size
        MaxHeaderBytes: 1 * 1024 * 1024, // 1MB max header size

        GOMAXPROCS:      runtime.NumCPU(), // Use all available CPU cores
        GCHeapThreshold: 1 << 30,          // 1GB memory threshold for GC
        BufferPoolSize:  32768,            // Buffer pool size

        RouteCapacity: 1000,  // Default initial route capacity
        MoreRequests:  290,   // Default GC value
        NoBanner:      false, // Show Quick banner by default
}

// Zeroth is a custom type for zero-value constants
type Zeroth int

// Zero is a predefined constant of type Zeroth
const (
        Zero Zeroth = 0
)

// CorsConfig defines the CORS settings for Quick
type CorsConfig struct {
        Enabled  bool              // If true, enables CORS support
        Options  map[string]string // Custom CORS options
        AllowAll bool              // If true, allows all origins
}

// Quick is the main structure of the framework, holding routes and configurations.
type Quick struct {
        config        Config         // Configuration settings.
        Cors          bool           // Indicates if CORS is enabled.
        groups        []Group        // List of route groups.
        handler       http.Handler   // The primary HTTP handler.
        mux           *http.ServeMux // Multiplexer for routing requests.
        routes        []*Route       // Registered routes.
        routeCapacity int            // The maximum number of routes allowed.
        mws2          []any          // List of registered middlewares.

        CorsSet     func(http.Handler) http.Handler // CORS middleware handler function.
        CorsOptions map[string]string               // CORS options map
        // corsConfig    *CorsConfig // Specific type for CORS // Removed unused field
        embedFS embed.FS     // File system for embedded static files.
        server  *http.Server // Http server

        bufferPool *sync.Pool
}

// indeed to Quick
type App = Quick

// HandlerFunc adapts a quick.HandlerFunc to a standard http.HandlerFunc.
// It creates a new Quick context (Ctx) for each HTTP request,
// allowing Quick handlers to access request and response objects seamlessly.
//
// Usage Example:
//
//        http.HandleFunc(\"/\", app.HandlerFunc(func(c *quick.Ctx) error {
//                return c.Status(200).JSON(map[string]string{\"message\": \"Hello, Quick!\"})
//        }))
func (q *Quick) HandlerFunc(h HandlerFunc) http.HandlerFunc {
        return func(w http.ResponseWriter, req *http.Request) {
                c := &Ctx{
                        Response: w,
                        Request:  req,
                        App:      q,
                }

                if err := h(c); err != nil {
                        http.Error(w, err.Error(), StatusInternalServerError)
                }
        }
}

// Handler returns the main HTTP handler for Quick, allowing integration with standard http.Server and testing frameworks.
func (q *Quick) Handler() http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
                q.ServeHTTP(w, r)
        })
}

// MiddlewareFunc defines the signature for middleware functions in Quick.
// A middleware function receives the next HandlerFunc in the chain and returns a new HandlerFunc.
// Middleware can perform actions before and/or after calling the next handler.
//
// Example:
//
//        func LoggingMiddleware() quick.MiddlewareFunc {
//                return func(next quick.HandlerFunc) quick.HandlerFunc {
//                        return func(c *quick.Ctx) error {
//                                // Before handler logic (e.g., logging request details)
//                                log.Printf("Request received: %s %s", c.Request.Method, c.Request.URL)
//
//                                err := next(c) // Call the next handler
//
//                                // After handler logic (e.g., logging response status)
//                                log.Printf("Response sent with status: %d", c.ResponseWriter.Status())
//
//                                return err
//                        }
//                }
//        }
type MiddlewareFunc func(next HandlerFunc) HandlerFunc

// GetDefaultConfig returns the default configuration pre-defined for the system.
//
// This function provides a standardized configuration setup, ensuring that
// new instances use a consistent and optimized set of defaults.
//
// Returns:
//   - Config: A struct containing the default system configuration.
//
// Example Usage:
//
//        // This function is typically used when initializing a new Quick instance
//        // to ensure it starts with the default settings if no custom config is provided.
func GetDefaultConfig() Config {
        return defaultConfig
}

// New creates a new instance of the Quick structure to manage HTTP routes and handlers.
//
// This function initializes a Quick instance with optional configurations provided
// through the `Config` parameter. If no configuration is provided, it uses the `defaultConfig`.
//
// Parameters:
//   - c ...Config: (Optional) Configuration settings for customizing the Quick instance.
//
// Returns:
//   - *Quick: A pointer to the initialized Quick instance.
//
// Example Usage:
//
//        // Basic usage - Create a default Quick instance
//        q := quick.New()
//
//        // Custom usage - Create a Quick instance with specific configurations
//        q := quick.New(quick.Config{
//                RouteCapacity: 500,
//        })
//
//        q.Get("/", func(c quick.Ctx) error {
//                return c.SendString("Hello, Quick!")
//        })
func New(c ...Config) *Quick {
        var config Config
        // Check if a custom configuration is provided
        if len(c) > 0 {
                config = c[0] // Use the provided configuration
        } else {
                config = defaultConfig // Use the default configuration
        }

        // Ensure a minimum route capacity if not set
        if config.RouteCapacity == 0 {
                config.RouteCapacity = 1000
        }

        // Initialize and return the Quick instance
        return &Quick{
                routes:        make([]*Route, 0, config.RouteCapacity),
                routeCapacity: config.RouteCapacity,
                mux:           http.NewServeMux(),
                handler:       http.NewServeMux(),
                config:        config,
        }
}

// Use function adds middleware to the Quick server, with special treatment for CORS.
//
// This method allows adding custom middleware functions to process requests before they
// reach the final handler. If a CORS middleware is detected, it is automatically applied.
//
// Parameters:
//   - mw any: Middleware function to be added. It must be of type `func(http.Handler) http.Handler`.
//
// Example Usage:
//
//        q := quick.New()
//
//        q.Use(maxbody.New(50000))
//
//        q.Post("/v1/user/maxbody/any", func(c *quick.Ctx) error {
//            c.Set("Content-Type", "application/json")//
//            return c.Status(200).Send(c.Body())
//        })
func (q *Quick) Use(mw any) {
        switch mwc := mw.(type) {
        case func(http.Handler) http.Handler:
                // Detect if the middleware is related to CORS and apply it separately
                if isCorsMiddleware(mwc) {
                        q.Cors = true
                        q.CorsSet = mwc
                        return
                }

        case func(HandleFunc) HandleFunc:
                q.mws2 = append(q.mws2, mwc)

        }

        // Append middleware to the list of registered middlewares
        q.mws2 = append(q.mws2, mw)

}

// isCorsMiddleware checks whether the provided middleware function is a CORS handler.
//
// This function detects if a middleware is handling CORS by sending an
// HTTP OPTIONS request and checking if it sets the `Access-Control-Allow-Origin` header.
//
// Parameters:
//   - mw func(http.Handler) http.Handler: The middleware function to be tested.
//
// Returns:
//   - bool: `true` if the middleware is identified as CORS, `false` otherwise.
//
// Example Usage:
// This function is automatically executed when a middleware is added to detect if it's a CORS handler.
func isCorsMiddleware(mw func(http.Handler) http.Handler) bool {
        testHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {})
        testRequest := httptest.NewRequest("OPTIONS", "/", nil)
        testResponse := httptest.NewRecorder()

        mw(testHandler).ServeHTTP(testResponse, testRequest)

        // If the middleware sets Access-Control-Allow-Origin, it's CORS
        return testResponse.Header().Get("Access-Control-Allow-Origin") != ""
}

// clearRegex processes a route pattern, removing dynamic path parameters
// and replacing them with a simplified placeholder.
//
// This function is used internally to standardize dynamic routes in
// ServeMux, converting patterns like `/v1/user/{id:[0-9]+}` into
// `/v1/user/_id_`, making them easier to process.
//
// Parameters:
//   - route string: The route pattern containing dynamic parameters.
//
// Returns:
//   - string: A cleaned-up version of the route with placeholders instead of regex patterns.
//
// Example Usage:
// This function is automatically triggered internally to normalize route patterns.
func clearRegex(route string) string {
        // Here you transform "/v1/user/{id:[0-9]+}"
        // into something simple, like "/v1/user/_id_"
        // You can get more sophisticated if you want
        var re = regexp.MustCompile(`\{[^/]+\}`)
        return re.ReplaceAllStringFunc(route, func(s string) string {
                // s is "{id:[0-9]+}"
                // Let's just replace it with "_id_"
                // or any string that doesn't contain ":" or "{ }"
                return "_" + strings.Trim(s, "{}") + "_"
                //return "_" + strings.ReplaceAll(strings.ReplaceAll(strings.Trim(s, "{}"), ":", "_"), "[", "_") + "_"
        })
}

// registerRoute is a helper function that centralizes the logic for registering routes.
//
// This function processes and registers an HTTP route, ensuring no duplicate routes
// are added. It extracts route parameters, formats the route, and associates the
// appropriate handler function.
//
// Parameters:
//   - method string: The HTTP method (e.g., "GET", "POST").
//   - pattern string: The route pattern, which may include dynamic parameters.
//   - handlerFunc HandleFunc: The function that will handle the route.
//
// Example Usage:
// This function is automatically triggered internally when a new route is added.
func (q *Quick) registerRoute(method, pattern string, handlerFunc HandleFunc) {
        path, params, patternExist := extractParamsPattern(pattern)
        formattedPath := concat.String(strings.ToLower(method), "#", clearRegex(pattern))

        for _, route := range q.routes {
                if route.Method == method && route.Path == path {
                        fmt.Printf("Warning: Route '%s %s' is already registered, ignoring duplicate registration.\n", method, path)
                        return // Ignore duplication instead of generating panic
                }
        }

        route := Route{
                Pattern: patternExist,
                Path:    path,
                Params:  params,
                handler: extractHandler(q, method, path, params, handlerFunc),
                Method:  method,
        }

        q.appendRoute(&route)
        q.mux.HandleFunc(formattedPath, route.handler)

}

// handleOptions processes HTTP OPTIONS requests for CORS preflight checks.
// This function is automatically called before routing when an OPTIONS request is received.
// It ensures that the appropriate CORS headers are included in the response.
//
// If CORS middleware is enabled, it applies the middleware before setting default headers.
//
// Headers added by this function:
// - Access-Control-Allow-Origin: Allows cross-origin requests (set dynamically).
// - Access-Control-Allow-Methods: Specifies allowed HTTP methods (GET, POST, PUT, DELETE, OPTIONS).
// - Access-Control-Allow-Headers: Defines which headers are allowed in the request.
//
// If no Origin header is provided in the request, a 204 No Content response is returned.
//
// Parameters:
// - w: http.ResponseWriter – The response writer to send headers and status.
// - r: *http.Request – The incoming HTTP request.
//
// Response:
// - 204 No Content (if the request is valid and processed successfully).
//
// Example Usage:
// This function is automatically triggered in `ServeHTTP()` when an OPTIONS request is received.
func (q *Quick) handleOptions(w http.ResponseWriter, r *http.Request) {
        origin := r.Header.Get("Origin")
        if origin == "" {
                w.WriteHeader(StatusNoContent)
                return
        }

        // Apply CORS middleware before setting headers
        if q.Cors && q.CorsSet != nil {
                q.CorsSet(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {})).ServeHTTP(w, r)
        }

        // Set default CORS headers
        w.Header().Set("Allow", "GET, POST, PUT, DELETE, OPTIONS")
        w.Header().Set("Access-Control-Allow-Origin", "*") // Ajustável pelo middleware
        w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
        w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")

        w.WriteHeader(http.StatusNoContent) // Returns 204 No Content
}

// Get registers an HTTP route with the GET method on the Quick server.
//
// This function associates a GET request with a specific route pattern and handler function.
// It ensures that the request is properly processed when received.
//
// Parameters:
//   - pattern string: The route pattern (e.g., "/users/:id").
//   - handlerFunc HandleFunc: The function that will handle the GET request.
//
// Example Usage:
//
//        // This function is automatically triggered when defining a GET route in Quick.
func (q *Quick) Get(pattern string, handlerFunc HandleFunc) {
        q.registerRoute(MethodGet, pattern, handlerFunc)
}

// Post registers an HTTP route with the POST method on the Quick server.
//
// This function associates a POST request with a specific route pattern and handler function.
// It is typically used for handling form submissions, JSON payloads, or data creation.
//
// Parameters:
//   - pattern string: The route pattern (e.g., "/users").
//   - handlerFunc HandleFunc: The function that will handle the POST request.
//
// Example Usage:
//
//        // This function is automatically triggered when defining a POST route in Quick.
func (q *Quick) Post(pattern string, handlerFunc HandleFunc) {
        q.registerRoute(MethodPost, pattern, handlerFunc)
}

// Put registers an HTTP route with the PUT method on the Quick server.
//
// This function associates a PUT request with a specific route pattern and handler function.
// It is typically used for updating existing resources.
//
// Parameters:
//   - pattern string: The route pattern (e.g., "/users/:id").
//   - handlerFunc HandleFunc: The function that will handle the PUT request.
//
// Example Usage:
//
//        // This function is automatically triggered when defining a PUT route in Quick.
func (q *Quick) Put(pattern string, handlerFunc HandleFunc) {
        q.registerRoute(MethodPut, pattern, handlerFunc)
}

// Delete registers an HTTP route with the DELETE method on the Quick server.
//
// This function associates a DELETE request with a specific route pattern and handler function.
// It is typically used for deleting existing resources.
//
// Parameters:
//   - pattern string: The route pattern (e.g., "/users/:id").
//   - handlerFunc HandleFunc: The function that will handle the DELETE request.
//
// Example Usage:
//
//        // This function is automatically triggered when defining a DELETE route in Quick.
func (q *Quick) Delete(pattern string, handlerFunc HandleFunc) {
        q.registerRoute(MethodDelete, pattern, handlerFunc)
}

// Patch registers an HTTP route with the PATCH method on the Quick server.
//
// This function associates a PATCH request with a specific route pattern and handler function.
// It is typically used for applying partial updates to an existing resource.
//
// Parameters:
//   - pattern string: The route pattern (e.g., "/users/:id").
//   - handlerFunc HandleFunc: The function that will handle the PATCH request.
//
// Example Usage:
//
//        // This function is automatically triggered when defining a PATCH route in Quick.
func (q *Quick) Patch(pattern string, handlerFunc HandleFunc) {
        q.registerRoute(MethodPatch, pattern, handlerFunc)
}

// Options registers an HTTP route with the OPTIONS method on the Quick server.
//
// This function associates an OPTIONS request with a specific route pattern and handler function.
// OPTIONS requests are typically used to determine the allowed HTTP methods for a resource.
//
// Parameters:
//   - pattern string: The route pattern (e.g., "/users").
//   - handlerFunc HandleFunc: The function that will handle the OPTIONS request.
//
// Example Usage:
//
//        // This function is automatically triggered when defining an OPTIONS route in Quick.
func (q *Quick) Options(pattern string, handlerFunc HandleFunc) {
        q.registerRoute(MethodOptions, pattern, handlerFunc)
}

// extractHandler selects the appropriate handler function for different HTTP methods.
//
// This function is responsible for determining which internal request processing function
// should handle a given HTTP method. It maps the method to the corresponding request parser.
//
// Parameters:
//   - q *Quick: The Quick instance managing the route and request context.
//   - method string: The HTTP method (e.g., "GET", "POST").
//   - path string: The route path associated with the request.
//   - params string: Route parameters extracted from the request URL.
//   - handlerFunc HandleFunc: The function that will handle the request.
//
// Returns:
//   - http.HandlerFunc: The appropriate handler function based on the HTTP method.
//
// Example Usage:
//
//        // This function is automatically executed internally when processing an HTTP request.
func extractHandler(q *Quick, method, path, params string, handlerFunc HandleFunc) http.HandlerFunc {
        switch method {
        case MethodGet:
                return extractParamsGet(q, path, params, handlerFunc)
        case MethodPost:
                return extractParamsPost(q, handlerFunc)
        case MethodPut:
                return extractParamsPut(q, handlerFunc)
        case MethodDelete:
                return extractParamsDelete(q, handlerFunc)
        case MethodPatch:
                return extractParamsPatch(q, handlerFunc) // same as PUT
        case MethodOptions:
                return extractParamsOptions(q, method, path, handlerFunc)
        }
        return nil
}

// extractParamsPatch processes an HTTP PATCH request by reusing the logic of the PUT method.
//
// The PATCH method is typically used for partial updates, while PUT replaces an entire resource.
// However, both methods often handle request parameters and body parsing in the same way,
// so this function delegates the processing to `extractParamsPut`.
//
// Parameters:
//   - q *Quick: The Quick instance managing the request context.
//   - handlerFunc HandleFunc: The function that will handle the PATCH request.
//
// Returns:
//   - http.HandlerFunc: A handler function that processes PATCH requests.
//
// Example Usage:
//
//        // This function is automatically executed internally when a PATCH request is received.
func extractParamsPatch(q *Quick, handlerFunc HandleFunc) http.HandlerFunc {
        return extractParamsPut(q, handlerFunc)
}

// extractParamsOptions processes an HTTP OPTIONS request, setting appropriate
// headers to handle CORS preflight requests. It reuses a pooled Ctx instance
// for optimized memory usage and performance.
//
// If a handlerFunc is provided, it executes that handler with the pooled context.
// If no handlerFunc is given, it responds with HTTP 204 No Content.
//
// Parameters:
//   - q: The Quick instance providing configurations and routing context.
//   - method: The HTTP method being handled (typically "OPTIONS").
//   - path: The route path being handled.
//   - handlerFunc: An optional handler to execute for the OPTIONS request.
//
// Returns:
//   - http.HandlerFunc: A handler function optimized for handling OPTIONS requests.
func extractParamsOptions(q *Quick, method, path string, handlerFunc HandleFunc) http.HandlerFunc {
        return func(w http.ResponseWriter, r *http.Request) {
                // Acquire a pooled context
                ctx := acquireCtx()
                defer releaseCtx(ctx) // Ensure context is returned to the pool after handling

                // Populate the pooled context
                ctx.Response = w
                ctx.Request = r
                ctx.MoreRequests = q.config.MoreRequests

                if q.Cors && q.CorsSet != nil {
                        wrappedHandler := q.CorsSet(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
                                // Middleware CORS apply success
                        }))
                        wrappedHandler.ServeHTTP(w, r)
                }

                if ctx.Response.Header().Get("Access-Control-Allow-Origin") == "" {
                        allowMethods := []string{MethodGet, MethodPost, MethodPut, MethodDelete, MethodPatch, MethodOptions}
                        ctx.Set("Allow", strings.Join(allowMethods, ", "))
                        ctx.Set("Access-Control-Allow-Origin", "*")
                        ctx.Set("Access-Control-Allow-Methods", strings.Join(allowMethods, ", "))
                        ctx.Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
                }

                // Execute handler function if provided
                if handlerFunc != nil {
                        if err := handlerFunc(ctx); err != nil {
                                http.Error(w, err.Error(), StatusInternalServerError)
                        }
                } else {
                        w.WriteHeader(StatusNoContent) // 204 No Content if no handlerFunc
                }
        }
}

// extractHeaders extracts all headers from an HTTP request and returns them as a map.
//
// This function iterates over all headers in the request and organizes them into a
// map structure, where each header key is mapped to its corresponding values.
//
// Parameters:
//   - req http.Request: The HTTP request from which headers will be extracted.
//
// Returns:
//   - map[string][]string: A map containing all request headers.
//
// Example Usage:
//
//        // This function is automatically executed internally when extracting headers from a request.
func extractHeaders(req http.Request) map[string][]string {
        headersMap := make(map[string][]string)
        for key, values := range req.Header {
                headersMap[key] = values
        }
        return headersMap
}

// extractParamsBind decodes request bodies for JSON/XML payloads using a pooled buffer
// to minimize memory allocations and garbage collection overhead.
//
// This function checks the request's `Content-Type` and processes JSON or XML payloads accordingly.
// It ensures efficient memory usage by leveraging buffer pools for reading request bodies.
//
// Parameters:
//   - c *Ctx: The Quick context containing request information.
//   - v interface{}: The target structure where the decoded JSON/XML data will be stored.
//
// Returns:
//   - error: Returns any decoding errors encountered or an error for unsupported content types.
//
// Example Usage:
//
//        // This function is automatically executed internally when binding request data to a struct.
func extractParamsBind(c *Ctx, v interface{}) error {
        contentType := strings.ToLower(c.Request.Header.Get("Content-Type"))

        // Check supported Content-Type
        if !strings.HasPrefix(contentType, ContentTypeAppJSON) &&
                !strings.HasPrefix(contentType, ContentTypeAppXML) &&
                !strings.HasPrefix(contentType, ContentTypeTextXML) {
                return fmt.Errorf("unsupported content type: %s", contentType)
        }

        switch {
        case strings.HasPrefix(contentType, ContentTypeAppJSON):

                // Acquire pooled buffer
                buf := acquireJSONBuffer()
                defer releaseJSONBuffer(buf)

                // Read body content into buffer
                if _, err := buf.ReadFrom(c.Request.Body); err != nil {
                        return err
                }

                // Reset the Request.Body after reading, enabling re-reads if needed
                c.Request.Body = io.NopCloser(bytes.NewReader(buf.Bytes()))

                return json.Unmarshal(buf.Bytes(), v)
        case strings.HasPrefix(contentType, ContentTypeAppXML), strings.HasPrefix(contentType, ContentTypeTextXML):

                // Acquire pooled buffer
                buf := acquireXMLBuffer()
                defer releaseXMLBuffer(buf)

                // Read body content into buffer
                if _, err := buf.ReadFrom(c.Request.Body); err != nil {
                        return err
                }

                // Reset the Request.Body after reading, enabling re-reads if needed
                c.Request.Body = io.NopCloser(bytes.NewReader(buf.Bytes()))

                return xml.Unmarshal(buf.Bytes(), v)
        default:
                return fmt.Errorf("unsupported content type: %s", contentType)
        }
}

// extractParamsPattern extracts the fixed path and dynamic parameters from a given route pattern.
//
// This function is responsible for identifying and separating static paths from dynamic parameters
// in a route pattern. It ensures proper extraction of URL path segments and dynamic query parameters.
//
// Parameters:
//   - pattern string: The route pattern that may contain dynamic parameters.
//
// Returns:
//   - path string: The fixed portion of the route without dynamic parameters.
//   - params string: The extracted dynamic parameters (if any).
//   - patternExist string: The original pattern before extraction.
//
// Example Usage:
//
//        // This function is automatically executed internally when registering a dynamic route.
//        path, params, patternExist := extractParamsPattern("/users/:id")
func extractParamsPattern(pattern string) (path, params, partternExist string) {
        path = pattern
        index := strings.Index(pattern, ":")

        if index > 0 {
                path = pattern[:index]
                path = strings.TrimSuffix(path, "/")
                if index == 1 {
                        path = "/"
                }
                params = strings.TrimPrefix(pattern, path)
                partternExist = pattern
        }

        return
}

// extractParamsGet processes an HTTP GET request for a dynamic route,
// extracting query parameters, headers, and handling the request using
// the provided handler function.
//
// This function ensures efficient processing by leveraging a pooled
// Ctx instance, which minimizes memory allocations and reduces garbage
// collection overhead.
//
// The request context (`myContextKey`) is retrieved to extract dynamic
// parameters mapped to the route.
//
// Parameters:
//   - q: The Quick instance that provides configurations and routing context.
//   - pathTmp: The template path used for dynamic route matching.
//   - paramsPath: The actual path used to extract route parameters.
//   - handlerFunc: The function that processes the HTTP request.
//
// Returns:
//   - http.HandlerFunc: A function that processes the request efficiently.
func extractParamsGet(q *Quick, pathTmp, paramsPath string, handlerFunc HandleFunc) http.HandlerFunc {
        return func(w http.ResponseWriter, req *http.Request) {
                // Acquire a context from the pool
                ctx := acquireCtx()
                defer releaseCtx(ctx)

                // Retrieve the custom context from the request (myContextKey)
                v := req.Context().Value(myContextKey)
                if v == nil {
                        http.NotFound(w, req)
                        return
                }

                cval := v.(ctxServeHttp)

                // Fill the pooled context with request-specific data
                ctx.Response = w
                ctx.Request = req
                ctx.Params = cval.ParamsMap

                // Initialize Query and Headers maps properly
                ctx.Query = make(map[string]string)
                for key, val := range req.URL.Query() {
                        ctx.Query[key] = val[0]
                }

                ctx.Headers = extractHeaders(*req)
                ctx.MoreRequests = q.config.MoreRequests

                // Execute the handler function using the pooled context
                execHandleFunc(ctx, handlerFunc)
        }
}

// extractParamsPost processes an HTTP POST request, extracting the request body
// and headers and handling the request using the provided handler function.
//
// This function ensures that the request body is within the allowed size limit,
// extracts headers, and reuses a pooled Ctx instance to optimize memory usage.
//
// Parameters:
//   - q: The Quick instance that provides configurations and routing context.
//   - handlerFunc: The function that processes the HTTP request.
//
// Returns:
//   - http.HandlerFunc: A handler function that processes the request efficiently.
func extractParamsPost(q *Quick, handlerFunc HandleFunc) http.HandlerFunc {
        return func(w http.ResponseWriter, req *http.Request) {
                // Validate body size before processing
                // req.Body = http.MaxBytesReader(w, req.Body, q.config.MaxBodySize)
                if req.ContentLength > q.config.MaxBodySize {
                        http.Error(w, "Request body too large", StatusRequestEntityTooLarge)
                        return
                }

                // Acquire a pooled context for request processing
                ctx := acquireCtx()
                defer releaseCtx(ctx) // Ensure the context is returned to the pool after execution

                // Retrieve the custom context from the request
                v := req.Context().Value(myContextKey)
                if v == nil {
                        http.NotFound(w, req) // Return 404 if no context value is found
                        return
                }

                // Extract headers into the pooled Ctx
                ctx.Headers = extractHeaders(*req)

                // Read the request body while minimizing allocations
                bodyBytes, bodyReader := extractBodyBytes(req.Body)

                // Populate the Ctx with relevant data
                ctx.Response = w
                ctx.Request = req
                ctx.bodyByte = bodyBytes
                ctx.MoreRequests = q.config.MoreRequests

                // Reset `Request.Body` with the new bodyReader to allow re-reading
                ctx.Request.Body = bodyReader

                // Execute the handler function using the pooled context
                execHandleFunc(ctx, handlerFunc)
        }
}

// extractParamsPut processes an HTTP PUT request, extracting the request body,
// headers, and route parameters while efficiently reusing a pooled Ctx instance.
//
// This function ensures that the request body does not exceed the configured
// size limit, extracts headers, and minimizes memory allocations by leveraging
// a preallocated Ctx from the sync.Pool.
//
// Parameters:
//   - q: The Quick instance that provides configurations and routing context.
//   - handlerFunc: The function that processes the HTTP request.
//
// Returns:
//   - http.HandlerFunc: A function that processes the request efficiently.
func extractParamsPut(q *Quick, handlerFunc HandleFunc) http.HandlerFunc {
        return func(w http.ResponseWriter, req *http.Request) {
                // Validate body size before processing
                if req.ContentLength > q.config.MaxBodySize {
                        http.Error(w, "Request body too large", StatusRequestEntityTooLarge)
                        return
                }

                // Acquire a pooled context for request processing
                ctx := acquireCtx()
                defer releaseCtx(ctx) // Ensure the context is returned to the pool after execution

                // Retrieve the custom context from the request
                v := req.Context().Value(myContextKey)
                if v == nil {
                        http.NotFound(w, req) // Return 404 if no context value is found
                        return
                }

                cval := v.(ctxServeHttp)

                // Extract headers into the pooled Ctx
                ctx.Headers = extractHeaders(*req)

                // Read the request body while minimizing allocations
                bodyBytes, bodyReader := extractBodyBytes(req.Body)

                // Populate the Ctx with relevant data
                ctx.Response = w
                ctx.Request = req
                ctx.bodyByte = bodyBytes
                ctx.Params = cval.ParamsMap
                ctx.MoreRequests = q.config.MoreRequests

                // Reset `Request.Body` with the new bodyReader to allow re-reading
                ctx.Request.Body = bodyReader

                // Execute the handler function using the pooled context
                execHandleFunc(ctx, handlerFunc)
        }
}

// extractParamsDelete processes an HTTP DELETE request, extracting request parameters
// and headers before executing the provided handler function.
//
// This function optimizes memory usage by reusing a pooled Ctx instance,
// reducing unnecessary allocations and garbage collection overhead.
//
// Parameters:
//   - q: The Quick instance that provides configurations and routing context.
//   - handlerFunc: The function that processes the HTTP request.
//
// Returns:
//   - http.HandlerFunc: A function that processes the request efficiently.
func extractParamsDelete(q *Quick, handlerFunc HandleFunc) http.HandlerFunc {
        return func(w http.ResponseWriter, req *http.Request) {
                // Acquire a pooled context for request processing
                ctx := acquireCtx()
                defer releaseCtx(ctx) // Ensure the context is returned to the pool after execution

                // Retrieve the custom context from the request
                v := req.Context().Value(myContextKey)
                if v == nil {
                        http.NotFound(w, req) // Return 404 if no context value is found
                        return
                }

                cval := v.(ctxServeHttp)

                // Extract headers into the pooled Ctx
                ctx.Headers = extractHeaders(*req)

                // Populate the Ctx with relevant data
                ctx.Response = w
                ctx.Request = req
                ctx.Params = cval.ParamsMap
                ctx.MoreRequests = q.config.MoreRequests

                // Execute the handler function using the pooled context
                execHandleFunc(ctx, handlerFunc)
        }
}

// execHandleFunc executes the provided handler function and handles errors if they occur.
//
// This function ensures that the HTTP response is properly handled, including setting the
// appropriate content type and returning an error message if the handler function fails.
//
// Parameters:
//   - c *Ctx: The Quick context instance containing request and response data.
//   - handleFunc HandleFunc: The function that processes the HTTP request.
//
// Example Usage:
//
//        // This function is automatically executed internally after processing a request.
func execHandleFunc(c *Ctx, handleFunc HandleFunc) {
        err := handleFunc(c)
        if err != nil {
                c.Set("Content-Type", "text/plain; charset=utf-8")
                // #nosec G104
                c.Status(500).SendString(err.Error())
        }
}

// extractBodyBytes reads the entire request body into a pooled buffer, then
// copies the data to a new byte slice before returning it. This ensures that
// once the buffer is returned to the pool, the returned data remains valid.
//
// Additionally, this function returns a new `io.ReadCloser` wrapping the same data,
// allowing it to be re-read if needed.
//
// Parameters:
//   - r io.ReadCloser: The original request body stream.
//
// Returns:
//   - []byte: A byte slice containing the full request body data.
//   - io.ReadCloser: A new ReadCloser that allows the body to be re-read.
//
// Example Usage:
//
//        // Read the request body into a byte slice and obtain a new ReadCloser.
func extractBodyBytes(r io.ReadCloser) ([]byte, io.ReadCloser) {
        // Acquire a reusable buffer from the pool
        buf := acquireBuffer()
        defer releaseBuffer(buf)

        // Read all data from the request body into the buffer
        _, err := buf.ReadFrom(r)
        if err != nil {
                // If there's an error, return an empty NopCloser
                // so downstream logic can handle gracefully.
                return nil, io.NopCloser(bytes.NewBuffer(nil))
        }

        // Copy the data from the buffer into a separate byte slice.
        // This step is crucial because once the buffer is released
        // back to the pool, its underlying memory can be reused.
        data := make([]byte, buf.Len())
        copy(data, buf.Bytes())

        // Return both the raw byte slice and a new ReadCloser
        // wrapping the same data, which allows for re-reading.
        return data, io.NopCloser(bytes.NewReader(data))
}

// mwWrapper applies all registered middlewares to an HTTP handler.
//
// This function iterates through the registered middleware stack in reverse order
// (last added middleware is executed first) and wraps the final HTTP handler
// with each middleware layer.
//
// Parameters:
//   - handler http.Handler: The final HTTP handler to be wrapped with middlewares.
//
// Returns:
//   - http.Handler: The HTTP handler wrapped with all registered middlewares.
//
// Example Usage:
//
//        // This function is automatically executed internally before processing requests.
//
// mwWrapper applies all registered middlewares to an HTTP handler.
//
// This function iterates through the middleware stack in reverse order
// (last added middleware is executed first) and wraps the final HTTP handler
// with each middleware layer.
//
// It supports multiple middleware function signatures:
//   - `func(http.Handler) http.Handler`: Standard net/http middleware.
//   - `func(http.ResponseWriter, *http.Request, http.Handler)`: Middleware that
//     directly manipulates the response and request.
//   - `func(HandlerFunc) HandlerFunc`: Quick-specific middleware format.
//   - `func(Handler) Handler`: Another Quick middleware format.
//
// Parameters:
//   - handler http.Handler: The final HTTP handler to be wrapped.
//
// Returns:
//   - http.Handler: The HTTP handler wrapped with all registered middlewares.
func (q *Quick) mwWrapper(handler http.Handler) http.Handler {
        for i := len(q.mws2) - 1; i >= 0; i-- {
                switch mw := q.mws2[i].(type) {

                case func(http.Handler) http.Handler:
                        // Apply standard net/http middleware
                        handler = mw(handler)

                case func(http.ResponseWriter, *http.Request, http.Handler):
                        // Apply middleware that takes ResponseWriter, Request, and the next handler
                        originalHandler := handler // Avoid infinite reassignment
                        handler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
                                mw(w, r, originalHandler)
                        })

                case func(HandlerFunc) HandlerFunc:
                        // Convert net/http.Handler to Quick.HandlerFunc
                        quickHandler := convertToQuickHandler(handler)
                        // Apply Quick middleware
                        quickHandler = mw(quickHandler)

                        // Convert back to http.Handler
                        handler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
                                c := &Ctx{
                                        Response: w,
                                        Request:  r,
                                        App:      q,
                                }
                                quickHandler(c)
                        })

                case func(Handler) Handler:
                        // Convert net/http.Handler to Quick.Handler
                        qh := convertHttpToQuickHandler(handler)
                        // Apply Quick middleware
                        qh = mw(qh)
                        // Convert back to http.Handler
                        handler = convertQuickToHttpHandler(qh)
                }
        }
        return handler
}

// convertHttpToQuickHandler adapts a net/http.Handler to a Quick.Handler.
//
// This function allows standard HTTP handlers to be wrapped within Quick's middleware
// system by transforming them into the Quick.Handler interface.
//
// Parameters:
//   - h http.Handler: The standard HTTP handler to convert.
//
// Returns:
//   - Handler: The Quick-compatible handler.
func convertHttpToQuickHandler(h http.Handler) Handler {
        return HandlerFunc(func(c *Ctx) error {
                h.ServeHTTP(c.Response, c.Request)
                return nil
        })
}

// convertQuickToHttpHandler adapts a Quick.Handler to a net/http.Handler.
//
// This function wraps Quick handlers into a standard HTTP handler so they can
// be used within net/http's ecosystem.
//
// Parameters:
//   - h Handler: The Quick handler to convert.
//
// Returns:
//   - http.Handler: The net/http-compatible handler.
func convertQuickToHttpHandler(h Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
                c := &Ctx{Response: w, Request: r}
                if err := h.ServeQuick(c); err != nil {
                        http.Error(w, err.Error(), http.StatusInternalServerError)
                }
        })
}

// convertToQuickHandler adapts a net/http.Handler to a Quick.HandlerFunc.
//
// This function allows standard HTTP handlers to be used within Quick's middleware
// system by transforming them into Quick.HandlerFunc.
//
// Parameters:
//   - h http.Handler: The standard HTTP handler to convert.
//
// Returns:
//   - HandlerFunc: The Quick-compatible handler function.
func convertToQuickHandler(h http.Handler) HandlerFunc {
        return func(c *Ctx) error {
                h.ServeHTTP(c.Response, c.Request)
                return nil
        }
}

// func convertToQuickMiddleware(mw func(http.Handler) http.Handler) func(Handler) Handler {
//         return func(next Handler) Handler {
//                 return HandlerFunc(func(c *Ctx) error {
//                         adaptedHandler := mw(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
//                                 c.Response = w
//                                 c.Request = r
//                                 next(c)
//                         }))

//                         adaptedHandler.ServeHTTP(c.Response, c.Request)
//                         return nil
//                 })
//         }
// }

// appendRoute registers a new route in the Quick router and applies middlewares.
//
// This function ensures that the given route's handler is wrapped with all registered
// middlewares before being stored in the router. It optimizes performance by applying
// middleware only once during route registration instead of at runtime.
//
// Parameters:
//   - route *Route: The route to be registered in the Quick router.
//
// Example Usage:
//
//        // This function is automatically called when registering a new route.
func (q *Quick) appendRoute(route *Route) {
        route.handler = q.mwWrapper(route.handler).ServeHTTP
        //q.routes = append(q.routes, *route)
        q.routes = append(q.routes, route)
}

// Header retrieves the HTTP headers from the response writer.
//
// This method allows middleware or handlers to modify response headers
// before sending them to the client.
//
// Returns:
//   - http.Header: The set of response headers.
//
// Example Usage:
//
//        // Retrieve headers within a middleware or handler function
func (rw *pooledResponseWriter) Header() http.Header {
        return rw.ResponseWriter.Header()
}

// ServeHTTP processes incoming HTTP requests and matches them to registered routes.
//
// This function efficiently routes HTTP requests to the appropriate handler while
// leveraging a **pooled response writer** and **context pooling** to minimize memory
// allocations and improve performance.
//
// If the request method is `OPTIONS`, it is handled separately via `handleOptions`.
// If no matching route is found, the function responds with `404 Not Found`.
//
// Example Usage:
// This function is automatically invoked by the `http.Server` when a request reaches
// the Quick router.
func (q *Quick) ServeHTTP(w http.ResponseWriter, req *http.Request) {
        // call options
        if req.Method == http.MethodOptions {
                q.handleOptions(w, req)
                return
        }

        // Acquire a ResponseWriter from the pool for efficient request handling.
        rw := acquireResponseWriter(w)
        defer releaseResponseWriter(rw) // Ensure it returns to the pool.

        // Acquiring Ctx from the pool
        ctx := newCtx(rw, req) // <- creates a new, clean instance of the context
        defer releaseCtx(ctx)  // Returns it to the pool

        for i := range q.routes {
                var requestURI = req.URL.Path
                var patternUri = q.routes[i].Pattern

                if q.routes[i].Method != req.Method {
                        continue
                }

                if len(patternUri) == 0 {
                        patternUri = q.routes[i].Path
                }

                paramsMap, isValid := createParamsAndValid(requestURI, patternUri)

                if !isValid {
                        continue // This route doesn't match, continue checking.
                }

                var c = ctxServeHttp{
                        Path:      requestURI,
                        ParamsMap: paramsMap,
                        Method:    q.routes[i].Method,
                }
                req = req.WithContext(context.WithValue(req.Context(), myContextKey, c))

                // Pass the rw (pooledResponseWriter) to the handler
                q.routes[i].handler(rw, req)
                return
        }

        // If no route matches, send a 404 response.
        http.NotFound(rw, req)
}

// createParamsAndValid extracts dynamic parameters from a request URI and validates the pattern.
//
// This function compares the request URI with the registered pattern and extracts
// route parameters such as `:id` or `{id:[0-9]+}` dynamically.
//
// Example Usage:
// This function is internally used by `ServeHTTP()` to verify if a request matches a
// registered route pattern. If it does, it extracts the dynamic parameters and returns
// them as a map.
func createParamsAndValid(reqURI, patternURI string) (map[string]string, bool) {
        params := make(map[string]string)
        var builder strings.Builder

        reqURI = strings.TrimPrefix(reqURI, "/")
        patternURI = strings.TrimPrefix(patternURI, "/")

        reqSplit := strings.Split(reqURI, "/")
        patternSplit := strings.Split(patternURI, "/")
        if len(reqSplit) != len(patternSplit) {
                return nil, false
        }

        for i, seg := range patternSplit {
                reqSeg := reqSplit[i]

                switch {
                // Ex: :id => paramName = "id"
                case strings.HasPrefix(seg, ":"):
                        paramName := seg[1:]
                        if paramName == "" {
                                return nil, false
                        }
                        params[paramName] = reqSeg
                        builder.WriteString("/")
                        builder.WriteString(reqSeg)

                // Ex: {id:[0-9]+}
                case strings.HasPrefix(seg, "{") && strings.HasSuffix(seg, "}"):
                        content := seg[1 : len(seg)-1]
                        parts := strings.SplitN(content, ":", 2)
                        // Check for name and regex
                        if len(parts) != 2 || parts[0] == "" {
                                return nil, false
                        }
                        paramName, regexPattern := parts[0], parts[1]

                        rgx, err := regexp.Compile("^" + regexPattern + "$")
                        if err != nil || !rgx.MatchString(reqSeg) {
                                return nil, false
                        }
                        params[paramName] = reqSeg
                        builder.WriteString("/")
                        builder.WriteString(reqSeg)

                default:
                        if seg != reqSeg {
                                return nil, false
                        }
                        builder.WriteString("/")
                        builder.WriteString(seg)
                }
        }

        //if "/"+reqURI != builder.String() {
        //        return nil, false
        //}

        return params, true
}

// GetRoute retrieves all registered routes in the Quick framework.
//
// This function returns a slice containing all the routes that have been
// registered in the Quick instance. It is useful for debugging, logging,
// or dynamically inspecting available routes.
//
// Example Usage:
//
//        routes := q.GetRoute()
//        for _, route := range routes {
//            fmt.Println("Method:", route.Method, "Path:", route.Path)
//        }
//
// Returns:
//   - []*Route: A slice of pointers to the registered Route instances.
func (q *Quick) GetRoute() []*Route {
        return q.routes
}

// Static serves static files (HTML, CSS, JS, images, etc.) from a directory or embedded filesystem.
//
// This function allows you to register a static file server in the Quick framework, either using
// a local directory (`string`) or an embedded filesystem (`embed.FS`). By embedding files,
// they become part of the binary at compile time, eliminating the need for external file access.
//
// Example Usage:
// This function is useful for serving front-end assets or static resources directly from
// the Go application. It supports both local directories and embedded files.
//
// Parameters:
//   - route: The base path where static files will be served (e.g., "/static").
//   - dirOrFS: The source of the static files. It accepts either:
//   - `string`: A local directory path (e.g., `"./static"`).
//   - `embed.FS`: An embedded file system for compiled-in assets.
//
// Returns:
//   - None (void function).
//
// Notes:
//   - The function automatically trims trailing slashes from `route`.
//   - If an invalid parameter is provided, the function panics.
//   - When using an embedded filesystem, files are served directly from memory.
func (q *Quick) Static(route string, dirOrFS any) {
        route = strings.TrimSuffix(route, "/")

        var fileServer http.Handler

        // check of dirOrFS is a embed.FS
        switch v := dirOrFS.(type) {
        case string:
                fileServer = http.FileServer(http.Dir(v))
        case embed.FS:
                q.embedFS = v
                fileServer = http.FileServer(http.FS(v))
        default:
                panic("Static: invalid parameter, must be string or embed.FS")
        }

        q.mux.Handle(concat.String(route, "/"), http.StripPrefix(route, fileServer))
}

// execHandler wraps an HTTP handler with additional processing.
//
// This function ensures that the provided `http.Handler` is executed properly,
// allowing for additional middleware wrapping or request pre-processing.
//
// Example Usage:
// This function is automatically applied within Quick's internal request processing pipeline.
//
// Parameters:
//   - next: The next HTTP handler to be executed.
//
// Returns:
//   - http.Handler: A wrapped HTTP handler that ensures correct execution.
func (q *Quick) execHandler(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
                next.ServeHTTP(w, r)
        })
}

// corsHandler applies the configured CORS middleware to the Quick router.
//
// This function checks if CORS is enabled in the Quick instance (`q.Cors`).
// If enabled, it wraps the request processing with the configured CORS middleware.
//
// Example Usage:
// Automatically used when CORS support is detected within `Use()`.
//
// Returns:
//   - http.Handler: The HTTP handler wrapped with CORS processing.
func (q *Quick) corsHandler() http.Handler {
        return q.CorsSet(q)
}

// httpServerTLS initializes and returns an HTTP server instance configured for TLS/HTTPS.
//
// This function sets up a secure server with `TLSConfig` and allows optional
// custom handlers to be provided. If no custom handler is specified, the default
// Quick router is used.
//
// Example Usage:
// Used internally by Quick when setting up an HTTPS server via `ListenTLS()`.
//
// Parameters:
//   - addr:      The network address the server should listen on (e.g., ":443").
//   - tlsConfig: A `*tls.Config` instance containing certificate and security settings.
//   - handler:   (Optional) One or more custom HTTP handlers.
//
// Returns:
//   - *http.Server: A configured HTTPS server instance.
func (q *Quick) httpServerTLS(addr string, tlsConfig *tls.Config, handler ...http.Handler) *http.Server {
        var h http.Handler = q
        if len(handler) > 0 {
                h = q.execHandler(handler[0])
        } else if q.Cors {
                h = q.corsHandler()
        }

        // Return a fully configured http.Server, including TLS settings.
        return &http.Server{
                Addr:              addr,
                Handler:           h,
                TLSConfig:         tlsConfig,
                ReadTimeout:       q.config.ReadTimeout,
                WriteTimeout:      q.config.WriteTimeout,
                IdleTimeout:       q.config.IdleTimeout,
                ReadHeaderTimeout: q.config.ReadHeaderTimeout,
                MaxHeaderBytes:    q.config.MaxHeaderBytes,
        }
}

// httpServer initializes and returns an HTTP server instance configured for plain HTTP.
//
// This function sets up a standard HTTP server, allowing optional custom handlers
// to be specified. If no handler is provided, the default Quick router is used.
//
// Example Usage:
// Used internally when starting an HTTP server via `Listen()`.
//
// Parameters:
//   - addr:    The network address the server should listen on (e.g., ":8080").
//   - handler: (Optional) One or more custom HTTP handlers.
//
// Returns:
//   - *http.Server: A configured HTTP server instance.
func (q *Quick) httpServer(addr string, handler ...http.Handler) *http.Server {
        // Determine the handler to use based on optional arguments and CORS configuration.
        var h http.Handler = q
        if len(handler) > 0 {
                h = q.execHandler(handler[0])
        } else if q.Cors {
                h = q.corsHandler()
        }

        // Return a fully configured http.Server for plain HTTP usage.
        return &http.Server{
                Addr:              addr,
                Handler:           h,
                ReadTimeout:       q.config.ReadTimeout,
                WriteTimeout:      q.config.WriteTimeout,
                IdleTimeout:       q.config.IdleTimeout,
                ReadHeaderTimeout: q.config.ReadHeaderTimeout,
                MaxHeaderBytes:    q.config.MaxHeaderBytes,
        }
}

// ListenWithShutdown starts an HTTP server and returns both the server instance and a shutdown function.
//
// This method initializes performance tuning settings, creates a TCP listener, and starts the server in a background goroutine.
// The returned shutdown function allows for a graceful termination of the server.
//
// Parameters:
//   - addr: The address (host:port) where the server should listen.
//   - handler: Optional HTTP handlers that can be provided to the server.
//
// Returns:
//   - *http.Server: A reference to the initialized HTTP server.
//   - func(): A shutdown function to gracefully stop the server.
//   - error: Any error encountered during the server setup.
func (q *Quick) ListenWithShutdown(addr string, handler ...http.Handler) (*http.Server, func(), error) {
        q.setupPerformanceTuning()

        listener, err := net.Listen("tcp", addr)
        if err != nil {
                return nil, nil, err
        }

        server := q.httpServer(listener.Addr().String(), handler...)
        q.server = server

        // Shutdown function to gracefully terminate the server.
        shutdownFunc := func() {
                ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
                defer cancel()
                server.Shutdown(ctx)
                listener.Close()
        }

        // Start the server in a background goroutine.
        go func() {
                server.Serve(listener)
        }()

        return server, shutdownFunc, nil
}

// setupPerformanceTuning configures performance settings for the Quick server.
//
// This method optimizes performance by:
//   - Dynamically tuning garbage collection behavior if `MoreRequests` is configured.
//   - Adjusting the `GOMAXPROCS` value based on the configuration.
//   - Initializing a buffer pool to optimize memory allocation.
//
// Example Usage:
// Called automatically when initializing the Quick server.
func (q *Quick) setupPerformanceTuning() {
        if q.config.MoreRequests > 0 {
                go q.adaptiveGCTuner()
        }

        if q.config.GOMAXPROCS > 0 {
                runtime.GOMAXPROCS(q.config.GOMAXPROCS)
        }

        q.bufferPool = &sync.Pool{
                New: func() interface{} {
                        return bytes.NewBuffer(make([]byte, 0, q.config.BufferPoolSize))
                },
        }
}

// adaptiveGCTuner periodically monitors memory usage and triggers garbage collection if necessary.
//
// This function runs in a background goroutine and:
//   - Checks heap memory usage every 15 seconds.
//   - If the heap usage exceeds a defined threshold, it triggers garbage collection and frees OS memory.
//
// Example Usage:
// Automatically invoked by `setupPerformanceTuning()` when `MoreRequests` is enabled.
func (q *Quick) adaptiveGCTuner() {
        var threshold uint64 = uint64(q.config.GCHeapThreshold)
        if threshold == 0 {
                threshold = 1 << 30 // Default threshold: 1GB
        }

        ticker := time.NewTicker(15 * time.Second)
        defer ticker.Stop()

        var m runtime.MemStats
        for range ticker.C {
                runtime.ReadMemStats(&m)

                if m.HeapInuse > threshold {
                        debug.FreeOSMemory()
                        runtime.GC()
                }
        }
}

// Listen starts the Quick server and blocks indefinitely.
//
// This function initializes the HTTP server and prevents the application from exiting.
//
// Example Usage:
//
//        q.Listen(":8080")
//
// Parameters:
//   - addr: The address on which the server should listen (e.g., ":8080").
//   - handler: (Optional) Custom HTTP handlers.
//
// Returns:
//   - error: Any errors encountered while starting the server.
func (q *Quick) Listen(addr string, handler ...http.Handler) error {
        _, shutdown, err := q.ListenWithShutdown(addr, handler...)
        if err != nil {
                return err
        }
        defer shutdown()

        q.Display("http", addr)
        // Locks indefinitely
        <-make(chan struct{}) // Bloqueio sem consumo de CPU
        return nil
}

// Shutdown gracefully shuts down the Quick server without interrupting active connections.
//
// This function ensures that all ongoing requests are completed before shutting down,
// preventing abrupt connection termination.
//
// Example Usage:
//
//                q := quick.New()
//
//            q.Get("/", func(c *quick.Ctx) error {
//                return c.SendString("Server is running!")
//            })
//
//                q.Shutdown()
//
// Returns:
//   - error: Any errors encountered during shutdown.
func (q *Quick) Shutdown() error {
        // Create a context with a timeout to control the shutdown process
        ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
        defer cancel() // Ensure the context is cancelled to free resources

        // Check if the server is initialized before attempting to shut it down
        if q.server != nil {
                q.server.SetKeepAlivesEnabled(false)
                err := q.server.Shutdown(ctx)
                q.releaseResources()
                return err // Attempt to shutdown the server gracefully
        }
        return nil // Return nil if there is no server to shutdown
}

// releaseResources resets system-level performance settings after server shutdown.
//
// This function ensures that system configurations return to their default states
// after the Quick server is gracefully shut down, preventing excessive resource usage.
//
// Example Usage:
//
//        q.releaseResources()
//
// Actions Performed:
//   - Resets the garbage collection behavior to the default percentage (100).
//   - Restores `GOMAXPROCS` to automatic CPU thread allocation.
func (q *Quick) releaseResources() {
        // System settings reset
        debug.SetGCPercent(100) // Return to default GC
        runtime.GOMAXPROCS(0)   // Reset to automatic thread configuration
}

// ListenTLS starts an HTTPS server on the specified address using the provided
// certificate and key files. It allows enabling or disabling HTTP/2 support.
// It also configures basic modern TLS settings, sets up a listener with
// SO_REUSEPORT (when possible), and applies a graceful shutdown procedure.
//
// Parameters:
//   - addr: the TCP network address to listen on (e.g., ":443")
//   - certFile: the path to the SSL certificate file
//   - keyFile: the path to the SSL private key file
//   - useHTTP2: whether or not to enable HTTP/2
//   - handler: optional HTTP handlers. If none is provided, the default handler is used.
//
// Returns:
//   - error: an error if something goes wrong creating the listener or starting the server.
func (q *Quick) ListenTLS(addr, certFile, keyFile string, useHTTP2 bool, handler ...http.Handler) error {
        // If the user has specified a custom GC percentage (> 0),
        // set it here to help control garbage collection aggressiveness.
        if q.config.GCPercent > 0 {
                debug.SetGCPercent(q.config.GCPercent)
        }

        // Extract or create a TLS configuration.
        // If q.config.TLSConfig is nil, set up a default TLS config with modern protocols
        // and ciphers. This includes TLS 1.3 and secure cipher suites.
        var tlsConfig = q.config.TLSConfig
        if tlsConfig == nil {
                tlsConfig = &tls.Config{
                        MinVersion:       tls.VersionTLS13, // Sets TLS 1.3 as the minimum version
                        CurvePreferences: []tls.CurveID{tls.X25519, tls.CurveP256},
                        CipherSuites: []uint16{
                                tls.TLS_AES_128_GCM_SHA256,
                                tls.TLS_AES_256_GCM_SHA384,
                                tls.TLS_CHACHA20_POLY1305_SHA256,
                        },
                        PreferServerCipherSuites: true,                              // Prioritize server ciphers
                        SessionTicketsDisabled:   false,                             // Enable Session Resumption (minus TLS Handshakes)
                        ClientSessionCache:       tls.NewLRUClientSessionCache(128), // Cache TLS sessions for reuse
                }
        }

        // Enable or disable HTTP/2 support based on the useHTTP2 parameter.
        if useHTTP2 {
                // HTTP/2 + HTTP/1.1
                tlsConfig.NextProtos = []string{"h2", "http/1.1"}
        } else {
                // Only HTTP/1.1
                tlsConfig.NextProtos = []string{"http/1.1"}
        }

        // Create a net.ListenConfig that attempts to set SO_REUSEPORT on supported platforms.
        // This feature can improve load balancing by letting multiple processes
        // bind to the same address.
        cfg := &net.ListenConfig{
                Control: func(network, address string, c syscall.RawConn) error {
                        return c.Control(func(fd uintptr) {
                                // Avoid setting SO_REUSEPORT on macOS to prevent errors.
                                if runtime.GOOS != "darwin" {
                                        if runtime.GOOS == "linux" {
                                                if err := syscall.SetsockoptInt(int(fd), syscall.SOL_SOCKET, SO_REUSEPORT, 1); err != nil {
                                                        log.Fatalf("Erro ao definir SO_REUSEPORT: %v", err)
                                                }
                                        }
                                        // } else {
                                        //         if err := syscall.SetsockoptInt(int(fd), syscall.SOL_SOCKET, syscall.SO_REUSEPORT, 1); err != nil {
                                        //                 log.Fatalf("Erro ao definir SO_REUSEPORT: %v", err)
                                        //         }
                                        // }
                                }
                        })
                },
        }

        // Listen on the specified TCP address using our custom ListenConfig.
        listener, err := cfg.Listen(context.Background(), "tcp", addr)
        if err != nil {
                return fmt.Errorf("failed to create listener: %w", err)
        }

        // Create the HTTP server configured for TLS using the provided or default tlsConfig.
        // The address is taken from the listener to ensure correctness in case the actual
        // bound port differs (for example, if you used ":0" for a random port).
        q.server = q.httpServerTLS(listener.Addr().String(), tlsConfig, handler...)

        // Start the server and perform a graceful shutdown when a termination signal is received.
        return q.startServerWithGracefulShutdown(listener, certFile, keyFile)
}

// startServerWithGracefulShutdown starts the HTTPS server (using the provided TLS certificate
// and private key) on the given listener and blocks until the server either encounters
// an unrecoverable error or receives a termination signal.
//
// The server runs in a goroutine so that this function can simultaneously listen for
// interrupt signals (SIGINT, SIGTERM, SIGHUP). Once such a signal is detected, the function
// will gracefully shut down the server, allowing any ongoing requests to finish or timing
// out after 15 seconds.
//
// Parameters:
//   - listener: A net.Listener that the server will use to accept connections.
//   - certFile: Path to the TLS certificate file.
//   - keyFile:  Path to the TLS private key file.
//
// Returns:
//   - error: An error if the server fails to start, or if a forced shutdown occurs.
//     Returns nil on normal shutdown.
func (q *Quick) startServerWithGracefulShutdown(listener net.Listener, certFile, keyFile string) error {

        serverErr := make(chan error, 1)

        // Run ServeTLS in a goroutine. Any unrecoverable error that isn't http.ErrServerClosed
        // is sent to the channel for handling in the main select block.
        go func() {
                if err := q.server.ServeTLS(listener, certFile, keyFile); err != nil && err != http.ErrServerClosed {
                        serverErr <- fmt.Errorf("server error: %w", err)
                }
                close(serverErr)
        }()

        // Create a context that listens for SIGINT, SIGTERM, and SIGHUP signals.
        // When one of these signals occurs, the context is canceled automatically.
        ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM, syscall.SIGHUP)
        defer stop()

        select {
        case <-ctx.Done():
                // We've received a termination signal, so attempt a graceful shutdown.
                log.Println("Received shutdown signal. Stopping server...")
                shutdownCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
                defer cancel()

                // If the server cannot gracefully shut down within 15 seconds,
                // it will exit with an error.
                if err := q.server.Shutdown(shutdownCtx); err != nil {
                        return fmt.Errorf("forced shutdown: %w", err)
                }
                return nil

        case err := <-serverErr:
                // If an unrecoverable error occurred in ServeTLS, return it here.
                return err
        }
}

jeffotoni / quick / 260

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous