gateway

type ActiveHealthChecksConfig struct {
	// Enabled enables/disables the active health check system.
	Enabled bool `yaml:"enabled,omitempty"`
	// SyncAllowance is the default number of blocks behind the latest block that an endpoint
	// can be before it's considered out of sync. Per-service overrides can set different values.
	// 0 means disabled (no sync allowance check). Default: 0 (disabled).
	SyncAllowance int `yaml:"sync_allowance,omitempty"`
	// MaxWorkers is the maximum number of concurrent health check workers.
	// Higher values allow faster health check cycles but increase load on endpoints.
	// Default: 10 workers
	MaxWorkers int `yaml:"max_workers,omitempty"`
	// Coordination configures leader election for distributed deployments.
	Coordination LeaderElectionConfig `yaml:"coordination,omitempty"`
	// External is an optional external URL for health check rules.
	// Local rules override external rules on conflict.
	External *ExternalConfigSource `yaml:"external,omitempty"`
	// Local defines health checks in the local config.
	// These override any checks from External with the same service_id + name.
	Local []ServiceHealthCheckConfig `yaml:"local,omitempty"`
}

type BlockHeightOperator string

type BlockHeightReference struct {
	// Type is the reference source: "static", "external", "perceived"
	Type BlockHeightReferenceType `yaml:"type"`

	// Value is the static block height (only for type="static")
	Value int64 `yaml:"value,omitempty"`

	// Endpoint is the external RPC endpoint to query (only for type="external")
	// Example: "https://arb-mainnet.g.alchemy.com/v2/demo"
	Endpoint string `yaml:"endpoint,omitempty"`

	// Method is the RPC method to call on external endpoint (only for type="external")
	// Example: "eth_blockNumber" for EVM chains
	Method string `yaml:"method,omitempty"`

	// Tolerance is the allowed difference (only for type="external" and type="perceived")
	// For external: endpoint_height >= (external_height - tolerance)
	// For perceived: endpoint_height >= (perceived_height - tolerance)
	// Default: 0 (no tolerance)
	Tolerance int64 `yaml:"tolerance,omitempty"`

	// Headers for external endpoint authentication (only for type="external")
	Headers map[string]string `yaml:"headers,omitempty"`

	// Timeout for external endpoint query (default: 5s)
	Timeout time.Duration `yaml:"timeout,omitempty"`

	// CacheDuration how long to cache external endpoint response (default: 10s)
	// Prevents hammering external endpoint on every health check
	CacheDuration time.Duration `yaml:"cache_duration,omitempty"`
}

type BlockHeightReferenceType string

type BlockHeightValidation struct {
	// Operator is the comparison operator: "<", ">", "<=", ">=", "=="
	Operator BlockHeightOperator `yaml:"operator"`

	// Reference specifies where to get the reference value for comparison.
	Reference BlockHeightReference `yaml:"reference"`
}

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

type ConcurrencyConfig struct {
	// MaxParallelEndpoints is the maximum number of endpoints to query in parallel per request.
	// Higher values reduce latency but increase load. Range: 1-10. Default: 1.
	MaxParallelEndpoints int `yaml:"max_parallel_endpoints,omitempty"`

	// MaxConcurrentRelays is the global limit on concurrent relay goroutines across all requests.
	// Prevents resource exhaustion from too many simultaneous relays. Range: 100-10000. Default: 5500.
	MaxConcurrentRelays int `yaml:"max_concurrent_relays,omitempty"`

	// MaxBatchPayloads is the maximum number of payloads allowed in a batch request.
	// Must be less than or equal to MaxConcurrentRelays. Range: 1-10000. Default: 5500.
	MaxBatchPayloads int `yaml:"max_batch_payloads,omitempty"`
}

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

type EndpointInfo struct {
	// Addr is the unique identifier for the endpoint (supplier-url format).
	Addr protocol.EndpointAddr

	// HTTPURL is the URL for HTTP-based health checks (jsonrpc, rest).
	// This is the endpoint's public URL for JSON-RPC requests.
	HTTPURL string

	// WebSocketURL is the URL for WebSocket health checks.
	// May be empty if the endpoint doesn't support WebSocket.
	WebSocketURL string

	// SessionID is the session this endpoint belongs to.
	// Used to detect session rollover - if session is no longer active,
	// health checks for this endpoint should be skipped.
	SessionID string
}

type ErrorDetection struct {
	// StatusCodes defines HTTP status codes to detect and penalize.
	StatusCodes []ErrorStatusCode `yaml:"status_codes,omitempty"`

	// ResponsePatterns defines error patterns to search for in response body.
	// Matches are case-insensitive substring searches.
	ResponsePatterns []ErrorPattern `yaml:"response_patterns,omitempty"`

	// JSONRPCErrorCodes defines JSON-RPC error codes to detect and penalize.
	JSONRPCErrorCodes []JSONRPCErrorCode `yaml:"jsonrpc_error_codes,omitempty"`
}

