okapi.go

/*
 *  MIT License
 *
 * Copyright (c) 2025 Jonas Kaninda
 *
 *  Permission is hereby granted, free of charge, to any person obtaining a copy
 *  of this software and associated documentation files (the "Software"), to deal
 *  in the Software without restriction, including without limitation the rights
 *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 *  copies of the Software, and to permit persons to whom the Software is
 *  furnished to do so, subject to the following conditions:
 *
 *  The above copyright notice and this permission notice shall be included in all
 *  copies or substantial portions of the Software.
 *
 *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 *  SOFTWARE.
 */

package okapi

import (
	"bufio"
	"context"
	"crypto/tls"
	"errors"
	"fmt"
	"io"
	"log"
	"log/slog"
	"net"
	"net/http"
	"os"
	"strconv"
	"strings"
	"time"

	"github.com/getkin/kin-openapi/openapi3"
	"github.com/gorilla/mux"
	goutils "github.com/jkaninda/go-utils"
)

var (
	defaultWriter      io.Writer = os.Stdout
	defaultErrorWriter io.Writer = os.Stderr
	defaultPort                  = 8080
	defaultAddr                  = ":8080"
)

type (
	// Okapi represents the core application structure of the framework,
	// holding configuration, routers, middleware, server settings, and documentation components.
	Okapi struct {
		context            *Context
		ctx                context.Context
		router             *Router
		middlewares        []Middleware
		server             *http.Server
		tlsServer          *http.Server
		baseCancel         context.CancelFunc
		tlsConfig          *tls.Config
		tlsServerConfig    *tls.Config
		withTlsServer      bool
		tlsAddr            string
		routes             []*Route
		debug              bool
		accessLog          bool
		strictSlash        bool
		logger             *slog.Logger
		renderer           Renderer
		corsEnabled        bool
		cors               Cors
		writeTimeout       int
		readTimeout        int
		idleTimeout        int
		optionsRegistered  map[string]bool
		openapiSpec        *openapi3.T
		openAPI            *OpenAPI
		openApiEnabled     bool
		maxMultipartMemory int64 // Maximum memory for multipart forms
		noRoute            HandlerFunc
		noMethod           HandlerFunc
		errorHandler       ErrorHandler
	}

	Router struct {
		muxRouter *mux.Router
	}
	OptionFunc func(*Okapi)

	// M is shortcut of map[string]any
	M map[string]any

	// Route defines the structure of a registered HTTP route in the framework.
	// It includes metadata used for routing, OpenAPI documentation, and middleware handling.
	Route struct {
		Name            string
		Path            string
		Method          string
		docPath         string
		chain           chain
		tags            []string
		tagInfos        []GroupTag
		operationId     string
		summary         string
		request         *openapi3.SchemaRef
		pathParams      []*openapi3.ParameterRef
		queryParams     []*openapi3.ParameterRef
		headers         []*openapi3.ParameterRef
		middlewares     []Middleware
		responseHeaders map[string]*openapi3.HeaderRef
		bearerAuth      bool
		basicAuth       bool
		security        []map[string][]string
		deprecated      bool
		requestExample  map[string]interface{}
		responses       map[int]*openapi3.SchemaRef
		description     string
		disabled        bool
		hidden          bool
		internal        bool
		handle          HandlerFunc
		cookies         []*openapi3.ParameterRef
	}

	// ResponseWriter extends http.ResponseWriter with additional utilities.
	ResponseWriter interface {
		http.ResponseWriter

		// StatusCode returns the written status code, or 0 if not written.
		StatusCode() int

		// BytesWritten returns number of bytes written to the body.
		BytesWritten() int

		// Close closes the writer if supported. Returns error instead of hiding it.
		Close() error

		// Hijack upgrades to raw TCP if supported (WebSockets, proxy, etc).
		Hijack() (net.Conn, *bufio.ReadWriter, error)

		// Flush flushes buffered data if supported (streaming, SSE, gzip, etc).
		Flush()

		// Push initiates HTTP/2 server push if supported.
		Push(string, *http.PushOptions) error
	}
	// HandlerFunc is a function type that takes a Context and returns an error.
	HandlerFunc func(*Context) error

	// Middleware is a function that processes a request before or after the next handler.
	// Call c.Next() to pass control to the next middleware or final handler.
	Middleware     = HandlerFunc
	MiddlewareFunc = HandlerFunc

	// Response implementation
	responseWriter struct {
		writer      http.ResponseWriter
		status      int
		wroteHeader bool
		wroteBytes  int
	}
)

// chain is an interface that provides access to global middlewares for building handler chains.
type chain interface {
	globalMiddlewares() []Middleware
}

// Hide marks the Route as hidden, preventing it from being listed in OpenAPI documentation.
func (r *Route) Hide() *Route {
	r.hidden = true
	return r
}

// internalRoute marks the Route as an internal route.
func (r *Route) internalRoute() *Route {
	r.internal = true
	return r
}

// Disable marks the Route as disabled, causing it to return 404 Not Found.
// Returns the Route to allow method chaining.
func (r *Route) Disable() *Route {
	r.disabled = true
	return r
}

// Enable marks the Route as enabled, allowing it to handle requests normally.
// Returns the Route to allow method chaining.
func (r *Route) Enable() *Route {
	r.disabled = false
	return r
}

// setDisabled sets the disabled state of the Route.
// When disabled is true, the route returns 404 Not Found.
// Returns the Route to allow method chaining.
func (r *Route) setDisabled(disabled bool) *Route {
	r.disabled = disabled
	return r
}

// Deprecated marks the Route as deprecated.
// Returns the Route to allow method chaining.
func (r *Route) Deprecated() *Route {
	r.deprecated = true
	return r
}

// WithSecurity sets the security requirements for the Route.
func (r *Route) WithSecurity(security ...map[string][]string) *Route {
	// Set the security requirements for the route
	if len(security) > 0 {
		r.security = security
	}
	return r
}

// WithIO sets both the input (request) and output (response) schemas
// for the route. This is a convenience method that combines WithInput
// and WithOutput in a single call.
// Both parameters are optional: pass nil if you only want one side.
//
// Example:
//
//	route.WithIO(CreateBookInput{}, BookResponse{})
func (r *Route) WithIO(req any, res any) *Route {
	if req != nil {
		r.generateRequestSchema(req)
	}
	if res != nil {
		r.generateResponseSchema(res)
	}
	return r
}

// WithInput sets the input (request) schema for the route.
// The value should be a struct or pointer to a struct with binding tags
// (query, path, header, cookie, form, body). If provided, Okapi will:
//   - Bind incoming request data to the struct
//   - Validate based on struct tags
//   - Generate OpenAPI documentation for the request schema
func (r *Route) WithInput(req any) *Route {
	if req != nil {
		r.generateRequestSchema(req)
	}
	return r
}

