httpclient

README

HTTP Client Library

A Go HTTP client library with built-in caching, authentication, and automatic background updates.

🚀 Quick Start (2 minutes)

Basic HTTP Client

// 1. Import the package
import "github.com/samhoque/httpclient"

// 2. Create a client
client := httpclient.NewClient(
    "https://api.example.com",
    httpclient.WithTimeout(10*time.Second),
    httpclient.WithAuth(), // Enable cookie handling
)

// 3. Make requests
// Basic request
resp, err := client.Get(context.Background(), "/users")

// Request with custom headers
resp, err = client.Get(context.Background(), "/users",
    httpclient.WithRequestHeader("X-Request-ID", "123"),
)

// POST with data
resp, err = client.Post(context.Background(), "/users", user)

Authentication Example

// Create client with auth enabled
client := httpclient.NewClient(
    "https://api.example.com",
    httpclient.WithAuth(),
)

// Login - cookies will be automatically saved
loginData := struct {
    Username string `json:"username"`
    Password string `json:"password"`
}{
    Username: "user@example.com",
    Password: "password123",
}
resp, err := client.Post(ctx, "/login", loginData)

// Subsequent requests will automatically include saved cookies
resp, err = client.Get(ctx, "/protected-endpoint")

Cached HTTP Client

// 1. Create a cached client
client := httpclient.NewCachedClient("https://api.example.com")
defer client.Stop()

// 2. Define your data structure
var users []struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}

// 3. Setup automatic cache updates
err := client.SetupCachedEndpoint(
    context.Background(),
    httpclient.CacheConfig{
        Path:       "/users",
        CronSpec:   "*/15 * * * *",  // Every 15 minutes
        Expiration: 20 * time.Minute,
    },
    &users,
)

// 4. Use the cached data
data, err := client.GetCached("/users")

📦 Installation

go get github.com/samhoque/httpclient

🔥 Common Use Cases

1. API Client with Authentication

client := httpclient.NewClient(
    "https://api.example.com",
    httpclient.WithAuth(),
    httpclient.WithTimeout(5*time.Second),
)

2. Per-Request Headers

// Add custom headers for specific requests
resp, err := client.Get(ctx, "/users", 
    httpclient.WithRequestHeader("X-Custom-Header", "value"),
    httpclient.WithRequestHeader("X-Request-ID", "123"),
)

// Different headers for another request
resp, err = client.Post(ctx, "/data", data,
    httpclient.WithRequestHeader("Authorization", "Bearer token"),
)

3. Cached API Data with Auto-Updates

client := httpclient.NewCachedClient("https://api.example.com")
defer client.Stop()

var prices []PriceData
err := client.SetupCachedEndpoint(
    context.Background(),
    httpclient.CacheConfig{
        Path:       "/prices",
        CronSpec:   "*/5 * * * *",  // Update every 5 minutes
        Expiration: 10 * time.Minute,
    },
    &prices,
)

⚡️ Features At a Glance

Basic Client

• ✅ Automatic JSON encoding/decoding
• ✅ Custom headers and timeouts
• ✅ Context support
• ✅ Clean, fluent API
• ✅ Per-request headers
• ✅ Cookie-based authentication

Authentication

• ✅ Automatic cookie handling
• ✅ Session persistence
• ✅ Support for cookie-based auth flows
• ✅ Per-request header customization

Cached Client

• ✅ Automatic background updates
• ✅ In-memory caching
• ✅ Configurable update schedules
• ✅ Thread-safe operations

🔧 Configuration Options

Client Options

• WithTimeout(duration) - Set client timeout
• WithHeader(key, value) - Add default headers
• WithAuth() - Enable cookie handling

Request Options

• WithRequestHeader(key, value) - Add headers to specific requests

📝 Common Cron Patterns

CacheConfig{
    CronSpec: "*/15 * * * *"  // Every 15 minutes
    CronSpec: "0 * * * *"     // Every hour
    CronSpec: "0 0 * * *"     // Every day at midnight
}

🚨 Error Handling

// Basic error handling
resp, err := client.Get(ctx, "/users")
if err != nil {
    if errors.Is(err, context.DeadlineExceeded) {
        // Handle timeout
    }
    return err
}
defer resp.Body.Close()

// Cache error handling
data, err := client.GetCached("/users")
if err != nil {
    // If cache expired, fetch fresh data
    data, err = client.GetCachedOrFetch(ctx, "/users")
}

🔍 Advanced Usage

Authentication with Custom Headers

client := httpclient.NewClient(
    "https://api.example.com",
    httpclient.WithAuth(),
)

// Login with custom headers
resp, err := client.Post(ctx, "/login", loginData,
    httpclient.WithRequestHeader("X-Device-ID", "device123"),
)

// Subsequent authenticated requests
resp, err = client.Get(ctx, "/profile",
    httpclient.WithRequestHeader("X-Request-ID", "req123"),
)

Custom Configuration

client := httpclient.NewClient(
    "https://api.example.com",
    httpclient.WithAuth(),
    httpclient.WithTimeout(5*time.Second),
    httpclient.WithHeader("X-API-Key", "key"),
)

