rpc

package
v1.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 26, 2024 License: GPL-3.0 Imports: 46 Imported by: 0

Documentation

Overview

Package rpc provides access to the exported methods of an object across a network or other I/O connection. After creating a server instance objects can be registered, making it visible from the outside. Exported methods that follow specific conventions can be called remotely. It also has support for the publish/subscribe pattern.

Methods that satisfy the following criteria are made available for remote access:

  • object must be exported
  • method must be exported
  • method returns 0, 1 (response or error) or 2 (response and error) values
  • method argument(s) must be exported or builtin types
  • method returned value(s) must be exported or builtin types

An example method: 

func (s *CalcService) Add(a, b int) (int, error)

When the returned error isn't nil the returned integer is ignored and the error is send back to the client. Otherwise the returned integer is send back to the client.

Optional arguments are supported by accepting pointer values as arguments. E.g. if we want to do the addition in an optional finite field we can accept a mod argument as pointer value. 

func (s *CalService) Add(a, b int, mod *int) (int, error)

This RPC method can be called with 2 integers and a null value as third argument. In that case the mod argument will be nil. Or it can be called with 3 integers, in that case mod will be pointing to the given third argument. Since the optional argument is the last argument the RPC package will also accept 2 integers as arguments. It will pass the mod argument as nil to the RPC method.

The server offers the ServeCodec method which accepts a ServerCodec instance. It will read requests from the codec, process the request and sends the response back to the client using the codec. The server can execute requests concurrently. Responses can be sent back to the client out of order.

