jrpc

Documentation

Overview

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

Index

• Constants
• Variables
• func Call[Q any, T any](url *Destination, payload *T) (*Q, error)
• func CallNoPayload[Q any](url *Destination) (*Q, error)
• func CallNoPayloadURL[Q any](url string) (*Q, error)
• func CallURL[Q any, T any](url string, payload *T) (*Q, error)
• func CallWithPayload[Q any](url *Destination, 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 *Destination) (int, []byte, error)
• func FetchURL(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(dest *Destination, jsonPayload []byte) (int, []byte, error)
• func Serialize(obj interface{}) ([]byte, error)
• func SetCallTimeout(t time.Duration) time.Duration
• func SetHeaderIfMissing(headers http.Header, name, value string)
• type Destination
  • func NewDestination(url string) *Destination
• type FetchError
  • func (fe *FetchError) Error() string
  • func (fe *FetchError) Unwrap() error
• type ServerReply
  • func NewErrorReply(message string, err error) *ServerReply

Constants

const (
	UserAgentHeader = "User-Agent"
)

Variables

var UserAgent = "fortio.org/fortio-" + version.Short()

UserAgent is the User-Agent header used by client calls (also used in fhttp/).

Functions

func Call

func Call[Q any, T any](url *Destination, 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 *Destination) (*Q, error)

CallNoPayload is for an API call without json payload.

func CallNoPayloadURL

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

func CallURL

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

CallURL is Call without any options/non default headers, timeout etc and just the URL.

func CallWithPayload

func CallWithPayload[Q any](url *Destination, 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 *Destination) (int, []byte, error)

func FetchURL

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

FetchURL is Send without a payload and no additional options (default timeout and headers).

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(dest *Destination, jsonPayload []byte) (int, []byte, error)

Send fetches the result from url and sends 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). Value is used when a timeout isn't passed in the options. Note this is not thread safe, use Destination.Timeout for changing values outside of main/single thread.

func SetHeaderIfMissing

func SetHeaderIfMissing(headers http.Header, name, value string)

Types

type Destination

type Destination struct {
	URL     string
	Headers *http.Header
	Timeout time.Duration
}

Destination is the URL and optional additional headers.

func NewDestination

func NewDestination(url string) *Destination

NewDestination returns a Destination object set for the given url (and default/nil replacement headers and default global timeout).

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