// WithOutput sets the output (response) schema for the route.
// The value can be any type (struct, slice, map, etc.). If provided, Okapi will:
//   - Serialize the value into the response body
//   - Generate OpenAPI documentation for the response schema
func (r *Route) WithOutput(res any) *Route {
	if res != nil {
		r.generateResponseSchema(res)
	}
	return r
}

// UseMiddleware registers one or more middleware functions to the Route.
func UseMiddleware(m ...Middleware) RouteOption {
	return func(r *Route) {
		if len(m) == 0 {
			return
		}
		r.middlewares = append(r.middlewares, m...)
	}
}

// Use registers one or more middleware functions to the Route.
func (r *Route) Use(m ...Middleware) {
	if len(m) == 0 {
		return
	}
	r.middlewares = append(r.middlewares, m...)
}

// ****** OKAPI OPTIONS ******

// WithMuxRouter sets the router for the Okapi instance
func WithMuxRouter(router *mux.Router) OptionFunc {
	return func(o *Okapi) {
		if router != nil {
			o.router.muxRouter = router
		}
	}
}

// WithServer sets the HTTP server for the Okapi instance
func WithServer(server *http.Server) OptionFunc {
	return func(o *Okapi) {
		if server != nil {
			o.server = server
		}
	}
}

// WithTLS sets tls config to HTTP Server for the Okapi instance
//
// Use okapi.LoadTLSConfig() to create a TLS configuration from certificate and key files
func WithTLS(tlsConfig *tls.Config) OptionFunc {
	return func(o *Okapi) {
		if tlsConfig != nil {
			o.tlsConfig = tlsConfig
		}
	}
}

// WithContext sets the default context for the Okapi instance
func WithContext(ctx context.Context) OptionFunc {
	return func(o *Okapi) {
		if ctx != nil {
			o.ctx = ctx
		}
	}
}

// WithTLSServer sets the TLS server for the Okapi instance
//
// Use okapi.LoadTLSConfig() to create a TLS configuration from certificate and key files
func WithTLSServer(addr string, tlsConfig *tls.Config) OptionFunc {
	return func(o *Okapi) {
		if len(addr) != 0 && tlsConfig != nil {
			if !ValidateAddr(addr) {
				log.Panicf("Invalid address for the TLS Server: %s", addr)
			}
			o.withTlsServer = true
			o.tlsAddr = addr
			o.tlsServerConfig = tlsConfig
		}
	}
}

// WithLogger sets the logger for the Okapi instance
func WithLogger(logger *slog.Logger) OptionFunc {
	return func(o *Okapi) {
		if logger != nil {
			o.logger = logger
		}
	}
}

// WithCors returns an OptionFunc that configures CORS settings
func WithCors(cors Cors) OptionFunc {
	return func(o *Okapi) {
		o.corsEnabled = true
		o.cors = cors
	}
}

// WithWriteTimeout returns an OptionFunc that sets the write timeout
func WithWriteTimeout(t int) OptionFunc {
	return func(o *Okapi) {
		o.writeTimeout = t
		o.server.WriteTimeout = secondsToDuration(t)
	}
}

// WithReadTimeout returns an OptionFunc that sets the read timeout
func WithReadTimeout(t int) OptionFunc {
	return func(o *Okapi) {
		o.readTimeout = t
		o.server.ReadTimeout = secondsToDuration(t)
	}
}

// WithIdleTimeout returns an OptionFunc that sets the idle timeout
func WithIdleTimeout(t int) OptionFunc {
	return func(o *Okapi) {
		o.idleTimeout = t
		o.server.IdleTimeout = secondsToDuration(t)
	}
}

// WithStrictSlash sets whether to enforce strict slash handling
func WithStrictSlash(strict bool) OptionFunc {
	return func(o *Okapi) {
		o.strictSlash = strict
	}
}

// WithDebug enables debug mode and access logging
func WithDebug() OptionFunc {
	return func(o *Okapi) {
		o.debug = true
		o.accessLog = true
	}
}

// WithAccessLogDisabled disables access logging
func WithAccessLogDisabled() OptionFunc {
	return func(o *Okapi) {
		o.accessLog = false
	}
}

// WithPort sets the server port
func WithPort(port int) OptionFunc {
	return func(o *Okapi) {
		if port <= 0 {
			port = defaultPort
		}
		host, _, err := net.SplitHostPort(o.server.Addr)
		if err != nil || host == "" {
			host = ""
		}
		o.server.Addr = net.JoinHostPort(host, strconv.Itoa(port))
	}
}

// WithAddr sets the server address
func WithAddr(addr string) OptionFunc {
	return func(o *Okapi) {
		if strings.TrimSpace(addr) == "" || addr == ":" {
			addr = defaultAddr
		}
		if _, _, err := net.SplitHostPort(addr); err != nil {
			addr = net.JoinHostPort(addr, strconv.Itoa(defaultPort))
		}
		o.server.Addr = addr
	}
}

// WithRenderer sets a custom Renderer for the server.
//
// This allows you to define how templates or views are rendered in response handlers.
// You can implement the Renderer interface on your own type, or use the built-in
// RendererFunc adapter to provide an inline function.
//
// Example using a custom Renderer type:
//
//	type Template struct {
//		templates *template.Template
//	}
//
//	func (t *Template) Render(w io.Writer, name string, data interface{}, c okapi.Context) error {
//		return t.templates.ExecuteTemplate(w, name, data)
//	}
//
// o := okapi.New().WithRenderer(&Template{templates: template.Must(template.ParseGlob("public/views/*.html"))})
//
// Example using RendererFunc:
//
//	o := okapi.New().WithRenderer(okapi.RendererFunc(func(w io.Writer,
//	name string, data interface{}, c *okapi.Context) error {
//		tmpl, err := template.ParseFiles("public/views/" + name + ".html")
//		if err != nil {
//			return err
//		}
//		return tmpl.ExecuteTemplate(w, name, data)
//	}))
func WithRenderer(renderer Renderer) OptionFunc {
	return func(o *Okapi) {
		if renderer != nil {
			o.renderer = renderer
		}
	}
}

// WithOpenAPIDisabled disabled OpenAPI Docs
func WithOpenAPIDisabled() OptionFunc {
	return func(o *Okapi) {
		o.openApiEnabled = false
	}
}

// WithMaxMultipartMemory Maximum memory for multipart forms
func WithMaxMultipartMemory(max int64) OptionFunc {
	return func(o *Okapi) {
		o.maxMultipartMemory = max
	}
}

// ************* Chaining methods *************
// These methods reuse the OptionFunc implementations

