json

package
v0.69.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 2, 2026 License: Apache-2.0 Imports: 4 Imported by: 1

Documentation

Overview

Package json provides utilities for handling JSON requests and responses.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ReadBody 

func ReadBody[T any](req *http.Request) (T, error)

ReadBody reads and decodes the JSON request body into the specified type. It automatically closes the request body.

Types

type Problem added in v0.68.0 

type Problem struct {
	// Type is a URI reference identifying the problem type. Defaults to
	// "about:blank" (RFC 9457 section 3.1) when empty. Consumers MUST use
	// Type, not Status, as the problem's primary identifier.
	Type string
	// Title is a short, human-readable summary. It should stay stable
	// across occurrences of this problem type, except for localization.
	Title string
	// Status is the HTTP status code, advisory only -- the response's
	// actual status line is authoritative. Left zero, it is set to the
	// status code passed to Problem.
	Status int
	// Detail is a human-readable explanation specific to this occurrence.
	// It should help the client correct the problem, not aid debugging.
	Detail string
	// Instance is a URI reference identifying this specific occurrence.
	Instance string
	// Extensions carries problem-type-specific members (e.g. a
	// machine-readable "reason" code) as additional top-level JSON members
	// alongside type/title/status/detail/instance (RFC 9457 section 3.2). A
	// key colliding with one of those five names is dropped in favour of
	// the standard member.
	Extensions map[string]any
}

Problem is an RFC 9457 Problem Details object. Every field is optional per the RFC; Type defaults to "about:blank" and Status is filled in from the status code passed to (*Response).Problem when left zero, so the common case only needs Title (and Detail, for an occurrence-specific message).

type Response 

type Response struct {
	Writer http.ResponseWriter
	// contains filtered or unexported fields
}

Response simplifies sending structured JSON responses and logging errors.

func NewResponse 

func NewResponse(w http.ResponseWriter) *Response

NewResponse creates a new Response helper with the provided ResponseWriter.

func NewResponseFromRequest added in v0.59.0 

func NewResponseFromRequest(w http.ResponseWriter, r *http.Request) *Response

NewResponseFromRequest creates a Response that logs using the zerolog logger stored in r's context. All context fields — request_id, principal, auth_source, method, url (the full pre-strip path), remote_addr, and user_agent — are present because AddResource injects them into the context logger before calling the resource handler.

Prefer this over NewResponseWithLogger in HTTP handlers.

func NewResponseWithLogger deprecated 

func NewResponseWithLogger(w http.ResponseWriter, r *http.Request, l zerolog.Logger) *Response

NewResponseWithLogger creates a new Response helper with a logger that includes request metadata.

Deprecated: Use NewResponseFromRequest in HTTP handlers to automatically inherit the request-scoped context logger (carrying request_id, principal, etc.). NewResponseWithLogger remains useful when an explicit logger is needed (e.g. tests).

func (*Response) Accepted added in v0.58.0 

func (r *Response) Accepted(opts ...ResponseOption)

Accepted sends a 202 Accepted response.

func (*Response) AcceptedWithMessage deprecated added in v0.45.5 

func (r *Response) AcceptedWithMessage(message string)

AcceptedWithMessage sends a 202 Accepted response with message as the public message.

Deprecated: Use Accepted() with options instead.

func (*Response) BadRequest added in v0.58.0 

func (r *Response) BadRequest(opts ...ResponseOption)

BadRequest sends a 400 Bad Request response.

func (*Response) BadRequestWithMessage deprecated 

func (r *Response) BadRequestWithMessage(message string)

BadRequestWithMessage sends a 400 Bad Request response with message as the public message.

Deprecated: Use BadRequest() with options instead.

func (*Response) BadRequestWithMessages deprecated 

func (r *Response) BadRequestWithMessages(responseMessage, logMessage string)

BadRequestWithMessages sends a 400 Bad Request response with responseMessage as the public message and logMessage logged separately.

Deprecated: Use BadRequest() with options instead.

func (*Response) Conflict added in v0.58.0 

func (r *Response) Conflict(opts ...ResponseOption)

Conflict sends a 409 Conflict response.

func (*Response) ConflictWithMessage deprecated 

func (r *Response) ConflictWithMessage(message string)