⚠️ Common Gotchas

1. Always defer client.Stop() for cached clients
2. Always defer resp.Body.Close() for responses
3. Cache expiration is separate from update schedule
4. Cookie handling requires WithAuth() option

🤝 Need Help?

• Report issues: GitHub Issues
• Contribute: GitHub Repository

Full API Reference

For complete API documentation, see our GoDoc.

Documentation

Overview

Package httpclient provides a flexible HTTP client with caching capabilities.

The package offers two main types of clients: 1. A basic HTTP client with simplified request methods 2. A cached client that supports automatic background updates

Basic usage:

client := httpclient.NewClient("https://api.example.com")
resp, err := client.Get(context.Background(), "/users")

Cached client usage:

client := httpclient.NewCachedClient("https://api.example.com")
defer client.Stop()

Index

• type CacheConfig
• type CacheEntry
• type CachedClient
  • func NewCachedClient(baseURL string, opts ...Option) *CachedClient
  • func (c *CachedClient) GetCached(path string) (interface{}, error)
  • func (c *CachedClient) GetCachedOrFetch(ctx context.Context, path string) (interface{}, error)
  • func (c *CachedClient) SetupCachedEndpoint(ctx context.Context, config CacheConfig, result interface{}) error
  • func (c *CachedClient) Stop()
  • func (c *CachedClient) StopCacheUpdates(path string)
• type Client
  • func NewClient(baseURL string, opts ...Option) *Client
  • func (c *Client) Delete(ctx context.Context, path string, opts ...RequestOption) (*http.Response, error)
  • func (c *Client) Get(ctx context.Context, path string, opts ...RequestOption) (*http.Response, error)
  • func (c *Client) Post(ctx context.Context, path string, body interface{}, opts ...RequestOption) (*http.Response, error)
  • func (c *Client) Put(ctx context.Context, path string, body interface{}, opts ...RequestOption) (*http.Response, error)
• type Option
  • func WithAuth() Option
  • func WithHeader(key, value string) Option
  • func WithTimeout(timeout time.Duration) Option
• type RequestOption
  • func WithRequestHeader(key, value string) RequestOption

Types

type CacheConfig

type CacheConfig struct {
	Path             string        // API endpoint path
	CronSpec         string        // Cron specification for updates
	Expiration       time.Duration // How long the cache is valid
	SkipInitialFetch bool          // Skip the initial fetch on startup
}

CacheConfig defines the configuration for a cached endpoint

type CacheEntry

type CacheEntry struct {
	Data       interface{}
	UpdatedAt  time.Time
	Expiration time.Duration
}

type CachedClient

type CachedClient struct {
	*Client
	// contains filtered or unexported fields
}

CachedClient extends our base HTTP client with caching capabilities

func NewCachedClient

func NewCachedClient(baseURL string, opts ...Option) *CachedClient

func (*CachedClient) GetCached

func (c *CachedClient) GetCached(path string) (interface{}, error)

GetCached retrieves data from cache if available and not expired

func (*CachedClient) GetCachedOrFetch

func (c *CachedClient) GetCachedOrFetch(ctx context.Context, path string) (interface{}, error)

GetCachedOrFetch gets data from cache if available and not expired, otherwise fetches fresh data

func (*CachedClient) SetupCachedEndpoint

func (c *CachedClient) SetupCachedEndpoint(ctx context.Context, config CacheConfig, result interface{}) error

SetupCachedEndpoint configures automatic updates for a specific endpoint

func (*CachedClient) Stop

func (c *CachedClient) Stop()

func (*CachedClient) StopCacheUpdates

func (c *CachedClient) StopCacheUpdates(path string)

StopCacheUpdates stops the cron job for a specific endpoint

type Client

type Client struct {
	// contains filtered or unexported fields
}

func NewClient

func NewClient(baseURL string, opts ...Option) *Client

NewClient creates a new HTTP client with default configurations

func (*Client) Delete

func (c *Client) Delete(ctx context.Context, path string, opts ...RequestOption) (*http.Response, error)

Delete performs a DELETE request

func (*Client) Get

func (c *Client) Get(ctx context.Context, path string, opts ...RequestOption) (*http.Response, error)

Get performs a GET request

func (*Client) Post

func (c *Client) Post(ctx context.Context, path string, body interface{}, opts ...RequestOption) (*http.Response, error)

Post performs a POST request

func (*Client) Put

func (c *Client) Put(ctx context.Context, path string, body interface{}, opts ...RequestOption) (*http.Response, error)

Put performs a PUT request

type Option

type Option func(*Client)

func WithAuth

func WithAuth() Option

WithAuth enables cookie handling for authentication

func WithHeader

func WithHeader(key, value string) Option

WithHeader adds custom header

func WithTimeout

func WithTimeout(timeout time.Duration) Option

WithTimeout sets custom timeout

type RequestOption

type RequestOption func(*http.Request)

RequestOption defines per-request configuration

func WithRequestHeader

func WithRequestHeader(key, value string) RequestOption

WithRequestHeader adds a header for a single request