feat: implement rfc 7807 core lib and tests

Author: SemmiDev

http.go

@@ -0,0 +1,27 @@
+package problem
+
+import (
+	"encoding/json"
+	"net/http"
+)
+
+// Write automatically writes the Problem Details as a JSON HTTP response
+// with the correct Application/Problem+JSON content type.
+func (p *Problem) Write(w http.ResponseWriter) error {
+	w.Header().Set("Content-Type", "application/problem+json; charset=utf-8")
+	w.Header().Set("X-Content-Type-Options", "nosniff")
+	w.WriteHeader(p.Status)
+
+	enc := json.NewEncoder(w)
+	// Optionally prevent escaping HTML inside JSON to keep URI strings clean
+	enc.SetEscapeHTML(false)
+
+	if err := enc.Encode(p); err != nil {
+		return err
+	}
+	return nil
+}
+
+// Handler is a generic middleware interface or handler concept, but realistically
+// you just need `problem.Write(w)`.
+// We can provide a functional wrapper if you wanted, but usually `Write` is enough.

options.go

@@ -0,0 +1,58 @@
+package problem
+
+import "fmt"
+
+// Option is a functional option for customizing a Problem details object.
+type Option func(*Problem)
+
+// WithDetail sets the human-readable explanation specific to this occurrence of the problem.
+func WithDetail(detail string) Option {
+	return func(p *Problem) {
+		p.Detail = detail
+	}
+}
+
+// WithDetailf formats and sets the detail message.
+func WithDetailf(format string, args ...any) Option {
+	return func(p *Problem) {
+		p.Detail = fmt.Sprintf(format, args...)
+	}
+}
+
+// WithInstance sets the URI reference that identifies the specific occurrence of the problem.
+func WithInstance(instance string) Option {
+	return func(p *Problem) {
+		p.Instance = instance
+	}
+}
+
+// WithExtension sets a single extension field.
+// According to RFC 7807, extension members are additional members within the Problem Details object.
+func WithExtension(key string, value any) Option {
+	return func(p *Problem) {
+		if p.Extensions == nil {
+			p.Extensions = make(map[string]any)
+		}
+		p.Extensions[key] = value
+	}
+}
+
+// WithExtensions merges multiple extension fields at once.
+func WithExtensions(ext map[string]any) Option {
+	return func(p *Problem) {
+		if p.Extensions == nil {
+			p.Extensions = make(map[string]any)
+		}
+		for k, v := range ext {
+			p.Extensions[k] = v
+		}
+	}
+}
+
+// WithErr sets the underlying error that caused this problem.
+// This allows the Problem to wrap another error, supporting standard Go wrapping (errors.Is/As).
+func WithErr(err error) Option {
+	return func(p *Problem) {
+		p.err = err
+	}
+}

problem.go

