httpx

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 20, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package httpx provides runtime debug admin dashboard endpoints for gorp framework.

Package httpx provides OpenAPI 3.0 route introspection and auto-export capabilities.

Package httpx provides HTTP response helpers and error mappings for gorp framework.

Package httpx provides unified HTTP response and documentation helpers for gorp framework.

Index

Constants

View Source 
const (
	CodeBadRequest         = 400
	CodeUnauthorized       = 401
	CodeForbidden          = 403
	CodeNotFound           = 404
	CodeInternalError      = 500
	CodeServiceUnavailable = 503
	CodeTooManyRequests    = 429
	CodeConflict           = 409
	CodeValidationFailed   = 422
)

Business error code constants.

View Source 
const CodeSuccess = 0

CodeSuccess is the success response code.

Variables

This section is empty.

Functions

func BadRequest 

func BadRequest(c JSONResponder, message string)

BadRequest writes a 400 Bad Request response with a message.

func DashboardHTML added in v0.2.0 

func DashboardHTML(prefix string) string

DashboardHTML returns the self-contained HTML page for the /debug/gorp Web Console.

func Error 

func Error(c JSONResponder, err error)

Error writes an error response, automatically resolving AppError and BizError.

func ErrorWithData 

func ErrorWithData(c JSONResponder, err error, data any)

ErrorWithData writes an error response and attaches extra response data.

func ErrorWithStatus 

func ErrorWithStatus(c JSONResponder, status int, err error)

ErrorWithStatus writes an error response using a caller-provided HTTP status.

func ExportOpenAPI3JSON added in v0.2.0 

func ExportOpenAPI3JSON(engine *gin.Engine, title, version string) string

ExportOpenAPI3JSON converts the Gin routes to formatted OpenAPI 3.0 JSON.

func Fail added in v0.2.0 

func Fail(c JSONResponder, err error)

Fail is an alias for Error.

func Forbidden 

func Forbidden(c JSONResponder, message string)

Forbidden writes a 403 Forbidden response with a message.

func GinSwaggerHandler added in v0.2.0 

func GinSwaggerHandler(specPath string) gin.HandlerFunc

GinSwaggerHandler returns a Gin handler that serves interactive Swagger UI or the spec JSON.

func InternalError 

func InternalError(c JSONResponder, message string)

InternalError writes a 500 Internal Server Error response with a message.

func MountDebugDashboard added in v0.2.0 

func MountDebugDashboard(engine *gin.Engine, container runtimecontract.Container, prefix ...string)

MountDebugDashboard attaches the /debug/gorp developer console and JSON API endpoints to Gin.

func NotFound 

func NotFound(c JSONResponder, message string)

NotFound writes a 404 Not Found response with a message.

func OK added in v0.2.0 

func OK(c JSONResponder, data any)

OK is an alias for Success.

func RegisterAdminDashboard added in v0.2.0 

func RegisterAdminDashboard(engine *gin.Engine, container runtimecontract.Container, pathPrefix string, opts ...AdminDashboardOption)

RegisterAdminDashboard mounts the /debug/gorp Web Admin Console and REST endpoints onto a Gin engine.

func Success 

func Success(c JSONResponder, data any)

Success writes a standard success response.

func SuccessPaginated 

func SuccessPaginated(c JSONResponder, items any, total int64, page, pageSize int)

SuccessPaginated writes a standard paginated success response.

func SuccessWithMessage 

func SuccessWithMessage(c JSONResponder, message string, data any)

SuccessWithMessage writes a success response with a custom message.

func SuccessWithStatus 

func SuccessWithStatus(c JSONResponder, status int, data any)

SuccessWithStatus writes a success response with a custom HTTP status.

func SwaggerUIHTML added in v0.2.0 

func SwaggerUIHTML(specURL, title string) string

SwaggerUIHTML returns a lightweight, self-contained HTML string loading Swagger UI CDN.

func Unauthorized 

func Unauthorized(c JSONResponder, message string)

Unauthorized writes a 401 Unauthorized response with a message.

Types

type AdminDashboardOption added in v0.2.0 

type AdminDashboardOption func(*AdminDashboardOptions)

AdminDashboardOption configures AdminDashboardOptions.

func WithAdminToken added in v0.2.0 

func WithAdminToken(token string) AdminDashboardOption

WithAdminToken sets the required bearer or query token to access the debug dashboard.

