httpkit

type AccessLog struct {
	Next http.Handler

	AdditionalLoggingDetail func(w http.ResponseWriter, r *http.Request) logging.Detail
}

type ClientErrUnexpectedResponse struct {
	StatusCode int
	Body       string
	URL        *url.URL

	RequestMethod string
	RequestURL    *url.URL
}

type ErrorHandler interface {
	HandleError(w http.ResponseWriter, r *http.Request, err error)
}

type FormURLEncodedCodec struct{}

type IDContextKey[ENT, ID any] struct{}

type IDConverter[ID any] struct {
	Format func(ID) (string, error)
	Parse  func(string) (ID, error)
}

type IDInContext[CtxKey, EntityIDType any] struct{}

type IntID[ID ~int] struct{}

type Mapper[ENT any] interface {
	// contains filtered or unexported methods
}

type MediaTypeCodecs map[mediatype.MediaType]codec.Codec

type MediaTypeMappings[ENT any] map[mediatype.MediaType]dtokit.Mapper[ENT]

type MiddlewareFactoryFunc func(next http.Handler) http.Handler

type Multiplexer interface {
	Handle(pattern string, handler http.Handler)
}

type PathInfo struct {
	Method string `enum:"ALL,POST,GET,PUT,PATCH,DELETE,"`
	Path   string
	Desc   string
}

type RESTClient[ENT, ID any] struct {
	// BaseURL [required] is the url base that the rest client will use to access the remote resource.
	BaseURL string
	// HTTPClient [optional] will be used to make the http requests from the rest client.
	//
	// default: httpkit.DefaultRestClientHTTPClient
	HTTPClient *http.Client
	// MediaType [optional] is used in the related headers such as Content-Type and Accept.
	//
	// default: httpkit.DefaultCodec.MediaType
	MediaType mediatype.MediaType
	// Mapping [optional] is used if the ENT must be mapped into a DTO type prior to serialization.
	//
	// default: ENT type is used as the DTO type.
	Mapping dtokit.Mapper[ENT]
	// Codec [optional] is used for the serialization process with DTO values.
	//
	// default: DefaultCodecs will be used to find a matching codec for the given media type.
	Codec codec.Codec
	// MediaTypeCodecs [optional] is a registry that helps choose the right codec for each media type.
	//
	// default: DefaultCodecs
	MediaTypeCodecs MediaTypeCodecs
	// IDFormatter [optional] is used to format the ID value into a string format that can be part of the request path.
	//
	// default: httpkit.IDFormatter[ID].Format
	IDFormatter func(ID) (string, error)
	// IDA [optional] is the ENT's ID accessor helper, to describe how to look up the ID field in a ENT.
	//
	// default: extid.Lookup[ID, ENT]
	IDA extid.Accessor[ENT, ID]
	// WithContext [optional] allows you to add data to the context for requests.
	// If you need to select a RESTful subresource and return it as a RestClient,
	// you can use this function to add the selected resource's path parameter
	// to the context using httpkit.WithPathParam.
	//
	// default: ignored
	WithContext func(context.Context) context.Context
	// PrefetchLimit is used when a methor requires fetching entities ahead.
	// If set to -1, then prefetch is disabled.
	//
	// default: 20
	PrefetchLimit int
	// BodyReadLimit is the read limit in bytes of how much response body is accepted from the server.
	// When set to -1, it accepts indifinitelly.
	//
	// default: DefaultBodyReadLimit
	BodyReadLimit int
	// DisableStreaming switches off the streaming behaviour in results processing,
	// meaning the entire response body of the RESTful API is loaded at once, rather than bit by bit.
	// By enabling DisableStreaming, you load everything into memory upfront and can close the response connection faster.
	//
	// However, this increases memory usage and stops you from handling a very long JSON stream.
	// In return, it could reduce the number of open connections, helping ease the server’s load.
	//
	// This is useful for situations:
	//   - where slowwer servers might feel overwhelmed with holding connections concurrently open (lik ruby's unicorn server)
	//   - when the server incorrect mistake the streaming based request processing as a slow-client attack.
	//
	// default: false
	DisableStreaming bool
}

