jsonrpc

go-jsonrpc

This package provides JsonRPC 2.0 implementation based on interfaces with easy components extending.

Installation and usage

The import path for the package is github.com/tarampampam/go-jsonrpc.

To install it, run:

go get github.com/tarampampam/go-jsonrpc

API documentation can be found here.

Usage example

Working examples can be found in examples directory.

RPC methods definition is very simple:

package main

import "github.com/tarampampam/go-jsonrpc"

type myRpcMethod struct{} // Implements `jsonrpc.Method` interface

// GetParamsType says to Router a structure (or nil) which must be used for params parsing (fields, etc.).
func (*myRpcMethod) GetParamsType() interface{} { return nil }

// GetName returns method name in string representation.
func (*myRpcMethod) GetName() string { return "my.method" }

// Handle will be called by Router when method with current name will be requested.
func (*myRpcMethod) Handle(_ interface{}) (interface{}, jsonrpc.Error) {
	return "your method response", nil
}

You can define method params as a structure too:

package main

import "errors"

type (
    myRpcMethod struct{} // Implements `jsonrpc.Method` interface

    myRpcMethodParams struct { // Implements `jsonrpc.Validator` interface
        Number     int     `json:"number"`
        IsOptional *string `json:"is_optional"` // optional value (can be nil)
    }
)

// Implement `jsonrpc.Validator` interface for easy incoming params validation
func (p *myRpcMethodParams) Validate() error {
	if p.Number <= 0 {
		return errors.New("number must be positive")
	}

	return nil // all is ok
}

// GetParamsType NOW returns structure for method params
func (*myRpcMethod) GetParamsType() interface{} { return &myRpcMethodParams{} }

// ...

And use use provided kernel and router:

package main

import (
	"fmt"

	"github.com/tarampampam/go-jsonrpc"
	rpcKernel "github.com/tarampampam/go-jsonrpc/kernel"
	rpcRouter "github.com/tarampampam/go-jsonrpc/router"
)

// ... methods and params definitions ...

func main () {
    // create router instance
	router := rpcRouter.New()

    // register our RPC method
    router.RegisterMethod(new(myRpcMethod))

    // create kernel using our router
    kernel := rpcKernel.New(router)

    // handle RPC request
    responseAsJSON := kernel.HandleJSONRequest([]byte(`{"jsonrpc":"2.0", "method":"ping", "id":1}`))

    fmt.Println(responseAsJSON)
}

Testing

For application testing we use built-in golang testing feature and docker-ce + docker-compose as develop environment. So, just write into your terminal after repository cloning:

$ make test

Changelog

Changes log can be found here.

Support

If you will find any package errors, please, make an issue in current repository.

License

This is open-sourced software licensed under the MIT License.