router

type AuthLevel int

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 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

	// Exporter is the metrics exporter to use.
	// If nil, a default exporter will be used if metrics are enabled.
	Exporter any // metrics.Exporter

	// 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   *middleware.RateLimitConfig[any, any] // 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)
}

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   *middleware.RateLimitConfig[any, any] // 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 {
	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    *middleware.RateLimitConfig[any, any] // Default rate limit for all routes
	IPConfig           *middleware.IPConfig                  // Configuration for client IP extraction
	EnableMetrics      bool                                  // Enable metrics collection
	TraceIDBufferSize  int                                   // Buffer size for trace ID generator (0 disables trace ID)
	PrometheusConfig   *PrometheusConfig                     // Prometheus metrics configuration (optional, deprecated)
	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
}

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   *middleware.RateLimitConfig[any, any] // 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)
}