type RESTHandler[ENT, ID any] struct {
	// Create will create a new entity in the restful resource.
	// Create is a collection endpoint.
	// 		POST /
	Create func(ctx context.Context, ptr *ENT) error
	// Index will return the entities, optionally filtered with the query argument.
	// Index is a collection endpoint.
	//		GET /
	Index func(ctx context.Context) (iter.Seq2[ENT, error], error)
	// Show will return a single entity, looked up by its ID.
	// Show is a resource endpoint.
	// 		GET /:id
	Show func(ctx context.Context, id ID) (ent ENT, found bool, err error)
	// Update will update/replace an entity with the new state.
	// Update is a resource endpoint.
	// 		PUT   /:id - update/replace
	// 		PATCH /:id - partial update (WIP)
	Update func(ctx context.Context, ptr *ENT) error
	// Destroy will delete an entity, identified by its id.
	// Destroy is a resource endpoint.
	// 		 Delete /:id
	Destroy func(ctx context.Context, id ID) error
	// DestroyAll will delete all entity.
	// DestroyAll is a collection endpoint
	// 		 Delete /
	DestroyAll func(ctx context.Context) error
	// ResourceRoutes field is an http.Handler that will receive resource-specific requests.
	// ResourceRoutes field is optional.
	// ResourceRoutes are resource endpoints.
	//
	// The http.Request.Context will contain the parsed ID from the request path,
	// and can be accessed with the IDContextKey.
	//
	// Example paths
	// 		/plural-resource-identifier-name/:id/sub-routes
	// 		/users/42/status
	// 		/users/42/jobs/13
	//
	// Request paths will be stripped from their prefix.
	// For example, "/users/42/jobs" will end up as "/jobs".
	ResourceRoutes http.Handler
	// Mapping [optional] is the generic ENT to DTO mapping configuration.
	//
	// default: the ENT type itself is used as the DTO type.
	Mapping dtokit.Mapper[ENT]
	// MediaType [optional] configures what MediaType the handler should use, when the request doesn't defines it.
	//
	// default: DefaultCodec.MediaType
	MediaType mediatype.MediaType
	// MediaTypeMappings [optional] defines a per MediaType DTO Mapping,
	// that takes priority over the Mapping.
	//
	// default: Mapping is used.
	MediaTypeMappings MediaTypeMappings[ENT]
	// MediaTypeCodecs [optional] contains per media type related codec which is used to marshal and unmarshal data in the response and response body.
	//
	// default: will use httpkit.DefaultCodecs
	MediaTypeCodecs MediaTypeCodecs
	// ErrorHandler [optional] is used to handle errors from the request, by mapping the error value into an error DTO Mapping.
	ErrorHandler ErrorHandler
	// IDContextKey is an optional field used to store the parsed ID from the URL in the context.
	//
	// default: IDContextKey[ENT, ID]{}
	IDContextKey any
	// IDParser [optional] is the ID converter which is used to parse the ID value from the request path.
	//
	// default: IDConverter[ID]{}.ParseID(rawID)
	IDParser func(string) (ID, error)
	// IDAccessor [optional] tells how to look up or set the ENT's ID.
	//
	// Default: extid.Lookup / extid.Set
	IDAccessor extid.Accessor[ENT, ID]
	// BodyReadLimit is the max bytes that the handler is willing to read from the request body.
	// If BodyReadLimit set to -1, then body io reading is not limited.
	//
	// default: DefaultBodyReadLimit, which is preset to 16MB.
	BodyReadLimit iokit.ByteSize
	// CollectionContext is called when a collection endpoint is called.
	//
	// applies to:
	// 	- CREATE
	// 	- INDEX
	CollectionContext func(context.Context) (context.Context, error)
	// ResourceContext is called when a resource endpoint is called.
	//
	// applies to:
	// 	- SHOW
	// 	- UPDATE
	// 	- DESTORY
	// 	- sub routes
	ResourceContext func(context.Context, ID) (context.Context, error)
	// Filters [optional]
	//
	// Filters allow the definition of client side requested server side response filtering.
	// Such as limiting the results of the Index endpoint by query parameters.
	// This approach enables efficient retrieval of specific subsets of resources
	// without requiring the client to fetch and process the entire collection.
	Filters []func(context.Context, ENT) bool
	// ScopeAware flags the RESTHandler that is is aware of the REST scope, such as being a nested resource.
	//   > RESTHandler[Note, NoteID] that is a subresource of a RESTHandler[User, UserID]
	//   > /users/:user_id/notes -> accessed notes should belong to a given :user_id only.
	//
	// If the current handler is not ScopeAware, then we assume so does its REST methods,
	// and when the RESTHandler used as a subresource ("/users/:user_id/notes"),
	// to avoid unwanted consequences, the DestroyAll operation will be either disabled or replaced with a sequenced of deletion using a scoped id list.
	//
	// Additionally, the Destroy operation is also disabled
	// unless the Show command is used to retrieve the ENT for validation with Constraint.
	ScopeAware bool
	// DisableOwnershipConstraint will disable the ownership check when the RESTHandler is in a sub-resource scope.
	DisableOwnershipConstraint bool
	// CommitManager [WIP]
	//
	// CommitManager is meant to make the API interaction transactional.
	CommitManager comproto.OnePhaseCommitProtocol
}

type RestClientCodec interface {
	codec.Codec
	codec.ListDecoderMaker
}

type RetryRoundTripper struct {
	// Transport specifies the mechanism by which individual
	// HTTP requests are made.
	//
	// Default: http.DefaultTransport
	Transport http.RoundTripper
	// RetryStrategy will be used to evaluate if a new retry attempt should be done.
	//
	// Default: retry.ExponentialBackoff
	RetryStrategy resilience.RetryPolicy[resilience.FailureCount]
	// OnStatus is an [OPTIONAL] configuration field that could contain whether a certain http status code should be retried or not.
	// The RetryRoundTripper has a default behaviour about which status code can be retried, and this option can override that.
	OnStatus map[int]bool
}

type RoundTripperFactoryFunc func(next http.RoundTripper) http.RoundTripper

type RoundTripperFunc func(request *http.Request) (*http.Response, error)

type RouteInfo []PathInfo

type RouteInformer interface {
	RouteInfo() RouteInfo
}

type Router struct {
	// contains filtered or unexported fields
}

type StringID[ID ~string] struct{}