[
https://issues.apache.org/jira/browse/CASSANDRA-21195?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18083106#comment-18083106
]
BHARATH KUMAR edited comment on CASSANDRA-21195 at 5/24/26 12:07 AM:
---------------------------------------------------------------------
*Phase 1 Patch: Initial HttpUtil Implementation*
Attached patch {{[^CASSANDRA-21195.patch]}} implements Phase 1 of the HTTP
utility extraction.
*What's Included*
*New File:* {{src/java/org/apache/cassandra/utils/HttpUtil.java}} (308 lines)
*Key Components:*
* {{HttpConfig}} class - Encapsulates configurable timeouts and headers
* {{HttpResponse}} class - Contains status code, status message, and raw
response body
* {{executeGet(url, config)}} - Convenience method for GET requests
* {{execute(url, method, config)}} - Generic method supporting any HTTP method
(GET, PUT, POST, DELETE)
* {{HttpException}} - Structured exception with response code and message
* Comprehensive logging using SLF4J (DEBUG, TRACE, WARN, ERROR levels)
*Design Decisions*
*Synchronous Only:* Appropriate for startup-time operations (metadata
retrieval, secret fetching, keystore password retrieval).
*Method Flexibility:*
* GET is the default (95% of use cases - all cloud metadata queries)
* PUT explicitly supported (5% of use cases - AWS IMDSv2 token retrieval)
* The Generic {{execute()}} method allows any HTTP method for future
extensibility
*No Mandatory Requirements:* Caller controls method, headers, and tokens. No
assumptions about authentication or service-specific requirements.
*Extracted Pattern:* Based on
{{AbstractCloudMetadataServiceConnector.apiCall()}} (lines 100-135),
maintaining the same behavior and response handling.
*Logging Coverage*
* DEBUG: Request initiation, configuration, response timing, status codes
* TRACE: Headers, body content (truncated if >1000 bytes), connection lifecycle
* WARN: HTTP error statuses (4xx, 5xx)
* ERROR: IOExceptions with full context and timing
*Verified Against Current Usage*
*Analyzed all cloud snitch implementations:*
* {{{}Ec2Snitch{}}}, {{{}AzureSnitch{}}}, {{{}GoogleCloudSnitch{}}},
{{{}AlibabaCloudSnitch{}}}, {
Unknown macro: \{CloudstackSnitch}
}
* All use GET for metadata queries
* {{Ec2MetadataServiceConnector.V2Connector}} uses PUT for AWS IMDSv2 token
retrieval
* HttpUtil supports both patterns
*Zero Behavioral Impact*
This patch introduces the utility {*}without modifying any existing code{*}. No
cloud metadata connectors have been changed. This ensures:
* No risk of breaking existing functionality
* Safe to merge independently
* Foundation for Phase 2 refactoring
*Next Steps*
* Phase 2: Refactor {{AbstractCloudMetadataServiceConnector}} to use HttpUtil
* Phase 3: Add unit tests for HttpUtil
* Phase 4: Extend with additional functionality if needed
was (Author: JIRAUSER301713):
*Phase 1 Patch: Initial HttpUtil Implementation*
Attached patch {{[^CASSANDRA-21195.patch]}} implements Phase 1 of the HTTP
utility extraction.
*What's Included*
*New File:* \{{src/java/org/apache/cassandra/utils/HttpUtil.java}} (308 lines)
*Key Components:*
* \{{HttpConfig}} class - Encapsulates configurable timeouts and headers
* \{{HttpResponse}} class - Contains status code, status message, and raw
response body
* \{{executeGet(url, config)}} - Convenience method for GET requests
* {\{execute(url, method, config)}} - Generic method supporting any HTTP
method (GET, PUT, POST, DELETE)
* \{{HttpException}} - Structured exception with response code and message
* Comprehensive logging using SLF4J (DEBUG, TRACE, WARN, ERROR levels)
*Design Decisions*
*Synchronous Only:* Appropriate for startup-time operations (metadata
retrieval, secret fetching, keystore password retrieval).
*Method Flexibility:*
* GET is the default (95% of use cases - all cloud metadata queries)
* PUT explicitly supported (5% of use cases - AWS IMDSv2 token retrieval)
* The Generic \{{execute()}} method allows any HTTP method for future
extensibility
*No Mandatory Requirements:* Caller controls method, headers, and tokens. No
assumptions about authentication or service-specific requirements.
*Extracted Pattern:* Based on
\{{AbstractCloudMetadataServiceConnector.apiCall()}} (lines 100-135),
maintaining the same behavior and response handling.
*Logging Coverage*
* DEBUG: Request initiation, configuration, response timing, status codes
* TRACE: Headers, body content (truncated if >1000 bytes), connection lifecycle
* WARN: HTTP error statuses (4xx, 5xx)
* ERROR: IOExceptions with full context and timing
*Verified Against Current Usage*
*Analyzed all cloud snitch implementations:*
* {\{Ec2Snitch}}, \{{AzureSnitch}}, \{{GoogleCloudSnitch}},
\{{AlibabaCloudSnitch}}, \{{CloudstackSnitch}}
* All use GET for metadata queries
* {\{Ec2MetadataServiceConnector.V2Connector}} uses PUT for AWS IMDSv2 token
retrieval
* HttpUtil supports both patterns
*Zero Behavioral Impact*
This patch introduces the utility {*}without modifying any existing code{*}. No
cloud metadata connectors have been changed. This ensures:
* No risk of breaking existing functionality
* Safe to merge independently
* Foundation for Phase 2 refactoring
*Next Steps*
* Phase 2: Refactor \{{AbstractCloudMetadataServiceConnector}} to use
\{{HttpUtil}}
* Phase 3: Add unit tests for \{{HttpUtil}}
* Phase 4: Extend with additional functionality if needed
> Extract HTTP-related code around cloud snitches so it can be reusable across
> the codebase
> -----------------------------------------------------------------------------------------
>
> Key: CASSANDRA-21195
> URL: https://issues.apache.org/jira/browse/CASSANDRA-21195
> Project: Apache Cassandra
> Issue Type: Task
> Components: Legacy/Core
> Reporter: Stefan Miklosovic
> Assignee: BHARATH KUMAR
> Priority: Normal
> Attachments: CASSANDRA-21195.patch
>
>
> *Overview*
> Several components in Apache Cassandra require making HTTP calls to external
> services (e.g., cloud metadata services or external authentication
> providers). Currently, HTTP logic exists within specific implementations such
> as {{{}AbstractCloudMetadataServiceConnector{}}}, which limits reuse and
> leads to duplication when additional components require a similar
> functionality.
> This proposal introduces a generic, reusable HTTP utility in the {{utils}}
> package that can be leveraged across Cassandra components requiring
> synchronous HTTP interactions.
> *Goals*
> * Introduce a generic HTTP utility that can be reused across the Cassandra
> codebase
> * Avoid modifying existing behavior during the initial implementation
> * Refactor existing cloud metadata connectors to leverage the shared utility
> * Provide a foundation that can support additional HTTP methods and use
> cases in the future
> * Keep response parsing outside the utility to maintain separation of
> concerns
> *Non-Goals*
> The following are intentionally out of scope for the initial implementation:
> * Introducing asynchronous HTTP clients
> * Implementing automatic response parsing
> * Adding external dependencies
> * Changing existing public interfaces
> * Modifying the behavior of existing cloud metadata connectors
> The goal is strictly to extract and centralize HTTP logic, not redesign the
> existing functionality.
> *Design Principles*
> # *Simplicity* - The utility will support synchronous HTTP requests only
> # *Reusability* - Minimal interface that allows reuse across different
> Cassandra components
> # *Separation of Concerns* - Utility responsible only for executing HTTP
> requests and returning raw responses; parsing remains the caller's
> responsibility
> # *Backward Compatibility* - Existing functionality must remain unchanged
> during early phases
> *Implementation Plan*
> The implementation will be delivered in phases:
> *Phase 1: Introduce HTTP Utility*
> * Create a new {{HttpUtil}} class in {{org.apache.cassandra.utils}} package
> * Encapsulate common HTTP logic from cloud metadata connectors
> * Support synchronous HTTP requests with configurable timeouts and headers
> * No modifications to existing classes (zero behavioral impact)
> *Phase 2: Refactor Cloud Metadata Implementations*
> * Update existing cloud metadata implementations to use {{HttpUtil}}
> internally
> * Replace duplicated HTTP code with a shared utility
> * Preserve existing external behavior and APIs
> *Phase 3: Validation and Regression Testing*
> * Ensure all cloud metadata implementations behave exactly as before
> * Validate through existing tests
> * Confirm no regressions in metadata retrieval or authentication flows
> *Phase 4: Extend the HTTP Utility*
> * Add support for additional HTTP methods (POST, PUT, DELETE)
> * Improve header handling
> * Add reusable configuration patterns
> *Phase 5: Maintain Clear Response Handling Boundaries*
> * Keep utility transport-focused only
> * Execute HTTP request and return raw response
> * Response parsing remains with the calling implementation
> *Current HTTP Usage in Cassandra*
> *Analysis of existing code shows:*
> * {*}GET requests{*}: Used by all cloud metadata services (AWS EC2, Azure,
> GCP, Alibaba Cloud, Cloudstack)
> * {*}PUT requests{*}: Used by AWS IMDSv2 for token retrieval
> ({{{}Ec2MetadataServiceConnector.V2Connector{}}})
> * Pattern: {{AbstractCloudMetadataServiceConnector.apiCall()}} method (lines
> 100-135)
> *Benefits*
> * *Reduced Code Duplication* - HTTP logic centralized rather than
> reimplemented
> * *Improved Maintainability* - Bug fixes/improvements in one place
> * *Better Extensibility* - Future features can reuse the same utility
> * *Low Risk Migration* - Phased approach ensures minimal disruption
> *Future Opportunities*
> Once stable, the utility may be reused for:
> * External secret managers (HashiCorp Vault)
> * Metadata services
> * Authentication integrations
> * Configuration services
> This utility could become the standard HTTP interaction mechanism within
> Cassandra for startup-time operations.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