func (o *Okapi) WithLogger(logger *slog.Logger) *Okapi {
	return o.apply(WithLogger(logger))
}

// WithContext sets the context for the Okapi instance
func (o *Okapi) WithContext(ctx context.Context) *Okapi {
	return o.apply(WithContext(ctx))
}
func (o *Okapi) WithCORS(cors Cors) *Okapi {
	return o.apply(WithCors(cors))
}

func (o *Okapi) WithWriteTimeout(seconds int) *Okapi {
	return o.apply(WithWriteTimeout(seconds))
}

func (o *Okapi) WithReadTimeout(seconds int) *Okapi {
	return o.apply(WithReadTimeout(seconds))
}

func (o *Okapi) WithIdleTimeout(seconds int) *Okapi {
	return o.apply(WithIdleTimeout(seconds))
}

func (o *Okapi) WithStrictSlash(strict bool) *Okapi {
	return o.apply(WithStrictSlash(strict))
}

func (o *Okapi) WithDebug() *Okapi {
	return o.apply(WithDebug())
}

// WithOpenAPIDisabled disabled OpenAPI Docs
func (o *Okapi) WithOpenAPIDisabled() *Okapi {
	return o.apply(WithOpenAPIDisabled())

}

// WithRenderer sets a custom Renderer for the server.
//
// This allows you to define how templates or views are rendered in response handlers.
// You can implement the Renderer interface on your own type, or use the built-in
// RendererFunc adapter to provide an inline function.
//
// Example using a custom Renderer type:
//
//	type Template struct {
//		templates *template.Template
//	}
//
//	func (t *Template) Render(w io.Writer, name string, data interface{}, c okapi.Context) error {
//		return t.templates.ExecuteTemplate(w, name, data)
//	}
//
// o := okapi.New().WithRenderer(&Template{templates: template.Must(template.ParseGlob("public/views/*.html"))})
//
// Example using RendererFunc:
//
//	o := okapi.New().WithRenderer(okapi.RendererFunc(func(w io.Writer,
//	name string, data interface{}, c *okapi.Context) error {
//		tmpl, err := template.ParseFiles("public/views/" + name + ".html")
//		if err != nil {
//			return err
//		}
//		return tmpl.ExecuteTemplate(w, name, data)
//	}))
func (o *Okapi) WithRenderer(renderer Renderer) *Okapi {
	return o.apply(WithRenderer(renderer))
}

func (o *Okapi) WithPort(port int) *Okapi {
	return o.apply(WithPort(port))
}

func (o *Okapi) WithAddr(addr string) *Okapi {
	return o.apply(WithAddr(addr))
}

func (o *Okapi) DisableAccessLog() *Okapi {
	return o.apply(WithAccessLogDisabled())
}
func (o *Okapi) WithMaxMultipartMemory(max int64) *Okapi {
	return o.apply(WithMaxMultipartMemory(max))
}

// WithOpenAPIDocs registers the OpenAPI JSON and Swagger UI handlers
// at the configured PathPrefix (default: /docs).
//
// UI Path: /docs
// JSON Path: /openapi.json
func (o *Okapi) WithOpenAPIDocs(cfg ...OpenAPI) *Okapi {
	o.openApiEnabled = true

	if len(cfg) > 0 {
		config := cfg[0]

		if config.Title != "" {
			o.openAPI.Title = config.Title
		}
		if config.Version != "" {
			o.openAPI.Version = config.Version
		}
		if len(config.Servers) > 0 {
			o.openAPI.Servers = config.Servers
		}
		o.openAPI.License = config.License
		o.openAPI.Contact = config.Contact
		o.openAPI.SecuritySchemes = config.SecuritySchemes

	}

	o.buildOpenAPISpec()
	// Register the OpenAPI JSON and Swagger UI routes
	o.registerDocRoutes(o.openAPI.Title)
	return o
}

// WithErrorHandler sets a custom error handler
func (o *Okapi) WithErrorHandler(handler ErrorHandler) *Okapi {
	return o.apply(WithErrorHandler(handler))
}

// WithDefaultErrorHandler sets the default error handler
func (o *Okapi) WithDefaultErrorHandler() *Okapi {
	return o.apply(WithDefaultErrorHandler())
}

// WithProblemDetailErrorHandler sets RFC 7807 Problem Details error handler
func (o *Okapi) WithProblemDetailErrorHandler(config *ErrorHandlerConfig) *Okapi {
	return o.apply(WithProblemDetailErrorHandler(config))
}

// WithSimpleProblemDetailErrorHandler sets RFC 7807 Problem Details with default config
func (o *Okapi) WithSimpleProblemDetailErrorHandler() *Okapi {
	return o.apply(WithSimpleProblemDetailErrorHandler())
}

// ****** END OKAPI OPTIONS ******

// ****** RESPONSE WRITER ******

func newResponseWriter(w http.ResponseWriter) *responseWriter {
	return &responseWriter{writer: w}
}

// Header delegates header access.
func (r *responseWriter) Header() http.Header {
	return r.writer.Header()
}

func (r *responseWriter) Write(b []byte) (int, error) {
	if !r.wroteHeader {
		r.WriteHeader(http.StatusOK)
	}
	n, err := r.writer.Write(b)
	r.wroteBytes += n
	return n, err
}

func (r *responseWriter) WriteHeader(statusCode int) {
	if r.wroteHeader {
		return
	}
	r.status = statusCode
	r.wroteHeader = true
	r.writer.WriteHeader(statusCode)
}

func (r *responseWriter) StatusCode() int {
	if !r.wroteHeader {
		return 0
	}
	return r.status
}

func (r *responseWriter) BytesWritten() int {
	return r.wroteBytes
}

// Close closes if the underlying writer supports io.Closer.
func (r *responseWriter) Close() error {
	if closer, ok := r.writer.(io.Closer); ok {
		return closer.Close()
	}
	return nil
}

// Flush flushes if supported.
func (r *responseWriter) Flush() {
	if fl, ok := r.writer.(http.Flusher); ok {
		if !r.wroteHeader {
			r.wroteHeader = true
			r.status = http.StatusOK
		}
		fl.Flush()
	}
}

// Hijack supports WebSockets / raw TCP upgrades.
func (r *responseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error) {
	hj, ok := r.writer.(http.Hijacker)
	if !ok {
		return nil, nil, fmt.Errorf("hijacking not supported")
	}
	return hj.Hijack()
}

func (r *responseWriter) Push(target string, opts *http.PushOptions) error {
	if pusher, ok := r.writer.(http.Pusher); ok {
		return pusher.Push(target, opts)
	}
	return http.ErrNotSupported
}

// ************ Router ************/

