chix

func AppendLogAttrs ¶

func AppendLogAttrs(ctx context.Context, attrs ...slog.Attr)

AppendLogAttrs appends the given attributes to the log entry in the context. Use this to annotate logs when using UseStructuredLogger, and when using Log, LogDebug, LogInfo, LogWarn, and LogError.

func Bind ¶

func Bind(r *http.Request, v any) (err error)

Bind binds various request attributes to the given struct, including query parameters, form data (multipart/form-data included), JSON bodies, etc, in addition to validating the struct. It calls both Config.GetRequestDecoder and Config.GetRequestValidator to perform the necessary operations. Behind the scenes, both go-playground/form and go-playground/validator are used to perform the necessary operations.

Example:

type User struct {
	Name	string	`json:"name" validate:"required"`
	Email	string	`json:"email" validate:"required,email"`
	Pretty	bool	`form:"pretty"`
}

func (u *User) Validate() error {
	if u.Name == "system" {
		return errors.New("system users are not allowed")
	}
	return nil
}

func main() {
	// [...]
	r.Post("/user", func(w http.ResponseWriter, r *http.Request) {
		var user User
		if err := chix.Bind(r, &user); err != nil {
			chix.Error(w, r, err)
			return
		}
		// [... more request-specific logic...]
		w.WriteHeader(http.StatusOK)
	})
}

References:

• https://github.com/go-playground/validator#fields
• https://github.com/go-playground/form#examples

func CSV ¶

func CSV(w http.ResponseWriter, r *http.Request, status int, rows [][]string)

CSV marshals 'rows' to CSV, and setting the Content-Type as text/csv.

func CSVIter ¶

func CSVIter(w http.ResponseWriter, r *http.Request, status int, it iter.Seq2[[]string, error])

CSVIter marshals rows from the associated iterator to CSV, and setting the Content-Type as text/csv. If the iterator returns an error, the error will be returned and the response will be set to a 500 internal server error, otherwise the rows are written to a buffer, which will be written once the iterator is exhausted.

func DefaultErrorHandler ¶

func DefaultErrorHandler(w http.ResponseWriter, r *http.Request, rerr *ResolvedError)

DefaultErrorHandler is the default error handler that will be used if no other error handler is provided. It will automatically mask 5xx+ errors if they are not configured to be public. If a custom API base path is provided through Config.SetAPIBasePath, if the request matches that base path, it will respond with DefaultErrorBody as JSON, otherwise will be a generic plain-text error response.

func DefaultLogRequestLeveler ¶

func DefaultLogRequestLeveler(r *http.Request, statusCode int) slog.Level

DefaultLogRequestLeveler determines the log level for a given request and response status code. The following request/response attributes define how the level is determined:

• statusCode >= 500: ERROR
• statusCode == 429: INFO
• statusCode >= 400: WARN
• method == OPTIONS: DEBUG
• default: INFO

func Error ¶

func Error(w http.ResponseWriter, r *http.Request, errs ...error)

Error handles errors in an HTTP request. At least one error must be specified (see IfError if you want to simplify if-error-then-respond logic). This function will do some cursory resolution of the errors based on what was provided (e.g. you can pass a ResolvedError directly to customize how something is resolved, e.g. custom status code, marking an error as public, etc), in addition to passing the error to the configured list of error resolvers (see Config.SetErrorResolvers). It will then pass the resolved error to the configured error handler (see Config.SetErrorHandler).

Panics if no errors were provided.

func ErrorWithCode ¶

func ErrorWithCode(w http.ResponseWriter, r *http.Request, statusCode int, errs ...error)

ErrorWithCode is a helper function that allows you to set a specific status code for an error. It will wrap the error in a ResolvedError and pass it to the Error function. If the status code is <500 (and no error resolvers or ExposableError implementations are used), the error will be marked as public. If this is not desired, you can use Error directly instead, and provide your own ResolvedError with the [Public] field set to false.

func GetContextIP ¶

func GetContextIP(ctx context.Context) net.IP

GetContextIP can be used to retrieve the IP from the context, that was previously set by UseContextIP. If no IP was set, nil is returned.

func GetLogAttrs ¶

func GetLogAttrs(ctx context.Context) []slog.Attr

GetLogAttrs returns the attributes that have been added to the log entry in the context.

func GetRequestID ¶

func GetRequestID(ctx context.Context) string

GetRequestID returns a request ID from the context if present, otherwise "".

func GetRequestIDOrHeader ¶

func GetRequestIDOrHeader(ctx context.Context, r *http.Request) string

GetRequestIDOrHeader returns a request ID from the context if present, otherwise the request header, if present. The header can be changed using Config.SetRequestIDHeader.

func IfError ¶

func IfError(w http.ResponseWriter, r *http.Request, errs ...error) bool

