gototo

README

Gototo

Documentation

https://godoc.org/github.com/JeremyOT/gototo.

Documentation

Index

• Constants
• Variables
• func ClientMarshalJSON(req *Request) (data []byte, err error)
• func ClientUnmarshalJSON(buf []byte) (data interface{}, err error)
• func ConvertValue(inputType reflect.Type, input interface{}, customUnpack bool, ...) (output reflect.Value, err error)
• type ClientMarshalFunction
• type ClientUnmarshalFunction
• type CodedError
  • func NewCodedError(message string, code int) CodedError
• type ConverterFunction
  • func CreateConverter(i interface{}, wrappedInResponse bool, convertTypeDecoderConfig *DecoderConfig, ...) ConverterFunction
• type DecodeHookFunc
• type DecoderConfig
• type MarshalFunction
• type Request
  • func UnmarshalJSON(buf []byte) (data *Request, err error)
• type RequestOptions
• type Response
  • func CreateErrorResponse(err error) *Response
  • func CreateResponse(result interface{}, err error) *Response
  • func CreateSuccessResponse(result interface{}) *Response
• type ResponseError
  • func (err *ResponseError) Code() int
  • func (err *ResponseError) Error() string
  • func (err *ResponseError) Timeout() bool
• type UnmarshalFunction
• type Unpacker
• type Validator
• type Worker
• type WorkerConnection
• type WorkerFunction
  • func MakeWorkerFunction(workerFunction interface{}, convertTypeDecoderConfig *DecoderConfig, ...) WorkerFunction

Constants

const (
	// CodeDecodeFailed type conversion failed
	CodeDecodeFailed = -50
	// CodeValidationFailed post-decode type validation failed
	CodeValidationFailed = -51
)

Variables

var ErrTimeout = &ResponseError{text: "Request timed out", timeout: true}

ErrTimeout is returned whenever a request times out and has no remaining retries.

var GlobalDefaultRequestOptions = RequestOptions{}

GlobalDefaultRequestOptions allows global defaults to be set for requests. It will be used when requests are invoked with Call and no method defaults are set.

Functions

func ClientMarshalJSON

func ClientMarshalJSON(req *Request) (data []byte, err error)

func ClientUnmarshalJSON

func ClientUnmarshalJSON(buf []byte) (data interface{}, err error)

func ConvertValue

func ConvertValue(inputType reflect.Type, input interface{}, customUnpack bool, baseConfig *DecoderConfig, defaultTagName string) (output reflect.Value, err error)

ConvertValue converts input (e.g. a map[string]interface{}) to an instance of inputType.

Types

type ClientMarshalFunction

type ClientMarshalFunction func(req *Request) ([]byte, error)

ClientMarshalFunction converts a Request into a bytgototo.e slice to send to worker

type ClientUnmarshalFunction

type ClientUnmarshalFunction func([]byte) (interface{}, error)

ClientUnmarshalFunction converts a byte slice to an interface response.

type CodedError

type CodedError interface {
	error
	Code() int
}

CodedError conforms to the error interface, but supports an additional response code.

func NewCodedError

func NewCodedError(message string, code int) CodedError

NewCodedError creates a new error with the given message and code.

type ConverterFunction

type ConverterFunction func(interface{}) (interface{}, error)

func CreateConverter

func CreateConverter(i interface{}, wrappedInResponse bool, convertTypeDecoderConfig *DecoderConfig, convertTypeTagName string) ConverterFunction

type DecodeHookFunc

type DecodeHookFunc interface{}

DecodeHookFunc is the callback function that can be used for data transformations. See "DecodeHook" in the DecoderConfig struct.

The type should be DecodeHookFuncType or DecodeHookFuncKind. Either is accepted. Types are a superset of Kinds (Types can return Kinds) and are generally a richer thing to use, but Kinds are simpler if you only need those.

The reason DecodeHookFunc is multi-typed is for backwards compatibility: we started with Kinds and then realized Types were the better solution, but have a promise to not break backwards compat so we now support both.

From github.com/mitchellh/mapstructure

type DecoderConfig

