node

package
v0.24.0 Latest Latest
Warning

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

Go to latest
Published: Apr 12, 2024 License: AGPL-3.0 Imports: 30 Imported by: 0

Documentation

Overview

Package node sets up multi-protocol Ethereum nodes.

In the model exposed by this package, a node is a collection of services which use shared resources to provide RPC APIs. Services can also offer devp2p protocols, which are wired up to the devp2p network when the node instance is started.

Node Lifecycle

The Node object has a lifecycle consisting of three basic states, INITIALIZING, RUNNING and CLOSED.

●───────┐
     New()
        │
        ▼
  INITIALIZING ────Start()─┐
        │                  │
        │                  ▼
    Close()             RUNNING
        │                  │
        ▼                  │
     CLOSED ◀──────Close()─┘

Creating a Node allocates basic resources such as the data directory and returns the node in its INITIALIZING state. Lifecycle objects, RPC APIs and peer-to-peer networking protocols can be registered in this state. Basic operations such as opening a key-value database are permitted while initializing.

Once everything is registered, the node can be started, which moves it into the RUNNING state. Starting the node starts all registered Lifecycle objects and enables RPC and peer-to-peer networking. Note that no additional Lifecycles, APIs or p2p protocols can be registered while the node is running.

Closing the node releases all held resources. The actions performed by Close depend on the state it was in. When closing a node in INITIALIZING state, resources related to the data directory are released. If the node was RUNNING, closing it also stops all Lifecycle objects and shuts down RPC and peer-to-peer networking.

You must always call Close on Node, even if the node was not started.

Resources Managed By Node

All file-system resources used by a node instance are located in a directory called the data directory. The location of each resource can be overridden through additional node configuration. The data directory is optional. If it is not set and the location of a resource is otherwise unspecified, //nolint package node

will create the resource in memory.

To access to the devp2p network, Node configures and starts p2p.Server. Each host on the devp2p network has a unique identifier, the node key. The Node instance persists this key across restarts. Node also loads static and trusted node lists and ensures that knowledge about other hosts is persisted.

JSON-RPC servers which run HTTP, WebSocket or IPC can be started on a Node. RPC modules offered by registered services will be offered on those endpoints. Users can restrict any endpoint to a subset of RPC modules. Node itself offers the "debug", "admin" and "web3" modules.

Service implementations can open LevelDB databases through the service context. Package node chooses the file system location of each database. If the node is configured to run without a data directory, databases are opened in memory instead.

Node also creates the shared store of encrypted Ethereum account keys. Services can access the account manager through the service context.

Sharing Data Directory Among Instances

Multiple node instances can share a single data directory if they have distinct instance names (set through the Name config option). Sharing behaviour depends on the type of resource.

devp2p-related resources (node key, static/trusted node lists, known hosts database) are stored in a directory with the same name as the instance. Thus, multiple node instances using the same data directory will store this information in different subdirectories of the data directory.

LevelDB databases are also stored within the instance subdirectory. If multiple node instances use the same data directory, opening the databases with identical names will create one database for each instance.

The account key store is shared among all node instances using the same data directory unless its location is changed through the KeyStoreDir configuration option.

Data Directory Sharing Example

In this example, two node instances named A and B are started with the same data directory. Node instance A opens the database "db", node instance B opens the databases "db" and "db-2". The following files will be created in the data directory:

data-directory/
	A/
		nodekey            -- devp2p node key of instance A
		nodes/             -- devp2p discovery knowledge database of instance A
		db/                -- LevelDB content for "db"
	A.ipc                  -- JSON-RPC UNIX domain socket endpoint of instance A
	B/
		nodekey            -- devp2p node key of node B
		nodes/             -- devp2p discovery knowledge database of instance B
		static-nodes.json  -- devp2p static node list of instance B
		db/                -- LevelDB content for "db"
		db-2/              -- LevelDB content for "db-2"
	B.ipc                  -- JSON-RPC UNIX domain socket endpoint of instance B
	keystore/              -- account key store, used by both instances