type ErrorPattern struct {
	// Pattern is the substring to search for in the response body (case-insensitive).
	// Examples: "rate limit", "exceeded your limit", "bad gateway", "quota"
	Pattern string `yaml:"pattern"`

	// ReputationSignal is the signal to send when this pattern is detected.
	// Values: "minor_error", "major_error", "critical_error", "fatal_error"
	ReputationSignal string `yaml:"reputation_signal"`
}

type ErrorStatusCode struct {
	// Code is the HTTP status code to match (e.g., 429, 502, 503).
	Code int `yaml:"code"`

	// ReputationSignal is the signal to send when this status code is detected.
	// Values: "minor_error", "major_error", "critical_error", "fatal_error"
	ReputationSignal string `yaml:"reputation_signal"`
}

type ExternalConfigSource struct {
	// URL is the URL to fetch health check rules from (e.g., GitHub raw file).
	URL string `yaml:"url"`
	// RefreshInterval is how often to re-fetch the external config.
	// 0 means only fetch at startup.
	RefreshInterval time.Duration `yaml:"refresh_interval,omitempty"`
	// Timeout is the HTTP timeout for fetching the external config.
	Timeout time.Duration `yaml:"timeout,omitempty"`
}

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

type Gateway struct {
	Logger polylog.Logger

	// HTTPRequestParser is used by the gateway instance to
	// interpret an HTTP request as a pair of service ID and
	// its corresponding QoS instance.
	HTTPRequestParser

	// The Protocol instance is used to fulfill the
	// service requests received by the gateway through
	// sending the service payload to an endpoint.
	Protocol

	// RPCTypeValidator validates detected RPC types against service configuration.
	// Used to fail fast with clear errors for unsupported RPC types.
	RPCTypeValidator *RPCTypeValidator

	// MetricsReporter is used to export metrics based on observations made in handling service requests.
	MetricsReporter RequestResponseReporter

	// WebsocketMessageBufferSize is the buffer size for websocket message observation channels.
	// Configurable to balance memory usage vs throughput for websocket connections.
	// Default: DefaultWebsocketMessageBufferSize (100)
	WebsocketMessageBufferSize int

	// ObservationQueue handles async, sampled observation processing for QoS data extraction.
	// When enabled, sampled requests are queued for deep parsing (block height, chain ID, etc.)
	// without blocking the hot path. This is optional - if nil, no async observation processing occurs.
	ObservationQueue *ObservationQueue
}

type HTTPRequestParser interface {
	// GetQoSService returns the qos for the service matching an HTTP request.
	GetQoSService(context.Context, *http.Request) (protocol.ServiceID, QoSService, error)

	// GetHTTPErrorResponse returns an HTTP response using the supplied error.
	// It will only be called if the GetQoSService method above returns an error.
	GetHTTPErrorResponse(context.Context, error) pathhttp.HTTPResponse
}

type HealthCheckConfig struct {
	// Name is a unique identifier for this check within a service.
	Name string `yaml:"name"`

	// Type specifies the RPC protocol type for this check.
	// REQUIRED - must match one of the service's configured rpc_types.
	// Valid values: "json_rpc", "rest", "comet_bft", "websocket", "grpc"
	//
	// BREAKING CHANGE: Old value "jsonrpc" is now "json_rpc" for consistency.
	// No default - explicit specification required to avoid ambiguity.
	Type HealthCheckType `yaml:"type"`

	// Enabled allows disabling individual checks without removing them.
	Enabled *bool `yaml:"enabled,omitempty"`

	// Method is the HTTP method (GET, POST). Required for jsonrpc/rest types.
	// Ignored for websocket and grpc types.
	Method string `yaml:"method,omitempty"`

	// Path is the URL path to send the request to (e.g., "/" or "/ws").
	Path string `yaml:"path"`

	// Headers is a map of HTTP headers to send with the request.
	// If not specified, defaults to {"Content-Type": "application/json"} for POST requests.
	// Can be used to set custom headers like Authorization, X-Api-Key, etc.
	Headers map[string]string `yaml:"headers,omitempty"`

	// Body is the request body (e.g., JSON-RPC payload).
	// For websocket: if provided, sent after connection and response is expected.
	// If empty for websocket: only connection test is performed.
	Body string `yaml:"body,omitempty"`

	// ExpectedStatusCode is the HTTP status code expected for success (default: 200).
	// Only applies to jsonrpc and rest types.
	ExpectedStatusCode int `yaml:"expected_status_code,omitempty"`

	// ExpectedResponseContains is an optional substring to look for in the response body.
	// If specified, the check fails if this substring is not found in the response.
	// For websocket with body: checked against any received message within timeout.
	ExpectedResponseContains string `yaml:"expected_response_contains,omitempty"`

	// BlockHeightValidation enables block height comparison checks.
	// If specified, the health check will extract the block height from the response
	// and compare it against a reference value using the specified operator.
	// This is useful for detecting stuck or lagging nodes.
	BlockHeightValidation *BlockHeightValidation `yaml:"block_height_validation,omitempty"`

	// ErrorDetection enables error pattern detection in health check responses.
	// If specified, the health check will detect known error patterns (rate limits,
	// bad gateway errors, quota errors, etc.) and send appropriate reputation signals.
	ErrorDetection *ErrorDetection `yaml:"error_detection,omitempty"`

	// Timeout is the request timeout for this check.
	// For websocket: how long to wait for connection + optional response.
	Timeout time.Duration `yaml:"timeout,omitempty"`

	// Archival indicates if this is an archival-specific check.
	Archival bool `yaml:"archival,omitempty"`

	// ReputationSignal is the signal type to record on failure.
	// Values: "minor_error", "major_error", "critical_error", "fatal_error"
	ReputationSignal string `yaml:"reputation_signal,omitempty"`
}

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