// newRouter creates a new Router instance
func newRouter() *Router {
	return &Router{
		muxRouter: mux.NewRouter(),
	}
}

// ********** OKAPI **********//

// New creates a new Okapi instance with the provided options.
func New(options ...OptionFunc) *Okapi {
	return initConfig(options...)
}

// Default creates a new Okapi instance with default settings.
func Default() *Okapi {
	return New(
		withDefaultConfig(),
	)
}

func withDefaultConfig() OptionFunc {
	return func(o *Okapi) {
		o.openApiEnabled = true
	}
}

// With applies the provided options to the Okapi instance
func (o *Okapi) With(options ...OptionFunc) *Okapi {

	o.apply(options...)

	o.applyServerConfig(o.server)

	if o.tlsServerConfig != nil {
		o.tlsServer.TLSConfig = o.tlsServerConfig
		o.tlsServer.Addr = o.tlsAddr
		o.applyServerConfig(o.tlsServer)
	}
	return o
}

// Start starts the Okapi server
func (o *Okapi) Start() error {
	return o.StartServer(o.server)
}

// StartOn starts the Okapi server with custom port
func (o *Okapi) StartOn(port int) error {
	o.WithPort(port)
	return o.Start()
}

// Use registers one or more middleware functions to the Okapi instance.
// These middleware will be executed in the order they are added for every request
// before reaching the route handler. Middleware added here will apply to all routes
// registered on this Okapi instance and any groups created from it.
//
// Middleware functions have the signature:
//
//	func(c *Context) error
//
// Call c.Next() inside middleware to pass control to the next handler in the chain.
//
// Example:
//
//	okapi.Use(func(c *okapi.Context) error {
//	    log.Println("before")
//	    err := c.Next()
//	    log.Println("after")
//	    return err
//	})
//
// Note: For group-specific middleware, use Group.Use() instead.
func (o *Okapi) Use(middlewares ...Middleware) {
	if len(middlewares) == 0 {
		return
	}
	o.middlewares = append(o.middlewares, middlewares...)
}

// UseMiddleware registers a standard HTTP middleware function and integrates
// it into Okapi's middleware chain.
//
// This enables compatibility with existing middleware libraries that use the
// func(http.Handler) http.Handler pattern.
//
// Example:
//
//	okapi.UseMiddleware(func(next http.Handler) http.Handler {
//	    return http.HandlerFunc(func(w http.ResponseWriter, r *http.request) {
//	        w.Header().Set("X-Powered-By", "Okapi")
//	        next.ServeHTTP(w, r)
//	    })
//	})
//
// Internally, Okapi converts between http.Handler and HandlerFunc to allow smooth interop.
func (o *Okapi) UseMiddleware(mw func(http.Handler) http.Handler) {
	o.Use(func(c *Context) error {
		// Convert the rest of the chain into an http.Handler
		next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			// Continue the Okapi middleware chain
			c.request = r
			if err := c.Next(); err != nil {
				http.Error(w, err.Error(), http.StatusInternalServerError)
			}
		})

		// Apply standard middleware and serve
		wrapped := mw(next)
		wrapped.ServeHTTP(c.response, c.request)
		return nil
	})
}

// StartServer starts the Okapi server with the specified HTTP server
func (o *Okapi) StartServer(server *http.Server) error {
	if !ValidateAddr(server.Addr) {
		o.logger.Error("Invalid server address", slog.String("addr", server.Addr))
		panic("Invalid server address")
	}
	if o.openApiEnabled {
		o.WithOpenAPIDocs()
	}
	o.server = server
	server.Handler = o

	// Set BaseContext so all request contexts derive from a cancellable parent.
	baseCtx, baseCancel := context.WithCancel(context.Background())
	o.baseCancel = baseCancel
	server.BaseContext = func(_ net.Listener) context.Context {
		return baseCtx
	}

	o.router.muxRouter.StrictSlash(o.strictSlash)
	o.context.okapi = o
	o.applyCommon()
	o.printServerInfo()
	// Serve with TLS if configured
	if server.TLSConfig != nil {
		return server.ListenAndServeTLS("", "")
	}

	// Serve with separate TLS server if enabled
	if o.withTlsServer && o.tlsServerConfig != nil {
		go func() {
			if err := server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
				o.logger.Error("HTTP server error", slog.String("error", err.Error()))
				panic(err)
			}
		}()

		o.tlsServer.Handler = o
		o.tlsServer.BaseContext = server.BaseContext
		return o.tlsServer.ListenAndServeTLS("", "")
	}

	// Default HTTP only
	return server.ListenAndServe()
}

// Stop gracefully shuts down all active Okapi servers (HTTP and HTTPS).
func (o *Okapi) Stop() error {
	return o.StopWithContext(o.ctx)
}

// StopWithContext gracefully shuts down all active Okapi servers with the provided context.
func (o *Okapi) StopWithContext(ctx context.Context) error {
	shutdownCtx := o.resolveContext(ctx)

	if err := o.shutdownServer(shutdownCtx, o.server, "HTTP"); err != nil {
		return err
	}

	if o.withTlsServer && o.tlsServerConfig != nil {
		if err := o.shutdownServer(shutdownCtx, o.tlsServer, "HTTPS"); err != nil {
			return err
		}
	}

	return nil
}

// shutdownServer handles the shutdown logic for a single server.
func (o *Okapi) shutdownServer(ctx context.Context, server *http.Server, serverType string) error {
	if server == nil {
		return nil
	}

	_, _ = fmt.Fprintf(defaultWriter, "[Okapi] Gracefully shutting down %s server at %s\n", serverType, server.Addr)

	// Cancel the base context to notify all in-flight requests (including SSE streams)
	if o.baseCancel != nil {
		o.baseCancel()
	}

	if err := server.Shutdown(ctx); err != nil {
		return fmt.Errorf("%s shutdown error at %s: %w", serverType, server.Addr, err)
	}
	// Clear the server
	if serverType == "HTTP" {
		o.server = nil
	} else {
		o.tlsServer = nil
	}

	return nil
}

// resolveContext returns the most appropriate context to use.
func (o *Okapi) resolveContext(ctx context.Context) context.Context {
	if ctx != nil {
		return ctx
	}
	if o.ctx != nil {
		return o.ctx
	}
	return context.Background()
}

// Shutdown performs graceful shutdown of the provided server using a background context
// Deprecated, please use StopCtx
func (o *Okapi) Shutdown(server *http.Server, ctx ...context.Context) error {
	if server == nil {
		return nil
	}

	var shutdownCtx context.Context
	if len(ctx) > 0 && ctx[0] != nil {
		shutdownCtx = ctx[0]
	} else {
		shutdownCtx = o.resolveContext(context.TODO())
	}

	return server.Shutdown(shutdownCtx)
}

