router

type AuthLevel int

type CORSConfig struct {
	Origins          []string      // Allowed origins (e.g., "http://example.com", "*"). Required.
	Methods          []string      // Allowed methods (e.g., "GET", "POST"). Defaults to simple methods if empty.
	Headers          []string      // Allowed headers. Defaults to simple headers if empty.
	ExposeHeaders    []string      // Headers the browser is allowed to access.
	AllowCredentials bool          // Whether to allow credentials (cookies, authorization headers).
	MaxAge           time.Duration // How long the results of a preflight request can be cached.
}

type Codec[T any, U any] interface {
	// NewRequest creates a new zero-value instance of the request type T.
	// This is used by the framework to get an instance for decoding, avoiding reflection.
	NewRequest() T

	// Decode extracts and deserializes data from an HTTP request body into a value of type T.
	// The type T represents the request data type.
	Decode(r *http.Request) (T, error)

	// DecodeBytes extracts and deserializes data from a byte slice into a value of type T.
	// This is used for source types where the data is already extracted (e.g., query/path parameters).
	// The type T represents the request data type.
	DecodeBytes(data []byte) (T, error)

	// Encode serializes a value of type U and writes it to the HTTP response.
	// It converts the Go value to the wire format (e.g., JSON, Protocol Buffers) and
	// sets appropriate headers (e.g., Content-Type). If the serialization fails, it returns an error.
	// The type U represents the response data type.
	Encode(w http.ResponseWriter, resp U) error
}

type GenericHandler[T any, U any] func(r *http.Request, data T) (U, error)

type GenericRouteRegistrationFunc[T comparable, U any] func(r *Router[T, U], sr SubRouterConfig)

type HTTPError struct {
	StatusCode int    // HTTP status code (e.g., 400, 404, 500)
	Message    string // Error message to be sent in the response body
}

type HttpMethod string

type IPConfig struct {
	// Source specifies where to extract the client IP from.
	Source IPSourceType

	// CustomHeader is the name of the custom header to use when Source is IPSourceCustomHeader
	CustomHeader string

	// TrustProxy determines whether to trust proxy headers like X-Forwarded-For
	// If false, RemoteAddr will be used as a fallback for all sources
	TrustProxy bool
}

type IPSourceType string

type MetricsConfig struct {
	// Collector is the metrics collector to use.
	// If nil, a default collector will be used if metrics are enabled.
	Collector any // metrics.Collector

	// MiddlewareFactory is the factory for creating metrics middleware.
	// If nil, a default middleware factory will be used if metrics are enabled.
	MiddlewareFactory any // metrics.MiddlewareFactory

	// Namespace for metrics.
	Namespace string

	// Subsystem for metrics.
	Subsystem string

	// EnableLatency enables latency metrics.
	EnableLatency bool

	// EnableThroughput enables throughput metrics.
	EnableThroughput bool

	// EnableQPS enables queries per second metrics.
	EnableQPS bool

	// EnableErrors enables error metrics.
	EnableErrors bool
}

type Middleware = common.Middleware

type PrometheusConfig struct{}

type RouteConfig[T any, U any] struct {
	Path        string                            // Route path (will be prefixed with sub-router path prefix if applicable)
	Methods     []HttpMethod                      // HTTP methods this route handles (use constants like MethodGet)
	AuthLevel   *AuthLevel                        // Authentication level for this route (NoAuth, AuthOptional, or AuthRequired). If nil, inherits from sub-router or defaults to NoAuth.
	Timeout     time.Duration                     // Override timeout for this specific route
	MaxBodySize int64                             // Override max body size for this specific route
	RateLimit   *common.RateLimitConfig[any, any] // Use common.RateLimitConfig // Rate limit for this specific route
	Codec       Codec[T, U]                       // Codec for marshaling/unmarshaling request and response
	Handler     GenericHandler[T, U]              // Generic handler function
	Middlewares []common.Middleware               // Middlewares applied to this specific route
	SourceType  SourceType                        // How to retrieve request data (defaults to Body)
	SourceKey   string                            // Query parameter name (only used for query parameters)
	Sanitizer   func(T) (T, error)                // Optional sanitizer function applied after decoding
}

type RouteConfigBase struct {
	Path        string                            // Route path (will be prefixed with sub-router path prefix if applicable)
	Methods     []HttpMethod                      // HTTP methods this route handles (use constants like MethodGet)
	AuthLevel   *AuthLevel                        // Authentication level for this route (NoAuth, AuthOptional, or AuthRequired). If nil, inherits from sub-router or defaults to NoAuth.
	Timeout     time.Duration                     // Override timeout for this specific route
	MaxBodySize int64                             // Override max body size for this specific route
	RateLimit   *common.RateLimitConfig[any, any] // Use common.RateLimitConfig // Rate limit for this specific route
	Handler     http.HandlerFunc                  // Standard HTTP handler function
	Middlewares []common.Middleware               // Middlewares applied to this specific route
}

type Router[T comparable, U any] struct {
	// contains filtered or unexported fields
}

type RouterConfig struct {
	ServiceName         string                            // Name of the service, used for metrics tagging etc.
	Logger              *zap.Logger                       // Logger for all router operations
	GlobalTimeout       time.Duration                     // Default response timeout for all routes
	GlobalMaxBodySize   int64                             // Default maximum request body size in bytes
	GlobalRateLimit     *common.RateLimitConfig[any, any] // Use common.RateLimitConfig // Default rate limit for all routes
	IPConfig            *IPConfig                         // Configuration for client IP extraction
	EnableMetrics       bool                              // Enable metrics collection
	EnableTraceLogging  bool                              // Enable trace logging
	TraceLoggingUseInfo bool                              // Use Info level for trace logging
	TraceIDBufferSize   int                               // Buffer size for trace ID generator (0 disables trace ID)
	MetricsConfig       *MetricsConfig                    // Metrics configuration (optional)
	SubRouters          []SubRouterConfig                 // Sub-routers with their own configurations
	Middlewares         []common.Middleware               // Global middlewares applied to all routes
	AddUserObjectToCtx  bool                              // Add user object to context
	CORSConfig          *CORSConfig                       // CORS configuration (optional, if nil CORS is disabled)
}

type SourceType int

type SubRouterConfig struct {
	PathPrefix          string                            // Common path prefix for all routes in this sub-router
	TimeoutOverride     time.Duration                     // Override global timeout for all routes in this sub-router
	MaxBodySizeOverride int64                             // Override global max body size for all routes in this sub-router
	RateLimitOverride   *common.RateLimitConfig[any, any] // Use common.RateLimitConfig // Override global rate limit for all routes in this sub-router
	Routes              []any                             // Routes in this sub-router. Can contain RouteConfigBase or GenericRouteRegistrationFunc.
	Middlewares         []common.Middleware               // Middlewares applied to all routes in this sub-router
	// SubRouters is a slice of nested sub-routers
	// This allows for creating a hierarchy of sub-routers
	SubRouters []SubRouterConfig // Nested sub-routers
	AuthLevel  *AuthLevel        // Default authentication level for all routes in this sub-router (overridden by route-specific AuthLevel)
}