An example server which uses the JSON codec: 

 type CalculatorService struct {}

 func (s *CalculatorService) Add(a, b int) int {
	return a + b
 }

 func (s *CalculatorService Div(a, b int) (int, error) {
	if b == 0 {
		return 0, errors.New("divide by zero")
	}
	return a/b, nil
 }

 calculator := new(CalculatorService)
 server := NewServer()
 server.RegisterName("calculator", calculator")

 l, _ := net.ListenUnix("unix", &net.UnixAddr{Net: "unix", Name: "/tmp/calculator.sock"})
 for {
	c, _ := l.AcceptUnix()
	codec := v2.NewJSONCodec(c)
	go server.ServeCodec(codec)
 }

The package also supports the publish subscribe pattern through the use of subscriptions. A method that is considered eligible for notifications must satisfy the following criteria:

  • object must be exported
  • method must be exported
  • first method argument type must be context.Context
  • method argument(s) must be exported or builtin types
  • method must return the tuple Subscription, error

An example method: 

func (s *BlockChainService) NewBlocks(ctx context.Context) (Subscription, error) {
	...
}

Subscriptions are deleted when:

  • the user sends an unsubscribe request
  • the connection which was used to create the subscription is closed. This can be initiated by the client and server. The server will close the connection on a write error or when the queue of buffered notifications gets too big.

Copyright 2024 The Kaia Authors This file is part of the Kaia library.

The Kaia library is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The Kaia library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with the Kaia library. If not, see <http://www.gnu.org/licenses/>.

Copyright 2024 The Kaia Authors This file is part of the Kaia library.

The Kaia library is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The Kaia library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with the Kaia library. If not, see <http://www.gnu.org/licenses/>.

Modifications Copyright 2024 The Kaia Authors Modifications Copyright 2018 The klaytn Authors Copyright 2015 The go-ethereum Authors This file is part of the go-ethereum library.

The go-ethereum library is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The go-ethereum library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.

This file is derived from rpc/json.go (2018/06/04). Modified and improved for the klaytn development. Modified and improved for the Kaia development.

Copyright 2024 The Kaia Authors This file is part of the Kaia library.

The Kaia library is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The Kaia library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with the Kaia library. If not, see <http://www.gnu.org/licenses/>.

Index

Examples

Constants

View Source 
const (
	PendingBlockNumber  = BlockNumber(-2)
	LatestBlockNumber   = BlockNumber(-1)
	EarliestBlockNumber = BlockNumber(0)
)
View Source 
const MetadataApi = "rpc"

Variables

View Source 
var (
	ErrClientQuit                = errors.New("client is closed")
	ErrNoResult                  = errors.New("no result in JSON-RPC response")
	ErrSubscriptionQueueOverflow = errors.New("subscription queue overflow")
)
View Source 
var (
	// ConcurrencyLimit is a limit for the number of concurrency connection for RPC servers.
	// It can be overwritten by rpc.concurrencylimit flag
	ConcurrencyLimit = 3000

	// TODO-Kaia: move websocket configurations to Config struct in /network/rpc/server.go
	// MaxSubscriptionPerWSConn is a maximum number of subscription for a websocket connection
	MaxSubscriptionPerWSConn int32 = 3000

	// WebsocketReadDeadline is the read deadline on the underlying network connection in seconds. 0 means read will not timeout
	WebsocketReadDeadline int64 = 0

	// WebsocketWriteDeadline is the write deadline on the underlying network connection in seconds. 0 means write will not timeout
	WebsocketWriteDeadline int64 = 0

	// MaxWebsocketConnections is a maximum number of websocket connections
	MaxWebsocketConnections int32 = 3000

	// NonEthCompatible is a bool value that determines whether to use return formatting of the eth namespace API  provided for compatibility.
	// It can be overwritten by rpc.eth.noncompatible flag
	NonEthCompatible = false

	// UpstreamArchiveEN is the upstream archive mode EN endpoint
	UpstreamArchiveEN string
)
View Source 
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")
)
View Source 
var DefaultHTTPTimeouts = HTTPTimeouts{
	ReadTimeout:      30 * time.Second,
	WriteTimeout:     30 * time.Second,
	IdleTimeout:      120 * time.Second,
	ExecutionTimeout: 30 * time.Second,
}

DefaultHTTPTimeouts represents the default timeout values used if further configuration is not provided.

Functions

func GetNullServices 

func GetNullServices() service

func NewFastHTTPServer deprecated 

func NewFastHTTPServer(cors []string, vhosts []string, timeouts HTTPTimeouts, srv *Server) *fasthttp.Server

NewFastHTTPServer creates a new HTTP RPC server around an API provider based on fasthttp library.

Deprecated: fasthttp server type endpoint is no longer supported

func NewFastWSServer 

func NewFastWSServer(allowedOrigins []string, srv *Server) *fasthttp.Server

func NewHTTPServer deprecated 

func NewHTTPServer(cors []string, vhosts []string, timeouts HTTPTimeouts, srv http.Handler) *http.Server

NewHTTPServer creates a new HTTP RPC server around an API provider.

Deprecated: Server implements http.Handler

func NewWSServer deprecated 

func NewWSServer(allowedOrigins []string, srv *Server) *http.Server

NewWSServer creates a new websocket RPC server around an API provider.

Deprecated: use Server.WebsocketHandler

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
	IPCOnly   bool        // only accessible to IPC
}

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) Uint64 

func (bn BlockNumber) Uint64() uint64

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 NewBlockNumberOrHashWithHash 

func NewBlockNumberOrHashWithHash(hash common.Hash, canonical bool) BlockNumberOrHash

func NewBlockNumberOrHashWithNumber 

func NewBlockNumberOrHashWithNumber(blockNr BlockNumber) BlockNumberOrHash

func (*BlockNumberOrHash) Hash 

func (bnh *BlockNumberOrHash) Hash() (common.Hash, bool)

func (*BlockNumberOrHash) Number 

func (bnh *BlockNumberOrHash) Number() (BlockNumber, bool)

func (*BlockNumberOrHash) NumberOrHashString 

