README
¶
problem
A golang library that implements application/problem+json and application/problem+xml
Features
- compatible with
application/problem+json - inspired by https://github.com/zalando/problem
- RFC link https://tools.ietf.org/html/rfc7807
- a Problem implements the Error interface and can be compared with errors.Is()
- Wrap an error to a Problem
application/problem+xmlis also supported usingxml.Unmarshalandxml.Marshal- Auto-Title based on StatusCode with
problem.Of(statusCode)
Install
go get -u github.com/thlib/problem
Usage
problem.New(problem.Title("Not Found"), problem.Status(404)).JSONString()
Will produce this:
{
"status": 404,
"title": "Not Found"
}
You can also autofill the title based on the StatusCode:
problem.Of(404)
Will produce the same problem as above!
You can also append some more options:
p := problem.Of(http.StatusNotFound)
p.Append(problem.Detail("some more details"))
// Use the Marshaler interface to get the problem json as []byte
jsonBytes, err := json.Marshal(p)
// or simpler (ignores the error)
jsonBytes = p.JSON()
Custom key/values are also supported:
problem.New(problem.Title("Not Found"), problem.Custom("key", "value"))
To write the Problem directly to a http.ResponseWriter:
http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
problem.New(
problem.Type("https://example.com/404"),
problem.Status(404),
).WriteTo(w)
})
Create a Problem from an existing error
_, err := ioutil.ReadFile("non-existing")
if err != nil {
p := problem.New(
problem.Wrap(err),
problem.Title("Internal Error"),
problem.Status(404),
)
if !errors.Is(p, os.ErrNotExist) {
t.Fatalf("expected not existing error")
}
}
Gin Framework
If you are using gin you can simply reply the problem to the client:
func(c *gin.Context) {
problem.New(
problem.Title("houston! we have a problem"),
problem.Status(http.StatusNotFound),
).WriteTo(c.Writer)
}
Echo Framework
If you are using echo you can use the following error handler to handle Problems and return them to client.
func ProblemHandler(err error, c echo.Context) {
if prb, ok := err.(*problem.Problem); ok {
if !c.Response().Committed {
if c.Request().Method == http.MethodHead {
prb.WriteHeaderTo(c.Response())
} else if _, err := prb.WriteTo(c.Response()); err != nil {
c.Logger().Error(err)
}
}
} else {
c.Echo().DefaultHTTPErrorHandler(err, c)
}
}
...
// e is an instance of echo.Echo
e.HTTPErrorHandler = ProblemHandler
Note
This is a fork of https://github.com/mschneider82/problem but can be imported directly from github without depending on a custom domain.
Documentation
¶
Index ¶
- Constants
- type Option
- type Problem
- func (p *Problem) Append(opts ...Option) *Problem
- func (p Problem) Error() string
- func (p Problem) Is(err error) bool
- func (p Problem) JSON() []byte
- func (p Problem) JSONString() string
- func (p Problem) MarshalJSON() ([]byte, error)
- func (p Problem) MarshalXML(e *xml.Encoder, start xml.StartElement) error
- func (p Problem) UnmarshalJSON(b []byte) error
- func (p *Problem) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error
- func (p Problem) Unwrap() error
- func (p Problem) WriteHeaderTo(w http.ResponseWriter)
- func (p Problem) WriteTo(w http.ResponseWriter) (int, error)
- func (p Problem) WriteXMLHeaderTo(w http.ResponseWriter)
- func (p Problem) WriteXMLTo(w http.ResponseWriter) (int, error)
- func (p Problem) XML() []byte
- func (p Problem) XMLString() string
Constants ¶
const ( // ContentTypeJSON https://tools.ietf.org/html/rfc7807#section-6.1 ContentTypeJSON = "application/problem+json" // ContentTypeXML https://tools.ietf.org/html/rfc7807#section-6.2 ContentTypeXML = "application/problem+xml" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
An Option configures a Problem using the functional options paradigm popularized by Rob Pike.
func Status ¶
Status sets the HTTP status code generated by the origin server for this occurrence of the problem.
func Title ¶
Title sets a title that appropriately describes it (think short) Written in english and readable for engineers (usually not suited for non technical stakeholders and not localized); example: Service Unavailable
type Problem ¶
type Problem struct {
// contains filtered or unexported fields
}
Problem is an RFC7807 error and can be compared with errors.Is()
func (Problem) JSONString ¶
JSONString returns the Problem as json string
func (Problem) MarshalJSON ¶
MarshalJSON implements the json.Marshaler interface
func (Problem) MarshalXML ¶
MarshalXML implements the xml.Marshaler interface
func (Problem) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaler interface
func (*Problem) UnmarshalXML ¶
UnmarshalXML implements the xml.Unmarshaler interface
func (Problem) Unwrap ¶
Unwrap returns the result of calling the Unwrap method on err, if err implements Unwrap. Otherwise, Unwrap returns nil.
func (Problem) WriteHeaderTo ¶
func (p Problem) WriteHeaderTo(w http.ResponseWriter)
WriteHeaderTo writes the HTTP headers for the JSON Problem ContentType and the problem's HTTP statuscode. This is suitable for responding to HEAD requests.
func (Problem) WriteTo ¶
func (p Problem) WriteTo(w http.ResponseWriter) (int, error)
WriteTo writes the JSON Problem to an HTTP Response Writer using the correct Content-Type and the problem's HTTP statuscode
func (Problem) WriteXMLHeaderTo ¶
func (p Problem) WriteXMLHeaderTo(w http.ResponseWriter)
WriteXMLHeaderTo writes the HTTP headers for the XML Problem ContentType and the problem's HTTP statuscode. This is suitable for responding to HEAD requests.
func (Problem) WriteXMLTo ¶
func (p Problem) WriteXMLTo(w http.ResponseWriter) (int, error)
WriteXMLTo writes the XML Problem to an HTTP Response Writer using the correct Content-Type and the problem's HTTP statuscode
Source Files