Index

Constants

View Source
const (
	DefaultHTTPHost = "localhost" // Default host interface for the HTTP RPC server
	DefaultHTTPPort = 8545        // Default TCP port for the HTTP RPC server
	DefaultWSHost   = "localhost" // Default host interface for the websocket RPC server
	DefaultWSPort   = 8546        // Default TCP port for the websocket RPC server
	DefaultAuthHost = "localhost" // Default host interface for the authenticated apis
	DefaultAuthPort = 8551        // Default port for the authenticated apis
)

Variables

View Source
var (
	DefaultAuthCors    = []string{"localhost"} // Default cors domain for the authenticated apis
	DefaultAuthVhosts  = []string{"localhost"} // Default virtual hosts for the authenticated apis
	DefaultAuthOrigins = []string{"localhost"} // Default origins for the authenticated apis
	DefaultAuthPrefix  = ""                    // Default prefix for the authenticated apis
	DefaultAuthModules = []string{"eth", "engine"}
)
View Source
var (
	ErrDatadirUsed = errors.New("datadir already used by another process")
	ErrNodeStopped = errors.New("node not started")
	ErrNodeRunning = errors.New("node already running")
)
View Source
var DefaultConfig = Config{
	DataDir:              DefaultDataDir(),
	HTTPPort:             DefaultHTTPPort,
	AuthAddr:             DefaultAuthHost,
	AuthPort:             DefaultAuthPort,
	AuthVirtualHosts:     DefaultAuthVhosts,
	HTTPModules:          []string{"net", "web3"},
	HTTPVirtualHosts:     []string{"localhost"},
	HTTPTimeouts:         rpc.DefaultHTTPTimeouts,
	WSPort:               DefaultWSPort,
	WSModules:            []string{"net", "web3"},
	BatchRequestLimit:    1000,
	BatchResponseMaxSize: 25 * 1000 * 1000,
	GraphQLVirtualHosts:  []string{"localhost"},
}

DefaultConfig contains reasonable default settings.

Functions

func CheckTimeouts

func CheckTimeouts(timeouts *rpc.HTTPTimeouts)

CheckTimeouts ensures that timeout values are meaningful

func DefaultDataDir

func DefaultDataDir() string

DefaultDataDir is the default data directory to use for the databases and other persistence requirements.

func DefaultHTTPEndpoint

func DefaultHTTPEndpoint() string

DefaultHTTPEndpoint returns the HTTP endpoint used by default.

func DefaultIPCEndpoint

func DefaultIPCEndpoint(clientIdentifier string) string

DefaultIPCEndpoint returns the IPC path used by default.

func DefaultWSEndpoint

func DefaultWSEndpoint() string

DefaultWSEndpoint returns the websocket endpoint used by default.

func NewHTTPHandlerStack

func NewHTTPHandlerStack(srv http.Handler, cors []string, vhosts []string, jwtSecret []byte, exposedParam string) http.Handler

NewHTTPHandlerStack returns wrapped http-related handlers

func NewJWTAuth

func NewJWTAuth(jwtsecret [32]byte) rpc.HTTPAuth

NewJWTAuth creates an rpc client authentication provider that uses JWT. The secret MUST be 32 bytes (256 bits) as defined by the Engine-API authentication spec.

See https://github.com/ethereum/execution-apis/blob/main/src/engine/authentication.md for more details about this authentication scheme.

func NewWSHandlerStack

func NewWSHandlerStack(srv http.Handler, jwtSecret []byte, exposedParam string) http.Handler

NewWSHandlerStack returns a wrapped ws-related handler.

func RegisterApis

func RegisterApis(apis []rpc.API, modules []string, srv *rpc.Server) error

RegisterApis checks the given modules' availability, generates an allowlist based on the allowed modules, and then registers all of the APIs exposed by the services.

func StartHTTPEndpoint

