feat: add key conflict validation for component request options

Author: ChristoGrab

airbyte_cdk/sources/declarative/requesters/paginators/default_paginator.py

@@ -23,6 +23,7 @@
 )
 from airbyte_cdk.sources.declarative.requesters.request_path import RequestPath
 from airbyte_cdk.sources.types import Config, Record, StreamSlice, StreamState
+from airbyte_cdk.utils.mapping_helpers import combine_mappings, _validate_multiple_request_options
 
 
 @dataclass
@@ -112,6 +113,13 @@ def __post_init__(self, parameters: Mapping[str, Any]) -> None:
             )
         if isinstance(self.url_base, str):
             self.url_base = InterpolatedString(string=self.url_base, parameters=parameters)
+        
+        if self.page_token_option and not isinstance(self.page_token_option, RequestPath):
+            _validate_multiple_request_options(
+                self.config,
+                self.page_size_option,
+                self.page_token_option,
+            )
 
     def get_initial_token(self) -> Optional[Any]:
         """

airbyte_cdk/utils/mapping_helpers.py

@@ -6,6 +6,8 @@
 import copy
 from typing import Any, Dict, List, Mapping, Optional, Union
 
+from airbyte_cdk.sources.declarative.requesters.request_option import RequestOption, RequestOptionType
+from airbyte_cdk.sources.types import Config
 
 def _merge_mappings(
     target: Dict[str, Any],
@@ -33,13 +35,13 @@ def _merge_mappings(
             if isinstance(target_value, dict) and isinstance(source_value, dict):
                 # Only body_json supports nested_structures
                 if not allow_same_value_merge:
-                    raise ValueError(f"Duplicate keys found: {'.'.join(current_path)}")
+                    raise ValueError(f"Request body collision, duplicate keys detected at: {'.'.join(current_path)}. Please ensure that all keys in request are unique.")
                 # If both are dictionaries, recursively merge them
                 _merge_mappings(target_value, source_value, current_path, allow_same_value_merge)
 
             elif not allow_same_value_merge or target_value != source_value:
                 # If same key has different values, that's a conflict
-                raise ValueError(f"Duplicate keys found: {'.'.join(current_path)}")
+                raise ValueError(f"Request body collision, duplicate keys detected at: {'.'.join(current_path)}. Please ensure that all keys in request are unique.")
         else:
             # No conflict, just copy the value (using deepcopy for nested structures)
             target[key] = copy.deepcopy(source_value)
@@ -102,3 +104,37 @@ def combine_mappings(
             _merge_mappings(result, mapping, allow_same_value_merge=allow_same_value_merge)
 
     return result
+
+def _validate_multiple_request_options(
+    config: Config,
+    *request_options: Optional[RequestOption]
+) -> None:
+    """
+    Validates that a component with multiple request options does not have conflicting paths.
+    Uses dummy values for validation since actual values might not be available at init time.
+    """
+    grouped_options: Dict[RequestOptionType, List[RequestOption]] = {}
+    for option in request_options:
+        if option:
+            grouped_options.setdefault(option.inject_into, []).append(option)
+            
+    for inject_type, options in grouped_options.items():
+        if len(options) <= 1:
+            continue
+        
+        option_dicts: List[Optional[Union[Mapping[str, Any], str]]] = []
+        for i, option in enumerate(options):
+            option_dict: Dict[str, Any] = {}
+            # Use indexed dummy values to ensure we catch conflicts
+            option.inject_into_request(option_dict, f"dummy_value_{i}", config)
+            option_dicts.append(option_dict)
+            
+        try:
+            combine_mappings(
+                option_dicts,
+                allow_same_value_merge=(inject_type == RequestOptionType.body_json)
+            )
+        except ValueError as e:
+            print(e)
+            raise ValueError(f"Conflict mapping request options: {e}") from e
+