type HealthCheckExecutorConfig struct {
	Config                *ActiveHealthChecksConfig
	ReputationSvc         reputation.ReputationService
	Logger                polylog.Logger
	Protocol              Protocol
	MetricsReporter       RequestResponseReporter
	LeaderElector         *LeaderElector
	ObservationQueue      *ObservationQueue
	MaxWorkers            int
	UnifiedServicesConfig *UnifiedServicesConfig
}

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

type HealthCheckQoSContextConfig struct {
	Logger         polylog.Logger
	ServiceID      protocol.ServiceID
	CheckConfig    HealthCheckConfig
	ServicePayload protocol.Payload
}

type HealthCheckType string

type HealthChecksConfig = ActiveHealthChecksConfig

type JSONRPCErrorCode struct {
	// Code is the JSON-RPC error code to match (e.g., -31002, -32001).
	Code int `yaml:"code"`

	// ReputationSignal is the signal to send when this error code is detected.
	// Values: "minor_error", "major_error", "critical_error", "fatal_error"
	ReputationSignal string `yaml:"reputation_signal"`
}

type LatencyProfileConfig struct {
	// FastThreshold is the maximum latency for "fast" responses.
	FastThreshold time.Duration `yaml:"fast_threshold"`
	// NormalThreshold is the maximum latency for "normal" responses.
	NormalThreshold time.Duration `yaml:"normal_threshold"`
	// SlowThreshold is the maximum latency for "slow" responses.
	SlowThreshold time.Duration `yaml:"slow_threshold"`
	// PenaltyThreshold triggers a slow_response penalty signal.
	PenaltyThreshold time.Duration `yaml:"penalty_threshold"`
	// SevereThreshold triggers a very_slow_response penalty signal.
	SevereThreshold time.Duration `yaml:"severe_threshold"`
	// FastBonus is the multiplier for success impact when response is fast.
	FastBonus float64 `yaml:"fast_bonus,omitempty"`
	// SlowPenalty is the multiplier for success impact when response is slow.
	SlowPenalty float64 `yaml:"slow_penalty,omitempty"`
	// VerySlowPenalty is the multiplier for success when response is very slow.
	VerySlowPenalty float64 `yaml:"very_slow_penalty,omitempty"`
}

type LeaderElectionConfig struct {
	// Type is the coordination type: "leader_election" or "none".
	// Default: "leader_election" when Redis is configured, "none" otherwise.
	Type string `yaml:"type,omitempty"`
	// LeaseDuration is how long the leader holds the lock.
	LeaseDuration time.Duration `yaml:"lease_duration,omitempty"`
	// RenewInterval is how often the leader renews the lock.
	RenewInterval time.Duration `yaml:"renew_interval,omitempty"`
	// Key is the Redis key for the leader lock.
	Key string `yaml:"key,omitempty"`
}

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

type LeaderElectorConfig struct {
	Client *redis.Client
	Config LeaderElectionConfig
	Logger polylog.Logger
}

type ObservationHandler interface {
	// HandleExtractedData processes the extracted data from an observation.
	// Called by worker pool goroutines, must be thread-safe.
	HandleExtractedData(obs *QueuedObservation, data *qostypes.ExtractedData) error
}

type ObservationPipelineConfig struct {
	// Enabled enables async observation processing mode.
	// When true, responses are returned as raw bytes without blocking on parsing.
	// When false (default), legacy behavior is used (parse then re-encode).
	Enabled bool `yaml:"enabled,omitempty"`

	// SampleRate is the fraction of requests to deep-parse (0.0 to 1.0).
	// Only applies when Enabled is true.
	// Default: 0.1 (10% of requests get queued for deep parsing)
	// Set to 0.0 to disable sampling (only active health checks update endpointStore)
	// Set to 1.0 to parse all requests async (not recommended for high traffic)
	SampleRate float64 `yaml:"sample_rate,omitempty"`

	// WorkerCount is the number of worker goroutines for async parsing.
	// Default: 4
	WorkerCount int `yaml:"worker_count,omitempty"`

	// QueueSize is the max number of pending observations.
	// If queue is full, new observations are dropped (non-blocking).
	// Default: 1000
	QueueSize int `yaml:"queue_size,omitempty"`
}

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