func WithAllowInProduction added in v0.2.0 

func WithAllowInProduction(allow bool) AdminDashboardOption

WithAllowInProduction explicitly permits access to the dashboard in gin.ReleaseMode.

type AdminDashboardOptions added in v0.2.0 

type AdminDashboardOptions struct {
	AdminToken        string // If specified, requests must provide Authorization: Bearer <token> or ?token=<token>
	AllowInProduction bool   // If false, /debug/gorp returns 403 Forbidden in release/production mode (default: false)
}

AdminDashboardOptions configures security and behavior of the developer console.

func DefaultAdminDashboardOptions added in v0.2.0 

func DefaultAdminDashboardOptions() AdminDashboardOptions

DefaultAdminDashboardOptions returns default production-safe options.

type BizError 

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

BizError is the default business error implementation.

func NewBizError 

func NewBizError(code int, message string) *BizError

NewBizError creates a new business error with the given code and message.

func (*BizError) Code 

func (e *BizError) Code() int

func (*BizError) Error 

func (e *BizError) Error() string

func (*BizError) Message 

func (e *BizError) Message() string

type BusinessError 

type BusinessError interface {
	error
	Code() int
	Message() string
}

BusinessError describes an error carrying business code and message semantics.

type JSONResponder added in v0.2.0 

type JSONResponder interface {
	JSON(code int, obj any)
}

JSONResponder represents any context capable of rendering a JSON response, seamlessly supporting both *gin.Context and transportcontract.Context.

type OpenAPI3Components added in v0.2.0 

type OpenAPI3Components struct {
	SecuritySchemes map[string]OpenAPI3SecurityScheme `json:"securitySchemes,omitempty"`
}

OpenAPI3Components defines reusable OpenAPI schemas.

type OpenAPI3Document added in v0.2.0 

type OpenAPI3Document struct {
	OpenAPI    string                                  `json:"openapi"`
	Info       OpenAPI3Info                            `json:"info"`
	Paths      map[string]map[string]OpenAPI3Operation `json:"paths"`
	Components *OpenAPI3Components                     `json:"components,omitempty"`
	Security   []map[string][]string                   `json:"security,omitempty"`
}

OpenAPI3Document represents a lightweight OpenAPI 3.0 root document.

func ExportOpenAPI3 added in v0.2.0 

func ExportOpenAPI3(engine *gin.Engine, title, version string) *OpenAPI3Document

ExportOpenAPI3 inspects the Gin engine's routes and auto-generates an OpenAPI 3.0 spec document.

type OpenAPI3Info added in v0.2.0 

type OpenAPI3Info struct {
	Title       string `json:"title"`
	Version     string `json:"version"`
	Description string `json:"description,omitempty"`
}

OpenAPI3Info describes API metadata.

type OpenAPI3Operation added in v0.2.0 

type OpenAPI3Operation struct {
	Summary    string                      `json:"summary"`
	Tags       []string                    `json:"tags,omitempty"`
	Parameters []OpenAPI3Parameter         `json:"parameters,omitempty"`
	Responses  map[string]OpenAPI3Response `json:"responses"`
}

OpenAPI3Operation describes an HTTP operation on a path.

type OpenAPI3Parameter added in v0.2.0 

type OpenAPI3Parameter struct {
	Name     string            `json:"name"`
	In       string            `json:"in"` // path, query, header
	Required bool              `json:"required"`
	Schema   map[string]string `json:"schema"`
}

OpenAPI3Parameter describes a request parameter.

type OpenAPI3Response added in v0.2.0 

type OpenAPI3Response struct {
	Description string `json:"description"`
}

OpenAPI3Response describes an API response.

type OpenAPI3SecurityScheme added in v0.2.0 

type OpenAPI3SecurityScheme struct {
	Type         string `json:"type"`
	Scheme       string `json:"scheme,omitempty"`
	BearerFormat string `json:"bearerFormat,omitempty"`
}

OpenAPI3SecurityScheme defines security schemes such as Bearer JWT.

type PaginatedData 

type PaginatedData struct {
	Items    any   `json:"items"`
	Total    int64 `json:"total"`
	Page     int   `json:"page"`
	PageSize int   `json:"page_size"`
}

PaginatedData is the standard pagination payload shape.

type Response 

type Response struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    any    `json:"data,omitempty"`
}

Response is the standard HTTP response envelope used by the framework.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.