server

Documentation

Overview

Package server provides simple and standard utilities for building HTTP servers. These components are designed to ensure consistencty and reduce the amount of boilerplate code that needs to be written for each new server.

Index

• func Decode(r *http.Request, val interface{}) error
• func DecodeStrict(r *http.Request, val interface{}) error
• func IsResponseError(err error) bool
• func JSON(w http.ResponseWriter, code int, data interface{}) error
• func SetRequestIDFunc(fn RequestIDFunc)
• type ErrorBuilder
  • func Err(err error) *ErrorBuilder
  • func Error() *ErrorBuilder
  • func (b *ErrorBuilder) Code(code int) *ErrorBuilder
  • func (b *ErrorBuilder) Data(data any) *ErrorBuilder
  • func (b *ErrorBuilder) Err(err error) *ErrorBuilder
  • func (b *ErrorBuilder) Errf(format string, args ...any) *ErrorBuilder
  • func (b *ErrorBuilder) Msg(msg string) *ErrorBuilder
  • func (b *ErrorBuilder) Msgf(format string, args ...any) *ErrorBuilder
  • func (b *ErrorBuilder) Status(status int) *ErrorBuilder
  • func (b *ErrorBuilder) Write(ctx context.Context, w http.ResponseWriter) error
• type ErrorResp
• type RequestIDFunc
• type ResponseError
  • func (e ResponseError) Error() string
  • func (e ResponseError) Unwrap() error

Functions

func Decode

func Decode(r *http.Request, val interface{}) error

Decode reads the body of an HTTP request looking for a JSON document. The body is decoded into the provided value.

func DecodeStrict

func DecodeStrict(r *http.Request, val interface{}) error

DecodeStrict reads the body of an HTTP request looking for a JSON document. The body is decoded into the provided value. DecodeStrict will return an error if the JSON document contains fields that are not defined in the provided value.

func IsResponseError

func IsResponseError(err error) bool

IsResponseError returns true if the error is a ResponseError or wraps a ResponseError. If the error is a ResponseError, the caller can assume that the HTTP status code and message have already been sent to the client.

func JSON

func JSON(w http.ResponseWriter, code int, data interface{}) error

JSON converts a Go value to JSON and sends it to the client. If the code is StatusNoContent, no body is sent. Adapted from https://github.com/ardanlabs/service/tree/master/foundation/web

func SetRequestIDFunc

func SetRequestIDFunc(fn RequestIDFunc)

SetRequestIDFunc sets the function used to get the request ID from a context.

Types

type ErrorBuilder

type ErrorBuilder struct {
	// contains filtered or unexported fields
}

func Err

func Err(err error) *ErrorBuilder

Err creates a new ErrorBuilder with the provided error value. this is equivalent to calling

Error().Err(err).

func Error

func Error() *ErrorBuilder

Error creates a new ErrorBuilder with a default error value.

Default ResponseError:

{
  "error": "unknown error"
	"statusCode": 500
  "requestId": "..."
}

value 'requestId' is generated by requestIDFunc, which is set by SetRequestIDFunc if not set, it will be omitted from response

func (*ErrorBuilder) Code

func (b *ErrorBuilder) Code(code int) *ErrorBuilder

Code sets the HTTP status code that will be used in the response. If no code is provided, http.StatusInternalServerError will be used.

Deprecated: Use Status instead.

func (*ErrorBuilder) Data

func (b *ErrorBuilder) Data(data any) *ErrorBuilder

Data sets the data that will be included in the response. The data will be marshaled to JSON and included in the response body.

Example JSON:

	{
	 "error": "invalid request body"
   "statusCode": 400
	 "data": {
		 "foo": "bar"
	 }
	}

func (*ErrorBuilder) Err

func (b *ErrorBuilder) Err(err error) *ErrorBuilder

Err sets the error value that will be embedded into the resulting ResponseError returned from a successful call to Write. The error.Err() value will be used as the message in the response if no message is provided.

func (*ErrorBuilder) Errf

func (b *ErrorBuilder) Errf(format string, args ...any) *ErrorBuilder

Errf is the same as Err, but allows you to provide a format string and arguments that will be used to create a new error. This calls fmt.Errorf(format, args...) to create the error.

func (*ErrorBuilder) Msg

func (b *ErrorBuilder) Msg(msg string) *ErrorBuilder

Msg sets the message that will be used in the response. If no message is provided, the error.Err() value will be used as the message.

func (*ErrorBuilder) Msgf

func (b *ErrorBuilder) Msgf(format string, args ...any) *ErrorBuilder

Msgf is the same as Msg, but allows you to provide a format string and arguments that will be used to create the message. This calls fmt.Sprintf(format, args...) to create the message.

func (*ErrorBuilder) Status

func (b *ErrorBuilder) Status(status int) *ErrorBuilder

Status sets the HTTP status code that will be used in the response. If no code is provided, http.StatusInternalServerError will be used.

func (*ErrorBuilder) Write

func (b *ErrorBuilder) Write(ctx context.Context, w http.ResponseWriter) error

Write sends an error response back to the client with properties in the ErrorBuilder. If the code is http.StatusNoContent, no body is sent. It returns a type of server.ResponseError that can be if you are using an error middleware that logs errors.

type ErrorResp

type ErrorResp struct {
	Message    string `json:"message"`
	StatusCode int    `json:"statusCode"`
	RequestID  string `json:"requestId,omitempty"`
	Data       any    `json:"data,omitempty"`
}

ErrorResp is the JSON response body for an error response. It contains the message, status code, request ID, and optional data.

type RequestIDFunc

type RequestIDFunc func(ctx context.Context) string

type ResponseError

type ResponseError struct {
	// contains filtered or unexported fields
}

ResponseError is an error that can be returned from a call to Write. It contains the underlying error and the optional message send to the client. Unwrap can be used to get the underlying error, and Error can be used to get the message sent to the client.

func (ResponseError) Error

func (e ResponseError) Error() string

func (ResponseError) Unwrap

func (e ResponseError) Unwrap() error