type DecoderConfig struct {
	// DecodeHook, if set, will be called before any decoding and any
	// type conversion (if WeaklyTypedInput is on). This lets you modify
	// the values before they're set down onto the resulting struct.
	//
	// If an error is returned, the entire decode will fail with that
	// error.
	//
	// From github.com/mitchellh/mapstructure
	DecodeHook DecodeHookFunc

	// If ErrorUnused is true, then it is an error for there to exist
	// keys in the original map that were unused in the decoding process
	// (extra keys).
	//
	// From github.com/mitchellh/mapstructure
	ErrorUnused bool

	// ZeroFields, if set to true, will zero fields before writing them.
	// For example, a map will be emptied before decoded values are put in
	// it. If this is false, a map will be merged.
	//
	// From github.com/mitchellh/mapstructure
	ZeroFields bool

	// If WeaklyTypedInput is true, the decoder will make the following
	// "weak" conversions:
	//
	//   - bools to string (true = "1", false = "0")
	//   - numbers to string (base 10)
	//   - bools to int/uint (true = 1, false = 0)
	//   - strings to int/uint (base implied by prefix)
	//   - int to bool (true if value != 0)
	//   - string to bool (accepts: 1, t, T, TRUE, true, True, 0, f, F,
	//     FALSE, false, False. Anything else is an error)
	//   - empty array = empty map and vice versa
	//   - negative numbers to overflowed uint values (base 10)
	//
	//
	// From github.com/mitchellh/mapstructure
	WeaklyTypedInput bool

	// Result is a pointer to the struct that will contain the decoded
	// value.
	//
	// From github.com/mitchellh/mapstructure
	Result interface{}

	// The tag name that mapstructure reads for field names. This
	// defaults to "mapstructure"
	//
	// From github.com/mitchellh/mapstructure
	TagName string
}

DecoderConfig is the configuration that is used to create a new decoder and allows customization of various aspects of decoding.

From github.com/mitchellh/mapstructure

type MarshalFunction

type MarshalFunction func(interface{}) ([]byte, error)

MarshalFunction converts the result of a WorkerFunction to a byte slice to be sent back to the caller.

type Request

type Request struct {
	Method     string      `json:"method"`
	Parameters interface{} `json:"parameters"`
}

Request is a general request container. It has a Method identifier and Parameters.

func UnmarshalJSON

func UnmarshalJSON(buf []byte) (data *Request, err error)

UnmarshalJSON in an UnmarshalFunction for JSON

type RequestOptions

type RequestOptions struct {
	// Timeout specifies a timeout for request. It will be retried if there have been
	// less than RetryCount attempts. Otherwise ErrTimeout will be returned.
	Timeout time.Duration `json:"timeout"`
	// RetryCount specifies the maximum number of retries to attempt when a request
	// times out. Retrying does not cancel existing requests and the first response
	// will be returned to the caller.
	RetryCount int `json:"retry_count"`
}

RequestOptions may be used to set additional parameters when calling remote methods.

type Response

type Response struct {
	Success   bool        `json:"success"`
	Error     string      `json:"error,omitempty"`
	ErrorCode int         `json:"error_code,omitempty"`
	Result    interface{} `json:"result,omitempty"`
}

Response is a general response container that will be returned with Success = false if any errors are encountered while attempting to call a type safe function.

func CreateErrorResponse

func CreateErrorResponse(err error) *Response

CreateErrorResponse creates a new response based on an error. If err is nil, then the response signify success. Otherwise it will be initialized with the error text.

func CreateResponse

func CreateResponse(result interface{}, err error) *Response

CreateResponse creates a new response based on the supplied result and error. If err is nil, then the response will contain the supplied result. Otherwise it will be initialized with the error text.

func CreateSuccessResponse

func CreateSuccessResponse(result interface{}) *Response

CreateSuccessResponse creates a new successful response with the supplied parameter stored in its Result field.

type ResponseError

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

func (*ResponseError) Code

func (err *ResponseError) Code() int

Code returns the error code from the error

func (*ResponseError) Error

func (err *ResponseError) Error() string

Error returns the message from the error

func (*ResponseError) Timeout

func (err *ResponseError) Timeout() bool

Timeout returns true if the error was caused by a timeout

type UnmarshalFunction

type UnmarshalFunction func([]byte) (*Request, error)

UnmarshalFunction converts a byte slice to a worker invocation payload.

type Unpacker

type Unpacker interface {
	Unpack(interface{}) error
}

Unpacker allows custom translation of request objects before calling type safe functions. Before calling a type safe function, Unpack() will be called on a new instance of the parameter type. Note that mapstructure will not be used if this interface is implemented.

type Validator

type Validator interface {
	Validate() error
}

Validator allows automatic validation when calling type safe functions. If implemented by the type passed as an argument, Type.Validate() will be called before calling the worker function. If an error is returned then that error will be sent in response to the worker request and the method will not be called.

type Worker

