httpz

package module
v1.3.1 Latest Latest
Warning

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

 Go to latest Published: Jan 27, 2025 License: MIT Imports: 15 Imported by: 1

README

Logo

httpz v1.0.0 is release, its API is stable.

简体中文

httpz is not a new framework but rather an enhancement library for net/http. When you use httpz, you’re essentially working with the net/http standard library. Its goal is to address the usability gap in net/http 1.22, which, despite its improved routing capabilities, remains less convenient compared to frameworks like Echo and chi.

Key Features:

  • Built on net/http version 1.22+
  • Global error handling
  • Convenient grouping
  • Middleware adopted from chi
  • Data binding adopted from Echo
  • Easy response shortcuts

httpz is fully compatible with net/http. You can choose to leverage the enhanced features of httpz or stick to using plain net/http directly.

Quick Start

1.Installation

To install httpz, Go 1.22 or higher is required.

go get github.com/aeilang/httpz

2.Hello World

import (
	"net/http"

	"github.com/aeilang/httpz"
	"github.com/aeilang/httpz/middleware"
)

func main() {
	// Create a new mux
	mux := httpz.NewServeMux()

	// add logger middleware, it 's copy from chi/middleware
	mux.Use(middleware.Logger)

	// register a GET /hello route
	// GET /hello
	mux.Get("/hello", func(w http.ResponseWriter, r *http.Request) error {
		// rw is a helper responsewriter to send response
		rw := httpz.NewHelperRW(w)
		return rw.String(http.StatusOK, "hello httpz")
		
		// or you can write it by yourself.
		// hw.Header().Set("Content-Type", "text/plain; charset=UTF-8")
		// hw.WriteHeader(http.StatusOK)
		// hw.Write([]byte("hello httpz"))
		// return nil
	})
  
  // just like net/http's ServerMux
	http.ListenAndServe(":8080", mux)
}

the middleware package is copied from chi/middleware.

The complete example can be found in the _example directory

Benchmark

Generated by Go web framework benchmark:

benchmark

For detailed benchmark results, please refer to benchmark.

Feel free to contribute your code.

  • test

  • example

  • middleware

  • other

Documentation

Index

Constants

View Source 
const (
	// MIMEApplicationJSON JavaScript Object Notation (JSON) https://www.rfc-editor.org/rfc/rfc8259
	MIMEApplicationJSON                  = "application/json"
	MIMEApplicationJavaScript            = "application/javascript"
	MIMEApplicationJavaScriptCharsetUTF8 = MIMEApplicationJavaScript + "; " + charsetUTF8
	MIMEApplicationXML                   = "application/xml"
	MIMEApplicationXMLCharsetUTF8        = MIMEApplicationXML + "; " + charsetUTF8
	MIMETextXML                          = "text/xml"
	MIMETextXMLCharsetUTF8               = MIMETextXML + "; " + charsetUTF8
	MIMEApplicationForm                  = "application/x-www-form-urlencoded"
	MIMEApplicationProtobuf              = "application/protobuf"
	MIMEApplicationMsgpack               = "application/msgpack"
	MIMETextHTML                         = "text/html"
	MIMETextHTMLCharsetUTF8              = MIMETextHTML + "; " + charsetUTF8
	MIMETextPlain                        = "text/plain"
	MIMETextPlainCharsetUTF8             = MIMETextPlain + "; " + charsetUTF8
	MIMEMultipartForm                    = "multipart/form-data"
	MIMEOctetStream                      = "application/octet-stream"
	MIMETextEventStream                  = "text/event-stream"
	MIMEXNDJSON                          = "application/x-ndjson"
)

MIME types

