Help us shape the future of Go! Take the 2026 Go Developer Survey

httpx

package
v0.3.2 Latest Latest
Warning

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

 Go to latest Published: Nov 3, 2026 License: MIT Imports: 16 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 CodeSuccess = CodeOK

CodeSuccess is an alias for CodeOK to maintain compatibility where needed.

Variables

This section is empty.

Functions

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 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 IsProblemJSONEnabled added in v0.3.0 

func IsProblemJSONEnabled() bool

IsProblemJSONEnabled reports whether RFC 9457 Problem Details is enabled.

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 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 UseProblemJSON added in v0.3.0 

func UseProblemJSON(enabled bool)

UseProblemJSON enables or disables RFC 9457 Problem Details (application/problem+json) error responses.

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.

func WithPathPrefix added in v0.2.2 

func WithPathPrefix(prefix string) AdminDashboardOption

WithPathPrefix sets a custom mount path prefix for the debug dashboard (default: "/debug/gorp").

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)
	PathPrefix        string // Mount path prefix (default: "/debug/gorp")
}

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 standard business error carrying canonical Code and domain Reason.

func Aborted added in v0.3.0 

func Aborted(reason, msg string) *BizError

func AlreadyExists added in v0.3.0 

func AlreadyExists(reason, msg string) *BizError

func Cancelled added in v0.3.0 

func Cancelled(reason, msg string) *BizError

func DataLoss added in v0.3.0 

func DataLoss(reason, msg string) *BizError

func DeadlineExceeded added in v0.3.0 

func DeadlineExceeded(reason, msg string) *BizError

func FailedPrecondition added in v0.3.0 

func FailedPrecondition(reason, msg string) *BizError

func Internal added in v0.3.0 

func Internal(msg string) *BizError

func InvalidArgument added in v0.3.0 

func InvalidArgument(reason, msg string) *BizError

Convenient constructors for canonical codes (covers 90%+ business scenarios).

func NewBizError 

func NewBizError(code Code, reason, message string) *BizError

NewBizError creates a new BizError with constructor-level fail-fast verification.

func NotFound 

func NotFound(reason, msg string) *BizError

func OutOfRange added in v0.3.0 

func OutOfRange(reason, msg string) *BizError

func PermissionDenied added in v0.3.0 

func PermissionDenied(reason, msg string) *BizError

func ResourceExhausted added in v0.3.0 

func ResourceExhausted(reason, msg string) *BizError

func Unauthenticated added in v0.3.0 

func Unauthenticated(reason, msg string) *BizError

func Unavailable added in v0.3.0 

func Unavailable(reason, msg string) *BizError

func Unimplemented added in v0.3.0 

func Unimplemented(reason, msg string) *BizError

func Unknown added in v0.3.0 

func Unknown(reason, msg string) *BizError

func (*BizError) Code 

func (e *BizError) Code() Code

func (*BizError) Error 

func (e *BizError) Error() string

func (*BizError) Message 

func (e *BizError) Message() string

func (*BizError) Reason added in v0.3.0 

func (e *BizError) Reason() string

type BusinessError 

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

BusinessError describes an error carrying canonical Code, Reason, and message semantics.

type Code added in v0.3.0 

type Code int

Code represents canonical semantic status codes aligned with gRPC AIP-193. It determines the HTTP transmission status, while business domain semantics use Reason. 

const (
	CodeOK                 Code = 0
	CodeCancelled          Code = 1
	CodeUnknown            Code = 2
	CodeInvalidArgument    Code = 3  // -> 400
	CodeDeadlineExceeded   Code = 4  // -> 504
	CodeNotFound           Code = 5  // -> 404
	CodeAlreadyExists      Code = 6  // -> 409
	CodePermissionDenied   Code = 7  // -> 403
	CodeResourceExhausted  Code = 8  // -> 429
	CodeFailedPrecondition Code = 9  // -> 400
	CodeAborted            Code = 10 // -> 409
	CodeOutOfRange         Code = 11 // -> 400
	CodeUnimplemented      Code = 12 // -> 501
	CodeInternal           Code = 13 // -> 500
	CodeUnavailable        Code = 14 // -> 503
	CodeDataLoss           Code = 15 // -> 500
	CodeUnauthenticated    Code = 16 // -> 401
)

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 Problem added in v0.3.0 

type Problem struct {
	Type   string `json:"type"`
	Title  string `json:"title"`
	Status int    `json:"status"`
	Detail string `json:"detail,omitempty"`
	Reason string `json:"reason,omitempty"`
}

Problem represents an RFC 9457 Problem Details payload (application/problem+json).

type Response 

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

Response is the default 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.