// GetContext returns the current context
func (o *Okapi) GetContext() *Context {
	return o.context
}
func (o *Okapi) SetContext(ctx *Context) {
	o.context = ctx
}

// ********** HTTP METHODS ***************

// Get registers a new GET route with the given path and handler function.
// Returns the created *Route for possible chaining or modification.
//
// Path parameters support type hints for OpenAPI documentation generation:
//
//   - /users/{id} or /users/:id -> "id" documented as UUID in OpenAPI
//   - /users/{user_id} -> "user_id" documented as UUID in OpenAPI
//   - /users/{id:int} or /users/:id:int -> "id" documented as integer in OpenAPI
//   - /users/{user_id:uuid} -> "user_id" documented as UUID in OpenAPI
//
// Note: Type hints affect OpenAPI schema generation only. All parameters are
// accessed as strings via Context.Param() at runtime.
//
// Example:
//
//	o.Get("/users/{id:int}", func(c okapi.Context) error {
//	    userID := c.Param("id") // Returns string "123"
//	    return c.JSON(200, okapi.M{"user_id": userID})
//	})
func (o *Okapi) Get(path string, h HandlerFunc, opts ...RouteOption) *Route {
	return o.addRoute(methodGet, path, nil, h, opts...)
}

// Post registers a new POST route with the given path and handler function.
// Returns the created *Route for possible chaining or modification.
//
// Commonly used for creating resources. The handler can access request body
// via Context.Bind() or Context.Body().
//
// Example:
//
//	o.Post("/users", func(c okapi.Context) error {
//	    var user User
//	    if err := c.Bind(&user); err != nil {
//	        return err
//	    }
//	    // Create user logic...
//	    return c.Created(user)
//	})
func (o *Okapi) Post(path string, h HandlerFunc, opts ...RouteOption) *Route {
	return o.addRoute(methodPost, path, nil, h, opts...)
}

// Put registers a new PUT route with the given path and handler function.
// Returns the created *Route for possible chaining or modification.
//
// Commonly used for replacing/updating entire resources.
//
// Example:
//
//	o.Put("/users/{id}", func(c okapi.Context) error {
//	    id := c.Param("id")
//	    var user User
//	    if err := c.Bind(&user); err != nil {
//	        return err
//	    }
//	    // Update user logic...
//	    return c.JSON(200, user)
//	})
func (o *Okapi) Put(path string, h HandlerFunc, opts ...RouteOption) *Route {
	return o.addRoute(methodPut, path, nil, h, opts...)
}

// Delete registers a new DELETE route with the given path and handler function.
// Returns the created *Route for possible chaining or modification.
//
// Commonly used for removing resources.
//
// Example:
//
//	o.Delete("/users/{id}", func(c okapi.Context) error {
//	    id := c.Param("id")
//	    // Delete user logic...
//	    return c.NoContent(204)
//	})
func (o *Okapi) Delete(path string, h HandlerFunc, opts ...RouteOption) *Route {
	return o.addRoute(http.MethodDelete, path, nil, h, opts...)
}

// Patch registers a new PATCH route with the given path and handler function.
// Returns the created *Route for possible chaining or modification.
//
// Commonly used for partial updates to resources.
//
// Example:
//
//	o.Patch("/users/{id}", func(c okapi.Context) error {
//	    id := c.Param("id")
//	    var updates map[string]any
//	    if err := c.Bind(&updates); err != nil {
//	        return err
//	    }
//	    // Partial update logic...
//	    return c.JSON(200, updates)
//	})
func (o *Okapi) Patch(path string, h HandlerFunc, opts ...RouteOption) *Route {
	return o.addRoute(methodPatch, path, nil, h, opts...)
}

// Options registers a new OPTIONS route with the given path and handler function.
// Returns the created *Route for possible chaining or modification.
//
// Commonly used for CORS preflight requests to describe communication options.
func (o *Okapi) Options(path string, h HandlerFunc, opts ...RouteOption) *Route {
	return o.addRoute(http.MethodOptions, path, nil, h, opts...)
}

// Head registers a new HEAD route with the given path and handler function.
// Returns the created *Route for possible chaining or modification.
//
// Identical to GET but without the response body, useful for checking resource
// existence or metadata.
func (o *Okapi) Head(path string, h HandlerFunc, opts ...RouteOption) *Route {
	return o.addRoute(methodHead, path, nil, h, opts...)
}

// Any registers a route that matches any HTTP method with the given path and handler function.
// Returns the created *Route for possible chaining or modification.
//
// Useful for handlers that need to respond to multiple HTTP methods uniformly.
//
// Example:
//
//	o.Any("/health", func(c okapi.Context) error {
//	    return c.String(200, "OK")
//	})
func (o *Okapi) Any(path string, h HandlerFunc, opts ...RouteOption) *Route {
	return o.addRoute("", path, nil, h, opts...)
}

// ********** Static Content ***************

// Static serves static files under a path prefix, without directory listing
func (o *Okapi) Static(prefix string, dir string) {
	fs := http.StripPrefix(prefix, http.FileServer(noDirListing{http.Dir(dir)}))
	o.router.muxRouter.PathPrefix(prefix).Handler(fs).Methods(http.MethodGet)
}

// StaticFile serves a single file at the specified path.
func (o *Okapi) StaticFile(path string, filepath string) {
	o.router.muxRouter.HandleFunc(path, func(w http.ResponseWriter, r *http.Request) {
		http.ServeFile(w, r, filepath)
	}).Methods(http.MethodGet)
}

// StaticFS serves static files from a custom http.FileSystem (e.g., embed.FS).
func (o *Okapi) StaticFS(prefix string, fs http.FileSystem) {
	fileServer := http.StripPrefix(prefix, http.FileServer(fs))
	o.router.muxRouter.PathPrefix(prefix).Handler(fileServer).Methods(http.MethodGet)
}

// addRoute adds a route with the specified method to the Okapi instance
func (o *Okapi) addRoute(method, path string, tags []string, h HandlerFunc, opts ...RouteOption) *Route {
	if path == "" {
		panic("Path cannot be empty")
	}
	normalizedPath := normalizeRoutePath(path)
	route := &Route{
		Name:      handleName(h),
		Path:      normalizedPath,
		docPath:   path,
		Method:    method,
		tags:      goutils.RemoveDuplicates(tags),
		handle:    h,
		chain:     o,
		responses: make(map[int]*openapi3.SchemaRef),
	}
	// Register all route options
	for _, opt := range opts {
		opt(route)
	}
	o.routes = append(o.routes, route)
	// Main handler
	o.router.muxRouter.StrictSlash(o.strictSlash).HandleFunc(normalizedPath, func(w http.ResponseWriter, r *http.Request) {
		ctx := NewContext(o, w, r)
		// if the route is disabled, return 404 Not Found
		if route.disabled {
			http.Error(ctx.response, "404 Not Found", http.StatusNotFound)
			return
		}
		// Build the handler chain: global middlewares + route middlewares + handler
		ctx.handlers = route.buildHandlers()
		ctx.index = -1
		// Any error returned by the route will result in a 500 Internal Server Error
		if err := ctx.Next(); err != nil {
			if ctx.response.StatusCode() == 0 {
				http.Error(ctx.response, err.Error(), http.StatusInternalServerError)
			}
		}
	}).Methods(method)
	// Register OPTIONS handler only once per path if CORS is enabled
	o.registerOptionsHandler(normalizedPath)
	return route
}