func StartHTTPEndpoint(endpoint string, timeouts rpc.HTTPTimeouts, handler http.Handler) (*http.Server, net.Addr, error)

StartHTTPEndpoint starts the HTTP RPC endpoint.

Types

type Config

type Config struct {
	// Name sets the instance name of the node. It must not contain the / character and is
	// used in the devp2p node identifier. The instance name of geth is "geth". If no
	// value is specified, the basename of the current executable is used.
	Name string `toml:"-"`

	// Version should be set to the version number of the program. It is used
	// in the devp2p node identifier.
	Version string `toml:"-"`

	// DataDir is the file system folder the node should use for any data storage
	// requirements. The configured data directory will not be directly shared with
	// registered services, instead those can use utility methods to create/access
	// databases or flat files. This enables ephemeral nodes which can fully reside
	// in memory.
	DataDir string

	// IPCPath is the requested location to place the IPC endpoint. If the path is
	// a simple file name, it is placed inside the data directory (or on the root
	// pipe path on Windows), whereas if it's a resolvable path name (absolute or
	// relative), then that specific path is enforced. An empty path disables IPC.
	IPCPath string

	// HTTPHost is the host interface on which to start the HTTP RPC server. If this
	// field is empty, no HTTP API endpoint will be started.
	HTTPHost string

	// HTTPPort is the TCP port number on which to start the HTTP RPC server. The
	// default zero value is/ valid and will pick a port number randomly (useful
	// for ephemeral nodes).
	HTTPPort int `toml:",omitempty"`

	// HTTPCors is the Cross-Origin Resource Sharing header to send to requesting
	// clients. Please be aware that CORS is a browser enforced security, it's fully
	// useless for custom HTTP clients.
	HTTPCors []string `toml:",omitempty"`

	// HTTPVirtualHosts is the list of virtual hostnames which are allowed on incoming requests.
	// This is by default {'localhost'}. Using this prevents attacks like
	// DNS rebinding, which bypasses SOP by simply masquerading as being within the same
	// origin. These attacks do not utilize CORS, since they are not cross-domain.
	// By explicitly checking the Host-header, the server will not allow requests
	// made against the server with a malicious host domain.
	// Requests using ip address directly are not affected
	HTTPVirtualHosts []string `toml:",omitempty"`

	// HTTPModules is a list of API modules to expose via the HTTP RPC interface.
	// If the module list is empty, all RPC API endpoints designated public will be
	// exposed.
	HTTPModules []string

	// HTTPTimeouts allows for customization of the timeout values used by the HTTP RPC
	// interface.
	HTTPTimeouts rpc.HTTPTimeouts

	// HTTPPathPrefix specifies a path prefix on which http-rpc is to be served.
	HTTPPathPrefix string `toml:",omitempty"`

	// AuthAddr is the listening address on which authenticated APIs are provided.
	AuthAddr string `toml:",omitempty"`

	// AuthPort is the port number on which authenticated APIs are provided.
	AuthPort int `toml:",omitempty"`

	// AuthVirtualHosts is the list of virtual hostnames which are allowed on incoming requests
	// for the authenticated api. This is by default {'localhost'}.
	AuthVirtualHosts []string `toml:",omitempty"`

	// WSHost is the host interface on which to start the websocket RPC server. If
	// this field is empty, no websocket API endpoint will be started.
	WSHost string

	// WSPort is the TCP port number on which to start the websocket RPC server. The
	// default zero value is/ valid and will pick a port number randomly (useful for
	// ephemeral nodes).
	WSPort int `toml:",omitempty"`

	// WSPathPrefix specifies a path prefix on which ws-rpc is to be served.
	WSPathPrefix string `toml:",omitempty"`

	// WSOrigins is the list of domain to accept websocket requests from. Please be
	// aware that the server can only act upon the HTTP request the client sends and
	// cannot verify the validity of the request header.
	WSOrigins []string `toml:",omitempty"`

	// WSModules is a list of API modules to expose via the websocket RPC interface.
	// If the module list is empty, all RPC API endpoints designated public will be
	// exposed.
	WSModules []string

	// WSExposeAll exposes all API modules via the WebSocket RPC interface rather
	// than just the public ones.
	//
	// *WARNING* Only set this if the node is running in a trusted network, exposing
	// private APIs to untrusted users is a major security risk.
	WSExposeAll bool `toml:",omitempty"`

	// GraphQLCors is the Cross-Origin Resource Sharing header to send to requesting
	// clients. Please be aware that CORS is a browser enforced security, it's fully
	// useless for custom HTTP clients.
	GraphQLCors []string `toml:",omitempty"`

	// GraphQLVirtualHosts is the list of virtual hostnames which are allowed on incoming requests.
	// This is by default {'localhost'}. Using this prevents attacks like
	// DNS rebinding, which bypasses SOP by simply masquerading as being within the same
	// origin. These attacks do not utilize CORS, since they are not cross-domain.
	// By explicitly checking the Host-header, the server will not allow requests
	// made against the server with a malicious host domain.
	// Requests using ip address directly are not affected
	GraphQLVirtualHosts []string `toml:",omitempty"`

	// Logger is a custom logger to use with the p2p.Server.
	Logger log.Logger `toml:",omitempty"`

	// AllowUnprotectedTxs allows non EIP-155 protected transactions to be send over RPC.
	AllowUnprotectedTxs bool `toml:",omitempty"`

	// BatchRequestLimit is the maximum number of requests in a batch.
	BatchRequestLimit int `toml:",omitempty"`

	// BatchResponseMaxSize is the maximum number of bytes returned from a batched rpc call.
	BatchResponseMaxSize int `toml:",omitempty"`

	// JWTSecret is the path to the hex-encoded jwt secret.
	JWTSecret string `toml:",omitempty"`

	// EnablePersonal enables the deprecated personal namespace.
	EnablePersonal bool `toml:"-"`

	// TEN
	ExposedURLParamNames []string
	// contains filtered or unexported fields
}

