kit: Index | Files

package jsonrpc

import ""

Package jsonrpc provides a JSON RPC (v2.0) binding for endpoints. See


Package Files

client.go doc.go encode_decode.go error.go request_response_types.go server.go


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"

func DefaultErrorEncoder Uses

func DefaultErrorEncoder(_ 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 Uses

func DefaultRequestEncoder(_ context.Context, req interface{}) (json.RawMessage, error)

DefaultRequestEncoder marshals the given request to JSON.

func DefaultResponseDecoder Uses

func DefaultResponseDecoder(_ context.Context, res Response) (interface{}, error)

DefaultResponseDecoder unmarshals the result to interface{}, or returns an error, if found.

func ErrorMessage Uses

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.

type Client Uses

type Client struct {
    // contains filtered or unexported fields

Client wraps a JSON RPC method and provides a method that implements endpoint.Endpoint.

func NewClient Uses

func NewClient(
    tgt *url.URL,
    method string,
    options ...ClientOption,
) *Client

NewClient constructs a usable Client for a single remote method.

func (Client) Endpoint Uses

func (c Client) Endpoint() endpoint.Endpoint

Endpoint returns a usable endpoint that invokes the remote endpoint.

type ClientFinalizerFunc Uses

type ClientFinalizerFunc func(ctx context.Context, err error)

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 ClientOption Uses

type ClientOption func(*Client)

ClientOption sets an optional parameter for clients.

func BufferedStream Uses

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 Uses

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 Uses

func ClientBefore(before ...httptransport.RequestFunc) ClientOption

ClientBefore sets the RequestFuncs that are applied to the outgoing HTTP request before it's invoked.

func ClientFinalizer Uses

func ClientFinalizer(f httptransport.ClientFinalizerFunc) ClientOption

ClientFinalizer is executed at the end of every HTTP request. By default, no finalizer is registered.

func ClientRequestEncoder Uses

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 Uses

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 Uses

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 Uses

func SetClient(client httptransport.HTTPClient) ClientOption

SetClient sets the underlying HTTP client used for requests. By default, http.DefaultClient is used.

type DecodeRequestFunc Uses

type DecodeRequestFunc func(context.Context, json.RawMessage) (request interface{}, err error)

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 DecodeResponseFunc Uses

type DecodeResponseFunc func(context.Context, Response) (response 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 EncodeRequestFunc Uses

type EncodeRequestFunc func(context.Context, interface{}) (request json.RawMessage, 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 EncodeResponseFunc Uses

type EncodeResponseFunc func(context.Context, interface{}) (response 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 EndpointCodec Uses

type EndpointCodec struct {
    Endpoint endpoint.Endpoint
    Decode   DecodeRequestFunc
    Encode   EncodeResponseFunc

EndpointCodec defines a server Endpoint and its associated codecs

type EndpointCodecMap Uses

type EndpointCodecMap map[string]EndpointCodec

EndpointCodecMap maps the Request.Method to the proper EndpointCodec

type Error Uses

type Error struct {
    Code    int         `json:"code"`
    Message string      `json:"message"`
    Data    interface{} `json:"data,omitempty"`

Error defines a JSON RPC error that can be returned in a Response from the spec

func (Error) Error Uses

func (e Error) Error() string

Error implements error.

func (Error) ErrorCode Uses

func (e Error) ErrorCode() int

ErrorCode returns the JSON RPC error code associated with the error.

type ErrorCoder Uses

type ErrorCoder interface {
    ErrorCode() int

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 Request Uses

type Request struct {
    JSONRPC string          `json:"jsonrpc"`
    Method  string          `json:"method"`
    Params  json.RawMessage `json:"params"`
    ID      *RequestID      `json:"id"`

Request defines a JSON RPC request from the spec

type RequestID Uses

type RequestID struct {
    // contains filtered or unexported fields

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.

func (*RequestID) Float32 Uses

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 (*RequestID) Int Uses

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 (*RequestID) MarshalJSON Uses

func (id *RequestID) MarshalJSON() ([]byte, error)

func (*RequestID) String Uses

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 (*RequestID) UnmarshalJSON Uses

func (id *RequestID) UnmarshalJSON(b []byte) error

UnmarshalJSON satisfies json.Unmarshaler

type RequestIDGenerator Uses

type RequestIDGenerator interface {
    Generate() interface{}

RequestIDGenerator returns an ID for the request.

func NewAutoIncrementID Uses

func NewAutoIncrementID(init uint64) RequestIDGenerator

NewAutoIncrementID returns an auto-incrementing request ID generator, initialised with the given value.

type Response Uses

type Response struct {
    JSONRPC string          `json:"jsonrpc"`
    Result  json.RawMessage `json:"result,omitempty"`
    Error   *Error          `json:"error,omitempty"`
    ID      *RequestID      `json:"id"`

Response defines a JSON RPC response from the spec

type Server Uses

type Server struct {
    // contains filtered or unexported fields

Server wraps an endpoint and implements http.Handler.

func NewServer Uses

func NewServer(
    ecm EndpointCodecMap,
    options ...ServerOption,
) *Server

NewServer constructs a new server, which implements http.Server.

func (Server) ServeHTTP Uses

func (s Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler.

type ServerOption Uses

type ServerOption func(*Server)

ServerOption sets an optional parameter for servers.

func ServerAfter Uses

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 Uses

func ServerBefore(before ...httptransport.RequestFunc) ServerOption

ServerBefore functions are executed on the HTTP request object before the request is decoded.

func ServerErrorEncoder Uses

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 Uses

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 Uses

func ServerFinalizer(f httptransport.ServerFinalizerFunc) ServerOption

ServerFinalizer is executed at the end of every HTTP request. By default, no finalizer is registered.

Package jsonrpc imports 12 packages (graph) and is imported by 2 packages. Updated 2018-08-23. Refresh now. Tools for package owners.