// Handle registers a new route with the given HTTP method, path, and Okapi-style handler function.
//
// It performs the following steps:
//  1. Normalizes the route path
//  2. Creates and configures a new Route instance
//  3. Applies all registered middleware to the handler
//  4. Registers the route with the underlying router (with method filtering)
//  5. Adds centralized error handling for the route
//
// Parameters:
//   - method: HTTP method (e.g., "GET", "POST", "PUT")
//   - path:   URL path pattern (supports path parameters, e.g., /users/:id)
//   - h:      A handler function using Okapi's Context abstraction
//   - opts:   Optional route metadata (e.g., OpenAPI summary, description, tags)
//
// Middleware:
//
//	All middleware registered via Use() or UseMiddleware() will be applied in order,
//	wrapping around the handler.
//
// Error Handling:
//
//	Any non-nil error returned by the handler will automatically result in a
//	500 Internal Server Error response.
//
// Example:
//
//	okapi.Handle("GET", "/users/:id", func(c *okapi.Context) error {
//	    id := c.Param("id")
//	    // process request...
//	    return nil
//	})
func (o *Okapi) Handle(method, path string, h HandlerFunc, opts ...RouteOption) {
	o.addRoute(method, path, nil, h, opts...)
}

// HandleHTTP registers a new route using a standard http.Handler.
//
// It wraps the provided http.Handler into Okapi's internal HandlerFunc signature
// and processes it as if it were registered via Handle.
//
// Parameters:
//   - method: HTTP method (e.g., "GET", "POST", "DELETE")
//   - path:   URL path pattern (supports dynamic segments)
//   - h:      A standard http.Handler (or http.HandlerFunc)
//   - opts:   Optional route metadata (e.g., OpenAPI summary, description, tags)
//
// Differences from Handle:
//   - Uses the standard http.Handler interface
//   - Middleware is still applied
//   - Errors must be handled inside the handler itself (Okapi will not capture them)
//
// Example:
//
//	okapi.HandleHTTP("GET", "/static", http.FileServer(http.Dir("./public")))
func (o *Okapi) HandleHTTP(method, path string, h http.Handler, opts ...RouteOption) {
	o.addRoute(method, path, nil, o.wrapHTTPHandler(h), opts...)
}

// HandleStd is a convenience method for registering handlers using the standard
// http.HandlerFunc signature (func(http.ResponseWriter, *http.Request)).
//
// Internally, it wraps the handler into http.Handler and delegates to HandleHTTP.
//
// Example:
//
//	okapi.HandleStd("GET", "/greet", func(w http.ResponseWriter, r *http.Request) {
//	    w.Write([]byte("Hello from Okapi!"))
//	})
//
// This handler will still benefit from:
//   - All registered middleware
//   - Automatic route and CORS registration
func (o *Okapi) HandleStd(method, path string, h func(http.ResponseWriter, *http.Request), opts ...RouteOption) {
	o.HandleHTTP(method, path, http.HandlerFunc(h), opts...)
}

// registerOptionsHandler registers OPTIONS handler
func (o *Okapi) registerOptionsHandler(path string) {
	// Register OPTIONS handler only once per path if CORS is enabled
	if o.corsEnabled && !o.optionsRegistered[path] {
		o.optionsRegistered[path] = true

		o.router.muxRouter.StrictSlash(o.strictSlash).HandleFunc(path, func(w http.ResponseWriter, r *http.Request) {
			origin := r.Header.Get("Origin")
			if origin == "" || !originAllowed(o.cors.AllowedOrigins, origin) {
				http.Error(w, "", http.StatusMethodNotAllowed)
				return
			}

			cors := o.cors

			if len(cors.AllowMethods) == 0 {
				for _, route := range o.routes {
					if route.Path == path {
						cors.AllowMethods = append(cors.AllowMethods, route.Method)
					}
				}
			}
			cors.writeHeaders(w.Header(), r, true)

			w.WriteHeader(http.StatusNoContent)
		}).Methods(http.MethodOptions)
	}
}

// ServeHTTP implements the http.Handler interface
func (o *Okapi) ServeHTTP(w http.ResponseWriter, r *http.Request) {

	ctx := &Context{
		request:  r,
		response: newResponseWriter(w),
		okapi:    o,
	}
	handler := func(c *Context) {
		o.router.muxRouter.ServeHTTP(c.response, c.request)
	}
	handler(ctx)
}

// globalMiddlewares returns the global middleware chain.
func (o *Okapi) globalMiddlewares() []Middleware {
	return o.middlewares
}

// buildHandlers constructs the full handler chain for a route:
// global middlewares + route middlewares + final handler.
func (r *Route) buildHandlers() []HandlerFunc {
	global := r.chain.globalMiddlewares()
	handlers := make([]HandlerFunc, 0, len(global)+len(r.middlewares)+1)
	handlers = append(handlers, global...)
	handlers = append(handlers, r.middlewares...)
	handlers = append(handlers, r.handle)
	return handlers
}
func (o *Okapi) Routes() []Route {
	routes := make([]Route, 0, len(o.routes))
	for _, route := range o.routes {
		if route.internal {
			continue // Skip internal routes
		}
		routes = append(routes, *route)
	}
	return routes
}

// Group creates a new route group with the specified base path and optional middlewares.
// The group inherits all existing middlewares from the parent Okapi instance.
// Routes registered within the group will have their paths prefixed with the group's path,
// and the group's middlewares will be executed before the route-specific handlers.
//
// Panics if the path is empty, as this would lead to ambiguous routing.
//
// Example:
//
//	api := okapi.Group("/api", AuthMiddleware) // All /api routes require auth
//	api.Get("/users", getUserHandler)          // Handles /api/users
//	api.Post("/users", createUserHandler)      // Handles /api/users
func (o *Okapi) Group(prefix string, middlewares ...Middleware) *Group {
	if len(prefix) == 0 {
		panic("Group prefix cannot be empty")
	}
	group := &Group{
		Prefix:      prefix,
		okapi:       o,
		middlewares: middlewares,
	}
	return group
}

