Add Extracter, Validator, StatusSetter, and RawWriter interfaces to xapi package

- Introduced interfaces for extracting request data, validating requests, setting custom status codes, and writing raw responses.
- Updated Endpoint handler to utilize these new interfaces for improved request handling and response customization.
- Updatedexample tests to demonstrate usage of the new features, including custom response writing and request validation.

Author: Ravi Atluri

xapi/endpoint.go

@@ -19,6 +19,28 @@ func (e EndpointFunc[TReq, TRes]) Handle(ctx context.Context, req *TReq) (*TRes,
 	return e(ctx, req)
 }
 
+// Extracter allows extracting additional data - headers, query params, etc.
+// from the HTTP request.
+type Extracter interface {
+	Extract(r *http.Request) error
+}
+
+// Validator allows validating endpoint requests.
+type Validator interface {
+	Validate() error
+}
+
+// StatusSetter allows setting a custom HTTP status code of the response.
+type StatusSetter interface {
+	StatusCode() int
+}
+
+// RawWriter allows writing raw data to the HTTP response instead of
+// the default JSON encoder.
+type RawWriter interface {
+	Write(w http.ResponseWriter) error
+}
+
 // Endpoint represents a type-safe HTTP endpoint with middleware and error handling.
 type Endpoint[TReq, TRes any] struct {
 	handler EndpointHandler[TReq, TRes]
@@ -46,9 +68,21 @@ func NewEndpoint[TReq, TRes any](handler EndpointHandler[TReq, TRes], opts ...En
 func (e *Endpoint[TReq, TRes]) Handler() http.Handler {
 	h := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		var req TReq
-		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
-			e.opts.errorHandler.HandleError(w, err)
-			return
+
+		if r.Body != nil {
+			if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+				e.opts.errorHandler.HandleError(w, err)
+				return
+			}
+
+			defer r.Body.Close()
+		}
+
+		if validator, ok := any(&req).(Validator); ok {
+			if err := validator.Validate(); err != nil {
+				e.opts.errorHandler.HandleError(w, err)
+				return
+			}
 		}
 
 		res, err := e.handler.Handle(r.Context(), &req)
@@ -57,6 +91,24 @@ func (e *Endpoint[TReq, TRes]) Handler() http.Handler {
 			return
 		}
 
+		if rawWriter, ok := any(res).(RawWriter); ok {
+			if err := rawWriter.Write(w); err != nil {
+				e.opts.errorHandler.HandleError(w, err)
+				return
+			}
+
+			return
+		}
+
+		statusCode := http.StatusOK
+
+		if statusSetter, ok := any(res).(StatusSetter); ok {
+			statusCode = statusSetter.StatusCode()
+		}
+
+		w.Header().Set("Content-Type", "application/json; charset=utf-8")
+		w.WriteHeader(statusCode)
+
 		if err := json.NewEncoder(w).Encode(res); err != nil {
 			e.opts.errorHandler.HandleError(w, err)
 			return

xapi/example_test.go

@@ -10,25 +10,47 @@ import (
 	"github.com/gojekfarm/xtools/xapi"
 )
 
-func ExampleEndpoint_basic() {
-	type CreateUserRequest struct {
-		Name  string `json:"name"`
-		Email string `json:"email"`
-	}
+type CreateUserRequest struct {
+	Name     string `json:"name"`
+	Email    string `json:"email"`
+	Language string `json:"-"`
+}
 
-	type CreateUserResponse struct {
-		ID    int    `json:"id"`
-		Name  string `json:"name"`
-		Email string `json:"email"`
+func (user *CreateUserRequest) Validate() error {
+	if user.Name == "" {
+		return fmt.Errorf("name is required")
 	}
+	if user.Email == "" {
+		return fmt.Errorf("email is required")
+	}
+	return nil
+}
 
+func (user *CreateUserRequest) Extract(r *http.Request) error {
+	user.Language = r.Header.Get("Language")
+	return nil
+}
+
+type CreateUserResponse struct {
+	ID       int    `json:"id"`
+	Name     string `json:"name"`
+	Email    string `json:"email"`
+	Language string `json:"language"`
+}
+
+func (user *CreateUserResponse) StatusCode() int {
+	return http.StatusCreated
+}
+
+func ExampleEndpoint_basic() {
 	createUser := xapi.EndpointFunc[CreateUserRequest, CreateUserResponse](
 		func(ctx context.Context, req *CreateUserRequest) (*CreateUserResponse, error) {
 			// Simulate user creation logic
 			return &CreateUserResponse{
-				ID:    1,
-				Name:  req.Name,
-				Email: req.Email,
+				ID:       1,
+				Name:     req.Name,
+				Email:    req.Email,
+				Language: req.Language,
 			}, nil
 		},
 	)
@@ -148,3 +170,44 @@ func ExampleEndpoint_withMiddleware() {
 
 	http.Handle("/data", endpoint.Handler())
 }
+
+type GetArticleRequest struct {
+	ID string `json:"-"`
+}
+
+func (article *GetArticleRequest) Extract(r *http.Request) error {
+	article.ID = r.PathValue("id")
+
+	return nil
+}
+
+type GetArticleResponse struct {
+	ID    string `json:"id"`
+	Title string `json:"title"`
+}
+
+func (article *GetArticleResponse) Write(w http.ResponseWriter) error {
+	w.Header().Set("Content-Type", "application/html")
+	w.WriteHeader(http.StatusOK)
+
+	_, _ = fmt.Fprintf(w, "<html><body><h1>%s</h1></body></html>", article.Title)
+
+	return nil
+}
+
+func ExampleEndpoint_withCustomResponseWriter() {
+	getArticle := xapi.EndpointFunc[GetArticleRequest, GetArticleResponse](
+		func(ctx context.Context, req *GetArticleRequest) (*GetArticleResponse, error) {
+			return &GetArticleResponse{
+				ID:    req.ID,
+				Title: "Article " + req.ID,
+			}, nil
+		},
+	)
+
+	endpoint := xapi.NewEndpoint(getArticle)
+
+	http.Handle("/articles/{id}", endpoint.Handler())
+	log.Println("Server starting on :8080")
+	log.Fatal(http.ListenAndServe(":8080", nil))
+}