httpclient

README

HTTP Client Library

A Go HTTP client library with built-in caching 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),
)

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

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.WithHeader("Authorization", "Bearer token"),
    httpclient.WithTimeout(5*time.Second),
)

2. 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,
)

3. POST Request with JSON

data := struct {
    Name string `json:"name"`
}{
    Name: "John",
}
resp, err := client.Post(ctx, "/users", data)

⚡️ Features At a Glance

Basic Client

• ✅ Automatic JSON encoding/decoding
• ✅ Custom headers and timeouts
• ✅ Context support
• ✅ Clean, fluent API

Cached Client

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

📝 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

Multiple Cached Endpoints

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

var users []UserData
var posts []PostData

// Setup multiple endpoints
err := client.SetupCachedEndpoint(ctx, CacheConfig{
    Path:       "/users",
    CronSpec:   "*/15 * * * *",
}, &users)

err = client.SetupCachedEndpoint(ctx, CacheConfig{
    Path:       "/posts",
    CronSpec:   "*/30 * * * *",
}, &posts)

Custom Configuration

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

⚠️ 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

🤝 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) (*http.Response, error)
  • func (c *Client) Get(ctx context.Context, path string) (*http.Response, error)
  • func (c *Client) Post(ctx context.Context, path string, body interface{}) (*http.Response, error)
  • func (c *Client) Put(ctx context.Context, path string, body interface{}) (*http.Response, error)
• type Option
  • func WithHeader(key, value string) Option
  • func WithTimeout(timeout time.Duration) Option

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) (*http.Response, error)

Delete performs a DELETE request

func (*Client) Get

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

Get performs a GET request

func (*Client) Post

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

Post performs a POST request

func (*Client) Put

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

Put performs a PUT request

type Option

type Option func(*Client)

func WithHeader

func WithHeader(key, value string) Option

WithHeader adds custom header

func WithTimeout

func WithTimeout(timeout time.Duration) Option

WithTimeout sets custom timeout