// initConfig initializes a new Okapi instance.
func initConfig(options ...OptionFunc) *Okapi {
	server := &http.Server{
		Addr: defaultAddr,
	}

	o := &Okapi{
		context: &Context{
			request:  new(http.Request),
			response: &responseWriter{},
			store:    newStoreData(),
		},
		router:             newRouter(),
		server:             server,
		tlsServer:          &http.Server{},
		logger:             slog.Default(),
		accessLog:          true,
		middlewares:        []Middleware{handleAccessLog},
		optionsRegistered:  make(map[string]bool),
		maxMultipartMemory: defaultMaxMemory,
		cors:               Cors{},
		ctx:                context.Background(),
		errorHandler:       DefaultErrorHandler,
		openAPI: &OpenAPI{
			Title:            okapiName,
			Version:          "1.0.0",
			Servers:          Servers{{}},
			SecuritySchemes:  SecuritySchemes{},
			ComponentSchemas: make(map[string]*SchemaInfo),
		},
		openapiSpec: &openapi3.T{},
	}

	return o.With(options...)
}

// applyServerConfig sets common server timeout and keep-alive configurations
func (o *Okapi) applyServerConfig(s *http.Server) {
	s.ReadTimeout = secondsToDuration(o.readTimeout)
	s.WriteTimeout = secondsToDuration(o.writeTimeout)
	s.IdleTimeout = secondsToDuration(o.idleTimeout)
}

// apply is a helper method to apply an OptionFunc to the Okapi instance
func (o *Okapi) apply(options ...OptionFunc) *Okapi {
	for _, option := range options {
		option(o)
	}
	return o
}
func (o *Okapi) applyCommon() {
	if o.noRoute != nil {
		o.router.muxRouter.NotFoundHandler = o.wrapHandleFunc(o.noRoute)
	}
	if o.noMethod != nil {
		o.router.muxRouter.MethodNotAllowedHandler = o.wrapHandleFunc(o.noMethod)
	}
}

// NoRoute sets a custom handler to be executed when no matching route is found.
//
// This function allows you to define a fallback handler for unmatched routes (404).
// It is useful for returning custom error pages or JSON responses when a route doesn't exist.
//
// Example:
//
//	o.NoRoute(func(c okapi.Context) error {
//		return c.AbortNotFound("Custom 404 - Not found")
//	})
func (o *Okapi) NoRoute(h HandlerFunc) {
	o.noRoute = h
}

// NoMethod sets a custom handler to be executed when the HTTP method is not allowed.
//
// This function is triggered when the request path exists but the method (e.g., POST, GET) is not allowed.
// It enables you to define a consistent response for unsupported HTTP methods (405).
//
// Example:
//
//	o.NoMethod(func(c okapi.Context) error {
//	 return c.AbortMethodNotAllowed("Custom 405 - Method Not Allowed")
//	})
func (o *Okapi) NoMethod(h HandlerFunc) {
	o.noMethod = h
}

// handleAccessLog logs the access details of the request
func handleAccessLog(c *Context) error {
	if c.IsWebSocketUpgrade() || c.IsSSE() || !c.okapi.accessLog {
		return c.Next()
	}
	startTime := time.Now()
	err := c.Next()
	status := c.response.StatusCode()
	logger := c.okapi.logger
	logFields := buildBaseLogFields(c, status, time.Since(startTime))
	if c.okapi.debug {
		debugFields := buildDebugFields(c)
		logFields = append(logFields, debugFields...)
	}
	switch {
	case status >= 500:
		logger.Error("[Okapi] Incoming request", logFields...)
	case status >= 400:
		logger.Warn("[Okapi] Incoming request", logFields...)
	default:
		logger.Info("[Okapi] Incoming request", logFields...)
	}
	return err
}

// buildBaseLogFields constructs the core log fields
func buildBaseLogFields(c *Context, status int, duration time.Duration) []any {
	bytesIn := c.request.ContentLength
	if bytesIn < 0 {
		bytesIn = 0
	}
	return []any{
		"method", c.request.Method,
		"path", c.request.URL.Path,
		"status", status,
		"duration", goutils.FormatDuration(duration, 2),
		"ip", c.RealIP(),
		"host", c.request.Host,
		"bytes_in", bytesIn,
		"bytes_out", c.response.BytesWritten(),
		"referer", c.request.Referer(),
		"user_agent", c.request.UserAgent(),
	}
}
func (o *Okapi) wrapHandleFunc(h HandlerFunc) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		ctx := NewContext(o, w, r)
		if err := h(ctx); err != nil {
			o.logger.Error("handler error", slog.String("error", err.Error()))
			http.Error(w, err.Error(), http.StatusInternalServerError)

		}
	})
}
func (o *Okapi) wrapHTTPHandler(h http.Handler) HandlerFunc {
	return func(ctx *Context) error {
		h.ServeHTTP(ctx.response, ctx.request)
		return nil
	}
}

func (o *Okapi) printServerInfo() {
	if o.server == nil {
		fmt.Println("Server not initialized")
		return
	}

	addr := o.server.Addr
	if addr == "" {
		addr = ":http"
	}

	host, port := parseAddr(addr)

	separatorWidth := 56
	fmt.Println(strings.Repeat("=", separatorWidth))

	fmt.Println("Starting Okapi server...")

	// Local HTTP
	fmt.Printf("  • Local:       http://%s:%s\n", host, port)

	// TLS (if enabled)
	if o.withTlsServer && o.tlsServerConfig != nil {
		tlsAddr := o.tlsServer.Addr
		if tlsAddr == "" {
			tlsAddr = ":https"
		}
		tlsHost, tlsPort := parseAddr(tlsAddr)
		fmt.Printf("  • Local TLS:   https://%s:%s\n", tlsHost, tlsPort)
	}

	// Environment
	env := o.environment()
	if env == "" {
		env = "development"
	}
	fmt.Printf("  • Environment: %s\n", env)

	// Docs
	if o.openApiEnabled {
		fmt.Printf("  • Docs:        http://%s:%s/docs\n", host, port)
		fmt.Printf("  • OpenAPI:     http://%s:%s/openapi.json\n", host, port)
	}
	fmt.Println(strings.Repeat("-", separatorWidth))

	// Print registered routes if debug is enabled
	if o.debug {
		o.printRoutes()
	}

}

