jrpc

Documentation

Overview

Opiniated JSON RPC / REST style library. Facilitates web JSON calls, using generics to serialize/deserialize any type.

Index

• func Call[Q any, T any](url string, payload *T) (*Q, error)
• func CallNoPayload[Q any](url string) (*Q, error)
• func CallWithPayload[Q any](url string, bytes []byte) (*Q, error)
• func DebugSummary(buf []byte, max int) string
• func Deserialize[Q any](bytes []byte) (*Q, error)
• func EscapeBytes(buf []byte) string
• func Fetch(url string) (int, []byte, error)
• func HandleCall[Q any](w http.ResponseWriter, r *http.Request) (*Q, error)
• func Reply[T any](w http.ResponseWriter, code int, data *T) error
• func ReplyClientError[T any](w http.ResponseWriter, data *T) error
• func ReplyError(w http.ResponseWriter, extraMsg string, err error) error
• func ReplyNoPayload(w http.ResponseWriter, code int) error
• func ReplyOk[T any](w http.ResponseWriter, data *T) error
• func ReplyServerError[T any](w http.ResponseWriter, data *T) error
• func Send(url string, jsonPayload []byte) (int, []byte, error)
• func Serialize(obj interface{}) ([]byte, error)
• func SetCallTimeout(t time.Duration) time.Duration
• type FetchError
  • func (fe *FetchError) Error() string
  • func (fe *FetchError) Unwrap() error
• type ServerReply
  • func NewErrorReply(message string, err error) *ServerReply

Functions

func Call

func Call[Q any, T any](url string, payload *T) (*Q, error)

Call calls the url endpoint, POSTing a serialized as json optional payload (pass nil for a GET http request) and returns the result, deserializing json into type Q. T can be inferred so we declare Response Q first.

func CallNoPayload

func CallNoPayload[Q any](url string) (*Q, error)

CallNoPayload is for an API call without json payload.

func CallWithPayload

func CallWithPayload[Q any](url string, bytes []byte) (*Q, error)

CallWithPayload is for cases where the payload is already serialized (or empty).

func DebugSummary

func DebugSummary(buf []byte, max int) string

DebugSummary returns a string with the size and escaped first max/2 and last max/2 bytes of a buffer (or the whole escaped buffer if small enough).

func Deserialize

func Deserialize[Q any](bytes []byte) (*Q, error)

func EscapeBytes

func EscapeBytes(buf []byte) string

EscapeBytes returns printable string. Same as %q format without the surrounding/extra "".

func Fetch

func Fetch(url string) (int, []byte, error)

Fetch is Send without a payload.

func HandleCall

func HandleCall[Q any](w http.ResponseWriter, r *http.Request) (*Q, error)

func Reply

func Reply[T any](w http.ResponseWriter, code int, data *T) error

Reply a struct as json (or just writes desired code).

func ReplyClientError

func ReplyClientError[T any](w http.ResponseWriter, data *T) error

func ReplyError

func ReplyError(w http.ResponseWriter, extraMsg string, err error) error

func ReplyNoPayload

func ReplyNoPayload(w http.ResponseWriter, code int) error

func ReplyOk

func ReplyOk[T any](w http.ResponseWriter, data *T) error

func ReplyServerError

func ReplyServerError[T any](w http.ResponseWriter, data *T) error

func Send

func Send(url string, jsonPayload []byte) (int, []byte, error)

Send fetches the result from url and sending optional payload as a POST, GET if missing. Returns the http code (if no other error before then, -1 if there are errors), the bytes from the reply and error if any.

func Serialize

func Serialize(obj interface{}) ([]byte, error)

func SetCallTimeout

func SetCallTimeout(t time.Duration) time.Duration

SetCallTimeout changes the timeout for further Call calls, returns the previous value (default in 60s).

Types

type FetchError

type FetchError struct {
	Message string
	// HTTP code if present, -1 for other errors.
	Code int
	// Original (wrapped) error if any
	Err error
	// Original reply payload if any
	Bytes []byte
}

FetchError is a custom error type that preserves http result code if obtained.

func (*FetchError) Error

func (fe *FetchError) Error() string

func (*FetchError) Unwrap

func (fe *FetchError) Unwrap() error

type ServerReply

type ServerReply struct {
	Error     bool   `json:"error,omitempty"` // Success if false/omitted, Error/Failure when true
	Message   string `json:"message,omitempty"`
	Exception string `json:"exception,omitempty"`
}

func NewErrorReply

func NewErrorReply(message string, err error) *ServerReply