type ObservationQueueConfig struct {
	// Enabled enables/disables async observation processing.
	// When disabled, all parsing happens synchronously (legacy behavior).
	Enabled bool `yaml:"enabled,omitempty"`

	// SampleRate is the fraction of requests to deep-parse (0.0 to 1.0).
	// Default: 0.1 (10% of requests get deep parsing)
	// Note: Reputation signals are recorded for 100% of requests regardless.
	SampleRate float64 `yaml:"sample_rate,omitempty"`

	// WorkerCount is the number of worker goroutines for parsing.
	// Default: 4
	WorkerCount int `yaml:"worker_count,omitempty"`

	// QueueSize is the max number of pending observations.
	// If queue is full, new observations are dropped (non-blocking).
	// Default: 1000
	QueueSize int `yaml:"queue_size,omitempty"`
}

type ObservationSource string

type ParentConfigDefaults struct {
	// TieredSelectionEnabled from reputation_config.tiered_selection.enabled
	TieredSelectionEnabled bool
	// Tier1Threshold from reputation_config.tiered_selection.tier1_threshold
	Tier1Threshold float64
	// Tier2Threshold from reputation_config.tiered_selection.tier2_threshold
	Tier2Threshold float64
	// ProbationEnabled from reputation_config.tiered_selection.probation.enabled
	ProbationEnabled bool
	// ProbationThreshold from reputation_config.tiered_selection.probation.threshold
	ProbationThreshold float64
	// ProbationTrafficPercent from reputation_config.tiered_selection.probation.traffic_percent
	ProbationTrafficPercent float64
	// ProbationRecoveryMultiplier from reputation_config.tiered_selection.probation.recovery_multiplier
	ProbationRecoveryMultiplier float64
	// RetryEnabled from retry_config.enabled
	RetryEnabled bool
	// MaxRetries from retry_config.max_retries
	MaxRetries int
	// RetryOn5xx from retry_config.retry_on_5xx
	RetryOn5xx bool
	// RetryOnTimeout from retry_config.retry_on_timeout
	RetryOnTimeout bool
	// RetryOnConnection from retry_config.retry_on_connection
	RetryOnConnection bool
	// MaxRetryLatency from retry_config.max_retry_latency
	MaxRetryLatency time.Duration
	// ObservationPipelineEnabled from observation_pipeline.enabled
	ObservationPipelineEnabled bool
	// SampleRate from observation_pipeline.sample_rate
	SampleRate float64
	// HealthChecksEnabled from active_health_checks.enabled
	HealthChecksEnabled bool
	// HealthCheckInterval from active_health_checks interval
	HealthCheckInterval time.Duration
	// SyncAllowance from active_health_checks.sync_allowance
	SyncAllowance int
}

type PassthroughConfig = ObservationPipelineConfig