View Source 
const (

	// PROPFIND Method can be used on collection and property resources.
	PROPFIND = "PROPFIND"
	// REPORT Method can be used to get information about a resource, see rfc 3253
	REPORT = "REPORT"
	// RouteNotFound is special method type for routes handling "route not found" (404) cases
	RouteNotFound = "echo_route_not_found"
)
View Source 
const (
	HeaderAccept         = "Accept"
	HeaderAcceptEncoding = "Accept-Encoding"
	// HeaderAllow is the name of the "Allow" header field used to list the set of methods
	// advertised as supported by the target resource. Returning an Allow header is mandatory
	// for status 405 (method not found) and useful for the OPTIONS method in responses.
	// See RFC 7231: https://datatracker.ietf.org/doc/html/rfc7231#section-7.4.1
	HeaderAllow               = "Allow"
	HeaderAuthorization       = "Authorization"
	HeaderContentDisposition  = "Content-Disposition"
	HeaderContentEncoding     = "Content-Encoding"
	HeaderContentLength       = "Content-Length"
	HeaderContentType         = "Content-Type"
	HeaderCookie              = "Cookie"
	HeaderSetCookie           = "Set-Cookie"
	HeaderIfModifiedSince     = "If-Modified-Since"
	HeaderLastModified        = "Last-Modified"
	HeaderLocation            = "Location"
	HeaderRetryAfter          = "Retry-After"
	HeaderUpgrade             = "Upgrade"
	HeaderVary                = "Vary"
	HeaderWWWAuthenticate     = "WWW-Authenticate"
	HeaderXForwardedFor       = "X-Forwarded-For"
	HeaderXForwardedProto     = "X-Forwarded-Proto"
	HeaderXForwardedProtocol  = "X-Forwarded-Protocol"
	HeaderXForwardedSsl       = "X-Forwarded-Ssl"
	HeaderXUrlScheme          = "X-Url-Scheme"
	HeaderXHTTPMethodOverride = "X-HTTP-Method-Override"
	HeaderXRealIP             = "X-Real-Ip"
	HeaderXRequestID          = "X-Request-Id"
	HeaderXCorrelationID      = "X-Correlation-Id"
	HeaderXRequestedWith      = "X-Requested-With"
	HeaderServer              = "Server"
	HeaderOrigin              = "Origin"
	HeaderCacheControl        = "Cache-Control"
	HeaderConnection          = "Connection"

	// Access control
	HeaderAccessControlRequestMethod    = "Access-Control-Request-Method"
	HeaderAccessControlRequestHeaders   = "Access-Control-Request-Headers"
	HeaderAccessControlAllowOrigin      = "Access-Control-Allow-Origin"
	HeaderAccessControlAllowMethods     = "Access-Control-Allow-Methods"
	HeaderAccessControlAllowHeaders     = "Access-Control-Allow-Headers"
	HeaderAccessControlAllowCredentials = "Access-Control-Allow-Credentials"
	HeaderAccessControlExposeHeaders    = "Access-Control-Expose-Headers"
	HeaderAccessControlMaxAge           = "Access-Control-Max-Age"

	// Security
	HeaderStrictTransportSecurity         = "Strict-Transport-Security"
	HeaderXContentTypeOptions             = "X-Content-Type-Options"
	HeaderXXSSProtection                  = "X-XSS-Protection"
	HeaderXFrameOptions                   = "X-Frame-Options"
	HeaderContentSecurityPolicy           = "Content-Security-Policy"
	HeaderContentSecurityPolicyReportOnly = "Content-Security-Policy-Report-Only"
	HeaderXCSRFToken                      = "X-CSRF-Token"
	HeaderReferrerPolicy                  = "Referrer-Policy"
)

Headers

Variables

