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 Middleware = common.Middleware

type PrometheusConfig struct {
	Registry         interface{} // Prometheus registry (prometheus.Registerer)
	Namespace        string      // Namespace for metrics
	Subsystem        string      // Subsystem for metrics
	EnableLatency    bool        // Enable latency metrics
	EnableThroughput bool        // Enable throughput metrics
	EnableQPS        bool        // Enable queries per second metrics
	EnableErrors     bool        // Enable error metrics
}

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
}

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