router

type Context interface {
	// Context embeds the standard context.Context interface
	context.Context

	// Metadata is used to decorate the context with additional data.
	// Useful to provide additional context about the current request.
	// Examples: User, RequestID, Ingress, etc.
	// Metadata is not a data store, use Value and SetValue for that.
	Metadata() structures.Map[string, interface{}]

	// Request returns a wrapper around the standard http.Request object
	// which provides assistive functions.
	//
	// The contained http.Request is the original request object passed to the
	// handler. The request object may be modified or replaced by the middleware chain.
	Request() Request

	// Response returns a wrapper around the response writer which provides
	// assistive functions for writing to the response body.
	//
	// The contained response writer is the original response writer passed to
	// the handler. The response writer may be modified or replaced by the middleware chain.
	Response() Response

	// SetValue modifies the context to contain the given value for the given key
	// This is a replacement for the context.WithValue function, since the type is not retained.
	// The embedded context.Context is kept immutable and gets replaced, never modified.
	SetValue(key any, value any)
}

type Group interface {
	// GET will add a route to this route group for the get method
	GET(path string, handler interface{})
	// HEAD will add a route to this route group for the head method
	HEAD(path string, handler interface{})
	// POST will add a route to this route group for the post method
	POST(path string, handler interface{})
	// PUT will add a route to this route group for the put method
	PUT(path string, handler interface{})
	// DELETE will add a route to this route group for the delete method
	DELETE(path string, handler interface{})
	// CONNECT will add a route to this route group for the connect method
	CONNECT(path string, handler interface{})
	// OPTIONS will add a route to this route group for the options method
	OPTIONS(path string, handler interface{})
	// TRACE will add a route to this route group for the trace method
	TRACE(path string, handler interface{})
	// PATCH will add a route to this route group for the patch method
	PATCH(path string, handler interface{})

	// WithMiddleware will add a middleware to the route group
	WithMiddleware(handler interface{})
	// WithRoute will add a new route with the given http method to the router group
	WithRoute(method string, path string, handler interface{})

	// Middleware will return a list of potential middlewares that were registered on this router group
	Middleware() []interface{}

	// ApplyToRouter will attempt to merge all middlewares with the collected route handlers
	// and then attempt to register the routes on the router with a given prefix.
	// Will return an error if any of the steps throw an error
	ApplyToRouter(router Router, prefix string) error
}

type Handleable interface {
	ToHandler() interface{}
}

type Handler interface {
	// AddMiddleware adds a middleware into the chain
	AddMiddleware(middleware interface{}) error

	// Introspection will return the introspected information about the handler
	Introspection() HandlerIntrospection

	// HandlerFunc will generate the original handlers function
	// without any chained middlewares
	HandlerFunc() HandlerFunc

	// Serve is the handler func that executes the handler and all the middlewares
	Serve(ctx Context) error

	// Value returns the reflection value of the handler func
	Value() reflect.Value
}

type HandlerArgFactory func(ctx Context, next HandlerFunc) (reflect.Value, error)

type HandlerFunc func(ctx Context) error

type HandlerIntrospection interface {
	introspector.IntrospectorResult[HandlerArgFactory]

	// CanError returns true when the handler func is returning error
	CanError() bool

	// IsStdlibMiddleware returns true when the handler func is a stdlib middleware
	IsStdlibMiddleware() bool
}

type MiddlewareHandlerFunc func(ctx Context, next interface{}) error

type Request interface {
	// GetRequest returns the underlying http.Request object
	GetRequest() *http.Request

	// Request replaces the underlying http.Request object
	SetRequest(req *http.Request)

	// Body returns a copy of the request body
	Body() ([]byte, error)

	// Param returns the route parameter or empty string if not found
	Param(name string) string

	// ParamOrDefault returns the route parameter or a custom default if not found
	ParamOrDefault(name string, def string) string

	// SetParams will set the routep params for this request
	SetParams(params map[string]string)

	// ParseString returns the request body as a string
	ParseString() (string, error)

	// ParseJSON will attempt to parse the request body as JSON
	ParseJSON(obj interface{}) error

	// ParseXML will attempt to parse the request body as XML
	ParseXML(obj interface{}) error

	// HasContentType determines whether a request has a given mime type as its content type
	HasContentType(mimetype string) bool
}

type Response interface {
	http.ResponseWriter

	// GetWriter returns the underlying response writer instance
	GetWriter() http.ResponseWriter

	// SetWriter replaces the underlying response writer instance
	SetWriter(res http.ResponseWriter)

	// WriteJSON writes any object to the response body as JSON
	WriteJSON(body interface{}, pretty bool) error

	// WriteString will write a string to the response body
	WriteString(str string) error
}

type Router interface {
	// WithGroup will create a new route group for the given prefix
	WithGroup(prefix string, callback func(group Group)) error
	// WithRoute will add a new route with the given RouteMethod to the router
	WithRoute(method string, path string, handler interface{}) error

	// WithNotFound will set the not found handler for the router
	WithNotFoundHandler(handler interface{}) error
	// WithMethodNotAllowedHandler will set the not allowed handler for the router
	WithMethodNotAllowedHandler(handler interface{}) error
	// WithErrorHandler will set the error handler for the router
	WithErrorHandler(handler interface{}) error
	// WithMiddleware will add a middleware to the router
	WithMiddleware(handler interface{}) error

	// ListenAndServe will start an HTTP webserver on the given address
	ListenAndServe(address string) error
	// ListenAndServeTLS will start an HTTP/S webserver on the given address
	ListenAndServeTLS(address string, certFile string, keyFile string) error
	// Shutdown will gracefully shutdown the router
	Shutdown() error
}