rfc7807

Documentation

Index

• type DTO
  • func (v DTO) MarshalJSON() ([]byte, error)
  • func (v *DTO) UnmarshalJSON(bytes []byte) error
• type DTOExt
  • func (v DTOExt[Extensions]) MarshalJSON() ([]byte, error)
  • func (v *DTOExt[Extensions]) UnmarshalJSON(bytes []byte) error
• type Handler
  • func (h Handler) HandleError(w http.ResponseWriter, r *http.Request, err error)
  • func (h Handler) ToDTO(ctx context.Context, err error) DTO
• type HandlerMappingFunc
• type Type
  • func (typ *Type) Parse(raw string) error
  • func (typ *Type) String() string

Examples

• Handler.HandleError

Types

type DTO

type DTO struct {
	// Type is a URI reference that identifies the problem type.
	// Ideally, the URI should resolve to human-readable information describing the type, but that’s not necessary.
	// The problem type provides more specific information than the HTTP status code itself.
	//
	// Type URI reference [RFC3986] identifies the problem type.
	// This specification encourages that, when dereferenced,
	// it provides human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]).
	// When this member is absent, its value is assumed to be "about:blank".
	//
	// Consumers MUST use the "type" string as the primary identifier for
	// the problem type; the "title" string is advisory and included only
	// for users who are not aware of the semantics of the URI and do not
	// have the ability to discover them (e.g., offline log analysis).
	// Consumers SHOULD NOT automatically dereference the type URI.
	//
	// Example: "/errors/incorrect-user-pass"
	Type Type
	// Title is a human-readable description of the problem type,
	// meaning that it should always be the same for the same type.
	//
	// Example: "Incorrect username or password."
	Title string
	// Status The status reflects the HTTP status code and is a convenient way to make problem details self-contained.
	// That way, error replies can interpret outside the context of the HTTP interaction.
	// Status is an optional field.
	//
	// Example: 401
	Status int
	// Detail is a human-readable description of the problem instance,
	// explaining why the problem occurred in this specific case.
	//
	// Example: "Authentication failed due to incorrect username or password."
	Detail string
	// Instance is a URI that identifies the specific occurrence of the error
	// Instance is optional
	//
	// Example: "/login/log/abc123"
	Instance string
	// Extensions is a user-defined optional generic type that holds additional details in your error reply.
	// For example, suppose your company already has its error reply convention.
	// In that case, you can use the extension as a backward compatibility layer
	// to roll out the Handler standard in your project
	// without breaking any API contract between your server and its clients.
	//
	// Example: {...,"error":{"code":"foo-bar-baz","message":"foo bar baz"}}
	Extensions any
}

DTO error data transfer object is made in an effort to standardize REST API error handling, the IETF devised RFC 7807, which creates a generalized error-handling schema. https://www.rfc-editor.org/rfc/rfc7807

Example:

{
   "type": "/errors/incorrect-user-pass",
   "title": "Incorrect username or password.",
   "status": 401,
   "detail": "Authentication failed due to incorrect username or password.",
   "instance": "/login/log/abc123"
}

func (DTO) MarshalJSON

func (v DTO) MarshalJSON() ([]byte, error)

func (*DTO) UnmarshalJSON

func (v *DTO) UnmarshalJSON(bytes []byte) error

type DTOExt

type DTOExt[Extensions any] struct {
	Type     Type
	Title    string
	Status   int
	Detail   string
	Instance string
	// Extensions is a user-defined optional generic structure type that holds additional details in your error reply.
	// For example, suppose your company already has its error reply convention.
	// In that case, you can use the extension as a backward compatibility layer
	// to roll out the Handler standard in your project
	// without breaking any API contract between your server and its clients.
	//
	// Example: {...,"error":{"code":"foo-bar-baz","message":"foo bar baz"}}
	Extensions Extensions
}

DTOExt is a DTO type variant that can be used for receiving error messages in a type safe way

func (DTOExt[Extensions]) MarshalJSON

func (v DTOExt[Extensions]) MarshalJSON() ([]byte, error)

func (*DTOExt[Extensions]) UnmarshalJSON

func (v *DTOExt[Extensions]) UnmarshalJSON(bytes []byte) error

type Handler

type Handler struct {
	// Mapping supplies the mapping logic that map the error value to a DTO[Extensions].
	Mapping HandlerMappingFunc
	// BaseURL is the URI path prefix the error types should have.
	// If none given, default is "/".
	BaseURL string
}

func (Handler) HandleError

func (h Handler) HandleError(w http.ResponseWriter, r *http.Request, err error)

Example

package main

import (
	"context"
	"errors"
	"net/http"

	"github.com/adamluzsi/frameless/pkg/errorutil"
	"github.com/adamluzsi/frameless/pkg/restapi/rfc7807"
)

type CompanyErrorStructure struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

const ErrSomeRandom errorutil.Error = "random error value"

func ErrorMapping(ctx context.Context, err error, dto *rfc7807.DTO) {
	switch {
	case errors.Is(err, ErrSomeRandom):
		dto.Type.ID = "some-random-err"
		dto.Detail = "this is a random error type"
	}
	dto.Extensions = CompanyErrorStructure{
		Code:    dto.Type.ID,
		Message: dto.Detail,
	}
}

func main() {
	h := rfc7807.Handler{
		Mapping: ErrorMapping,
		BaseURL: "/errors",
	}

	_ = func(w http.ResponseWriter, r *http.Request) {
		h.HandleError(w, r, ErrSomeRandom)
	}
}

func (Handler) ToDTO

func (h Handler) ToDTO(ctx context.Context, err error) DTO

type HandlerMappingFunc

type HandlerMappingFunc func(ctx context.Context, err error, dto *DTO)

type Type

type Type struct {
	ID      string
	BaseURL string
}

func (*Type) Parse

func (typ *Type) Parse(raw string) error

func (*Type) String

func (typ *Type) String() string