httpclient

Documentation

Overview

httpclient/client.go

The `http_client` package provides a configurable HTTP client tailored for interacting with specific APIs.

It supports different authentication methods, including "bearer" and "oauth". The client is designed with a focus on concurrency management, structured error handling, and flexible configuration options. The package offers a default timeout, custom backoff strategies, dynamic rate limiting, and detailed logging capabilities. The main `Client` structure encapsulates all necessary components, like the baseURL, authentication details, and an embedded standard HTTP client.

httpclient/client_configuration.go Description: This file contains functions to load and validate configuration values from a JSON file or environment variables.

httpclient/download.go

httpclient/ping.go

httpclient/request.go

Index

• Constants
• func DetermineAuthMethod(authConfig AuthConfig) (string, error)
• type AuthConfig
• type Client
  • func BuildClient(config ClientConfig) (*Client, error)
  • func (c *Client) DoDownloadRequest(method, endpoint string, out io.Writer) (*http.Response, error)
  • func (c *Client) DoMultiPartRequest(method, endpoint string, files map[string][]string, ...) (*http.Response, error)
  • func (c *Client) DoPing(host string, timeout time.Duration) error
  • func (c *Client) DoPole(method, endpoint string, body, out interface{}) (*http.Response, error)
  • func (c *Client) DoRequest(method, endpoint string, body, out interface{}) (*http.Response, error)
• type ClientConfig
  • func LoadConfigFromEnv(config *ClientConfig) (*ClientConfig, error)
  • func LoadConfigFromFile(filePath string) (*ClientConfig, error)
• type ClientOptions
• type ConcurrencyConfig
• type CookieConfig
• type EnvironmentConfig
• type LoggingConfig
• type RedirectConfig
• type RetryConfig
• type TimeoutConfig
• type UploadState

Constants

const (
	DefaultLogLevel                  = logger.LogLevelInfo
	DefaultMaxRetryAttempts          = 3
	DefaultEnableDynamicRateLimiting = true
	DefaultMaxConcurrentRequests     = 5
	DefaultTokenBufferPeriod         = helpers.JSONDuration(5 * time.Minute)
	DefaultTotalRetryDuration        = helpers.JSONDuration(5 * time.Minute)
	DefaultTimeout                   = helpers.JSONDuration(10 * time.Second)
	FollowRedirects                  = true
	MaxRedirects                     = 10
	ConfigFileExtension              = ".json"
)

Functions

func DetermineAuthMethod

func DetermineAuthMethod(authConfig AuthConfig) (string, error)

DetermineAuthMethod determines the authentication method based on the provided credentials. It prefers strong authentication methods (e.g., OAuth) over weaker ones (e.g., bearer tokens). It logs an error and returns "unknown" if no valid credentials are provided.

Types

type AuthConfig

type AuthConfig struct {
	Username     string `json:"Username,omitempty"`
	Password     string `json:"Password,omitempty"`
	ClientID     string `json:"ClientID,omitempty"`
	ClientSecret string `json:"ClientSecret,omitempty"`
}

AuthConfig represents the structure to read authentication details from a JSON configuration file.

type Client

type Client struct {
	AuthMethod string    // Specifies the authentication method: "bearer" or "oauth"
	Token      string    // Authentication Token
	Expiry     time.Time // Expiry time set for the auth token

	Logger             logger.Logger                           // Logger for logging messages
	ConcurrencyHandler *concurrency.ConcurrencyHandler         // ConcurrencyHandler for managing concurrent requests
	APIHandler         apihandler.APIHandler                   // APIHandler interface used to define which API handler to use
	AuthTokenHandler   *authenticationhandler.AuthTokenHandler // AuthTokenHandler for managing authentication
	// contains filtered or unexported fields
}

Client represents an HTTP client to interact with a specific API.

func BuildClient

func BuildClient(config ClientConfig) (*Client, error)

BuildClient creates a new HTTP client with the provided configuration.

func (*Client) DoDownloadRequest

func (c *Client) DoDownloadRequest(method, endpoint string, out io.Writer) (*http.Response, error)

DoDownloadRequest performs a download from a given URL. It follows the same authentication, header setting, and URL construction as the DoMultipartRequest function. The downloaded data is written to the provided writer.

Parameters: - method: The HTTP method to use (e.g., GET). - endpoint: The API endpoint from which the file will be downloaded. - out: A writer where the downloaded data will be written.

Returns: - A pointer to the http.Response received from the server. - An error if the request could not be sent or the response could not be processed.

The function first validates the authentication token, constructs the full URL for the request, sets the required headers (including Authorization), and sends the request.

If debug mode is enabled, the function logs all the request headers before sending the request. After the request is sent, the function checks the response status code. If the response is not within the success range (200-299), it logs an error and returns the response and an error. If the response is successful, the function writes the response body to the provided writer.

Note: The caller should handle closing the response body when successful.

func (*Client) DoMultiPartRequest

func (c *Client) DoMultiPartRequest(method, endpoint string, files map[string][]string, formDataFields map[string]string, fileContentTypes map[string]string, formDataPartHeaders map[string]http.Header, out interface{}) (*http.Response, error)

