restapi

type BeforeHook http.HandlerFunc

type Client[Entity, ID any] struct {
	BaseURL     string
	HTTPClient  *http.Client
	MIMEType    MIMEType
	Mapping     Mapping[Entity]
	Serializer  Serializer
	IDConverter idConverter[ID]
	LookupID    crud.LookupIDFunc[Entity, ID]
}

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

type CreateOperation[Entity, ID, DTO any] struct {
	BeforeHook BeforeHook
}

type DTOMapping[Entity, DTO any] struct{}

type DeleteOperation[Entity, ID, DTO any] struct {
	BeforeHook BeforeHook
}

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

type GenericListEncoder[T any] struct {
	W       io.Writer
	Marshal func(v []T) ([]byte, error)
	// contains filtered or unexported fields
}

type Handler[Entity, ID, DTO any] struct {
	// Resource is the CRUD Resource object that we wish to expose as a restful API resource.
	Resource crud.ByIDFinder[Entity, ID]
	// Mapping takes care mapping back and forth Entity into a DTOMapping, and ID into a string.
	// ID needs mapping into a string because it is used as part of the restful paths.
	Mapping OldMapping[Entity, ID, DTO]
	// ErrorHandler is used to handle errors from the request, by mapping the error value into an error DTOMapping.
	ErrorHandler ErrorHandler
	// Router is the sub-router, where you can define routes related to entity related paths
	//  > .../:id/sub-routes
	Router *Router
	// BodyReadLimit is the max bytes that the handler is willing to read from the request body.
	//
	// The default value is DefaultBodyReadLimit, which is preset to 16MB.
	BodyReadLimit int

	Operations[Entity, ID, DTO]

	// NoCreate will instruct the handler to not expose the `POST /` endpoint
	NoCreate bool
	// NoIndex will instruct the handler to not expose the `Get /` endpoint
	NoIndex bool
	// NoShow will instruct the handler to not expose the `Get /:id` endpoint
	NoShow bool
	// NoUpdate will instruct the handler to not expose the `PUT /:id` endpoint
	NoUpdate bool
	// NoDelete will instruct the handler to not expose the `DELETE /:id` endpoint
	NoDelete bool
}

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

type IDInContext[CtxKey, EntityIDType any] struct{}

type IndexOperation[Entity, ID, DTO any] struct {
	BeforeHook BeforeHook
	Override   func(r *http.Request) iterators.Iterator[Entity]
}

type IntID[ID ~int] struct{}

type JSONSerializer struct{}

type JSONStreamSerializer struct{}

type ListDecoder interface {
	Decode(ptr any) error
	// Next will ensure that Value returns the next item when executed.
	// If the next value is not retrievable, Next should return false and ensure Err() will return the error cause.
	Next() bool
	// Err return the error cause.
	Err() error
	// Closer is required to make it able to cancel iterators where resources are being used behind the scene
	// for all other cases where the underling io is handled on a higher level, it should simply return nil
	io.Closer
}

type ListEncoder interface {
	// Encode will encode an Entity in the underlying io writer.
	Encode(v any) error
	// Closer represent the finishing of the List encoding process.
	io.Closer
}

type MIMEType string

type Mapping[Entity any] interface {
	// contains filtered or unexported methods
}

type OldMapping[Entity, ID, DTO any] interface {
	LookupID(Entity) (ID, bool)
	SetID(*Entity, ID)

	FormatID(ID) (string, error)
	ParseID(string) (ID, error)

	ContextWithID(context.Context, ID) context.Context
	ContextLookupID(ctx context.Context) (ID, bool)

	MapEntity(context.Context, DTO) (Entity, error)
	MapDTO(context.Context, Entity) (DTO, error)
}

type Operations[Entity, ID, DTO any] struct {
	// Index is an OPTIONAL field if you wish to customise the index operation's behaviour
	//   GET /
	//
	Index IndexOperation[Entity, ID, DTO]
	// Create is an OPTIONAL field if you wish to customise the create operation's behaviour
	//   POST /
	//
	Create CreateOperation[Entity, ID, DTO]
	// Show is an OPTIONAL field if you wish to customise the show operation's behaviour
	//   GET /:id
	//
	Show ShowOperation[Entity, ID, DTO]
	// Update is an OPTIONAL field if you wish to customise the update operation's behaviour
	//   PUT /:id
	//   PATCH /:id
	//
	Update UpdateOperation[Entity, ID, DTO]
	// Delete is an OPTIONAL field if you wish to customise the delete operation's behaviour
	//   DELETE /:id
	//
	Delete DeleteOperation[Entity, ID, DTO]
}

type Path = string

type Resource[Entity, ID any] struct {
	// Create will create a new entity in the restful resource.
	// 		POST /
	Create func(ctx context.Context, ptr *Entity) error
	// Index will return the entities, optionally filtered with the query argument.
	//		GET /
	Index func(ctx context.Context, query url.Values) (iterators.Iterator[Entity], error)
	// Show will return a single entity, looked up by its ID.
	// 		GET /:id
	Show func(ctx context.Context, id ID) (ent Entity, found bool, err error)
	// Update will update/replace an entity with the new state.
	// 		PUT   /:id - update/replace
	// 		PATCH /:id - partial update (WIP)
	Update func(ctx context.Context, id ID, ptr *Entity) error
	// Destroy will delete an entity, identified by its id.
	// 		 Delete /:id
	Destroy func(ctx context.Context, id ID) error

	// DestroyAll will delete all entity.
	// 		 Delete /
	DestroyAll func(ctx context.Context, query url.Values) error

	// Serialization is responsible to serialise a DTO into or out from the right serialisation format.
	// Most format is supported out of the box, but in case you want to configure your own,
	// you can do so using this config.
	Serialization ResourceSerialization[Entity, ID]

	// Mapping is responsible to map a given entity to a given DTO
	Mapping ResourceMapping[Entity]

	// ErrorHandler is used to handle errors from the request, by mapping the error value into an error DTOMapping.
	ErrorHandler ErrorHandler

	// IDContextKey is an optional field used to store the parsed ID from the URL in the context.
	//
	// Default: IDContextKey[Entity, ID]{}
	IDContextKey any

	// EntityRoutes is an http.Handler that will receive entity related requests.
	// 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/entity-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".
	EntityRoutes http.Handler

	// BodyReadLimitByteSize is the max bytes that the handler is willing to read from the request body.
	//
	// The default value is DefaultBodyReadLimit, which is preset to 16MB.
	BodyReadLimitByteSize int
}

type ResourceMapping[Entity any] struct {
	// Mapping is the primary entity to DTO mapping configuration.
	Mapping Mapping[Entity]
	// ForMIME defines a per MIMEType restapi.Mapping, that takes priority over Mapping
	ForMIME map[MIMEType]Mapping[Entity]
}

type ResourceSerialization[Entity, ID any] struct {
	Serializers map[MIMEType]Serializer
	IDConverter idConverter[ID]
}

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

type Routes map[Path]http.Handler

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

type SerializerDefault struct {
	Serializer Serializer
	MIMEType   MIMEType
}

type SetIDByExtIDTag[Entity, ID any] struct{}

type ShowOperation[Entity, ID, DTO any] struct {
	BeforeHook BeforeHook
}

type StringID[ID ~string] struct{}

type UpdateOperation[Entity, ID, DTO any] struct {
	BeforeHook BeforeHook
}