Lint

Author: jshufro

go.mod

@@ -1,3 +1,41 @@
 module github.com/Rocket-Rescue-Node/guarded-beacon-proxy
 
 go 1.19
+
+require (
+	github.com/ethereum/go-ethereum v1.12.0
+	github.com/gorilla/mux v1.8.0
+	github.com/mwitkow/grpc-proxy v0.0.0-20230212185441-f345521cb9c9
+	github.com/prysmaticlabs/prysm/v3 v3.2.2
+	google.golang.org/grpc v1.55.0
+	google.golang.org/protobuf v1.30.0
+)
+
+require (
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/btcsuite/btcd/btcec/v2 v2.3.2 // indirect
+	github.com/cespare/xxhash/v2 v2.2.0 // indirect
+	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.1.0 // indirect
+	github.com/golang/protobuf v1.5.3 // indirect
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.0.1 // indirect
+	github.com/holiman/uint256 v1.2.2-0.20230321075855-87b91420868c // indirect
+	github.com/klauspost/cpuid/v2 v2.2.1 // indirect
+	github.com/matttproud/golang_protobuf_extensions v1.0.4 // indirect
+	github.com/minio/sha256-simd v1.0.0 // indirect
+	github.com/mitchellh/mapstructure v1.4.1 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/prometheus/client_golang v1.14.0 // indirect
+	github.com/prometheus/client_model v0.3.0 // indirect
+	github.com/prometheus/common v0.39.0 // indirect
+	github.com/prometheus/procfs v0.9.0 // indirect
+	github.com/prysmaticlabs/fastssz v0.0.0-20220628121656-93dfe28febab // indirect
+	github.com/prysmaticlabs/go-bitfield v0.0.0-20210809151128-385d8c5e3fb7 // indirect
+	github.com/prysmaticlabs/gohashtree v0.0.2-alpha // indirect
+	github.com/thomaso-mirodin/intmath v0.0.0-20160323211736-5dc6d854e46e // indirect
+	golang.org/x/crypto v0.5.0 // indirect
+	golang.org/x/net v0.8.0 // indirect
+	golang.org/x/sys v0.7.0 // indirect
+	golang.org/x/text v0.8.0 // indirect
+	google.golang.org/genproto v0.0.0-20230306155012-7f2fa6fef1f4 // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+)

go.sum

@@ -1,4 +1,4 @@
-package guarded_beacon_proxy
+package guardedbeaconproxy
 
 import (
 	"context"
@@ -18,6 +18,18 @@ import (
 	"google.golang.org/protobuf/proto"
 )
 
+// GRPCAuthenticator is a function type that authenticates gRPC traffic.
+// The authentication method must be based on gRPC Metadata, as gRPC does not
+// support BasicAuth out of box.
+//
+// Returning an AuthenticationStatus other than Allowed will prevent the request
+// from being proxied. You may optionally return a Context, which will be passed
+// to the PrepareBeaconProposerGuard/RegisterValidatorGuard functions provided.
+// In particular, conext.WithValue allows the authentication method to share state
+// with the guard methods.
+//
+// Any error returned will be sent back to the client, so do not encode sensitive
+// information.
 type GRPCAuthenticator func(metadata.MD) (AuthenticationStatus, context.Context, error)
 
 type prepareBeaconProposerStreamGuard struct {

grpc.go

@@ -1,4 +1,4 @@
-package guarded_beacon_proxy
+package guardedbeaconproxy
 
 import (
 	"context"
@@ -14,9 +14,26 @@ import (
 	"google.golang.org/grpc"
 )
 
+// PrepareBeaconProposerGuard is a function that validates whether or not a PrepareBeaconProposer call
+// should be proxied. The provided Context is whatever was returned by the authenticator.
 type PrepareBeaconProposerGuard func(PrepareBeaconProposerRequest, context.Context) (AuthenticationStatus, error)
+
+// RegisterValidatorGuard is a function that validates whether or not a RegisterValidator call
+// should be proxied. The provided Context is whatever was returned by the authenticator.
 type RegisterValidatorGuard func(RegisterValidatorRequest, context.Context) (AuthenticationStatus, error)
 
+// GuardedBeaconProxy is a reverse proxy for guarding beacon nodes with custom logic.
+//
+// The main goal is to provide easy hooks for custom request authentication and fee recipient
+// validation, which is achieved through the Authenticator and Guard callbacks.
+//
+// Since Prysm uses gRPC, GuardedBeaconProxy can optionally run a gRPC reverse
+// proxy in addition to an HTTP reverse proxy.
+//
+// If GRPCBeaconURL is set, all GRPC fields are required except the TLS block.
+// TLS is currently only supported for gRPC.
+//
+// Fields in GuardedBeaconProxy should be set prior to calling ListenAndServe.
 type GuardedBeaconProxy struct {
 	// URL of the upstream beacon node
 	BeaconURL *url.URL
@@ -60,15 +77,30 @@ type GuardedBeaconProxy struct {
 	upstream  *grpc.ClientConn
 }
 
+// Stop attempts to gracefully shut down the GuardedBeaconProxy.
+//
+// After gracePeriod has elapsed, the GuardedBeaconProxy will be
+// immediately stopped instead.
 func (gbp *GuardedBeaconProxy) Stop(gracePeriod time.Duration) {
 	go func() {
 		time.Sleep(gracePeriod)
 		gbp.server.Close()
+		if gbp.gRPCProxy != nil {
+			gbp.gRPCProxy.Stop()
+		}
 	}()
 
-	gbp.server.Shutdown(context.Background())
+	if gbp.gRPCProxy != nil {
+		go gbp.gRPCProxy.GracefulStop()
+	}
+	go gbp.server.Shutdown(context.Background())
 }
 
+// ListenAndServe binds the GuardedBeaconProxy to its HTTP port, and
+// optionally its gRPC port, and prepares to receive and proxy
+// traffic from validators.
+//
+// ListenAndServe blocks until Stop is called or an error is encountered.
 func (gbp *GuardedBeaconProxy) ListenAndServe() error {
 
 	gbp.server.Addr = gbp.Addr
@@ -133,6 +165,7 @@ func (gbp *GuardedBeaconProxy) ListenAndServe() error {
 		grpcErrChan <- gbp.gRPCProxy.Serve(listener)
 		close(grpcErrChan)
 	}()
+	defer gbp.gRPCProxy.Stop()
 
 	select {
 	case httpErr := <-httpErrChan:
@@ -141,5 +174,4 @@ func (gbp *GuardedBeaconProxy) ListenAndServe() error {
 		return grpcErr
 	}
 
-	return nil
 }

guarded-beacon-proxy.go

@@ -1,4 +1,4 @@
-package guarded_beacon_proxy
+package guardedbeaconproxy
 
 import (
 	"bytes"
@@ -9,6 +9,17 @@ import (
 	"net/http"
 )
 
+// HTTPAuthenticator is a function type which can authenticate HTTP requests.
+// For example, by checking the contents of the BasicAuth header.
+//
+// Returning an AuthenticationStatus other than Allowed will prevent the request
+// from being proxied. You may optionally return a Context, which will be passed
+// to the PrepareBeaconProposerGuard/RegisterValidatorGuard functions provided.
+// In particular, conext.WithValue allows the authentication method to share state
+// with the guard methods.
+//
+// Any error returned will be sent back to the client, so do not encode sensitive
+// information.
 type HTTPAuthenticator func(*http.Request) (AuthenticationStatus, context.Context, error)
 
 func (gbp *GuardedBeaconProxy) authenticationMiddleware(next http.Handler) http.Handler {
@@ -25,7 +36,6 @@ func (gbp *GuardedBeaconProxy) authenticationMiddleware(next http.Handler) http.
 		}
 
 		gbp.httpError(w, status.httpStatus(), err)
-		return
 	})
 }
 

http.go

@@ -1,13 +1,19 @@
-package guarded_beacon_proxy
+package guardedbeaconproxy
 
 import (
 	"net/http"
 
 	"google.golang.org/grpc/codes"
 )
 
+// AuthenticationStatus is a generic status response representing auth or guard
+// results.
+//
+// It is returned by the custom authentication or guard functions on the GuardedBeaconProxy,
+// and mapped to an appropriate HTTP or gRPC error as needed.
 type AuthenticationStatus uint32
 
+// These constants are the only allowable AuthenticationStatus values
 const (
 	Allowed AuthenticationStatus = iota
 	BadRequest

status.go

@@ -1,17 +1,23 @@
-package guarded_beacon_proxy
+package guardedbeaconproxy
 
+// PrepareBeaconProposerRequest is the in-memory representation of a
+// prepare_beacon_proposer API call, be it gRPC or HTTP.
 type PrepareBeaconProposerRequest []struct {
 	ValidatorIndex string `json:"validator_index"`
 	FeeRecipient   string `json:"fee_recipient"`
 }
 
+// RegisterValidatorMessage is the in-memory representation of a
+// register_validator API call entry, be it gRPC or HTTP.
 type RegisterValidatorMessage struct {
 	FeeRecipient string `json:"fee_recipient"`
 	GasLimit     string `json:"gas_limit"`
 	Timestamp    string `json:"timestamp"`
 	Pubkey       string `json:"pubkey"`
 }
 
+// RegisterValidatorRequest is the in-memory representation of a
+// register_validator API call, be it gRPC or HTTP.
 type RegisterValidatorRequest []struct {
 	Message   RegisterValidatorMessage `json:"message"`
 	Signature string                   `json:"signature"`