Documentation
¶
Overview ¶
backend_probe.go implements HTTP health check probing for backend servers.
The probe system is inspired by Kubernetes liveness/readiness probes and provides:
- Periodic HTTP health checks against a configurable endpoint
- Configurable success/failure thresholds to prevent flapping
- Async operation via a background goroutine per backend
Usage ¶
When a backend is configured with a probe_url, a ProbeWorker runs in the background, periodically checking the endpoint. The backend is only marked unhealthy after FailureThreshold consecutive failures, and only marked healthy after SuccessThreshold consecutive successes. This threshold behavior prevents health status from flapping due to transient network issues.
Configuration ¶
ProbeSpec controls the probe behavior:
- FailureThreshold: consecutive failures before marking unhealthy (default: 1)
- SuccessThreshold: consecutive successes before marking healthy (default: 2)
- Period: interval between probes (default: 4s)
- Timeout: HTTP request timeout per probe (default: 4s)
HTTP Probe Behavior ¶
The probe sends a GET request to the configured URL. Success is determined by:
- 2xx status codes: success
- 3xx (redirects), 4xx, 5xx, or connection errors: failure
The probe uses a custom dialer with SO_LINGER set (borrowed from Kubernetes) to ensure clean connection teardown, and disables keep-alives to get fresh connection state each probe.
Index ¶
- Constants
- Variables
- func CheckRedisConnection(client redis.UniversalClient) error
- func CommonStrategyOpts(opts ...commonStrategyOpt) []commonStrategyOpt
- func CreateTLSClient(ca string) (*tls.Config, error)
- func GetAuthCtx(ctx context.Context) string
- func GetOpTxProxyAuthHeader(ctx context.Context) string
- func GetReqID(ctx context.Context) string
- func GetReqReceivedAt(ctx context.Context) time.Time
- func GetXForwardedFor(ctx context.Context) string
- func IsBatch(raw []byte) bool
- func IsValidID(id json.RawMessage) bool
- func LimitReader(r io.Reader, n int64) io.Reader
- func MaybeRecordErrorsInRPCRes(ctx context.Context, backendName string, reqs []*RPCReq, resBatch []*RPCRes)
- func MaybeRecordSpecialRPCError(ctx context.Context, backendName, method string, rpcErr *RPCErr)
- func NewAgreementStrategy(urls []string, minResponses int, opts ...commonStrategyOpt) *agreementStrategyImpl
- func NewCommonInteropStrategy(urls []string, opts ...commonStrategyOpt) *commonInteropStrategy
- func NewFirstFilterStrategy(urls []string, opts ...commonStrategyOpt) *firstFilterStrategyImpl
- func NewHealthAwareBackend(url string, unhealthinessTimeout time.Duration) *healthAwareBackend
- func NewHealthAwareLoadBalancingStrategy(urls []string, unhealthinessTimeout time.Duration, opts ...commonStrategyOpt) *healthAwareLoadBalancingStrategyImpl
- func NewLoadBalancingBuffer(urls []string, unhealthinessTimeout time.Duration) *loadBalancingBuffer
- func NewMulticallStrategy(urls []string, opts ...commonStrategyOpt) *multicallStrategyImpl
- func NewRedisClient(url string, enable_cluster bool) (redis.UniversalClient, error)
- func ParseBatchRPCReq(body []byte) ([]json.RawMessage, error)
- func ParseKeyPair(crt, key string) (tls.Certificate, error)
- func ReadFromEnvOrConfig(value string) (string, error)
- func RecordBackendFinalizedBlock(b *Backend, blockNumber hexutil.Uint64)
- func RecordBackendGroupFallbacks(bg *BackendGroup, name string, fallback bool)
- func RecordBackendGroupMulticallCompletion(bg *BackendGroup, backendName string, error string)
- func RecordBackendGroupMulticallRequest(bg *BackendGroup, backendName string)
- func RecordBackendLatestBlock(b *Backend, blockNumber hexutil.Uint64)
- func RecordBackendNetworkErrorRateSlidingWindow(b *Backend, rate float64)
- func RecordBackendNetworkLatencyAverageSlidingWindow(b *Backend, avgLatency time.Duration)
- func RecordBackendProbeCheck(backendName string, success bool)
- func RecordBackendProbeDuration(backendName string, duration time.Duration)
- func RecordBackendProbeHealthy(backendName string, healthy bool)
- func RecordBackendSafeBlock(b *Backend, blockNumber hexutil.Uint64)
- func RecordBackendUnexpectedBlockTags(b *Backend, unexpected bool)
- func RecordBatchRPCError(ctx context.Context, backendName string, reqs []*RPCReq, err error)
- func RecordBatchRPCForward(ctx context.Context, backendName string, reqs []*RPCReq, source string)
- func RecordBatchSize(size int)
- func RecordCLBackendCurrentL1(b *Backend, blockNumber uint64)
- func RecordCLBackendL1Lag(b *Backend, lag uint64)
- func RecordCLBackendL1Stale(b *Backend, stale bool)
- func RecordCLBackendLocalSafeBlock(b *Backend, blockNumber hexutil.Uint64)
- func RecordCLBanInteropSafeGtLocalSafe(b *Backend)
- func RecordCLBanNotHealthy(b *Backend)
- func RecordCLBanOutputRootMismatch(b *Backend)
- func RecordCLBanOutputRootTimeout(b *Backend)
- func RecordCLBanUnexpectedBlockTags(b *Backend)
- func RecordCLConsensusHalted(group *BackendGroup, halted bool)
- func RecordCLGroupLocalSafeBlock(group *BackendGroup, blockNumber hexutil.Uint64)
- func RecordCLGroupPinL1(group *BackendGroup, pinBackend *Backend, blockNumber uint64)
- func RecordCLNoPinCandidate(group *BackendGroup)
- func RecordCLOutputRootDisagreement(b *Backend)
- func RecordCLSyncStatusCacheHit(group *BackendGroup)
- func RecordCLSyncStatusCacheMiss(group *BackendGroup)
- func RecordCacheError(method string)
- func RecordCacheHit(method string)
- func RecordCacheMiss(method string)
- func RecordConsensusBackendBanned(b *Backend, banned bool)
- func RecordConsensusBackendInSync(b *Backend, inSync bool)
- func RecordConsensusBackendPeerCount(b *Backend, peerCount uint64)
- func RecordConsensusBackendUpdateDelay(b *Backend, lastUpdate time.Time)
- func RecordGroupConsensusCount(group *BackendGroup, count int)
- func RecordGroupConsensusError(group *BackendGroup, label string, err error)
- func RecordGroupConsensusFilteredCount(group *BackendGroup, count int)
- func RecordGroupConsensusFinalizedBlock(group *BackendGroup, blockNumber hexutil.Uint64)
- func RecordGroupConsensusHACLPinL1(group *BackendGroup, leader string, l1Num uint64)
- func RecordGroupConsensusHAFinalizedBlock(group *BackendGroup, leader string, blockNumber hexutil.Uint64)
- func RecordGroupConsensusHALatestBlock(group *BackendGroup, leader string, blockNumber hexutil.Uint64)
- func RecordGroupConsensusHASafeBlock(group *BackendGroup, leader string, blockNumber hexutil.Uint64)
- func RecordGroupConsensusHAServingLocal(group *BackendGroup, servingLocal bool)
- func RecordGroupConsensusLatestBlock(group *BackendGroup, blockNumber hexutil.Uint64)
- func RecordGroupConsensusSafeBlock(group *BackendGroup, blockNumber hexutil.Uint64)
- func RecordGroupTotalCount(group *BackendGroup, count int)
- func RecordHTTPRequestByMethodDuration(method string, d time.Duration)
- func RecordHealthyCandidates(b *BackendGroup, candidates int)
- func RecordRPCCall(backendName, method, statusCode, transport string)
- func RecordRPCError(ctx context.Context, backendName, method string, err error)
- func RecordRPCForward(ctx context.Context, backendName, method, source string)
- func RecordRPCNotification(backendName string)
- func RecordRedisError(source string)
- func RecordRequestPayloadSize(ctx context.Context, payloadSize int)
- func RecordResponsePayloadSize(ctx context.Context, payloadSize int)
- func RecordUnserviceableRequest(ctx context.Context, source string)
- func RecordUp()
- func RecordWSMessage(ctx context.Context, backendName, source string)
- func SetLogLevel(logLevel slog.Leveler)
- func ValidateRPCReq(req *RPCReq) error
- type AliasRateLimitConfig
- type AliasRateLimitMethodOverride
- type Backend
- func (b *Backend) ClearSlidingWindows()
- func (b *Backend) ErrorRate() (errorRate float64)
- func (b *Backend) Forward(ctx context.Context, reqs []*RPCReq, isBatch bool) ([]*RPCRes, error)
- func (b *Backend) ForwardRPC(ctx context.Context, res *RPCRes, id string, method string, params ...any) error
- func (b *Backend) ForwardWithSource(ctx context.Context, reqs []*RPCReq, isBatch bool, source string) ([]*RPCRes, error)
- func (b *Backend) IsDegraded() bool
- func (b *Backend) IsHealthy() bool
- func (b *Backend) IsProbeHealthy() bool
- func (b *Backend) Override(opts ...BackendOpt)
- func (b *Backend) ProxyWS(clientConn *websocket.Conn, methodWhitelist *StringSet, serverReadLimit int64) (*WSProxier, error)
- func (b *Backend) SetProbeHealth(healthy bool)
- type BackendConfig
- type BackendGroup
- func (bg *BackendGroup) ExecuteMulticall(ctx context.Context, rpcReqs []*RPCReq, source string) *BackendGroupRPCResponse
- func (bg *BackendGroup) Fallbacks() []*Backend
- func (bg *BackendGroup) Forward(ctx context.Context, rpcReqs []*RPCReq, isBatch bool) ([]*RPCRes, string, error)
- func (bg *BackendGroup) ForwardRequestToBackendGroup(rpcReqs []*RPCReq, backends []*Backend, ctx context.Context, isBatch bool, ...) *BackendGroupRPCResponse
- func (bg *BackendGroup) ForwardWithSource(ctx context.Context, rpcReqs []*RPCReq, isBatch bool, source string) ([]*RPCRes, string, error)
- func (bg *BackendGroup) GetRoutingStrategy() RoutingStrategy
- func (bg *BackendGroup) MulticallRequest(backend *Backend, rpcReqs []*RPCReq, wg *sync.WaitGroup, ctx context.Context, ...)
- func (bg *BackendGroup) OverwriteConsensusResponses(rpcReqs []*RPCReq, overriddenResponses []*indexedReqRes, ...) ([]*RPCReq, []*indexedReqRes)
- func (bg *BackendGroup) OverwriteNonConsensusRequests(rpcReqs []*RPCReq, overriddenResponses []*indexedReqRes) ([]*RPCReq, []*indexedReqRes)
- func (bg *BackendGroup) Primaries() []*Backend
- func (bg *BackendGroup) ProcessMulticallResponses(ch chan *multicallTuple, ctx context.Context) (resp *BackendGroupRPCResponse, unserviceable bool)
- func (bg *BackendGroup) ProxyWS(ctx context.Context, clientConn *websocket.Conn, methodWhitelist *StringSet, ...) (*WSProxier, error)
- func (bg *BackendGroup) Shutdown()
- type BackendGroupConfig
- type BackendGroupRPCResponse
- type BackendGroupsConfig
- type BackendOpt
- func WithAllowedStatusCodes(allowedStatusCodes []int) BackendOpt
- func WithBasicAuth(username, password string) BackendOpt
- func WithConsensusForcedCandidate(forcedCandidate bool) BackendOpt
- func WithConsensusReceiptTarget(receiptsTarget string) BackendOpt
- func WithConsensusSkipPeerCountCheck(skipPeerCountCheck bool) BackendOpt
- func WithFinalizedBlockDriftThreshold(finalizedBlockDriftThreshold uint64) BackendOpt
- func WithHeaders(headers map[string]string) BackendOpt
- func WithIntermittentNetworkErrorSlidingWindow(sw *sw.AvgSlidingWindow) BackendOpt
- func WithMaxDegradedLatencyThreshold(maxDegradedLatencyThreshold time.Duration) BackendOpt
- func WithMaxErrorRateThreshold(maxErrorRateThreshold float64) BackendOpt
- func WithMaxLatencyThreshold(maxLatencyThreshold time.Duration) BackendOpt
- func WithMaxRPS(maxRPS int) BackendOpt
- func WithMaxResponseSize(size int64) BackendOpt
- func WithMaxRetries(retries int) BackendOpt
- func WithMaxWSConns(maxConns int) BackendOpt
- func WithOutOfServiceDuration(interval time.Duration) BackendOpt
- func WithProbe(probeURL string, probeFailureThreshold int, probeSuccessThreshold int, ...) BackendOpt
- func WithProxydIP(ip string) BackendOpt
- func WithSafeBlockDriftThreshold(safeBlockDriftThreshold uint64) BackendOpt
- func WithSkipIsSyncingCheck(skipIsSyncingCheck bool) BackendOpt
- func WithStrippedTrailingXFF() BackendOpt
- func WithTLSConfig(tlsConfig *tls.Config) BackendOpt
- func WithTimeout(timeout time.Duration) BackendOpt
- func WithWeight(weight int) BackendOpt
- type BackendOptions
- type BackendsConfig
- type BatchConfig
- type BlockHashOrNumberParameter
- type Cache
- type CacheConfig
- type Config
- type ConsensusAsyncHandler
- type ConsensusGetReceiptsResult
- type ConsensusOpt
- func WithAsyncHandler(asyncHandler ConsensusAsyncHandler) ConsensusOpt
- func WithBanPeriod(banPeriod time.Duration) ConsensusOpt
- func WithCLConsensusMode() ConsensusOpt
- func WithCLHeadL1MaxAge(maxAge time.Duration) ConsensusOpt
- func WithCLOutputRootBanThreshold(threshold uint) ConsensusOpt
- func WithCLSyncThreshold(threshold uint64) ConsensusOpt
- func WithListener(listener OnConsensusBroken) ConsensusOpt
- func WithMaxBlockLag(maxBlockLag uint64) ConsensusOpt
- func WithMaxBlockRange(maxBlockRange uint64) ConsensusOpt
- func WithMaxUpdateThreshold(maxUpdateThreshold time.Duration) ConsensusOpt
- func WithMinPeerCount(minPeerCount uint64) ConsensusOpt
- func WithPollerInterval(interval time.Duration) ConsensusOpt
- func WithTracker(tracker ConsensusTracker) ConsensusOpt
- type ConsensusPoller
- func (cp *ConsensusPoller) AddListener(listener OnConsensusBroken)
- func (cp *ConsensusPoller) Ban(be *Backend)
- func (cp *ConsensusPoller) BannedUntil(be *Backend) time.Time
- func (cp *ConsensusPoller) ClearListeners()
- func (cp *ConsensusPoller) FilterCandidates(backends []*Backend) map[*Backend]*backendState
- func (cp *ConsensusPoller) GetBackendState(be *Backend) *backendState
- func (cp *ConsensusPoller) GetConsensusGroup() []*Backend
- func (cp *ConsensusPoller) GetConsensusSyncStatusBody() json.RawMessage
- func (cp *ConsensusPoller) GetFinalizedBlockNumber() hexutil.Uint64
- func (cp *ConsensusPoller) GetLastUpdate(be *Backend) time.Time
- func (cp *ConsensusPoller) GetLatestBlockNumber() hexutil.Uint64
- func (cp *ConsensusPoller) GetLocalSafeBlockNumber() hexutil.Uint64
- func (cp *ConsensusPoller) GetSafeBlockNumber() hexutil.Uint64
- func (cp *ConsensusPoller) IsBanned(be *Backend) bool
- func (cp *ConsensusPoller) IsConsensusLayer() bool
- func (cp *ConsensusPoller) Reset()
- func (cp *ConsensusPoller) Shutdown()
- func (cp *ConsensusPoller) Unban(be *Backend)
- func (cp *ConsensusPoller) UpdateBackend(ctx context.Context, be *Backend)
- func (cp *ConsensusPoller) UpdateBackendGroupConsensus(ctx context.Context)
- type ConsensusTracker
- type ConsensusTrackerState
- type ELBlockState
- type FallbackRateLimiter
- type FrontendRateLimiter
- func NewFallbackRateLimiter(primary FrontendRateLimiter, secondary FrontendRateLimiter) FrontendRateLimiter
- func NewMemoryFrontendRateLimit(dur time.Duration, max int) FrontendRateLimiter
- func NewRedisFrontendRateLimiter(r redis.UniversalClient, dur time.Duration, max int, prefix string) FrontendRateLimiter
- type InMemoryConsensusTracker
- func (ct *InMemoryConsensusTracker) Behind(other *InMemoryConsensusTracker) bool
- func (ct *InMemoryConsensusTracker) GetCLSyncBody() (json.RawMessage, uint64)
- func (ct *InMemoryConsensusTracker) GetState() ConsensusTrackerState
- func (ct *InMemoryConsensusTracker) SetCLSyncBody(body json.RawMessage, l1Num uint64)
- func (ct *InMemoryConsensusTracker) SetState(state ConsensusTrackerState)
- func (ct *InMemoryConsensusTracker) UpdatedAt() time.Time
- func (ct *InMemoryConsensusTracker) Valid() bool
- type InteropStrategy
- type InteropValidationConfig
- type InteropValidationStrategy
- type LimitedHTTPClient
- type LimitedReader
- type MemoryFrontendRateLimiter
- type MemoryPendingStore
- func (s *MemoryPendingStore) Add(e txmonEntry) bool
- func (s *MemoryPendingStore) ExpireBefore(cutoff time.Time) []txmonEntry
- func (s *MemoryPendingStore) Len() int
- func (s *MemoryPendingStore) MarkSubblock(h common.Hash, at time.Time) (txmonEntry, bool)
- func (s *MemoryPendingStore) MatchAndRemove(hashes []common.Hash) []txmonEntry
- type MethodMappingsConfig
- type MetricsConfig
- type NoopAsyncHandler
- type NoopRPCCache
- type OnConsensusBroken
- type PendingStore
- type PollerAsyncHandler
- type ProbeSpec
- type ProbeWorker
- type RPCCache
- type RPCErr
- type RPCMethodHandler
- type RPCReq
- type RPCRes
- type RateLimitConfig
- type RateLimitMethodOverride
- type RedisConfig
- type RedisConsensusTracker
- func (ct *RedisConsensusTracker) GetCLSyncBody() (json.RawMessage, uint64)
- func (ct *RedisConsensusTracker) GetState() ConsensusTrackerState
- func (ct *RedisConsensusTracker) Init()
- func (ct *RedisConsensusTracker) SetCLSyncBody(body json.RawMessage, l1Num uint64)
- func (ct *RedisConsensusTracker) SetState(state ConsensusTrackerState)
- type RedisConsensusTrackerOpt
- type RedisFrontendRateLimiter
- type RewriteContext
- type RewriteResult
- type RoutingStrategy
- type SenderRateLimitConfig
- type Server
- func (s *Server) Drain()
- func (s *Server) HandleHealthz(w http.ResponseWriter, r *http.Request)
- func (s *Server) HandleRPC(w http.ResponseWriter, r *http.Request)
- func (s *Server) HandleWS(w http.ResponseWriter, r *http.Request)
- func (s *Server) RPCListenAndServe(host string, port int) error
- func (s *Server) Shutdown()
- func (s *Server) WSListenAndServe(host string, port int) error
- type ServerConfig
- type StaticMethodHandler
- type StringSet
- type TOMLDuration
- type TransactionWithFrom
- type TxFilter
- type TxFilterModule
- type TxMonitor
- type TxMonitorConfig
- type TxSubmission
- type TxValidationClient
- type TxValidationFunc
- type TxValidationMethodSet
- type TxValidationMiddlewareConfig
- type WSProxier
Constants ¶
const ( JSONRPCVersion = "2.0" // JSONRPCErrorInternal is geth's implementation-defined server error code; // jsonRPCSpecInternalError is the JSON-RPC 2.0 spec "Internal error" code. // Both are treated as internal (non-verdict) errors. JSONRPCErrorInternal = -32000 )
const ( MetricsNamespace = "proxyd" RPCRequestSourceHTTP = "http" RPCRequestSourceWS = "ws" BackendProxyd = "proxyd" BackendCache = "cache" SourceClient = "client" SourceBackend = "backend" MethodUnknown = "unknown" MethodNotAllowed = "method_not_allowed" // MethodBatch is the method_name label for an HTTP request whose body is a // JSON-RPC batch. One request carries many methods, so it cannot take a real one. MethodBatch = "<batch>" // StatusCodeRelayed marks a WS call relayed to the backend whose response // cannot be correlated back to the request (eth_subscribe / eth_unsubscribe). // Deliberately non-numeric so status_code=~"2.." and status_code=~"5.." can // never match it: such a call is neither a success nor a failure. StatusCodeRelayed = "relayed" )
const ( ContextKeyAuth = "authorization" ContextKeyReqID = "req_id" ContextKeyXForwardedFor = "x_forwarded_for" ContextKeyOpTxProxyAuth = "op_txproxy_auth" ContextKeyInteropValidationStrategy = "interop_validation_strategy" ContextKeyReqReceivedAt = "req_received_at" DefaultOpTxProxyAuthHeader = "X-Optimism-Signature" DefaultMaxBatchRPCCallsLimit = 100 MaxBatchRPCCallsHardLimit = 1000 )
const ConsensusGetReceiptsMethod = "consensus_getReceipts"
const (
DefaultPollerInterval = 1 * time.Second
)
const ReceiptsTargetAlchemyGetTransactionReceipts = "alchemy_getTransactionReceipts"
const ReceiptsTargetDebugGetRawReceipts = "debug_getRawReceipts"
const ReceiptsTargetEthGetTransactionReceipts = "eth_getBlockReceipts"
const ReceiptsTargetParityGetTransactionReceipts = "parity_getBlockReceipts"
Variables ¶
var ( ErrParseErr = &RPCErr{ Code: -32700, Message: "parse error", HTTPErrorCode: 400, } ErrInternal = &RPCErr{ Code: JSONRPCErrorInternal, Message: "internal error", HTTPErrorCode: 500, } ErrMethodNotWhitelisted = &RPCErr{ Code: notFoundRpcError, Message: "rpc method is not whitelisted", HTTPErrorCode: 403, } ErrBackendOffline = &RPCErr{ Code: JSONRPCErrorInternal - 10, Message: "backend offline", HTTPErrorCode: 503, } ErrNoBackends = &RPCErr{ Code: JSONRPCErrorInternal - 11, Message: "no backend is currently healthy to serve traffic", HTTPErrorCode: 503, } ErrBackendOverCapacity = &RPCErr{ Code: JSONRPCErrorInternal - 12, Message: "backend is over capacity", HTTPErrorCode: 429, } ErrBackendBadResponse = &RPCErr{ Code: JSONRPCErrorInternal - 13, Message: "backend returned an invalid response", HTTPErrorCode: 500, } ErrTooManyBatchRequests = &RPCErr{ Code: JSONRPCErrorInternal - 14, Message: "too many RPC calls in batch request", HTTPErrorCode: 413, } ErrGatewayTimeout = &RPCErr{ Code: JSONRPCErrorInternal - 15, Message: "gateway timeout", HTTPErrorCode: 504, } ErrOverRateLimit = &RPCErr{ Code: JSONRPCErrorInternal - 16, Message: "over rate limit", HTTPErrorCode: 429, } ErrOverSenderRateLimit = &RPCErr{ Code: JSONRPCErrorInternal - 17, Message: "sender is over rate limit", HTTPErrorCode: 429, } ErrNotHealthy = &RPCErr{ Code: JSONRPCErrorInternal - 18, Message: "backend is currently not healthy to serve traffic", HTTPErrorCode: 503, } ErrRequestBodyTooLarge = &RPCErr{ Code: JSONRPCErrorInternal - 21, Message: "request body too large", HTTPErrorCode: 413, } ErrBackendResponseTooLarge = &RPCErr{ Code: JSONRPCErrorInternal - 20, Message: "backend response too large", HTTPErrorCode: 400, } ErrInteropAccessListOutOfBounds = &RPCErr{ Code: JSONRPCErrorInternal - 22, Message: "access list out of bounds", HTTPErrorCode: 413, } ErrContextCanceled = &RPCErr{ Code: JSONRPCErrorInternal - 23, Message: context.Canceled.Error(), HTTPErrorCode: 499, } ErrTooManyRequests = &RPCErr{ Code: JSONRPCErrorInternal - 24, Message: "too many requests", HTTPErrorCode: 429, } ErrTransactionRejected = &RPCErr{ Code: JSONRPCErrorInternal - 100, Message: "transaction rejected", HTTPErrorCode: 400, } // Out-of-range answers keep HTTP 200, as an execution client's do. -32001 is // EIP-1898's "Resource not found", which op-reth returns for an unknown block. ErrBlockNotFound = &RPCErr{ Code: -32001, Message: "block not found", } // What op-geth and op-reth return for an eth_getLogs range past their head. ErrBlockRangeBeyondHead = &RPCErr{ Code: -32602, Message: "block range extends beyond current head block", } ErrCLConsensusSyncNotReady = &RPCErr{ Code: JSONRPCErrorInternal - 25, Message: "optimism_syncStatus not available", HTTPErrorCode: 503, } ErrBackendUnexpectedJSONRPC = errors.New("backend returned an unexpected JSON-RPC response") ErrConsensusGetReceiptsCantBeBatched = errors.New("consensus_getReceipts cannot be batched") ErrConsensusGetReceiptsInvalidTarget = errors.New("unsupported consensus_receipts_target") )
var ( ErrRewriteBlockOutOfRange = errors.New("block is out of range") ErrRewriteRangeTooLarge = errors.New("block range is too large") )
var DefaultTxValidationMethods = []string{
"eth_sendRawTransaction",
"eth_sendRawTransactionConditional",
"eth_sendBundle",
}
var ErrLimitReaderOverLimit = errors.New("over read limit")
var MillisecondDurationBuckets = []float64{1, 10, 50, 100, 500, 1000, 5000, 10000, 100000}
var NoopFrontendRateLimiter = &noopFrontendRateLimiter{}
var PayloadSizeBuckets = []float64{100, 500, 1000, 10000, 100000, 1000000, 2500000, 5000000, 7500000, 10000000, 25000000}
var WithAccessListSizeLimit = func(accessListSizeLimit int) commonStrategyOpt {
return func(s *commonInteropStrategy) {
s.accessListSizeLimit = accessListSizeLimit
}
}
var WithChainID = func(chainID uint64) commonStrategyOpt { return func(s *commonInteropStrategy) { s.chainID = eth.ChainIDFromUInt64(chainID) } }
var WithReqSizeLimit = func(reqSizeLimit int) commonStrategyOpt {
return func(s *commonInteropStrategy) {
s.reqSizeLimit = reqSizeLimit
}
}
var WithValidateAndDeduplicateInteropAccessList = func(validateAndDeduplicateInteropAccessList bool) commonStrategyOpt {
return func(s *commonInteropStrategy) {
s.validateAndDeduplicateInteropAccessList = validateAndDeduplicateInteropAccessList
}
}
Functions ¶
func CheckRedisConnection ¶
func CheckRedisConnection(client redis.UniversalClient) error
func CommonStrategyOpts ¶
func CommonStrategyOpts(opts ...commonStrategyOpt) []commonStrategyOpt
func GetAuthCtx ¶
func GetOpTxProxyAuthHeader ¶
func GetReqReceivedAt ¶
GetReqReceivedAt returns the wall-clock time the request was received at ingress, stamped by populateContext (HTTP) or per-message in the WS pump. It falls back to time.Now() when unset (internal or test callers) so the tx monitor never records a zero start time.
func GetXForwardedFor ¶
func IsValidID ¶
func IsValidID(id json.RawMessage) bool
func NewAgreementStrategy ¶
func NewCommonInteropStrategy ¶
func NewCommonInteropStrategy(urls []string, opts ...commonStrategyOpt) *commonInteropStrategy
func NewFirstFilterStrategy ¶
func NewFirstFilterStrategy(urls []string, opts ...commonStrategyOpt) *firstFilterStrategyImpl
func NewHealthAwareBackend ¶
func NewLoadBalancingBuffer ¶
func NewMulticallStrategy ¶
func NewMulticallStrategy(urls []string, opts ...commonStrategyOpt) *multicallStrategyImpl
func NewRedisClient ¶
func NewRedisClient(url string, enable_cluster bool) (redis.UniversalClient, error)
func ParseBatchRPCReq ¶
func ParseBatchRPCReq(body []byte) ([]json.RawMessage, error)
func ParseKeyPair ¶
func ParseKeyPair(crt, key string) (tls.Certificate, error)
func ReadFromEnvOrConfig ¶
func RecordBackendGroupFallbacks ¶
func RecordBackendGroupFallbacks(bg *BackendGroup, name string, fallback bool)
func RecordBackendGroupMulticallCompletion ¶
func RecordBackendGroupMulticallCompletion(bg *BackendGroup, backendName string, error string)
func RecordBackendGroupMulticallRequest ¶
func RecordBackendGroupMulticallRequest(bg *BackendGroup, backendName string)
func RecordBackendProbeCheck ¶
func RecordBackendSafeBlock ¶
func RecordBatchRPCError ¶
func RecordBatchRPCForward ¶
func RecordBatchSize ¶
func RecordBatchSize(size int)
func RecordCLBackendL1Lag ¶
func RecordCLBackendL1Stale ¶
func RecordCLBanInteropSafeGtLocalSafe ¶
func RecordCLBanInteropSafeGtLocalSafe(b *Backend)
func RecordCLBanNotHealthy ¶
func RecordCLBanNotHealthy(b *Backend)
func RecordCLBanOutputRootMismatch ¶
func RecordCLBanOutputRootMismatch(b *Backend)
func RecordCLBanOutputRootTimeout ¶
func RecordCLBanOutputRootTimeout(b *Backend)
func RecordCLBanUnexpectedBlockTags ¶
func RecordCLBanUnexpectedBlockTags(b *Backend)
func RecordCLConsensusHalted ¶
func RecordCLConsensusHalted(group *BackendGroup, halted bool)
RecordCLConsensusHalted updates the halted gauge for a group: 1 when halted, 0 otherwise. When halted is true it also increments the halt counter; the counter therefore rises once per halted consensus cycle, not once per transition into the halted state.
func RecordCLGroupLocalSafeBlock ¶
func RecordCLGroupLocalSafeBlock(group *BackendGroup, blockNumber hexutil.Uint64)
func RecordCLGroupPinL1 ¶
func RecordCLGroupPinL1(group *BackendGroup, pinBackend *Backend, blockNumber uint64)
func RecordCLNoPinCandidate ¶
func RecordCLNoPinCandidate(group *BackendGroup)
func RecordCLOutputRootDisagreement ¶
func RecordCLOutputRootDisagreement(b *Backend)
func RecordCLSyncStatusCacheHit ¶
func RecordCLSyncStatusCacheHit(group *BackendGroup)
func RecordCLSyncStatusCacheMiss ¶
func RecordCLSyncStatusCacheMiss(group *BackendGroup)
func RecordCacheError ¶
func RecordCacheError(method string)
func RecordCacheHit ¶
func RecordCacheHit(method string)
func RecordCacheMiss ¶
func RecordCacheMiss(method string)
func RecordGroupConsensusCount ¶
func RecordGroupConsensusCount(group *BackendGroup, count int)
func RecordGroupConsensusError ¶
func RecordGroupConsensusError(group *BackendGroup, label string, err error)
func RecordGroupConsensusFilteredCount ¶
func RecordGroupConsensusFilteredCount(group *BackendGroup, count int)
func RecordGroupConsensusFinalizedBlock ¶
func RecordGroupConsensusFinalizedBlock(group *BackendGroup, blockNumber hexutil.Uint64)
func RecordGroupConsensusHACLPinL1 ¶
func RecordGroupConsensusHACLPinL1(group *BackendGroup, leader string, l1Num uint64)
func RecordGroupConsensusHAFinalizedBlock ¶
func RecordGroupConsensusHAFinalizedBlock(group *BackendGroup, leader string, blockNumber hexutil.Uint64)
func RecordGroupConsensusHALatestBlock ¶
func RecordGroupConsensusHALatestBlock(group *BackendGroup, leader string, blockNumber hexutil.Uint64)
func RecordGroupConsensusHASafeBlock ¶
func RecordGroupConsensusHASafeBlock(group *BackendGroup, leader string, blockNumber hexutil.Uint64)
func RecordGroupConsensusHAServingLocal ¶
func RecordGroupConsensusHAServingLocal(group *BackendGroup, servingLocal bool)
func RecordGroupConsensusLatestBlock ¶
func RecordGroupConsensusLatestBlock(group *BackendGroup, blockNumber hexutil.Uint64)
func RecordGroupConsensusSafeBlock ¶
func RecordGroupConsensusSafeBlock(group *BackendGroup, blockNumber hexutil.Uint64)
func RecordGroupTotalCount ¶
func RecordGroupTotalCount(group *BackendGroup, count int)
func RecordHTTPRequestByMethodDuration ¶
RecordHTTPRequestByMethodDuration records an HTTP JSON-RPC request duration.
func RecordHealthyCandidates ¶
func RecordHealthyCandidates(b *BackendGroup, candidates int)
func RecordRPCCall ¶
func RecordRPCCall(backendName, method, statusCode, transport string)
RecordRPCCall records one client-initiated JSON-RPC call and the outcome the client received. Callers must pass a method name already bounded by Server.metricMethodName or WSProxier.metricMethodName — never a raw client-supplied method string, which is unbounded label cardinality.
func RecordRPCError ¶
func RecordRPCForward ¶
func RecordRPCNotification ¶
func RecordRPCNotification(backendName string)
RecordRPCNotification records one client-bound WS subscription notification.
func RecordRedisError ¶
func RecordRedisError(source string)
func RecordWSMessage ¶
func SetLogLevel ¶
func ValidateRPCReq ¶
Types ¶
type AliasRateLimitConfig ¶
type AliasRateLimitConfig struct {
BaseRate *int `toml:"base_rate"`
BaseInterval *TOMLDuration `toml:"base_interval"`
InfiniteRateLimit bool `toml:"infinite_rate_limit"`
MethodOverrides map[string]*AliasRateLimitMethodOverride `toml:"method_overrides"`
}
type AliasRateLimitMethodOverride ¶
type AliasRateLimitMethodOverride struct {
Limit *int `toml:"limit"`
Interval *TOMLDuration `toml:"interval"`
InfiniteRateLimit bool `toml:"infinite_rate_limit"`
}
type Backend ¶
type Backend struct {
Name string
ProbeWorker *ProbeWorker
// contains filtered or unexported fields
}
func NewBackend ¶
func (*Backend) ClearSlidingWindows ¶
func (b *Backend) ClearSlidingWindows()
func (*Backend) ForwardRPC ¶
func (b *Backend) ForwardRPC(ctx context.Context, res *RPCRes, id string, method string, params ...any) error
ForwardRPC makes a call directly to a backend and populate the response into `res`
func (*Backend) ForwardWithSource ¶
func (*Backend) IsDegraded ¶
IsDegraded checks if the backend is serving traffic in a degraded state (i.e. used as a last resource)
func (*Backend) IsHealthy ¶
IsHealthy checks if the backend is able to serve traffic, based on dynamic parameters
func (*Backend) IsProbeHealthy ¶
func (*Backend) Override ¶
func (b *Backend) Override(opts ...BackendOpt)
func (*Backend) SetProbeHealth ¶
type BackendConfig ¶
type BackendConfig struct {
Username string `toml:"username"`
Password string `toml:"password"`
RPCURL string `toml:"rpc_url"`
WSURL string `toml:"ws_url"`
WSPort int `toml:"ws_port"`
MaxRPS int `toml:"max_rps"`
MaxWSConns int `toml:"max_ws_conns"`
CAFile string `toml:"ca_file"`
ClientCertFile string `toml:"client_cert_file"`
ClientKeyFile string `toml:"client_key_file"`
StripTrailingXFF bool `toml:"strip_trailing_xff"`
Headers map[string]string `toml:"headers"`
ProbeFailureThreshold int `toml:"probe_failure_threshold"`
ProbeSuccessThreshold int `toml:"probe_success_threshold"`
ProbePeriodSeconds int `toml:"probe_period_seconds"`
ProbeTimeoutSeconds int `toml:"probe_timeout_seconds"`
ProbeURL string `toml:"probe_url"`
Weight int `toml:"weight"`
SkipIsSyncingCheck bool `toml:"skip_is_syncing_check"`
ResponseTimeoutMilliseconds int `toml:"response_timeout_milliseconds"`
MaxRetries *int `toml:"max_retries"`
SafeBlockDriftThreshold uint64 `toml:"safe_block_drift_threshold"`
FinalizedBlockDriftThreshold uint64 `toml:"finalized_block_drift_threshold"`
ConsensusSkipPeerCountCheck bool `toml:"consensus_skip_peer_count"`
ConsensusForcedCandidate bool `toml:"consensus_forced_candidate"`
ConsensusReceiptsTarget string `toml:"consensus_receipts_target"`
AllowedStatusCodes []int `toml:"allowed_status_codes"`
}
type BackendGroup ¶
type BackendGroup struct {
Name string
Backends []*Backend
WeightedRouting bool
Consensus *ConsensusPoller
FallbackBackends map[string]bool
// contains filtered or unexported fields
}
func (*BackendGroup) ExecuteMulticall ¶
func (bg *BackendGroup) ExecuteMulticall(ctx context.Context, rpcReqs []*RPCReq, source string) *BackendGroupRPCResponse
Note: rpcReqs should only contain 1 request of 'sendRawTransactions'
func (*BackendGroup) Fallbacks ¶
func (bg *BackendGroup) Fallbacks() []*Backend
func (*BackendGroup) Forward ¶
func (bg *BackendGroup) Forward(ctx context.Context, rpcReqs []*RPCReq, isBatch bool) ([]*RPCRes, string, error)
NOTE: BackendGroup Forward contains the log for balancing with consensus aware
func (*BackendGroup) ForwardRequestToBackendGroup ¶
func (bg *BackendGroup) ForwardRequestToBackendGroup( rpcReqs []*RPCReq, backends []*Backend, ctx context.Context, isBatch bool, source string, ) *BackendGroupRPCResponse
func (*BackendGroup) ForwardWithSource ¶
func (*BackendGroup) GetRoutingStrategy ¶
func (bg *BackendGroup) GetRoutingStrategy() RoutingStrategy
func (*BackendGroup) MulticallRequest ¶
func (*BackendGroup) OverwriteConsensusResponses ¶
func (bg *BackendGroup) OverwriteConsensusResponses(rpcReqs []*RPCReq, overriddenResponses []*indexedReqRes, rewrittenReqs []*RPCReq) ([]*RPCReq, []*indexedReqRes)
func (*BackendGroup) OverwriteNonConsensusRequests ¶
func (bg *BackendGroup) OverwriteNonConsensusRequests(rpcReqs []*RPCReq, overriddenResponses []*indexedReqRes) ([]*RPCReq, []*indexedReqRes)
func (*BackendGroup) Primaries ¶
func (bg *BackendGroup) Primaries() []*Backend
func (*BackendGroup) ProcessMulticallResponses ¶
func (bg *BackendGroup) ProcessMulticallResponses(ch chan *multicallTuple, ctx context.Context) (resp *BackendGroupRPCResponse, unserviceable bool)
func (*BackendGroup) Shutdown ¶
func (bg *BackendGroup) Shutdown()
type BackendGroupConfig ¶
type BackendGroupConfig struct {
Backends []string `toml:"backends"`
WeightedRouting bool `toml:"weighted_routing"`
RoutingStrategy RoutingStrategy `toml:"routing_strategy"`
MulticallRPCErrorCheck bool `toml:"multicall_rpc_error_check"`
/*
Deprecated: Use routing_strategy config to create a consensus_aware proxyd instance
*/
ConsensusAware bool `toml:"consensus_aware"`
ConsensusAsyncHandler string `toml:"consensus_handler"`
ConsensusPollerInterval TOMLDuration `toml:"consensus_poller_interval"`
ConsensusBanPeriod TOMLDuration `toml:"consensus_ban_period"`
ConsensusMaxUpdateThreshold TOMLDuration `toml:"consensus_max_update_threshold"`
ConsensusMaxBlockLag uint64 `toml:"consensus_max_block_lag"`
ConsensusMaxBlockRange uint64 `toml:"consensus_max_block_range"`
ConsensusMinPeerCount int `toml:"consensus_min_peer_count"`
// Will set Max Block Range for non-consensus eth_getLogs and eth_newFilter
// Will override consensus_max_block_range if consensus_max_block range is also set
MaxBlockRange uint64 `toml:"max_block_range"`
// consensus_cl_sync_threshold is the maximum number of L1 blocks a CL (op-node) backend
// may lag behind the network's head_l1 before it is considered out of sync and excluded
// from the consensus group. Computed as head_l1.number - current_l1.number.
// Default: 10 (~2 minutes at 12s L1 block time). Only applies when
// routing_strategy = "consensus_aware_consensus_layer".
ConsensusCLSyncThreshold uint64 `toml:"consensus_cl_sync_threshold"`
// consensus_cl_head_l1_max_age is the maximum age of a CL backend's head_l1 timestamp
// before the backend is considered stale and excluded from the consensus group.
// A backend whose L1 head is older than this duration has likely lost its L1 connection.
// Default: 5m. Set to 0 to disable the age check. Only applies when
// routing_strategy = "consensus_aware_consensus_layer".
ConsensusCLHeadL1MaxAge TOMLDuration `toml:"consensus_cl_head_l1_max_age"`
// consensus_cl_output_root_ban_threshold is the number of consecutive per-cycle
// optimism_outputAtBlock timeouts before a CL backend is banned. The counter resets
// to 0 on any successful fetch. Default: 3. Only applies when
// routing_strategy = "consensus_aware_consensus_layer".
ConsensusCLOutputRootBanThreshold uint `toml:"consensus_cl_output_root_ban_threshold"`
ConsensusHA bool `toml:"consensus_ha"`
ConsensusHAHeartbeatInterval TOMLDuration `toml:"consensus_ha_heartbeat_interval"`
ConsensusHALockPeriod TOMLDuration `toml:"consensus_ha_lock_period"`
ConsensusHARedis RedisConfig `toml:"consensus_ha_redis"`
// consensus_ha_serve_local_when_stale serves this instance's locally polled
// consensus state when its copy of the shared HA state has not been refreshed
// for longer than consensus_ha_lock_period (e.g. it cannot reach Redis),
// instead of the frozen shared state. Instances may then disagree on the head.
// Default: false.
ConsensusHAServeLocalWhenStale bool `toml:"consensus_ha_serve_local_when_stale"`
Fallbacks []string `toml:"fallbacks"`
}
func (*BackendGroupConfig) ValidateRoutingStrategy ¶
func (b *BackendGroupConfig) ValidateRoutingStrategy(bgName string) bool
type BackendGroupRPCResponse ¶
type BackendGroupsConfig ¶
type BackendGroupsConfig map[string]*BackendGroupConfig
type BackendOpt ¶
type BackendOpt func(b *Backend)
func WithAllowedStatusCodes ¶
func WithAllowedStatusCodes(allowedStatusCodes []int) BackendOpt
func WithBasicAuth ¶
func WithBasicAuth(username, password string) BackendOpt
func WithConsensusForcedCandidate ¶
func WithConsensusForcedCandidate(forcedCandidate bool) BackendOpt
func WithConsensusReceiptTarget ¶
func WithConsensusReceiptTarget(receiptsTarget string) BackendOpt
func WithConsensusSkipPeerCountCheck ¶
func WithConsensusSkipPeerCountCheck(skipPeerCountCheck bool) BackendOpt
func WithFinalizedBlockDriftThreshold ¶
func WithFinalizedBlockDriftThreshold(finalizedBlockDriftThreshold uint64) BackendOpt
func WithHeaders ¶
func WithHeaders(headers map[string]string) BackendOpt
func WithIntermittentNetworkErrorSlidingWindow ¶
func WithIntermittentNetworkErrorSlidingWindow(sw *sw.AvgSlidingWindow) BackendOpt
func WithMaxDegradedLatencyThreshold ¶
func WithMaxDegradedLatencyThreshold(maxDegradedLatencyThreshold time.Duration) BackendOpt
func WithMaxErrorRateThreshold ¶
func WithMaxErrorRateThreshold(maxErrorRateThreshold float64) BackendOpt
func WithMaxLatencyThreshold ¶
func WithMaxLatencyThreshold(maxLatencyThreshold time.Duration) BackendOpt
func WithMaxRPS ¶
func WithMaxRPS(maxRPS int) BackendOpt
func WithMaxResponseSize ¶
func WithMaxResponseSize(size int64) BackendOpt
func WithMaxRetries ¶
func WithMaxRetries(retries int) BackendOpt
func WithMaxWSConns ¶
func WithMaxWSConns(maxConns int) BackendOpt
func WithOutOfServiceDuration ¶
func WithOutOfServiceDuration(interval time.Duration) BackendOpt
func WithProxydIP ¶
func WithProxydIP(ip string) BackendOpt
func WithSafeBlockDriftThreshold ¶
func WithSafeBlockDriftThreshold(safeBlockDriftThreshold uint64) BackendOpt
func WithSkipIsSyncingCheck ¶
func WithSkipIsSyncingCheck(skipIsSyncingCheck bool) BackendOpt
func WithStrippedTrailingXFF ¶
func WithStrippedTrailingXFF() BackendOpt
func WithTLSConfig ¶
func WithTLSConfig(tlsConfig *tls.Config) BackendOpt
func WithTimeout ¶
func WithTimeout(timeout time.Duration) BackendOpt
func WithWeight ¶
func WithWeight(weight int) BackendOpt
type BackendOptions ¶
type BackendOptions struct {
// Deprecated: Use ResponseTimeoutMilliseconds instead. Note this field will be overridden if `ResponseTimeoutMilliseconds` is also set.
ResponseTimeoutSeconds int `toml:"response_timeout_seconds"`
ResponseTimeoutMilliseconds int `toml:"response_timeout_milliseconds"`
MaxResponseSizeBytes int64 `toml:"max_response_size_bytes"`
MaxRetries int `toml:"max_retries"`
OutOfServiceSeconds int `toml:"out_of_service_seconds"`
MaxDegradedLatencyThreshold TOMLDuration `toml:"max_degraded_latency_threshold"`
MaxLatencyThreshold TOMLDuration `toml:"max_latency_threshold"`
MaxErrorRateThreshold float64 `toml:"max_error_rate_threshold"`
}
type BackendsConfig ¶
type BackendsConfig map[string]*BackendConfig
type BatchConfig ¶
type BlockHashOrNumberParameter ¶
type BlockHashOrNumberParameter struct {
BlockHash *common.Hash `json:"blockHash"`
BlockNumber *rpc.BlockNumber `json:"blockNumber"`
}
BlockHashOrNumberParameter is a non-conventional wrapper used by alchemy_getTransactionReceipts
type CacheConfig ¶
type CacheConfig struct {
Enabled bool `toml:"enabled"`
TTL TOMLDuration `toml:"ttl"`
}
type Config ¶
type Config struct {
WSBackendGroup string `toml:"ws_backend_group"`
Server ServerConfig `toml:"server"`
Cache CacheConfig `toml:"cache"`
Redis RedisConfig `toml:"redis"`
Metrics MetricsConfig `toml:"metrics"`
RateLimit RateLimitConfig `toml:"rate_limit"`
BackendOptions BackendOptions `toml:"backend"`
Backends BackendsConfig `toml:"backends"`
BatchConfig BatchConfig `toml:"batch"`
Authentication map[string]string `toml:"authentication"`
BackendGroups BackendGroupsConfig `toml:"backend_groups"`
RPCMethodMappings map[string]string `toml:"rpc_method_mappings"`
WSMethodWhitelist []string `toml:"ws_method_whitelist"`
WhitelistErrorMessage string `toml:"whitelist_error_message"`
SenderRateLimit SenderRateLimitConfig `toml:"sender_rate_limit"`
InteropValidationConfig InteropValidationConfig `toml:"interop_validation"`
TxValidationMiddlewareConfig TxValidationMiddlewareConfig `toml:"tx_validation_middleware"`
TxMonitor TxMonitorConfig `toml:"tx_monitor"`
}
type ConsensusAsyncHandler ¶
type ConsensusAsyncHandler interface {
Init()
Shutdown()
}
ConsensusAsyncHandler controls the asynchronous polling mechanism, interval and shutdown
func NewNoopAsyncHandler ¶
func NewNoopAsyncHandler() ConsensusAsyncHandler
func NewPollerAsyncHandler ¶
func NewPollerAsyncHandler(ctx context.Context, cp *ConsensusPoller) ConsensusAsyncHandler
type ConsensusGetReceiptsResult ¶
type ConsensusGetReceiptsResult struct {
Method string `json:"method"`
Result interface{} `json:"result"`
}
type ConsensusOpt ¶
type ConsensusOpt func(cp *ConsensusPoller)
func WithAsyncHandler ¶
func WithAsyncHandler(asyncHandler ConsensusAsyncHandler) ConsensusOpt
func WithBanPeriod ¶
func WithBanPeriod(banPeriod time.Duration) ConsensusOpt
func WithCLConsensusMode ¶
func WithCLConsensusMode() ConsensusOpt
WithCLConsensusMode enables CL (op-node / consensus layer) consensus mode.
In this mode the poller queries optimism_syncStatus and optimism_outputAtBlock instead of eth_getBlockByNumber, and serves optimism_syncStatus responses from a cached pin backend (the consensus group member with the lowest current_l1 derivation position) rather than rewriting individual fields.
Output root verification: each poll cycle the poller calls optimism_outputAtBlock at the consensus safe block on every candidate backend. A backend whose output root disagrees with a strict majority is banned. If there is no majority (a tie or N-way split), the disagreement is unresolvable and consensus halts: the served block height and the cached optimism_syncStatus body stay frozen at the last-agreed value, while the served group is emptied so general RPCs fail closed rather than routing to a backend on an uncertain fork. Backends are not persistently banned, so consensus auto-recovers as soon as a majority returns. This catches derivation divergences between heterogeneous CL clients (e.g. op-node vs kona-node) before incorrect data reaches consumers.
Any number of backends is permitted, including even/2-node cross-client groups: a no-majority disagreement halts rather than being resolved by eviction.
func WithCLHeadL1MaxAge ¶
func WithCLHeadL1MaxAge(maxAge time.Duration) ConsensusOpt
WithCLHeadL1MaxAge sets the maximum age of the L1 head timestamp before a CL backend is considered stale.
func WithCLOutputRootBanThreshold ¶
func WithCLOutputRootBanThreshold(threshold uint) ConsensusOpt
WithCLOutputRootBanThreshold sets the number of consecutive per-cycle optimism_outputAtBlock timeouts before a CL backend is banned.
func WithCLSyncThreshold ¶
func WithCLSyncThreshold(threshold uint64) ConsensusOpt
WithCLSyncThreshold sets the maximum tolerated L1 block lag before a CL backend is considered out of sync.
func WithListener ¶
func WithListener(listener OnConsensusBroken) ConsensusOpt
func WithMaxBlockLag ¶
func WithMaxBlockLag(maxBlockLag uint64) ConsensusOpt
func WithMaxBlockRange ¶
func WithMaxBlockRange(maxBlockRange uint64) ConsensusOpt
func WithMaxUpdateThreshold ¶
func WithMaxUpdateThreshold(maxUpdateThreshold time.Duration) ConsensusOpt
func WithMinPeerCount ¶
func WithMinPeerCount(minPeerCount uint64) ConsensusOpt
func WithPollerInterval ¶
func WithPollerInterval(interval time.Duration) ConsensusOpt
func WithTracker ¶
func WithTracker(tracker ConsensusTracker) ConsensusOpt
type ConsensusPoller ¶
type ConsensusPoller struct {
// contains filtered or unexported fields
}
ConsensusPoller checks the consensus state for each member of a BackendGroup resolves the highest common block for multiple nodes, and reconciles the consensus in case of block hash divergence to minimize re-orgs
func NewConsensusPoller ¶
func NewConsensusPoller(bg *BackendGroup, opts ...ConsensusOpt) *ConsensusPoller
func (*ConsensusPoller) AddListener ¶
func (cp *ConsensusPoller) AddListener(listener OnConsensusBroken)
func (*ConsensusPoller) Ban ¶
func (cp *ConsensusPoller) Ban(be *Backend)
Ban bans a specific backend
func (*ConsensusPoller) BannedUntil ¶
func (cp *ConsensusPoller) BannedUntil(be *Backend) time.Time
IsBanned checks if a specific backend is banned
func (*ConsensusPoller) ClearListeners ¶
func (cp *ConsensusPoller) ClearListeners()
func (*ConsensusPoller) FilterCandidates ¶
func (cp *ConsensusPoller) FilterCandidates(backends []*Backend) map[*Backend]*backendState
filterCandidates find out what backends are the candidates to be in the consensus group and create a copy of current their state
Note: exclusion here is a per-cycle soft filter — a backend can be excluded this cycle and pass next cycle with no penalty, and it continues to be polled via UpdateBackend. This is distinct from a ban, which is a time-bounded penalty (default 5 min) that stops all polling of the backend and resets its block state.
a candidate is a serving node within the following conditions:
- not banned
- healthy (network latency and error rate)
- with minimum peer count
- in sync
- updated recently
- not lagging latest block
- (CL mode) finalized and local_safe blocks are at or above the current group consensus, preventing a restarting backend from dragging consensus backward
func (*ConsensusPoller) GetBackendState ¶
func (cp *ConsensusPoller) GetBackendState(be *Backend) *backendState
GetBackendState creates a copy of backend state so that the caller can use it without locking
func (*ConsensusPoller) GetConsensusGroup ¶
func (cp *ConsensusPoller) GetConsensusGroup() []*Backend
GetConsensusGroup returns the backend members that are agreeing in a consensus
func (*ConsensusPoller) GetConsensusSyncStatusBody ¶
func (cp *ConsensusPoller) GetConsensusSyncStatusBody() json.RawMessage
GetConsensusSyncStatusBody returns the cached optimism_syncStatus response body from the current pin backend. Returns nil if no poll cycle has completed yet.
func (*ConsensusPoller) GetFinalizedBlockNumber ¶
func (cp *ConsensusPoller) GetFinalizedBlockNumber() hexutil.Uint64
GetFinalizedBlockNumber returns the `finalized` agreed block number in a consensus
func (*ConsensusPoller) GetLastUpdate ¶
func (cp *ConsensusPoller) GetLastUpdate(be *Backend) time.Time
func (*ConsensusPoller) GetLatestBlockNumber ¶
func (cp *ConsensusPoller) GetLatestBlockNumber() hexutil.Uint64
GetLatestBlockNumber returns the `latest` agreed block number in a consensus
func (*ConsensusPoller) GetLocalSafeBlockNumber ¶
func (cp *ConsensusPoller) GetLocalSafeBlockNumber() hexutil.Uint64
GetLocalSafeBlockNumber returns the `local_safe` agreed block number in a consensus (CL mode only)
func (*ConsensusPoller) GetSafeBlockNumber ¶
func (cp *ConsensusPoller) GetSafeBlockNumber() hexutil.Uint64
GetSafeBlockNumber returns the `safe` agreed block number in a consensus
func (*ConsensusPoller) IsBanned ¶
func (cp *ConsensusPoller) IsBanned(be *Backend) bool
IsBanned checks if a specific backend is banned
func (*ConsensusPoller) IsConsensusLayer ¶
func (cp *ConsensusPoller) IsConsensusLayer() bool
IsConsensusLayer returns true if this poller is operating in CL (op-node) mode
func (*ConsensusPoller) Shutdown ¶
func (cp *ConsensusPoller) Shutdown()
func (*ConsensusPoller) Unban ¶
func (cp *ConsensusPoller) Unban(be *Backend)
Unban removes any bans from the backends
func (*ConsensusPoller) UpdateBackend ¶
func (cp *ConsensusPoller) UpdateBackend(ctx context.Context, be *Backend)
UpdateBackend refreshes the consensus state of a single backend
func (*ConsensusPoller) UpdateBackendGroupConsensus ¶
func (cp *ConsensusPoller) UpdateBackendGroupConsensus(ctx context.Context)
UpdateBackendGroupConsensus resolves the current group consensus based on the state of the backends
type ConsensusTracker ¶
type ConsensusTracker interface {
GetState() ConsensusTrackerState
SetState(state ConsensusTrackerState)
GetCLSyncBody() (body json.RawMessage, lastServedL1Num uint64)
SetCLSyncBody(body json.RawMessage, l1Num uint64)
}
ConsensusTracker abstracts how we store and retrieve the current consensus allowing it to be stored locally in-memory or in a shared Redis cluster
func NewInMemoryConsensusTracker ¶
func NewInMemoryConsensusTracker() ConsensusTracker
func NewRedisConsensusTracker ¶
func NewRedisConsensusTracker(ctx context.Context, redisClient redis.UniversalClient, bg *BackendGroup, namespace string, opts ...RedisConsensusTrackerOpt) ConsensusTracker
type ConsensusTrackerState ¶
type ConsensusTrackerState struct {
Latest hexutil.Uint64 `json:"latest"`
Safe hexutil.Uint64 `json:"safe"`
Finalized hexutil.Uint64 `json:"finalized"`
LocalSafe hexutil.Uint64 `json:"local_safe"`
CLSyncBody json.RawMessage `json:"cl_sync_body,omitempty"`
CLL1Num uint64 `json:"cl_l1_num,omitempty"`
}
ConsensusTrackerState holds the full consensus state in one snapshot. Adding a new field only requires changing this struct and update().
type ELBlockState ¶
type ELBlockState struct {
LatestBlockNumber hexutil.Uint64
LatestBlockHash string
SafeBlockNumber hexutil.Uint64
FinalizedBlockNumber hexutil.Uint64
}
ELBlockState holds the block numbers and hashes fetched from an EL backend in a single polling cycle.
type FallbackRateLimiter ¶
type FallbackRateLimiter struct {
// contains filtered or unexported fields
}
FallbackRateLimiter is a combination of a primary and secondary rate limiter. If the primary rate limiter fails, due to an unexpected error, the secondary rate limiter will be used. This is useful to reduce reliance on a single Redis instance for rate limiting. If both fail, the request is not let through.
type FrontendRateLimiter ¶
type FrontendRateLimiter interface {
// Take consumes a key, and a maximum number of requests
// per time interval. It returns a boolean denoting if
// the limit could be taken, or an error if a failure
// occurred in the backing rate limit implementation.
//
// No error will be returned if the limit could not be taken
// as a result of the requestor being over the limit.
Take(ctx context.Context, key string) (bool, error)
}
func NewFallbackRateLimiter ¶
func NewFallbackRateLimiter(primary FrontendRateLimiter, secondary FrontendRateLimiter) FrontendRateLimiter
func NewMemoryFrontendRateLimit ¶
func NewMemoryFrontendRateLimit(dur time.Duration, max int) FrontendRateLimiter
func NewRedisFrontendRateLimiter ¶
func NewRedisFrontendRateLimiter(r redis.UniversalClient, dur time.Duration, max int, prefix string) FrontendRateLimiter
type InMemoryConsensusTracker ¶
type InMemoryConsensusTracker struct {
// contains filtered or unexported fields
}
InMemoryConsensusTracker store and retrieve in memory, async-safe
func (*InMemoryConsensusTracker) Behind ¶
func (ct *InMemoryConsensusTracker) Behind(other *InMemoryConsensusTracker) bool
func (*InMemoryConsensusTracker) GetCLSyncBody ¶
func (ct *InMemoryConsensusTracker) GetCLSyncBody() (json.RawMessage, uint64)
func (*InMemoryConsensusTracker) GetState ¶
func (ct *InMemoryConsensusTracker) GetState() ConsensusTrackerState
func (*InMemoryConsensusTracker) SetCLSyncBody ¶
func (ct *InMemoryConsensusTracker) SetCLSyncBody(body json.RawMessage, l1Num uint64)
func (*InMemoryConsensusTracker) SetState ¶
func (ct *InMemoryConsensusTracker) SetState(state ConsensusTrackerState)
func (*InMemoryConsensusTracker) UpdatedAt ¶
func (ct *InMemoryConsensusTracker) UpdatedAt() time.Time
UpdatedAt returns when the state was last written by update.
func (*InMemoryConsensusTracker) Valid ¶
func (ct *InMemoryConsensusTracker) Valid() bool
type InteropStrategy ¶
type InteropValidationConfig ¶
type InteropValidationConfig struct {
Urls []string `toml:"urls"`
Strategy InteropValidationStrategy `toml:"strategy"`
ChainID uint64 `toml:"chain_id"`
LoadBalancingUnhealthinessTimeout time.Duration `toml:"load_balancing_unhealthiness_timeout"`
ReqSizeLimit int `toml:"req_size_limit"`
AccessListSizeLimit int `toml:"access_list_size_limit"`
RateLimit SenderRateLimitConfig `toml:"sender_rate_limit"`
// MinResponses is the quorum required by the agreement strategy: the number
// of definitive verdicts that must be collected before deciding. Defaults to
// len(Urls) (unanimity) when unset.
MinResponses int `toml:"min_responses"`
}
type InteropValidationStrategy ¶
type InteropValidationStrategy string
const ( EmptyStrategy InteropValidationStrategy = "" FirstFilterStrategy InteropValidationStrategy = "first-filter" MulticallStrategy InteropValidationStrategy = "multicall" HealthAwareLoadBalancingStrategy InteropValidationStrategy = "health-aware-load-balancing" AgreementStrategy InteropValidationStrategy = "agreement" // LegacyFirstSupervisorStrategy is the pre-rename name for FirstFilterStrategy, // accepted for config backwards compatibility. LegacyFirstSupervisorStrategy InteropValidationStrategy = "first-supervisor" )
type LimitedHTTPClient ¶
type LimitedReader ¶
A LimitedReader reads from R but limits the amount of data returned to just N bytes. Each call to Read updates N to reflect the new amount remaining. Unlike the standard library version, Read returns ErrLimitReaderOverLimit when N <= 0.
type MemoryFrontendRateLimiter ¶
type MemoryFrontendRateLimiter struct {
// contains filtered or unexported fields
}
MemoryFrontendRateLimiter is a rate limiter that stores all rate limiting information in local memory. It works by storing a limitedKeys struct that references the truncated timestamp at which the struct was created. If the current truncated timestamp doesn't match what's referenced, the limit is reset. Otherwise, values in a map are incremented to represent the limit. This will never return an error.
type MemoryPendingStore ¶
type MemoryPendingStore struct {
// contains filtered or unexported fields
}
func NewMemoryPendingStore ¶
func NewMemoryPendingStore(maxPending int) *MemoryPendingStore
func (*MemoryPendingStore) Add ¶
func (s *MemoryPendingStore) Add(e txmonEntry) bool
Add records a pending tx. Returns false when the store is at capacity. Re-adding a hash already present keeps whichever entry has the earlier IngestedAt: that is the user-perceived submission time, and because IngestedAt is stamped at request ingress, a later duplicate submission may be observed (enqueued) before an earlier one. Any already-set SubblockAt on the retained entry is preserved.
func (*MemoryPendingStore) ExpireBefore ¶
func (s *MemoryPendingStore) ExpireBefore(cutoff time.Time) []txmonEntry
func (*MemoryPendingStore) Len ¶
func (s *MemoryPendingStore) Len() int
func (*MemoryPendingStore) MarkSubblock ¶
MarkSubblock stamps the first subblock sighting. Returns the updated entry and true only on the first mark of a known hash.
func (*MemoryPendingStore) MatchAndRemove ¶
func (s *MemoryPendingStore) MatchAndRemove(hashes []common.Hash) []txmonEntry
type MethodMappingsConfig ¶
type MetricsConfig ¶
type NoopAsyncHandler ¶
type NoopAsyncHandler struct{}
NoopAsyncHandler allows fine control updating the consensus
func (*NoopAsyncHandler) Init ¶
func (ah *NoopAsyncHandler) Init()
func (*NoopAsyncHandler) Shutdown ¶
func (ah *NoopAsyncHandler) Shutdown()
type OnConsensusBroken ¶
type OnConsensusBroken func()
type PendingStore ¶
type PendingStore interface {
Add(e txmonEntry) bool
MatchAndRemove(hashes []common.Hash) []txmonEntry
MarkSubblock(h common.Hash, at time.Time) (txmonEntry, bool)
ExpireBefore(cutoff time.Time) []txmonEntry
Len() int
}
PendingStore tracks pending transactions. The interface is batch-shaped so a future Redis implementation can pipeline one multi-key op per block.
type PollerAsyncHandler ¶
type PollerAsyncHandler struct {
// contains filtered or unexported fields
}
PollerAsyncHandler asynchronously updates each individual backend and the group consensus
func (*PollerAsyncHandler) Init ¶
func (ah *PollerAsyncHandler) Init()
func (*PollerAsyncHandler) Shutdown ¶
func (ah *PollerAsyncHandler) Shutdown()
type ProbeWorker ¶
type ProbeWorker struct {
// contains filtered or unexported fields
}
func NewProbeWorker ¶
func (*ProbeWorker) Start ¶
func (w *ProbeWorker) Start()
func (*ProbeWorker) Stop ¶
func (w *ProbeWorker) Stop()
type RPCErr ¶
type RPCErr struct {
Code int `json:"code"`
Message string `json:"message"`
Data json.RawMessage `json:"data,omitempty"`
HTTPErrorCode int `json:"-"`
}
func ErrInvalidParams ¶
func ErrInvalidRequest ¶
func ParseInteropError ¶
type RPCMethodHandler ¶
type RPCReq ¶
type RPCReq struct {
JSONRPC string `json:"jsonrpc"`
Method string `json:"method"`
Params json.RawMessage `json:"params"`
ID json.RawMessage `json:"id"`
}
func ParseRPCReq ¶
type RPCRes ¶
type RPCRes struct {
JSONRPC string
Result interface{}
Error *RPCErr
ID json.RawMessage
// contains filtered or unexported fields
}
func NewRPCErrorRes ¶
func NewRPCErrorRes(id json.RawMessage, err error) *RPCRes
func NewRPCRes ¶
func NewRPCRes(id json.RawMessage, result interface{}) *RPCRes
func OverrideResponses ¶
func (*RPCRes) MarshalJSON ¶
type RateLimitConfig ¶
type RateLimitConfig struct {
UseRedis bool `toml:"use_redis"`
UseAuthAlias bool `toml:"use_auth_alias"`
BaseRate int `toml:"base_rate"`
BaseInterval TOMLDuration `toml:"base_interval"`
ExemptOrigins []string `toml:"exempt_origins"`
ExemptUserAgents []string `toml:"exempt_user_agents"`
ErrorMessage string `toml:"error_message"`
MethodOverrides map[string]*RateLimitMethodOverride `toml:"method_overrides"`
IPHeaderOverride string `toml:"ip_header_override"`
AliasOverrides map[string]*AliasRateLimitConfig `toml:"alias_overrides"`
}
type RateLimitMethodOverride ¶
type RateLimitMethodOverride struct {
Limit int `toml:"limit"`
Interval TOMLDuration `toml:"interval"`
Global bool `toml:"global"`
}
type RedisConfig ¶
type RedisConfig struct {
// If `redis_cluster = true`, you can specify url string for multi-node cluster:
// "redis://<user>:<password>@<host>:<port>?addr=<host2>:<port2>&addr=<host3>:<port3>"
// OR "rediss://<user>:<password>@<host>:<port>?addr=<host2>:<port2>&addr=<host3>:<port3>"
//
// Otherwise, it is also possible to specify single url for Redis cluster with proxy support.
URL string `toml:"url"`
Namespace string `toml:"namespace"`
ReadURL string `toml:"read_url"`
FallbackToMemory bool `toml:"fallback_to_memory"`
RedisCluster bool `toml:"redis_cluster"`
}
type RedisConsensusTracker ¶
type RedisConsensusTracker struct {
// contains filtered or unexported fields
}
RedisConsensusTracker store and retrieve in a shared Redis cluster, with leader election
func (*RedisConsensusTracker) GetCLSyncBody ¶
func (ct *RedisConsensusTracker) GetCLSyncBody() (json.RawMessage, uint64)
func (*RedisConsensusTracker) GetState ¶
func (ct *RedisConsensusTracker) GetState() ConsensusTrackerState
func (*RedisConsensusTracker) Init ¶
func (ct *RedisConsensusTracker) Init()
func (*RedisConsensusTracker) SetCLSyncBody ¶
func (ct *RedisConsensusTracker) SetCLSyncBody(body json.RawMessage, l1Num uint64)
func (*RedisConsensusTracker) SetState ¶
func (ct *RedisConsensusTracker) SetState(state ConsensusTrackerState)
type RedisConsensusTrackerOpt ¶
type RedisConsensusTrackerOpt func(cp *RedisConsensusTracker)
func WithHeartbeatInterval ¶
func WithHeartbeatInterval(heartbeatInterval time.Duration) RedisConsensusTrackerOpt
func WithLockPeriod ¶
func WithLockPeriod(lockPeriod time.Duration) RedisConsensusTrackerOpt
func WithServeLocalWhenStale ¶
func WithServeLocalWhenStale(serveLocalWhenStale bool) RedisConsensusTrackerOpt
type RedisFrontendRateLimiter ¶
type RedisFrontendRateLimiter struct {
// contains filtered or unexported fields
}
RedisFrontendRateLimiter is a rate limiter that stores data in Redis. It uses the basic rate limiter pattern described on the Redis best practices website: https://redis.com/redis-best-practices/basic-rate-limiting/.
type RewriteContext ¶
type RewriteContext struct {
// contains filtered or unexported fields
}
type RewriteResult ¶
type RewriteResult uint8
const ( // RewriteNone means request should be forwarded as-is RewriteNone RewriteResult = iota // RewriteOverrideError means there was an error attempting to rewrite RewriteOverrideError // RewriteOverrideRequest means the modified request should be forwarded to the backend RewriteOverrideRequest // RewriteOverrideResponse means to skip calling the backend and serve the overridden response RewriteOverrideResponse )
func RewriteRequest ¶
func RewriteRequest(rctx RewriteContext, req *RPCReq, res *RPCRes) (RewriteResult, error)
RewriteRequest modifies the request object to comply with the rewrite context before the method has been called at the backend it returns false if nothing was changed
func RewriteResponse ¶
func RewriteResponse(rctx RewriteContext, req *RPCReq, res *RPCRes) (RewriteResult, error)
RewriteResponse synthesizes responses from consensus state before the backend is called. This is EL-only: CL mode intercepts optimism_syncStatus entirely in OverwriteConsensusResponses and serves it from the pin-backend cache, so no rewriting is needed here.
func RewriteTags ¶
func RewriteTags(rctx RewriteContext, req *RPCReq, res *RPCRes) (RewriteResult, error)
RewriteTags modifies the request and the response based on block tags
type RoutingStrategy ¶
type RoutingStrategy string
const ( ConsensusAwareRoutingStrategy RoutingStrategy = "consensus_aware" ConsensusAwareCLRoutingStrategy RoutingStrategy = "consensus_aware_consensus_layer" MulticallRoutingStrategy RoutingStrategy = "multicall" FallbackRoutingStrategy RoutingStrategy = "fallback" )
type SenderRateLimitConfig ¶
type SenderRateLimitConfig struct {
Enabled bool
Interval TOMLDuration
Limit int
AllowedChainIds []*big.Int `toml:"allowed_chain_ids"`
}
SenderRateLimitConfig configures the sender-based rate limiter for eth_sendRawTransaction requests. To enable pre-eip155 transactions, add '0' to allowed_chain_ids.
type Server ¶
type Server struct {
BackendGroups map[string]*BackendGroup
// contains filtered or unexported fields
}
func NewServer ¶
func NewServer( backendGroups map[string]*BackendGroup, wsBackendGroup *BackendGroup, wsMethodWhitelist *StringSet, rpcMethodMappings map[string]string, maxBodySize int64, authenticatedPaths map[string]string, publicAccess bool, timeout time.Duration, maxUpstreamBatchSize int, enableServedByHeader bool, cache RPCCache, rateLimitConfig RateLimitConfig, senderRateLimitConfig SenderRateLimitConfig, interopSenderRateLimitConfig SenderRateLimitConfig, enableRequestLog bool, maxRequestBodyLogLen int, maxBatchSize int, limiterFactory limiterFactoryFunc, interopValidatingConfig InteropValidationConfig, interopStrategy InteropStrategy, enableTxHashLogging bool, limExemptKeys []string, txValidationConfig TxValidationMiddlewareConfig, gracefulShutdownDuration time.Duration, maxConcurrentWSRPCs int64, ) (*Server, error)
func (*Server) HandleHealthz ¶
func (s *Server) HandleHealthz(w http.ResponseWriter, r *http.Request)
type ServerConfig ¶
type ServerConfig struct {
RPCHost string `toml:"rpc_host"`
RPCPort int `toml:"rpc_port"`
WSHost string `toml:"ws_host"`
WSPort int `toml:"ws_port"`
MaxBodySizeBytes int64 `toml:"max_body_size_bytes"`
MaxConcurrentRPCs int64 `toml:"max_concurrent_rpcs"`
// MaxConcurrentWSRPCs limits concurrent mapped RPCs handled over a single WS connection.
MaxConcurrentWSRPCs int64 `toml:"max_concurrent_ws_rpcs"`
// DisableConcurrentRequestSemaphore=true allows unlimited concurrent RPC requests. This takes precedence over MaxConcurrentRPCs.
DisableConcurrentRequestSemaphore bool `toml:"disable_concurrent_request_semaphore"`
LogLevel string `toml:"log_level"`
// TimeoutSeconds specifies the maximum time spent serving an HTTP request. Note that isn't used for websocket connections
TimeoutSeconds int `toml:"timeout_seconds"`
MaxUpstreamBatchSize int `toml:"max_upstream_batch_size"`
EnableRequestLog bool `toml:"enable_request_log"`
MaxRequestBodyLogLen int `toml:"max_request_body_log_len"`
EnablePprof bool `toml:"enable_pprof"`
EnableXServedByHeader bool `toml:"enable_served_by_header"`
AllowAllOrigins bool `toml:"allow_all_origins"`
PublicAccess bool `toml:"public_access"`
EnableTxHashLogging bool `toml:"enable_tx_hash_logging"`
// GracefulShutdownSeconds is the duration to wait during drain before shutting down.
// Defaults to 0 (no drain delay). Set to a positive value to enable graceful drain.
GracefulShutdownSeconds int `toml:"graceful_shutdown_seconds"`
}
type StaticMethodHandler ¶
type StaticMethodHandler struct {
// contains filtered or unexported fields
}
func (*StaticMethodHandler) GetRPCMethod ¶
func (*StaticMethodHandler) PutRPCMethod ¶
type StringSet ¶
type StringSet struct {
// contains filtered or unexported fields
}
func NewStringSet ¶
func NewStringSet() *StringSet
func NewStringSetFromStrings ¶
type TOMLDuration ¶
func (*TOMLDuration) UnmarshalText ¶
func (t *TOMLDuration) UnmarshalText(b []byte) error
type TransactionWithFrom ¶
type TransactionWithFrom map[string]interface{}
TransactionWithFrom represents a transaction with the sender address included. We use a map instead of types.Transaction because go-ethereum's Transaction type does not include the "from" field in its JSON marshaling - the sender address must be derived from the signature using ecrecover. This type allows us to include "from" at the same level as other transaction fields for the validation service.
type TxFilter ¶
type TxFilter struct {
// contains filtered or unexported fields
}
TxFilter is the single chokepoint for transaction-submission filtering. It owns an ordered list of modules and runs them in order, short-circuiting on the first rejection (logical AND).
func NewTxFilter ¶
func NewTxFilter(decode txDecodeFunc, modules ...TxFilterModule) *TxFilter
func (*TxFilter) Apply ¶
func (f *TxFilter) Apply(ctx context.Context, sub *TxSubmission) error
Apply runs every module in order, returning the first module's rejection.
func (*TxFilter) Build ¶
func (f *TxFilter) Build(ctx context.Context, req *RPCReq, bypassRateLimit bool) (*TxSubmission, error)
Build decodes a submission request into a TxSubmission using the decoder registered for its method, propagating that decoder's errors and enforcing maxBundleTransactions here so the cap applies to every bundle regardless of middleware enablement.
func (*TxFilter) IsSubmissionMethod ¶
IsSubmissionMethod reports the static set of submission methods the filter handles. Per-method middleware opt-out is enforced inside the middleware module, not here — chain-ID/rate-limit/interop always apply.
type TxFilterModule ¶
type TxFilterModule interface {
Name() string
Apply(ctx context.Context, sub *TxSubmission) error
}
TxFilterModule is a single check in the submission filter pipeline.
Apply returns nil to accept (allowing the pipeline to continue) or an error to reject the whole submission. The contract:
- Apply runs for EVERY submission method the filter handles. Per-method scoping is the module's own responsibility — see txMiddlewareModule, which opts out of methods not in its configured set.
- Modules MUST treat sub.Txs as immutable. TxSubmission.Sender memoizes ecrecover per index keyed by position in sub.Txs; mutating or reordering the slice would corrupt that memo.
- The default failure policy is fail-CLOSED: returning an error rejects the submission. Fail-open (returning nil despite an internal failure) must be an explicit, operator-gated decision, as txMiddlewareModule does via its failOpen flag — never a silent default.
type TxMonitor ¶
type TxMonitor struct {
// contains filtered or unexported fields
}
TxMonitor passively measures user tx inclusion latency. It is fed by Observe (non-blocking) from the request hot path and runs its own block-poll, subblocks-stream, and reaper goroutines. Never critical: every failure mode degrades to missing metrics, not degraded ingestion.
func NewTxMonitor ¶
func NewTxMonitor(cfg TxMonitorConfig, backendGroups map[string]*BackendGroup, rpcMethodMappings map[string]string) (*TxMonitor, error)
func (*TxMonitor) Observe ¶
Observe records a successfully forwarded tx. Non-blocking by construction: a full channel drops the observation and counts it. This is the ONLY method called from the request hot path. at is the request-arrival time captured at ingress, so inclusion latency accounts for proxyd-internal handling and the forward round-trip, not just backend-ack-to-block.
type TxMonitorConfig ¶
type TxMonitorConfig struct {
Enabled bool `toml:"enabled"`
// BlockPollURL is an explicit RPC endpoint for block polling. When empty,
// the monitor polls through a proxyd backend group instead (see
// BlockPollBackendGroup).
BlockPollURL string `toml:"block_poll_url"`
// BlockPollBackendGroup names the backend group to poll blocks from when
// BlockPollURL is empty. Defaults to the group mapped for
// eth_getBlockByNumber, falling back to eth_sendRawTransaction's group.
BlockPollBackendGroup string `toml:"block_poll_backend_group"`
// SubblocksWSURL enables the subblocks preconfirmation watcher when set.
SubblocksWSURL string `toml:"subblocks_ws_url"`
// InclusionTimeout evicts pending txs and counts a timeout. Default 60s.
InclusionTimeout TOMLDuration `toml:"inclusion_timeout"`
// MaxPending caps the in-memory pending map. Default 10000.
MaxPending int `toml:"max_pending"`
// PollInterval is the block poll cadence. Default 1s.
PollInterval TOMLDuration `toml:"poll_interval"`
}
TxMonitorConfig configures the passive transaction-UX monitor: it observes successfully forwarded eth_sendRawTransaction hashes and measures latency until they appear in a block (and, optionally, in the subblocks stream). Purely observational — never blocks or affects tx ingestion.
type TxSubmission ¶
type TxSubmission struct {
Method string
Req *RPCReq
Txs []*types.Transaction
BypassRateLimit bool
// contains filtered or unexported fields
}
TxSubmission is the decoded form of a single transaction-submission request (eth_sendRawTransaction, eth_sendRawTransactionConditional, eth_sendBundle). The submission is decoded once and the recovered sender for each tx is memoized so that the chain-ID, sender-rate-limit, and interop modules can all share a single ecrecover per transaction.
Not safe for concurrent use.
func (*TxSubmission) Sender ¶
func (s *TxSubmission) Sender(i int) (common.Address, error)
Sender returns the recovered sender for Txs[i], computing it at most once. Recovery uses the same signer selection as getSender (HomesteadSigner for chainID 0, else LatestSignerForChainID) and memoizes both value and error. A recovery error is returned to the caller; modules treat it as a hard reject.
type TxValidationClient ¶
type TxValidationClient struct {
// contains filtered or unexported fields
}
TxValidationClient is a reusable HTTP client for validation requests.
func NewTxValidationClient ¶
func NewTxValidationClient(cfg TxValidationMiddlewareConfig) *TxValidationClient
NewTxValidationClient creates a new validation client from the middleware config. Unset (zero or negative) numeric fields fall back to defaults. cfg.APIKey is optional: when non-empty it is sent on every request in the x-api-key header.
type TxValidationFunc ¶
type TxValidationFunc func(ctx context.Context, endpoint string, payload []byte) (map[string]bool, error)
TxValidationFunc validates a batch of transactions and returns a map of tx hashes to unauthorized status. The endpoint is the middleware service URL, and payload is the request body to send.
type TxValidationMethodSet ¶
type TxValidationMethodSet map[string]struct{}
func NewTxValidationMethodSet ¶
func NewTxValidationMethodSet(methods []string) TxValidationMethodSet
func (TxValidationMethodSet) Contains ¶
func (s TxValidationMethodSet) Contains(method string) bool
type TxValidationMiddlewareConfig ¶
type TxValidationMiddlewareConfig struct {
// Enabled determines whether the middleware is active
Enabled bool `toml:"enabled"`
// Endpoint is the URL of the validation middleware service
Endpoint string `toml:"endpoint"`
// Methods is the list of RPC methods to apply validation to.
// Defaults to ["eth_sendRawTransaction", "eth_sendRawTransactionConditional", "eth_sendBundle"] if not specified.
Methods []string `toml:"methods"`
// APIKey is an optional credential sent to the validation service in the
// x-api-key header. No header is sent when empty. Supports $ENV_VAR
// indirection like other secrets in the config.
APIKey string `toml:"api_key"`
// TimeoutSeconds is the timeout for validation HTTP requests. Defaults to 5 seconds.
TimeoutSeconds int `toml:"timeout_seconds"`
// MaxConnsPerHost caps concurrent connections to the validation service.
// Over plain HTTP/1.1 this is also the cap on in-flight validations; further
// requests queue for a free connection, and that wait counts against
// TimeoutSeconds. Defaults to 10.
MaxConnsPerHost int `toml:"max_conns_per_host"`
// MaxIdleConns is the number of idle connections kept open to the validation
// service between bursts. Defaults to 10.
MaxIdleConns int `toml:"max_idle_conns"`
// FailOpen determines whether transactions should be allowed through if the validation
// service returns an error. Defaults to true for safety (fail-open).
FailOpen *bool `toml:"fail_open"`
}
TxValidationMiddlewareConfig configures the transaction validation middleware.
type WSProxier ¶
type WSProxier struct {
// contains filtered or unexported fields
}
func NewWSProxier ¶
Source Files
¶
- backend.go
- backend_probe.go
- backend_syscall.go
- cache.go
- config.go
- consensus_poller.go
- consensus_poller_cl.go
- consensus_tracker.go
- errors.go
- frontend_rate_limiter.go
- interop.go
- interop_strategy.go
- methods.go
- metrics.go
- proxyd.go
- rate_limit_tracker.go
- reader.go
- redis.go
- rewriter.go
- rpc.go
- server.go
- string_set.go
- tls.go
- tx_filter.go
- tx_filter_modules.go
- tx_monitor.go
- tx_monitor_blocks.go
- tx_monitor_store.go
- tx_monitor_subblocks.go
- tx_validation_middleware.go