response.go

package servekit

import (
	"context"
	"encoding/json"
	"errors"
	"net/http"
	"strings"
)

// ResponseEncoder writes successful responses for Handle.
//
// Returning an error passes control to the server ErrorEncoder. Implementations
// should avoid committing a success status or body before returning an error
// whenever practical. Once a success response has been committed, the
// ErrorEncoder may no longer be able to replace it with an error response.
type ResponseEncoder func(http.ResponseWriter, *http.Request, any) error

// ErrorEncoder writes error responses for Handle.
//
// The returned error is ignored by Servekit, so implementations should treat
// best-effort response writes as terminal. If the response has already been
// committed by an earlier writer, an ErrorEncoder may not be able to change the
// status code or replace the response body.
type ErrorEncoder func(http.ResponseWriter, *http.Request, error) error

// JSONResponse returns the default success encoder for Handle.
//
// A nil payload writes HTTP 204 No Content with no body. A non-nil payload
// writes HTTP 200 with Content-Type application/json and body shape
// {"data": <payload>}. JSONResponse serializes the complete response before
// committing HTTP 200 so Handle can delegate serialization failures to the
// server ErrorEncoder.
func JSONResponse() ResponseEncoder {
	return func(w http.ResponseWriter, _ *http.Request, payload any) error {
		if payload == nil {
			w.WriteHeader(http.StatusNoContent)
			return nil
		}
		body, err := json.Marshal(map[string]any{"data": payload})
		if err != nil {
			return err
		}
		body = append(body, '\n')
		w.Header().Set("Content-Type", "application/json")
		w.WriteHeader(http.StatusOK)
		_, err = w.Write(body)
		return err
	}
}

// JSONError returns the default error encoder for Handle.
//
// JSONError maps HTTPError values and pointers to their usable final StatusCode,
// maps context cancellation and deadline errors to HTTP 504, and otherwise
// returns HTTP 500. The payload shape is {"error": "..."} and includes
// request_id when one is present in the request context.
func JSONError() ErrorEncoder {
	return func(w http.ResponseWriter, r *http.Request, err error) error {
		status := statusFromError(err)
		return writeDefaultJSONError(w, status, clientErrorMessage(err, status), RequestIDFromContext(r.Context()))
	}
}

func clientErrorMessage(err error, status int) string {
	if httpErr, ok := asHTTPError(err); ok {
		if httpErr == nil {
			return defaultClientErrorMessage(status)
		}
		if httpErr.Message != "" {
			return httpErr.Message
		}
		if httpErr.StatusCode > 0 && !validHTTPErrorStatus(httpErr.StatusCode) {
			return defaultClientErrorMessage(status)
		}
	}
	var maxBytesErr *http.MaxBytesError
	if errors.As(err, &maxBytesErr) {
		return "request body too large"
	}
	switch {
	case errors.Is(err, context.DeadlineExceeded):
		return "request timed out"
	case errors.Is(err, context.Canceled):
		return "request canceled"
	}
	return defaultClientErrorMessage(status)
}

func defaultClientErrorMessage(status int) string {
	if text := http.StatusText(status); text != "" {
		return strings.ToLower(text)
	}
	return "error"
}

func writeDefaultJSONError(w http.ResponseWriter, status int, message, requestID string) error {
	body := map[string]any{"error": message}
	if requestID != "" {
		body["request_id"] = requestID
	}
	h := w.Header()
	h.Del("Content-Length")
	h.Set("Content-Type", "application/json")
	w.WriteHeader(status)
	return json.NewEncoder(w).Encode(body)
}