Corona

A Go library for implementing RFC 9457 Problem Details for HTTP APIs. It provides a standard way to carry machine-readable details of errors in HTTP response content.

Installation

go get luigimorel.com/corona

Usage

Basic Usage

package main

import (
    "net/http"
    "luigimorel.com/corona"
)

func handler(w http.ResponseWriter, r *http.Request) {
    // Create a problem for a bad request
    problem := corona.BadRequest("Invalid input provided")
    problem.WriteTo(w, r)
}

Custom Problem

problem := corona.New(
    http.StatusNotFound,
    "https://example.com/errors/not-found",
    "Resource Not Found",
    "The requested resource could not be found",
).WithInstance("/api/users/123")

problem.WriteTo(w, r)

With Extensions

problem := corona.NewValidationProblem([]corona.ValidationError{
    {Detail: "Name is required", Pointer: "/name"},
    {Detail: "Email must be valid", Pointer: "/email"},
})

problem.WriteTo(w, r)

JSON Response Example

{
  "type": "https://example.com/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "Your request parameters didn't validate.",
  "errors": [
    {
      "detail": "Name is required",
      "pointer": "/name"
    }
  ]
}

XML Response Example

When the client accepts application/problem+xml, the response will be in XML format:

<problem xmlns="urn:ietf:rfc:7807">
  <type>https://example.com/errors/validation</type>
  <title>Validation Error</title>
  <status>422</status>
  <detail>Your request parameters didn't validate.</detail>
</problem>

API Reference

Types

• Problem: The main problem details structure
• ValidationError: Example extension for validation errors

Functions

• New(status int, typeURI, title, detail string) *Problem: Create a new problem
• NewFromStatus(status int) *Problem: Create a problem from HTTP status
• BadRequest(detail string) *Problem: Create 400 Bad Request
• Unauthorized(detail string) *Problem: Create 401 Unauthorized
• Forbidden(detail string) *Problem: Create 403 Forbidden
• NotFound(detail string) *Problem: Create 404 Not Found
• Conflict(detail string) *Problem: Create 409 Conflict
• UnprocessableEntity(detail string) *Problem: Create 422 Unprocessable Entity
• InternalServerError(detail string) *Problem: Create 500 Internal Server Error
• ServiceUnavailable(detail string) *Problem: Create 503 Service Unavailable
• NewValidationProblem(errors []ValidationError) *Problem: Create validation error problem

Methods

• WithInstance(instance string) *Problem: Set instance URI
• WithExtension(name string, value interface{}) *Problem: Add custom extension
• WriteTo(w http.ResponseWriter, r *http.Request) error: Write to HTTP response
• Error() string: Implement error interface

License

This project is licensed under the MIT License - see the LICENSE file for details.