response

Documentation

Overview

Package response writes API envelopes and error payloads with centralized sanitization.

Index

• func Created(w http.ResponseWriter, data any, requestID string)
• func Error(w http.ResponseWriter, err error, requestID string)
• func JSON(w http.ResponseWriter, status int, payload Envelope)
• func OK(w http.ResponseWriter, data any, requestID string)
• type Envelope
• type ErrorBody

Functions

func Created

func Created(w http.ResponseWriter, data any, requestID string)

Created writes a 201 success envelope.

func Error

func Error(w http.ResponseWriter, err error, requestID string)

Error writes sanitized error envelope based on typed app errors.

Behavior: - Deadline exceeded maps to timeout response - AppError maps to configured status/code/message/details - Unknown errors map to generic internal error response

func JSON

func JSON(w http.ResponseWriter, status int, payload Envelope)

JSON writes a response envelope as JSON with explicit HTTP status code.

func OK

func OK(w http.ResponseWriter, data any, requestID string)

OK writes a 200 success envelope.

Types

type Envelope

type Envelope struct {
	// OK indicates whether request completed successfully.
	OK bool `json:"ok"`
	// Data contains success payload.
	Data any `json:"data,omitempty"`
	// Error contains error payload for failed responses.
	Error *ErrorBody `json:"error,omitempty"`
	// RequestID propagates request correlation identifier.
	RequestID string `json:"request_id,omitempty"`
	// Meta contains optional non-primary payload metadata.
	Meta any `json:"meta,omitempty"`
}

Envelope is the standard API response shape for all endpoints.

type ErrorBody

type ErrorBody struct {
	// Code is stable machine-readable error code.
	Code string `json:"code"`
	// Message is client-facing error summary.
	Message string `json:"message"`
	// Details contains optional structured diagnostics safe for clients.
	Details any `json:"details,omitempty"`
}

ErrorBody is the API error payload embedded in response envelope.