View Source 
var (
	ErrBadRequest                    = NewHTTPError(helper(http.StatusBadRequest))                    // HTTP 400 Bad Request
	ErrUnauthorized                  = NewHTTPError(helper(http.StatusUnauthorized))                  // HTTP 401 Unauthorized
	ErrPaymentRequired               = NewHTTPError(helper(http.StatusPaymentRequired))               // HTTP 402 Payment Required
	ErrForbidden                     = NewHTTPError(helper(http.StatusForbidden))                     // HTTP 403 Forbidden
	ErrNotFound                      = NewHTTPError(helper(http.StatusNotFound))                      // HTTP 404 Not Found
	ErrMethodNotAllowed              = NewHTTPError(helper(http.StatusMethodNotAllowed))              // HTTP 405 Method Not Allowed
	ErrNotAcceptable                 = NewHTTPError(helper(http.StatusNotAcceptable))                 // HTTP 406 Not Acceptable
	ErrProxyAuthRequired             = NewHTTPError(helper(http.StatusProxyAuthRequired))             // HTTP 407 Proxy AuthRequired
	ErrRequestTimeout                = NewHTTPError(helper(http.StatusRequestTimeout))                // HTTP 408 Request Timeout
	ErrConflict                      = NewHTTPError(helper(http.StatusConflict))                      // HTTP 409 Conflict
	ErrGone                          = NewHTTPError(helper(http.StatusGone))                          // HTTP 410 Gone
	ErrLengthRequired                = NewHTTPError(helper(http.StatusLengthRequired))                // HTTP 411 Length Required
	ErrPreconditionFailed            = NewHTTPError(helper(http.StatusPreconditionFailed))            // HTTP 412 Precondition Failed
	ErrStatusRequestEntityTooLarge   = NewHTTPError(helper(http.StatusRequestEntityTooLarge))         // HTTP 413 Payload Too Large
	ErrRequestURITooLong             = NewHTTPError(helper(http.StatusRequestURITooLong))             // HTTP 414 URI Too Long
	ErrUnsupportedMediaType          = NewHTTPError(helper(http.StatusUnsupportedMediaType))          // HTTP 415 Unsupported Media Type
	ErrRequestedRangeNotSatisfiable  = NewHTTPError(helper(http.StatusRequestedRangeNotSatisfiable))  // HTTP 416 Range Not Satisfiable
	ErrExpectationFailed             = NewHTTPError(helper(http.StatusExpectationFailed))             // HTTP 417 Expectation Failed
	ErrTeapot                        = NewHTTPError(helper(http.StatusTeapot))                        // HTTP 418 I'm a teapot
	ErrMisdirectedRequest            = NewHTTPError(helper(http.StatusMisdirectedRequest))            // HTTP 421 Misdirected Request
	ErrUnprocessableEntity           = NewHTTPError(helper(http.StatusUnprocessableEntity))           // HTTP 422 Unprocessable Entity
	ErrLocked                        = NewHTTPError(helper(http.StatusLocked))                        // HTTP 423 Locked
	ErrFailedDependency              = NewHTTPError(helper(http.StatusFailedDependency))              // HTTP 424 Failed Dependency
	ErrTooEarly                      = NewHTTPError(helper(http.StatusTooEarly))                      // HTTP 425 Too Early
	ErrUpgradeRequired               = NewHTTPError(helper(http.StatusUpgradeRequired))               // HTTP 426 Upgrade Required
	ErrPreconditionRequired          = NewHTTPError(helper(http.StatusPreconditionRequired))          // HTTP 428 Precondition Required
	ErrTooManyRequests               = NewHTTPError(helper(http.StatusTooManyRequests))               // HTTP 429 Too Many Requests
	ErrRequestHeaderFieldsTooLarge   = NewHTTPError(helper(http.StatusRequestHeaderFieldsTooLarge))   // HTTP 431 Request Header Fields Too Large
	ErrUnavailableForLegalReasons    = NewHTTPError(helper(http.StatusUnavailableForLegalReasons))    // HTTP 451 Unavailable For Legal Reasons
	ErrInternalServerError           = NewHTTPError(helper(http.StatusInternalServerError))           // HTTP 500 Internal Server Error
	ErrNotImplemented                = NewHTTPError(helper(http.StatusNotImplemented))                // HTTP 501 Not Implemented
	ErrBadGateway                    = NewHTTPError(helper(http.StatusBadGateway))                    // HTTP 502 Bad Gateway
	ErrServiceUnavailable            = NewHTTPError(helper(http.StatusServiceUnavailable))            // HTTP 503 Service Unavailable
	ErrGatewayTimeout                = NewHTTPError(helper(http.StatusGatewayTimeout))                // HTTP 504 Gateway Timeout
	ErrHTTPVersionNotSupported       = NewHTTPError(helper(http.StatusHTTPVersionNotSupported))       // HTTP 505 HTTP Version Not Supported
	ErrVariantAlsoNegotiates         = NewHTTPError(helper(http.StatusVariantAlsoNegotiates))         // HTTP 506 Variant Also Negotiates
	ErrInsufficientStorage           = NewHTTPError(helper(http.StatusInsufficientStorage))           // HTTP 507 Insufficient Storage
	ErrLoopDetected                  = NewHTTPError(helper(http.StatusLoopDetected))                  // HTTP 508 Loop Detected
	ErrNotExtended                   = NewHTTPError(helper(http.StatusNotExtended))                   // HTTP 510 Not Extended
	ErrNetworkAuthenticationRequired = NewHTTPError(helper(http.StatusNetworkAuthenticationRequired)) // HTTP 511 Network Authentication Required

	ErrValidatorNotRegistered = errors.New("validator not registered")
	ErrRendererNotRegistered  = errors.New("renderer not registered")
	ErrInvalidRedirectCode    = errors.New("invalid redirect status code")
	ErrCookieNotFound         = errors.New("cookie not found")
	ErrInvalidCertOrKeyType   = errors.New("invalid cert or key type, must be string or []byte")
	ErrInvalidListenerNetwork = errors.New("invalid listener network")
)