@@ -0,0 +1,135 @@
+package problem
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+)
+
+// Problem represents an RFC 7807 Problem Details object.
+type Problem struct {
+	// Type is a URI reference that identifies the problem type.
+	Type string `json:"type"`
+
+	// Title is a short, human-readable summary of the problem type.
+	Title string `json:"title"`
+
+	// Status is the HTTP status code for this occurrence of the problem.
+	Status int `json:"status"`
+
+	// Detail is a human-readable explanation specific to this occurrence of the problem.
+	Detail string `json:"detail,omitempty"`
+
+	// Instance is a URI reference that identifies the specific occurrence of the problem.
+	Instance string `json:"instance,omitempty"`
+
+	// Extensions contains additional properties beyond the standard RFC 7807 fields.
+	Extensions map[string]any `json:"-"`
+
+	// err is the underlying error that caused this problem, if any.
+	// This makes Problem compatible with Go 1.13+ error wrapping.
+	err error
+}
+
+// MarshalJSON implements custom JSON marshaling to flatten the Extensions
+// into the top-level object, as required by RFC 7807.
+func (p Problem) MarshalJSON() ([]byte, error) {
+	// Start with standard fields
+	base := map[string]any{
+		"type":   p.Type,
+		"title":  p.Title,
+		"status": p.Status,
+	}
+
+	if p.Detail != "" {
+		base["detail"] = p.Detail
+	}
+	if p.Instance != "" {
+		base["instance"] = p.Instance
+	}
+
+	// Merge extensions to the top level, avoiding overwriting standard fields
+	protectedFields := map[string]bool{
+		"type": true, "title": true, "status": true,
+		"detail": true, "instance": true,
+	}
+
+	for k, v := range p.Extensions {
+		if !protectedFields[k] {
+			base[k] = v
+		}
+	}
+
+	return json.Marshal(base)
+}
+
+// UnmarshalJSON implements custom JSON unmarshaling to extract non-standard
+// fields into the Extensions map.
+func (p *Problem) UnmarshalJSON(data []byte) error {
+	var raw map[string]any
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return err
+	}
+
+	p.Extensions = make(map[string]any)
+	protectedFields := map[string]bool{
+		"type": true, "title": true, "status": true,
+		"detail": true, "instance": true,
+	}
+
+	for k, v := range raw {
+		switch k {
+		case "type":
+			if s, ok := v.(string); ok {
+				p.Type = s
+			}
+		case "title":
+			if s, ok := v.(string); ok {
+				p.Title = s
+			}
+		case "status":
+			if f, ok := v.(float64); ok { // JSON numbers decode to float64 by default
+				p.Status = int(f)
+			}
+		case "detail":
+			if s, ok := v.(string); ok {
+				p.Detail = s
+			}
+		case "instance":
+			if s, ok := v.(string); ok {
+				p.Instance = s
+			}
+		default:
+			if !protectedFields[k] {
+				p.Extensions[k] = v
+			}
+		}
+	}
+	return nil
+}
+
+// Error implements the standard Go `error` interface.
+func (p *Problem) Error() string {
+	if p.err != nil {
+		return fmt.Sprintf("[%d] %s: %s: %v", p.Status, p.Type, p.Title, p.err)
+	}
+	if p.Detail != "" {
+		return fmt.Sprintf("[%d] %s: %s", p.Status, p.Type, p.Detail)
+	}
+	return fmt.Sprintf("[%d] %s: %s", p.Status, p.Type, p.Title)
+}
+
+// Unwrap makes Problem compatible with Go 1.13+ error wrapping.
+// It returns the underlying error if one was optionally provided.
+func (p *Problem) Unwrap() error {
+	return p.err
+}
+
+// IsProblem checks if an error is or wraps a *Problem details object.
+func IsProblem(err error) (*Problem, bool) {
+	var p *Problem
+	if err != nil && errors.As(err, &p) {
+		return p, true
+	}
+	return nil, false
+}

problem_test.go