IfError is a helper function that allows you to check if an error is present, and if so, call Error to handle it, and returning true.

Example:

if chix.IfError(w, r, Something(foo, bar)) {
	return // Response already handled.
}
// [... more request-specific logic...]

func IsDebug ¶

func IsDebug(ctx context.Context) bool

IsDebug returns true if debugging for the server is enabled.

func IsExposableError ¶

func IsExposableError(err error) bool

IsExposableError returns true if the error is safe to be exposed to the client. If the error implements the ExposableError interface, it will be used to determine if the error is public. Otherwise, it will return false. Accounts for ResolvedError, and will return the [ExposableError.Public] result.

func JSON ¶

func JSON(w http.ResponseWriter, r *http.Request, status int, v any)

JSON marshals 'v' to JSON, and setting the Content-Type as application/json. Note that this does NOT auto-escape HTML.

JSON also supports indented output when the origin request has "?pretty=true" or similar.

func Log ¶

func Log(ctx context.Context, lvl slog.Level, msg string, attrs ...slog.Attr)

Log logs a message at the given level, with the given attributes. This includes any attributes which have been added by AppendLogAttrs or SetLogError.

TODO: make this always include the request ID.

func LogDebug ¶

func LogDebug(ctx context.Context, msg string, attrs ...slog.Attr)

LogDebug logs a message at the debug level, with the given attributes. This includes any attributes which have been added by AppendLogAttrs or SetLogError.

func LogError ¶

func LogError(ctx context.Context, msg string, attrs ...slog.Attr)

LogError logs a message at the error level, with the given attributes. This includes any attributes which have been added by AppendLogAttrs or SetLogError.

func LogInfo ¶

func LogInfo(ctx context.Context, msg string, attrs ...slog.Attr)

LogInfo logs a message at the info level, with the given attributes. This includes any attributes which have been added by AppendLogAttrs or SetLogError.

func LogWarn ¶

func LogWarn(ctx context.Context, msg string, attrs ...slog.Attr)

LogWarn logs a message at the warn level, with the given attributes. This includes any attributes which have been added by AppendLogAttrs or SetLogError.

func NewServer ¶

func NewServer(
	ctx context.Context,
	logger *slog.Logger,
	srv *http.Server,
	certFile, keyFile string,
) error

NewServer runs the HTTP server (with sane/safe defaults set), including with graceful termination, so when the context is cancelled, the server will be gracefully terminated (with a max timeout of 60 seconds), waiting for all requests to complete. If certFile and keyFile are provided, the server will be run with TLS enabled.

func NewServerWithoutDefaults ¶

func NewServerWithoutDefaults(
	ctx context.Context,
	logger *slog.Logger,
	srv *http.Server,
	certFile, keyFile string,
) error

NewServerWithoutDefaults runs the HTTP server, including with graceful termination, so when the context is cancelled, the server will be gracefully terminated (with a max timeout of 60 seconds), waiting for all requests to complete. If certFile and keyFile are provided, the server will be run with TLS enabled.

func Run ¶

func Run(
	pctx context.Context,
	logger *slog.Logger,
	srv *http.Server,
	jobs ...scheduler.Job,
) error

Run runs the HTTP server (with sane/safe defaults set), including with graceful termination. When the context is cancelled, the server will be gracefully terminated (with a max timeout of 60 seconds), waiting for all requests to complete. You can pass additional scheduler jobs, which allows additional asynchronous tasks/cron-jobs to be run alongside the HTTP server.

This will also listen for OS signals (SIGINT, SIGTERM, SIGQUIT) and gracefully terminate the server and all jobs when received.

func RunTLS ¶

func RunTLS(
	pctx context.Context,
	logger *slog.Logger,
	srv *http.Server,
	certFile, keyFile string,
	jobs ...scheduler.Job,
) error

RunTLS runs the HTTP server (with sane/safe defaults set) with TLS support, including with graceful termination. When the context is cancelled, the server will be gracefully terminated (with a max timeout of 60 seconds), waiting for all requests to complete. You can pass additional scheduler jobs, which allows additional asynchronous tasks/cron-jobs to be run alongside the HTTP server.

This will also listen for OS signals (SIGINT, SIGTERM, SIGQUIT) and gracefully terminate the server and all jobs when received.

func SecureRedirect ¶

func SecureRedirect(w http.ResponseWriter, r *http.Request, status int, target string)

SecureRedirect supports validating that redirect requests fulfill the following conditions:

Target URL must match one of:

• Absolute/relative to the same host
• http or https, with a host matching the requested host (no cross-domain, no port matching).
• Target URL can be parsed by net/url.Parse.

Additionally, if using UseNextURL middleware, see SecureRedirectOrNext for advanced redirect logic.

func SecureRedirectOrNext ¶