type Protocol interface {
	// AvailableHTTPEndpoints returns the list of available HTTP endpoints matching both the service ID
	//
	// If the Pocket Network Gateway is in delegated mode, the staked application is passed via
	// the `App-Address` header. In all other modes, *http.Request will be nil.
	//
	// Context may contain a deadline that protocol should respect on best-effort basis.
	// Return observation if endpoint lookup fails.
	// Used as protocol observation for the request when no protocol context exists.
	AvailableHTTPEndpoints(
		context.Context,
		protocol.ServiceID,
		sharedtypes.RPCType,
		*http.Request,
	) (protocol.EndpointAddrList, protocolobservations.Observations, error)

	// AvailableWebsocketEndpoints returns the list of available websocket endpoints matching both the service ID
	//
	// If the Pocket Network Gateway is in delegated mode, the staked application is passed via
	// the `App-Address` header. In all other modes, *http.Request will be nil.
	//
	// Context may contain a deadline that protocol should respect on best-effort basis.
	// Return observation if endpoint lookup fails.
	// Used as protocol observation for the request when no protocol context exists.
	AvailableWebsocketEndpoints(
		context.Context,
		protocol.ServiceID,
		*http.Request,
	) (protocol.EndpointAddrList, protocolobservations.Observations, error)

	// BuildRequestContextForEndpoint builds and returns a ProtocolRequestContext containing a single selected endpoint.
	// One `ProtocolRequestContext` correspond to a single request, which is sent to a single endpoint.
	//
	// If the Pocket Network Gateway is in delegated mode, the staked application is passed via
	// the `App-Address` header. In all other modes, *http.Request will be nil.
	//
	// Context may contain a deadline that protocol should respect on best-effort basis.
	//
	// Return observation if the context setup fails.
	// Used as protocol observation for the request when no protocol context exists.
	// filterByReputation controls whether to filter endpoints by reputation score.
	// Pass true for normal requests (respects reputation), false for health checks (reaches all endpoints).
	BuildHTTPRequestContextForEndpoint(
		ctx context.Context,
		serviceID protocol.ServiceID,
		endpointAddr protocol.EndpointAddr,
		rpcType sharedtypes.RPCType,
		httpReq *http.Request,
		filterByReputation bool,
	) (ProtocolRequestContext, protocolobservations.Observations, error)

	// BuildWebsocketRequestContextForEndpoint builds and returns a ProtocolRequestContextWebsocket containing a single selected endpoint.
	// One `ProtocolRequestContextWebsocket` corresponds to a single long-lived websocket connection to a single endpoint.
	// This method immediately establishes the Websocket connection and starts the bridge.
	//
	// If the Pocket Network Gateway is in delegated mode, the staked application is passed via
	// the `App-Address` header. In all other modes, *http.Request will be nil.
	//
	// Return observation channel for connection-level observations (establishment, closure, errors).
	// Message observations are sent through the provided messageObservationsChan.
	// Return error if the context setup or connection establishment fails.
	BuildWebsocketRequestContextForEndpoint(
		context.Context,
		protocol.ServiceID,
		protocol.EndpointAddr,
		websockets.WebsocketMessageProcessor,
		*http.Request,
		http.ResponseWriter,
		chan *observation.RequestResponseObservations,
	) (ProtocolRequestContextWebsocket, <-chan *protocolobservations.Observations, error)

	// SupportedGatewayModes returns the Gateway modes supported by the protocol instance.
	// See protocol/gateway_mode.go for more details.
	SupportedGatewayModes() []protocol.GatewayMode

	// ApplyHTTPObservations applies the supplied observations to the protocol instance's internal state.
	// Hypothetical example (for illustrative purposes only):
	// 	- protocol: Shannon
	// 	- observation: "endpoint maxed-out or over-serviced (i.e. onchain rate limiting)"
	// 	- result: skip the endpoint for a set time period until a new session begins.
	ApplyHTTPObservations(*protocolobservations.Observations) error

	// ApplyWebSocketObservations applies the supplied observations to the protocol instance's internal state.
	// Hypothetical example (for illustrative purposes only):
	// 	- protocol: Shannon
	// 	- observation: "endpoint maxed-out or over-serviced (i.e. onchain rate limiting)"
	// 	- result: skip the endpoint for a set time period until a new session begins.
	ApplyWebSocketObservations(*protocolobservations.Observations) error

	// TODO_FUTURE(@adshmh): support specifying the app(s) used for sending/signing synthetic relay requests by the hydrator.
	// TODO_TECHDEBT: Enable the hydrator for gateway modes beyond Centralized only.
	//
	// ConfiguredServiceIDs returns the list of service IDs that the protocol instance is configured to serve.
	ConfiguredServiceIDs() map[protocol.ServiceID]struct{}

	// GetTotalServiceEndpointsCount returns the count of all unique endpoints for a service ID
	// without filtering sanctioned endpoints.
	GetTotalServiceEndpointsCount(protocol.ServiceID, *http.Request) (int, error)

	// HydrateDisqualifiedEndpointsResponse hydrates the disqualified endpoint response with the protocol-specific data.
	HydrateDisqualifiedEndpointsResponse(protocol.ServiceID, *devtools.DisqualifiedEndpointResponse)

	// CheckWebsocketConnection checks if the websocket connection to the endpoint is established.
	CheckWebsocketConnection(context.Context, protocol.ServiceID, protocol.EndpointAddr) *protocolobservations.Observations

	// GetReputationService returns the reputation service instance used by the protocol.
	// This is used by the health check executor to record health check results.
	GetReputationService() reputation.ReputationService

	// GetEndpointsForHealthCheck returns a function that gets endpoints for health checks.
	// The returned function takes a service ID and returns endpoint info suitable for health checks.
	// Note: This does NOT filter by reputation - health checks should run against all endpoints.
	GetEndpointsForHealthCheck() func(protocol.ServiceID) ([]EndpointInfo, error)

	// GetUnifiedServicesConfig returns the unified services configuration.
	// This is used by components that need access to per-service configuration overrides.
	GetUnifiedServicesConfig() *UnifiedServicesConfig

	// GetConcurrencyConfig returns the concurrency configuration.
	// This is used by components that need to respect concurrency limits.
	GetConcurrencyConfig() ConcurrencyConfig

	// UnblacklistSupplier removes a supplier from the blacklist.
	// Called when a health check succeeds for a previously blacklisted supplier.
	// Returns true if the supplier was blacklisted and has been removed.
	UnblacklistSupplier(serviceID protocol.ServiceID, supplierAddr string) bool

	// IsSupplierBlacklisted checks if a supplier is currently blacklisted.
	IsSupplierBlacklisted(serviceID protocol.ServiceID, supplierAddr string) bool

	// IsSessionActive checks if a session is currently active for a service.
	// Used by health check executor to detect session rollover before attempting health checks.
	// Returns true if the session is still in the current active sessions list.
	IsSessionActive(ctx context.Context, serviceID protocol.ServiceID, sessionID string) bool

	// health.Check interface is used to verify protocol instance's health status.
	health.Check
}

