README
¶
JSON-RPC 2.0 clientrpc transport
jsonrpc package implements JSON-RPC
2.0 clients and servers for automating a
Bison Relay client activities, such as writing bots, interfacing with third
party systems, and so on.
The server side of this package runs inside BR clients (such as brclient) while the client side may be used by other applications, such as bot daemons, to connect to and perform BR-related operations (such as sending and receiving PMs, GC messages, etc).
End-users are generally interested in the client side of this package. Currently, a single client mode is provided, which uses a websockets-based transport. This transport allows both unary requests and client-initiated server streams (requests where the server may stream data back to the client at arbitrary times).
Example Client
Following is the simplest example for creating a new client, connecting to a brclient instance with the JSON-RPC enabled and using client certficate authentication. Error handling is omitted for brevity:
c, _ := jsonrpc.NewWSClient(
jsonrpc.WithWebsocketURL("wss://127.0.0.1:7676"),
jsonrpc.WithServerTLSCertPath("/path/to/rpc.cert"),
jsonrpc.WithClientTLSCert("/path/to/rpc-client.cert",
"/path/to/rpc-client.key"),
)
go c.Run(context.Background())
vc := types.NewVersionServiceClient(c)
res := &types.VersionResponse{}
_ = vc.Version(context.Background(), nil, res)
fmt.Println(res)
Example curl call
$ curl \
--cert ~/.brclient/rpc-client.cert \
--key ~/.brclient/rpc-client.key \
--cacert ~/.brclient/rpc.cert \
--data-binary '{"jsonrpc":"2.0","id":"dummy_id","method":"VersionService.Version","params":{}}' \
https://127.0.0.1:7676/index
Documentation
¶
Index ¶
Constants ¶
const ( // Application defined error codes. ErrEOF = 10000 // JSON-RPC defined error codes. ErrParseError = -32700 ErrInvalidRequest = -32600 ErrMethodNotFound = -32601 ErrInvalidParams = -32602 ErrInternal = -32603 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ClientOption ¶
type ClientOption func(cfg *clientConfig)
ClientOption is a configuration option for JSON-RPC clients.
func WithClientLog ¶
func WithClientLog(log slog.Logger) ClientOption
WithClientLog defines the logger to use to log client-related debug messages.
func WithClientTLSCert ¶
func WithClientTLSCert(certPath, keyPath string) ClientOption
WithClientTLSCert defines the path to the client certificate and key to use to authenticate against the server. If the server requires client authentication, then providing this option is necessary.
func WithServerTLSCertPath ¶
func WithServerTLSCertPath(certPath string) ClientOption
WithServerTLSCertPath defines the path to the certificate file to use to connect to the server. If this option is not defined, only system certificates will be used to verify the server connection.
func WithWebsocketURL ¶
func WithWebsocketURL(url string) ClientOption
WithWebsocketURL defines the URL to use to connect to the clientrpc server.
type Error ¶
type Error struct {
Code ErrorCode `json:"code"`
Message string `json:"message"`
Data interface{} `json:"data,omitempty"`
}
Error is a JSON-RPC error response.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is a JSON-RPC 2.0 server. It supports both POST-based and websockets-based requests.
func NewServer ¶
func NewServer(options ...ServerOption) *Server
NewServer returns a new JSON-RPC server.
This is usually only used inside Bison Relay clients.
type ServerOption ¶
type ServerOption func(*serverConfig)
ServerOption defines an option when configuring a JSON-RPC server.
func WithListeners ¶
func WithListeners(listeners []net.Listener) ServerOption
WithListeners defines which listeners to bind the server to. The listeners must have been configured with TLS, client-side authentication or any other needed configuration.
func WithServerLog ¶
func WithServerLog(log slog.Logger) ServerOption
WithServerLog defines the logger to use to log server debug messages.
func WithServices ¶
func WithServices(s *types.ServersMap) ServerOption
WithServices defines the service map to use on the server. Services may be added or removed from this as needed.
type WSClient ¶
type WSClient struct {
// contains filtered or unexported fields
}
WSClient is a websockets-based bidirectional JSON-RPC 2.0 client. It can connect to compatible servers to perform requests.
After it is started by its [Run] method, the client will attempt to maintain a connection to the server to be able to perform its requests.
func NewWSClient ¶
func NewWSClient(options ...ClientOption) (*WSClient, error)
NewWSClient creates a new Websockets-based JSON-RPC 2.0 client.
func (*WSClient) Request ¶
Request performs a unary request to the server, filling in the passed response object.
The request will fail with an error if the connection drops before the response is received.
func (*WSClient) Stream ¶
func (c *WSClient) Stream(ctx context.Context, method string, params proto.Message) (types.ClientStream, error)
Stream performs a streaming request to the server. It returns a stream from which individual responses can be read.
The stream closes when the passed context is closed, when the server sends and error (including EOF at the end of the stream) or when the connection to the server on which the request was made is broken.
Source Files