gateway

type EndpointHydrator struct {
	Logger polylog.Logger

	// Protocol instance to be used by the hydrator when listing endpoints and sending relays.
	Protocol

	// ActiveQoSServices provides the hydrator with the QoS instances
	// it needs to invoke for generating synthetic service requests.
	// IMPORTANT: ActiveQoSServices should not be modified after the hydrator is started.
	ActiveQoSServices map[protocol.ServiceID]QoSService

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

	// DataReporter is used to export, to the data pipeline, observations made in handling service requests.
	// It is declared separately from the `MetricsReporter` to be consistent with the gateway package's role
	// of explicitly defining PATH gateway's components and their interactions.
	DataReporter RequestResponseReporter

	// RunInterval is the interval at which the Endpoint Hydrator will run HTTP checks in milliseconds.
	RunInterval time.Duration
	// MaxEndpointCheckWorkers is the maximum number of workers that will be used to concurrently check endpoints.
	MaxEndpointCheckWorkers int
	// 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

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

	// DataReporter is used to export, to the data pipeline, observations made in handling service requests.
	// It is declared separately from the `MetricsReporter` to be consistent with the gateway package's role
	// of explicitly defining PATH gateway's components and their interactions.
	DataReporter 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
}

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 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,
		*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.
	BuildHTTPRequestContextForEndpoint(
		context.Context,
		protocol.ServiceID,
		protocol.EndpointAddr,
		*http.Request,
	) (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

	// 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.
	ParseHTTPRequest(context.Context, *http.Request) (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

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

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)
}