response.go

package restapi

import "github.com/gin-gonic/gin"

// WriteResponse writes body as a JSON response to c with the given HTTP
// status. The write is a no-op if:
//   - c is nil, or
//   - the response has already been written (c.Writer.Written() is true).
//
// When abort is true, the middleware chain is terminated after the write; the
// call is equivalent to [gin.Context.AbortWithStatusJSON] (or
// [gin.Context.AbortWithStatus] when body is nil). When abort is false, the
// chain continues; the call is equivalent to [gin.Context.JSON] (or
// [gin.Context.Status] when body is nil).
func (a *API) WriteResponse(c *gin.Context, statusCode int, abort bool, body *ResponseBody) {
	if c == nil || c.Writer.Written() {
		return
	}

	if abort {
		if body == nil {
			c.AbortWithStatus(statusCode)
			return
		}
		c.AbortWithStatusJSON(statusCode, body)
		return
	}

	if body == nil {
		c.Status(statusCode)
		c.Writer.WriteHeaderNow()
		return
	}
	c.JSON(statusCode, body)
}

// Success writes a successful response with data as the envelope Data field.
// Additional options allow setting pagination and extra errors.
func (a *API) Success(c *gin.Context, statusCode int, data any, opts ...ResponseBodyOption) {
	body := &ResponseBody{Data: data}
	for _, opt := range opts {
		if opt != nil {
			opt(body)
		}
	}
	a.WriteResponse(c, statusCode, false, body)
}

// SuccessBody writes a caller-supplied [ResponseBody] as a successful
// response. It is the escape hatch for exotic envelopes.
func (a *API) SuccessBody(c *gin.Context, statusCode int, body *ResponseBody) {
	a.WriteResponse(c, statusCode, false, body)
}

// Error writes an error response whose HTTP status and default message come
// from the registry entry for errorCode. The middleware chain continues.
func (a *API) Error(c *gin.Context, errorCode int, opts ...ErrorOption) {
	entry, _ := a.registry.Lookup(errorCode)
	errorResponse := buildErrorResponse(entry, opts...)
	a.WriteResponse(c, entry.StatusCode, false, &ResponseBody{Errors: []ErrorResponse{errorResponse}})
}

// ErrorBody writes a caller-supplied [ResponseBody] as an error response at
// the given HTTP status. The middleware chain continues.
func (a *API) ErrorBody(c *gin.Context, statusCode int, body *ResponseBody) {
	a.WriteResponse(c, statusCode, false, body)
}

// Abort writes an error response whose HTTP status and default message come
// from the registry entry for errorCode, and terminates the middleware chain.
func (a *API) Abort(c *gin.Context, errorCode int, opts ...ErrorOption) {
	entry, _ := a.registry.Lookup(errorCode)
	errorResponse := buildErrorResponse(entry, opts...)
	a.WriteResponse(c, entry.StatusCode, true, &ResponseBody{Errors: []ErrorResponse{errorResponse}})
}

// AbortBody writes a caller-supplied [ResponseBody] as an error response at
// the given HTTP status and terminates the middleware chain.
func (a *API) AbortBody(c *gin.Context, statusCode int, body *ResponseBody) {
	a.WriteResponse(c, statusCode, true, body)
}

// WriteResponse calls Default().WriteResponse.
func WriteResponse(c *gin.Context, statusCode int, abort bool, body *ResponseBody) {
	Default().WriteResponse(c, statusCode, abort, body)
}

// Success calls Default().Success.
func Success(c *gin.Context, statusCode int, data any, opts ...ResponseBodyOption) {
	Default().Success(c, statusCode, data, opts...)
}

// SuccessBody calls Default().SuccessBody.
func SuccessBody(c *gin.Context, statusCode int, body *ResponseBody) {
	Default().SuccessBody(c, statusCode, body)
}

// Error calls Default().Error.
func Error(c *gin.Context, errorCode int, opts ...ErrorOption) {
	Default().Error(c, errorCode, opts...)
}

// ErrorBody calls Default().ErrorBody.
func ErrorBody(c *gin.Context, statusCode int, body *ResponseBody) {
	Default().ErrorBody(c, statusCode, body)
}

// Abort calls Default().Abort.
func Abort(c *gin.Context, errorCode int, opts ...ErrorOption) {
	Default().Abort(c, errorCode, opts...)
}

// AbortBody calls Default().AbortBody.
func AbortBody(c *gin.Context, statusCode int, body *ResponseBody) {
	Default().AbortBody(c, statusCode, body)
}