type ProtocolRequestContext interface {
	// HandleServiceRequest sends the supplied payload to the endpoint selected using the above SelectEndpoint method,
	// and receives and verifies the response.
	HandleServiceRequest([]protocol.Payload) ([]protocol.Response, error)

	// GetObservations builds and returns the set of protocol-specific observations using the current context.
	//
	// Hypothetical illustrative example.
	//
	// If the context is:
	// 	- Protocol: Shannon
	//	- SelectedEndpoint: `endpoint_101`
	//	- Event: HandleServiceRequest returned a "maxed-out endpoint" error
	//
	// Then the observation can be:
	//  - `maxed-out endpoint` on `endpoint_101`.
	GetObservations() protocolobservations.Observations
}

type ProtocolRequestContextWebsocket interface {
	// ProcessProtocolClientWebsocketMessage processes a message from the client.
	ProcessProtocolClientWebsocketMessage([]byte) ([]byte, error)

	// ProcessProtocolEndpointWebsocketMessage processes a message from the endpoint.
	ProcessProtocolEndpointWebsocketMessage([]byte) ([]byte, protocolobservations.Observations, error)
}

type QoSContextBuilder interface {
	// ParseHTTPRequest:
	// - Ensures the HTTP request is valid for the target service.
	// - detectedRPCType: The RPC type detected by the gateway (or UNKNOWN_RPC if detection failed)
	// - Services should respect this if not UNKNOWN_RPC, or apply their own fallback logic
	ParseHTTPRequest(ctx context.Context, httpReq *http.Request, detectedRPCType sharedtypes.RPCType) (RequestQoSContext, bool)

	// ParseWebsocketRequest:
	// - Ensures a Websocket request is valid for the target service.
	// - Websocket connection requests have no body, so no parsing needed.
	// - If service supports Websocket, returns a valid RequestQoSContext.
	//
	// TODO_TECHDEBT(@adshmh,@commoddity): Remove ParseWebsocketRequest and update ParseHTTPRequest to be the single entry point to QoS.
	// It should perform basic validation of the HTTP handshake request in the case that it is a Websocket request.
	// eg. check that the request is a websocket request, check headers, etc.
	ParseWebsocketRequest(context.Context) (RequestQoSContext, bool)
}

type QoSEndpointCheckGenerator interface {
	// TODO_FUTURE:
	// - Add GetOptionalQualityChecks() to collect additional QoS data (e.g., endpoint latency).
	//
	// GetRequiredQualityChecks:
	// - Returns required quality checks for a QoS instance to assess endpoint validity.
	// - Example: EVM QoS may skip block height check if chain ID check already failed.
	GetRequiredQualityChecks(protocol.EndpointAddr) []RequestQoSContext

	// TODO_TECHDEBT(@commoddity): Currently websocket QoS only performs a protocol-level check
	// which determines if an endpoint connection request is successful or not.
	//
	// This only require a simple bool that tells the hydrator if the endpoint should be checked
	// for Websocket connection and applies protocol-level sanctions if it fails.
	//
	// In the future, we may want to add QoS-level checks that take into account specific endpoint
	// responses to apply websocket-related filtering at the QoS level.
	//
	// CheckWebsocketConnection
	//  - Checks if the endpoint supports Websocket connections.
	//  - Returns a boolean indicating whether the endpoint should be checked for Websocket connection.
	CheckWebsocketConnection() bool
}

type QoSService interface {
	QoSContextBuilder
	QoSEndpointCheckGenerator

	// ApplyObservations:
	// - Applies QoS-related observations to the local QoS instance.
	// - TODO_FUTURE: Observations can be:
	//   - "local": from requests sent to an endpoint by THIS PATH instance.
	//   - "shared": from QoS observations shared by OTHER PATH instances.
	ApplyObservations(*qos.Observations) error

	// UpdateFromExtractedData:
	// - Updates QoS state from extracted observation data.
	// - Called by the observation pipeline after async parsing completes.
	// - This method updates endpoint state (e.g., perceived block number) without
	//   blocking the hot path of user requests.
	// - Data is extracted via DataExtractor from sampled requests and health checks.
	UpdateFromExtractedData(endpointAddr protocol.EndpointAddr, data *qostypes.ExtractedData) error

	// GetPerceivedBlockNumber:
	// - Returns the perceived current block number for the service.
	// - Used by health checks for block height validation.
	// - Returns 0 if no block number has been observed yet.
	GetPerceivedBlockNumber() uint64

	// HydrateDisqualifiedEndpointsResponse:
	// - Fills the disqualified endpoint response with QoS-specific data.
	HydrateDisqualifiedEndpointsResponse(protocol.ServiceID, *devtools.DisqualifiedEndpointResponse)
}