Config represents a small collection of configuration values to fine tune the P2P network layer of a protocol stack. These values can be further extended by all registered services.

func (*Config) ExtRPCEnabled

func (c *Config) ExtRPCEnabled() bool

ExtRPCEnabled returns the indicator whether node enables the external RPC(http, ws or graphql).

func (*Config) HTTPEndpoint

func (c *Config) HTTPEndpoint() string

HTTPEndpoint resolves an HTTP endpoint based on the configured host interface and port parameters.

func (*Config) IPCEndpoint

func (c *Config) IPCEndpoint() string

IPCEndpoint resolves an IPC endpoint based on a configured value, taking into account the set data folders as well as the designated platform we're currently running on.

func (*Config) NodeDB

func (c *Config) NodeDB() string

NodeDB returns the path to the discovery node database.

func (*Config) NodeName

func (c *Config) NodeName() string

NodeName returns the devp2p node identifier.

func (*Config) ResolvePath

func (c *Config) ResolvePath(path string) string

ResolvePath resolves path in the instance directory.

func (*Config) WSEndpoint

func (c *Config) WSEndpoint() string

WSEndpoint resolves a websocket endpoint based on the configured host interface and port parameters.

type Lifecycle

type Lifecycle interface {
	// Start is called after all services have been constructed and the networking
	// layer was also initialized to spawn any goroutines required by the service.
	Start() error

	// Stop terminates all goroutines belonging to the service, blocking until they
	// are all terminated.
	Stop() error
}

Lifecycle encompasses the behavior of services that can be started and stopped on the node. Lifecycle management is delegated to the node, but it is the responsibility of the service-specific package to configure and register the service on the node using the `RegisterLifecycle` method.

type Node

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

Node is a container on which services can be registered.

func New

func New(conf *Config) (*Node, error)