Predefined HTTP errors

Functions

func Bind added in v1.1.0 

func Bind(r *http.Request, i interface{}) (err error)

Bind implements the `Binder#Bind` function. Binding is done in following order: 1) path params; 2) query params; 3) request body. Each step COULD override previous step binded values. For single source binding use their own methods BindBody, BindQueryParams, BindPathParams.

func BindBody added in v1.1.0 

func BindBody(req *http.Request, i interface{}) (err error)

BindBody binds request body contents to bindable object NB: then binding forms take note that this implementation uses standard library form parsing which parses form data from BOTH URL and BODY if content type is not MIMEMultipartForm See non-MIMEMultipartForm: https://golang.org/pkg/net/http/#Request.ParseForm See MIMEMultipartForm: https://golang.org/pkg/net/http/#Request.ParseMultipartForm

func BindHeaders added in v1.1.0 

func BindHeaders(r *http.Request, i interface{}) error

BindHeaders binds HTTP headers to a bindable object

func BindPathParams added in v1.1.0 

func BindPathParams(r *http.Request, i interface{}) error

BindPathParams binds path params to bindable object

func BindQueryParams added in v1.1.0 

func BindQueryParams(r *http.Request, i interface{}) error

BindQueryParams binds query params to bindable object

func DefaultErrHandlerFunc 

func DefaultErrHandlerFunc(err error, w http.ResponseWriter)

DefaultErrHandlerFunc is the default centralized error handling function. It only triggers an error response for *HTTPError.

func HTML added in v1.2.1 

func HTML(w http.ResponseWriter, statusCode int, html string) error

func JSON added in v1.2.1 

func JSON(w http.ResponseWriter, statusCode int, data any) error

func String added in v1.2.1 

func String(w http.ResponseWriter, statusCode int, s string) error

func XML added in v1.2.1 

func XML(w http.ResponseWriter, statusCode int, data any, indent string) error

Types

type ErrHandlerFunc 

type ErrHandlerFunc func(err error, w http.ResponseWriter)

ErrHandlerFunc defines the function signature for centralized error handling.

type HTTPError 

type HTTPError struct {
	StatusCode int    // HTTP status code
	Msg        string // Error message
	Internal   error  // Internal error
}

HTTPError represents a custom error type inspired by Echo.

func NewHTTPError 

func NewHTTPError(statusCode int, msg string) *HTTPError

NewHTTPError creates a new HTTPError with the given status code and message.

func (*HTTPError) Error 

func (e *HTTPError) Error() string

Error returns the error message for the HTTPError.

func (*HTTPError) SetInternal added in v1.1.0 

func (e *HTTPError) SetInternal(err error) *HTTPError

SetInternal sets the internal error for the HTTPError.

func (*HTTPError) Unwrap added in v1.1.2 

func (e *HTTPError) Unwrap() error

Unwrap returns the internal error of the HTTPError.

type HandlerFunc 

type HandlerFunc func(w http.ResponseWriter, r *http.Request) error

HandlerFunc defines the function signature for a handler. It returns an error, which is used for centralized error handling.

func Adator 

func Adator(fn func(w http.ResponseWriter, r *http.Request)) HandlerFunc

Adator converts a standard http.HandlerFunc to a HandlerFunc that returns an error.

type HelperResponseWriter 

type HelperResponseWriter struct {
	http.ResponseWriter
}

HelperResponseWriter is a built-in type used to record the StatusCode and quickly send responses.

func NewHelperRW 

func NewHelperRW(w http.ResponseWriter) *HelperResponseWriter

NewHelperRW creates a new instance of HelperResponseWriter.

func (*HelperResponseWriter) Flush 

func (rw *HelperResponseWriter) Flush()

Flush implements the http.Flusher interface.

func (*HelperResponseWriter) HTML 

func (rw *HelperResponseWriter) HTML(statusCode int, html string) error

HTML sends an HTML response with the specified status code and HTML content.

func (*HelperResponseWriter) Hijack 

func (rw *HelperResponseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error)

Hijack implements the http.Hijacker interface.

