problem

README

github.com/n-vr/httptoolkit/problem

This package can be used in addition to the github.com/n-vr/httptoolkit/handler package to return a response according to the poblem details format (RFC 9457).

Example

package main

import (
	"errors"
	"net/http"

	"github.com/n-vr/httptoolkit/handler"
	"github.com/n-vr/httptoolkit/problem"
)

// userNotFoundProblemType is a problem type for user not found.
// This can be reused when creating a Problem.
//
// This is an example of how to create a problem type.
// The URI should should uniquely identify the problem type
// and dereferencing it should provide human-readable documentation.
var userNotFoundProblemType = problem.NewType("http://localhost/user-not-found", "User not found")

func main() {
	mux := http.NewServeMux()

	mux.Handle("GET /", handler.Handler(handleHome))
	mux.Handle("GET /simple-error", handler.Handler(handleSimpleError))
	mux.Handle("GET /complex-error", handler.Handler(handleComplexError))

	// Set the error handler to the problem.ErrorHandler.
	// This is needed to handle problem.Problem errors.
	handler.ErrorHandler = problem.ErrorHandler

	http.ListenAndServe(":8080", mux)
}

func handleHome(w http.ResponseWriter, r *http.Request) error {
	w.Write([]byte("Hello, World!"))
	return nil
}

func handleSimpleError(w http.ResponseWriter, r *http.Request) error {
	err := errors.New("an error occurred")
	return problem.New(err, http.StatusTeapot)
}

func handleComplexError(w http.ResponseWriter, r *http.Request) error {
	err := errors.New("an error occurred")
	return problem.New(err, http.StatusNotFound,
		problem.WithType(userNotFoundProblemType),
		problem.WithInstance("/users/123"),
		problem.WithExtension("user", "123"))
}

Documentation

Overview

Package problem implements RFC 9457 errors that can be returned from a handler.

Index

• func ErrorHandler(err error, w http.ResponseWriter)
• func WithExtension(key string, value any) option
• func WithInstance(instance string) option
• func WithType(t *Type) option
• type Problem
  • func New(err error, status int, opts ...option) *Problem
  • func (p *Problem) Error() string
  • func (p *Problem) MarshalJSON() ([]byte, error)
• type Type
  • func NewType(typeURI, title string) *Type

Functions

func ErrorHandler

func ErrorHandler(err error, w http.ResponseWriter)

func WithExtension

func WithExtension(key string, value any) option

WithExtension adds an extension field to the problem.

func WithInstance

func WithInstance(instance string) option

WithInstance sets the instance that identifies the specific occurrence of the problem.

func WithType

func WithType(t *Type) option

WithType sets the type and title of the problem.

Types

type Problem

type Problem struct {
	Type     string `json:"type"`
	Title    string `json:"title"`
	Status   int    `json:"status"`
	Detail   string `json:"detail,omitempty"`
	Instance string `json:"instance,omitempty"`

	// Extensions is a map of additional optional members.
	Extensions map[string]any
}

Problem is an error that implements the RFC 9457 problem details.

func New

func New(err error, status int, opts ...option) *Problem

Createa a new Problem using err and status. The status code should be a valid HTTP status code.

func (*Problem) Error

func (p *Problem) Error() string

func (*Problem) MarshalJSON

func (p *Problem) MarshalJSON() ([]byte, error)

type Type

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

Type represents a problem type.

func NewType

func NewType(typeURI, title string) *Type

Create a new Type using typeURI and title. This Type can be reused when creating a Problem.