func SecureRedirectOrNext(w http.ResponseWriter, r *http.Request, status int, fallback string)

SecureRedirectOrNext is a helper function that will redirect to the next URL if it is stored in the session (using UseNextURL), otherwise it will redirect to the fallback URL, using SecureRedirect. See SecureRedirect for more details on the set of rules that are enforced when redirecting/security checks.

Use this for advanced multi-step authentication flows, where a frontend (for example), can pass in "?next=<URL>" to redirect to after authentication is complete, which is persisted in a cookie across multiple requests.

func SetLogError ¶

func SetLogError(ctx context.Context, rerr *ResolvedError)

SetLogError sets the error that occurred in the request/response in the context. Not required when using Error and similar functions, as they will automatically set the error in the context for you.

func SkipNextURL ¶

func SkipNextURL(r *http.Request) *http.Request

SkipNextURL is a help that will prevent the next URL (if any), that is loaded by UseNextURL from being used during a redirect. This is useful when you have to redirect to another source first.

func UseAPIKeyRequired ¶

func UseAPIKeyRequired(keys []string, header string) func(next http.Handler) http.Handler

UseAPIKeyRequired is a middleware that checks if the request has the correct API keys provided in the associated header. Returns net/http.StatusUnauthorized if an invalid key is provided, and net/http.StatusPreconditionFailed if no key header is provided.

If no header is provided, the default header "X-Api-Key" will be used.

func UseAPIVersionMatch ¶

func UseAPIVersionMatch(version, header string) func(next http.Handler) http.Handler

UseAPIVersionMatch is a middleware that checks if the request has the correct API version provided in the associated header.

If no header is provided, the default header "X-Api-Version" will be used.

func UseContextIP ¶

func UseContextIP() func(next http.Handler) http.Handler

UseContextIP can be used to add the requests IP to the context. This is beneficial for passing the request context to a request-unaware function/method/service, that does not have access to the original request. Ensure that this middleware is registered after UseRealIP, otherwise the stored IP may be incorrect.

func UseCrossOriginProtection ¶

func UseCrossOriginProtection(rules ...string) func(next http.Handler) http.Handler

UseCrossOriginProtection implements protections against Cross-Site Request Forgery (CSRF) by rejecting non-safe cross-origin browser requests. It will check if the request is from a trusted origin, and if not, it will return a 403 Forbidden error. It uses the Sec-Fetch-Site and Origin headers to determine if the request is trusted. GET, HEAD, and OPTIONS methods are safe methods and are always allowed. Rules should be provided in one of the following formats:

• Trusted origin: "scheme://host[:port]" (e.g. "https://example.com", "http://localhost:8080")
• Glob pattern: "*.example.com" (e.g. "*.example.com" which is http/https, "https://*.example.com").

func UseCrossOriginProtectionFunc ¶

func UseCrossOriginProtectionFunc(cond CrossOriginValidator) func(next http.Handler) http.Handler

UseCrossOriginProtectionFunc is an alternative to UseCrossOriginProtection that allows you to provide a custom condition function to determine if the request is trusted. Note that the origin URL may not be provided in the request. In that scenario, unless you have a specific path that you want to bypass, you should return false.

func UseCrossOriginResourceSharing ¶

func UseCrossOriginResourceSharing(config *CORSConfig) func(next http.Handler) http.Handler

UseCrossOriginResourceSharing is a middleware that implements the CORS spec. It will set the appropriate headers for the request based on the existence of CORS headers. Follows the CORS spec as close as possible. See also.

func UseDebug ¶

func UseDebug(debug bool) func(next http.Handler) http.Handler

UseDebug is a middleware that allows passing if debugging is enabled for the http server. Use IsDebug to check if debugging is enabled.

func UseHeaders ¶

func UseHeaders(headers map[string]string) func(next http.Handler) http.Handler

UseHeaders is a convenience handler to set multiple response header key/value pairs. Similar to go-chi's SetHeader, but allows for multiple headers to be set at once.

func UseIf ¶

func UseIf(cond bool, handler func(http.Handler) http.Handler) func(http.Handler) http.Handler

UseIf is a conditional middleware that only uses the provided middleware if the condition is true, otherwise continues as normal.

func UseIfFunc ¶

func UseIfFunc(mw func(next http.Handler) http.Handler, cond func(r *http.Request) bool) func(next http.Handler) http.Handler

UseIfFunc is a conditional middleware that only uses the provided middleware if the condition function returns true, otherwise continues as normal.

func UseNextURL ¶

func UseNextURL() func(next http.Handler) http.Handler

UseNextURL is a middleware that will store the current URL provided via the "next" query parameter, as a cookie in the response, for use with multi-step authentication flows. This allows the user to be redirected back to the original destination after authentication. Must use SecureRedirect to redirect the user, which will pick up the url from the cookie.