func (bnh *BlockNumberOrHash) NumberOrHashString() (string, 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 

func ClientFromContext(ctx context.Context) (*Client, bool)

Client retrieves the client from the context, if any. This can be used to perform 'reverse calls' in a handler method.

func Dial 

func Dial(rawurl string) (*Client, error)

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 

func DialContext(ctx context.Context, rawurl string) (*Client, error)

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 DialHTTP 

func DialHTTP(endpoint string) (*Client, error)

DialHTTP creates a new RPC client that connects to an RPC server over HTTP.

func DialHTTPWithClient 

func DialHTTPWithClient(endpoint string, client *http.Client) (*Client, error)

DialHTTPWithClient creates a new RPC client that connects to an RPC server over HTTP using the provided HTTP Client.

func DialIO 

func DialIO(ctx context.Context, in io.Reader, out io.Writer) (*Client, error)

DialIO creates a client which uses the given IO channels

func DialIPC 

func DialIPC(ctx context.Context, endpoint string) (*Client, error)

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 

func DialInProc(handler *Server) *Client

DialInProc attaches an in-process connection to the given RPC server.

func DialStdIO 

func DialStdIO(ctx context.Context) (*Client, error)

DialStdIO creates a client on stdin/stdout.

func DialWebsocket 

func DialWebsocket(ctx context.Context, endpoint, origin string) (*Client, error)

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 NewClient 

func NewClient(initctx context.Context, connect reconnectFunc) (*Client, error)

func (*Client) BatchCall 

func (c *Client) BatchCall(b []BatchElem) error

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 

func (c *Client) BatchCallContext(ctx context.Context, b []BatchElem) error

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 

func (c *Client) Call(result interface{}, method string, args ...interface{}) error

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) KaiaSubscribe 

func (c *Client) KaiaSubscribe(ctx context.Context, channel interface{}, args ...interface{}) (*ClientSubscription, error)

KaiaSubscribe registers a subscripion under the "kaia" namespace.

func (*Client) Notify 

func (c *Client) Notify(ctx context.Context, method string, args ...interface{}) error

Notify sends a notification, i.e. a method call that doesn't expect a response.

func (*Client) RegisterName 

func (c *Client) RegisterName(name string, receiver interface{}) error

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) SetHeader 

func (c *Client) SetHeader(key, value string)

SetHeader adds a custom HTTP header to the client's requests. This method only works for clients using HTTP, it doesn't have any effect for clients using another transport.

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 8000 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.

func (*Client) SupportedModules 

func (c *Client) SupportedModules() (map[string]string, error)

SupportedModules calls the rpc_modules method, retrieving the list of APIs that are available on the server.

type ClientSubscription 

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

ClientSubscription is a subscription established through the Client's Subscribe or KaiaSubscribe methods.

Example 
// Modifications Copyright 2024 The Kaia Authors
// Modifications Copyright 2018 The klaytn Authors
// Copyright 2016 The go-ethereum Authors
// This file is part of the go-ethereum library.
//
// The go-ethereum library is free software: you can redistribute it and/or modify
// it under the terms of the GNU Lesser General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// The go-ethereum library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public License
// along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
//
// This file is derived from rpc/client_example_test.go (2018/06/04).
// Modified and improved for the klaytn development.
// Modified and improved for the Kaia development.

package main

import (
	"context"
	"fmt"
	"math/big"
	"time"

	"github.com/kaiachain/kaia/networks/rpc"
)

// In this example, our client whishes to track the latest 'block number'
// known to the server. The server supports two methods:
//
// eth_getBlockByNumber("latest", {})
//    returns the latest block object.
//
// eth_subscribe("newBlocks")
//    creates a subscription which fires block objects when new blocks arrive.

type Block struct {
	Number *big.Int
}

func main() {
	// Connect the client.
	client, _ := rpc.Dial("ws://127.0.0.1:8485")
	subch := make(chan Block)

	// Ensure that subch receives the latest block.
	go func() {
		for i := 0; ; i++ {
			if i > 0 {
				time.Sleep(2 * time.Second)
			}
			subscribeBlocks(client, subch)
		}
	}()

	// Print events from the subscription as they arrive.
	for block := range subch {
		fmt.Println("latest block:", block.Number)
	}
}

