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 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[Q any](url *Destination, bytes []byte) (*Q, error)
• func FetchBytes(url *Destination) (int, []byte, error)
• func FetchURL(url string) (int, []byte, error)
• func Get[Q any](url *Destination) (*Q, error)
• func GetArray[Q any](url *Destination) ([]Q, error)
• func GetURL[Q any](url string) (*Q, 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)

Deprecated: CallNoPayload is for an API call without json payload. Use Get() instead.

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)

Deprecated: CallWithPayload use Fetch() instead.

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)

Deserialize deserializes json as a new object of desired type.

func EscapeBytes

func EscapeBytes(buf []byte) string

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

func Fetch

func Fetch[Q any](url *Destination, bytes []byte) (*Q, error)

Fetch is for cases where the payload is already serialized (or empty but call Get() when empty for clarity). Note that if you're looking for the []byte version instead of this generics version, it's now called FetchBytes().

func FetchBytes

func FetchBytes(url *Destination) (int, []byte, error)

Fetch is Send without a payload (so will be a GET request). Used to be called Fetch() but we needed that shorter name to simplify the former CallWithPayload function name.

func FetchURL

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

FetchURL is Send without a payload and no additional options (default timeout and headers). Technically this should be called FetchBytesURL().

func Get

func Get[Q any](url *Destination) (*Q, error)

Get fetches and deseializes the JSON returned by the Destination into a Q struct. Used when there is no json payload to send.

func GetArray

func GetArray[Q any](url *Destination) ([]Q, error)

GetArray fetches and deseializes the JSON returned by the Destination into a slice of Q struct (ie the response is a json array).

func GetURL

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

GetURL is Get without additional options (default timeout and headers).

func HandleCall

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

HandleCall deserializes the expected type from the request body. Sample usage code:

req, err := jrpc.HandleCall[Request](w, r)
if err != nil {
    _ = jrpc.ReplyError(w, "request error", err)
}

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

ReplyClientError is a short cut for Reply() with http.StatusBadRequest as the result code.

func ReplyError

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

ReplyError is to send back a client error with exception details.

func ReplyNoPayload

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

ReplyNoPayload is a short cut for Reply() with empty (nil) payload.

func ReplyOk

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

ReplyOk is a short cut for Reply() with http.StatusOK as the result code.

func ReplyServerError

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

ReplyServerError is a short cut for Reply() with http.StatusServiceUnavailable as the result code.

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)

Serialize serializes the object as json.

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)

SetHeaderIfMissing utility function to not overwrite nor append to existing headers.

Types

type Destination

type Destination struct {
	URL string
	// Default is nil, which means no additional headers.
	Headers *http.Header
	// Default is 0 which means use global timeout.
	Timeout time.Duration
	// Default is "" which will use POST if there is a payload and GET otherwise.
	Method string
}

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"`
}

ServerReply is used to reply errors but can also be the base for Ok replies, see the unit tests `Response` and ../rapi for examples of use.

func NewErrorReply

func NewErrorReply(message string, err error) *ServerReply

NewErrorReply creates a new error reply with the message and err error.