client

Documentation

Overview

Package client provides some base Kwil rpc clients. JSONRPCClient is a JSON-RPC (API v1) client supports only HTTP POST, no WebSockets yet.

Index

• Constants
• Variables
• type ActionCallOption
  • func WithAuthCookie(cookie *http.Cookie) ActionCallOption
• type ActionCallOpts
• type BroadcastWait
• type JSONRPCClient
  • func NewJSONRPCClient(url *url.URL, opts ...RPCClientOpts) *JSONRPCClient
  • func (cl *JSONRPCClient) CallMethod(ctx context.Context, method string, cmd, res any) error
• type RPCClientOpts
  • func WithHTTPClient(client *http.Client) RPCClientOpts
  • func WithLogger(log log.Logger) RPCClientOpts
• type RPCError
  • func (err RPCError) Error() string

Constants

const (
	BroadcastWaitAsync  = BroadcastWait(userjson.BroadcastSyncAsync)
	BroadcastWaitSync   = BroadcastWait(userjson.BroadcastSyncSync)
	BroadcastWaitCommit = BroadcastWait(userjson.BroadcastSyncCommit)
)

Variables

var (
	// ErrUnauthorized is returned when the client is not authenticated
	// It is the equivalent of http status code 401
	ErrUnauthorized   = errors.New("unauthorized")
	ErrNotFound       = errors.New("not found")
	ErrInvalidRequest = errors.New("invalid request")
	ErrNotAllowed     = errors.New("not allowed")
)

The following errors may be detected by consumers using errors.Is.

Types

type ActionCallOption

type ActionCallOption func(*ActionCallOpts)

func WithAuthCookie

func WithAuthCookie(cookie *http.Cookie) ActionCallOption

type ActionCallOpts

type ActionCallOpts struct {
	// authn cookie, for provider that supports cookie authn, now only for KGW
	// Call action(view action) is read oriented; for data privacy, a network needs
	// extra infra to protect the data. KGW is such infra using cookie authn.
	// NOTE: setting cookie this way means the cookie policy is not applied.
	// AuthCookies is a general way to use cookie in SDK when calling action.
	AuthCookies []*http.Cookie
}

ActionCallOpts is the options for action call. Currently only HTTP RPCClient supports this option.

type BroadcastWait

type BroadcastWait uint8

BroadcastWait is an argument type that indicates how long to wait when broadcasting a transaction. The levels are async (do not wait for mempool acceptance), sync (wait for mempool acceptance), and commit (wait for it to be included in a block).

type JSONRPCClient

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

JSONRPCClient is a JSON-RPC client that handles JSON RPC communication. It is a low-level client that does not care about the specifics of the JSON-RPC methods or responses.

func NewJSONRPCClient

func NewJSONRPCClient(url *url.URL, opts ...RPCClientOpts) *JSONRPCClient

NewJSONRPCClient creates a new JSONRPCClient for a provider at a given base URL of an HTTP server where the "/rpc/v1" rooted. i.e. The URL should not include "/rpc/v1" as that is appended automatically.

func (*JSONRPCClient) CallMethod

func (cl *JSONRPCClient) CallMethod(ctx context.Context, method string, cmd, res any) error

CallMethod makes a JSON-RPC request to the server. The method is the name of the method to call, cmd is the request parameter, and res is the response object. If the server returns a jsonrpc.Error, it's a business logic error.

type RPCClientOpts

type RPCClientOpts func(*clientOptions)

func WithHTTPClient

func WithHTTPClient(client *http.Client) RPCClientOpts

func WithLogger

func WithLogger(log log.Logger) RPCClientOpts

type RPCError

type RPCError struct {
	Msg  string
	Code int32
}

RPCError is a common error type used by any RPC client implementation to provide a detectable error to consumers using errors.As. We may define our own codes. Instances of RPCError may also be combined with other error types defined above using errors.Join.

func (RPCError) Error

func (err RPCError) Error() string