type QueuedObservation struct {

	// ServiceID identifies the service (e.g., "eth", "base", "cosmos").
	ServiceID protocol.ServiceID

	// EndpointAddr identifies the endpoint that responded.
	EndpointAddr protocol.EndpointAddr

	// Source indicates where this observation came from.
	Source ObservationSource

	// Timestamp when the response was received.
	Timestamp time.Time

	// Latency of the request-response cycle.
	Latency time.Duration

	// RequestID is a unique identifier for this request, used for log correlation.
	// It is either extracted from the X-Request-ID header or generated as a new UUID.
	RequestID string

	// RequestPath is the URL path (e.g., "/", "/v1/completions").
	RequestPath string

	// RequestHTTPMethod is the HTTP method (GET, POST, etc.).
	RequestHTTPMethod string

	// RequestHeaders are the request headers (optional, for context).
	RequestHeaders map[string]string

	// RequestBody is the raw request payload (for determining RPC method, etc.).
	RequestBody []byte

	// ResponseStatusCode is the HTTP status code from the endpoint.
	ResponseStatusCode int

	// ResponseHeaders are the response headers (optional, for context).
	ResponseHeaders map[string]string

	// ResponseBody is the raw endpoint response to parse.
	ResponseBody []byte
}

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

type RPCTypeMapper struct{}

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

type RequestQoSContext interface {
	// TODO_TECHDEBT: Should eventually return []Payload
	// - Allows mapping a single RelayRequest into multiple ServiceRequests.
	// - Example: A batch relay request on JSONRPC should decompose into multiple independent requests.
	GetServicePayloads() []protocol.Payload

	// TODO_FUTURE:
	// - Add retry-related return values to UpdateWithResponse,
	//   or add retry-related methods (e.g., Failed(), ShouldRetry()).
	//
	// UpdateWithResponse:
	// - Informs the request QoS context of the payload returned by a specific endpoint.
	// - Response is for the service payload produced by GetServicePayload.
	// - httpStatusCode is the original HTTP status code from the backend endpoint.
	UpdateWithResponse(endpointAddr protocol.EndpointAddr, endpointSerializedResponse []byte, httpStatusCode int)

	// GetHTTPResponse:
	// - Returns the user-facing HTTP response.
	// - Response depends on the current state of the service request context.
	// - State is set at context creation and updated via UpdateWithResponse.
	// - If never updated, may return 404 HTTP status.
	GetHTTPResponse() pathhttp.HTTPResponse

	// GetObservations:
	// - Returns QoS-level observations in the context.
	//
	// Example:
	//   Context:
	//     - Service: Solana
	//     - SelectedEndpoint: `endpoint_101`
	//     - Request: `getHealth`
	//     - Endpoint response: error
	//   Observation:
	//     - `endpoint_101` is unhealthy.
	GetObservations() qos.Observations

	// GetEndpointSelector:
	// - Enables specialized endpoint selection (e.g., method-based selection for EVM requests).
	GetEndpointSelector() protocol.EndpointSelector
}

type RequestResponseReporter interface {
	// Publish exports observations made on a service request and response(s), to the external component used by the corresponding implementation.
	Publish(*observation.RequestResponseObservations)
}

type RetryConfig struct {
	// Enabled enables/disables automatic retries.
	Enabled bool `yaml:"enabled,omitempty"`
	// MaxRetries is the maximum number of retry attempts.
	MaxRetries int `yaml:"max_retries,omitempty"`
	// MaxRetryLatency is the maximum latency threshold for retries.
	// Only retry if failed request took less than this duration.
	MaxRetryLatency *time.Duration `yaml:"max_retry_latency,omitempty"`
	// RetryOn5xx enables retrying on 5xx errors.
	RetryOn5xx bool `yaml:"retry_on_5xx,omitempty"`
	// RetryOnTimeout enables retrying on timeout errors.
	RetryOnTimeout bool `yaml:"retry_on_timeout,omitempty"`
	// RetryOnConnection enables retrying on connection errors.
	RetryOnConnection bool `yaml:"retry_on_connection,omitempty"`
}

type ServiceConcurrencyConfig struct {
	MaxParallelEndpoints *int `yaml:"max_parallel_endpoints,omitempty"`
	MaxBatchPayloads     *int `yaml:"max_batch_payloads,omitempty"`
}

type ServiceConfig struct {
	ID                  protocol.ServiceID            `yaml:"id"`
	Type                ServiceType                   `yaml:"type,omitempty"`
	RPCTypes            []string                      `yaml:"rpc_types,omitempty"`
	RPCTypeFallbacks    map[string]string             `yaml:"rpc_type_fallbacks,omitempty"`
	LatencyProfile      string                        `yaml:"latency_profile,omitempty"`
	ReputationConfig    *ServiceReputationConfig      `yaml:"reputation_config,omitempty"`
	Latency             *ServiceLatencyConfig         `yaml:"latency,omitempty"`
	TieredSelection     *ServiceTieredSelectionConfig `yaml:"tiered_selection,omitempty"`
	Probation           *ServiceProbationConfig       `yaml:"probation,omitempty"`
	RetryConfig         *ServiceRetryConfig           `yaml:"retry_config,omitempty"`
	ObservationPipeline *ServiceObservationConfig     `yaml:"observation_pipeline,omitempty"`
	ConcurrencyConfig   *ServiceConcurrencyConfig     `yaml:"concurrency_config,omitempty"`
	Fallback            *ServiceFallbackConfig        `yaml:"fallback,omitempty"`
	HealthChecks        *ServiceHealthCheckOverride   `yaml:"health_checks,omitempty"`
}

