From 63c0338db4408aba686a42db8f606137f89717e4 Mon Sep 17 00:00:00 2001 From: Jonathan Combs <150135962+JonathanTylerCombs@users.noreply.github.com> Date: Thu, 23 May 2024 02:29:06 -0400 Subject: [PATCH] Add files via upload --- .github/workflows/api.go | 337 +++++++ .github/workflows/api_test.go | 355 ++++++++ .github/workflows/auth0-integration.pdf | Bin 0 -> 83721 bytes .github/workflows/config.go | 480 ++++++++++ .github/workflows/config_test.go | 153 ++++ .github/workflows/defaults.go | 134 +++ .github/workflows/doc.go | 121 +++ .github/workflows/endpoints.go | 91 ++ .github/workflows/errors.go | 52 ++ .github/workflows/full-node-ansible.md | 136 +++ .github/workflows/full-node-binaries.md | 181 ++++ .github/workflows/full-node-docker.md | 482 ++++++++++ .github/workflows/full-node-gcp.md | 102 +++ .github/workflows/full-node-packages.md | 161 ++++ .../full-node-system-requirements.md | 19 + .github/workflows/jwt_auth.go | 45 + .github/workflows/jwt_handler.go | 80 ++ .github/workflows/lifecycle.go | 31 + .github/workflows/main.go | 209 +++++ .github/workflows/node.go | 824 ++++++++++++++++++ .github/workflows/node_auth_test.go | 237 +++++ .github/workflows/node_example_test.go | 59 ++ .github/workflows/node_test.go | 638 ++++++++++++++ .github/workflows/rpcstack.go | 651 ++++++++++++++ .github/workflows/rpcstack_test.go | 616 +++++++++++++ .github/workflows/utils_test.go | 106 +++ 26 files changed, 6300 insertions(+) create mode 100644 .github/workflows/api.go create mode 100644 .github/workflows/api_test.go create mode 100644 .github/workflows/auth0-integration.pdf create mode 100644 .github/workflows/config.go create mode 100644 .github/workflows/config_test.go create mode 100644 .github/workflows/defaults.go create mode 100644 .github/workflows/doc.go create mode 100644 .github/workflows/endpoints.go create mode 100644 .github/workflows/errors.go create mode 100644 .github/workflows/full-node-ansible.md create mode 100644 .github/workflows/full-node-binaries.md create mode 100644 .github/workflows/full-node-docker.md create mode 100644 .github/workflows/full-node-gcp.md create mode 100644 .github/workflows/full-node-packages.md create mode 100644 .github/workflows/full-node-system-requirements.md create mode 100644 .github/workflows/jwt_auth.go create mode 100644 .github/workflows/jwt_handler.go create mode 100644 .github/workflows/lifecycle.go create mode 100644 .github/workflows/main.go create mode 100644 .github/workflows/node.go create mode 100644 .github/workflows/node_auth_test.go create mode 100644 .github/workflows/node_example_test.go create mode 100644 .github/workflows/node_test.go create mode 100644 .github/workflows/rpcstack.go create mode 100644 .github/workflows/rpcstack_test.go create mode 100644 .github/workflows/utils_test.go diff --git a/.github/workflows/api.go b/.github/workflows/api.go new file mode 100644 index 0000000..f81f394 --- /dev/null +++ b/.github/workflows/api.go @@ -0,0 +1,337 @@ +// 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 . + +package node + +import ( + "context" + "fmt" + "strings" + + "github.com/ethereum/go-ethereum/common/hexutil" + "github.com/ethereum/go-ethereum/crypto" + "github.com/ethereum/go-ethereum/internal/debug" + "github.com/ethereum/go-ethereum/log" + "github.com/ethereum/go-ethereum/p2p" + "github.com/ethereum/go-ethereum/p2p/enode" + "github.com/ethereum/go-ethereum/rpc" +) + +// apis returns the collection of built-in RPC APIs. +func (n *Node) apis() []rpc.API { + return []rpc.API{ + { + Namespace: "admin", + Service: &adminAPI{n}, + }, { + Namespace: "debug", + Service: debug.Handler, + }, { + Namespace: "web3", + Service: &web3API{n}, + }, + } +} + +// adminAPI is the collection of administrative API methods exposed over +// both secure and unsecure RPC channels. +type adminAPI struct { + node *Node // Node interfaced by this API +} + +// AddPeer requests connecting to a remote node, and also maintaining the new +// connection at all times, even reconnecting if it is lost. +func (api *adminAPI) AddPeer(url string) (bool, error) { + // Make sure the server is running, fail otherwise + server := api.node.Server() + if server == nil { + return false, ErrNodeStopped + } + // Try to add the url as a static peer and return + node, err := enode.Parse(enode.ValidSchemes, url) + if err != nil { + return false, fmt.Errorf("invalid enode: %v", err) + } + server.AddPeer(node) + return true, nil +} + +// RemovePeer disconnects from a remote node if the connection exists +func (api *adminAPI) RemovePeer(url string) (bool, error) { + // Make sure the server is running, fail otherwise + server := api.node.Server() + if server == nil { + return false, ErrNodeStopped + } + // Try to remove the url as a static peer and return + node, err := enode.Parse(enode.ValidSchemes, url) + if err != nil { + return false, fmt.Errorf("invalid enode: %v", err) + } + server.RemovePeer(node) + return true, nil +} + +// AddTrustedPeer allows a remote node to always connect, even if slots are full +func (api *adminAPI) AddTrustedPeer(url string) (bool, error) { + // Make sure the server is running, fail otherwise + server := api.node.Server() + if server == nil { + return false, ErrNodeStopped + } + node, err := enode.Parse(enode.ValidSchemes, url) + if err != nil { + return false, fmt.Errorf("invalid enode: %v", err) + } + server.AddTrustedPeer(node) + return true, nil +} + +// RemoveTrustedPeer removes a remote node from the trusted peer set, but it +// does not disconnect it automatically. +func (api *adminAPI) RemoveTrustedPeer(url string) (bool, error) { + // Make sure the server is running, fail otherwise + server := api.node.Server() + if server == nil { + return false, ErrNodeStopped + } + node, err := enode.Parse(enode.ValidSchemes, url) + if err != nil { + return false, fmt.Errorf("invalid enode: %v", err) + } + server.RemoveTrustedPeer(node) + return true, nil +} + +// PeerEvents creates an RPC subscription which receives peer events from the +// node's p2p.Server +func (api *adminAPI) PeerEvents(ctx context.Context) (*rpc.Subscription, error) { + // Make sure the server is running, fail otherwise + server := api.node.Server() + if server == nil { + return nil, ErrNodeStopped + } + + // Create the subscription + notifier, supported := rpc.NotifierFromContext(ctx) + if !supported { + return nil, rpc.ErrNotificationsUnsupported + } + rpcSub := notifier.CreateSubscription() + + go func() { + events := make(chan *p2p.PeerEvent) + sub := server.SubscribeEvents(events) + defer sub.Unsubscribe() + + for { + select { + case event := <-events: + notifier.Notify(rpcSub.ID, event) + case <-sub.Err(): + return + case <-rpcSub.Err(): + return + case <-notifier.Closed(): + return + } + } + }() + + return rpcSub, nil +} + +// StartHTTP starts the HTTP RPC API server. +func (api *adminAPI) StartHTTP(host *string, port *int, cors *string, apis *string, vhosts *string) (bool, error) { + api.node.lock.Lock() + defer api.node.lock.Unlock() + + // Determine host and port. + if host == nil { + h := DefaultHTTPHost + if api.node.config.HTTPHost != "" { + h = api.node.config.HTTPHost + } + host = &h + } + if port == nil { + port = &api.node.config.HTTPPort + } + + // Determine config. + config := httpConfig{ + CorsAllowedOrigins: api.node.config.HTTPCors, + Vhosts: api.node.config.HTTPVirtualHosts, + Modules: api.node.config.HTTPModules, + rpcEndpointConfig: rpcEndpointConfig{ + batchItemLimit: api.node.config.BatchRequestLimit, + batchResponseSizeLimit: api.node.config.BatchResponseMaxSize, + }, + } + if cors != nil { + config.CorsAllowedOrigins = nil + for _, origin := range strings.Split(*cors, ",") { + config.CorsAllowedOrigins = append(config.CorsAllowedOrigins, strings.TrimSpace(origin)) + } + } + if vhosts != nil { + config.Vhosts = nil + for _, vhost := range strings.Split(*host, ",") { + config.Vhosts = append(config.Vhosts, strings.TrimSpace(vhost)) + } + } + if apis != nil { + config.Modules = nil + for _, m := range strings.Split(*apis, ",") { + config.Modules = append(config.Modules, strings.TrimSpace(m)) + } + } + + if err := api.node.http.setListenAddr(*host, *port); err != nil { + return false, err + } + if err := api.node.http.enableRPC(api.node.rpcAPIs, config); err != nil { + return false, err + } + if err := api.node.http.start(); err != nil { + return false, err + } + return true, nil +} + +// StartRPC starts the HTTP RPC API server. +// Deprecated: use StartHTTP instead. +func (api *adminAPI) StartRPC(host *string, port *int, cors *string, apis *string, vhosts *string) (bool, error) { + log.Warn("Deprecation warning", "method", "admin.StartRPC", "use-instead", "admin.StartHTTP") + return api.StartHTTP(host, port, cors, apis, vhosts) +} + +// StopHTTP shuts down the HTTP server. +func (api *adminAPI) StopHTTP() (bool, error) { + api.node.http.stop() + return true, nil +} + +// StopRPC shuts down the HTTP server. +// Deprecated: use StopHTTP instead. +func (api *adminAPI) StopRPC() (bool, error) { + log.Warn("Deprecation warning", "method", "admin.StopRPC", "use-instead", "admin.StopHTTP") + return api.StopHTTP() +} + +// StartWS starts the websocket RPC API server. +func (api *adminAPI) StartWS(host *string, port *int, allowedOrigins *string, apis *string) (bool, error) { + api.node.lock.Lock() + defer api.node.lock.Unlock() + + // Determine host and port. + if host == nil { + h := DefaultWSHost + if api.node.config.WSHost != "" { + h = api.node.config.WSHost + } + host = &h + } + if port == nil { + port = &api.node.config.WSPort + } + + // Determine config. + config := wsConfig{ + Modules: api.node.config.WSModules, + Origins: api.node.config.WSOrigins, + // ExposeAll: api.node.config.WSExposeAll, + rpcEndpointConfig: rpcEndpointConfig{ + batchItemLimit: api.node.config.BatchRequestLimit, + batchResponseSizeLimit: api.node.config.BatchResponseMaxSize, + }, + } + if apis != nil { + config.Modules = nil + for _, m := range strings.Split(*apis, ",") { + config.Modules = append(config.Modules, strings.TrimSpace(m)) + } + } + if allowedOrigins != nil { + config.Origins = nil + for _, origin := range strings.Split(*allowedOrigins, ",") { + config.Origins = append(config.Origins, strings.TrimSpace(origin)) + } + } + + // Enable WebSocket on the server. + server := api.node.wsServerForPort(*port, false) + if err := server.setListenAddr(*host, *port); err != nil { + return false, err + } + openApis, _ := api.node.getAPIs() + if err := server.enableWS(openApis, config); err != nil { + return false, err + } + if err := server.start(); err != nil { + return false, err + } + api.node.http.log.Info("WebSocket endpoint opened", "url", api.node.WSEndpoint()) + return true, nil +} + +// StopWS terminates all WebSocket servers. +func (api *adminAPI) StopWS() (bool, error) { + api.node.http.stopWS() + api.node.ws.stop() + return true, nil +} + +// Peers retrieves all the information we know about each individual peer at the +// protocol granularity. +func (api *adminAPI) Peers() ([]*p2p.PeerInfo, error) { + server := api.node.Server() + if server == nil { + return nil, ErrNodeStopped + } + return server.PeersInfo(), nil +} + +// NodeInfo retrieves all the information we know about the host node at the +// protocol granularity. +func (api *adminAPI) NodeInfo() (*p2p.NodeInfo, error) { + server := api.node.Server() + if server == nil { + return nil, ErrNodeStopped + } + return server.NodeInfo(), nil +} + +// Datadir retrieves the current data directory the node is using. +func (api *adminAPI) Datadir() string { + return api.node.DataDir() +} + +// web3API offers helper utils +type web3API struct { + stack *Node +} + +// ClientVersion returns the node name +func (s *web3API) ClientVersion() string { + return s.stack.Server().Name +} + +// Sha3 applies the ethereum sha3 implementation on the input. +// It assumes the input is hex encoded. +func (s *web3API) Sha3(input hexutil.Bytes) hexutil.Bytes { + return crypto.Keccak256(input) +} diff --git a/.github/workflows/api_test.go b/.github/workflows/api_test.go new file mode 100644 index 0000000..8761c48 --- /dev/null +++ b/.github/workflows/api_test.go @@ -0,0 +1,355 @@ +// Copyright 2020 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 . + +package node + +import ( + "bytes" + "io" + "net" + "net/http" + "net/url" + "strings" + "testing" + + "github.com/ethereum/go-ethereum/rpc" + "github.com/stretchr/testify/assert" +) + +// This test uses the admin_startRPC and admin_startWS APIs, +// checking whether the HTTP server is started correctly. +func TestStartRPC(t *testing.T) { + type test struct { + name string + cfg Config + fn func(*testing.T, *Node, *adminAPI) + + // Checks. These run after the node is configured and all API calls have been made. + wantReachable bool // whether the HTTP server should be reachable at all + wantHandlers bool // whether RegisterHandler handlers should be accessible + wantRPC bool // whether JSON-RPC/HTTP should be accessible + wantWS bool // whether JSON-RPC/WS should be accessible + } + + tests := []test{ + { + name: "all off", + cfg: Config{}, + fn: func(t *testing.T, n *Node, api *adminAPI) { + }, + wantReachable: false, + wantHandlers: false, + wantRPC: false, + wantWS: false, + }, + { + name: "rpc enabled through config", + cfg: Config{HTTPHost: "127.0.0.1"}, + fn: func(t *testing.T, n *Node, api *adminAPI) { + }, + wantReachable: true, + wantHandlers: true, + wantRPC: true, + wantWS: false, + }, + { + name: "rpc enabled through API", + cfg: Config{}, + fn: func(t *testing.T, n *Node, api *adminAPI) { + _, err := api.StartHTTP(sp("127.0.0.1"), ip(0), nil, nil, nil) + assert.NoError(t, err) + }, + wantReachable: true, + wantHandlers: true, + wantRPC: true, + wantWS: false, + }, + { + name: "rpc start again after failure", + cfg: Config{}, + fn: func(t *testing.T, n *Node, api *adminAPI) { + // Listen on a random port. + listener, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatal("can't listen:", err) + } + defer listener.Close() + port := listener.Addr().(*net.TCPAddr).Port + + // Now try to start RPC on that port. This should fail. + _, err = api.StartHTTP(sp("127.0.0.1"), ip(port), nil, nil, nil) + if err == nil { + t.Fatal("StartHTTP should have failed on port", port) + } + + // Try again after unblocking the port. It should work this time. + listener.Close() + _, err = api.StartHTTP(sp("127.0.0.1"), ip(port), nil, nil, nil) + assert.NoError(t, err) + }, + wantReachable: true, + wantHandlers: true, + wantRPC: true, + wantWS: false, + }, + { + name: "rpc stopped through API", + cfg: Config{HTTPHost: "127.0.0.1"}, + fn: func(t *testing.T, n *Node, api *adminAPI) { + _, err := api.StopHTTP() + assert.NoError(t, err) + }, + wantReachable: false, + wantHandlers: false, + wantRPC: false, + wantWS: false, + }, + { + name: "rpc stopped twice", + cfg: Config{HTTPHost: "127.0.0.1"}, + fn: func(t *testing.T, n *Node, api *adminAPI) { + _, err := api.StopHTTP() + assert.NoError(t, err) + + _, err = api.StopHTTP() + assert.NoError(t, err) + }, + wantReachable: false, + wantHandlers: false, + wantRPC: false, + wantWS: false, + }, + { + name: "ws enabled through config", + cfg: Config{WSHost: "127.0.0.1"}, + wantReachable: true, + wantHandlers: false, + wantRPC: false, + wantWS: true, + }, + { + name: "ws enabled through API", + cfg: Config{}, + fn: func(t *testing.T, n *Node, api *adminAPI) { + _, err := api.StartWS(sp("127.0.0.1"), ip(0), nil, nil) + assert.NoError(t, err) + }, + wantReachable: true, + wantHandlers: false, + wantRPC: false, + wantWS: true, + }, + { + name: "ws stopped through API", + cfg: Config{WSHost: "127.0.0.1"}, + fn: func(t *testing.T, n *Node, api *adminAPI) { + _, err := api.StopWS() + assert.NoError(t, err) + }, + wantReachable: false, + wantHandlers: false, + wantRPC: false, + wantWS: false, + }, + { + name: "ws stopped twice", + cfg: Config{WSHost: "127.0.0.1"}, + fn: func(t *testing.T, n *Node, api *adminAPI) { + _, err := api.StopWS() + assert.NoError(t, err) + + _, err = api.StopWS() + assert.NoError(t, err) + }, + wantReachable: false, + wantHandlers: false, + wantRPC: false, + wantWS: false, + }, + { + name: "ws enabled after RPC", + cfg: Config{HTTPHost: "127.0.0.1"}, + fn: func(t *testing.T, n *Node, api *adminAPI) { + wsport := n.http.port + _, err := api.StartWS(sp("127.0.0.1"), ip(wsport), nil, nil) + assert.NoError(t, err) + }, + wantReachable: true, + wantHandlers: true, + wantRPC: true, + wantWS: true, + }, + { + name: "ws enabled after RPC then stopped", + cfg: Config{HTTPHost: "127.0.0.1"}, + fn: func(t *testing.T, n *Node, api *adminAPI) { + wsport := n.http.port + _, err := api.StartWS(sp("127.0.0.1"), ip(wsport), nil, nil) + assert.NoError(t, err) + + _, err = api.StopWS() + assert.NoError(t, err) + }, + wantReachable: true, + wantHandlers: true, + wantRPC: true, + wantWS: false, + }, + { + name: "rpc stopped with ws enabled", + fn: func(t *testing.T, n *Node, api *adminAPI) { + _, err := api.StartHTTP(sp("127.0.0.1"), ip(0), nil, nil, nil) + assert.NoError(t, err) + + wsport := n.http.port + _, err = api.StartWS(sp("127.0.0.1"), ip(wsport), nil, nil) + assert.NoError(t, err) + + _, err = api.StopHTTP() + assert.NoError(t, err) + }, + wantReachable: false, + wantHandlers: false, + wantRPC: false, + wantWS: false, + }, + { + name: "rpc enabled after ws", + fn: func(t *testing.T, n *Node, api *adminAPI) { + _, err := api.StartWS(sp("127.0.0.1"), ip(0), nil, nil) + assert.NoError(t, err) + + wsport := n.http.port + _, err = api.StartHTTP(sp("127.0.0.1"), ip(wsport), nil, nil, nil) + assert.NoError(t, err) + }, + wantReachable: true, + wantHandlers: true, + wantRPC: true, + wantWS: true, + }, + } + + for _, test := range tests { + test := test + t.Run(test.name, func(t *testing.T) { + t.Parallel() + + // Apply some sane defaults. + config := test.cfg + // config.Logger = testlog.Logger(t, log.LvlDebug) + config.P2P.NoDiscovery = true + if config.HTTPTimeouts == (rpc.HTTPTimeouts{}) { + config.HTTPTimeouts = rpc.DefaultHTTPTimeouts + } + + // Create Node. + stack, err := New(&config) + if err != nil { + t.Fatal("can't create node:", err) + } + defer stack.Close() + + // Register the test handler. + stack.RegisterHandler("test", "/test", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Write([]byte("OK")) + })) + + if err := stack.Start(); err != nil { + t.Fatal("can't start node:", err) + } + + // Run the API call hook. + if test.fn != nil { + test.fn(t, stack, &adminAPI{stack}) + } + + // Check if the HTTP endpoints are available. + baseURL := stack.HTTPEndpoint() + reachable := checkReachable(baseURL) + handlersAvailable := checkBodyOK(baseURL + "/test") + rpcAvailable := checkRPC(baseURL) + wsAvailable := checkRPC(strings.Replace(baseURL, "http://", "ws://", 1)) + if reachable != test.wantReachable { + t.Errorf("HTTP server is %sreachable, want it %sreachable", not(reachable), not(test.wantReachable)) + } + if handlersAvailable != test.wantHandlers { + t.Errorf("RegisterHandler handlers %savailable, want them %savailable", not(handlersAvailable), not(test.wantHandlers)) + } + if rpcAvailable != test.wantRPC { + t.Errorf("HTTP RPC %savailable, want it %savailable", not(rpcAvailable), not(test.wantRPC)) + } + if wsAvailable != test.wantWS { + t.Errorf("WS RPC %savailable, want it %savailable", not(wsAvailable), not(test.wantWS)) + } + }) + } +} + +// checkReachable checks if the TCP endpoint in rawurl is open. +func checkReachable(rawurl string) bool { + u, err := url.Parse(rawurl) + if err != nil { + panic(err) + } + conn, err := net.Dial("tcp", u.Host) + if err != nil { + return false + } + conn.Close() + return true +} + +// checkBodyOK checks whether the given HTTP URL responds with 200 OK and body "OK". +func checkBodyOK(url string) bool { + resp, err := http.Get(url) + if err != nil { + return false + } + defer resp.Body.Close() + + if resp.StatusCode != 200 { + return false + } + buf := make([]byte, 2) + if _, err = io.ReadFull(resp.Body, buf); err != nil { + return false + } + return bytes.Equal(buf, []byte("OK")) +} + +// checkRPC checks whether JSON-RPC works against the given URL. +func checkRPC(url string) bool { + c, err := rpc.Dial(url) + if err != nil { + return false + } + defer c.Close() + + _, err = c.SupportedModules() + return err == nil +} + +// string/int pointer helpers. +func sp(s string) *string { return &s } +func ip(i int) *int { return &i } + +func not(ok bool) string { + if ok { + return "" + } + return "not " +} diff --git a/.github/workflows/auth0-integration.pdf b/.github/workflows/auth0-integration.pdf new file mode 100644 index 0000000000000000000000000000000000000000..bcc27a8b8bd89921b4c870366d86de1218cc6cb4 GIT binary patch literal 83721 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�XRF_G7(E#4Eh- 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. + +package node + +import ( + "crypto/ecdsa" + "fmt" + "net" + "os" + "path/filepath" + "runtime" + "strings" + + "github.com/ethereum/go-ethereum/common" + "github.com/ethereum/go-ethereum/crypto" + "github.com/ethereum/go-ethereum/log" + "github.com/ethereum/go-ethereum/p2p" + "github.com/ethereum/go-ethereum/rpc" +) + +const ( + datadirPrivateKey = "nodekey" // Path within the datadir to the node's private key + datadirJWTKey = "jwtsecret" // Path within the datadir to the node's jwt secret + datadirDefaultKeyStore = "keystore" // Path within the datadir to the keystore + datadirStaticNodes = "static-nodes.json" // Path within the datadir to the static node list + datadirTrustedNodes = "trusted-nodes.json" // Path within the datadir to the trusted node list + datadirNodeDatabase = "nodes" // Path within the datadir to store the node infos +) + +// 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. +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:"-"` + + // UserIdent, if set, is used as an additional component in the devp2p node identifier. + UserIdent string `toml:",omitempty"` + + // 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 + + // Configuration of peer-to-peer networking. + P2P p2p.Config + + // KeyStoreDir is the file system folder that contains private keys. The directory can + // be specified as a relative path, in which case it is resolved relative to the + // current directory. + // + // If KeyStoreDir is empty, the default location is the "keystore" subdirectory of + // DataDir. If DataDir is unspecified and KeyStoreDir is empty, an ephemeral directory + // is created by New and destroyed when the node is stopped. + KeyStoreDir string `toml:",omitempty"` + + // ExternalSigner specifies an external URI for a clef-type signer. + ExternalSigner string `toml:",omitempty"` + + // UseLightweightKDF lowers the memory and CPU requirements of the key store + // scrypt KDF at the expense of security. + UseLightweightKDF bool `toml:",omitempty"` + + // InsecureUnlockAllowed allows user to unlock accounts in unsafe http environment. + InsecureUnlockAllowed bool `toml:",omitempty"` + + // NoUSB disables hardware wallet monitoring and connectivity. + // Deprecated: USB monitoring is disabled by default and must be enabled explicitly. + NoUSB bool `toml:",omitempty"` + + // USB enables hardware wallet monitoring and connectivity. + USB bool `toml:",omitempty"` + + // SmartCardDaemonPath is the path to the smartcard daemon's socket. + SmartCardDaemonPath string `toml:",omitempty"` + + // 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"` + + oldGethResourceWarning bool + + // 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:"-"` + + DBEngine string `toml:",omitempty"` +} + +// 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 (c *Config) IPCEndpoint() string { + // Short circuit if IPC has not been enabled + if c.IPCPath == "" { + return "" + } + // On windows we can only use plain top-level pipes + if runtime.GOOS == "windows" { + if strings.HasPrefix(c.IPCPath, `\\.\pipe\`) { + return c.IPCPath + } + return `\\.\pipe\` + c.IPCPath + } + // Resolve names into the data directory full paths otherwise + if filepath.Base(c.IPCPath) == c.IPCPath { + if c.DataDir == "" { + return filepath.Join(os.TempDir(), c.IPCPath) + } + return filepath.Join(c.DataDir, c.IPCPath) + } + return c.IPCPath +} + +// NodeDB returns the path to the discovery node database. +func (c *Config) NodeDB() string { + if c.DataDir == "" { + return "" // ephemeral + } + return c.ResolvePath(datadirNodeDatabase) +} + +// DefaultIPCEndpoint returns the IPC path used by default. +func DefaultIPCEndpoint(clientIdentifier string) string { + if clientIdentifier == "" { + clientIdentifier = strings.TrimSuffix(filepath.Base(os.Args[0]), ".exe") + if clientIdentifier == "" { + panic("empty executable name") + } + } + config := &Config{DataDir: DefaultDataDir(), IPCPath: clientIdentifier + ".ipc"} + return config.IPCEndpoint() +} + +// HTTPEndpoint resolves an HTTP endpoint based on the configured host interface +// and port parameters. +func (c *Config) HTTPEndpoint() string { + if c.HTTPHost == "" { + return "" + } + return net.JoinHostPort(c.HTTPHost, fmt.Sprintf("%d", c.HTTPPort)) +} + +// DefaultHTTPEndpoint returns the HTTP endpoint used by default. +func DefaultHTTPEndpoint() string { + config := &Config{HTTPHost: DefaultHTTPHost, HTTPPort: DefaultHTTPPort, AuthPort: DefaultAuthPort} + return config.HTTPEndpoint() +} + +// WSEndpoint resolves a websocket endpoint based on the configured host interface +// and port parameters. +func (c *Config) WSEndpoint() string { + if c.WSHost == "" { + return "" + } + return net.JoinHostPort(c.WSHost, fmt.Sprintf("%d", c.WSPort)) +} + +// DefaultWSEndpoint returns the websocket endpoint used by default. +func DefaultWSEndpoint() string { + config := &Config{WSHost: DefaultWSHost, WSPort: DefaultWSPort} + return config.WSEndpoint() +} + +// ExtRPCEnabled returns the indicator whether node enables the external +// RPC(http, ws or graphql). +func (c *Config) ExtRPCEnabled() bool { + return c.HTTPHost != "" || c.WSHost != "" +} + +// NodeName returns the devp2p node identifier. +func (c *Config) NodeName() string { + name := c.name() + // Backwards compatibility: previous versions used title-cased "Geth", keep that. + if name == "geth" || name == "geth-testnet" { + name = "Geth" + } + if c.UserIdent != "" { + name += "/" + c.UserIdent + } + if c.Version != "" { + name += "/v" + c.Version + } + name += "/" + runtime.GOOS + "-" + runtime.GOARCH + name += "/" + runtime.Version() + return name +} + +func (c *Config) name() string { + if c.Name == "" { + progname := strings.TrimSuffix(filepath.Base(os.Args[0]), ".exe") + if progname == "" { + panic("empty executable name, set Config.Name") + } + return progname + } + return c.Name +} + +// These resources are resolved differently for "geth" instances. +var isOldGethResource = map[string]bool{ + "chaindata": true, + "nodes": true, + "nodekey": true, + "static-nodes.json": false, // no warning for these because they have their + "trusted-nodes.json": false, // own separate warning. +} + +// ResolvePath resolves path in the instance directory. +func (c *Config) ResolvePath(path string) string { + if filepath.IsAbs(path) { + return path + } + if c.DataDir == "" { + return "" + } + // Backwards-compatibility: ensure that data directory files created + // by geth 1.4 are used if they exist. + if warn, isOld := isOldGethResource[path]; isOld { + oldpath := "" + if c.name() == "geth" { + oldpath = filepath.Join(c.DataDir, path) + } + if oldpath != "" && common.FileExist(oldpath) { + if warn && !c.oldGethResourceWarning { + c.oldGethResourceWarning = true + log.Warn("Using deprecated resource file, please move this file to the 'geth' subdirectory of datadir.", "file", oldpath) + } + return oldpath + } + } + return filepath.Join(c.instanceDir(), path) +} + +func (c *Config) instanceDir() string { + if c.DataDir == "" { + return "" + } + return filepath.Join(c.DataDir, c.name()) +} + +// NodeKey retrieves the currently configured private key of the node, checking +// first any manually set key, falling back to the one found in the configured +// data folder. If no key can be found, a new one is generated. +func (c *Config) NodeKey() *ecdsa.PrivateKey { + // Use any specifically configured key. + if c.P2P.PrivateKey != nil { + return c.P2P.PrivateKey + } + // Generate ephemeral key if no datadir is being used. + if c.DataDir == "" { + key, err := crypto.GenerateKey() + if err != nil { + log.Crit(fmt.Sprintf("Failed to generate ephemeral node key: %v", err)) + } + return key + } + + keyfile := c.ResolvePath(datadirPrivateKey) + if key, err := crypto.LoadECDSA(keyfile); err == nil { + return key + } + // No persistent key found, generate and store a new one. + key, err := crypto.GenerateKey() + if err != nil { + log.Crit(fmt.Sprintf("Failed to generate node key: %v", err)) + } + instanceDir := filepath.Join(c.DataDir, c.name()) + if err := os.MkdirAll(instanceDir, 0700); err != nil { + log.Error(fmt.Sprintf("Failed to persist node key: %v", err)) + return key + } + keyfile = filepath.Join(instanceDir, datadirPrivateKey) + if err := crypto.SaveECDSA(keyfile, key); err != nil { + log.Error(fmt.Sprintf("Failed to persist node key: %v", err)) + } + return key +} + +// checkLegacyFiles inspects the datadir for signs of legacy static-nodes +// and trusted-nodes files. If they exist it raises an error. +func (c *Config) checkLegacyFiles() { + c.checkLegacyFile(c.ResolvePath(datadirStaticNodes)) + c.checkLegacyFile(c.ResolvePath(datadirTrustedNodes)) +} + +// checkLegacyFile will only raise an error if a file at the given path exists. +func (c *Config) checkLegacyFile(path string) { + // Short circuit if no node config is present + if c.DataDir == "" { + return + } + if _, err := os.Stat(path); err != nil { + return + } + logger := c.Logger + if logger == nil { + logger = log.Root() + } + switch fname := filepath.Base(path); fname { + case "static-nodes.json": + logger.Error("The static-nodes.json file is deprecated and ignored. Use P2P.StaticNodes in config.toml instead.") + case "trusted-nodes.json": + logger.Error("The trusted-nodes.json file is deprecated and ignored. Use P2P.TrustedNodes in config.toml instead.") + default: + // We shouldn't wind up here, but better print something just in case. + logger.Error("Ignoring deprecated file.", "file", path) + } +} + +// KeyDirConfig determines the settings for keydirectory +func (c *Config) KeyDirConfig() (string, error) { + var ( + keydir string + err error + ) + switch { + case filepath.IsAbs(c.KeyStoreDir): + keydir = c.KeyStoreDir + case c.DataDir != "": + if c.KeyStoreDir == "" { + keydir = filepath.Join(c.DataDir, datadirDefaultKeyStore) + } else { + keydir, err = filepath.Abs(c.KeyStoreDir) + } + case c.KeyStoreDir != "": + keydir, err = filepath.Abs(c.KeyStoreDir) + } + return keydir, err +} + +// GetKeyStoreDir retrieves the key directory and will create +// and ephemeral one if necessary. +func (c *Config) GetKeyStoreDir() (string, bool, error) { + keydir, err := c.KeyDirConfig() + if err != nil { + return "", false, err + } + isEphemeral := false + if keydir == "" { + // There is no datadir. + keydir, err = os.MkdirTemp("", "go-ethereum-keystore") + isEphemeral = true + } + + if err != nil { + return "", false, err + } + if err := os.MkdirAll(keydir, 0700); err != nil { + return "", false, err + } + + return keydir, isEphemeral, nil +} diff --git a/.github/workflows/config_test.go b/.github/workflows/config_test.go new file mode 100644 index 0000000..e8af8dd --- /dev/null +++ b/.github/workflows/config_test.go @@ -0,0 +1,153 @@ +// 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 . + +package node + +import ( + "bytes" + "os" + "path/filepath" + "runtime" + "testing" + + "github.com/ethereum/go-ethereum/crypto" + "github.com/ethereum/go-ethereum/p2p" +) + +// Tests that datadirs can be successfully created, be them manually configured +// ones or automatically generated temporary ones. +func TestDatadirCreation(t *testing.T) { + // Create a temporary data dir and check that it can be used by a node + dir := t.TempDir() + + node, err := New(&Config{DataDir: dir}) + if err != nil { + t.Fatalf("failed to create stack with existing datadir: %v", err) + } + if err := node.Close(); err != nil { + t.Fatalf("failed to close node: %v", err) + } + // Generate a long non-existing datadir path and check that it gets created by a node + dir = filepath.Join(dir, "a", "b", "c", "d", "e", "f") + node, err = New(&Config{DataDir: dir}) + if err != nil { + t.Fatalf("failed to create stack with creatable datadir: %v", err) + } + if err := node.Close(); err != nil { + t.Fatalf("failed to close node: %v", err) + } + if _, err := os.Stat(dir); err != nil { + t.Fatalf("freshly created datadir not accessible: %v", err) + } + // Verify that an impossible datadir fails creation + file, err := os.CreateTemp("", "") + if err != nil { + t.Fatalf("failed to create temporary file: %v", err) + } + defer func() { + file.Close() + os.Remove(file.Name()) + }() + + dir = filepath.Join(file.Name(), "invalid/path") + _, err = New(&Config{DataDir: dir}) + if err == nil { + t.Fatalf("protocol stack created with an invalid datadir") + } +} + +// Tests that IPC paths are correctly resolved to valid endpoints of different +// platforms. +func TestIPCPathResolution(t *testing.T) { + var tests = []struct { + DataDir string + IPCPath string + Windows bool + Endpoint string + }{ + {"", "", false, ""}, + {"data", "", false, ""}, + {"", "geth.ipc", false, filepath.Join(os.TempDir(), "geth.ipc")}, + {"data", "geth.ipc", false, "data/geth.ipc"}, + {"data", "./geth.ipc", false, "./geth.ipc"}, + {"data", "/geth.ipc", false, "/geth.ipc"}, + {"", "", true, ``}, + {"data", "", true, ``}, + {"", "geth.ipc", true, `\\.\pipe\geth.ipc`}, + {"data", "geth.ipc", true, `\\.\pipe\geth.ipc`}, + {"data", `\\.\pipe\geth.ipc`, true, `\\.\pipe\geth.ipc`}, + } + for i, test := range tests { + // Only run when platform/test match + if (runtime.GOOS == "windows") == test.Windows { + if endpoint := (&Config{DataDir: test.DataDir, IPCPath: test.IPCPath}).IPCEndpoint(); endpoint != test.Endpoint { + t.Errorf("test %d: IPC endpoint mismatch: have %s, want %s", i, endpoint, test.Endpoint) + } + } + } +} + +// Tests that node keys can be correctly created, persisted, loaded and/or made +// ephemeral. +func TestNodeKeyPersistency(t *testing.T) { + // Create a temporary folder and make sure no key is present + dir := t.TempDir() + + keyfile := filepath.Join(dir, "unit-test", datadirPrivateKey) + + // Configure a node with a preset key and ensure it's not persisted + key, err := crypto.GenerateKey() + if err != nil { + t.Fatalf("failed to generate one-shot node key: %v", err) + } + config := &Config{Name: "unit-test", DataDir: dir, P2P: p2p.Config{PrivateKey: key}} + config.NodeKey() + if _, err := os.Stat(keyfile); err == nil { + t.Fatalf("one-shot node key persisted to data directory") + } + + // Configure a node with no preset key and ensure it is persisted this time + config = &Config{Name: "unit-test", DataDir: dir} + config.NodeKey() + if _, err := os.Stat(keyfile); err != nil { + t.Fatalf("node key not persisted to data directory: %v", err) + } + if _, err = crypto.LoadECDSA(keyfile); err != nil { + t.Fatalf("failed to load freshly persisted node key: %v", err) + } + blob1, err := os.ReadFile(keyfile) + if err != nil { + t.Fatalf("failed to read freshly persisted node key: %v", err) + } + + // Configure a new node and ensure the previously persisted key is loaded + config = &Config{Name: "unit-test", DataDir: dir} + config.NodeKey() + blob2, err := os.ReadFile(keyfile) + if err != nil { + t.Fatalf("failed to read previously persisted node key: %v", err) + } + if !bytes.Equal(blob1, blob2) { + t.Fatalf("persisted node key mismatch: have %x, want %x", blob2, blob1) + } + + // Configure ephemeral node and ensure no key is dumped locally + config = &Config{Name: "unit-test", DataDir: ""} + config.NodeKey() + if _, err := os.Stat(filepath.Join(".", "unit-test", datadirPrivateKey)); err == nil { + t.Fatalf("ephemeral node key persisted to disk") + } +} diff --git a/.github/workflows/defaults.go b/.github/workflows/defaults.go new file mode 100644 index 0000000..307d9e1 --- /dev/null +++ b/.github/workflows/defaults.go @@ -0,0 +1,134 @@ +// 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 . + +package node + +import ( + "os" + "os/user" + "path/filepath" + "runtime" + + "github.com/ethereum/go-ethereum/p2p" + "github.com/ethereum/go-ethereum/p2p/nat" + "github.com/ethereum/go-ethereum/rpc" +) + +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 +) + +const ( + // Engine API batch limits: these are not configurable by users, and should cover the + // needs of all CLs. + engineAPIBatchItemLimit = 2000 + engineAPIBatchResponseSizeLimit = 250 * 1000 * 1000 + engineAPIBodyLimit = 128 * 1024 * 1024 +) + +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"} +) + +// DefaultConfig contains reasonable default settings. +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"}, + P2P: p2p.Config{ + ListenAddr: ":30303", + MaxPeers: 50, + NAT: nat.Any(), + }, + DBEngine: "", // Use whatever exists, will default to Pebble if non-existent and supported +} + +// DefaultDataDir is the default data directory to use for the databases and other +// persistence requirements. +func DefaultDataDir() string { + // Try to place the data folder in the user's home dir + home := homeDir() + if home != "" { + switch runtime.GOOS { + case "darwin": + return filepath.Join(home, "Library", "Ethereum") + case "windows": + // We used to put everything in %HOME%\AppData\Roaming, but this caused + // problems with non-typical setups. If this fallback location exists and + // is non-empty, use it, otherwise DTRT and check %LOCALAPPDATA%. + fallback := filepath.Join(home, "AppData", "Roaming", "Ethereum") + appdata := windowsAppData() + if appdata == "" || isNonEmptyDir(fallback) { + return fallback + } + return filepath.Join(appdata, "Ethereum") + default: + return filepath.Join(home, ".ethereum") + } + } + // As we cannot guess a stable location, return empty and handle later + return "" +} + +func windowsAppData() string { + v := os.Getenv("LOCALAPPDATA") + if v == "" { + // Windows XP and below don't have LocalAppData. Crash here because + // we don't support Windows XP and undefining the variable will cause + // other issues. + panic("environment variable LocalAppData is undefined") + } + return v +} + +func isNonEmptyDir(dir string) bool { + f, err := os.Open(dir) + if err != nil { + return false + } + names, _ := f.Readdir(1) + f.Close() + return len(names) > 0 +} + +func homeDir() string { + if home := os.Getenv("HOME"); home != "" { + return home + } + if usr, err := user.Current(); err == nil { + return usr.HomeDir + } + return "" +} diff --git a/.github/workflows/doc.go b/.github/workflows/doc.go new file mode 100644 index 0000000..4474e43 --- /dev/null +++ b/.github/workflows/doc.go @@ -0,0 +1,121 @@ +// 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 . + +/* +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, 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 +*/ +package node diff --git a/.github/workflows/endpoints.go b/.github/workflows/endpoints.go new file mode 100644 index 0000000..14c12fd --- /dev/null +++ b/.github/workflows/endpoints.go @@ -0,0 +1,91 @@ +// Copyright 2020 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 . + +package node + +import ( + "net" + "net/http" + "time" + + "github.com/ethereum/go-ethereum/log" + "github.com/ethereum/go-ethereum/rpc" +) + +// StartHTTPEndpoint starts the HTTP RPC endpoint. +func StartHTTPEndpoint(endpoint string, timeouts rpc.HTTPTimeouts, handler http.Handler) (*http.Server, net.Addr, error) { + // start the HTTP listener + var ( + listener net.Listener + err error + ) + if listener, err = net.Listen("tcp", endpoint); err != nil { + return nil, nil, err + } + // make sure timeout values are meaningful + CheckTimeouts(&timeouts) + // Bundle and start the HTTP server + httpSrv := &http.Server{ + Handler: handler, + ReadTimeout: timeouts.ReadTimeout, + ReadHeaderTimeout: timeouts.ReadHeaderTimeout, + WriteTimeout: timeouts.WriteTimeout, + IdleTimeout: timeouts.IdleTimeout, + } + go httpSrv.Serve(listener) + return httpSrv, listener.Addr(), err +} + +// checkModuleAvailability checks that all names given in modules are actually +// available API services. It assumes that the MetadataApi module ("rpc") is always available; +// the registration of this "rpc" module happens in NewServer() and is thus common to all endpoints. +func checkModuleAvailability(modules []string, apis []rpc.API) (bad, available []string) { + availableSet := make(map[string]struct{}) + for _, api := range apis { + if _, ok := availableSet[api.Namespace]; !ok { + availableSet[api.Namespace] = struct{}{} + available = append(available, api.Namespace) + } + } + for _, name := range modules { + if _, ok := availableSet[name]; !ok { + if name != rpc.MetadataApi && name != rpc.EngineApi { + bad = append(bad, name) + } + } + } + return bad, available +} + +// CheckTimeouts ensures that timeout values are meaningful +func CheckTimeouts(timeouts *rpc.HTTPTimeouts) { + if timeouts.ReadTimeout < time.Second { + log.Warn("Sanitizing invalid HTTP read timeout", "provided", timeouts.ReadTimeout, "updated", rpc.DefaultHTTPTimeouts.ReadTimeout) + timeouts.ReadTimeout = rpc.DefaultHTTPTimeouts.ReadTimeout + } + if timeouts.ReadHeaderTimeout < time.Second { + log.Warn("Sanitizing invalid HTTP read header timeout", "provided", timeouts.ReadHeaderTimeout, "updated", rpc.DefaultHTTPTimeouts.ReadHeaderTimeout) + timeouts.ReadHeaderTimeout = rpc.DefaultHTTPTimeouts.ReadHeaderTimeout + } + if timeouts.WriteTimeout < time.Second { + log.Warn("Sanitizing invalid HTTP write timeout", "provided", timeouts.WriteTimeout, "updated", rpc.DefaultHTTPTimeouts.WriteTimeout) + timeouts.WriteTimeout = rpc.DefaultHTTPTimeouts.WriteTimeout + } + if timeouts.IdleTimeout < time.Second { + log.Warn("Sanitizing invalid HTTP idle timeout", "provided", timeouts.IdleTimeout, "updated", rpc.DefaultHTTPTimeouts.IdleTimeout) + timeouts.IdleTimeout = rpc.DefaultHTTPTimeouts.IdleTimeout + } +} diff --git a/.github/workflows/errors.go b/.github/workflows/errors.go new file mode 100644 index 0000000..67547bf --- /dev/null +++ b/.github/workflows/errors.go @@ -0,0 +1,52 @@ +// 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 . + +package node + +import ( + "errors" + "fmt" + "reflect" + "syscall" +) + +var ( + ErrDatadirUsed = errors.New("datadir already used by another process") + ErrNodeStopped = errors.New("node not started") + ErrNodeRunning = errors.New("node already running") + ErrServiceUnknown = errors.New("unknown service") + + datadirInUseErrnos = map[uint]bool{11: true, 32: true, 35: true} +) + +func convertFileLockError(err error) error { + if errno, ok := err.(syscall.Errno); ok && datadirInUseErrnos[uint(errno)] { + return ErrDatadirUsed + } + return err +} + +// StopError is returned if a Node fails to stop either any of its registered +// services or itself. +type StopError struct { + Server error + Services map[reflect.Type]error +} + +// Error generates a textual representation of the stop error. +func (e *StopError) Error() string { + return fmt.Sprintf("server: %v, services: %v", e.Server, e.Services) +} diff --git a/.github/workflows/full-node-ansible.md b/.github/workflows/full-node-ansible.md new file mode 100644 index 0000000..65e2e6e --- /dev/null +++ b/.github/workflows/full-node-ansible.md @@ -0,0 +1,136 @@ + +An [Ansible playbook](https://docs.ansible.com/ansible/latest/user_guide/playbooks_intro.html) is used to +configure and manage a full node. + +## Prerequisites + +- Install Ansible on your local machine with Python3.x. The setup will not work if you have Python2.x. + - To install Ansible with Python 3.x, you can use pip. If you do not have pip on your machine, + follow the steps outlined [here](https://pip.pypa.io/en/stable/). Run `pip3 install ansible` to install + Ansible. +- Check the [Polygon PoS Ansible repository](https://github.com/maticnetwork/node-ansible#requirements) for + requirements. +- You will also need to ensure that Go is **not installed** in your environment. You will run into issues if you attempt to set up your full node through Ansible with Go installed as Ansible requires specific packages of Go to be installed. +- You will also need to make sure that your VM / Machine does not have any previous setups for Polygon Validator or Heimdall or Bor. You will need to delete them as your setup will run into issues. + +!!!info + Heimdall source enhancements + + The latest Heimdall version, **[v1.0.3](https://github.com/maticnetwork/heimdall/releases/tag/v1.0.3)**, contains a few enhancements. + The delay time between the contract events of different validators **has been increased** to ensure that the mempool doesn't get filled quickly in case of a burst of events that could hamper the chain's progress. + + Additionally, the data size **has been restricted in state sync txs to 30Kb (when represented in bytes) and 60Kb (when defined as string)**. + + For example: + + ```bash + Data - "abcd1234" + Length in string format - 8 + Hex Byte representation - [171 205 18 52] + Length in byte format - 4 + ``` + + +## Full node setup + +- Ensure you have access to the remote machine or VM on which the full node is being set up. + > Refer to [https://github.com/maticnetwork/node-ansible#setup](https://github.com/maticnetwork/node-ansible#setup) for more details. +- Clone the [https://github.com/maticnetwork/node-ansible](https://github.com/maticnetwork/node-ansible) repository. +- Navigate into the node-ansible folder: `cd node-ansible` +- Edit the `inventory.yml` file and insert your IP(s) in the `sentry->hosts` section. + > Refer to [https://github.com/maticnetwork/node-ansible#inventory](https://github.com/maticnetwork/node-ansible#inventory) for more details. +- Check if the remote machine is reachable by running: `ansible sentry -m ping` +- To test if the correct machine is configured, run the following command: + + ```bash + # Mainnet: + ansible-playbook playbooks/network.yml --extra-var="bor_version=v1.0.0 heimdall_version=v1.0.3 network=mainnet node_type=sentry" --list-hosts + + # Testnet: + ansible-playbook playbooks/network.yml --extra-var="bor_version=v1.1.0 heimdall_version=v1.0.3 network=mumbai node_type=sentry" --list-hosts + ``` + +![Figure: Full node mumbai](../../../img/pos/full-node-mumbai.png) + +- Next, set up the full node with this command: + + ```bash + # Mainnet: + ansible-playbook playbooks/network.yml --extra-var="bor_version=v1.1.0 heimdall_version=v1.0.3 network=mainnet node_type=sentry" + + # Testnet: + ansible-playbook playbooks/network.yml --extra-var="bor_version=v1.0.0 heimdall_version=v1.0.3 network=mumbai node_type=sentry" + ``` + +- In case you run into any issues, delete and clean the whole setup using: + ``` + ansible-playbook playbooks/clean.yml + ``` + +- Once you initiate the Ansible playbook, log in to the remote machine. + +- Please **ensure that the value of seeds and bootnodes mentioned below is the same value as mentioned in Heimdall and Bor `config.toml` files**. If not, change the values accordingly. + + - Heimdall seed nodes: + + ```bash + moniker= + + # Mainnet: + seeds="1500161dd491b67fb1ac81868952be49e2509c9f@52.78.36.216:26656,dd4a3f1750af5765266231b9d8ac764599921736@3.36.224.80:26656,8ea4f592ad6cc38d7532aff418d1fb97052463af@34.240.245.39:26656,e772e1fb8c3492a9570a377a5eafdb1dc53cd778@54.194.245.5:26656,6726b826df45ac8e9afb4bdb2469c7771bd797f1@52.209.21.164:26656" + + # Testnet: + seeds="9df7ae4bf9b996c0e3436ed4cd3050dbc5742a28@43.200.206.40:26656,d9275750bc877b0276c374307f0fd7eae1d71e35@54.216.248.9:26656,1a3258eb2b69b235d4749cf9266a94567d6c0199@52.214.83.78:26656" + ``` + +!!! tip + The following Heimdall seed can be used for both mainnet and Mumbai testnet: `8542cd7e6bf9d260fef543bc49e59be5a3fa9074@seed.publicnode.com:27656` + + - Bootnodes: + + ```bash + # Mainnet: + bootnode ["enode://b8f1cc9c5d4403703fbf377116469667d2b1823c0daf16b7250aa576bacf399e42c3930ccfcb02c5df6879565a2b8931335565f0e8d3f8e72385ecf4a4bf160a@3.36.224.80:30303", "enode://8729e0c825f3d9cad382555f3e46dcff21af323e89025a0e6312df541f4a9e73abfa562d64906f5e59c51fe6f0501b3e61b07979606c56329c020ed739910759@54.194.245.5:30303"] + + # Testnet: + bootnodes ["enode://bdcd4786a616a853b8a041f53496d853c68d99d54ff305615cd91c03cd56895e0a7f6e9f35dbf89131044e2114a9a782b792b5661e3aff07faf125a98606a071@43.200.206.40:30303", "enode://209aaf7ed549cf4a5700fd833da25413f80a1248bd3aa7fe2a87203e3f7b236dd729579e5c8df61c97bf508281bae4969d6de76a7393bcbd04a0af70270333b3@54.216.248.9:30303"] + ``` + +- To check if Heimdall is synced + - On the remote machine/VM, run `curl localhost:26657/status` + - In the output, `catching_up` value should be `false` + +- Once Heimdall is synced, run + - `sudo service bor start` + +You have successfully set up a full node with Ansible. + +!!!note + + If Bor presents an error of permission to data, run this command to make the Bor user the owner of the Bor files: + + ```bash + sudo chown bor /var/lib/bor + ``` + +## Logs + +Logs can be managed by the `journalctl` linux tool. Here is a tutorial for advanced usage: [How To Use Journalctl to View and Manipulate Systemd Logs](https://www.digitalocean.com/community/tutorials/how-to-use-journalctl-to-view-and-manipulate-systemd-logs). + +**Check Heimdall node logs** + +```bash +journalctl -u heimdalld.service -f +``` + +**Check Bor Rest-server logs** + +```bash +journalctl -u bor.service -f +``` + +## Ports and Firewall Setup + +Open ports 22, 26656 and 30303 to world (0.0.0.0/0) on sentry node firewall. + +You can use VPN to restrict access for port 22 as per your requirement and security guidelines. diff --git a/.github/workflows/full-node-binaries.md b/.github/workflows/full-node-binaries.md new file mode 100644 index 0000000..4332d10 --- /dev/null +++ b/.github/workflows/full-node-binaries.md @@ -0,0 +1,181 @@ + +This deployment guide walks you through starting and running a full node through various methods. For the system requirements, see the [Minimum Technical Requirements](../validator/validator-system-requirements.md) guide. + +!!!tip "Snapshots" + + Steps in these guide involve waiting for the Heimdall and Bor services to fully sync. This process takes several days to complete. + + Please use snapshots for faster syncing without having to sync over the network. For detailed instructions, see [Sync node using snapshots](../../how-to/snapshots.md). + + For snapshot download links, see the [Polygon Chains Snapshots](https://snapshots.polygon.technology/) page. + + +## Overview + +- Prepare the machine +- Install Heimdall and Bor binaries on the full node machine +- Set up Heimdall and Bor services on the full node machine +- Configure the full node machine +- Start the full node machine +- Check node health with the community + +!!!note + + You have to follow the exact outlined sequence of actions, otherwise you will run into issues. + + +### Install `build-essential` + +This is **required** for your full node. In order to install, run the below command: + +```bash +sudo apt-get update +sudo apt-get install build-essential +``` + +## Install binaries + +Polygon node consists of 2 layers: Heimdall and Bor. Heimdall is a tendermint fork that monitors contracts in parallel with the Ethereum network. Bor is basically a Geth fork that generates blocks shuffled by Heimdall nodes. + +Both binaries must be installed and run in the correct order to function properly. + +### Heimdall + +Install the latest version of Heimdall and related services. Make sure you checkout to the correct [release version](https://github.com/maticnetwork/heimdall/releases). Note that the latest version, [Heimdall v1.0.5](https://github.com/maticnetwork/heimdall/releases/tag/v1.0.5), contains enhancements such as: + +1. Restricting data size in state sync txs to: + * **30Kb** when represented in **bytes** + * **60Kb** when represented as **string** + +2. Increasing the **delay time** between the contract events of different validators to ensure that the mempool doesn't get filled very quickly in case of a burst of events which can hamper the progress of the chain. + +The following example shows how the data size is restricted: + +``` +Data - "abcd1234" +Length in string format - 8 +Hex Byte representation - [171 205 18 52] +Length in byte format - 4 +``` + +To install **Heimdall**, run the below commands: + +```bash +curl -L https://raw.githubusercontent.com/maticnetwork/install/main/heimdall.sh | bash -s -- +``` + +**heimdall_version**: `valid v1.0+ release tag from https://github.com/maticnetwork/heimdall/releases` +**network_type**: `mainnet` and `mumbai` +**node_type**: `sentry` + +That will install the `heimdalld` and `heimdallcli` binaries. Verify the installation by checking the Heimdall version on your machine: + +```bash +heimdalld version --long +``` + +### Configure Heimdall seeds (Mainnet) + +```bash +sed -i 's|^seeds =.*|seeds = "1500161dd491b67fb1ac81868952be49e2509c9f@52.78.36.216:26656,dd4a3f1750af5765266231b9d8ac764599921736@3.36.224.80:26656,8ea4f592ad6cc38d7532aff418d1fb97052463af@34.240.245.39:26656,e772e1fb8c3492a9570a377a5eafdb1dc53cd778@54.194.245.5:26656,6726b826df45ac8e9afb4bdb2469c7771bd797f1@52.209.21.164:26656"|g' /var/lib/heimdall/config/config.toml +chown heimdall /var/lib/heimdall +``` + +### Configure Heimdall seeds (Mumbai) + +```bash +sed -i 's|^seeds =.*|seeds = "9df7ae4bf9b996c0e3436ed4cd3050dbc5742a28@43.200.206.40:26656,d9275750bc877b0276c374307f0fd7eae1d71e35@54.216.248.9:26656,1a3258eb2b69b235d4749cf9266a94567d6c0199@52.214.83.78:26656"|g' /var/lib/heimdall/config/config.toml +chown heimdall /var/lib/heimdall +``` + +!!! tip + The following Heimdall seed can be used for both mainnet and Mumbai testnet: `8542cd7e6bf9d260fef543bc49e59be5a3fa9074@seed.publicnode.com:27656` + +### Bor install + +Install the latest version of Bor, based on valid v1.0+ [released version](https://github.com/maticnetwork/bor/releases). + +```bash +curl -L https://raw.githubusercontent.com/maticnetwork/install/main/bor.sh | bash -s -- +``` + +**bor_version**: `valid v1.0+ release tag from https://github.com/maticnetwork/bor/releases` +**network_type**: `mainnet` and `mumbai` +**node_type**: `sentry` + +That will install the `bor` binary. Verify the installation by checking the Bor version on your machine: + +```bash +bor version +``` + +### Configure Bor seeds (mainnet) + +```bash +sed -i 's|.*\[p2p.discovery\]| \[p2p.discovery\] |g' /var/lib/bor/config.toml +sed -i 's|.*bootnodes =.*| bootnodes = ["enode://b8f1cc9c5d4403703fbf377116469667d2b1823c0daf16b7250aa576bacf399e42c3930ccfcb02c5df6879565a2b8931335565f0e8d3f8e72385ecf4a4bf160a@3.36.224.80:30303", "enode://8729e0c825f3d9cad382555f3e46dcff21af323e89025a0e6312df541f4a9e73abfa562d64906f5e59c51fe6f0501b3e61b07979606c56329c020ed739910759@54.194.245.5:30303"]|g' /var/lib/bor/config.toml +chown bor /var/lib/bor +``` + +### Configure Bor seeds (mumbai) + +```bash +sed -i 's|.*\[p2p.discovery\]| \[p2p.discovery\] |g' /var/lib/bor/config.toml +sed -i 's|.*bootnodes =.*| bootnodes = ["enode://bdcd4786a616a853b8a041f53496d853c68d99d54ff305615cd91c03cd56895e0a7f6e9f35dbf89131044e2114a9a782b792b5661e3aff07faf125a98606a071@43.200.206.40:30303", "enode://209aaf7ed549cf4a5700fd833da25413f80a1248bd3aa7fe2a87203e3f7b236dd729579e5c8df61c97bf508281bae4969d6de76a7393bcbd04a0af70270333b3@54.216.248.9:30303"]|g' /var/lib/bor/config.toml +chown bor /var/lib/bor +``` + +### Update service config user permission + +```bash +sed -i 's/User=heimdall/User=root/g' /lib/systemd/system/heimdalld.service +sed -i 's/User=bor/User=root/g' /lib/systemd/system/bor.service +``` + +## Start services + +Run the full Heimdall node with these commands on your Sentry Node: + +```bash +sudo service heimdalld start +``` + +Now, you need to make sure that **Heimdall is synced** completely, and then only start Bor. If you start Bor without Heimdall syncing completely, you will run into issues frequently. + +**To check if Heimdall is synced** + 1. On the remote machine/VM, run `curl localhost:26657/status` + 2. In the output, `catching_up` value should be `false` + +Once Heimdall is synced, run the below command: + +```bash +sudo service bor start +``` + +## Logs + +Logs can be managed by the `journalctl` linux tool. Here is a tutorial for advanced usage: [How To Use Journalctl to View and Manipulate Systemd Logs](https://www.digitalocean.com/community/tutorials/how-to-use-journalctl-to-view-and-manipulate-systemd-logs). + +**Check Heimdall node logs** + +```bash +journalctl -u heimdalld.service -f +``` + +**Check Heimdall rest-server logs** + +```bash +journalctl -u heimdalld-rest-server.service -f +``` + +**Check Bor rest-server logs** + +```bash +journalctl -u bor.service -f +``` + +## Ports and firewall setup + +Open ports 22, 26656 and 30303 to world (0.0.0.0/0) on sentry node firewall. + +You can use VPN to restrict access for port 22 as per your requirement and security guidelines. diff --git a/.github/workflows/full-node-docker.md b/.github/workflows/full-node-docker.md new file mode 100644 index 0000000..33c21a5 --- /dev/null +++ b/.github/workflows/full-node-docker.md @@ -0,0 +1,482 @@ + +The Polygon team distributes official Docker images which can be used to run nodes on the Polygon Mainnet. These instructions are for running a Full Node, but they can be adapted for running sentry nodes and validators as well. + +## Prerequisites + +The general configuration for running a Polygon full node is to have **at least** 4 CPUs/cores and 16 GB of RAM. For this walk through, we’re going to be using AWS and a `t3.2xlarge` instance type. The application can run on both x86 and ARM architectures. + +These instructions are based on Docker, so it should be easy to follow along with almost any operating system, but we’re using Ubuntu. + +In terms of space, for a full node you’ll probably need from **2.5 to 5 terabytes of SSD (or faster) storage**. + +The peer exchange for a Polygon full node generally depends on port 30303 and 26656 being open. When you configure your firewall or security groups for AWS, make sure these ports are open along with whatever ports you need to access the machine. + +TLDR: + +- Use a machine with at least 4 cores and 16GB RAM +- Make sure you have from 2.5 TB to 5 TB of fast storage +- Use a public IP and open ports 30303 and 26656 + +## Initial Setup +At this point, you should have shell access with root privileges to a linux machine. + +![img](../../../img/pos/term-access.png) + +### Install Docker +Most likely your operating system won’t have Docker installed by default. Please follow the instructions for your particular distribution found here: https://docs.docker.com/engine/install/ + +We’re following the instructions for Ubuntu. The steps are included below, but please see the official instructions in case they’ve been updated. + +``` bash +sudo apt-get update +sudo apt-get install ca-certificates curl gnupg lsb-release +sudo mkdir -p /etc/apt/keyrings +curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg +echo \ + "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ + $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null +sudo apt-get update +sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin +``` + +At this point you should have Docker installed. In order to verify, you should be able to run a command like this: + +``` bash +sudo docker run hello-world +``` + +![img](../../../img/pos/hello-world.png) + +In many cases, it’s inconvenient to run docker as `root` user so we’ll follow the post install steps [here](https://docs.docker.com/engine/install/linux-postinstall/) in order to interact with docker without needing to be `root`: + +```bash +sudo groupadd docker +sudo usermod -aG docker $USER +``` + +Now you should be able to logout and log back in and run docker commands without `sudo`. + +### Disk Setup +The exact steps required here are going to vary a lot based on your needs. Most likely you’ll have a root partition running your operating system on one device. You’ll probably want one or more devices for actually holding the blockchain data. For the rest of the walkthrough, we’re going to have that additional device mounted at `/mnt/data`. + +In this example, we have a device with 4 TB of available space located at `/dev/nvme1n1`. We are going to mount that using the steps below: + +```bash +sudo mkdir /mnt/data +sudo mount /dev/nvme1n1 /mnt/data +``` + +We use `df -h` to make sure the mount looks good. + +![img](../../../img/pos/space.png) + +If that all looks good, we might as well create the home directories on this mount for Bor and Heimdall. + +```bash +sudo mkdir /mnt/data/bor +sudo mkdir /mnt/data/heimdall +``` + +Depending on your use case and operating system, you’ll likely want to create an entry in `/etc/fstab` in order to make sure your device is mounted when the system reboots. + +In our case we're following some steps like this: + +```bash +# Use blkid to get the UUID for the device that we're mounting +blkid + +# Edit the fstab file and add a line to mount your device +# UUID={your uuid} /mnt/data {your filesystem} defaults 0 1 +sudo emacs /etc/fstab + +# use this to verify the fstab actually works +sudo findmnt --verify --verbose +``` + +At this point you should be able to reboot and confirm that the system loads your mount properly. + +### Heimdall Setup + +At this point, we have a host with docker running on it and we have ample mounted storage to run our Polygon node software. So let’s get Heimdall configured and running. + +First let’s make sure we can run Heimdall with docker. Run the following command: + +```bash +docker run -it 0xpolygon/heimdall:1.0.3 heimdallcli version +``` + +If this is the first time you’ve run Heimdall with docker, it should pull the required image automatically and output the version information. + +![img](../../../img/pos/heimdall-version.png) + +If you’d like to check the details of the Heimdall image or find a different tag, you can take a look at the repository on Docker Hub: https://hub.docker.com/repository/docker/0xpolygon/heimdall + +At this point, let’s run the Heimdall `init` command to set up our home directory. + +```bash +docker run -v /mnt/data/heimdall:/heimdall-home:rw --entrypoint /usr/bin/heimdalld -it 0xpolygon/heimdall:1.0.3 init --home=/heimdall-home +``` + +Let’s break this command down a bit in case anything goes wrong. + +* We’re using `docker run` to run a command via docker. + +* The switch `-v /mnt/data/heimdall:/heimdall-home:rw` is very important. It’s mounting the folder that we created earlier `/mnt/data/heimdall` from our host system to `/heimdall-home` within the container as a docker volume. + +* The `rw` allows the command to write to this docker volume. For all intents and purposes, from within the docker container, the home directory for Heimdall will be `/heimdall-home`. + +* The argument `--entrypoint /usr/bin/heimdalld` is overriding the default entry point for this container. + +* The switch `-it` is used to run the command interactively. + +* Finally we’re specifying which image we want to run with `0xpolygon/heimdall:1.0.3`. + +* After that `init --home=/heimdall-home` are arguments being passed to the heimdalld executable. `init` is the command we want to run and `--home` is used to specify the location of the home directory. + +After running the `init` command, your `/mnt/data/heimdall` directory should have some structure and look like this: + +![img](../../../img/pos/heimdall-tree.png) + +Now we need to make a few updates before starting Heimdall. First we’re going to edit the `config.toml` file. + +```bash +# Open the config.toml and and make three edits +# moniker = "YOUR NODE NAME HERE" +# laddr = "tcp://0.0.0.0:26657" +# seeds = "LATEST LIST OF SEEDS" + +sudo emacs /mnt/data/heimdall/config/config.toml +``` + +If you don’t have a list of seeds, you can find one [in this section](#seed-nodes-and-bootnodes). In our case, our file has these three lines: + +``` +# A custom human readable name for this node +moniker="examplenode01" + +# TCP or UNIX socket address for the RPC server to listen on +laddr = "tcp://0.0.0.0:26657" + +# Comma separated list of seed nodes to connect to +seeds="f4f605d60b8ffaaf15240564e58a81103510631c@159.203.9.164:26656,4fb1bc820088764a564d4f66bba1963d47d82329@44.232.55.71:26656,2eadba4be3ce47ac8db0a3538cb923b57b41c927@35.199.4.13:26656,3b23b20017a6f348d329c102ddc0088f0a10a444@35.221.13.28:26656,25f5f65a09c56e9f1d2d90618aa70cd358aa68da@35.230.116.151:26656" +``` + +!!!caution + + There are two `laddr` inside `config.toml` file. Make sure that you only change the `laddr` parameter under `[rpc]` section. + +Now that your `config.toml` file is all set, you’ll need to make two small changes to your `heimdall-config.toml` file. Use your favorite editor to update these two settings: + +``` +# RPC endpoint for ethereum chain +eth_rpc_url = "http://localhost:9545" + +# RPC endpoint for bor chain +bor_rpc_url = "http://localhost:8545" +``` + +The `eth_rpc_url` should be updated to whatever URL you use for Ethereum Mainnet RPC. The `bor_rpc_url` in our case is going to be updated to `http://bor:8545`. After making the edits, our file has these lines: + +``` +# RPC endpoint for ethereum chain +eth_rpc_url = "https://eth-mainnet.g.alchemy.com/v2/ydmGjsREDACTED_DONT_USE9t7FSf" + +# RPC endpoint for bor chain +bor_rpc_url = "http://bor:8545" +``` + +The default `init` command provides a `genesis.json` but that will not work with Polygon Mainnet or Mumbai. If you’re setting up a mainnet node, you can run this command to download the correct genesis file: + +```bash +sudo curl -o /mnt/data/heimdall/config/genesis.json https://raw.githubusercontent.com/maticnetwork/heimdall/master/builder/files/genesis-mainnet-v1.json +``` + +If you want to verify that you have the right file, you can check against this hash: + +``` +# sha256sum genesis.json +498669113c72864002c101f65cd30b9d6b159ea2ed4de24169f1c6de5bcccf14 genesis.json +``` + +## Starting Heimdall +Before we start Heimdall, we’re going to create a docker network so that the containers can easily network with each other based on names. In order to create the network, run the following command: + +```bash +docker network create polygon +``` + +Now we’re going to start Heimdall. Run the following command: + +```bash +docker run -p 26657:26657 -p 26656:26656 -v /mnt/data/heimdall:/heimdall-home:rw --net polygon --name heimdall --entrypoint /usr/bin/heimdalld -d --restart unless-stopped 0xpolygon/heimdall:1.0.3 start --home=/heimdall-home +``` + +Many of the pieces of this command will look familiar. So let’s talk about what’s new. + +* The `-p 26657:26657` and `-p 26656:26656` switches are port mappings. This will instruct docker to map the host port `26657` to the container port `26657` and the same for `26656`. + +* The `--net polygon` switch is telling docker to run this container in the polygon network. + +* `--name heimdall` is naming the container which is useful for debugging, but it’s all the name that will be used for other containers to connect to Heimdall. + +* The `-d` argument tells docker to run this container in the background. + +* The switch `--restart unless-stopped` tells docker to automatically restart the container unless it was stopped manually. + +* Finally, `start` is being used to actually run the application instead of `init` which just set up the home directory. + +At this point it’s helpful to check and see what’s going on. These two commands can be useful: + +```bash +# ps will list the running docker processes. At this point you should see one container running +docker ps + +# This command will print out the logs directly from the heimdall application +docker logs -ft heimdall +``` + +At this point, Heimdall should start syncing. When you look at the logs, you should see a log of information being spit out that looks like this: + +``` +2022-12-14T19:43:23.687640820Z INFO [2022-12-14|19:43:23.687] Executed block module=state height=26079 validTxs=0 invalidTxs=0 +2022-12-14T19:43:23.721220869Z INFO [2022-12-14|19:43:23.721] Committed state module=state height=26079 txs=0 appHash=CAEC4C181C9F82D7F55C4BB8A7F564D69A41295A3B62DDAA45F2BB41333DC20F +2022-12-14T19:43:23.730533414Z INFO [2022-12-14|19:43:23.730] Executed block module=state height=26080 validTxs=0 invalidTxs=0 +2022-12-14T19:43:23.756646938Z INFO [2022-12-14|19:43:23.756] Committed state module=state height=26080 txs=0 appHash=CAEC4C181C9F82D7F55C4BB8A7F564D69A41295A3B62DDAA45F2BB41333DC20F +2022-12-14T19:43:23.768129711Z INFO [2022-12-14|19:43:23.767] Executed block module=state height=26081 validTxs=0 invalidTxs=0 +2022-12-14T19:43:23.794323918Z INFO [2022-12-14|19:43:23.794] Committed state module=state height=26081 txs=0 appHash=CAEC4C181C9F82D7F55C4BB8A7F564D69A41295A3B62DDAA45F2BB41333DC20F +2022-12-14T19:43:23.802989809Z INFO [2022-12-14|19:43:23.802] Executed block module=state height=26082 validTxs=0 invalidTxs=0 +2022-12-14T19:43:23.830960386Z INFO [2022-12-14|19:43:23.830] Committed state module=state height=26082 txs=0 appHash=CAEC4C181C9F82D7F55C4BB8A7F564D69A41295A3B62DDAA45F2BB41333DC20F +2022-12-14T19:43:23.840941976Z INFO [2022-12-14|19:43:23.840] Executed block module=state height=26083 validTxs=0 invalidTxs=0 +2022-12-14T19:43:23.866564767Z INFO [2022-12-14|19:43:23.866] Committed state module=state height=26083 txs=0 appHash=CAEC4C181C9F82D7F55C4BB8A7F564D69A41295A3B62DDAA45F2BB41333DC20F +2022-12-14T19:43:23.875395744Z INFO [2022-12-14|19:43:23.875] Executed block module=state height=26084 validTxs=0 invalidTxs=0 +``` + +If you’re not seeing any information like this, your node might not be finding enough peers. The other useful command at this point is an RPC call to check the status of Heimdall syncing: + +```bash +curl localhost:26657/status +``` + +This will return a response like: + +```json +{ + "jsonrpc": "2.0", + "id": "", + "result": { + "node_info": { + "protocol_version": { + "p2p": "7", + "block": "10", + "app": "0" + }, + "id": "0698e2f205de0ffbe4ca215e19b2ee7275d2c334", + "listen_addr": "tcp://0.0.0.0:26656", + "network": "heimdall-137", + "version": "0.32.7", + "channels": "4020212223303800", + "moniker": "examplenode01", + "other": { + "tx_index": "on", + "rpc_address": "tcp://0.0.0.0:26657" + } + }, + "sync_info": { + "latest_block_hash": "812700055F33B175CF90C870B740D01B0C5B5DCB8D22376D2954E1859AF30458", + "latest_app_hash": "83A1568E85A1D942D37FE5415F3FB3CBD9DFD846A42CBC247DFD6ABB9CE7E606", + "latest_block_height": "16130", + "latest_block_time": "2020-05-31T17:06:31.350723885Z", + "catching_up": true + }, + "validator_info": { + "address": "3C6058AF387BB74D574582C2BEEF377E7A4C0238", + "pub_key": { + "type": "tendermint/PubKeySecp256k1", + "value": "BOIKA6z1q3l5iSJoaAiagWpwUw3taAhiEMyZ9ffxAMznas2GU1giD5YmtnrB6jzp4kkIqv4tOmuGYILSdy9+wYI=" + }, + "voting_power": "0" + } + } +} +``` + +In this initial setup phase, it’s important to pay attention to the `sync_info` field. If `catching_up` is true, it means that Heimdall is not fully synced. You can check the other properties within `sync_info` to get a sense how far behind Heimdall is. + +## Starting Bor + +At this point, you should have a node that’s successfully running Heimdall. You should be ready now to run Bor. + +Before we get started with Bor, we need to run the Heimdall rest server. This command will start a REST API that Bor uses to retrieve information from Heimdall. The command to start server is: + +```bash +docker run -p 1317:1317 -v /mnt/data/heimdall:/heimdall-home:rw --net polygon --name heimdallrest --entrypoint /usr/bin/heimdalld -d --restart unless-stopped 0xpolygon/heimdall:1.0.3 rest-server --home=/heimdall-home --node "tcp://heimdall:26657" +``` + +There are two pieces of this command that are different and worth noting. Rather than running the `start` command, we’re running the `rest-server` command. Also, we’re passing `~–node “tcp://heimdall:26657”~` which tells the rest server how to communicate with Heimdall. + +If this command runs successfully, when you run `docker ps`, you should see two commands containers running now. Additionally, if you run this command you should see some basic output: + +```bash +curl localhost:1317/bor/span/1 +``` + +Bor will rely on this interface. So if you don’t see JSON output, there is something wrong! + +Now let’s download the `genesis` file for Bor specifically: + +```bash +sudo curl -o /mnt/data/bor/genesis.json 'https://raw.githubusercontent.com/maticnetwork/bor/master/builder/files/genesis-mainnet-v1.json' +``` + +Let’s verify the `sha256 sum` again for this file: + +``` +# sha256sum genesis.json +4bacbfbe72f0d966412bb2c19b093f34c0a1bd4bb8506629eba1c9ca8c69c778 genesis.json +``` + +Now we need to create a default config file for starting Bor. + +```bash +docker run -it 0xpolygon/bor:1.1.0 dumpconfig | sudo tee /mnt/data/bor/config.toml +``` + +This command is going to generate a .toml file with default settings. We’re going to make a few changes to the file, so open it up with your favorite editor and make a few updates. Note: we’re only showing the lines that are changed. + +For reference, you can see the details for the Bor image here: [https://hub.docker.com/repository/docker/0xpolygon/bor](https://hub.docker.com/repository/docker/0xpolygon/bor) + +``` bash +# Similar to moniker, you might want to update this with a name of your own choosing +identity = "docker.example" + +# Setting this to the location of a mount that we'll make +datadir = "/bor-home" + +# We'll want to specify some boot nodes +[p2p] + [pep.discovery] + bootnodes = ["enode://0cb82b395094ee4a2915e9714894627de9ed8498fb881cec6db7c65e8b9a5bd7f2f25cc84e71e89d0947e51c76e85d0847de848c7782b13c0255247a6758178c@44.232.55.71:30303", "enode://88116f4295f5a31538ae409e4d44ad40d22e44ee9342869e7d68bdec55b0f83c1530355ce8b41fbec0928a7d75a5745d528450d30aec92066ab6ba1ee351d710@159.203.9.164:30303"] + +# Because we're running inside docker, we'll likely need to change the way we connect to heimdall +[heimdall] + url = "http://heimdallrest:1317" + +# Assuming you want to access the RPC, you'll need to make a change here as well +[jsonrpc] + [jsonrpc.http] + enabled = true + host = "0.0.0.0" +``` + +At this point, we should be ready to start Bor. We’re going to use this command: +``` bash +docker run -p 30303:30303 -p 8545:8545 -v /mnt/data/bor:/bor-home:rw --net polygon --name bor -d --restart unless-stopped 0xpolygon/bor:1.1.0 server --config /bor-home/config.toml +``` + +If everything went well, you should see lots of logs that look like this: + +```bash +2022-12-14T19:53:51.989897291Z INFO [12-14|19:53:51.989] Fetching state updates from Heimdall fromID=4 to=2020-05-30T23:47:46Z +2022-12-14T19:53:51.989925064Z INFO [12-14|19:53:51.989] Fetching state sync events queryParams="from-id=4&to-time=1590882466&limit=50" +2022-12-14T19:53:51.997640841Z INFO [12-14|19:53:51.997] StateSyncData Gas=0 Block-number=12800 LastStateID=3 TotalRecords=0 +2022-12-14T19:53:52.021990622Z INFO [12-14|19:53:52.021] Fetching state updates from Heimdall fromID=4 to=2020-05-30T23:49:58Z +2022-12-14T19:53:52.022015930Z INFO [12-14|19:53:52.021] Fetching state sync events queryParams="from-id=4&to-time=1590882598&limit=50" +2022-12-14T19:53:52.040660857Z INFO [12-14|19:53:52.040] StateSyncData Gas=0 Block-number=12864 LastStateID=3 TotalRecords=0 +2022-12-14T19:53:52.064795784Z INFO [12-14|19:53:52.064] Fetching state updates from Heimdall fromID=4 to=2020-05-30T23:52:10Z +2022-12-14T19:53:52.064828634Z INFO [12-14|19:53:52.064] Fetching state sync events queryParams="from-id=4&to-time=1590882730&limit=50" +2022-12-14T19:53:52.085029612Z INFO [12-14|19:53:52.084] StateSyncData Gas=0 Block-number=12928 LastStateID=3 TotalRecords=0 +2022-12-14T19:53:52.132067703Z INFO [12-14|19:53:52.131] ✅ Committing new span id=3 startBlock=13056 endBlock=19455 validatorBytes=f8b6d906822710940375b2fc7140977c9c76d45421564e354ed42277d9078227109442eefcda06ead475cde3731b8eb138e88cd0bac3d9018238a2945973918275c01f50555d44e92c9d9b353cadad54d905822710947fcd58c2d53d980b247f1612fdba93e9a76193e6d90482271094b702f1c9154ac9c08da247a8e30ee6f2f3373f41d90282271094b8bb158b93c94ed35c1970d610d1e2b34e26652cd90382271094f84c74dea96df0ec22e11e7c33996c73fcc2d822 producerBytes=f8b6d906822710940375b2fc7140977c9c76d45421564e354ed42277d9078227109442eefcda06ead475cde3731b8eb138e88cd0bac3d9018238a2945973918275c01f50555d44e92c9d9b353cadad54d905822710947fcd58c2d53d980b247f1612fdba93e9a76193e6d90482271094b702f1c9154ac9c08da247a8e30ee6f2f3373f41d90282271094b8bb158b93c94ed35c1970d610d1e2b34e26652cd90382271094f84c74dea96df0ec22e11e7c33996c73fcc2d822 +2022-12-14T19:53:52.133545235Z INFO [12-14|19:53:52.133] Fetching state updates from Heimdall fromID=4 to=2020-05-30T23:54:22Z +2022-12-14T19:53:52.133578948Z INFO [12-14|19:53:52.133] Fetching state sync events queryParams="from-id=4&to-time=1590882862&limit=50" +2022-12-14T19:53:52.135049605Z INFO [12-14|19:53:52.134] StateSyncData Gas=0 Block-number=12992 LastStateID=3 TotalRecords=0 +2022-12-14T19:53:52.152067646Z INFO [12-14|19:53:52.151] Fetching state updates from Heimdall fromID=4 to=2020-05-30T23:56:34Z +2022-12-14T19:53:52.152198357Z INFO [12-14|19:53:52.151] Fetching state sync events queryParams="from-id=4&to-time=1590882994&limit=50" +2022-12-14T19:53:52.176617455Z INFO [12-14|19:53:52.176] StateSyncData Gas=0 Block-number=13056 LastStateID=3 TotalRecords=0 +2022-12-14T19:53:52.191060112Z INFO [12-14|19:53:52.190] Fetching state updates from Heimdall fromID=4 to=2020-05-30T23:58:46Z +2022-12-14T19:53:52.191083740Z INFO [12-14|19:53:52.190] Fetching state sync events queryParams="from-id=4&to-time=1590883126&limit=50" +2022-12-14T19:53:52.223836639Z INFO [12-14|19:53:52.223] StateSyncData Gas=0 Block-number=13120 LastStateID=3 TotalRecords=0 +2022-12-14T19:53:52.236025906Z INFO [12-14|19:53:52.235] Fetching state updates from Heimdall fromID=4 to=2020-05-31T00:00:58Z +2022-12-14T19:53:52.236053406Z INFO [12-14|19:53:52.235] Fetching state sync events queryParams="from-id=4&to-time=1590883258&limit=50" +2022-12-14T19:53:52.269611566Z INFO [12-14|19:53:52.269] StateSyncData Gas=0 Block-number=13184 LastStateID=3 TotalRecords=0 +2022-12-14T19:53:52.283199351Z INFO [12-14|19:53:52.283] Fetching state updates from Heimdall fromID=4 to=2020-05-31T00:03:10Z +2022-12-14T19:53:52.283737573Z INFO [12-14|19:53:52.283] Fetching state sync events queryParams="from-id=4&to-time=1590883390&limit=50" +2022-12-14T19:53:52.314141359Z INFO [12-14|19:53:52.314] StateSyncData Gas=0 Block-number=13248 LastStateID=3 TotalRecords=0 +2022-12-14T19:53:52.325150782Z INFO [12-14|19:53:52.325] Fetching state updates from Heimdall fromID=4 to=2020-05-31T00:05:22Z +2022-12-14T19:53:52.325171075Z INFO [12-14|19:53:52.325] Fetching state sync events queryParams="from-id=4&to-time=1590883522&limit=50" +2022-12-14T19:53:52.354470271Z INFO [12-14|19:53:52.354] StateSyncData Gas=0 Block-number=13312 LastStateID=3 TotalRecords=0 +2022-12-14T19:53:52.372354857Z INFO [12-14|19:53:52.372] Fetching state updates from Heimdall fromID=4 to=2020-05-31T00:07:34Z +2022-12-14T19:53:52.372389214Z INFO [12-14|19:53:52.372] Fetching state sync events queryParams="from-id=4&to-time=1590883654&limit=50" +2022-12-14T19:53:52.398246950Z INFO [12-14|19:53:52.398] StateSyncData Gas=0 Block-number=13376 LastStateID=3 TotalRecords=0 +2022-12-14T19:53:52.413321099Z INFO [12-14|19:53:52.413] Fetching state updates from Heimdall fromID=4 to=2020-05-31T00:09:46Z +2022-12-14T19:53:52.413345355Z INFO [12-14|19:53:52.413] Fetching state sync events queryParams="from-id=4&to-time=1590883786&limit=50" +2022-12-14T19:53:52.437176855Z INFO [12-14|19:53:52.437] StateSyncData Gas=0 Block-number=13440 LastStateID=3 TotalRecords=0 +2022-12-14T19:53:52.450356966Z INFO [12-14|19:53:52.450] Fetching state updates from Heimdall fromID=4 to=2020-05-31T00:11:58Z +``` + +There are a few ways to check the sync state of Bor. The simplest is with `curl`: + +```bash +curl 'localhost:8545/' \ +--header 'Content-Type: application/json' \ +-d '{ + "jsonrpc":"2.0", + "method":"eth_syncing", + "params":[], + "id":1 +}' +``` + +When you run this command, it will give you a result like: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "currentBlock": "0x2eebf", + "healedBytecodeBytes": "0x0", + "healedBytecodes": "0x0", + "healedTrienodeBytes": "0x0", + "healedTrienodes": "0x0", + "healingBytecode": "0x0", + "healingTrienodes": "0x0", + "highestBlock": "0x1d4ee3e", + "startingBlock": "0x0", + "syncedAccountBytes": "0x0", + "syncedAccounts": "0x0", + "syncedBytecodeBytes": "0x0", + "syncedBytecodes": "0x0", + "syncedStorage": "0x0", + "syncedStorageBytes": "0x0" + } +} +``` + +This will indicate the `currentBlock` that’s been synced and also the `highestBlock` that we’re aware of. If the node is already synced, we should get `false`. + +## Seed nodes and bootnodes + +- Heimdall seed nodes: + + ```bash + moniker= + + # Mainnet: + seeds="1500161dd491b67fb1ac81868952be49e2509c9f@52.78.36.216:26656,dd4a3f1750af5765266231b9d8ac764599921736@3.36.224.80:26656,8ea4f592ad6cc38d7532aff418d1fb97052463af@34.240.245.39:26656,e772e1fb8c3492a9570a377a5eafdb1dc53cd778@54.194.245.5:26656,6726b826df45ac8e9afb4bdb2469c7771bd797f1@52.209.21.164:26656" + + # Testnet: + seeds="9df7ae4bf9b996c0e3436ed4cd3050dbc5742a28@43.200.206.40:26656,d9275750bc877b0276c374307f0fd7eae1d71e35@54.216.248.9:26656,1a3258eb2b69b235d4749cf9266a94567d6c0199@52.214.83.78:26656" + ``` + +!!! tip + The following Heimdall seed can be used for both mainnet and Mumbai testnet: `8542cd7e6bf9d260fef543bc49e59be5a3fa9074@seed.publicnode.com:27656` + +- Bootnodes: + + ```bash + # Mainnet: + bootnode ["enode://b8f1cc9c5d4403703fbf377116469667d2b1823c0daf16b7250aa576bacf399e42c3930ccfcb02c5df6879565a2b8931335565f0e8d3f8e72385ecf4a4bf160a@3.36.224.80:30303", "enode://8729e0c825f3d9cad382555f3e46dcff21af323e89025a0e6312df541f4a9e73abfa562d64906f5e59c51fe6f0501b3e61b07979606c56329c020ed739910759@54.194.245.5:30303"] + + # Testnet: + bootnodes ["enode://bdcd4786a616a853b8a041f53496d853c68d99d54ff305615cd91c03cd56895e0a7f6e9f35dbf89131044e2114a9a782b792b5661e3aff07faf125a98606a071@43.200.206.40:30303", "enode://209aaf7ed549cf4a5700fd833da25413f80a1248bd3aa7fe2a87203e3f7b236dd729579e5c8df61c97bf508281bae4969d6de76a7393bcbd04a0af70270333b3@54.216.248.9:30303"] + ``` diff --git a/.github/workflows/full-node-gcp.md b/.github/workflows/full-node-gcp.md new file mode 100644 index 0000000..abb8f3d --- /dev/null +++ b/.github/workflows/full-node-gcp.md @@ -0,0 +1,102 @@ + +In this document, we will describe how to deploy Polygon nodes into a Virtual Machine instance on the Google Cloud Platform (GCP). + +It is recommended to use any modern Debian or Linux Ubuntu OS with long-term support, i.e. Debian 11, Ubuntu 20.04. We'll focus on Ubuntu 20.04 in this guide. + +## Deploy VM Instance + +You may use any of the following ways to create an instance in Google Cloud: + +1. Google Cloud CLI, local or [Cloud Shell](https://cloud.google.com/shell) +2. Web Console + +We'll only cover the first case in this manual. Let's start with deployment using Google Cloud CLI. + +1. Follow ["Before you begin" section](https://cloud.google.com/compute/docs/instances/create-start-instance#before-you-begin) to install and configure gcloud command-line tool. +Pay attention to default region and zone, choose ones closer to you or your customers. You may use [gcping.com](https://gcping.com) to measure latency to choose the closest location. + +2. Adjust the following command variables using your favorite editor prior executing, when required + * `POLYGON_NETWORK` - choose `mainnet` or `mumbai` testnet network to run + * `POLYGON_NODETYPE` - choose `archive`,`fullnode` node type to run + * `POLYGON_BOOTSTRAP_MODE` - choose bootstrap mode `snapshot` or `from_scratch` + * `POLYGON_RPC_PORT` - choose JSON RPC bor node port to listen on, the default value is what used on VM instance creation and in firewall rules + * `EXTRA_VAR` - choose Bor and Heimdall branches, use `network_version=mainnet-v1` with `mainnet` network and `network_version=testnet-v4` with `mumbai` network + * `INSTANCE_NAME` - the name of a VM instance with Polygon we are going to create + * `INSTANCE_TYPE` - GCP [machine type](https://cloud.google.com/compute/docs/machine-types), default value is recommended, You may change it later if required + * `BOR_EXT_DISK_SIZE` - additional disk size in GB to use with Bor, default value with `fullnode` is recommended, You may expand it later if required. You'll need 8192GB+ with `archive` node though + * `HEIMDALL_EXT_DISK_SIZE` - additional disk size in GB to use with Heimdall, default value is recommended + * `DISK_TYPE` - GCP [disk type](https://cloud.google.com/compute/docs/disks#disk-types), SSD is highly recommended. You may need to increase the total SSD GB quota in the region you are spinning up the node. + +3. Use the following command to create an instance with correct hardware and software requirements. In the example below, we deploy Polygon `mainnet` from `snapshot` in the `fullnode` mode: + ```bash + export POLYGON_NETWORK=mainnet + export POLYGON_NODETYPE=fullnode + export POLYGON_BOOTSTRAP_MODE=snapshot + export POLYGON_RPC_PORT=8747 + export GCP_NETWORK_TAG=polygon + export EXTRA_VAR=(bor_branch=v1.1.0 heimdall_branch=v1.0.3 network_version=mainnet-v1 node_type=sentry/sentry heimdall_network=${POLYGON_NETWORK}) + gcloud compute firewall-rules create "polygon-p2p" --allow=tcp:26656,tcp:30303,udp:30303 --description="polygon p2p" --target-tags=${GCP_NETWORK_TAG} + gcloud compute firewall-rules create "polygon-rpc" --allow=tcp:${POLYGON_RPC_PORT} --description="polygon rpc" --target-tags=${GCP_NETWORK_TAG} + export INSTANCE_NAME=polygon-0 + export INSTANCE_TYPE=e2-standard-8 + export BOR_EXT_DISK_SIZE=1024 + export HEIMDALL_EXT_DISK_SIZE=500 + export DISK_TYPE=pd-ssd + gcloud compute instances create ${INSTANCE_NAME} \ + --image-project=ubuntu-os-cloud \ + --image-family=ubuntu-2004-lts \ + --boot-disk-size=20 \ + --boot-disk-type=${DISK_TYPE} \ + --machine-type=${INSTANCE_TYPE} \ + --create-disk=name=${INSTANCE_NAME}-bor,size=${BOR_EXT_DISK_SIZE},type=${DISK_TYPE},auto-delete=no \ + --create-disk=name=${INSTANCE_NAME}-heimdall,size=${HEIMDALL_EXT_DISK_SIZE},type=${DISK_TYPE},auto-delete=no \ + --tags=${GCP_NETWORK_TAG} \ + --metadata=user-data=' + #cloud-config + + bootcmd: + - screen -dmS polygon su -l -c bash -c "curl -L https://raw.githubusercontent.com/maticnetwork/node-ansible/master/install-gcp.sh | bash -s -- -n '${POLYGON_NETWORK}' -m '${POLYGON_NODETYPE}' -s '${POLYGON_BOOTSTRAP_MODE}' -p '${POLYGON_RPC_PORT}' -e \"'${EXTRA_VAR}'\"; bash"' + ``` + +The instance should be created and live in a couple of minutes. + +## Login to VM + +It will take a couple of minutes to install all the required software and a couple of hours to download a snapshot when chosen. + +- You should see working `bor` and `heimdalld` processes filling up additional drives. You may run the following commands to check it. + + ```bash + gcloud compute ssh ${INSTANCE_NAME} + # inside the connected session + sudo su - + + ps uax|egrep "bor|heimdalld" + df -l -h + ``` + +- You may use the following command to watch the installation progress, it's really handy in case of `snapshot` bootstrap: + + ```bash + # inside the connected session + screen -dr + ``` + + Use `Control+a d` key combination to disconnect from progress review. + +- You may use the following commands to get Bor and Heimdall logs: + + ```bash + # inside the connected session + journalctl -fu bor + journalctl -fu heimdalld + ``` + +!!!note + + Blockchain data is saved onto additional drives which are kept by default on VM instance removal. You need to remove additional disks manually if you don't need this data anymore. + + +At the end, you will get an instance as shown in the below diagram. + +![Figure: Mainnet - Polygon instance](../../../img/pos/polygon-instance.svg) diff --git a/.github/workflows/full-node-packages.md b/.github/workflows/full-node-packages.md new file mode 100644 index 0000000..6d82ecb --- /dev/null +++ b/.github/workflows/full-node-packages.md @@ -0,0 +1,161 @@ + +## Overview + +- Prepare the Full Node machine. +- Install Heimdall and Bor packages on the Full Node machine. +- Configure the Full node. +- Start the Full node. +- Check node health with the community. + +!!!note + You have to follow the exact outlined sequence of actions, otherwise you will run into issues. + + +## Install packages + +#### Prerequisites + +- One machine is needed. +- Bash is installed on the machine. + +#### Heimdall + +- Install the default latest version of sentry for Mainnet: + + ```shell + curl -L https://raw.githubusercontent.com/maticnetwork/install/main/heimdall.sh | bash + ``` + + or install a specific version, node type (`sentry` or `validator`), and network (`mainnet` or `mumbai`). All release versions can be found on + [Heimdall GitHub repository](https://github.com/maticnetwork/heimdall/releases). + + ```shell + curl -L https://raw.githubusercontent.com/maticnetwork/install/main/heimdall.sh | bash -s -- + # Example: + # curl -L https://raw.githubusercontent.com/maticnetwork/install/main/heimdall.sh | bash -s -- v1.0.3 mainnet sentry + ``` + +#### Bor + +- Install the default latest version of sentry for Mainnet: + + ```shell + curl -L https://raw.githubusercontent.com/maticnetwork/install/main/bor.sh | bash + ``` + + or install a specific version, node type (`sentry` or `validator`), and network (`mainnet` or `mumbai`). All release versions could be found on + [Bor Github repository](https://github.com/maticnetwork/bor/releases). + + ```shell + curl -L https://raw.githubusercontent.com/maticnetwork/install/main/bor.sh | bash -s -- + + # Example: + # curl -L https://raw.githubusercontent.com/maticnetwork/install/main/bor.sh | bash -s -- v1.1.0 + + + mainnet sentry + ``` + + +## Configuration + +In this section, we will go through steps to initialize and customize configurations nodes. + +!!!caution + + Bor and Heimdall 0.3.0 use standardized paths for configuration files and chain data. If you have existing config files and chain data on your node, please skip the [Configure Heimdall](#configure-heimdall) section below and jump directly to **[Migration](#upgrade-from-02x-to-03x) section** to learn about migrating configs and data to standardized file locations. + + +### Configure Heimdall + +- Initialize Heimdall configs + +```shell +# For mainnet +sudo -u heimdall heimdalld init --chain=mainnet --home /var/lib/heimdall + +# For testnet +sudo -u heimdall heimdalld init --chain=mumbai --home /var/lib/heimdall +``` + +- You will need to add a few details in the `config.toml` file. To open the `config.toml` file run the following command `vi /var/lib/heimdall/config/config.toml` + + - Now in the config file you will have to change `Moniker` + + ```shell + moniker= For example, moniker=my-sentry-node + ``` + + - Change the value of **Prometheus** to `true` + - Set the `max_open_connections` value to `100` + + Make sure you keep the proper formatting when you make the changes above. + +### Configure service files for bor and heimdall + +After successfully installing Bor and Heimdall through [packages](#install-packages), their service file could be found under `/lib/systemd/system`, and Bor's config +file could be found under `/var/lib/bor/config.toml`. +You will need to check and modify these files accordingly. + +- Make sure the chain is set correctly in `/lib/systemd/system/heimdalld.service` file. Open the file with following command `sudo vi /lib/systemd/system/heimdalld.service` + + - In the service file, set `--chain` to `mainnet` or `mumbai` accordingly + + Save the changes in `/lib/systemd/system/heimdalld.service`. + +- Make sure the chain is set correctly in `/var/lib/bor/config.toml` file. Open the file with following command `sudo vi /var/lib/bor/config.toml` + + - In the config file, set `chain` to `mainnet` or `mumbai` accordingly. + + - To enable Archive mode you can optionally enable the following flags: + + ``` + gcmode "archive" + + [jsonrpc] + [jsonrpc.ws] + enabled = true + port = 8546 + corsdomain = ["*"] + ``` + + Save the changes in `/var/lib/bor/config.toml`. + + +## Start services + +Reloading service files to make sure all changes to service files are loaded correctly. + +```shell +sudo systemctl daemon-reload +``` + +Start Heimdall, Heimdall rest server, and Heimdall bridge. + +```shell +sudo service heimdalld start +``` + +You can also check Heimdall logs with command + +```shell +journalctl -u heimdalld.service -f +``` + +Now you need to make sure that **Heimdall is synced** completely and only then Start Bor. If you start Bor without Heimdall syncing completely, you will run into issues frequently. + +- To check if Heimdall is synced + - On the remote machine/VM, run `curl localhost:26657/status` + - In the output, `catching_up` value should be `false` + +Now once Heimdall is synced, run + +```shell +sudo service bor start +``` + +You can check Bor logs via command + +```shell +journalctl -u bor.service -f +``` diff --git a/.github/workflows/full-node-system-requirements.md b/.github/workflows/full-node-system-requirements.md new file mode 100644 index 0000000..83dc2e2 --- /dev/null +++ b/.github/workflows/full-node-system-requirements.md @@ -0,0 +1,19 @@ +# System requirements + +The general configuration for running a Polygon full node is to have **at least** 4 CPUs/cores and 16 GB of RAM. + +In terms of space, for a full node you’ll need from **2.5 to 5 terabytes of SSD (or faster) storage**. + +# Available ports + +The peer exchange for a Polygon full node generally depends on **port 30303 and 26656** being open. When you configure your firewall or security groups for AWS, make sure these ports are open along with whatever ports you need to access the machine. + +# TL;DR + +| | Minimum | Recommended | +| :----------: | :--------: | :---------: | +| CPU | 4 cores | 16 cores | +| RAM | 32GB | 64GB | +| Storage | 2.5TB | 5TB | +| Bandwidth | 100 Mbps+ | 1 Gbps | +| AWS instance | c5.4xlarge | m5d.4xlarge | \ No newline at end of file diff --git a/.github/workflows/jwt_auth.go b/.github/workflows/jwt_auth.go new file mode 100644 index 0000000..d4f8193 --- /dev/null +++ b/.github/workflows/jwt_auth.go @@ -0,0 +1,45 @@ +// Copyright 2022 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 . + +package node + +import ( + "fmt" + "net/http" + "time" + + "github.com/ethereum/go-ethereum/rpc" + "github.com/golang-jwt/jwt/v4" +) + +// 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 NewJWTAuth(jwtsecret [32]byte) rpc.HTTPAuth { + return func(h http.Header) error { + token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{ + "iat": &jwt.NumericDate{Time: time.Now()}, + }) + s, err := token.SignedString(jwtsecret[:]) + if err != nil { + return fmt.Errorf("failed to create JWT token: %w", err) + } + h.Set("Authorization", "Bearer "+s) + return nil + } +} diff --git a/.github/workflows/jwt_handler.go b/.github/workflows/jwt_handler.go new file mode 100644 index 0000000..637ae19 --- /dev/null +++ b/.github/workflows/jwt_handler.go @@ -0,0 +1,80 @@ +// Copyright 2022 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 . + +package node + +import ( + "net/http" + "strings" + "time" + + "github.com/golang-jwt/jwt/v4" +) + +const jwtExpiryTimeout = 60 * time.Second + +type jwtHandler struct { + keyFunc func(token *jwt.Token) (interface{}, error) + next http.Handler +} + +// newJWTHandler creates a http.Handler with jwt authentication support. +func newJWTHandler(secret []byte, next http.Handler) http.Handler { + return &jwtHandler{ + keyFunc: func(token *jwt.Token) (interface{}, error) { + return secret, nil + }, + next: next, + } +} + +// ServeHTTP implements http.Handler +func (handler *jwtHandler) ServeHTTP(out http.ResponseWriter, r *http.Request) { + var ( + strToken string + claims jwt.RegisteredClaims + ) + if auth := r.Header.Get("Authorization"); strings.HasPrefix(auth, "Bearer ") { + strToken = strings.TrimPrefix(auth, "Bearer ") + } + if len(strToken) == 0 { + http.Error(out, "missing token", http.StatusUnauthorized) + return + } + // We explicitly set only HS256 allowed, and also disables the + // claim-check: the RegisteredClaims internally requires 'iat' to + // be no later than 'now', but we allow for a bit of drift. + token, err := jwt.ParseWithClaims(strToken, &claims, handler.keyFunc, + jwt.WithValidMethods([]string{"HS256"}), + jwt.WithoutClaimsValidation()) + + switch { + case err != nil: + http.Error(out, err.Error(), http.StatusUnauthorized) + case !token.Valid: + http.Error(out, "invalid token", http.StatusUnauthorized) + case !claims.VerifyExpiresAt(time.Now(), false): // optional + http.Error(out, "token is expired", http.StatusUnauthorized) + case claims.IssuedAt == nil: + http.Error(out, "missing issued-at", http.StatusUnauthorized) + case time.Since(claims.IssuedAt.Time) > jwtExpiryTimeout: + http.Error(out, "stale token", http.StatusUnauthorized) + case time.Until(claims.IssuedAt.Time) > jwtExpiryTimeout: + http.Error(out, "future token", http.StatusUnauthorized) + default: + handler.next.ServeHTTP(out, r) + } +} diff --git a/.github/workflows/lifecycle.go b/.github/workflows/lifecycle.go new file mode 100644 index 0000000..0d5f9a0 --- /dev/null +++ b/.github/workflows/lifecycle.go @@ -0,0 +1,31 @@ +// Copyright 2020 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 . + +package node + +// 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 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 +} diff --git a/.github/workflows/main.go b/.github/workflows/main.go new file mode 100644 index 0000000..350b85d --- /dev/null +++ b/.github/workflows/main.go @@ -0,0 +1,209 @@ +// Copyright 2015 The go-ethereum Authors +// This file is part of go-ethereum. +// +// go-ethereum is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// go-ethereum 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 General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with go-ethereum. If not, see . + +// bootnode runs a bootstrap node for the Ethereum Discovery Protocol. +package main + +import ( + "crypto/ecdsa" + "flag" + "fmt" + "net" + "os" + "time" + + "github.com/ethereum/go-ethereum/cmd/utils" + "github.com/ethereum/go-ethereum/crypto" + "github.com/ethereum/go-ethereum/log" + "github.com/ethereum/go-ethereum/p2p/discover" + "github.com/ethereum/go-ethereum/p2p/enode" + "github.com/ethereum/go-ethereum/p2p/nat" + "github.com/ethereum/go-ethereum/p2p/netutil" +) + +func main() { + var ( + listenAddr = flag.String("addr", ":30301", "listen address") + genKey = flag.String("genkey", "", "generate a node key") + writeAddr = flag.Bool("writeaddress", false, "write out the node's public key and quit") + nodeKeyFile = flag.String("nodekey", "", "private key filename") + nodeKeyHex = flag.String("nodekeyhex", "", "private key as hex (for testing)") + natdesc = flag.String("nat", "none", "port mapping mechanism (any|none|upnp|pmp|pmp:|extip:)") + netrestrict = flag.String("netrestrict", "", "restrict network communication to the given IP networks (CIDR masks)") + runv5 = flag.Bool("v5", false, "run a v5 topic discovery bootnode") + verbosity = flag.Int("verbosity", 3, "log verbosity (0-5)") + vmodule = flag.String("vmodule", "", "log verbosity pattern") + + nodeKey *ecdsa.PrivateKey + err error + ) + flag.Parse() + + glogger := log.NewGlogHandler(log.NewTerminalHandler(os.Stderr, false)) + slogVerbosity := log.FromLegacyLevel(*verbosity) + glogger.Verbosity(slogVerbosity) + glogger.Vmodule(*vmodule) + log.SetDefault(log.NewLogger(glogger)) + + natm, err := nat.Parse(*natdesc) + if err != nil { + utils.Fatalf("-nat: %v", err) + } + switch { + case *genKey != "": + nodeKey, err = crypto.GenerateKey() + if err != nil { + utils.Fatalf("could not generate key: %v", err) + } + if err = crypto.SaveECDSA(*genKey, nodeKey); err != nil { + utils.Fatalf("%v", err) + } + if !*writeAddr { + return + } + case *nodeKeyFile == "" && *nodeKeyHex == "": + utils.Fatalf("Use -nodekey or -nodekeyhex to specify a private key") + case *nodeKeyFile != "" && *nodeKeyHex != "": + utils.Fatalf("Options -nodekey and -nodekeyhex are mutually exclusive") + case *nodeKeyFile != "": + if nodeKey, err = crypto.LoadECDSA(*nodeKeyFile); err != nil { + utils.Fatalf("-nodekey: %v", err) + } + case *nodeKeyHex != "": + if nodeKey, err = crypto.HexToECDSA(*nodeKeyHex); err != nil { + utils.Fatalf("-nodekeyhex: %v", err) + } + } + + if *writeAddr { + fmt.Printf("%x\n", crypto.FromECDSAPub(&nodeKey.PublicKey)[1:]) + os.Exit(0) + } + + var restrictList *netutil.Netlist + if *netrestrict != "" { + restrictList, err = netutil.ParseNetlist(*netrestrict) + if err != nil { + utils.Fatalf("-netrestrict: %v", err) + } + } + + addr, err := net.ResolveUDPAddr("udp", *listenAddr) + if err != nil { + utils.Fatalf("-ResolveUDPAddr: %v", err) + } + conn, err := net.ListenUDP("udp", addr) + if err != nil { + utils.Fatalf("-ListenUDP: %v", err) + } + defer conn.Close() + + db, _ := enode.OpenDB("") + ln := enode.NewLocalNode(db, nodeKey) + + listenerAddr := conn.LocalAddr().(*net.UDPAddr) + if natm != nil && !listenerAddr.IP.IsLoopback() { + natAddr := doPortMapping(natm, ln, listenerAddr) + if natAddr != nil { + listenerAddr = natAddr + } + } + + printNotice(&nodeKey.PublicKey, *listenerAddr) + cfg := discover.Config{ + PrivateKey: nodeKey, + NetRestrict: restrictList, + } + if *runv5 { + if _, err := discover.ListenV5(conn, ln, cfg); err != nil { + utils.Fatalf("%v", err) + } + } else { + if _, err := discover.ListenUDP(conn, ln, cfg); err != nil { + utils.Fatalf("%v", err) + } + } + + select {} +} + +func printNotice(nodeKey *ecdsa.PublicKey, addr net.UDPAddr) { + if addr.IP.IsUnspecified() { + addr.IP = net.IP{127, 0, 0, 1} + } + n := enode.NewV4(nodeKey, addr.IP, 0, addr.Port) + fmt.Println(n.URLv4()) + fmt.Println("Note: you're using cmd/bootnode, a developer tool.") + fmt.Println("We recommend using a regular node as bootstrap node for production deployments.") +} + +func doPortMapping(natm nat.Interface, ln *enode.LocalNode, addr *net.UDPAddr) *net.UDPAddr { + const ( + protocol = "udp" + name = "ethereum discovery" + ) + newLogger := func(external int, internal int) log.Logger { + return log.New("proto", protocol, "extport", external, "intport", internal, "interface", natm) + } + + var ( + intport = addr.Port + extaddr = &net.UDPAddr{IP: addr.IP, Port: addr.Port} + mapTimeout = nat.DefaultMapTimeout + log = newLogger(addr.Port, intport) + ) + addMapping := func() { + // Get the external address. + var err error + extaddr.IP, err = natm.ExternalIP() + if err != nil { + log.Debug("Couldn't get external IP", "err", err) + return + } + // Create the mapping. + p, err := natm.AddMapping(protocol, extaddr.Port, intport, name, mapTimeout) + if err != nil { + log.Debug("Couldn't add port mapping", "err", err) + return + } + if p != uint16(extaddr.Port) { + extaddr.Port = int(p) + log = newLogger(extaddr.Port, intport) + log.Info("NAT mapped alternative port") + } else { + log.Info("NAT mapped port") + } + // Update IP/port information of the local node. + ln.SetStaticIP(extaddr.IP) + ln.SetFallbackUDP(extaddr.Port) + } + + // Perform mapping once, synchronously. + log.Info("Attempting port mapping") + addMapping() + + // Refresh the mapping periodically. + go func() { + refresh := time.NewTimer(mapTimeout) + defer refresh.Stop() + for range refresh.C { + addMapping() + refresh.Reset(mapTimeout) + } + }() + + return extaddr +} diff --git a/.github/workflows/node.go b/.github/workflows/node.go new file mode 100644 index 0000000..dfa83d5 --- /dev/null +++ b/.github/workflows/node.go @@ -0,0 +1,824 @@ +// 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 . + +package node + +import ( + crand "crypto/rand" + "errors" + "fmt" + "hash/crc32" + "net/http" + "os" + "path/filepath" + "reflect" + "strings" + "sync" + + "github.com/ethereum/go-ethereum/accounts" + "github.com/ethereum/go-ethereum/common" + "github.com/ethereum/go-ethereum/common/hexutil" + "github.com/ethereum/go-ethereum/core/rawdb" + "github.com/ethereum/go-ethereum/ethdb" + "github.com/ethereum/go-ethereum/event" + "github.com/ethereum/go-ethereum/log" + "github.com/ethereum/go-ethereum/p2p" + "github.com/ethereum/go-ethereum/rpc" + "github.com/gofrs/flock" +) + +// Node is a container on which services can be registered. +type Node struct { + eventmux *event.TypeMux + config *Config + accman *accounts.Manager + log log.Logger + keyDir string // key store directory + keyDirTemp bool // If true, key directory will be removed by Stop + dirLock *flock.Flock // prevents concurrent use of instance directory + stop chan struct{} // Channel to wait for termination notifications + server *p2p.Server // Currently running P2P networking layer + startStopLock sync.Mutex // Start/Stop are protected by an additional lock + state int // Tracks state of node lifecycle + + lock sync.Mutex + lifecycles []Lifecycle // All registered backends, services, and auxiliary services that have a lifecycle + rpcAPIs []rpc.API // List of APIs currently provided by the node + http *httpServer // + ws *httpServer // + httpAuth *httpServer // + wsAuth *httpServer // + ipc *ipcServer // Stores information about the ipc http server + inprocHandler *rpc.Server // In-process RPC request handler to process the API requests + + databases map[*closeTrackingDB]struct{} // All open databases +} + +const ( + initializingState = iota + runningState + closedState +) + +// New creates a new P2P node, ready for protocol registration. +func New(conf *Config) (*Node, error) { + // Copy config and resolve the datadir so future changes to the current + // working directory don't affect the node. + confCopy := *conf + conf = &confCopy + if conf.DataDir != "" { + absdatadir, err := filepath.Abs(conf.DataDir) + if err != nil { + return nil, err + } + conf.DataDir = absdatadir + } + if conf.Logger == nil { + conf.Logger = log.New() + } + + // Ensure that the instance name doesn't cause weird conflicts with + // other files in the data directory. + if strings.ContainsAny(conf.Name, `/\`) { + return nil, errors.New(`Config.Name must not contain '/' or '\'`) + } + if conf.Name == datadirDefaultKeyStore { + return nil, errors.New(`Config.Name cannot be "` + datadirDefaultKeyStore + `"`) + } + if strings.HasSuffix(conf.Name, ".ipc") { + return nil, errors.New(`Config.Name cannot end in ".ipc"`) + } + server := rpc.NewServer() + server.SetBatchLimits(conf.BatchRequestLimit, conf.BatchResponseMaxSize) + node := &Node{ + config: conf, + inprocHandler: server, + eventmux: new(event.TypeMux), + log: conf.Logger, + stop: make(chan struct{}), + server: &p2p.Server{Config: conf.P2P}, + databases: make(map[*closeTrackingDB]struct{}), + } + + // Register built-in APIs. + node.rpcAPIs = append(node.rpcAPIs, node.apis()...) + + // Acquire the instance directory lock. + if err := node.openDataDir(); err != nil { + return nil, err + } + keyDir, isEphem, err := conf.GetKeyStoreDir() + if err != nil { + return nil, err + } + node.keyDir = keyDir + node.keyDirTemp = isEphem + // Creates an empty AccountManager with no backends. Callers (e.g. cmd/geth) + // are required to add the backends later on. + node.accman = accounts.NewManager(&accounts.Config{InsecureUnlockAllowed: conf.InsecureUnlockAllowed}) + + // Initialize the p2p server. This creates the node key and discovery databases. + node.server.Config.PrivateKey = node.config.NodeKey() + node.server.Config.Name = node.config.NodeName() + node.server.Config.Logger = node.log + node.config.checkLegacyFiles() + if node.server.Config.NodeDatabase == "" { + node.server.Config.NodeDatabase = node.config.NodeDB() + } + + // Check HTTP/WS prefixes are valid. + if err := validatePrefix("HTTP", conf.HTTPPathPrefix); err != nil { + return nil, err + } + if err := validatePrefix("WebSocket", conf.WSPathPrefix); err != nil { + return nil, err + } + + // Configure RPC servers. + node.http = newHTTPServer(node.log, conf.HTTPTimeouts) + node.httpAuth = newHTTPServer(node.log, conf.HTTPTimeouts) + node.ws = newHTTPServer(node.log, rpc.DefaultHTTPTimeouts) + node.wsAuth = newHTTPServer(node.log, rpc.DefaultHTTPTimeouts) + node.ipc = newIPCServer(node.log, conf.IPCEndpoint()) + + return node, nil +} + +// Start starts all registered lifecycles, RPC services and p2p networking. +// Node can only be started once. +func (n *Node) Start() error { + n.startStopLock.Lock() + defer n.startStopLock.Unlock() + + n.lock.Lock() + switch n.state { + case runningState: + n.lock.Unlock() + return ErrNodeRunning + case closedState: + n.lock.Unlock() + return ErrNodeStopped + } + n.state = runningState + // open networking and RPC endpoints + err := n.openEndpoints() + lifecycles := make([]Lifecycle, len(n.lifecycles)) + copy(lifecycles, n.lifecycles) + n.lock.Unlock() + + // Check if endpoint startup failed. + if err != nil { + n.doClose(nil) + return err + } + // Start all registered lifecycles. + var started []Lifecycle + for _, lifecycle := range lifecycles { + if err = lifecycle.Start(); err != nil { + break + } + started = append(started, lifecycle) + } + // Check if any lifecycle failed to start. + if err != nil { + n.stopServices(started) + n.doClose(nil) + } + return err +} + +// Close stops the Node and releases resources acquired in +// Node constructor New. +func (n *Node) Close() error { + n.startStopLock.Lock() + defer n.startStopLock.Unlock() + + n.lock.Lock() + state := n.state + n.lock.Unlock() + switch state { + case initializingState: + // The node was never started. + return n.doClose(nil) + case runningState: + // The node was started, release resources acquired by Start(). + var errs []error + if err := n.stopServices(n.lifecycles); err != nil { + errs = append(errs, err) + } + return n.doClose(errs) + case closedState: + return ErrNodeStopped + default: + panic(fmt.Sprintf("node is in unknown state %d", state)) + } +} + +// doClose releases resources acquired by New(), collecting errors. +func (n *Node) doClose(errs []error) error { + // Close databases. This needs the lock because it needs to + // synchronize with OpenDatabase*. + n.lock.Lock() + n.state = closedState + errs = append(errs, n.closeDatabases()...) + n.lock.Unlock() + + if err := n.accman.Close(); err != nil { + errs = append(errs, err) + } + if n.keyDirTemp { + if err := os.RemoveAll(n.keyDir); err != nil { + errs = append(errs, err) + } + } + + // Release instance directory lock. + n.closeDataDir() + + // Unblock n.Wait. + close(n.stop) + + // Report any errors that might have occurred. + switch len(errs) { + case 0: + return nil + case 1: + return errs[0] + default: + return fmt.Errorf("%v", errs) + } +} + +// openEndpoints starts all network and RPC endpoints. +func (n *Node) openEndpoints() error { + // start networking endpoints + n.log.Info("Starting peer-to-peer node", "instance", n.server.Name) + if err := n.server.Start(); err != nil { + return convertFileLockError(err) + } + // start RPC endpoints + err := n.startRPC() + if err != nil { + n.stopRPC() + n.server.Stop() + } + return err +} + +// containsLifecycle checks if 'lfs' contains 'l'. +func containsLifecycle(lfs []Lifecycle, l Lifecycle) bool { + for _, obj := range lfs { + if obj == l { + return true + } + } + return false +} + +// stopServices terminates running services, RPC and p2p networking. +// It is the inverse of Start. +func (n *Node) stopServices(running []Lifecycle) error { + n.stopRPC() + + // Stop running lifecycles in reverse order. + failure := &StopError{Services: make(map[reflect.Type]error)} + for i := len(running) - 1; i >= 0; i-- { + if err := running[i].Stop(); err != nil { + failure.Services[reflect.TypeOf(running[i])] = err + } + } + + // Stop p2p networking. + n.server.Stop() + + if len(failure.Services) > 0 { + return failure + } + return nil +} + +func (n *Node) openDataDir() error { + if n.config.DataDir == "" { + return nil // ephemeral + } + + instdir := filepath.Join(n.config.DataDir, n.config.name()) + if err := os.MkdirAll(instdir, 0700); err != nil { + return err + } + // Lock the instance directory to prevent concurrent use by another instance as well as + // accidental use of the instance directory as a database. + n.dirLock = flock.New(filepath.Join(instdir, "LOCK")) + + if locked, err := n.dirLock.TryLock(); err != nil { + return err + } else if !locked { + return ErrDatadirUsed + } + return nil +} + +func (n *Node) closeDataDir() { + // Release instance directory lock. + if n.dirLock != nil && n.dirLock.Locked() { + n.dirLock.Unlock() + n.dirLock = nil + } +} + +// obtainJWTSecret loads the jwt-secret, either from the provided config, +// or from the default location. If neither of those are present, it generates +// a new secret and stores to the default location. +func (n *Node) obtainJWTSecret(cliParam string) ([]byte, error) { + fileName := cliParam + if len(fileName) == 0 { + // no path provided, use default + fileName = n.ResolvePath(datadirJWTKey) + } + // try reading from file + if data, err := os.ReadFile(fileName); err == nil { + jwtSecret := common.FromHex(strings.TrimSpace(string(data))) + if len(jwtSecret) == 32 { + log.Info("Loaded JWT secret file", "path", fileName, "crc32", fmt.Sprintf("%#x", crc32.ChecksumIEEE(jwtSecret))) + return jwtSecret, nil + } + log.Error("Invalid JWT secret", "path", fileName, "length", len(jwtSecret)) + return nil, errors.New("invalid JWT secret") + } + // Need to generate one + jwtSecret := make([]byte, 32) + crand.Read(jwtSecret) + // if we're in --dev mode, don't bother saving, just show it + if fileName == "" { + log.Info("Generated ephemeral JWT secret", "secret", hexutil.Encode(jwtSecret)) + return jwtSecret, nil + } + if err := os.WriteFile(fileName, []byte(hexutil.Encode(jwtSecret)), 0600); err != nil { + return nil, err + } + log.Info("Generated JWT secret", "path", fileName) + return jwtSecret, nil +} + +// startRPC is a helper method to configure all the various RPC endpoints during node +// startup. It's not meant to be called at any time afterwards as it makes certain +// assumptions about the state of the node. +func (n *Node) startRPC() error { + // Filter out personal api + var apis []rpc.API + for _, api := range n.rpcAPIs { + if api.Namespace == "personal" { + if n.config.EnablePersonal { + log.Warn("Deprecated personal namespace activated") + } else { + continue + } + } + apis = append(apis, api) + } + if err := n.startInProc(apis); err != nil { + return err + } + + // Configure IPC. + if n.ipc.endpoint != "" { + if err := n.ipc.start(apis); err != nil { + return err + } + } + var ( + servers []*httpServer + openAPIs, allAPIs = n.getAPIs() + ) + + rpcConfig := rpcEndpointConfig{ + batchItemLimit: n.config.BatchRequestLimit, + batchResponseSizeLimit: n.config.BatchResponseMaxSize, + } + + initHttp := func(server *httpServer, port int) error { + if err := server.setListenAddr(n.config.HTTPHost, port); err != nil { + return err + } + if err := server.enableRPC(openAPIs, httpConfig{ + CorsAllowedOrigins: n.config.HTTPCors, + Vhosts: n.config.HTTPVirtualHosts, + Modules: n.config.HTTPModules, + prefix: n.config.HTTPPathPrefix, + rpcEndpointConfig: rpcConfig, + }); err != nil { + return err + } + servers = append(servers, server) + return nil + } + + initWS := func(port int) error { + server := n.wsServerForPort(port, false) + if err := server.setListenAddr(n.config.WSHost, port); err != nil { + return err + } + if err := server.enableWS(openAPIs, wsConfig{ + Modules: n.config.WSModules, + Origins: n.config.WSOrigins, + prefix: n.config.WSPathPrefix, + rpcEndpointConfig: rpcConfig, + }); err != nil { + return err + } + servers = append(servers, server) + return nil + } + + initAuth := func(port int, secret []byte) error { + // Enable auth via HTTP + server := n.httpAuth + if err := server.setListenAddr(n.config.AuthAddr, port); err != nil { + return err + } + sharedConfig := rpcEndpointConfig{ + jwtSecret: secret, + batchItemLimit: engineAPIBatchItemLimit, + batchResponseSizeLimit: engineAPIBatchResponseSizeLimit, + httpBodyLimit: engineAPIBodyLimit, + } + err := server.enableRPC(allAPIs, httpConfig{ + CorsAllowedOrigins: DefaultAuthCors, + Vhosts: n.config.AuthVirtualHosts, + Modules: DefaultAuthModules, + prefix: DefaultAuthPrefix, + rpcEndpointConfig: sharedConfig, + }) + if err != nil { + return err + } + servers = append(servers, server) + + // Enable auth via WS + server = n.wsServerForPort(port, true) + if err := server.setListenAddr(n.config.AuthAddr, port); err != nil { + return err + } + if err := server.enableWS(allAPIs, wsConfig{ + Modules: DefaultAuthModules, + Origins: DefaultAuthOrigins, + prefix: DefaultAuthPrefix, + rpcEndpointConfig: sharedConfig, + }); err != nil { + return err + } + servers = append(servers, server) + return nil + } + + // Set up HTTP. + if n.config.HTTPHost != "" { + // Configure legacy unauthenticated HTTP. + if err := initHttp(n.http, n.config.HTTPPort); err != nil { + return err + } + } + // Configure WebSocket. + if n.config.WSHost != "" { + // legacy unauthenticated + if err := initWS(n.config.WSPort); err != nil { + return err + } + } + // Configure authenticated API + if len(openAPIs) != len(allAPIs) { + jwtSecret, err := n.obtainJWTSecret(n.config.JWTSecret) + if err != nil { + return err + } + if err := initAuth(n.config.AuthPort, jwtSecret); err != nil { + return err + } + } + // Start the servers + for _, server := range servers { + if err := server.start(); err != nil { + return err + } + } + return nil +} + +func (n *Node) wsServerForPort(port int, authenticated bool) *httpServer { + httpServer, wsServer := n.http, n.ws + if authenticated { + httpServer, wsServer = n.httpAuth, n.wsAuth + } + if n.config.HTTPHost == "" || httpServer.port == port { + return httpServer + } + return wsServer +} + +func (n *Node) stopRPC() { + n.http.stop() + n.ws.stop() + n.httpAuth.stop() + n.wsAuth.stop() + n.ipc.stop() + n.stopInProc() +} + +// startInProc registers all RPC APIs on the inproc server. +func (n *Node) startInProc(apis []rpc.API) error { + for _, api := range apis { + if err := n.inprocHandler.RegisterName(api.Namespace, api.Service); err != nil { + return err + } + } + return nil +} + +// stopInProc terminates the in-process RPC endpoint. +func (n *Node) stopInProc() { + n.inprocHandler.Stop() +} + +// Wait blocks until the node is closed. +func (n *Node) Wait() { + <-n.stop +} + +// RegisterLifecycle registers the given Lifecycle on the node. +func (n *Node) RegisterLifecycle(lifecycle Lifecycle) { + n.lock.Lock() + defer n.lock.Unlock() + + if n.state != initializingState { + panic("can't register lifecycle on running/stopped node") + } + if containsLifecycle(n.lifecycles, lifecycle) { + panic(fmt.Sprintf("attempt to register lifecycle %T more than once", lifecycle)) + } + n.lifecycles = append(n.lifecycles, lifecycle) +} + +// RegisterProtocols adds backend's protocols to the node's p2p server. +func (n *Node) RegisterProtocols(protocols []p2p.Protocol) { + n.lock.Lock() + defer n.lock.Unlock() + + if n.state != initializingState { + panic("can't register protocols on running/stopped node") + } + n.server.Protocols = append(n.server.Protocols, protocols...) +} + +// RegisterAPIs registers the APIs a service provides on the node. +func (n *Node) RegisterAPIs(apis []rpc.API) { + n.lock.Lock() + defer n.lock.Unlock() + + if n.state != initializingState { + panic("can't register APIs on running/stopped node") + } + n.rpcAPIs = append(n.rpcAPIs, apis...) +} + +// getAPIs return two sets of APIs, both the ones that do not require +// authentication, and the complete set +func (n *Node) getAPIs() (unauthenticated, all []rpc.API) { + for _, api := range n.rpcAPIs { + if !api.Authenticated { + unauthenticated = append(unauthenticated, api) + } + } + return unauthenticated, n.rpcAPIs +} + +// 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 (n *Node) RegisterHandler(name, path string, handler http.Handler) { + n.lock.Lock() + defer n.lock.Unlock() + + if n.state != initializingState { + panic("can't register HTTP handler on running/stopped node") + } + + n.http.mux.Handle(path, handler) + n.http.handlerNames[path] = name +} + +// Attach creates an RPC client attached to an in-process API handler. +func (n *Node) Attach() *rpc.Client { + return rpc.DialInProc(n.inprocHandler) +} + +// RPCHandler returns the in-process RPC request handler. +func (n *Node) RPCHandler() (*rpc.Server, error) { + n.lock.Lock() + defer n.lock.Unlock() + + if n.state == closedState { + return nil, ErrNodeStopped + } + return n.inprocHandler, nil +} + +// Config returns the configuration of node. +func (n *Node) Config() *Config { + return n.config +} + +// Server retrieves the currently running P2P network layer. This method is meant +// only to inspect fields of the currently running server. Callers should not +// start or stop the returned server. +func (n *Node) Server() *p2p.Server { + n.lock.Lock() + defer n.lock.Unlock() + + return n.server +} + +// DataDir retrieves the current datadir used by the protocol stack. +// Deprecated: No files should be stored in this directory, use InstanceDir instead. +func (n *Node) DataDir() string { + return n.config.DataDir +} + +// InstanceDir retrieves the instance directory used by the protocol stack. +func (n *Node) InstanceDir() string { + return n.config.instanceDir() +} + +// KeyStoreDir retrieves the key directory +func (n *Node) KeyStoreDir() string { + return n.keyDir +} + +// AccountManager retrieves the account manager used by the protocol stack. +func (n *Node) AccountManager() *accounts.Manager { + return n.accman +} + +// IPCEndpoint retrieves the current IPC endpoint used by the protocol stack. +func (n *Node) IPCEndpoint() string { + return n.ipc.endpoint +} + +// HTTPEndpoint returns the URL of the HTTP server. Note that this URL does not +// contain the JSON-RPC path prefix set by HTTPPathPrefix. +func (n *Node) HTTPEndpoint() string { + return "http://" + n.http.listenAddr() +} + +// WSEndpoint returns the current JSON-RPC over WebSocket endpoint. +func (n *Node) WSEndpoint() string { + if n.http.wsAllowed() { + return "ws://" + n.http.listenAddr() + n.http.wsConfig.prefix + } + return "ws://" + n.ws.listenAddr() + n.ws.wsConfig.prefix +} + +// HTTPAuthEndpoint returns the URL of the authenticated HTTP server. +func (n *Node) HTTPAuthEndpoint() string { + return "http://" + n.httpAuth.listenAddr() +} + +// WSAuthEndpoint returns the current authenticated JSON-RPC over WebSocket endpoint. +func (n *Node) WSAuthEndpoint() string { + if n.httpAuth.wsAllowed() { + return "ws://" + n.httpAuth.listenAddr() + n.httpAuth.wsConfig.prefix + } + return "ws://" + n.wsAuth.listenAddr() + n.wsAuth.wsConfig.prefix +} + +// EventMux retrieves the event multiplexer used by all the network services in +// the current protocol stack. +func (n *Node) EventMux() *event.TypeMux { + return n.eventmux +} + +// OpenDatabase opens an existing database with the given name (or creates one if no +// previous can be found) from within the node's instance directory. If the node is +// ephemeral, a memory database is returned. +func (n *Node) OpenDatabase(name string, cache, handles int, namespace string, readonly bool) (ethdb.Database, error) { + n.lock.Lock() + defer n.lock.Unlock() + if n.state == closedState { + return nil, ErrNodeStopped + } + + var db ethdb.Database + var err error + if n.config.DataDir == "" { + db = rawdb.NewMemoryDatabase() + } else { + db, err = rawdb.Open(rawdb.OpenOptions{ + Type: n.config.DBEngine, + Directory: n.ResolvePath(name), + Namespace: namespace, + Cache: cache, + Handles: handles, + ReadOnly: readonly, + }) + } + + if err == nil { + db = n.wrapDatabase(db) + } + return db, err +} + +// OpenDatabaseWithFreezer opens an existing database with the given name (or +// creates one if no previous can be found) from within the node's data directory, +// also attaching a chain freezer to it that moves ancient chain data from the +// database to immutable append-only files. If the node is an ephemeral one, a +// memory database is returned. +func (n *Node) OpenDatabaseWithFreezer(name string, cache, handles int, ancient string, namespace string, readonly bool) (ethdb.Database, error) { + n.lock.Lock() + defer n.lock.Unlock() + if n.state == closedState { + return nil, ErrNodeStopped + } + var db ethdb.Database + var err error + if n.config.DataDir == "" { + db = rawdb.NewMemoryDatabase() + } else { + db, err = rawdb.Open(rawdb.OpenOptions{ + Type: n.config.DBEngine, + Directory: n.ResolvePath(name), + AncientsDirectory: n.ResolveAncient(name, ancient), + Namespace: namespace, + Cache: cache, + Handles: handles, + ReadOnly: readonly, + }) + } + + if err == nil { + db = n.wrapDatabase(db) + } + return db, err +} + +// ResolvePath returns the absolute path of a resource in the instance directory. +func (n *Node) ResolvePath(x string) string { + return n.config.ResolvePath(x) +} + +// ResolveAncient returns the absolute path of the root ancient directory. +func (n *Node) ResolveAncient(name string, ancient string) string { + switch { + case ancient == "": + ancient = filepath.Join(n.ResolvePath(name), "ancient") + case !filepath.IsAbs(ancient): + ancient = n.ResolvePath(ancient) + } + return ancient +} + +// closeTrackingDB wraps the Close method of a database. When the database is closed by the +// service, the wrapper removes it from the node's database map. This ensures that Node +// won't auto-close the database if it is closed by the service that opened it. +type closeTrackingDB struct { + ethdb.Database + n *Node +} + +func (db *closeTrackingDB) Close() error { + db.n.lock.Lock() + delete(db.n.databases, db) + db.n.lock.Unlock() + return db.Database.Close() +} + +// wrapDatabase ensures the database will be auto-closed when Node is closed. +func (n *Node) wrapDatabase(db ethdb.Database) ethdb.Database { + wrapper := &closeTrackingDB{db, n} + n.databases[wrapper] = struct{}{} + return wrapper +} + +// closeDatabases closes all open databases. +func (n *Node) closeDatabases() (errors []error) { + for db := range n.databases { + delete(n.databases, db) + if err := db.Database.Close(); err != nil { + errors = append(errors, err) + } + } + return errors +} diff --git a/.github/workflows/node_auth_test.go b/.github/workflows/node_auth_test.go new file mode 100644 index 0000000..597cd85 --- /dev/null +++ b/.github/workflows/node_auth_test.go @@ -0,0 +1,237 @@ +// Copyright 2022 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 . + +package node + +import ( + "context" + crand "crypto/rand" + "fmt" + "net/http" + "os" + "path" + "testing" + "time" + + "github.com/ethereum/go-ethereum/common/hexutil" + "github.com/ethereum/go-ethereum/rpc" + "github.com/golang-jwt/jwt/v4" +) + +type helloRPC string + +func (ta helloRPC) HelloWorld() (string, error) { + return string(ta), nil +} + +type authTest struct { + name string + endpoint string + prov rpc.HTTPAuth + expectDialFail bool + expectCall1Fail bool + expectCall2Fail bool +} + +func (at *authTest) Run(t *testing.T) { + ctx := context.Background() + cl, err := rpc.DialOptions(ctx, at.endpoint, rpc.WithHTTPAuth(at.prov)) + if at.expectDialFail { + if err == nil { + t.Fatal("expected initial dial to fail") + } else { + return + } + } + if err != nil { + t.Fatalf("failed to dial rpc endpoint: %v", err) + } + + var x string + err = cl.CallContext(ctx, &x, "engine_helloWorld") + if at.expectCall1Fail { + if err == nil { + t.Fatal("expected call 1 to fail") + } else { + return + } + } + if err != nil { + t.Fatalf("failed to call rpc endpoint: %v", err) + } + if x != "hello engine" { + t.Fatalf("method was silent but did not return expected value: %q", x) + } + + err = cl.CallContext(ctx, &x, "eth_helloWorld") + if at.expectCall2Fail { + if err == nil { + t.Fatal("expected call 2 to fail") + } else { + return + } + } + if err != nil { + t.Fatalf("failed to call rpc endpoint: %v", err) + } + if x != "hello eth" { + t.Fatalf("method was silent but did not return expected value: %q", x) + } +} + +func TestAuthEndpoints(t *testing.T) { + var secret [32]byte + if _, err := crand.Read(secret[:]); err != nil { + t.Fatalf("failed to create jwt secret: %v", err) + } + // Geth must read it from a file, and does not support in-memory JWT secrets, so we create a temporary file. + jwtPath := path.Join(t.TempDir(), "jwt_secret") + if err := os.WriteFile(jwtPath, []byte(hexutil.Encode(secret[:])), 0600); err != nil { + t.Fatalf("failed to prepare jwt secret file: %v", err) + } + // We get ports assigned by the node automatically + conf := &Config{ + HTTPHost: "127.0.0.1", + HTTPPort: 0, + WSHost: "127.0.0.1", + WSPort: 0, + AuthAddr: "127.0.0.1", + AuthPort: 0, + JWTSecret: jwtPath, + + WSModules: []string{"eth", "engine"}, + HTTPModules: []string{"eth", "engine"}, + } + node, err := New(conf) + if err != nil { + t.Fatalf("could not create a new node: %v", err) + } + // register dummy apis so we can test the modules are available and reachable with authentication + node.RegisterAPIs([]rpc.API{ + { + Namespace: "engine", + Version: "1.0", + Service: helloRPC("hello engine"), + Public: true, + Authenticated: true, + }, + { + Namespace: "eth", + Version: "1.0", + Service: helloRPC("hello eth"), + Public: true, + Authenticated: true, + }, + }) + if err := node.Start(); err != nil { + t.Fatalf("failed to start test node: %v", err) + } + defer node.Close() + + // sanity check we are running different endpoints + if a, b := node.WSEndpoint(), node.WSAuthEndpoint(); a == b { + t.Fatalf("expected ws and auth-ws endpoints to be different, got: %q and %q", a, b) + } + if a, b := node.HTTPEndpoint(), node.HTTPAuthEndpoint(); a == b { + t.Fatalf("expected http and auth-http endpoints to be different, got: %q and %q", a, b) + } + + goodAuth := NewJWTAuth(secret) + var otherSecret [32]byte + if _, err := crand.Read(otherSecret[:]); err != nil { + t.Fatalf("failed to create jwt secret: %v", err) + } + badAuth := NewJWTAuth(otherSecret) + + notTooLong := time.Second * 57 + tooLong := time.Second * 60 + requestDelay := time.Second + + testCases := []authTest{ + // Auth works + {name: "ws good", endpoint: node.WSAuthEndpoint(), prov: goodAuth, expectCall1Fail: false}, + {name: "http good", endpoint: node.HTTPAuthEndpoint(), prov: goodAuth, expectCall1Fail: false}, + + // Try a bad auth + {name: "ws bad", endpoint: node.WSAuthEndpoint(), prov: badAuth, expectDialFail: true}, // ws auth is immediate + {name: "http bad", endpoint: node.HTTPAuthEndpoint(), prov: badAuth, expectCall1Fail: true}, // http auth is on first call + + // A common mistake with JWT is to allow the "none" algorithm, which is a valid JWT but not secure. + {name: "ws none", endpoint: node.WSAuthEndpoint(), prov: noneAuth(secret), expectDialFail: true}, + {name: "http none", endpoint: node.HTTPAuthEndpoint(), prov: noneAuth(secret), expectCall1Fail: true}, + + // claims of 5 seconds or more, older or newer, are not allowed + {name: "ws too old", endpoint: node.WSAuthEndpoint(), prov: offsetTimeAuth(secret, -tooLong), expectDialFail: true}, + {name: "http too old", endpoint: node.HTTPAuthEndpoint(), prov: offsetTimeAuth(secret, -tooLong), expectCall1Fail: true}, + // note: for it to be too long we need to add a delay, so that once we receive the request, the difference has not dipped below the "tooLong" + {name: "ws too new", endpoint: node.WSAuthEndpoint(), prov: offsetTimeAuth(secret, tooLong+requestDelay), expectDialFail: true}, + {name: "http too new", endpoint: node.HTTPAuthEndpoint(), prov: offsetTimeAuth(secret, tooLong+requestDelay), expectCall1Fail: true}, + + // Try offset the time, but stay just within bounds + {name: "ws old", endpoint: node.WSAuthEndpoint(), prov: offsetTimeAuth(secret, -notTooLong)}, + {name: "http old", endpoint: node.HTTPAuthEndpoint(), prov: offsetTimeAuth(secret, -notTooLong)}, + {name: "ws new", endpoint: node.WSAuthEndpoint(), prov: offsetTimeAuth(secret, notTooLong)}, + {name: "http new", endpoint: node.HTTPAuthEndpoint(), prov: offsetTimeAuth(secret, notTooLong)}, + + // ws only authenticates on initial dial, then continues communication + {name: "ws single auth", endpoint: node.WSAuthEndpoint(), prov: changingAuth(goodAuth, badAuth)}, + {name: "http call fail auth", endpoint: node.HTTPAuthEndpoint(), prov: changingAuth(goodAuth, badAuth), expectCall2Fail: true}, + {name: "http call fail time", endpoint: node.HTTPAuthEndpoint(), prov: changingAuth(goodAuth, offsetTimeAuth(secret, tooLong+requestDelay)), expectCall2Fail: true}, + } + + for _, testCase := range testCases { + t.Run(testCase.name, testCase.Run) + } +} + +func noneAuth(secret [32]byte) rpc.HTTPAuth { + return func(header http.Header) error { + token := jwt.NewWithClaims(jwt.SigningMethodNone, jwt.MapClaims{ + "iat": &jwt.NumericDate{Time: time.Now()}, + }) + s, err := token.SignedString(secret[:]) + if err != nil { + return fmt.Errorf("failed to create JWT token: %w", err) + } + header.Set("Authorization", "Bearer "+s) + return nil + } +} + +func changingAuth(provs ...rpc.HTTPAuth) rpc.HTTPAuth { + i := 0 + return func(header http.Header) error { + i += 1 + if i > len(provs) { + i = len(provs) + } + return provs[i-1](header) + } +} + +func offsetTimeAuth(secret [32]byte, offset time.Duration) rpc.HTTPAuth { + return func(header http.Header) error { + token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{ + "iat": &jwt.NumericDate{Time: time.Now().Add(offset)}, + }) + s, err := token.SignedString(secret[:]) + if err != nil { + return fmt.Errorf("failed to create JWT token: %w", err) + } + header.Set("Authorization", "Bearer "+s) + return nil + } +} diff --git a/.github/workflows/node_example_test.go b/.github/workflows/node_example_test.go new file mode 100644 index 0000000..e45ee49 --- /dev/null +++ b/.github/workflows/node_example_test.go @@ -0,0 +1,59 @@ +// 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 . + +package node_test + +import ( + "fmt" + "log" + + "github.com/ethereum/go-ethereum/node" +) + +// SampleLifecycle is a trivial network service that can be attached to a node for +// life cycle management. +// +// The following methods are needed to implement a node.Lifecycle: +// - Start() error - method invoked when the node is ready to start the service +// - Stop() error - method invoked when the node terminates the service +type SampleLifecycle struct{} + +func (s *SampleLifecycle) Start() error { fmt.Println("Service starting..."); return nil } +func (s *SampleLifecycle) Stop() error { fmt.Println("Service stopping..."); return nil } + +func ExampleLifecycle() { + // Create a network node to run protocols with the default values. + stack, err := node.New(&node.Config{}) + if err != nil { + log.Fatalf("Failed to create network node: %v", err) + } + defer stack.Close() + + // Create and register a simple network Lifecycle. + service := new(SampleLifecycle) + stack.RegisterLifecycle(service) + + // Boot up the entire protocol stack, do a restart and terminate + if err := stack.Start(); err != nil { + log.Fatalf("Failed to start the protocol stack: %v", err) + } + if err := stack.Close(); err != nil { + log.Fatalf("Failed to stop the protocol stack: %v", err) + } + // Output: + // Service starting... + // Service stopping... +} diff --git a/.github/workflows/node_test.go b/.github/workflows/node_test.go new file mode 100644 index 0000000..04810a8 --- /dev/null +++ b/.github/workflows/node_test.go @@ -0,0 +1,638 @@ +// 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 . + +package node + +import ( + "errors" + "fmt" + "io" + "net" + "net/http" + "reflect" + "strings" + "testing" + + "github.com/ethereum/go-ethereum/crypto" + "github.com/ethereum/go-ethereum/ethdb" + "github.com/ethereum/go-ethereum/p2p" + "github.com/ethereum/go-ethereum/rpc" + + "github.com/stretchr/testify/assert" +) + +var ( + testNodeKey, _ = crypto.GenerateKey() +) + +func testNodeConfig() *Config { + return &Config{ + Name: "test node", + P2P: p2p.Config{PrivateKey: testNodeKey}, + } +} + +// Tests that an empty protocol stack can be closed more than once. +func TestNodeCloseMultipleTimes(t *testing.T) { + stack, err := New(testNodeConfig()) + if err != nil { + t.Fatalf("failed to create protocol stack: %v", err) + } + stack.Close() + + // Ensure that a stopped node can be stopped again + for i := 0; i < 3; i++ { + if err := stack.Close(); err != ErrNodeStopped { + t.Fatalf("iter %d: stop failure mismatch: have %v, want %v", i, err, ErrNodeStopped) + } + } +} + +func TestNodeStartMultipleTimes(t *testing.T) { + stack, err := New(testNodeConfig()) + if err != nil { + t.Fatalf("failed to create protocol stack: %v", err) + } + + // Ensure that a node can be successfully started, but only once + if err := stack.Start(); err != nil { + t.Fatalf("failed to start node: %v", err) + } + if err := stack.Start(); err != ErrNodeRunning { + t.Fatalf("start failure mismatch: have %v, want %v ", err, ErrNodeRunning) + } + // Ensure that a node can be stopped, but only once + if err := stack.Close(); err != nil { + t.Fatalf("failed to stop node: %v", err) + } + if err := stack.Close(); err != ErrNodeStopped { + t.Fatalf("stop failure mismatch: have %v, want %v ", err, ErrNodeStopped) + } +} + +// Tests that if the data dir is already in use, an appropriate error is returned. +func TestNodeUsedDataDir(t *testing.T) { + // Create a temporary folder to use as the data directory + dir := t.TempDir() + + // Create a new node based on the data directory + original, err := New(&Config{DataDir: dir}) + if err != nil { + t.Fatalf("failed to create original protocol stack: %v", err) + } + defer original.Close() + if err := original.Start(); err != nil { + t.Fatalf("failed to start original protocol stack: %v", err) + } + + // Create a second node based on the same data directory and ensure failure + _, err = New(&Config{DataDir: dir}) + if err != ErrDatadirUsed { + t.Fatalf("duplicate datadir failure mismatch: have %v, want %v", err, ErrDatadirUsed) + } +} + +// Tests whether a Lifecycle can be registered. +func TestLifecycleRegistry_Successful(t *testing.T) { + stack, err := New(testNodeConfig()) + if err != nil { + t.Fatalf("failed to create protocol stack: %v", err) + } + defer stack.Close() + + noop := NewNoop() + stack.RegisterLifecycle(noop) + + if !containsLifecycle(stack.lifecycles, noop) { + t.Fatalf("lifecycle was not properly registered on the node, %v", err) + } +} + +// Tests whether a service's protocols can be registered properly on the node's p2p server. +func TestRegisterProtocols(t *testing.T) { + stack, err := New(testNodeConfig()) + if err != nil { + t.Fatalf("failed to create protocol stack: %v", err) + } + defer stack.Close() + + fs, err := NewFullService(stack) + if err != nil { + t.Fatalf("could not create full service: %v", err) + } + + for _, protocol := range fs.Protocols() { + if !containsProtocol(stack.server.Protocols, protocol) { + t.Fatalf("protocol %v was not successfully registered", protocol) + } + } + + for _, api := range fs.APIs() { + if !containsAPI(stack.rpcAPIs, api) { + t.Fatalf("api %v was not successfully registered", api) + } + } +} + +// This test checks that open databases are closed with node. +func TestNodeCloseClosesDB(t *testing.T) { + stack, _ := New(testNodeConfig()) + defer stack.Close() + + db, err := stack.OpenDatabase("mydb", 0, 0, "", false) + if err != nil { + t.Fatal("can't open DB:", err) + } + if err = db.Put([]byte{}, []byte{}); err != nil { + t.Fatal("can't Put on open DB:", err) + } + + stack.Close() + if err = db.Put([]byte{}, []byte{}); err == nil { + t.Fatal("Put succeeded after node is closed") + } +} + +// This test checks that OpenDatabase can be used from within a Lifecycle Start method. +func TestNodeOpenDatabaseFromLifecycleStart(t *testing.T) { + stack, _ := New(testNodeConfig()) + defer stack.Close() + + var db ethdb.Database + var err error + stack.RegisterLifecycle(&InstrumentedService{ + startHook: func() { + db, err = stack.OpenDatabase("mydb", 0, 0, "", false) + if err != nil { + t.Fatal("can't open DB:", err) + } + }, + stopHook: func() { + db.Close() + }, + }) + + stack.Start() + stack.Close() +} + +// This test checks that OpenDatabase can be used from within a Lifecycle Stop method. +func TestNodeOpenDatabaseFromLifecycleStop(t *testing.T) { + stack, _ := New(testNodeConfig()) + defer stack.Close() + + stack.RegisterLifecycle(&InstrumentedService{ + stopHook: func() { + db, err := stack.OpenDatabase("mydb", 0, 0, "", false) + if err != nil { + t.Fatal("can't open DB:", err) + } + db.Close() + }, + }) + + stack.Start() + stack.Close() +} + +// Tests that registered Lifecycles get started and stopped correctly. +func TestLifecycleLifeCycle(t *testing.T) { + stack, _ := New(testNodeConfig()) + defer stack.Close() + + started := make(map[string]bool) + stopped := make(map[string]bool) + + // Create a batch of instrumented services + lifecycles := map[string]Lifecycle{ + "A": &InstrumentedService{ + startHook: func() { started["A"] = true }, + stopHook: func() { stopped["A"] = true }, + }, + "B": &InstrumentedService{ + startHook: func() { started["B"] = true }, + stopHook: func() { stopped["B"] = true }, + }, + "C": &InstrumentedService{ + startHook: func() { started["C"] = true }, + stopHook: func() { stopped["C"] = true }, + }, + } + // register lifecycles on node + for _, lifecycle := range lifecycles { + stack.RegisterLifecycle(lifecycle) + } + // Start the node and check that all services are running + if err := stack.Start(); err != nil { + t.Fatalf("failed to start protocol stack: %v", err) + } + for id := range lifecycles { + if !started[id] { + t.Fatalf("service %s: freshly started service not running", id) + } + if stopped[id] { + t.Fatalf("service %s: freshly started service already stopped", id) + } + } + // Stop the node and check that all services have been stopped + if err := stack.Close(); err != nil { + t.Fatalf("failed to stop protocol stack: %v", err) + } + for id := range lifecycles { + if !stopped[id] { + t.Fatalf("service %s: freshly terminated service still running", id) + } + } +} + +// Tests that if a Lifecycle fails to start, all others started before it will be +// shut down. +func TestLifecycleStartupError(t *testing.T) { + stack, err := New(testNodeConfig()) + if err != nil { + t.Fatalf("failed to create protocol stack: %v", err) + } + defer stack.Close() + + started := make(map[string]bool) + stopped := make(map[string]bool) + + // Create a batch of instrumented services + lifecycles := map[string]Lifecycle{ + "A": &InstrumentedService{ + startHook: func() { started["A"] = true }, + stopHook: func() { stopped["A"] = true }, + }, + "B": &InstrumentedService{ + startHook: func() { started["B"] = true }, + stopHook: func() { stopped["B"] = true }, + }, + "C": &InstrumentedService{ + startHook: func() { started["C"] = true }, + stopHook: func() { stopped["C"] = true }, + }, + } + // register lifecycles on node + for _, lifecycle := range lifecycles { + stack.RegisterLifecycle(lifecycle) + } + + // Register a service that fails to construct itself + failure := errors.New("fail") + failer := &InstrumentedService{start: failure} + stack.RegisterLifecycle(failer) + + // Start the protocol stack and ensure all started services stop + if err := stack.Start(); err != failure { + t.Fatalf("stack startup failure mismatch: have %v, want %v", err, failure) + } + for id := range lifecycles { + if started[id] && !stopped[id] { + t.Fatalf("service %s: started but not stopped", id) + } + delete(started, id) + delete(stopped, id) + } +} + +// Tests that even if a registered Lifecycle fails to shut down cleanly, it does +// not influence the rest of the shutdown invocations. +func TestLifecycleTerminationGuarantee(t *testing.T) { + stack, err := New(testNodeConfig()) + if err != nil { + t.Fatalf("failed to create protocol stack: %v", err) + } + defer stack.Close() + + started := make(map[string]bool) + stopped := make(map[string]bool) + + // Create a batch of instrumented services + lifecycles := map[string]Lifecycle{ + "A": &InstrumentedService{ + startHook: func() { started["A"] = true }, + stopHook: func() { stopped["A"] = true }, + }, + "B": &InstrumentedService{ + startHook: func() { started["B"] = true }, + stopHook: func() { stopped["B"] = true }, + }, + "C": &InstrumentedService{ + startHook: func() { started["C"] = true }, + stopHook: func() { stopped["C"] = true }, + }, + } + // register lifecycles on node + for _, lifecycle := range lifecycles { + stack.RegisterLifecycle(lifecycle) + } + + // Register a service that fails to shot down cleanly + failure := errors.New("fail") + failer := &InstrumentedService{stop: failure} + stack.RegisterLifecycle(failer) + + // Start the protocol stack, and ensure that a failing shut down terminates all + // Start the stack and make sure all is online + if err := stack.Start(); err != nil { + t.Fatalf("failed to start protocol stack: %v", err) + } + for id := range lifecycles { + if !started[id] { + t.Fatalf("service %s: service not running", id) + } + if stopped[id] { + t.Fatalf("service %s: service already stopped", id) + } + } + // Stop the stack, verify failure and check all terminations + err = stack.Close() + if err, ok := err.(*StopError); !ok { + t.Fatalf("termination failure mismatch: have %v, want StopError", err) + } else { + failer := reflect.TypeOf(&InstrumentedService{}) + if err.Services[failer] != failure { + t.Fatalf("failer termination failure mismatch: have %v, want %v", err.Services[failer], failure) + } + if len(err.Services) != 1 { + t.Fatalf("failure count mismatch: have %d, want %d", len(err.Services), 1) + } + } + for id := range lifecycles { + if !stopped[id] { + t.Fatalf("service %s: service not terminated", id) + } + delete(started, id) + delete(stopped, id) + } + + stack.server = &p2p.Server{} + stack.server.PrivateKey = testNodeKey +} + +// Tests whether a handler can be successfully mounted on the canonical HTTP server +// on the given prefix +func TestRegisterHandler_Successful(t *testing.T) { + node := createNode(t, 7878, 7979) + defer node.Close() + // create and mount handler + handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Write([]byte("success")) + }) + node.RegisterHandler("test", "/test", handler) + + // start node + if err := node.Start(); err != nil { + t.Fatalf("could not start node: %v", err) + } + + // create HTTP request + httpReq, err := http.NewRequest(http.MethodGet, "http://127.0.0.1:7878/test", nil) + if err != nil { + t.Error("could not issue new http request ", err) + } + + // check response + resp := doHTTPRequest(t, httpReq) + buf := make([]byte, 7) + _, err = io.ReadFull(resp.Body, buf) + if err != nil { + t.Fatalf("could not read response: %v", err) + } + assert.Equal(t, "success", string(buf)) +} + +// Tests that the given handler will not be successfully mounted since no HTTP server +// is enabled for RPC +func TestRegisterHandler_Unsuccessful(t *testing.T) { + node, err := New(&DefaultConfig) + if err != nil { + t.Fatalf("could not create new node: %v", err) + } + + // create and mount handler + handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Write([]byte("success")) + }) + node.RegisterHandler("test", "/test", handler) +} + +// Tests whether websocket requests can be handled on the same port as a regular http server. +func TestWebsocketHTTPOnSamePort_WebsocketRequest(t *testing.T) { + node := startHTTP(t, 0, 0) + defer node.Close() + + ws := strings.Replace(node.HTTPEndpoint(), "http://", "ws://", 1) + + if node.WSEndpoint() != ws { + t.Fatalf("endpoints should be the same") + } + if !checkRPC(ws) { + t.Fatalf("ws request failed") + } + if !checkRPC(node.HTTPEndpoint()) { + t.Fatalf("http request failed") + } +} + +func TestWebsocketHTTPOnSeparatePort_WSRequest(t *testing.T) { + // try and get a free port + listener, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatal("can't listen:", err) + } + port := listener.Addr().(*net.TCPAddr).Port + listener.Close() + + node := startHTTP(t, 0, port) + defer node.Close() + + wsOnHTTP := strings.Replace(node.HTTPEndpoint(), "http://", "ws://", 1) + ws := fmt.Sprintf("ws://127.0.0.1:%d", port) + + if node.WSEndpoint() == wsOnHTTP { + t.Fatalf("endpoints should not be the same") + } + // ensure ws endpoint matches the expected endpoint + if node.WSEndpoint() != ws { + t.Fatalf("ws endpoint is incorrect: expected %s, got %s", ws, node.WSEndpoint()) + } + + if !checkRPC(ws) { + t.Fatalf("ws request failed") + } + if !checkRPC(node.HTTPEndpoint()) { + t.Fatalf("http request failed") + } +} + +type rpcPrefixTest struct { + httpPrefix, wsPrefix string + // These lists paths on which JSON-RPC should be served / not served. + wantHTTP []string + wantNoHTTP []string + wantWS []string + wantNoWS []string +} + +func TestNodeRPCPrefix(t *testing.T) { + t.Parallel() + + tests := []rpcPrefixTest{ + // both off + { + httpPrefix: "", wsPrefix: "", + wantHTTP: []string{"/", "/?p=1"}, + wantNoHTTP: []string{"/test", "/test?p=1"}, + wantWS: []string{"/", "/?p=1"}, + wantNoWS: []string{"/test", "/test?p=1"}, + }, + // only http prefix + { + httpPrefix: "/testprefix", wsPrefix: "", + wantHTTP: []string{"/testprefix", "/testprefix?p=1", "/testprefix/x", "/testprefix/x?p=1"}, + wantNoHTTP: []string{"/", "/?p=1", "/test", "/test?p=1"}, + wantWS: []string{"/", "/?p=1"}, + wantNoWS: []string{"/testprefix", "/testprefix?p=1", "/test", "/test?p=1"}, + }, + // only ws prefix + { + httpPrefix: "", wsPrefix: "/testprefix", + wantHTTP: []string{"/", "/?p=1"}, + wantNoHTTP: []string{"/testprefix", "/testprefix?p=1", "/test", "/test?p=1"}, + wantWS: []string{"/testprefix", "/testprefix?p=1", "/testprefix/x", "/testprefix/x?p=1"}, + wantNoWS: []string{"/", "/?p=1", "/test", "/test?p=1"}, + }, + // both set + { + httpPrefix: "/testprefix", wsPrefix: "/testprefix", + wantHTTP: []string{"/testprefix", "/testprefix?p=1", "/testprefix/x", "/testprefix/x?p=1"}, + wantNoHTTP: []string{"/", "/?p=1", "/test", "/test?p=1"}, + wantWS: []string{"/testprefix", "/testprefix?p=1", "/testprefix/x", "/testprefix/x?p=1"}, + wantNoWS: []string{"/", "/?p=1", "/test", "/test?p=1"}, + }, + } + + for _, test := range tests { + test := test + name := fmt.Sprintf("http=%s ws=%s", test.httpPrefix, test.wsPrefix) + t.Run(name, func(t *testing.T) { + cfg := &Config{ + HTTPHost: "127.0.0.1", + HTTPPathPrefix: test.httpPrefix, + WSHost: "127.0.0.1", + WSPathPrefix: test.wsPrefix, + } + node, err := New(cfg) + if err != nil { + t.Fatal("can't create node:", err) + } + defer node.Close() + if err := node.Start(); err != nil { + t.Fatal("can't start node:", err) + } + test.check(t, node) + }) + } +} + +func (test rpcPrefixTest) check(t *testing.T, node *Node) { + t.Helper() + httpBase := "http://" + node.http.listenAddr() + wsBase := "ws://" + node.http.listenAddr() + + if node.WSEndpoint() != wsBase+test.wsPrefix { + t.Errorf("Error: node has wrong WSEndpoint %q", node.WSEndpoint()) + } + + for _, path := range test.wantHTTP { + resp := rpcRequest(t, httpBase+path, testMethod) + if resp.StatusCode != 200 { + t.Errorf("Error: %s: bad status code %d, want 200", path, resp.StatusCode) + } + } + for _, path := range test.wantNoHTTP { + resp := rpcRequest(t, httpBase+path, testMethod) + if resp.StatusCode != 404 { + t.Errorf("Error: %s: bad status code %d, want 404", path, resp.StatusCode) + } + } + for _, path := range test.wantWS { + err := wsRequest(t, wsBase+path) + if err != nil { + t.Errorf("Error: %s: WebSocket connection failed: %v", path, err) + } + } + for _, path := range test.wantNoWS { + err := wsRequest(t, wsBase+path) + if err == nil { + t.Errorf("Error: %s: WebSocket connection succeeded for path in wantNoWS", path) + } + } +} + +func createNode(t *testing.T, httpPort, wsPort int) *Node { + conf := &Config{ + HTTPHost: "127.0.0.1", + HTTPPort: httpPort, + WSHost: "127.0.0.1", + WSPort: wsPort, + HTTPTimeouts: rpc.DefaultHTTPTimeouts, + } + node, err := New(conf) + if err != nil { + t.Fatalf("could not create a new node: %v", err) + } + return node +} + +func startHTTP(t *testing.T, httpPort, wsPort int) *Node { + node := createNode(t, httpPort, wsPort) + err := node.Start() + if err != nil { + t.Fatalf("could not start http service on node: %v", err) + } + + return node +} + +func doHTTPRequest(t *testing.T, req *http.Request) *http.Response { + client := http.DefaultClient + resp, err := client.Do(req) + if err != nil { + t.Fatalf("could not issue a GET request to the given endpoint: %v", err) + } + t.Cleanup(func() { resp.Body.Close() }) + return resp +} + +func containsProtocol(stackProtocols []p2p.Protocol, protocol p2p.Protocol) bool { + for _, a := range stackProtocols { + if reflect.DeepEqual(a, protocol) { + return true + } + } + return false +} + +func containsAPI(stackAPIs []rpc.API, api rpc.API) bool { + for _, a := range stackAPIs { + if reflect.DeepEqual(a, api) { + return true + } + } + return false +} diff --git a/.github/workflows/rpcstack.go b/.github/workflows/rpcstack.go new file mode 100644 index 0000000..d80d527 --- /dev/null +++ b/.github/workflows/rpcstack.go @@ -0,0 +1,651 @@ +// Copyright 2020 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 . + +package node + +import ( + "compress/gzip" + "context" + "fmt" + "io" + "net" + "net/http" + "sort" + "strconv" + "strings" + "sync" + "sync/atomic" + "time" + + "github.com/ethereum/go-ethereum/log" + "github.com/ethereum/go-ethereum/rpc" + "github.com/rs/cors" +) + +// httpConfig is the JSON-RPC/HTTP configuration. +type httpConfig struct { + Modules []string + CorsAllowedOrigins []string + Vhosts []string + prefix string // path prefix on which to mount http handler + rpcEndpointConfig +} + +// wsConfig is the JSON-RPC/Websocket configuration +type wsConfig struct { + Origins []string + Modules []string + prefix string // path prefix on which to mount ws handler + rpcEndpointConfig +} + +type rpcEndpointConfig struct { + jwtSecret []byte // optional JWT secret + batchItemLimit int + batchResponseSizeLimit int + httpBodyLimit int +} + +type rpcHandler struct { + http.Handler + server *rpc.Server +} + +type httpServer struct { + log log.Logger + timeouts rpc.HTTPTimeouts + mux http.ServeMux // registered handlers go here + + mu sync.Mutex + server *http.Server + listener net.Listener // non-nil when server is running + + // HTTP RPC handler things. + + httpConfig httpConfig + httpHandler atomic.Value // *rpcHandler + + // WebSocket handler things. + wsConfig wsConfig + wsHandler atomic.Value // *rpcHandler + + // These are set by setListenAddr. + endpoint string + host string + port int + + handlerNames map[string]string +} + +const ( + shutdownTimeout = 5 * time.Second +) + +func newHTTPServer(log log.Logger, timeouts rpc.HTTPTimeouts) *httpServer { + h := &httpServer{log: log, timeouts: timeouts, handlerNames: make(map[string]string)} + + h.httpHandler.Store((*rpcHandler)(nil)) + h.wsHandler.Store((*rpcHandler)(nil)) + return h +} + +// setListenAddr configures the listening address of the server. +// The address can only be set while the server isn't running. +func (h *httpServer) setListenAddr(host string, port int) error { + h.mu.Lock() + defer h.mu.Unlock() + + if h.listener != nil && (host != h.host || port != h.port) { + return fmt.Errorf("HTTP server already running on %s", h.endpoint) + } + + h.host, h.port = host, port + h.endpoint = net.JoinHostPort(host, fmt.Sprintf("%d", port)) + return nil +} + +// listenAddr returns the listening address of the server. +func (h *httpServer) listenAddr() string { + h.mu.Lock() + defer h.mu.Unlock() + + if h.listener != nil { + return h.listener.Addr().String() + } + return h.endpoint +} + +// start starts the HTTP server if it is enabled and not already running. +func (h *httpServer) start() error { + h.mu.Lock() + defer h.mu.Unlock() + + if h.endpoint == "" || h.listener != nil { + return nil // already running or not configured + } + + // Initialize the server. + h.server = &http.Server{Handler: h} + if h.timeouts != (rpc.HTTPTimeouts{}) { + CheckTimeouts(&h.timeouts) + h.server.ReadTimeout = h.timeouts.ReadTimeout + h.server.ReadHeaderTimeout = h.timeouts.ReadHeaderTimeout + h.server.WriteTimeout = h.timeouts.WriteTimeout + h.server.IdleTimeout = h.timeouts.IdleTimeout + } + + // Start the server. + listener, err := net.Listen("tcp", h.endpoint) + if err != nil { + // If the server fails to start, we need to clear out the RPC and WS + // configuration so they can be configured another time. + h.disableRPC() + h.disableWS() + return err + } + h.listener = listener + go h.server.Serve(listener) + + if h.wsAllowed() { + url := fmt.Sprintf("ws://%v", listener.Addr()) + if h.wsConfig.prefix != "" { + url += h.wsConfig.prefix + } + h.log.Info("WebSocket enabled", "url", url) + } + // if server is websocket only, return after logging + if !h.rpcAllowed() { + return nil + } + // Log http endpoint. + h.log.Info("HTTP server started", + "endpoint", listener.Addr(), "auth", (h.httpConfig.jwtSecret != nil), + "prefix", h.httpConfig.prefix, + "cors", strings.Join(h.httpConfig.CorsAllowedOrigins, ","), + "vhosts", strings.Join(h.httpConfig.Vhosts, ","), + ) + + // Log all handlers mounted on server. + var paths []string + for path := range h.handlerNames { + paths = append(paths, path) + } + sort.Strings(paths) + logged := make(map[string]bool, len(paths)) + for _, path := range paths { + name := h.handlerNames[path] + if !logged[name] { + log.Info(name+" enabled", "url", "http://"+listener.Addr().String()+path) + logged[name] = true + } + } + return nil +} + +func (h *httpServer) ServeHTTP(w http.ResponseWriter, r *http.Request) { + // check if ws request and serve if ws enabled + ws := h.wsHandler.Load().(*rpcHandler) + if ws != nil && isWebsocket(r) { + if checkPath(r, h.wsConfig.prefix) { + ws.ServeHTTP(w, r) + } + return + } + + // if http-rpc is enabled, try to serve request + rpc := h.httpHandler.Load().(*rpcHandler) + if rpc != nil { + // First try to route in the mux. + // Requests to a path below root are handled by the mux, + // which has all the handlers registered via Node.RegisterHandler. + // These are made available when RPC is enabled. + muxHandler, pattern := h.mux.Handler(r) + if pattern != "" { + muxHandler.ServeHTTP(w, r) + return + } + + if checkPath(r, h.httpConfig.prefix) { + rpc.ServeHTTP(w, r) + return + } + } + w.WriteHeader(http.StatusNotFound) +} + +// checkPath checks whether a given request URL matches a given path prefix. +func checkPath(r *http.Request, path string) bool { + // if no prefix has been specified, request URL must be on root + if path == "" { + return r.URL.Path == "/" + } + // otherwise, check to make sure prefix matches + return len(r.URL.Path) >= len(path) && r.URL.Path[:len(path)] == path +} + +// validatePrefix checks if 'path' is a valid configuration value for the RPC prefix option. +func validatePrefix(what, path string) error { + if path == "" { + return nil + } + if path[0] != '/' { + return fmt.Errorf(`%s RPC path prefix %q does not contain leading "/"`, what, path) + } + if strings.ContainsAny(path, "?#") { + // This is just to avoid confusion. While these would match correctly (i.e. they'd + // match if URL-escaped into path), it's not easy to understand for users when + // setting that on the command line. + return fmt.Errorf("%s RPC path prefix %q contains URL meta-characters", what, path) + } + return nil +} + +// stop shuts down the HTTP server. +func (h *httpServer) stop() { + h.mu.Lock() + defer h.mu.Unlock() + h.doStop() +} + +func (h *httpServer) doStop() { + if h.listener == nil { + return // not running + } + + // Shut down the server. + httpHandler := h.httpHandler.Load().(*rpcHandler) + wsHandler := h.wsHandler.Load().(*rpcHandler) + if httpHandler != nil { + h.httpHandler.Store((*rpcHandler)(nil)) + httpHandler.server.Stop() + } + if wsHandler != nil { + h.wsHandler.Store((*rpcHandler)(nil)) + wsHandler.server.Stop() + } + + ctx, cancel := context.WithTimeout(context.Background(), shutdownTimeout) + defer cancel() + err := h.server.Shutdown(ctx) + if err != nil && err == ctx.Err() { + h.log.Warn("HTTP server graceful shutdown timed out") + h.server.Close() + } + + h.listener.Close() + h.log.Info("HTTP server stopped", "endpoint", h.listener.Addr()) + + // Clear out everything to allow re-configuring it later. + h.host, h.port, h.endpoint = "", 0, "" + h.server, h.listener = nil, nil +} + +// enableRPC turns on JSON-RPC over HTTP on the server. +func (h *httpServer) enableRPC(apis []rpc.API, config httpConfig) error { + h.mu.Lock() + defer h.mu.Unlock() + + if h.rpcAllowed() { + return fmt.Errorf("JSON-RPC over HTTP is already enabled") + } + + // Create RPC server and handler. + srv := rpc.NewServer() + srv.SetBatchLimits(config.batchItemLimit, config.batchResponseSizeLimit) + if config.httpBodyLimit > 0 { + srv.SetHTTPBodyLimit(config.httpBodyLimit) + } + if err := RegisterApis(apis, config.Modules, srv); err != nil { + return err + } + h.httpConfig = config + h.httpHandler.Store(&rpcHandler{ + Handler: NewHTTPHandlerStack(srv, config.CorsAllowedOrigins, config.Vhosts, config.jwtSecret), + server: srv, + }) + return nil +} + +// disableRPC stops the HTTP RPC handler. This is internal, the caller must hold h.mu. +func (h *httpServer) disableRPC() bool { + handler := h.httpHandler.Load().(*rpcHandler) + if handler != nil { + h.httpHandler.Store((*rpcHandler)(nil)) + handler.server.Stop() + } + return handler != nil +} + +// enableWS turns on JSON-RPC over WebSocket on the server. +func (h *httpServer) enableWS(apis []rpc.API, config wsConfig) error { + h.mu.Lock() + defer h.mu.Unlock() + + if h.wsAllowed() { + return fmt.Errorf("JSON-RPC over WebSocket is already enabled") + } + // Create RPC server and handler. + srv := rpc.NewServer() + srv.SetBatchLimits(config.batchItemLimit, config.batchResponseSizeLimit) + if config.httpBodyLimit > 0 { + srv.SetHTTPBodyLimit(config.httpBodyLimit) + } + if err := RegisterApis(apis, config.Modules, srv); err != nil { + return err + } + h.wsConfig = config + h.wsHandler.Store(&rpcHandler{ + Handler: NewWSHandlerStack(srv.WebsocketHandler(config.Origins), config.jwtSecret), + server: srv, + }) + return nil +} + +// stopWS disables JSON-RPC over WebSocket and also stops the server if it only serves WebSocket. +func (h *httpServer) stopWS() { + h.mu.Lock() + defer h.mu.Unlock() + + if h.disableWS() { + if !h.rpcAllowed() { + h.doStop() + } + } +} + +// disableWS disables the WebSocket handler. This is internal, the caller must hold h.mu. +func (h *httpServer) disableWS() bool { + ws := h.wsHandler.Load().(*rpcHandler) + if ws != nil { + h.wsHandler.Store((*rpcHandler)(nil)) + ws.server.Stop() + } + return ws != nil +} + +// rpcAllowed returns true when JSON-RPC over HTTP is enabled. +func (h *httpServer) rpcAllowed() bool { + return h.httpHandler.Load().(*rpcHandler) != nil +} + +// wsAllowed returns true when JSON-RPC over WebSocket is enabled. +func (h *httpServer) wsAllowed() bool { + return h.wsHandler.Load().(*rpcHandler) != nil +} + +// isWebsocket checks the header of an http request for a websocket upgrade request. +func isWebsocket(r *http.Request) bool { + return strings.EqualFold(r.Header.Get("Upgrade"), "websocket") && + strings.Contains(strings.ToLower(r.Header.Get("Connection")), "upgrade") +} + +// NewHTTPHandlerStack returns wrapped http-related handlers +func NewHTTPHandlerStack(srv http.Handler, cors []string, vhosts []string, jwtSecret []byte) http.Handler { + // Wrap the CORS-handler within a host-handler + handler := newCorsHandler(srv, cors) + handler = newVHostHandler(vhosts, handler) + if len(jwtSecret) != 0 { + handler = newJWTHandler(jwtSecret, handler) + } + return newGzipHandler(handler) +} + +// NewWSHandlerStack returns a wrapped ws-related handler. +func NewWSHandlerStack(srv http.Handler, jwtSecret []byte) http.Handler { + if len(jwtSecret) != 0 { + return newJWTHandler(jwtSecret, srv) + } + return srv +} + +func newCorsHandler(srv http.Handler, allowedOrigins []string) http.Handler { + // disable CORS support if user has not specified a custom CORS configuration + if len(allowedOrigins) == 0 { + return srv + } + c := cors.New(cors.Options{ + AllowedOrigins: allowedOrigins, + AllowedMethods: []string{http.MethodPost, http.MethodGet}, + AllowedHeaders: []string{"*"}, + MaxAge: 600, + }) + return c.Handler(srv) +} + +// virtualHostHandler is a handler which validates the Host-header of incoming requests. +// Using virtual hosts can help prevent DNS rebinding attacks, where a 'random' domain name points to +// the service ip address (but without CORS headers). By verifying the targeted virtual host, we can +// ensure that it's a destination that the node operator has defined. +type virtualHostHandler struct { + vhosts map[string]struct{} + next http.Handler +} + +func newVHostHandler(vhosts []string, next http.Handler) http.Handler { + vhostMap := make(map[string]struct{}) + for _, allowedHost := range vhosts { + vhostMap[strings.ToLower(allowedHost)] = struct{}{} + } + return &virtualHostHandler{vhostMap, next} +} + +// ServeHTTP serves JSON-RPC requests over HTTP, implements http.Handler +func (h *virtualHostHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) { + // if r.Host is not set, we can continue serving since a browser would set the Host header + if r.Host == "" { + h.next.ServeHTTP(w, r) + return + } + host, _, err := net.SplitHostPort(r.Host) + if err != nil { + // Either invalid (too many colons) or no port specified + host = r.Host + } + if ipAddr := net.ParseIP(host); ipAddr != nil { + // It's an IP address, we can serve that + h.next.ServeHTTP(w, r) + return + } + // Not an IP address, but a hostname. Need to validate + if _, exist := h.vhosts["*"]; exist { + h.next.ServeHTTP(w, r) + return + } + if _, exist := h.vhosts[host]; exist { + h.next.ServeHTTP(w, r) + return + } + http.Error(w, "invalid host specified", http.StatusForbidden) +} + +var gzPool = sync.Pool{ + New: func() interface{} { + w := gzip.NewWriter(io.Discard) + return w + }, +} + +type gzipResponseWriter struct { + resp http.ResponseWriter + + gz *gzip.Writer + contentLength uint64 // total length of the uncompressed response + written uint64 // amount of written bytes from the uncompressed response + hasLength bool // true if uncompressed response had Content-Length + inited bool // true after init was called for the first time +} + +// init runs just before response headers are written. Among other things, this function +// also decides whether compression will be applied at all. +func (w *gzipResponseWriter) init() { + if w.inited { + return + } + w.inited = true + + hdr := w.resp.Header() + length := hdr.Get("content-length") + if len(length) > 0 { + if n, err := strconv.ParseUint(length, 10, 64); err != nil { + w.hasLength = true + w.contentLength = n + } + } + + // Setting Transfer-Encoding to "identity" explicitly disables compression. net/http + // also recognizes this header value and uses it to disable "chunked" transfer + // encoding, trimming the header from the response. This means downstream handlers can + // set this without harm, even if they aren't wrapped by newGzipHandler. + // + // In go-ethereum, we use this signal to disable compression for certain error + // responses which are flushed out close to the write deadline of the response. For + // these cases, we want to avoid chunked transfer encoding and compression because + // they require additional output that may not get written in time. + passthrough := hdr.Get("transfer-encoding") == "identity" + if !passthrough { + w.gz = gzPool.Get().(*gzip.Writer) + w.gz.Reset(w.resp) + hdr.Del("content-length") + hdr.Set("content-encoding", "gzip") + } +} + +func (w *gzipResponseWriter) Header() http.Header { + return w.resp.Header() +} + +func (w *gzipResponseWriter) WriteHeader(status int) { + w.init() + w.resp.WriteHeader(status) +} + +func (w *gzipResponseWriter) Write(b []byte) (int, error) { + w.init() + + if w.gz == nil { + // Compression is disabled. + return w.resp.Write(b) + } + + n, err := w.gz.Write(b) + w.written += uint64(n) + if w.hasLength && w.written >= w.contentLength { + // The HTTP handler has finished writing the entire uncompressed response. Close + // the gzip stream to ensure the footer will be seen by the client in case the + // response is flushed after this call to write. + err = w.gz.Close() + } + return n, err +} + +func (w *gzipResponseWriter) Flush() { + if w.gz != nil { + w.gz.Flush() + } + if f, ok := w.resp.(http.Flusher); ok { + f.Flush() + } +} + +func (w *gzipResponseWriter) close() { + if w.gz == nil { + return + } + w.gz.Close() + gzPool.Put(w.gz) + w.gz = nil +} + +func newGzipHandler(next http.Handler) http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if !strings.Contains(r.Header.Get("Accept-Encoding"), "gzip") { + next.ServeHTTP(w, r) + return + } + + wrapper := &gzipResponseWriter{resp: w} + defer wrapper.close() + + next.ServeHTTP(wrapper, r) + }) +} + +type ipcServer struct { + log log.Logger + endpoint string + + mu sync.Mutex + listener net.Listener + srv *rpc.Server +} + +func newIPCServer(log log.Logger, endpoint string) *ipcServer { + return &ipcServer{log: log, endpoint: endpoint} +} + +// Start starts the httpServer's http.Server +func (is *ipcServer) start(apis []rpc.API) error { + is.mu.Lock() + defer is.mu.Unlock() + + if is.listener != nil { + return nil // already running + } + listener, srv, err := rpc.StartIPCEndpoint(is.endpoint, apis) + if err != nil { + is.log.Warn("IPC opening failed", "url", is.endpoint, "error", err) + return err + } + is.log.Info("IPC endpoint opened", "url", is.endpoint) + is.listener, is.srv = listener, srv + return nil +} + +func (is *ipcServer) stop() error { + is.mu.Lock() + defer is.mu.Unlock() + + if is.listener == nil { + return nil // not running + } + err := is.listener.Close() + is.srv.Stop() + is.listener, is.srv = nil, nil + is.log.Info("IPC endpoint closed", "url", is.endpoint) + return err +} + +// 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 RegisterApis(apis []rpc.API, modules []string, srv *rpc.Server) error { + if bad, available := checkModuleAvailability(modules, apis); len(bad) > 0 { + log.Error("Unavailable modules in HTTP API list", "unavailable", bad, "available", available) + } + // Generate the allow list based on the allowed modules + allowList := make(map[string]bool) + for _, module := range modules { + allowList[module] = true + } + // Register all the APIs exposed by the services + for _, api := range apis { + if allowList[api.Namespace] || len(allowList) == 0 { + if err := srv.RegisterName(api.Namespace, api.Service); err != nil { + return err + } + } + } + return nil +} diff --git a/.github/workflows/rpcstack_test.go b/.github/workflows/rpcstack_test.go new file mode 100644 index 0000000..e41cc51 --- /dev/null +++ b/.github/workflows/rpcstack_test.go @@ -0,0 +1,616 @@ +// Copyright 2020 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 . + +package node + +import ( + "bytes" + "fmt" + "io" + "net/http" + "net/http/httptest" + "net/url" + "strconv" + "strings" + "testing" + "time" + + "github.com/ethereum/go-ethereum/internal/testlog" + "github.com/ethereum/go-ethereum/log" + "github.com/ethereum/go-ethereum/rpc" + "github.com/golang-jwt/jwt/v4" + "github.com/gorilla/websocket" + "github.com/stretchr/testify/assert" +) + +const testMethod = "rpc_modules" + +// TestCorsHandler makes sure CORS are properly handled on the http server. +func TestCorsHandler(t *testing.T) { + srv := createAndStartServer(t, &httpConfig{CorsAllowedOrigins: []string{"test", "test.com"}}, false, &wsConfig{}, nil) + defer srv.stop() + url := "http://" + srv.listenAddr() + + resp := rpcRequest(t, url, testMethod, "origin", "test.com") + assert.Equal(t, "test.com", resp.Header.Get("Access-Control-Allow-Origin")) + + resp2 := rpcRequest(t, url, testMethod, "origin", "bad") + assert.Equal(t, "", resp2.Header.Get("Access-Control-Allow-Origin")) +} + +// TestVhosts makes sure vhosts are properly handled on the http server. +func TestVhosts(t *testing.T) { + srv := createAndStartServer(t, &httpConfig{Vhosts: []string{"test"}}, false, &wsConfig{}, nil) + defer srv.stop() + url := "http://" + srv.listenAddr() + + resp := rpcRequest(t, url, testMethod, "host", "test") + assert.Equal(t, resp.StatusCode, http.StatusOK) + + resp2 := rpcRequest(t, url, testMethod, "host", "bad") + assert.Equal(t, resp2.StatusCode, http.StatusForbidden) +} + +type originTest struct { + spec string + expOk []string + expFail []string +} + +// splitAndTrim splits input separated by a comma +// and trims excessive white space from the substrings. +// Copied over from flags.go +func splitAndTrim(input string) (ret []string) { + l := strings.Split(input, ",") + for _, r := range l { + r = strings.TrimSpace(r) + if len(r) > 0 { + ret = append(ret, r) + } + } + return ret +} + +// TestWebsocketOrigins makes sure the websocket origins are properly handled on the websocket server. +func TestWebsocketOrigins(t *testing.T) { + tests := []originTest{ + { + spec: "*", // allow all + expOk: []string{"", "http://test", "https://test", "http://test:8540", "https://test:8540", + "http://test.com", "https://foo.test", "http://testa", "http://atestb:8540", "https://atestb:8540"}, + }, + { + spec: "test", + expOk: []string{"http://test", "https://test", "http://test:8540", "https://test:8540"}, + expFail: []string{"http://test.com", "https://foo.test", "http://testa", "http://atestb:8540", "https://atestb:8540"}, + }, + // scheme tests + { + spec: "https://test", + expOk: []string{"https://test", "https://test:9999"}, + expFail: []string{ + "test", // no scheme, required by spec + "http://test", // wrong scheme + "http://test.foo", "https://a.test.x", // subdomain variations + "http://testx:8540", "https://xtest:8540"}, + }, + // ip tests + { + spec: "https://12.34.56.78", + expOk: []string{"https://12.34.56.78", "https://12.34.56.78:8540"}, + expFail: []string{ + "http://12.34.56.78", // wrong scheme + "http://12.34.56.78:443", // wrong scheme + "http://1.12.34.56.78", // wrong 'domain name' + "http://12.34.56.78.a", // wrong 'domain name' + "https://87.65.43.21", "http://87.65.43.21:8540", "https://87.65.43.21:8540"}, + }, + // port tests + { + spec: "test:8540", + expOk: []string{"http://test:8540", "https://test:8540"}, + expFail: []string{ + "http://test", "https://test", // spec says port required + "http://test:8541", "https://test:8541", // wrong port + "http://bad", "https://bad", "http://bad:8540", "https://bad:8540"}, + }, + // scheme and port + { + spec: "https://test:8540", + expOk: []string{"https://test:8540"}, + expFail: []string{ + "https://test", // missing port + "http://test", // missing port, + wrong scheme + "http://test:8540", // wrong scheme + "http://test:8541", "https://test:8541", // wrong port + "http://bad", "https://bad", "http://bad:8540", "https://bad:8540"}, + }, + // several allowed origins + { + spec: "localhost,http://127.0.0.1", + expOk: []string{"localhost", "http://localhost", "https://localhost:8443", + "http://127.0.0.1", "http://127.0.0.1:8080"}, + expFail: []string{ + "https://127.0.0.1", // wrong scheme + "http://bad", "https://bad", "http://bad:8540", "https://bad:8540"}, + }, + } + for _, tc := range tests { + srv := createAndStartServer(t, &httpConfig{}, true, &wsConfig{Origins: splitAndTrim(tc.spec)}, nil) + url := fmt.Sprintf("ws://%v", srv.listenAddr()) + for _, origin := range tc.expOk { + if err := wsRequest(t, url, "Origin", origin); err != nil { + t.Errorf("spec '%v', origin '%v': expected ok, got %v", tc.spec, origin, err) + } + } + for _, origin := range tc.expFail { + if err := wsRequest(t, url, "Origin", origin); err == nil { + t.Errorf("spec '%v', origin '%v': expected not to allow, got ok", tc.spec, origin) + } + } + srv.stop() + } +} + +// TestIsWebsocket tests if an incoming websocket upgrade request is handled properly. +func TestIsWebsocket(t *testing.T) { + r, _ := http.NewRequest(http.MethodGet, "/", nil) + + assert.False(t, isWebsocket(r)) + r.Header.Set("upgrade", "websocket") + assert.False(t, isWebsocket(r)) + r.Header.Set("connection", "upgrade") + assert.True(t, isWebsocket(r)) + r.Header.Set("connection", "upgrade,keep-alive") + assert.True(t, isWebsocket(r)) + r.Header.Set("connection", " UPGRADE,keep-alive") + assert.True(t, isWebsocket(r)) +} + +func Test_checkPath(t *testing.T) { + tests := []struct { + req *http.Request + prefix string + expected bool + }{ + { + req: &http.Request{URL: &url.URL{Path: "/test"}}, + prefix: "/test", + expected: true, + }, + { + req: &http.Request{URL: &url.URL{Path: "/testing"}}, + prefix: "/test", + expected: true, + }, + { + req: &http.Request{URL: &url.URL{Path: "/"}}, + prefix: "/test", + expected: false, + }, + { + req: &http.Request{URL: &url.URL{Path: "/fail"}}, + prefix: "/test", + expected: false, + }, + { + req: &http.Request{URL: &url.URL{Path: "/"}}, + prefix: "", + expected: true, + }, + { + req: &http.Request{URL: &url.URL{Path: "/fail"}}, + prefix: "", + expected: false, + }, + { + req: &http.Request{URL: &url.URL{Path: "/"}}, + prefix: "/", + expected: true, + }, + { + req: &http.Request{URL: &url.URL{Path: "/testing"}}, + prefix: "/", + expected: true, + }, + } + + for i, tt := range tests { + t.Run(strconv.Itoa(i), func(t *testing.T) { + assert.Equal(t, tt.expected, checkPath(tt.req, tt.prefix)) + }) + } +} + +func createAndStartServer(t *testing.T, conf *httpConfig, ws bool, wsConf *wsConfig, timeouts *rpc.HTTPTimeouts) *httpServer { + t.Helper() + + if timeouts == nil { + timeouts = &rpc.DefaultHTTPTimeouts + } + srv := newHTTPServer(testlog.Logger(t, log.LvlDebug), *timeouts) + assert.NoError(t, srv.enableRPC(apis(), *conf)) + if ws { + assert.NoError(t, srv.enableWS(nil, *wsConf)) + } + assert.NoError(t, srv.setListenAddr("localhost", 0)) + assert.NoError(t, srv.start()) + return srv +} + +// wsRequest attempts to open a WebSocket connection to the given URL. +func wsRequest(t *testing.T, url string, extraHeaders ...string) error { + t.Helper() + //t.Logf("checking WebSocket on %s (origin %q)", url, browserOrigin) + + headers := make(http.Header) + // Apply extra headers. + if len(extraHeaders)%2 != 0 { + panic("odd extraHeaders length") + } + for i := 0; i < len(extraHeaders); i += 2 { + key, value := extraHeaders[i], extraHeaders[i+1] + headers.Set(key, value) + } + conn, _, err := websocket.DefaultDialer.Dial(url, headers) + if conn != nil { + conn.Close() + } + return err +} + +// rpcRequest performs a JSON-RPC request to the given URL. +func rpcRequest(t *testing.T, url, method string, extraHeaders ...string) *http.Response { + t.Helper() + + body := fmt.Sprintf(`{"jsonrpc":"2.0","id":1,"method":"%s","params":[]}`, method) + return baseRpcRequest(t, url, body, extraHeaders...) +} + +func batchRpcRequest(t *testing.T, url string, methods []string, extraHeaders ...string) *http.Response { + reqs := make([]string, len(methods)) + for i, m := range methods { + reqs[i] = fmt.Sprintf(`{"jsonrpc":"2.0","id":1,"method":"%s","params":[]}`, m) + } + body := fmt.Sprintf(`[%s]`, strings.Join(reqs, ",")) + return baseRpcRequest(t, url, body, extraHeaders...) +} + +func baseRpcRequest(t *testing.T, url, bodyStr string, extraHeaders ...string) *http.Response { + t.Helper() + + // Create the request. + body := bytes.NewReader([]byte(bodyStr)) + req, err := http.NewRequest(http.MethodPost, url, body) + if err != nil { + t.Fatal("could not create http request:", err) + } + req.Header.Set("content-type", "application/json") + req.Header.Set("accept-encoding", "identity") + + // Apply extra headers. + if len(extraHeaders)%2 != 0 { + panic("odd extraHeaders length") + } + for i := 0; i < len(extraHeaders); i += 2 { + key, value := extraHeaders[i], extraHeaders[i+1] + if strings.EqualFold(key, "host") { + req.Host = value + } else { + req.Header.Set(key, value) + } + } + + // Perform the request. + t.Logf("checking RPC/HTTP on %s %v", url, extraHeaders) + resp, err := http.DefaultClient.Do(req) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { resp.Body.Close() }) + return resp +} + +type testClaim map[string]interface{} + +func (testClaim) Valid() error { + return nil +} + +func TestJWT(t *testing.T) { + var secret = []byte("secret") + issueToken := func(secret []byte, method jwt.SigningMethod, input map[string]interface{}) string { + if method == nil { + method = jwt.SigningMethodHS256 + } + ss, _ := jwt.NewWithClaims(method, testClaim(input)).SignedString(secret) + return ss + } + cfg := rpcEndpointConfig{jwtSecret: []byte("secret")} + httpcfg := &httpConfig{rpcEndpointConfig: cfg} + wscfg := &wsConfig{Origins: []string{"*"}, rpcEndpointConfig: cfg} + srv := createAndStartServer(t, httpcfg, true, wscfg, nil) + wsUrl := fmt.Sprintf("ws://%v", srv.listenAddr()) + htUrl := fmt.Sprintf("http://%v", srv.listenAddr()) + + expOk := []func() string{ + func() string { + return fmt.Sprintf("Bearer %v", issueToken(secret, nil, testClaim{"iat": time.Now().Unix()})) + }, + func() string { + return fmt.Sprintf("Bearer %v", issueToken(secret, nil, testClaim{"iat": time.Now().Unix() + 4})) + }, + func() string { + return fmt.Sprintf("Bearer %v", issueToken(secret, nil, testClaim{"iat": time.Now().Unix() - 4})) + }, + func() string { + return fmt.Sprintf("Bearer %v", issueToken(secret, nil, testClaim{ + "iat": time.Now().Unix(), + "exp": time.Now().Unix() + 2, + })) + }, + func() string { + return fmt.Sprintf("Bearer %v", issueToken(secret, nil, testClaim{ + "iat": time.Now().Unix(), + "bar": "baz", + })) + }, + } + for i, tokenFn := range expOk { + token := tokenFn() + if err := wsRequest(t, wsUrl, "Authorization", token); err != nil { + t.Errorf("test %d-ws, token '%v': expected ok, got %v", i, token, err) + } + token = tokenFn() + if resp := rpcRequest(t, htUrl, testMethod, "Authorization", token); resp.StatusCode != 200 { + t.Errorf("test %d-http, token '%v': expected ok, got %v", i, token, resp.StatusCode) + } + } + + expFail := []func() string{ + // future + func() string { + return fmt.Sprintf("Bearer %v", issueToken(secret, nil, testClaim{"iat": time.Now().Unix() + int64(jwtExpiryTimeout.Seconds()) + 1})) + }, + // stale + func() string { + return fmt.Sprintf("Bearer %v", issueToken(secret, nil, testClaim{"iat": time.Now().Unix() - int64(jwtExpiryTimeout.Seconds()) - 1})) + }, + // wrong algo + func() string { + return fmt.Sprintf("Bearer %v", issueToken(secret, jwt.SigningMethodHS512, testClaim{"iat": time.Now().Unix() + 4})) + }, + // expired + func() string { + return fmt.Sprintf("Bearer %v", issueToken(secret, nil, testClaim{"iat": time.Now().Unix(), "exp": time.Now().Unix()})) + }, + // missing mandatory iat + func() string { + return fmt.Sprintf("Bearer %v", issueToken(secret, nil, testClaim{})) + }, + // wrong secret + func() string { + return fmt.Sprintf("Bearer %v", issueToken([]byte("wrong"), nil, testClaim{"iat": time.Now().Unix()})) + }, + func() string { + return fmt.Sprintf("Bearer %v", issueToken([]byte{}, nil, testClaim{"iat": time.Now().Unix()})) + }, + func() string { + return fmt.Sprintf("Bearer %v", issueToken(nil, nil, testClaim{"iat": time.Now().Unix()})) + }, + // Various malformed syntax + func() string { + return fmt.Sprintf("%v", issueToken(secret, nil, testClaim{"iat": time.Now().Unix()})) + }, + func() string { + return fmt.Sprintf("Bearer %v", issueToken(secret, nil, testClaim{"iat": time.Now().Unix()})) + }, + func() string { + return fmt.Sprintf("bearer %v", issueToken(secret, nil, testClaim{"iat": time.Now().Unix()})) + }, + func() string { + return fmt.Sprintf("Bearer: %v", issueToken(secret, nil, testClaim{"iat": time.Now().Unix()})) + }, + func() string { + return fmt.Sprintf("Bearer:%v", issueToken(secret, nil, testClaim{"iat": time.Now().Unix()})) + }, + func() string { + return fmt.Sprintf("Bearer\t%v", issueToken(secret, nil, testClaim{"iat": time.Now().Unix()})) + }, + func() string { + return fmt.Sprintf("Bearer \t%v", issueToken(secret, nil, testClaim{"iat": time.Now().Unix()})) + }, + } + for i, tokenFn := range expFail { + token := tokenFn() + if err := wsRequest(t, wsUrl, "Authorization", token); err == nil { + t.Errorf("tc %d-ws, token '%v': expected not to allow, got ok", i, token) + } + + token = tokenFn() + resp := rpcRequest(t, htUrl, testMethod, "Authorization", token) + if resp.StatusCode != http.StatusUnauthorized { + t.Errorf("tc %d-http, token '%v': expected not to allow, got %v", i, token, resp.StatusCode) + } + } + srv.stop() +} + +func TestGzipHandler(t *testing.T) { + type gzipTest struct { + name string + handler http.HandlerFunc + status int + isGzip bool + header map[string]string + } + tests := []gzipTest{ + { + name: "Write", + handler: func(w http.ResponseWriter, r *http.Request) { + w.Write([]byte("response")) + }, + isGzip: true, + status: 200, + }, + { + name: "WriteHeader", + handler: func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("x-foo", "bar") + w.WriteHeader(205) + w.Write([]byte("response")) + }, + isGzip: true, + status: 205, + header: map[string]string{"x-foo": "bar"}, + }, + { + name: "WriteContentLength", + handler: func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("content-length", "8") + w.Write([]byte("response")) + }, + isGzip: true, + status: 200, + }, + { + name: "Flush", + handler: func(w http.ResponseWriter, r *http.Request) { + w.Write([]byte("res")) + w.(http.Flusher).Flush() + w.Write([]byte("ponse")) + }, + isGzip: true, + status: 200, + }, + { + name: "disable", + handler: func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("transfer-encoding", "identity") + w.Header().Set("x-foo", "bar") + w.Write([]byte("response")) + }, + isGzip: false, + status: 200, + header: map[string]string{"x-foo": "bar"}, + }, + { + name: "disable-WriteHeader", + handler: func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("transfer-encoding", "identity") + w.Header().Set("x-foo", "bar") + w.WriteHeader(205) + w.Write([]byte("response")) + }, + isGzip: false, + status: 205, + header: map[string]string{"x-foo": "bar"}, + }, + } + + for _, test := range tests { + test := test + t.Run(test.name, func(t *testing.T) { + srv := httptest.NewServer(newGzipHandler(test.handler)) + defer srv.Close() + + resp, err := http.Get(srv.URL) + if err != nil { + t.Fatal(err) + } + defer resp.Body.Close() + + content, err := io.ReadAll(resp.Body) + if err != nil { + t.Fatal(err) + } + wasGzip := resp.Uncompressed + + if string(content) != "response" { + t.Fatalf("wrong response content %q", content) + } + if wasGzip != test.isGzip { + t.Fatalf("response gzipped == %t, want %t", wasGzip, test.isGzip) + } + if resp.StatusCode != test.status { + t.Fatalf("response status == %d, want %d", resp.StatusCode, test.status) + } + for name, expectedValue := range test.header { + if v := resp.Header.Get(name); v != expectedValue { + t.Fatalf("response header %s == %s, want %s", name, v, expectedValue) + } + } + }) + } +} + +func TestHTTPWriteTimeout(t *testing.T) { + const ( + timeoutRes = `{"jsonrpc":"2.0","id":1,"error":{"code":-32002,"message":"request timed out"}}` + greetRes = `{"jsonrpc":"2.0","id":1,"result":"Hello"}` + ) + // Set-up server + timeouts := rpc.DefaultHTTPTimeouts + timeouts.WriteTimeout = time.Second + srv := createAndStartServer(t, &httpConfig{Modules: []string{"test"}}, false, &wsConfig{}, &timeouts) + url := fmt.Sprintf("http://%v", srv.listenAddr()) + + // Send normal request + t.Run("message", func(t *testing.T) { + resp := rpcRequest(t, url, "test_sleep") + defer resp.Body.Close() + body, err := io.ReadAll(resp.Body) + if err != nil { + t.Fatal(err) + } + if string(body) != timeoutRes { + t.Errorf("wrong response. have %s, want %s", string(body), timeoutRes) + } + }) + + // Batch request + t.Run("batch", func(t *testing.T) { + want := fmt.Sprintf("[%s,%s,%s]", greetRes, timeoutRes, timeoutRes) + resp := batchRpcRequest(t, url, []string{"test_greet", "test_sleep", "test_greet"}) + defer resp.Body.Close() + body, err := io.ReadAll(resp.Body) + if err != nil { + t.Fatal(err) + } + if string(body) != want { + t.Errorf("wrong response. have %s, want %s", string(body), want) + } + }) +} + +func apis() []rpc.API { + return []rpc.API{ + { + Namespace: "test", + Service: &testService{}, + }, + } +} + +type testService struct{} + +func (s *testService) Greet() string { + return "Hello" +} + +func (s *testService) Sleep() { + time.Sleep(1500 * time.Millisecond) +} diff --git a/.github/workflows/utils_test.go b/.github/workflows/utils_test.go new file mode 100644 index 0000000..681f3a8 --- /dev/null +++ b/.github/workflows/utils_test.go @@ -0,0 +1,106 @@ +// 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 . + +// Contains a batch of utility type declarations used by the tests. As the node +// operates on unique types, a lot of them are needed to check various features. + +package node + +import ( + "github.com/ethereum/go-ethereum/p2p" + "github.com/ethereum/go-ethereum/rpc" +) + +// NoopLifecycle is a trivial implementation of the Service interface. +type NoopLifecycle struct{} + +func (s *NoopLifecycle) Start() error { return nil } +func (s *NoopLifecycle) Stop() error { return nil } + +func NewNoop() *Noop { + noop := new(Noop) + return noop +} + +// Set of services all wrapping the base NoopLifecycle resulting in the same method +// signatures but different outer types. +type Noop struct{ NoopLifecycle } + +// InstrumentedService is an implementation of Lifecycle for which all interface +// methods can be instrumented both return value as well as event hook wise. +type InstrumentedService struct { + start error + stop error + + startHook func() + stopHook func() +} + +func (s *InstrumentedService) Start() error { + if s.startHook != nil { + s.startHook() + } + return s.start +} + +func (s *InstrumentedService) Stop() error { + if s.stopHook != nil { + s.stopHook() + } + return s.stop +} + +type FullService struct{} + +func NewFullService(stack *Node) (*FullService, error) { + fs := new(FullService) + + stack.RegisterProtocols(fs.Protocols()) + stack.RegisterAPIs(fs.APIs()) + stack.RegisterLifecycle(fs) + return fs, nil +} + +func (f *FullService) Start() error { return nil } + +func (f *FullService) Stop() error { return nil } + +func (f *FullService) Protocols() []p2p.Protocol { + return []p2p.Protocol{ + { + Name: "test1", + Version: uint(1), + }, + { + Name: "test2", + Version: uint(2), + }, + } +} + +func (f *FullService) APIs() []rpc.API { + return []rpc.API{ + { + Namespace: "admin", + }, + { + Namespace: "debug", + }, + { + Namespace: "net", + }, + } +}