swrv

type ControllerSpec interface {
	// GetPath returns the URL path for the controller.
	GetPath() string

	// GetHandler returns the handler instance for the controller.
	GetHandler() RequestHandler

	// WithRequestFilters appends controller-specific request filters that will be
	// applied to incoming requests after the global request filters set on the
	// parent Server instance.
	WithRequestFilters(filters ...RequestFilter) ControllerSpec

	// GetRequestFilters returns this controller's controller-specific
	// RequestFilter instances.
	GetRequestFilters() []RequestFilter

	// WithResponseFilters appends controller-specific response filters that will
	// be applied to outgoing responses after the global response filters set on
	// the parent Server instance.
	WithResponseFilters(filters ...ResponseFilter) ControllerSpec

	// GetResponseFilters returns this controller's controller-specific
	// ResponseFilter instances.
	GetResponseFilters() []ResponseFilter

	// ForMethods sets the HTTP methods that the built controller will listen for.
	//
	// If set, the controller will only be called for matching HTTP methods.
	//
	// If unset, the controller will be called for any HTTP method.
	ForMethods(methods ...string) ControllerSpec

	// GetMethods returns the list of HTTP methods that the controller will listen
	// for.
	GetMethods() []string

	// GetRequiredHeaders returns the header requirements for this controller.
	//
	// The built controller will only be called for requests containing headers
	// that match the given requirements.
	GetRequiredHeaders() map[string]string

	// WithRequiredHeader sets a header requirement for request matching.  Only
	// requests that contain the given header set to the given value will be
	// matched and forwarded to this controller.
	//
	// If the given value string is empty, the matcher will match any value set
	// on the target header.
	WithRequiredHeader(header, value string) ControllerSpec
}

type ErrorControllerSpec interface {
	// GetHandler returns the handler instance for the controller.
	GetHandler() RequestHandler

	// WithRequestFilters appends controller-specific request filters that will be
	// applied to incoming requests after the global request filters set on the
	// parent Server instance.
	WithRequestFilters(filters ...RequestFilter) ErrorControllerSpec

	// GetRequestFilters returns this controller's controller-specific
	// RequestFilter instances.
	GetRequestFilters() []RequestFilter

	// WithResponseFilters appends controller-specific response filters that will
	// be applied to outgoing responses after the global response filters set on
	// the parent Server instance.
	WithResponseFilters(filters ...ResponseFilter) ErrorControllerSpec

	// GetResponseFilters returns this controller's controller-specific
	// ResponseFilter instances.
	GetResponseFilters() []ResponseFilter
}

type MatcherFn = func(object any) bool

type ObjectSerializer interface {

	// Matches tests whether the given object may be serialized by the current
	// ObjectSerializer.
	//
	// If this method returns true, Serialize will be called on the object and no
	// further ObjectSerializers will be tested.
	Matches(object any) bool

	// Serialize serializes the given object into an io.Reader instance which will
	// be passed to the HTTP client caller.
	Serialize(object any) (io.Reader, error)

	// ContentType returns the content type of the serialized data that this
	// ObjectSerializer returns.
	ContentType() string
}

type Request interface {

	// Raw returns the underling http.Request struct pointer.
	Raw() *http.Request

	// Method returns the HTTP request method used.
	Method() string

	// AdditionalContext returns the RequestContext object attached to this
	// request.
	//
	// Additional context may be used to store arbitrary data along with the
	// incoming request.
	AdditionalContext() RequestContext

	// GetHeader returns the first value associated with the given header name.
	//
	// If no such header was found on the request, the returned string will be
	// empty.
	//
	// This lookup is case-insensitive.
	GetHeader(header string) string

	// GetHeaders returns all the values associated with the given header name.
	//
	// If no such header was found on the request, the returned slice will be
	// empty.
	//
	// This lookup is case-insensitive.
	GetHeaders(header string) []string

	// HasQueryParam tests whether this request was sent with the target query
	// param as part of the URL.
	HasQueryParam(name string) bool

	// GetQueryParam fetches the value for the target query param from the request
	// URL.
	//
	// If the request URL did not contain the target query param, the returned
	// string will be empty.
	GetQueryParam(name string) string

	// GetCookie returns the cookie with the given name.
	//
	// If no such cookie was found, the return value will be nil.
	GetCookie(name string) *http.Cookie

	// HasCookie tests whether this request has the target cookie.
	HasCookie(name string) bool

	// GetCookies returns a slice of all the cookies sent with the request.
	GetCookies() []*http.Cookie

	// URIParam fetches the value of the URI param with the given name.
	//
	// URI params are the parameterized portion of a path set on the parent
	// controller.
	URIParam(name string) string

	// URIParams returns
	URIParams() map[string]string

	// Body returns an io.ReadCloser over the raw request body.
	Body() io.ReadCloser

	// WithBody executes the given function, passing in the request body.
	//
	// The request body will be automatically closed on return of the given
	// function.
	WithBody(fn func(reader io.Reader))

	// MultipartReader returns a MIME multipart reader if this is a
	// multipart/form-data or a multipart/mixed POST request, else returns nil and
	// an error.
	MultipartReader() (*multipart.Reader, error)
}

