Add initial set of TODOs for batch request processing (#425)

## Summary

TODOs for batch JSONRPC requests feature.

Author: adshmh

gateway/gateway.go

@@ -128,6 +128,12 @@ func (g Gateway) handleHTTPServiceRequest(
 		return
 	}
 
+	// TODO_TECHDEBT(@adshmh): Build a single protocol context to handle a request.
+	// - Obtaining a response to the user's request is protocol context's main responsibility.
+	// - The protocol context can/should:
+	//   - Use fallback endpoints if needed.
+	//   - Launch parallel requests to multiple endpoints if appropriate.
+	//
 	// TODO_CHECK_IF_DONE(@adshmh): Enhance the protocol interface used by the gateway to provide explicit error classification.
 	// Implementation should:
 	//   1. Differentiate between user errors (e.g., invalid Service ID in request) and system errors (e.g., endpoint timeout)

gateway/http_request_context_handle_request.go

@@ -37,6 +37,9 @@ type parallelRequestMetrics struct {
 	overallStartTime         time.Time
 }
 
+// TODO_TECHDEBT(@adshmh): Use a SINGLE protocol context to handle a relay request.
+// - Launching multiple parallel requests to multiple endpoints is an internal protocol decision.
+//
 // HandleRelayRequest sends a relay from the perspective of a gateway.
 //
 // It performs the following steps:
@@ -79,13 +82,23 @@ func (rc *requestContext) handleSingleRelayRequest() error {
 		return err
 	}
 
+	// TODO_TECHDEBT(@adshmh): Ensure the protocol returns exactly one response per service payload:
+	// - Define a struct to contain each service payload and its corresponding response.
+	// - protocol should return this new struct to clarify mapping of service payloads and the corresponding endpoint response.
+	// - QoS packages should use this new struct to prepare the user response.
+	// - Remove the individual endpoint response handling from the gateway package.
+	//
 	for _, endpointResponse := range endpointResponses {
 		rc.qosCtx.UpdateWithResponse(endpointResponse.EndpointAddr, endpointResponse.Bytes)
 	}
 
 	return nil
 }
 
+// TODO_TECHDEBT(@adshmh): Remove this method:
+// Parallel requests are an internal detail of a protocol integration package
+// As of PR #388, `protocol/shannon` is the only protocol integration package.
+//
 // handleParallelRelayRequests orchestrates parallel relay requests and returns the first successful response.
 func (rc *requestContext) handleParallelRelayRequests() error {
 	metrics := &parallelRequestMetrics{

observation/protocol/shannon.pb.go

@@ -309,6 +309,9 @@ message ShannonEndpointObservation {
   // HTTP Response payload size
   optional int64 endpoint_backend_service_http_response_payload_size = 15;
 
+  // TODO_TECHDEBT(@adshmh): Separate fallback endpoints into a separate message:
+  // Most of fields above (e.g. session_id) only apply to a Shannon endpoint.
+  //
   // TODO_CONSIDERATION(@adshmh): Consider renaming to is_gateway_owned OR is_off_protocol.
   //
   // Tracks whether the endpoint is a fallback endpoint.

proto/path/protocol/shannon.proto

@@ -146,6 +146,14 @@ func (rc *requestContext) sendSingleRelay(payload protocol.Payload) (protocol.Re
 	return relayResponse, err
 }
 
+// TODO_TECHDEBT(@adshmh): Single and Multiple payloads should be handled as similarly as possible:
+// - This includes using similar execution paths.
+//
+// TODO_TECHDEBT(@adshmh): Use the same endpoint response processing used in single relay requests:
+// - Use the following on every parallel request:
+//   - handleEndpointSuccess
+//   - handleEndpointError
+//
 // handleParallelRelayRequests orchestrates parallel relay requests to a single endpoint.
 // Uses concurrent processing while maintaining response order and proper error handling.
 func (rc *requestContext) handleParallelRelayRequests(payloads []protocol.Payload) ([]protocol.Response, error) {
@@ -189,6 +197,8 @@ func (rc *requestContext) launchParallelRelays(payloads []protocol.Payload) <-ch
 	return resultChan
 }
 
+// TODO_TECHDEBT(@adshmh): Define/configure limits for the number of parallel requests from a single context.
+//
 // executeParallelRelay handles a single relay request in a goroutine
 func (rc *requestContext) executeParallelRelay(
 	payload protocol.Payload,
@@ -238,6 +248,9 @@ func (rc *requestContext) waitForAllRelayResponses(
 	return rc.convertResultsToResponses(results, firstErr)
 }
 
+// TODO_TECHDEBT(@adshmh): Handle EVERY error encountered in parallel requests.
+// TODO_TECHDEBT(@adshmh): Support multiple endpoints for parallel requests.
+//
 // convertResultsToResponses converts parallel relay results into an array of protocol responses.
 // Maintains the order of responses to match the order of input payloads.
 func (rc *requestContext) convertResultsToResponses(results []parallelRelayResult, firstErr error) ([]protocol.Response, error) {

protocol/shannon/context.go

@@ -188,6 +188,12 @@ const (
 	jsonrpcBatchRequest
 )
 
+// TODO_TECHDEBT(@adshmh): JSONRPC handling should be done in the qos/jsonrpc package:
+// - Parse a []byte into a JSONRPC request: detect whether it is a single or a batch request.
+// - Validate the request: e.g. no duplicate IDs in a batch request.
+// - Determine the response format: e.g. response to a single request formatted as a batch must also be formatted as a batch.
+// - Support building observations.
+//
 // TODO_MVP(@adshmh): Add a JSON-RPC request validator to reject invalid/unsupported
 // method calls early in request flow.
 //
@@ -211,6 +217,8 @@ func parseJSONRPCFromRequestBody(
 		return nil, err
 	}
 
+	// TODO_TECHDEBT(@adshmh): Move the parsing logic to qos/jsonrpc package.
+	//
 	// Step 2: Detect request format (batch vs single)
 	requestFormat := detectRequestFormat(trimmedBody)
 
@@ -225,6 +233,9 @@ func parseJSONRPCFromRequestBody(
 	}
 }
 
+// TODO_TECHDEBT(@adshmh): Move this to qos/jsonrpc package.
+// Parsing (via encoding/json) should handle this without the need for extra validation logic.
+//
 // validateRequestBody performs initial validation on the HTTP request body.
 // It trims whitespace and ensures the body is not empty.
 //
@@ -240,6 +251,10 @@ func validateRequestBody(logger polylog.Logger, requestBody []byte) ([]byte, err
 	return trimmedBody, nil
 }
 
+// TODO_TECHDEBT(@adshmh): Handle all the parsing in qos/jsonrpc package:
+// - No need to check for specific characters.
+// - encoding/json Unmarshaling can handle different cases: single vs. batch.
+//
 // detectRequestFormat analyzes the trimmed request body to determine if it represents
 // a single JSON-RPC request or a batch request.
 //
@@ -263,6 +278,8 @@ func detectRequestFormat(trimmedBody []byte) jsonrpcRequestFormat {
 	}
 }
 
+// TODO_TECHDEBT(@adshmh): move any validation to the qos/jsonrpc package.
+//
 // parseBatchRequest handles parsing of JSON-RPC batch requests (JSON arrays).
 // Performs validation to ensure:
 //   - The array can be unmarshaled into JSON-RPC request structures