// printRoutes prints all registered routes in a formatted table
func (o *Okapi) printRoutes() {
	routes := o.routes
	if len(routes) == 0 {
		fmt.Printf("No routes registered")
		return
	}

	// Calculate column widths for better formatting
	maxMethod := 0
	maxPath := 0
	maxName := 0

	for _, route := range routes {
		if len(route.Method) > maxMethod {
			maxMethod = len(route.Method)
		}
		if len(route.Path) > maxPath {
			maxPath = len(route.Path)
		}
		if len(route.Name) > maxName {
			maxName = len(route.Name)
		}
	}

	// Calculate total width for the separator
	totalWidth := maxMethod + maxPath + maxName + 6
	separatorWidth := totalWidth

	// Print table header
	fmt.Printf("%-*s | %-*s | %-*s\n",
		maxMethod, "METHOD",
		maxPath, "PATH",
		maxName, "NAME")
	fmt.Println(strings.Repeat("-", totalWidth))

	// Print routes
	for _, route := range routes {
		if route.hidden || route.disabled {
			continue // Skip hidden/disabled routes
		}

		methodColor := getMethodColor(route.Method)
		fmt.Printf("%s%-*s\033[0m | %-*s | %-*s\n",
			methodColor,
			maxMethod, route.Method,
			maxPath, route.Path,
			maxName, route.Name)
	}

	fmt.Println(strings.Repeat("=", separatorWidth))
}

// Register registers a list of RouteDefinition to the Okapi instance.
// This method allows you to define multiple routes in a single call, which can be useful for
// organizing your routes in a more structured way.
// Example:
//
//	routes := []okapi.RouteDefinition{
//	    {
//	        Method:  "POST",
//	        Path:    "/example",
//	        Handler: exampleHandler,
//			Middlewares: []okapi.Middleware{customMiddleware}
//			OperationId: "PostExample",
//			Summary: "Example POST request",
//			Description: "This endpoint handles example POST request.",
//			Request: &RequestExample{},
//			Response: &ResponseExample{}
//	    },
//	    {
//	        Method:  "GET",
//	        Path:    "/example",
//	        Handler: exampleHandler,
//	        Options: []okapi.RouteOption{
//	            okapi.DocSummary("Example GET request"),
//	        },
//	    	Security: Security: []map[string][]string{
//				{
//					"bearerAuth": {},
//				},
//			},
//	    },
//	}
//	// Create a new Okapi instance
//	app := okapi.New()
//	app.Register(routes...)
func (o *Okapi) Register(routes ...RouteDefinition) {
	RegisterRoutes(o, routes)
}

// ************************ Helpers functions **************************

// Handle binds and validates the request body into the input type I,
// then executes the handler.
//
// This helper is useful when you only need to process the request input
// and control the response manually inside the handler (e.g. using c.OK(),
// c.JSON(), c.NoContent(), etc.).
//
// Example:
//
//	o.Post("/books", okapi.Handle(func(c *okapi.Context, in *Book) error {
//	    return c.Created(in)
//	}))
func Handle[I any](h func(*Context, *I) error) HandlerFunc {
	return func(c *Context) error {
		var in I
		if err := c.Bind(&in); err != nil {
			return c.AbortBadRequest("Bad Request", err)
		}
		return h(c, &in)
	}
}

// H is a shorthand alias for Handle.
// It provides the same behavior and is intended for more concise route
// definitions when readability is preferred over verbosity.
//
// Example:
//
//	o.Post("/books", okapi.H(func(c *okapi.Context, in *Book) error {
//	    return c.Created(in)
//	}))
func H[I any](h func(*Context, *I) error) HandlerFunc {
	return Handle(h)
}

// HandleIO binds and validates the request body into the input type I,
// then executes the handler and writes the response based on content negotiation.
//
// The response format is determined by the Accept request header:
// - application/json -> JSON response
// - application/xml -> XML response
// - text/html -> HTML response (if template registered)
// - etc.
//
// This is useful for APIs that need to support multiple response formats
// without writing separate handlers.
//
// Example:
//
//	type Book struct {
//		ID     int    `json:"id"`
//		Name   string `json:"name" form:"name"  maxLength:"50" example:"The Go Programming Language" yaml:"name" required:"true"`
//		Price  int    `json:"price" form:"price" query:"price" yaml:"price" min:"0" default:"0" max:"500"`
//		Qty    int    `json:"qty" form:"qty" query:"qty" yaml:"qty" default:"0"`
//		Status string `json:"status" form:"status" query:"status" yaml:"status" enum:"paid,unpaid,canceled"  required:"true" example:"available"`
//	}
//
//	type BookOutput struct {
//	    Status int
//	    Body Book
//	}
//
//	o.Post("/books", okapi.HandleIO(func(c *okapi.Context, in *Book) (*BookOutput, error) {
//	    books = append(books, *in)
//	    return &BookOutput{Body: *in}, nil
//	}))
//
//	// Client requests with Accept: application/json -> JSON response
//	// Client requests with Accept: application/xml -> XML response
func HandleIO[I any, O any](h func(*Context, *I) (*O, error)) HandlerFunc {
	return func(c *Context) error {
		var in I
		if err := c.Bind(&in); err != nil {
			return c.AbortBadRequest("Bad Request", err)
		}

		out, err := h(c, &in)
		if err != nil {
			return err
		}
		return c.Return(out) // Content negotiation based on Accept header
	}
}

// HandleO executes the handler and writes the response based on content negotiation.
// Useful for GET/LIST endpoints that don't need input binding but support
// multiple response formats.
//
// Example:
//
//	type BooksOutput struct {
//	    Status int
//	    Body []Book
//	}
//	o.Get("/books", okapi.HandleO(func(c *okapi.Context) (*BooksOutput, error) {
//	    return &BooksOutput{Body: books}, nil
//	}))
//
//	// Client can request JSON, XML, HTML, etc. via Accept header
func HandleO[O any](h func(*Context) (*O, error)) HandlerFunc {
	return func(c *Context) error {
		out, err := h(c)
		if err != nil {
			return err
		}
		return c.Return(out)
	}
}

// RegisterSchemas registers component schemas that are re-used as references.
func (o *Okapi) RegisterSchemas(schemas map[string]*SchemaInfo) error {
	for name, schema := range schemas {
		if _, exists := o.openAPI.ComponentSchemas[name]; exists {
			return fmt.Errorf("component schema with name [%s] exists", name)
		}
		// ensure valid type name.
		if schema.TypeName == "" {
			schema.TypeName = name
		}
		o.openAPI.ComponentSchemas[name] = schema
	}
	return nil
}

// environment returns the current application environment
func (o *Okapi) environment() string {
	envVars := []string{
		"OKAPI_ENV",
		"GO_ENV",
		"APP_ENV",
		"ENV",
		"ENVIRONMENT",
		"NODE_ENV",
	}
	for _, envVar := range envVars {
		if env := os.Getenv(envVar); env != "" {
			return normalizeEnvironment(env)
		}
	}

	return "development"
}