New creates a new P2P node, ready for protocol registration.

func (*Node) Attach

func (n *Node) Attach() *rpc.Client

Attach creates an RPC client attached to an in-process API handler.

func (*Node) Close

func (n *Node) Close() error

Close stops the Node and releases resources acquired in Node constructor New.

func (*Node) Config

func (n *Node) Config() *Config

Config returns the configuration of node.

func (*Node) DataDir

func (n *Node) DataDir() string

DataDir retrieves the current datadir used by the protocol stack. Deprecated: No files should be stored in this directory, use InstanceDir instead.

func (*Node) EventMux

func (n *Node) EventMux() *event.TypeMux

EventMux retrieves the event multiplexer used by all the network services in the current protocol stack.

func (*Node) HTTPAuthEndpoint

func (n *Node) HTTPAuthEndpoint() string

HTTPAuthEndpoint returns the URL of the authenticated HTTP server.

func (*Node) HTTPEndpoint

func (n *Node) HTTPEndpoint() string

HTTPEndpoint returns the URL of the HTTP server. Note that this URL does not contain the JSON-RPC path prefix set by HTTPPathPrefix.

func (*Node) IPCEndpoint

func (n *Node) IPCEndpoint() string

IPCEndpoint retrieves the current IPC endpoint used by the protocol stack.

func (*Node) InstanceDir

func (n *Node) InstanceDir() string

InstanceDir retrieves the instance directory used by the protocol stack.

func (*Node) RPCHandler

func (n *Node) RPCHandler() (*rpc.Server, error)

RPCHandler returns the in-process RPC request handler.

func (*Node) RegisterAPIs

func (n *Node) RegisterAPIs(apis []rpc.API)

RegisterAPIs registers the APIs a service provides on the node.

func (*Node) RegisterHandler

func (n *Node) RegisterHandler(name, path string, handler http.Handler)

RegisterHandler mounts a handler on the given path on the canonical HTTP server.

The name of the handler is shown in a log message when the HTTP server starts and should be a descriptive term for the service provided by the handler.

func (*Node) RegisterLifecycle

func (n *Node) RegisterLifecycle(lifecycle Lifecycle)

RegisterLifecycle registers the given Lifecycle on the node.

func (*Node) ResolvePath

func (n *Node) ResolvePath(x string) string

ResolvePath returns the absolute path of a resource in the instance directory.

func (*Node) Start

func (n *Node) Start() error

Start starts all registered lifecycles, RPC services and p2p networking. Node can only be started once.

func (*Node) WSAuthEndpoint

func (n *Node) WSAuthEndpoint() string

WSAuthEndpoint returns the current authenticated JSON-RPC over WebSocket endpoint.

func (*Node) WSEndpoint

func (n *Node) WSEndpoint() string

WSEndpoint returns the current JSON-RPC over WebSocket endpoint.

func (*Node) Wait

func (n *Node) Wait()

Wait blocks until the node is closed.

type RPCConfig

type RPCConfig struct {
	Host       string
	EnableHTTP bool
	HTTPPort   int
	EnableWs   bool
	WsPort     int
	WsPath     string
	HTTPPath   string

	// ExposedURLParamNames - url prams that are available in the services
	ExposedURLParamNames []string
}

type Route

type Route struct {
	Name string
	Func func(resp http.ResponseWriter, req *http.Request)
}

Route defines the path plus handler for a given path

type Server

type Server interface {
	Start() error
	Stop()
	RegisterAPIs(apis []rpc.API)
	RegisterRoutes(routes []Route)
}

Server manages the lifeycle of an RPC Server

func NewServer

func NewServer(config *RPCConfig, logger gethlog.Logger) Server

type StopError

type StopError struct {
	Server   error
	Services map[reflect.Type]error
}

StopError is returned if a Node fails to stop either any of its registered services or itself.

func (*StopError) Error

func (e *StopError) Error() string

Error generates a textual representation of the stop error.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL