const (
// ParseError defines invalid JSON was received by the server.
// An error occurred on the server while parsing the JSON text.
ParseError int = -32700
// InvalidRequestError defines the JSON sent is not a valid Request object.
InvalidRequestError int = -32600
// MethodNotFoundError defines the method does not exist / is not available.
MethodNotFoundError int = -32601
// InvalidParamsError defines invalid method parameter(s).
InvalidParamsError int = -32602
// InternalError defines a server error
InternalError int = -32603
)
const (
// Version defines the version of the JSON RPC implementation
Version string = "2.0"
// ContentType defines the content type to be served.
ContentType string = "application/json; charset=utf-8"
)
const (
ContextKeyRequestMethod contextKey = iota
)
func DefaultErrorEncoder(ctx context.Context, err error, w http.ResponseWriter)
DefaultErrorEncoder writes the error to the ResponseWriter, as a json-rpc error response, with an InternalError status code. The Error() string of the error will be used as the response error message. If the error implements ErrorCoder, the provided code will be set on the response error. If the error implements Headerer, the given headers will be set.
func DefaultRequestEncoder(_ context.Context, req interface{}) (json.RawMessage, error)
DefaultRequestEncoder marshals the given request to JSON.
func DefaultResponseDecoder(_ context.Context, res Response) (interface{}, error)
DefaultResponseDecoder unmarshals the result to interface{}, or returns an error, if found.
func ErrorMessage(code int) string
ErrorMessage returns a message for the JSON RPC error code. It returns the empty string if the code is unknown.
Client wraps a JSON RPC method and provides a method that implements endpoint.Endpoint.
type Client struct {
// contains filtered or unexported fields
}
func NewClient(
tgt *url.URL,
method string,
options ...ClientOption,
) *Client
NewClient constructs a usable Client for a single remote method.
func (c Client) Endpoint() endpoint.Endpoint
Endpoint returns a usable endpoint that invokes the remote endpoint.
ClientFinalizerFunc can be used to perform work at the end of a client HTTP request, after the response is returned. The principal intended use is for error logging. Additional response parameters are provided in the context under keys with the ContextKeyResponse prefix. Note: err may be nil. There maybe also no additional response parameters depending on when an error occurs.
type ClientFinalizerFunc func(ctx context.Context, err error)
ClientOption sets an optional parameter for clients.
type ClientOption func(*Client)
func BufferedStream(buffered bool) ClientOption
BufferedStream sets whether the Response.Body is left open, allowing it to be read from later. Useful for transporting a file as a buffered stream.
func ClientAfter(after ...httptransport.ClientResponseFunc) ClientOption
ClientAfter sets the ClientResponseFuncs applied to the server's HTTP response prior to it being decoded. This is useful for obtaining anything from the response and adding onto the context prior to decoding.
func ClientBefore(before ...httptransport.RequestFunc) ClientOption
ClientBefore sets the RequestFuncs that are applied to the outgoing HTTP request before it's invoked.
func ClientFinalizer(f httptransport.ClientFinalizerFunc) ClientOption
ClientFinalizer is executed at the end of every HTTP request. By default, no finalizer is registered.
func ClientRequestEncoder(enc EncodeRequestFunc) ClientOption
ClientRequestEncoder sets the func used to encode the request params to JSON. If not set, DefaultRequestEncoder is used.
func ClientRequestIDGenerator(g RequestIDGenerator) ClientOption
ClientRequestIDGenerator is executed before each request to generate an ID for the request. By default, AutoIncrementRequestID is used.
func ClientResponseDecoder(dec DecodeResponseFunc) ClientOption
ClientResponseDecoder sets the func used to decode the response params from JSON. If not set, DefaultResponseDecoder is used.
func SetClient(client httptransport.HTTPClient) ClientOption
SetClient sets the underlying HTTP client used for requests. By default, http.DefaultClient is used.
DecodeRequestFunc extracts a user-domain request object from raw JSON It's designed to be used in JSON RPC servers, for server-side endpoints. One straightforward DecodeRequestFunc could be something that unmarshals JSON from the request body to the concrete request type.
type DecodeRequestFunc func(context.Context, json.RawMessage) (request interface{}, err error)
DecodeResponseFunc extracts a user-domain response object from an JSON RPC response object. It's designed to be used in JSON RPC clients, for client-side endpoints. It is the responsibility of this function to decide whether any error present in the JSON RPC response should be surfaced to the client endpoint.
type DecodeResponseFunc func(context.Context, Response) (response interface{}, err error)
EncodeRequestFunc encodes the given request object to raw JSON. It's designed to be used in JSON RPC clients, for client-side endpoints. One straightforward EncodeResponseFunc could be something that JSON encodes the object directly.
type EncodeRequestFunc func(context.Context, interface{}) (request json.RawMessage, err error)
EncodeResponseFunc encodes the passed response object to a JSON RPC result. It's designed to be used in HTTP servers, for server-side endpoints. One straightforward EncodeResponseFunc could be something that JSON encodes the object directly.
type EncodeResponseFunc func(context.Context, interface{}) (response json.RawMessage, err error)
EndpointCodec defines a server Endpoint and its associated codecs
type EndpointCodec struct {
Endpoint endpoint.Endpoint
Decode DecodeRequestFunc
Encode EncodeResponseFunc
}
EndpointCodecMap maps the Request.Method to the proper EndpointCodec
type EndpointCodecMap map[string]EndpointCodec
Error defines a JSON RPC error that can be returned in a Response from the spec http://www.jsonrpc.org/specification#error_object
type Error struct {
Code int `json:"code"`
Message string `json:"message"`
Data interface{} `json:"data,omitempty"`
}
func (e Error) Error() string
Error implements error.
func (e Error) ErrorCode() int
ErrorCode returns the JSON RPC error code associated with the error.
ErrorCoder is checked by DefaultErrorEncoder. If an error value implements ErrorCoder, the integer result of ErrorCode() will be used as the JSONRPC error code when encoding the error.
By default, InternalError (-32603) is used.
type ErrorCoder interface {
ErrorCode() int
}
Request defines a JSON RPC request from the spec http://www.jsonrpc.org/specification#request_object
type Request struct {
JSONRPC string `json:"jsonrpc"`
Method string `json:"method"`
Params json.RawMessage `json:"params"`
ID *RequestID `json:"id"`
}
RequestFunc may take information from decoded json body and place in request context. In Servers, RequestFuncs are executed after json is parsed but prior to invoking the codec
type RequestFunc func(context.Context, *http.Request, Request) context.Context
RequestID defines a request ID that can be string, number, or null. An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null and Numbers SHOULD NOT contain fractional parts.
type RequestID struct {
// contains filtered or unexported fields
}
func (id *RequestID) Float32() (float32, error)
Float32 returns the ID as a float value. An error is returned if the ID can't be treated as an float.
func (id *RequestID) Int() (int, error)
Int returns the ID as an integer value. An error is returned if the ID can't be treated as an int.
func (id *RequestID) MarshalJSON() ([]byte, error)
func (id *RequestID) String() (string, error)
String returns the ID as a string value. An error is returned if the ID can't be treated as an string.
func (id *RequestID) UnmarshalJSON(b []byte) error
UnmarshalJSON satisfies json.Unmarshaler
RequestIDGenerator returns an ID for the request.
type RequestIDGenerator interface {
Generate() interface{}
}
func NewAutoIncrementID(init uint64) RequestIDGenerator
NewAutoIncrementID returns an auto-incrementing request ID generator, initialised with the given value.
Response defines a JSON RPC response from the spec http://www.jsonrpc.org/specification#response_object
type Response struct {
JSONRPC string `json:"jsonrpc"`
Result json.RawMessage `json:"result,omitempty"`
Error *Error `json:"error,omitempty"`
ID *RequestID `json:"id"`
}
Server wraps an endpoint and implements http.Handler.
type Server struct {
// contains filtered or unexported fields
}
func NewServer(
ecm EndpointCodecMap,
options ...ServerOption,
) *Server
NewServer constructs a new server, which implements http.Server.
func (s Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP implements http.Handler.
ServerOption sets an optional parameter for servers.
type ServerOption func(*Server)
func ServerAfter(after ...httptransport.ServerResponseFunc) ServerOption
ServerAfter functions are executed on the HTTP response writer after the endpoint is invoked, but before anything is written to the client.
func ServerBefore(before ...httptransport.RequestFunc) ServerOption
ServerBefore functions are executed on the HTTP request object before the request is decoded.
func ServerBeforeCodec(beforeCodec ...RequestFunc) ServerOption
ServerBeforeCodec functions are executed after the JSON request body has been decoded, but before the method's decoder is called. This provides an opportunity for middleware to inspect the contents of the rpc request before being passed to the codec.
func ServerErrorEncoder(ee httptransport.ErrorEncoder) ServerOption
ServerErrorEncoder is used to encode errors to the http.ResponseWriter whenever they're encountered in the processing of a request. Clients can use this to provide custom error formatting and response codes. By default, errors will be written with the DefaultErrorEncoder.
func ServerErrorLogger(logger log.Logger) ServerOption
ServerErrorLogger is used to log non-terminal errors. By default, no errors are logged. This is intended as a diagnostic measure. Finer-grained control of error handling, including logging in more detail, should be performed in a custom ServerErrorEncoder or ServerFinalizer, both of which have access to the context.
func ServerFinalizer(f httptransport.ServerFinalizerFunc) ServerOption
ServerFinalizer is executed at the end of every HTTP request. By default, no finalizer is registered.