How andresxlp/raventree works
Project Overview and Purpose
• Raven Tree is a Go library intended to simplify making HTTP requests. It abstracts away common HTTP functionality by:
– Providing a simple API (e.g., NewRavensTree and SendRaven) that end users can call.
– Supporting various HTTP methods and handling request options (headers, query parameters, JSON body, timeouts).
– Incorporating a retry mechanism with configurable backoff strategies (default, linear, exponential).
Analyzing the File Structure
• Top-Level Files: The project contains Go source files such as:
– backoff.go and backoff_test.go: Define the backoff mechanism and strategies.
– client.go and client_test.go: Likely contain the logic for sending and managing HTTP requests.
– options.go: Defines the Options struct that users provide including host, path, headers, query parameters, timeout, retry count, etc.
– err_collections.go: Manages error handling and possibly error categorization.
– wrapper.go: Possibly wraps the lower-level functionality for easier consumption from the public API.
• Other Items: GitHub workflows, configuration files like .golangci.yml, and docs are for CI and documentation purposes, not the runtime architecture.
Key Architectural Components
a. Public API Layer:
– Components: RavensTree Constructor (NewRavensTree), API method (SendRaven)
– Description: These functions are the entry points for users.
b. Options Management:
– Components: Options struct (options.go) that encapsulates HTTP method, URL details, body, headers, timeout, retry count, and backoff.
– Data flow: Receives configuration from the user and passes it to the internal workflow.
c. Backoff/Retry Engine:
– Components: Backoff struct and its configuration (backoff.go)
– Functionality: Implements the retry logic with different strategies (exponential, linear) and handles timing (BackoffDelay, MaxDelay). This component interacts with the HTTP client on failure to decide if and when to retry a request.
d. HTTP Client and Request Execution:
– Components: Client functionality (client.go) and possibly wrappers (wrapper.go) to enhance the API.
– Functionality: Builds and sends HTTP requests based on Options, manages the actual network call.
e. Error Handling:
– Components: Error collections (err_collections.go)
– Functionality: Captures and processes errors, sending them downstream if a request ultimately fails.
f. Testing & CI Considerations:
– Note: Although not directly part of the runtime system design, tests (backoff_test.go, client_test.go) and CI configuration files help validate the design’s reliability.
Relationships and Interactions
• The user calls NewRavensTree to get a library instance.
• The user then calls SendRaven, passing in an Options struct that contains HTTP request parameters plus backoff and retry settings.
• Inside SendRaven:
– The Options are parsed and prepared.
– The HTTP Client is invoked to send the request.
– If a request fails, the Backoff engine (configured with options from NewBackoff) is triggered to wait and then retry sending the request.
– If errors persist, they are handled and wrapped by the error handling module.
– Initialization (user → NewRavensTree)
– Request configuration (user-specified Options) → HTTP Client
– Error flow from HTTP Client ➜ Backoff Engine ➜ Error Handling