router

type AuthLevel int

type Codec[T any, U any] interface {
	// Decode extracts and deserializes data from an HTTP request into a value of type T.
	// It reads the request body and converts it from the wire format (e.g., JSON, Protocol Buffers)
	// into the appropriate Go type. If the deserialization fails, it returns an error.
	// The type T represents the request data type.
	Decode(r *http.Request) (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 HTTPError struct {
	StatusCode int    // HTTP status code (e.g., 400, 404, 500)
	Message    string // Error message to be sent in the response body
}

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

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

	// MiddlewareFactory is the factory for creating metrics middleware.
	// If nil, a default middleware factory will be used if metrics are enabled.
	MiddlewareFactory interface{} // 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        []string                              // HTTP methods this route handles
	AuthLevel      AuthLevel                             // Authentication level for this route (NoAuth, AuthOptional, or AuthRequired)
	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)
	CacheResponse  bool                                  // Whether to cache responses for this route
	CacheKeyPrefix string                                // Prefix for cache keys to avoid collisions
}

type RouteConfigBase struct {
	Path        string                                // Route path (will be prefixed with sub-router path prefix if applicable)
	Methods     []string                              // HTTP methods this route handles
	AuthLevel   AuthLevel                             // Authentication level for this route (NoAuth, AuthOptional, or AuthRequired)
	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
	EnableTracing      bool                                  // Enable distributed tracing
	EnableTraceID      bool                                  // Enable trace ID logging
	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
	CacheGet           func(string) ([]byte, bool)           // Function to retrieve cached responses
	CacheSet           func(string, []byte) error            // Function to store responses in the cache
	CacheKeyPrefix     string                                // Prefix for cache keys to avoid collisions
}

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              []RouteConfigBase                     // Routes in this sub-router
	Middlewares         []common.Middleware                   // Middlewares applied to all routes in this sub-router
	CacheResponse       bool                                  // Whether to cache responses for routes in this sub-router
	CacheKeyPrefix      string                                // Prefix for cache keys to avoid collisions
}