@@ -9,103 +9,104 @@ import (
99 "github.com/buildwithgrove/path/protocol"
1010)
1111
12- // RequestQoSContext represents the interactions of the gateway with the QoS instance
13- // corresponding to the service specified by a service request.
12+ // RequestQoSContext
1413//
15- // A RequestQoSContext can be built in various ways such as:
16- // - 1. Building a new context by parsing an organic request from an end-user
17- // - 2. Building a new context based on a desired endpoint check, e.g. an `eth_chainId` request on an EVM blockchain.
18- // - 3. Rebuilding an existing context by deserializing a shared context from another PATH instance
14+ // Represents interactions between the gateway and the QoS instance for a given service request.
15+ //
16+ // Construction methods:
17+ // - Parse an organic request from an end-user.
18+ // - Rebuild from a shared context deserialized from another PATH instance.
1919type RequestQoSContext interface {
20- // TODO_TECHDEBT: This should eventually return a []Payload
21- // to allow mapping a single RelayRequest into multiple ServiceRequests,
22- // e.g. A single batch relay request on a JSONRPC blockchain should be decomposable into
23- // multiple independent requests.
20+ // TODO_TECHDEBT: Should eventually return []Payload
21+ // - Allows mapping a single RelayRequest into multiple ServiceRequests.
22+ // - Example: A batch relay request on JSONRPC should decompose into multiple independent requests.
2423 GetServicePayload () protocol.Payload
2524
26- // TODO_FUTURE: add retry-related return values to UpdateWithResponse,
27- // or add retry-related methods to the interface, e.g. Failed(), ShouldRetry().
28- // UpdateWithResponse is used to inform the request QoS context of the
29- // payload returned by a specific endpoint in response to the service
30- // payload produced (through the `GetServicePayload` method) by the
31- // request QoS context instance
25+ // TODO_FUTURE:
26+ // - Add retry-related return values to UpdateWithResponse,
27+ // or add retry-related methods (e.g., Failed(), ShouldRetry()).
28+ //
29+ // UpdateWithResponse:
30+ // - Informs the request QoS context of the payload returned by a specific endpoint.
31+ // - Response is for the service payload produced by GetServicePayload.
3232 UpdateWithResponse (endpointAddr protocol.EndpointAddr , endpointSerializedResponse []byte )
3333
34- // GetHTTPResponse returns the user-facing HTTP response.
35- // The received response will depend on the state of the service request context,
36- // which is set at the time of establishing the context,
37- // and updated using the UpdateWithResponse method above.
38- // e.g. Calling this on a ServiceRequestContext instance which has
39- // never been updated with a response could return an HTTP response
40- // with a 404 HTTP status code.
34+ // GetHTTPResponse:
35+ // - Returns the user-facing HTTP response.
36+ // - Response depends on the current state of the service request context.
37+ // - State is set at context creation and updated via UpdateWithResponse.
38+ // - If never updated, may return 404 HTTP status.
4139 GetHTTPResponse () HTTPResponse
4240
43- // GetObservations returns the set of QoS-level observations contained in the context.
44- //
45- // Hypothetical illustrative example.
41+ // GetObservations:
42+ // - Returns QoS-level observations in the context.
4643 //
47- // If the context is :
48- // - Service: Solana
49- // - SelectedEndpoint: `endpoint_101`
50- // - Request : `getHealth `
51- // - Endpoint response: an error
52- //
53- // Then the observation can be :
54- // - `endpoint_101` is unhealthy.
44+ // Example :
45+ // Context:
46+ // - Service: Solana
47+ // - SelectedEndpoint : `endpoint_101 `
48+ // - Request: `getHealth`
49+ // - Endpoint response: error
50+ // Observation :
51+ // - `endpoint_101` is unhealthy.
5552 GetObservations () qos.Observations
5653
57- // GetEndpointSelector is part of this interface to enable more specialized endpoint
58- // selection, e.g. method-based endpoint selection for an EVM blockchain service request .
54+ // GetEndpointSelector:
55+ // - Enables specialized endpoint selection ( e.g., method-based selection for EVM requests) .
5956 GetEndpointSelector () protocol.EndpointSelector
6057}
6158
62- // QoSContextBuilder builds the QoS context required for handling
63- // all steps of a service request, e.g. generating a user-facing
64- // HTTP response from an endpoint's response.
59+ // QoSContextBuilder
60+ //
61+ // Builds the QoS context required for all steps of a service request.
62+ // Example: Generate a user-facing HTTP response from an endpoint's response.
6563type QoSContextBuilder interface {
66- // ParseHTTPRequest ensures that an HTTP request represents a valid request on the target service.
64+ // ParseHTTPRequest:
65+ // - Ensures the HTTP request is valid for the target service.
6766 ParseHTTPRequest (context.Context , * http.Request ) (RequestQoSContext , bool )
6867
69- // ParseWebsocketRequest ensures that a WebSocket request represents a valid request on the target service.
70- // WebSocket connection requests do not have a body so there is no need to parse anything.
71- // As long as the service supports WebSocket connections, this method should return a valid RequestQoSContext.
68+ // ParseWebsocketRequest:
69+ // - Ensures a WebSocket request is valid for the target service.
70+ // - WebSocket connection requests have no body, so no parsing needed.
71+ // - If service supports WebSocket, returns a valid RequestQoSContext.
7272 ParseWebsocketRequest (context.Context ) (RequestQoSContext , bool )
7373}
7474
75- // QoSEndpointCheckGenerator returns one or more service request contexts
76- // that can provide data on the quality of an enpoint by sending it the
77- // corresponding payloads and parsing its response.
78- // These checks are service-specific, i.e. the QoS instance for a
79- // service decides what checks should be done against an endpoint .
75+ // QoSEndpointCheckGenerator
76+ //
77+ // Returns one or more service request contexts that:
78+ // - Provide data on endpoint quality by sending payloads and parsing responses.
79+ // - Checks are service-specific; the QoS instance decides what checks to run .
8080type QoSEndpointCheckGenerator interface {
81- // TODO_FUTURE: add a GetOptionalQualityChecks() method, e.g. to enable
82- // a higher level of quality of service by collecting endpoints' latency
83- // in responding to certain requests.
81+ // TODO_FUTURE:
82+ // - Add GetOptionalQualityChecks() to collect additional QoS data (e.g., endpoint latency).
8483 //
85- // GetRequiredQualityChecks returns the set of quality checks required by
86- // the a QoS instance to assess the validity of an endpoint.
87- // e.g. An EVM-based blockchain service QoS may decide to skip querying an endpoint on
88- // its current block height if it has already failed the chain ID check.
84+ // GetRequiredQualityChecks:
85+ // - Returns required quality checks for a QoS instance to assess endpoint validity.
86+ // - Example: EVM QoS may skip block height check if chain ID check already failed.
8987 GetRequiredQualityChecks (protocol.EndpointAddr ) []RequestQoSContext
9088}
9189
92- // TODO_IMPLEMENT: Add one QoS instance per service that is to be supported by the gateway, implementing the QoSService interface below.
93- // e.g. a QoSService implementation for Ethereum, another for Solana, and third one for a RESTful service .
90+ // TODO_IMPLEMENT:
91+ // - Add a QoS instance per service supported by the gateway (e.g., Ethereum, Solana, RESTful) .
9492//
95- // QoSService represents the embedded definition of a service, e.g. a JSONRPC blockchain.
96- // It is broken into several pieces to clarify its responsibilities:
97- // 1. QoSRequestParser: Translates a service request from a supported format (currently only HTTP) into a service request context.
98- // 2. EndpointSelector: chooses the best endpoint for performing a particular service request.
93+ // QoSService:
94+ // - Represents the embedded definition of a service (e.g., JSONRPC blockchain).
95+ // - Responsibilities:
96+ // 1. QoSRequestParser: Translates service requests (currently only HTTP) into service request contexts.
97+ // 2. EndpointSelector: Chooses the best endpoint for a specific service request.
9998type QoSService interface {
10099 QoSContextBuilder
101100 QoSEndpointCheckGenerator
102101
103- // ApplyObservations is used to apply QoS-related observations to the local QoS instance.
104- // The observations can be either of:
105- // - "local": from requests sent to an endpoint by **THIS** PATH instance
106- // - "shared": from QoS observations shared by **OTHER** PATH instances.
102+ // ApplyObservations:
103+ // - Applies QoS-related observations to the local QoS instance.
104+ // - TODO_FUTURE: Observations can be:
105+ // - "local": from requests sent to an endpoint by THIS PATH instance.
106+ // - "shared": from QoS observations shared by OTHER PATH instances.
107107 ApplyObservations (* qos.Observations ) error
108108
109- // HydrateDisqualifiedEndpointsResponse hydrates the disqualified endpoint response with the QoS-specific data.
109+ // HydrateDisqualifiedEndpointsResponse:
110+ // - Fills the disqualified endpoint response with QoS-specific data.
110111 HydrateDisqualifiedEndpointsResponse (protocol.ServiceID , * devtools.DisqualifiedEndpointResponse )
111112}
0 commit comments