type ServiceDefaults struct {
	Type                ServiceType                  `yaml:"type,omitempty"`
	RPCTypes            []string                     `yaml:"rpc_types,omitempty"`
	LatencyProfile      string                       `yaml:"latency_profile,omitempty"`
	ReputationConfig    ServiceReputationConfig      `yaml:"reputation_config,omitempty"`
	Latency             ServiceLatencyConfig         `yaml:"latency,omitempty"`
	TieredSelection     ServiceTieredSelectionConfig `yaml:"tiered_selection,omitempty"`
	Probation           ServiceProbationConfig       `yaml:"probation,omitempty"`
	RetryConfig         ServiceRetryConfig           `yaml:"retry_config,omitempty"`
	ObservationPipeline ServiceObservationConfig     `yaml:"observation_pipeline,omitempty"`
	ConcurrencyConfig   ServiceConcurrencyConfig     `yaml:"concurrency_config,omitempty"`
	ActiveHealthChecks  ServiceHealthCheckOverride   `yaml:"active_health_checks,omitempty"`
}

type ServiceFallbackConfig struct {
	Enabled        bool                `yaml:"enabled,omitempty"`
	SendAllTraffic bool                `yaml:"send_all_traffic,omitempty"`
	Endpoints      []map[string]string `yaml:"endpoints,omitempty"`
}

type ServiceHealthCheckConfig struct {
	// ServiceID is the service identifier (e.g., "eth", "base", "poly").
	ServiceID protocol.ServiceID `yaml:"service_id"`
	// CheckInterval is how often to run health checks for this service.
	CheckInterval time.Duration `yaml:"check_interval,omitempty"`
	// Enabled allows disabling all checks for this service.
	Enabled *bool `yaml:"enabled,omitempty"`
	// SyncAllowance is the number of blocks behind the latest block that an endpoint
	// can be before it's considered out of sync. Overrides the global default for this service.
	// 0 means disabled (no sync allowance check). Default: 0 (disabled).
	SyncAllowance *int `yaml:"sync_allowance,omitempty"`
	// Checks is the list of health checks to run for this service.
	Checks []HealthCheckConfig `yaml:"checks"`
}

type ServiceHealthCheckOverride struct {
	Enabled       *bool                 `yaml:"enabled,omitempty"`
	Interval      time.Duration         `yaml:"interval,omitempty"`
	SyncAllowance *int                  `yaml:"sync_allowance,omitempty"`
	External      *ExternalConfigSource `yaml:"external,omitempty"`
	Local         []HealthCheckConfig   `yaml:"local,omitempty"`
}

type ServiceLatencyConfig struct {
	Enabled       *bool   `yaml:"enabled,omitempty"`
	TargetMs      int     `yaml:"target_ms,omitempty"`
	PenaltyWeight float64 `yaml:"penalty_weight,omitempty"`
}

type ServiceObservationConfig struct {
	Enabled    *bool    `yaml:"enabled,omitempty"`
	SampleRate *float64 `yaml:"sample_rate,omitempty"`
}

type ServiceProbationConfig struct {
	Enabled            *bool    `yaml:"enabled,omitempty"`
	Threshold          *float64 `yaml:"threshold,omitempty"`
	TrafficPercent     *float64 `yaml:"traffic_percent,omitempty"`
	RecoveryMultiplier *float64 `yaml:"recovery_multiplier,omitempty"`
}

type ServiceReputationConfig struct {
	Enabled         *bool          `yaml:"enabled,omitempty"`
	InitialScore    *float64       `yaml:"initial_score,omitempty"`
	MinThreshold    *float64       `yaml:"min_threshold,omitempty"`
	KeyGranularity  string         `yaml:"key_granularity,omitempty"`
	RecoveryTimeout *time.Duration `yaml:"recovery_timeout,omitempty"`
}

type ServiceRetryConfig struct {
	Enabled           *bool          `yaml:"enabled,omitempty"`
	MaxRetries        *int           `yaml:"max_retries,omitempty"`
	RetryOn5xx        *bool          `yaml:"retry_on_5xx,omitempty"`
	RetryOnTimeout    *bool          `yaml:"retry_on_timeout,omitempty"`
	RetryOnConnection *bool          `yaml:"retry_on_connection,omitempty"`
	MaxRetryLatency   *time.Duration `yaml:"max_retry_latency,omitempty"` // Only retry if failed request took less than this duration
}

type ServiceTieredSelectionConfig struct {
	Enabled        *bool    `yaml:"enabled,omitempty"`
	Tier1Threshold *float64 `yaml:"tier1_threshold,omitempty"`
	Tier2Threshold *float64 `yaml:"tier2_threshold,omitempty"`
}

type ServiceType string

type UnifiedServicesConfig struct {
	LatencyProfiles map[string]LatencyProfileConfig `yaml:"latency_profiles,omitempty"`
	Defaults        ServiceDefaults                 `yaml:"defaults,omitempty"`
	Services        []ServiceConfig                 `yaml:"services,omitempty"`
}