// subscribeBlocks runs in its own goroutine and maintains
// a subscription for new blocks.
func subscribeBlocks(client *rpc.Client, subch chan Block) {
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	// Subscribe to new blocks.
	sub, err := client.KaiaSubscribe(ctx, subch, "newHeads")
	if err != nil {
		fmt.Println("subscribe error:", err)
		return
	}

	// The connection is established now.
	// Update the channel with the current block.
	var lastBlock Block
	if err := client.CallContext(ctx, &lastBlock, "eth_getBlockByNumber", "latest"); err != nil {
		fmt.Println("can't get latest block:", err)
		return
	}
	subch <- lastBlock

	// The subscription will deliver events to the channel. Wait for the
	// subscription to end for any reason, then loop around to re-establish
	// the connection.
	fmt.Println("connection lost: ", <-sub.Err())
}

Output:

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 DatadogTracer 

type DatadogTracer struct {
	Tags         []tagInfo
	Service      string
	KaiaResponse bool
}

type Error 

type Error interface {
	Error() string  // returns the message
	ErrorCode() int // returns the code
}

Error wraps RPC errors, which contain an error code in addition to the 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

	// ExecutionTimeout is the maximum duration for processing the
	// entire request. If the process is over the time,
	// the request is stopped immediately and timeout message is sent to client.
	ExecutionTimeout 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.

func NewID 

func NewID() ID

NewID returns a new, random ID.

type KASAttrs 

type KASAttrs struct {
	ChainID      string `json:"x-chain-id"`
	AccountID    string `json:"x-account-id"`
	RequestID    string `json:"x-request-id"`
	ParentSpanID string `json:"x-b3-parentspanid,omitempty"`
	SpanID       string `json:"x-b3-spanid,omitempty"`
	TraceID      string `json:"x-b3-traceid,omitempty"`
}

KASAttrs contains identifications for a KAS request

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 

func NotifierFromContext(ctx context.Context) (*Notifier, bool)

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.

func (*Notifier) Notify 

func (n *Notifier) Notify(id ID, data interface{}) error

Notify sends a notification to the client with the given data as payload. If an error occurs the RPC connection is closed and the error is returned.

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 StartHTTPEndpoint 

func StartHTTPEndpoint(endpoint string, apis []API, modules []string, cors []string, vhosts []string, timeouts HTTPTimeouts) (net.Listener, *Server, error)

StartHTTPEndpoint starts the HTTP RPC endpoint, configured with cors/vhosts/modules

func StartIPCEndpoint 

func StartIPCEndpoint(ipcEndpoint string, apis []API) (net.Listener, *Server, error)

StartIPCEndpoint starts an IPC endpoint.

func StartWSEndpoint 

func StartWSEndpoint(endpoint string, apis []API, modules []string, wsOrigins []string, exposeAll bool) (net.Listener, *Server, error)

StartWSEndpoint starts a websocket endpoint

func (*Server) FastWebsocketHandler 

func (srv *Server) FastWebsocketHandler(ctx *fasthttp.RequestCtx)

func (*Server) GetServices 

func (s *Server) GetServices() map[string]service

func (*Server) HandleFastHTTP 

func (srv *Server) HandleFastHTTP(requestCtx *fasthttp.RequestCtx)

func (*Server) RegisterName 

func (s *Server) RegisterName(name string, rcvr interface{}) error

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 

func (s *Server) ServeListener(l net.Listener) error

ServeListener accepts connections on l, serving JSON-RPC on them.

func (*Server) ServeSingleRequest 

func (s *Server) ServeSingleRequest(ctx context.Context, codec ServerCodec)

ServeSingleRequest reads and processes a single RPC request from the given codec. This is used to serve HTTP connections. Subscriptions and reverse calls are not allowed in this mode.

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 

func (srv *Server) WebsocketHandler(allowedOrigins []string) http.Handler

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 tight 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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.