go: github.com/stellar/go/support/render/problem Index | Files

package problem

import "github.com/stellar/go/support/render/problem"

Package problem provides utility functions for rendering errors as RFC7807 compatible responses.

RFC7807: https://tools.ietf.org/html/rfc7807

The P type is used to define application problems. The Render function is used to serialize problems in a HTTP response.

Index

Package Files

default.go problem.go

Constants

const (

    // LogNoErrors indicates that the Problem instance should not log any errors
    LogNoErrors = LogFilter(iota)
    // LogUnknownErrors indicates that the Problem instance should only log errors
    // which are not registered
    LogUnknownErrors = LogFilter(iota)
    // LogAllErrors indicates that the Problem instance should log all errors
    LogAllErrors = LogFilter(iota)
)

Variables

var (
    // ServerError is a well-known problem type. Use it as a shortcut.
    ServerError = P{
        Type:   "server_error",
        Title:  "Internal Server Error",
        Status: http.StatusInternalServerError,
        Detail: "An error occurred while processing this request.  This is usually due " +
            "to a bug within the server software.  Trying this request again may " +
            "succeed if the bug is transient. Otherwise, please contact the system " +
            "administrator.",
    }

    // NotFound is a well-known problem type.  Use it as a shortcut in your actions
    NotFound = P{
        Type:   "not_found",
        Title:  "Resource Missing",
        Status: http.StatusNotFound,
        Detail: "The resource at the url requested was not found.  This usually " +
            "occurs for one of two reasons:  The url requested is not valid, or no " +
            "data in our database could be found with the parameters provided.",
    }

    // BadRequest is a well-known problem type.  Use it as a shortcut
    // in your actions.
    BadRequest = P{
        Type:   "bad_request",
        Title:  "Bad Request",
        Status: http.StatusBadRequest,
        Detail: "The request you sent was invalid in some way.",
    }
)
var Default = New(DefaultServiceHost, DefaultLogger, LogAllErrors)

Default is the problem instance used by the package functions providing a global state registry and rendering of problems for an application. For a non-global state registry instantiate a new Problem with New.

var DefaultLogger = log.DefaultLogger

DefaultLogger is the default logger used with the default problem instance.

var DefaultServiceHost = "https://stellar.org/horizon-errors/"

DefaultServiceHost is the default service host used with the default problem instance.

func IsKnownError Uses

func IsKnownError(err error) error

IsKnownError maps an error to a list of known errors

func RegisterError Uses

func RegisterError(err error, p P)

RegisterError records an error -> P mapping, allowing the app to register specific errors that may occur in other packages to be rendered as a specific P instance.

For example, you might want to render any sql.ErrNoRows errors as a problem.NotFound, and you would do so by calling:

problem.RegisterError(sql.ErrNoRows, problem.NotFound) in you application initialization sequence

func RegisterHost Uses

func RegisterHost(host string)

RegisterHost registers the service host url. It is used to prepend the host url to the error type. If you don't wish to prepend anything to the error type, register host as an empty string. The default service host points to `https://stellar.org/horizon-errors/`.

func RegisterReportFunc Uses

func RegisterReportFunc(fn ReportFunc)

RegisterReportFunc registers the report function that you want to use to report errors. Once reportFn is initialzied, it will be used to report unexpected errors.

func Render Uses

func Render(ctx context.Context, w http.ResponseWriter, err error)

Render writes a http response to `w`, compliant with the "Problem Details for HTTP APIs" RFC: https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00

func UnRegisterErrors Uses

func UnRegisterErrors()

UnRegisterErrors removes all registered errors

type LogFilter Uses

type LogFilter int

LogFilter describes which errors should be logged when terminating requests in Problem.Render()

type P Uses

type P struct {
    Type   string                 `json:"type"`
    Title  string                 `json:"title"`
    Status int                    `json:"status"`
    Detail string                 `json:"detail,omitempty"`
    Extras map[string]interface{} `json:"extras,omitempty"`
}

P is a struct that represents an error response to be rendered to a connected client.

func MakeInvalidFieldProblem Uses

func MakeInvalidFieldProblem(name string, reason error) *P

MakeInvalidFieldProblem is a helper function to make a BadRequest with extras

func NewProblemWithInvalidField Uses

func NewProblemWithInvalidField(p P, name string, reason error) *P

NewProblemWithInvalidField creates a copy of the given problem, setting the invalid_field key in extras with the given reason.

func (P) Error Uses

func (p P) Error() string

type Problem Uses

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

Problem is an instance of the functionality served by the problem package.

func New Uses

func New(serviceHost string, log *log.Entry, filter LogFilter) *Problem

New returns a new instance of Problem.

func (*Problem) IsKnownError Uses

func (ps *Problem) IsKnownError(err error) error

IsKnownError maps an error to a list of known errors

func (*Problem) RegisterError Uses

func (ps *Problem) RegisterError(err error, p P)

RegisterError records an error -> P mapping, allowing the app to register specific errors that may occur in other packages to be rendered as a specific P instance.

For example, you might want to render any sql.ErrNoRows errors as a problem.NotFound, and you would do so by calling:

problem.RegisterError(sql.ErrNoRows, problem.NotFound) in you application initialization sequence

func (*Problem) RegisterHost Uses

func (ps *Problem) RegisterHost(host string)

RegisterHost registers the service host url. It is used to prepend the host url to the error type. If you don't wish to prepend anything to the error type, register host as an empty string.

func (*Problem) RegisterReportFunc Uses

func (ps *Problem) RegisterReportFunc(fn ReportFunc)

RegisterReportFunc registers the report function that you want to use to report errors. Once reportFn is initialzied, it will be used to report unexpected errors.

func (*Problem) Render Uses

func (ps *Problem) Render(ctx context.Context, w http.ResponseWriter, err error)

Render writes a http response to `w`, compliant with the "Problem Details for HTTP APIs" RFC: https://www.rfc-editor.org/rfc/rfc7807.txt

func (*Problem) ServiceHost Uses

func (ps *Problem) ServiceHost() string

ServiceHost returns the service host the Problem instance is configured with.

func (*Problem) UnRegisterErrors Uses

func (ps *Problem) UnRegisterErrors()

UnRegisterErrors removes all registered errors

type ReportFunc Uses

type ReportFunc func(context.Context, error)

ReportFunc is a function type used to report unexpected errors.

Package problem imports 7 packages (graph) and is imported by 82 packages. Updated 2020-10-23. Refresh now. Tools for package owners.