func (*HelperResponseWriter) JSON 

func (rw *HelperResponseWriter) JSON(statusCode int, data any) error

JSON sends a JSON response with the specified status code and data.

func (*HelperResponseWriter) Push 

func (rw *HelperResponseWriter) Push(target string, opts *http.PushOptions) error

Push implements the http.Pusher interface.

func (*HelperResponseWriter) String 

func (rw *HelperResponseWriter) String(statusCode int, s string) error

String sends a plain text response with the specified status code and string.

func (*HelperResponseWriter) Unwrap 

func (rw *HelperResponseWriter) Unwrap() http.ResponseWriter

Unwrap returns the wrapped ResponseWriter.

func (*HelperResponseWriter) XML 

func (rw *HelperResponseWriter) XML(statusCode int, data any, indent string) error

XML sends an XML response with the specified status code and data.

type Map 

type Map map[string]any

Map is a type alias for a map with string keys and any type values.

type MiddlewareFunc 

type MiddlewareFunc func(next http.Handler) http.Handler

MiddlewareFunc defines the function signature for middleware. It wraps an http.Handler and returns a new http.Handler.

type RouteMiddlewareFunc 

type RouteMiddlewareFunc func(next HandlerFunc) HandlerFunc

RouteMiddlewareFunc defines the function signature for route-specific middleware. It wraps a HandlerFunc and returns a new HandlerFunc.

type ServeMux 

type ServeMux struct {
	http.ServeMux
	ErrHandlerFunc ErrHandlerFunc // Function for centralized error handling
	// contains filtered or unexported fields
}

ServeMux embeds http.ServeMux and provides additional features like error handling and middleware.

func NewServeMux 

func NewServeMux() *ServeMux

NewServeMux returns a new instance of ServeMux with default settings.

func (*ServeMux) Connect 

func (sm *ServeMux) Connect(path string, h HandlerFunc, m ...RouteMiddlewareFunc)

Connect registers a new CONNECT route with optional route-specific middleware.

func (*ServeMux) Delete 

func (sm *ServeMux) Delete(path string, h HandlerFunc, m ...RouteMiddlewareFunc)

Delete registers a new DELETE route with optional route-specific middleware.

func (*ServeMux) Get 

func (sm *ServeMux) Get(path string, h HandlerFunc, m ...RouteMiddlewareFunc)

Get registers a new GET route with optional route-specific middleware.

func (*ServeMux) Group 

func (sm *ServeMux) Group(prefix string) *ServeMux

Group creates a new ServeMux for a specific URL prefix, allowing for route grouping.

func (*ServeMux) HandleFunc 

func (sm *ServeMux) HandleFunc(pattern string, h HandlerFunc)

HandleFunc registers a new route with a pattern and a handler function. The handler function can return an error for centralized error handling.

func (*ServeMux) Head 

func (sm *ServeMux) Head(path string, h HandlerFunc, m ...RouteMiddlewareFunc)

Head registers a new HEAD route with optional route-specific middleware.

func (*ServeMux) Options 

func (sm *ServeMux) Options(path string, h HandlerFunc, m ...RouteMiddlewareFunc)

Options registers a new OPTIONS route with optional route-specific middleware.

func (*ServeMux) Patch 

func (sm *ServeMux) Patch(path string, h HandlerFunc, m ...RouteMiddlewareFunc)

Patch registers a new PATCH route with optional route-specific middleware.

func (*ServeMux) Post 

func (sm *ServeMux) Post(path string, h HandlerFunc, m ...RouteMiddlewareFunc)

Post registers a new POST route with optional route-specific middleware.

func (*ServeMux) Put 

func (sm *ServeMux) Put(path string, h HandlerFunc, m ...RouteMiddlewareFunc)

Put registers a new PUT route with optional route-specific middleware.

func (*ServeMux) ServeHTTP 

func (sm *ServeMux) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP processes HTTP requests using the registered handlers and middleware.

func (*ServeMux) Trace 

func (sm *ServeMux) Trace(path string, h HandlerFunc, m ...RouteMiddlewareFunc)

Trace registers a new TRACE route with optional route-specific middleware.

func (*ServeMux) Use 

func (sm *ServeMux) Use(m ...MiddlewareFunc)

Use adds middleware to the ServeMux, which will be applied to all routes.

Source Files

View all Source files

Directories

Path Synopsis
_example
hello_world

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.