func UsePrivateIP ¶

func UsePrivateIP() func(next http.Handler) http.Handler

UsePrivateIP can be used to allow only private IP's to access specific routes. Make sure to register this middleware after UseRealIP, otherwise the IP checking may be incorrect.

func UseRealIP ¶

func UseRealIP(config *RealIPConfig) func(next http.Handler) http.Handler

UseRealIP is a middleware that allows passing the real IP address of the client only if the request headers that include an override, come from a trusted proxy.

func UseRealIPStringOpts ¶

func UseRealIPStringOpts(options []string) func(next http.Handler) http.Handler

UseRealIPStringOpts is a convenience function that wraps UseRealIP, with support for configuring the middleware via CLI/string flags. You can pass in an array that contains a mix of different supported headers.

Supported options are provided below:

• "cloudflare", "cf-connecting-ip": trust cloudflare ranges, and use Cf-Connecting-Ip header.
• "x-forwarded-for": use X-Forwarded-For header.
• "x-real-ip": use X-Real-Ip header.
• "true-client-ip": use True-Client-Ip header.
• "*", "any", "all": trust any IP and use X-Forwarded-For header.
• "local", "localhost", "bogon", "internal", "private": trust private IP ranges.
• any other string is treated as a trusted IP or CIDR.

If no options are passed in, DefaultRealIPConfig is used.

func UseRecoverer ¶

func UseRecoverer(next http.Handler) http.Handler

UseRecoverer is a middleware that recovers from panics, and responds with a 500 status code and appropriate error message. If debug is enabled, through UseDebug, a stack trace will be printed to stderr. Do not use this middleware if you use UseStructuredLogger middleware, as it already handles panics (in a similar way).

NOTE: This middleware should be loaded after logging/request-id/use-debug, etc middleware, but before the handlers that may panic.

func UseRequestID ¶

func UseRequestID() func(next http.Handler) http.Handler

UseRequestID is a middleware that injects a request ID into the context of each request. If the connecting client provides a request ID in the request header, it will be used instead. If no request ID is provided, a new request ID will be generated. To change which header is referenced, use Config.SetRequestIDHeader.

func UseRobotsText ¶

func UseRobotsText(config *RobotsTextConfig) func(next http.Handler) http.Handler

UseRobotsText returns a handler that serves a robots.txt file.

func UseSecurityText ¶

func UseSecurityText(config SecurityTextConfig) func(next http.Handler) http.Handler

UseSecurityText returns a handler that serves a security.txt file at the standardized path(s). Only the provided fields will be included in the response.

func UseStatic ¶

func UseStatic(config *StaticConfig) http.Handler

UseStatic returns a handler that serves static files from the provided embedded filesystem, with support for using the direct filesystem when debugging is enabled. It also supports serviing Single Page Applications (SPA) by redirecting all files not found, to the [StaticConfig.Fallback] file, if configured through [StaticConfig.SPA].

Example usage:

//go:embed all:public/dist
var publicDist embed.FS
[...]
router.Mount("/static", chix.UseStatic(&chix.StaticConfig{
	FS:         publicDist,
	Prefix:     "/static",
	AllowLocal: true,
	Path:       "public/dist"
}))

func UseStripSlashes ¶

func UseStripSlashes() func(next http.Handler) http.Handler

UseStripSlashes is a middleware that strips trailing slashes from the URL path, and accounts for the pprof /debug/ path, which breaks when slahes are stripped. Use github.com/go-chi/chi/v5/middleware.StripSlashes instead if you don't need this functionality.

func UseStructuredLogger ¶

func UseStructuredLogger(config *LogConfig) func(http.Handler) http.Handler

UseStructuredLogger is a middleware that logs the request and response as a structured log entry. It uses the LogConfig to determine the log level, and what the schema of the log entry should be. See DefaultLogConfig for the default configuration, which can be customized.

NOTE:

• This can recover from panics (and always will, to log them, regardless the [LogConfig.RecoverPanics] setting, but will re-throw if panic recovery is disabled), and will always log the request/response in that scenario. This means that if [LogConfig.RecoverPanics] is enabled, you do not need to use UseRecoverer middleware after this one.
• This should be loaded after request-id type middleware, but before everything else.
• AppendLogAttrs can be used to add extra attributes to the log entry.
• GetLogAttrs can be used to get the attributes that have been added to the log entry, if you want to use them in other middleware or handlers.
• SetLogError can be used to set the error that occurred in the request/response, though if using Error and similar functions, this is automatically done for you.

func XML ¶

func XML(w http.ResponseWriter, r *http.Request, status int, v any)

XML marshals 'v' to XML, and setting the Content-Type as application/xml.

XML also supports indented output when the origin request has "?pretty=true" or similar.