type Worker interface {
	// Stop stops the worker and waits until it is completely shutdown
	Stop()
	// Quit stops the worker asynchronously
	Quit()
	Wait()
	SetMarshalFunction(marshal MarshalFunction)
	SetUnmarshalFunction(unmarshal UnmarshalFunction)
	SetConvertTypeTagName(tagName string)
	SetConvertTypeDecoderConfig(config *DecoderConfig)
	RegisterWorkerFunction(name string, workerFunction WorkerFunction)
	SetLogMetrics(logMetrics bool)

	// ConvertValue is a convenience method for converting a received interface{} to a specified type. It may
	// be used e.g. when a JSON request is parsed to a map[string]interface{} and you want to turn it into
	// a struct.
	ConvertValue(inputType reflect.Type, input interface{}) (output interface{}, err error)

	// MakeWorkerFunction creates a wrapper around a function that allows a function to be
	// called in a type safe manner. The function is expected to take a pointer to a struct
	// as its only argument and return one value. Internally, github.com/mitchellh/mapstructure
	// is used to convert the input parameters to a struct. MakeWorkerFunction will panic
	// if called with an incorrect type.
	MakeWorkerFunction(workerFunction interface{}) WorkerFunction

	// Start runs the worker in a new go routine
	Start() (err error)

	// Run runs the worker synchronously
	Run() (err error)
}

Worker is an RPC server. Functions registered with the worker may be called by a connected WorkerConnection.

type WorkerConnection

type WorkerConnection interface {

	// SetMarshalFunction sets the function used to marshal requests for transmission.
	SetMarshalFunction(marshal ClientMarshalFunction)

	SetUnmarshalFunction(unmarshal ClientUnmarshalFunction)

	// SetConvertTypeTagName sets the tag name to use to find field information when
	// converting request parameters to custom types. By default this is "json"
	SetConvertTypeTagName(tagName string)

	// SetConvertTypeDecoderConfig sets the mapstructure config to use when decoding.
	// if set, it takes precidence over SetConvertTypeTagName
	SetConvertTypeDecoderConfig(config *DecoderConfig)

	// RegisterResponseType ensures that responses from calls to the named method are converted
	// to the proper type before being returned to the caller. If wrappedInResponse is true then
	// the response will be parsed into a Response struct before reading the result from
	// Response.Result and any error from the Response will be returned as an *ResponseError from the
	// ConverterFunction.
	RegisterResponseType(method string, i interface{}, wrappedInResponse bool)

	// RegisterDefaultOptions sets the options that will be used whenever Call is used for a given method.
	// This does not affect CallWithOptions.
	RegisterDefaultOptions(method string, options *RequestOptions)

	// ConvertValue is a convenience method for converting a received interface{} to a specified type. It may
	// be used e.g. when a JSON response is parsed to a map[string]interface{} and you want to turn it into
	// a struct.
	ConvertValue(inputType reflect.Type, input interface{}) (output interface{}, err error)

	// PendingRequestCount returns the number of requests currently awaiting responses
	PendingRequestCount() int

	// GetEndpoints returns all endpoints that the WorkerConnection is connected to.
	GetEndpoints() (endpoints []string)

	// Connect connects to a new endpoint
	Connect(endpoint string) error

	// Disconnect disconnects from an existing endpoint
	Disconnect(endpoint string) error

	// SetEndpoints connects to any new endpoints contained in the supplied list and disconnects
	// from any current endpoints not in the list.
	SetEndpoints(endpoint ...string) error

	// Call calls a method on a worker and blocks until it receives a response. Use RegisterResponseType to automatically
	// convert responses into the correct type. Use RegisterDefaultOptions to set a RequestOptions to use with a given
	// method.
	Call(method string, parameters interface{}) (response interface{}, err error)

	// CallWithOptions calls a method on a worker and blocks until it receives a response. Use RegisterResponseType to automatically
	// convert responses into the correct type. This method is like Call but allows the caller to specify RequestOptions.
	CallWithOptions(method string, parameters interface{}, options *RequestOptions) (response interface{}, err error)
}

WorkerConnection is used to make RPCs to remote workers. If multiple workers are connected, requests will be round-robin load balanced between them.

type WorkerFunction

type WorkerFunction func(interface{}) interface{}

WorkerFunction may be registered with a worker

func MakeWorkerFunction

func MakeWorkerFunction(workerFunction interface{}, convertTypeDecoderConfig *DecoderConfig, convertTypeTagName string) WorkerFunction

MakeWorkerFunction creates a wrapper around a function that allows a function to be called in a type safe manner. The function is expected to take a pointer to a struct as its only argument and return one value. Internally, github.com/mitchellh/mapstructure is used to convert the input parameters to a struct. MakeWorkerFunction will panic if called with an incorrect type.