type RequestContext interface {

	// Has tests whether the RequestContext contains and entry with the given key.
	Has(key string) bool

	// Get returns the value stored at the given key.
	Get(key string) any

	// Put sets the given value into the RequestContext at the given key.
	Put(key string, val any)

	// Len returns the current size of the RequestContext instance.
	Len() int

	// IsEmpty tests whether this RequestContext has a length of 0.
	IsEmpty() bool
}

type RequestFilter interface {

	// FilterRequest may apply changes to the incoming Request's RequestContext,
	// or optionally, halt processing of the Request by returning a non-nil
	// Response.
	//
	// If this method returns a non-nil response, no further RequestFilters will
	// be called, and the RequestHandler will not be reached.  Instead, the Server
	// will return the response provided by this method.
	//
	// If this method returns a nil value, the request will be passed to the next
	// RequestFilter instance registered to either the server or the controller.
	FilterRequest(request Request) Response
}

type RequestFilterFunc func(request Request) Response

type RequestHandler interface {

	// HandleRequest is called to process incoming requests and transform them
	// into Response objects to be returned the HTTP client caller.
	HandleRequest(request Request) Response
}

type RequestHandlerFunc func(request Request) Response

type Response interface {

	// GetCode returns the HTTP status code set on this Response instance.
	//
	// If unset, the Response status code defaults to 200.
	GetCode() int

	// WithCode sets the HTTP status code of the response to the given value.
	//
	// If unset, the Response status code defaults to 200.
	WithCode(code int) Response

	// GetBody returns the body for this Response.
	GetBody() any

	// WithBody sets the body on this Response instance.
	//
	// The body may be any object and, if not an io.Reader, will be passed to the
	// first matching ObjectSerializer registered with the Server.
	//
	// If the body is an io.ReadCloser, the body will be closed automatically by
	// the server after the response has been written to the client.
	WithBody(body any) Response

	// GetHeaders returns the ResponseHeaders attached to this Response instance.
	GetHeaders() ResponseHeaders

	// WithHeader sets the target response header to the given values.
	WithHeader(header, value string, values ...string) Response

	// OnComplete sets a callback function that will be called after the request
	// processing is complete and the response has been sent to the HTTP client.
	OnComplete(fn func()) Response

	// GetOnComplete returns the OnComplete function, if one is present.
	GetOnComplete() func()
}

type ResponseFilter interface {

	// FilterResponse may apply changes to, or replace entirely, the passed
	// Response instance.
	//
	// FilterResponse is expected to always return a response instance.  If it
	// returns nil, the Server will respond with a 500 error.
	FilterResponse(request Request, response Response) Response
}

type ResponseFilterFunc func(request Request, response Response) Response

type ResponseHeaders interface {
	// Set puts the given header value(s) into the header mapping, replacing any
	// value previously set for the target header.
	Set(header, value string, values ...string)

	// Append puts the given header value(s) into the header mapping, appending
	// to any value(s) previously set for the target header.
	Append(header, value string, values ...string)

	// GetFirst returns the first value set for the target header.
	GetFirst(header string) (value string, found bool)

	// GetAll returns all values set for the target header.
	GetAll(header string) (values []string, found bool)

	// GetNth returns the nth value set for the target header.
	GetNth(header string, n int) (value string, found bool)

	// ForEach iterates over all the set headers and calls the given function on
	// each.
	ForEach(fn func(header string, values []string))
}