Example: var result MyResponseType resp, err := client.DoMultiPartRequest("POST", "/api/upload", files, formDataFields, fileContentTypes, formDataPartHeaders, &result)

if err != nil {
    // Handle error
}

// Use `result` or `resp` as needed

func (*Client) DoPing

func (c *Client) DoPing(host string, timeout time.Duration) error

func (*Client) DoPole

func (c *Client) DoPole(method, endpoint string, body, out interface{}) (*http.Response, error)

Example: var result MyResponseType resp, err := client.DoPing("GET", "/api/health", nil, &result)

if err != nil {
    // Handle error
}

// Process response

func (*Client) DoRequest

func (c *Client) DoRequest(method, endpoint string, body, out interface{}) (*http.Response, error)

type ClientConfig

type ClientConfig struct {
	Auth          AuthConfig        // User can either supply these values manually or pass from LoadAuthConfig/Env vars
	Environment   EnvironmentConfig // User can either supply these values manually or pass from LoadAuthConfig/Env vars
	ClientOptions ClientOptions     // Optional configuration options for the HTTP Client
}

Config holds configuration options for the HTTP Client.

func LoadConfigFromEnv

func LoadConfigFromEnv(config *ClientConfig) (*ClientConfig, error)

LoadConfigFromEnv populates the ClientConfig structure with values from environment variables. It updates the configuration for authentication, environment specifics, and client options based on the presence of environment variables. For each configuration option, if an environment variable is set, its value is used; otherwise, the existing value in the ClientConfig structure is retained. It also sets default values if necessary and validates the final configuration, returning an error if the configuration is incomplete.

func LoadConfigFromFile

func LoadConfigFromFile(filePath string) (*ClientConfig, error)

LoadConfigFromFile loads configuration values from a JSON file into the ClientConfig struct. This function opens the specified configuration file, reads its content, and unmarshals the JSON data into the ClientConfig struct. It's designed to initialize the client configuration with values from a file, complementing or overriding defaults and environment variable settings.

type ClientOptions

type ClientOptions struct {
	Logging     LoggingConfig     // Configuration related to logging
	Cookies     CookieConfig      // Cookie handling settings
	Retry       RetryConfig       // Retry behavior configuration
	Concurrency ConcurrencyConfig // Concurrency configuration
	Timeout     TimeoutConfig     // Custom timeout settings
	Redirect    RedirectConfig    // Redirect handling settings
}

ClientOptions holds optional configuration options for the HTTP Client.

type ConcurrencyConfig

type ConcurrencyConfig struct {
	MaxConcurrentRequests int // Maximum number of concurrent requests allowed.
}

ConcurrencyConfig holds configuration related to concurrency management.

type CookieConfig

type CookieConfig struct {
	EnableCookieJar bool              // Enable or disable cookie jar
	CustomCookies   map[string]string `json:"CustomCookies,omitempty"` // Key-value pairs for setting specific cookies
}

CookieConfig holds configuration related to cookie handling.

type EnvironmentConfig

type EnvironmentConfig struct {
	APIType            string `json:"APIType,omitempty"`            // APIType specifies the type of API integration to use
	InstanceName       string `json:"InstanceName,omitempty"`       // Website Instance name without the root domain
	OverrideBaseDomain string `json:"OverrideBaseDomain,omitempty"` // Base domain override used when the default in the api handler isn't suitable
	TenantID           string `json:"TenantID,omitempty"`           // TenantID is the unique identifier for the tenant
	TenantName         string `json:"TenantName,omitempty"`         // TenantName is the name of the tenant
}

EnvironmentConfig represents the structure to read authentication details from a JSON configuration file.

type LoggingConfig

type LoggingConfig struct {
	LogLevel            string // Tiered logging level.
	LogOutputFormat     string // Output format of the logs. Use "JSON" for JSON format, "console" for human-readable format
	LogConsoleSeparator string // Separator in console output format.
	LogExportPath       string // Path to output logs to.
	HideSensitiveData   bool   // Whether sensitive fields should be hidden in logs.
}

LoggingConfig holds configuration options related to logging.

type RedirectConfig

type RedirectConfig struct {
	FollowRedirects bool // Enable or disable following redirects
	MaxRedirects    int  // Maximum number of redirects to follow
}

RedirectConfig holds configuration related to redirect handling.

type RetryConfig

type RetryConfig struct {
	MaxRetryAttempts          int  // Maximum number of retry request attempts for retryable HTTP methods.
	EnableDynamicRateLimiting bool // Whether dynamic rate limiting should be enabled.
}

RetryConfig holds configuration related to retry behavior.

type TimeoutConfig

type TimeoutConfig struct {
	CustomTimeout            helpers.JSONDuration // Custom timeout for the HTTP client
	TokenRefreshBufferPeriod helpers.JSONDuration // Buffer period before token expiry to attempt token refresh
	TotalRetryDuration       helpers.JSONDuration // Total duration to attempt retries
}

type UploadState

type UploadState struct {
	LastUploadedByte int64
	sync.Mutex
}

UploadState represents the state of an upload operation, including the last uploaded byte. This struct is used to track the progress of file uploads for resumable uploads and to resume uploads from the last uploaded byte.