ConflictWithMessage sends a 409 Conflict response with message as the public message.

Deprecated: Use Conflict() with options instead.

func (*Response) ConflictWithMessages deprecated 

func (r *Response) ConflictWithMessages(responseMessage, logMessage string)

ConflictWithMessages sends a 409 Conflict response with responseMessage as the public message and logMessage logged separately.

Deprecated: Use Conflict() with options instead.

func (*Response) Created added in v0.58.0 

func (r *Response) Created(opts ...ResponseOption)

Created sends a 201 Created response.

func (*Response) CreatedWithMessage deprecated 

func (r *Response) CreatedWithMessage(message string)

CreatedWithMessage sends a 201 Created response with message as the public message.

Deprecated: Use Created() with options instead.

func (*Response) CreatedWithURI deprecated added in v0.53.0 

func (r *Response) CreatedWithURI(uri string)

CreatedWithURI sends a 201 Created response with a Location header and public message set to uri, and a body containing uri.

Deprecated: Use Created() with Location() option instead.

func (*Response) CreatedWithURIAndMessage deprecated added in v0.53.0 

func (r *Response) CreatedWithURIAndMessage(uri string, message string)

CreatedWithURIAndMessage sends a 201 Created response with a Location header set to uri, a body containing uri, and message as the public message.

Deprecated: Use Created() with Location() and PublicMessage() options instead.

func (*Response) Data 

func (r *Response) Data(status int, data any)

Data sends a JSON response with the specified status code and data.

func (*Response) Forbidden added in v0.58.0 

func (r *Response) Forbidden(opts ...ResponseOption)

Forbidden sends a 403 Forbidden response.

func (*Response) ForbiddenWithMessage deprecated added in v0.39.0 

func (r *Response) ForbiddenWithMessage(message string)

ForbiddenWithMessage sends a 403 Forbidden response with message as both the public message and the logged message.

Deprecated: Use Forbidden() with options instead.

func (*Response) ForbiddenWithMessages deprecated added in v0.39.0 

func (r *Response) ForbiddenWithMessages(responseMessage, logMessage string)

ForbiddenWithMessages sends a 403 Forbidden response with responseMessage as the public message and logMessage logged separately.

Deprecated: Use Forbidden() with options instead.

func (*Response) InternalServerError added in v0.58.0 

func (r *Response) InternalServerError(opts ...ResponseOption)

InternalServerError sends a 500 Internal Server Error response.

func (*Response) InternalServerErrorWithMessage deprecated 

func (r *Response) InternalServerErrorWithMessage(err error, message string)

InternalServerErrorWithMessage sends a 500 Internal Server Error response with message as the public message and err logged.

Deprecated: Use InternalServerError() with options instead.

func (*Response) InternalServerErrorWithMessages deprecated 

func (r *Response) InternalServerErrorWithMessages(err error, responseMessage string, logMessage string)

InternalServerErrorWithMessages sends a 500 Internal Server Error response with responseMessage as the public message, and err and logMessage logged.

Deprecated: Use InternalServerError() with options instead.

func (*Response) InvalidInput added in v0.58.0 

func (r *Response) InvalidInput(opts ...ResponseOption)

InvalidInput sends a 400 Bad Request response for invalid input.

func (*Response) InvalidInputWithMessage deprecated 

func (r *Response) InvalidInputWithMessage(err error, message string)

InvalidInputWithMessage sends a 400 Bad Request response with message as the public message and err logged.

Deprecated: Use InvalidInput() with options instead.

func (*Response) InvalidInputWithMessages deprecated 

func (r *Response) InvalidInputWithMessages(err error, responseMessage, logMessage string)

InvalidInputWithMessages sends a 400 Bad Request response with responseMessage as the public message, and err and logMessage logged.

Deprecated: Use InvalidInput() with options instead.

func (*Response) NoContent 

func (r *Response) NoContent(opts ...ResponseOption)

NoContent sends a 204 No Content response.

func (*Response) NotAcceptable added in v0.58.0 

func (r *Response) NotAcceptable(opts ...ResponseOption)

NotAcceptable sends a 406 Not Acceptable response.

func (*Response) NotAcceptableWithMessage deprecated 