type Server interface {
	// WithLogger configures the server to use the given logrus logger instance
	// for internal server logging.
	//
	// This will overwrite any value previously set using WithLogger or
	// WithLoggerEntry.
	//
	// Passing nil will cause the server to panic with a nil pointer exception on
	// startup.
	WithLogger(logger *logrus.Logger) Server

	// WithLoggerEntry configures the server to use the given logrus logger entry
	// instance for internal server logging.
	//
	// This will overwrite any value previously set using WithLogger or
	// WithLoggerEntry.
	//
	// Passing nil will cause the server to panic with a nil pointer exception on
	// startup.
	WithLoggerEntry(logger *logrus.Entry) Server

	// WithReadTimeout sets the server's read timeout value to the given duration.
	//
	// If unset, the Server will default to a 30-second timeout.
	WithReadTimeout(timeout time.Duration) Server

	// WithWriteTimeout sets the server's write timeout value to the given
	// duration.
	//
	// If unset, the Server will default to a 30-second timeout.
	WithWriteTimeout(timeout time.Duration) Server

	// WithControllers adds the given ControllerSpec to the Server.
	//
	// When the Server is started, this ControllerSpec will be built into a
	// controller instance that will handle incoming HTTP requests that match the
	// target path and filters.
	WithControllers(controller ControllerSpec) Server

	// WithRequestFilters appends global RequestFilter instances that will be hit
	// for requests to any controller registered with the Server instance.
	//
	// Global RequestFilter instances are applied before controller specific
	// RequestFilter instances.
	WithRequestFilters(filters ...RequestFilter) Server

	// WithResponseFilters appends global ResponseFilter instances that will be
	// hit for outgoing responses from any controller registered with the Server
	// instance.
	//
	// Global ResponseFilter instances are applied after controller specific
	// ResponseFilter instances.
	WithResponseFilters(filters ...ResponseFilter) Server

	// WithObjectSerializers appends ObjectSerializer instances to the Server.
	//
	// ObjectSerializers are used to serialize non-stream objects into values that
	// may be streamed out to the requesting client.
	//
	// If no ObjectSerializer instances are provided, the default ObjectSerializer
	// will be used.  The default ObjectSerializer simply stringifies the object.
	//
	// ObjectSerializers are not applied to Response bodies of type io.Reader.
	//
	// ObjectSerializers will be tested in the order they are appended to the
	// server.  The first matching serializer will be used to serialize a Response
	// body.
	WithObjectSerializers(serializers ...ObjectSerializer) Server

	// With404Controller configures the Server's 404 Not Found controller, that
	// is, the controller that will be called when a client makes a request to an
	// endpoint that is not registered to the Server.
	//
	// Optionally requests to this controller may choose to use the global
	// RequestFilter and ResponseFilter instances like a normal controller.
	With404Controller(useGlobalFilters bool, controller ErrorControllerSpec) Server

	// With405Controller configures the Server's 405 Method Not Allowed
	// controller, that is, the controller that will be called with a client makes
	// a request to an endpoint using an HTTP method that is not supported by that
	// endpoint.
	//
	// Optionally requests to this controller may choose to use the global
	// RequestFilter and ResponseFilter instances like a normal controller.
	With405Controller(useGlobalFilters bool, controller ErrorControllerSpec) Server

	// Start starts the server, binding to the configured port and address,
	// optionally using a given router.
	//
	// If the router parameter is nil, a new router will be initialized for the
	// server.
	//
	// Once a server has started, no new filters, controllers, or serializers may
	// be registered.
	//
	// A server may only be started once.
	//
	// Example: No Router
	//   server := xhttp.NewServer(address, port)
	//   ...
	//   server.Start(nil)
	//
	// Example: With Router
	//
	//   router := mux.NewRouter()
	//   server := xhttp.NewServer(address, port)
	//   ...
	//   server.Start(router)
	Start(router *mux.Router)
}