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 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 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. If nil, inherits from sub-router or defaults to NoAuth
	Overrides   common.RouteOverrides // Configuration overrides for this specific route
	Codec       codec.Codec[T, U]     // Codec for marshaling/unmarshaling request and response (required)
	Handler     GenericHandler[T, U]  // Generic handler function (required)
	Middlewares []common.Middleware   // Middlewares applied to this specific route (combined with sub-router and global middlewares)
	SourceType  SourceType            // Where to retrieve request data from (defaults to Body)
	SourceKey   string                // Parameter name for query/path parameters (required when SourceType is not Body/Empty)
	Sanitizer   func(T) (T, error)    // Optional function to validate/transform request data 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. If nil, inherits from sub-router or defaults to NoAuth
	Overrides      common.RouteOverrides // Configuration overrides for this specific route
	Handler        http.HandlerFunc      // Standard HTTP handler function
	Middlewares    []common.Middleware   // Middlewares applied to this specific route (combined with sub-router and global middlewares)
	DisableTimeout bool                  // Indicates if the timeout should be disabled for this route (e.g., for WebSockets or long-lived connections).
}

type RouteDefinition interface {
	// contains filtered or unexported methods
}

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
	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
	Overrides   common.RouteOverrides // Configuration overrides for routes in this sub-router (not inherited by nested sub-routers)
	Routes      []RouteDefinition     // Routes in this sub-router. Can contain RouteConfigBase or GenericRouteRegistrationFunc
	Middlewares []common.Middleware   // Middlewares applied to all routes in this sub-router (additive with global middlewares)
	// SubRouters is a slice of nested sub-routers.
	// Nested sub-routers inherit the parent's path prefix (concatenated) but NOT configuration overrides.
	// Each nested sub-router must explicitly set its own overrides if needed.
	SubRouters []SubRouterConfig // Nested sub-routers with concatenated path prefixes
	AuthLevel  *AuthLevel        // Default authentication level for all routes in this sub-router (overridden by route-specific AuthLevel)
}