func (r *Response) NotAcceptableWithMessage(message string)

NotAcceptableWithMessage sends a 406 Not Acceptable response with message as the public message.

Deprecated: Use NotAcceptable() with options instead.

func (*Response) NotAcceptableWithMessages deprecated 

func (r *Response) NotAcceptableWithMessages(responseMessage, logMessage string)

NotAcceptableWithMessages sends a 406 Not Acceptable response with responseMessage as the public message and logMessage logged separately.

Deprecated: Use NotAcceptable() with options instead.

func (*Response) NotFound added in v0.58.0 

func (r *Response) NotFound(opts ...ResponseOption)

NotFound sends a 404 Not Found response.

func (*Response) NotFoundWithMessage deprecated 

func (r *Response) NotFoundWithMessage(message string)

NotFoundWithMessage sends a 404 Not Found response with message as the public message.

Deprecated: Use NotFound() with options instead.

func (*Response) NotFoundWithMessages deprecated 

func (r *Response) NotFoundWithMessages(responseMessage, logMessage string)

NotFoundWithMessages sends a 404 Not Found response with responseMessage as the public message and logMessage logged separately.

Deprecated: Use NotFound() with options instead.

func (*Response) NotImplemented added in v0.68.0 

func (r *Response) NotImplemented(opts ...ResponseOption)

NotImplemented sends a 501 Not Implemented response.

func (*Response) OK 

func (r *Response) OK(opts ...ResponseOption)

OK sends a 200 OK response.

func (*Response) Problem added in v0.68.0 

func (r *Response) Problem(status int, p Problem, opts ...ResponseOption)

Problem sends an RFC 9457 "application/problem+json" response. status sets the HTTP status line; p.Status is set to status when p.Status is zero, since RFC 9457 requires the two to match.

opts accepts LogErr, LogMessage and Header/Location for side effects, exactly as the other Response methods do. Data and PublicMessage do not apply to a Problem body -- there is no message-merging step to plug them into -- and are dropped with a logged warning if passed.

func (*Response) ServiceUnavailable added in v0.68.0 

func (r *Response) ServiceUnavailable(opts ...ResponseOption)

ServiceUnavailable sends a 503 Service Unavailable response.

func (*Response) Unauthorized added in v0.58.0 

func (r *Response) Unauthorized(opts ...ResponseOption)

Unauthorized sends a 401 Unauthorized response.

func (*Response) UnauthorizedWithMessage deprecated added in v0.39.0 

func (r *Response) UnauthorizedWithMessage(message string)

UnauthorizedWithMessage sends a 401 Unauthorized response with message as both the public message and the logged message.

Deprecated: Use Unauthorized() with options instead.

func (*Response) UnauthorizedWithMessages deprecated added in v0.39.0 

func (r *Response) UnauthorizedWithMessages(responseMessage, logMessage string)

UnauthorizedWithMessages sends a 401 Unauthorized response with responseMessage as the public message and logMessage logged separately.

Deprecated: Use Unauthorized() with options instead.

func (*Response) UnprocessableEntity added in v0.68.0 

func (r *Response) UnprocessableEntity(opts ...ResponseOption)

UnprocessableEntity sends a 422 Unprocessable Entity response.

func (*Response) WithStatus added in v0.58.0 

func (r *Response) WithStatus(code int, opts ...ResponseOption)

WithStatus sends a response with a custom status code.

type ResponseOption added in v0.69.0 

type ResponseOption interface {
	// contains filtered or unexported methods
}

ResponseOption represents a configuration option for responses.

func Data added in v0.58.0 

func Data(data any) ResponseOption

Data includes structured data in the response. 

func Header(key, value string) ResponseOption

Header sets a custom response header.

func Location added in v0.58.0 

func Location(uri string) ResponseOption

Location sets the Location header (typically for 201 Created responses).

func LogErr added in v0.58.0 

func LogErr(err error) ResponseOption

LogErr includes an underlying error for server-side logging.

func LogMessage added in v0.58.0 

func LogMessage(msg string) ResponseOption

LogMessage provides a custom message for server logs (separate from public message).

func PublicMessage added in v0.58.0 

func PublicMessage(msg string) ResponseOption

PublicMessage sets the message sent to the client (overrides default).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.