@@ -0,0 +1,165 @@
+package problem_test
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/semmidev/problem"
+)
+
+func TestProblemSerialization(t *testing.T) {
+	t.Run("marshaling", func(t *testing.T) {
+		p := problem.New(
+			problem.BadRequest,
+			problem.WithDetail("Invalid input provided"),
+			problem.WithInstance("/api/v1/users"),
+			problem.WithExtension("trace_id", "req-1234"),
+			problem.WithExtension("balance", 5000),
+		)
+
+		data, err := json.Marshal(p)
+		if err != nil {
+			t.Fatalf("failed to marshal: %v", err)
+		}
+
+		var raw map[string]any
+		if err := json.Unmarshal(data, &raw); err != nil {
+			t.Fatalf("failed to unmarshal back to map: %v", err)
+		}
+
+		// Ensure top-level fields match expectations
+		if raw["type"] != "about:blank" {
+			t.Errorf("expected type 'about:blank', got %v", raw["type"])
+		}
+		if raw["title"] != "Bad Request" {
+			t.Errorf("expected title 'Bad Request', got %v", raw["title"])
+		}
+		if raw["status"].(float64) != float64(http.StatusBadRequest) {
+			t.Errorf("expected status %v, got %v", http.StatusBadRequest, raw["status"])
+		}
+		if raw["detail"] != "Invalid input provided" {
+			t.Errorf("expected detail, got %v", raw["detail"])
+		}
+		if raw["instance"] != "/api/v1/users" {
+			t.Errorf("expected instance, got %v", raw["instance"])
+		}
+		if raw["trace_id"] != "req-1234" {
+			t.Errorf("expected trace_id extension, got %v", raw["trace_id"])
+		}
+		if raw["balance"].(float64) != 5000 {
+			t.Errorf("expected balance extension, got %v", raw["balance"])
+		}
+	})
+
+	t.Run("unmarshaling", func(t *testing.T) {
+		rawJSON := []byte(`{
+			"type": "https://example.com/probs/out-of-credit",
+			"title": "You do not have enough credit.",
+			"status": 403,
+			"detail": "Your current balance is 30, but that costs 50.",
+			"instance": "/account/12345/msgs/abc",
+			"balance": 30,
+			"accounts": ["/account/12345", "/account/67890"]
+		}`)
+
+		var p problem.Problem
+		if err := json.Unmarshal(rawJSON, &p); err != nil {
+			t.Fatalf("failed to unmarshal: %v", err)
+		}
+
+		if p.Type != "https://example.com/probs/out-of-credit" {
+			t.Errorf("bad type: %s", p.Type)
+		}
+		if p.Title != "You do not have enough credit." {
+			t.Errorf("bad title: %s", p.Title)
+		}
+		if p.Status != 403 {
+			t.Errorf("bad status: %d", p.Status)
+		}
+		if p.Detail != "Your current balance is 30, but that costs 50." {
+			t.Errorf("bad detail: %s", p.Detail)
+		}
+		if p.Instance != "/account/12345/msgs/abc" {
+			t.Errorf("bad instance: %s", p.Instance)
+		}
+
+		// Extensions
+		if p.Extensions == nil {
+			t.Fatal("expected extensions to be initialized")
+		}
+		if p.Extensions["balance"].(float64) != 30 {
+			t.Errorf("bad extension balance: %v", p.Extensions["balance"])
+		}
+
+		// check accounts list length
+		accounts, ok := p.Extensions["accounts"].([]any)
+		if !ok || len(accounts) != 2 {
+			t.Errorf("bad extension accounts array: %v", p.Extensions["accounts"])
+		}
+	})
+}
+
+func TestProblemErrorWrapping(t *testing.T) {
+	origErr := errors.New("underlying generic network timeout")
+
+	p := problem.Wrap(origErr, problem.GatewayTimeout, problem.WithDetail("Upstream service failed"))
+
+	// Implement Standard Error()
+	if p.Error() == "" {
+		t.Error("error string should not be empty")
+	}
+
+	// Unwrap
+	if unwrapped := p.Unwrap(); unwrapped != origErr {
+		t.Errorf("expected to unwrap origErr, got: %v", unwrapped)
+	}
+
+	// errors.Is check
+	if !errors.Is(p, origErr) {
+		t.Error("errors.Is should return true for underlying error")
+	}
+
+	// errors.As check (getting Problem back out of an error)
+	var asErr *problem.Problem
+	if !errors.As(p, &asErr) {
+		t.Error("errors.As should extract Problem from itself")
+	}
+
+	// Double-wrapping scenario (simulating fmt.Errorf)
+	wrap2 := fmt.Errorf("adding more context: %w", p)
+	if !errors.As(wrap2, &asErr) {
+		t.Error("errors.As should extract Problem from a wrapped generic error")
+	}
+
+	// IsProblem convenience
+	if extracted, ok := problem.IsProblem(wrap2); !ok || extracted == nil {
+		t.Error("IsProblem should successfully extract the Problem from a wrapped error")
+	}
+}
+
+func TestProblemHTTPWrite(t *testing.T) {
+	p := problem.New(problem.InternalServerError, problem.WithDetail("DB connection failed"))
+
+	rec := httptest.NewRecorder()
+	if err := p.Write(rec); err != nil {
+		t.Fatalf("Write should not return error: %v", err)
+	}
+
+	res := rec.Result()
+	if res.StatusCode != 500 {
+		t.Errorf("bad status code, expected 500 got %d", res.StatusCode)
+	}
+
+	contentType := res.Header.Get("Content-Type")
+	if contentType != "application/problem+json; charset=utf-8" {
+		t.Errorf("bad content type: %s", contentType)
+	}
+
+	if snif := res.Header.Get("X-Content-Type-Options"); snif != "nosniff" {
+		t.Errorf("expected nosniff, got %v", snif)
+	}
+}