Documentation ¶
Index ¶
- Constants
- Variables
- type API
- type BatchElem
- type BlockNumber
- type BlockNumberOrHash
- type Client
- func ClientFromContext(ctx context.Context) (*Client, bool)
- func Dial(rawurl string) (*Client, error)
- func DialContext(ctx context.Context, rawurl string) (*Client, error)
- func DialHTTP(endpoint string) (*Client, error)
- func DialHTTPWithClient(endpoint string, client *http.Client) (*Client, error)
- func DialIO(ctx context.Context, in io.Reader, out io.Writer) (*Client, error)
- func DialIPC(ctx context.Context, endpoint string) (*Client, error)
- func DialInProc(handler *Server) *Client
- func DialStdIO(ctx context.Context) (*Client, error)
- func DialWebsocket(ctx context.Context, endpoint, origin string) (*Client, error)
- func DialWebsocketWithDialer(ctx context.Context, endpoint, origin string, dialer websocket.Dialer) (*Client, error)
- func (c *Client) BatchCall(b []BatchElem) error
- func (c *Client) BatchCallContext(ctx context.Context, b []BatchElem) error
- func (c *Client) Call(result interface{}, method string, args ...interface{}) error
- func (c *Client) CallContext(ctx context.Context, result interface{}, method string, args ...interface{}) error
- func (c *Client) Close()
- func (c *Client) EthSubscribe(ctx context.Context, channel interface{}, args ...interface{}) (*ClientSubscription, error)
- func (c *Client) Notify(ctx context.Context, method string, args ...interface{}) error
- func (c *Client) RegisterName(name string, receiver interface{}) error
- func (c *Client) ShhSubscribe(ctx context.Context, channel interface{}, args ...interface{}) (*ClientSubscription, error)
- func (c *Client) Subscribe(ctx context.Context, namespace string, channel interface{}, ...) (*ClientSubscription, error)
- func (c *Client) SupportedModules() (map[string]string, error)
- type ClientSubscription
- type CodecOptiondeprecated
- type Conn
- type ConnRemoteAddr
- type DataError
- type Error
- type HTTPTimeouts
- type ID
- type Notifier
- type RPCService
- type Server
- func (s *Server) RegisterName(name string, receiver interface{}) error
- func (s *Server) ServeCodec(codec ServerCodec, options CodecOption)
- func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (s *Server) ServeListener(l net.Listener) error
- func (s *Server) Stop()
- func (s *Server) WebsocketHandler(allowedOrigins []string) http.Handler
- type ServerCodec
- type Subscription
Examples ¶
Constants ¶
const ( PendingBlockNumber = BlockNumber(-2) LatestBlockNumber = BlockNumber(-1) EarliestBlockNumber = BlockNumber(0) )
const MetadataApi = "rpc"
Variables ¶
var ( ErrClientQuit = errors.New("client is closed") ErrNoResult = errors.New("no result in JSON-RPC response") ErrSubscriptionQueueOverflow = errors.New("subscription queue overflow") )
var ( // ErrNotificationsUnsupported is returned when the connection doesn't support notifications ErrNotificationsUnsupported = errors.New("notifications not supported") // ErrNotificationNotFound is returned when the notification for the given id is not found ErrSubscriptionNotFound = errors.New("subscription not found") )
var DefaultHTTPTimeouts = HTTPTimeouts{ ReadTimeout: 30 * time.Second, WriteTimeout: 30 * time.Second, IdleTimeout: 120 * time.Second, }
DefaultHTTPTimeouts represents the default timeout values used if further configuration is not provided.
Functions ¶
This section is empty.
Types ¶
type API ¶
type API struct { Namespace string // namespace under which the rpc methods of Service are exposed Version string // api version for DApp's Service interface{} // receiver instance which holds the methods Public bool // indication if the methods must be considered safe for public use }
API describes the set of methods offered over the RPC interface
type BatchElem ¶
type BatchElem struct { Method string Args []interface{} // The result is unmarshaled into this field. Result must be set to a // non-nil pointer value of the desired type, otherwise the response will be // discarded. Result interface{} // Error is set if the server returns an error for this request, or if // unmarshaling into Result fails. It is not set for I/O errors. Error error }
BatchElem is an element in a batch request.
type BlockNumber ¶
type BlockNumber int64
func (BlockNumber) Int64 ¶
func (bn BlockNumber) Int64() int64
func (*BlockNumber) UnmarshalJSON ¶
func (bn *BlockNumber) UnmarshalJSON(data []byte) error
UnmarshalJSON parses the given JSON fragment into a BlockNumber. It supports: - "latest", "earliest" or "pending" as string arguments - the block number Returned errors: - an invalid block number error when the given argument isn't a known strings - an out of range error when the given block number is either too little or too large
type BlockNumberOrHash ¶
type BlockNumberOrHash struct { BlockNumber *BlockNumber `json:"blockNumber,omitempty"` BlockHash *common.Hash `json:"blockHash,omitempty"` RequireCanonical bool `json:"requireCanonical,omitempty"` }
func BlockNumberOrHashWithHash ¶
func BlockNumberOrHashWithHash(hash common.Hash, canonical bool) BlockNumberOrHash
func BlockNumberOrHashWithNumber ¶
func BlockNumberOrHashWithNumber(blockNr BlockNumber) BlockNumberOrHash
func (*BlockNumberOrHash) Number ¶
func (bnh *BlockNumberOrHash) Number() (BlockNumber, bool)
func (*BlockNumberOrHash) UnmarshalJSON ¶
func (bnh *BlockNumberOrHash) UnmarshalJSON(data []byte) error
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client represents a connection to an RPC server.
func ClientFromContext ¶
Client retrieves the client from the context, if any. This can be used to perform 'reverse calls' in a handler method.
func Dial ¶
Dial creates a new client for the given URL.
The currently supported URL schemes are "http", "https", "ws" and "wss". If rawurl is a file name with no URL scheme, a local socket connection is established using UNIX domain sockets on supported platforms and named pipes on Windows. If you want to configure transport options, use DialHTTP, DialWebsocket or DialIPC instead.
For websocket connections, the origin is set to the local host name.
The client reconnects automatically if the connection is lost.
func DialContext ¶
DialContext creates a new RPC client, just like Dial.
The context is used to cancel or time out the initial connection establishment. It does not affect subsequent interactions with the client.
func DialHTTPWithClient ¶
DialHTTPWithClient creates a new RPC client that connects to an RPC server over HTTP using the provided HTTP Client.
func DialIPC ¶
DialIPC create a new IPC client that connects to the given endpoint. On Unix it assumes the endpoint is the full path to a unix socket, and Windows the endpoint is an identifier for a named pipe.
The context is used for the initial connection establishment. It does not affect subsequent interactions with the client.
func DialInProc ¶
DialInProc attaches an in-process connection to the given RPC server.
func DialWebsocket ¶
DialWebsocket creates a new RPC client that communicates with a JSON-RPC server that is listening on the given endpoint.
The context is used for the initial connection establishment. It does not affect subsequent interactions with the client.
func DialWebsocketWithDialer ¶
func DialWebsocketWithDialer(ctx context.Context, endpoint, origin string, dialer websocket.Dialer) (*Client, error)
DialWebsocketWithDialer creates a new RPC client that communicates with a JSON-RPC server that is listening on the given endpoint using the provided dialer.
func (*Client) BatchCall ¶
BatchCall sends all given requests as a single batch and waits for the server to return a response for all of them.
In contrast to Call, BatchCall only returns I/O errors. Any error specific to a request is reported through the Error field of the corresponding BatchElem.
Note that batch calls may not be executed atomically on the server side.
func (*Client) BatchCallContext ¶
BatchCall sends all given requests as a single batch and waits for the server to return a response for all of them. The wait duration is bounded by the context's deadline.
In contrast to CallContext, BatchCallContext only returns errors that have occurred while sending the request. Any error specific to a request is reported through the Error field of the corresponding BatchElem.
Note that batch calls may not be executed atomically on the server side.
func (*Client) Call ¶
Call performs a JSON-RPC call with the given arguments and unmarshals into result if no error occurred.
The result must be a pointer so that package json can unmarshal into it. You can also pass nil, in which case the result is ignored.
func (*Client) CallContext ¶
func (c *Client) CallContext(ctx context.Context, result interface{}, method string, args ...interface{}) error
CallContext performs a JSON-RPC call with the given arguments. If the context is canceled before the call has successfully returned, CallContext returns immediately.
The result must be a pointer so that package json can unmarshal into it. You can also pass nil, in which case the result is ignored.
func (*Client) Close ¶
func (c *Client) Close()
Close closes the client, aborting any in-flight requests.
func (*Client) EthSubscribe ¶
func (c *Client) EthSubscribe(ctx context.Context, channel interface{}, args ...interface{}) (*ClientSubscription, error)
EthSubscribe registers a subscripion under the "eth" namespace.
func (*Client) Notify ¶
Notify sends a notification, i.e. a method call that doesn't expect a response.
func (*Client) RegisterName ¶
RegisterName creates a service for the given receiver type under the given name. When no methods on the given receiver match the criteria to be either a RPC method or a subscription an error is returned. Otherwise a new service is created and added to the service collection this client provides to the server.
func (*Client) ShhSubscribe ¶
func (c *Client) ShhSubscribe(ctx context.Context, channel interface{}, args ...interface{}) (*ClientSubscription, error)
ShhSubscribe registers a subscripion under the "shh" namespace.
func (*Client) Subscribe ¶
func (c *Client) Subscribe(ctx context.Context, namespace string, channel interface{}, args ...interface{}) (*ClientSubscription, error)
Subscribe calls the "<namespace>_subscribe" method with the given arguments, registering a subscription. Server notifications for the subscription are sent to the given channel. The element type of the channel must match the expected type of content returned by the subscription.
The context argument cancels the RPC request that sets up the subscription but has no effect on the subscription after Subscribe has returned.
Slow subscribers will be dropped eventually. Client buffers up to 20000 notifications before considering the subscriber dead. The subscription Err channel will receive ErrSubscriptionQueueOverflow. Use a sufficiently large buffer on the channel or ensure that the channel usually has at least one reader to prevent this issue.
type ClientSubscription ¶
type ClientSubscription struct {
// contains filtered or unexported fields
}
ClientSubscription is a subscription established through the Client's Subscribe or EthSubscribe methods.
func (*ClientSubscription) Err ¶
func (sub *ClientSubscription) Err() <-chan error
Err returns the subscription error channel. The intended use of Err is to schedule resubscription when the client connection is closed unexpectedly.
The error channel receives a value when the subscription has ended due to an error. The received error is nil if Close has been called on the underlying client and no other error has occurred.
The error channel is closed when Unsubscribe is called on the subscription.
func (*ClientSubscription) Unsubscribe ¶
func (sub *ClientSubscription) Unsubscribe()
Unsubscribe unsubscribes the notification and closes the error channel. It can safely be called more than once.
type CodecOption
deprecated
type CodecOption int
CodecOption specifies which type of messages a codec supports.
Deprecated: this option is no longer honored by Server.
const ( // OptionMethodInvocation is an indication that the codec supports RPC method calls OptionMethodInvocation CodecOption = 1 << iota // OptionSubscriptions is an indication that the codec supports RPC notifications OptionSubscriptions = 1 << iota // support pub sub )
type Conn ¶
type Conn interface { io.ReadWriteCloser SetWriteDeadline(time.Time) error }
Conn is a subset of the methods of net.Conn which are sufficient for ServerCodec.
type ConnRemoteAddr ¶
type ConnRemoteAddr interface {
RemoteAddr() string
}
ConnRemoteAddr wraps the RemoteAddr operation, which returns a description of the peer address of a connection. If a Conn also implements ConnRemoteAddr, this description is used in log messages.
type DataError ¶
type DataError interface { Error() string // returns the message ErrorData() interface{} // returns the error data }
A DataError contains some data in addition to the error message.
type HTTPTimeouts ¶
type HTTPTimeouts struct { // ReadTimeout is the maximum duration for reading the entire // request, including the body. // // Because ReadTimeout does not let Handlers make per-request // decisions on each request body's acceptable deadline or // upload rate, most users will prefer to use // ReadHeaderTimeout. It is valid to use them both. ReadTimeout time.Duration // WriteTimeout is the maximum duration before timing out // writes of the response. It is reset whenever a new // request's header is read. Like ReadTimeout, it does not // let Handlers make decisions on a per-request basis. WriteTimeout time.Duration // IdleTimeout is the maximum amount of time to wait for the // next request when keep-alives are enabled. If IdleTimeout // is zero, the value of ReadTimeout is used. If both are // zero, ReadHeaderTimeout is used. IdleTimeout time.Duration }
HTTPTimeouts represents the configuration params for the HTTP RPC server.
type ID ¶
type ID string
ID defines a pseudo random number that is used to identify RPC subscriptions.
type Notifier ¶
type Notifier struct {
// contains filtered or unexported fields
}
Notifier is tied to a RPC connection that supports subscriptions. Server callbacks use the notifier to send notifications.
func NotifierFromContext ¶
NotifierFromContext returns the Notifier value stored in ctx, if any.
func (*Notifier) Closed ¶
func (n *Notifier) Closed() <-chan interface{}
Closed returns a channel that is closed when the RPC connection is closed. Deprecated: use subscription error channel
func (*Notifier) CreateSubscription ¶
func (n *Notifier) CreateSubscription() *Subscription
CreateSubscription returns a new subscription that is coupled to the RPC connection. By default subscriptions are inactive and notifications are dropped until the subscription is marked as active. This is done by the RPC server after the subscription ID is send to the client.
type RPCService ¶
type RPCService struct {
// contains filtered or unexported fields
}
RPCService gives meta information about the server. e.g. gives information about the loaded modules.
func (*RPCService) Modules ¶
func (s *RPCService) Modules() map[string]string
Modules returns the list of RPC services with their version number
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is an RPC server.
func NewServer ¶
func NewServer() *Server
NewServer creates a new server instance with no registered handlers.
func StartIPCEndpoint ¶
StartIPCEndpoint starts an IPC endpoint.
func (*Server) RegisterName ¶
RegisterName creates a service for the given receiver type under the given name. When no methods on the given receiver match the criteria to be either a RPC method or a subscription an error is returned. Otherwise a new service is created and added to the service collection this server provides to clients.
func (*Server) ServeCodec ¶
func (s *Server) ServeCodec(codec ServerCodec, options CodecOption)
ServeCodec reads incoming requests from codec, calls the appropriate callback and writes the response back using the given codec. It will block until the codec is closed or the server is stopped. In either case the codec is closed.
Note that codec options are no longer supported.
func (*Server) ServeHTTP ¶
func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP serves JSON-RPC requests over HTTP.
func (*Server) ServeListener ¶
ServeListener accepts connections on l, serving JSON-RPC on them.
func (*Server) Stop ¶
func (s *Server) Stop()
Stop stops reading new requests, waits for stopPendingRequestTimeout to allow pending requests to finish, then closes all codecs which will cancel pending requests and subscriptions.
func (*Server) WebsocketHandler ¶
WebsocketHandler returns a handler that serves JSON-RPC to WebSocket connections.
allowedOrigins should be a comma-separated list of allowed origin URLs. To allow connections with any origin, pass "*".
type ServerCodec ¶
type ServerCodec interface {
// contains filtered or unexported methods
}
ServerCodec implements reading, parsing and writing RPC messages for the server side of a RPC session. Implementations must be go-routine safe since the codec can be called in multiple go-routines concurrently.
func NewCodec ¶
func NewCodec(conn Conn) ServerCodec
NewCodec creates a codec on the given connection. If conn implements ConnRemoteAddr, log messages will use it to include the remote address of the connection.
func NewFuncCodec ¶
func NewFuncCodec(conn deadlineCloser, encode, decode func(v interface{}) error) ServerCodec
NewFuncCodec creates a codec which uses the given functions to read and write. If conn implements ConnRemoteAddr, log messages will use it to include the remote address of the connection.
type Subscription ¶
type Subscription struct { ID ID // contains filtered or unexported fields }
A Subscription is created by a notifier and tied to that notifier. The client can use this subscription to wait for an unsubscribe request for the client, see Err().
func (*Subscription) Err ¶
func (s *Subscription) Err() <-chan error
Err returns a channel that is closed when the client send an unsubscribe request.
func (*Subscription) MarshalJSON ¶
func (s *Subscription) MarshalJSON() ([]byte, error)
MarshalJSON marshals a subscription as its ID.