httpcache

httpcache

httpcache is a Go package that provides a standards-compliant http.RoundTripper for transparent HTTP response caching, following RFC 9111 (HTTP Caching).

!!! note This package is intended for use as a private (client-side) cache. It is not a shared or proxy cache. It is designed to be used with an HTTP client to cache responses from origin servers, improving performance and reducing load on those servers.

Features

• Plug-and-Play: Drop-in replacement for http.RoundTripper with no additional configuration required.
• RFC 9111 Compliance: Handles validation, expiration, and revalidation. View full compliance details.
• Cache Control: Supports all required HTTP cache control directives, as well as extensions like stale-while-revalidate and stale-if-error.
• Cache Backends: Built-in support for file system and memory caches, with the ability to implement custom backends.
• Extensible: Options for logging, transport and timeouts.
• Debuggable: Adds a cache status header to every response.
• Zero Dependencies: No external dependencies, pure Go implementation.

Demonstration of HTTP caching in action. See _examples/app for code.

Installation

To install the package, run:

go get github.com/bartventer/httpcache

Quick Start

To get started, create a new HTTP client with the httpcache transport, specifying a cache backend DSN. You'll need to register the desired cache backend before using it. Here's an example using the built-in file system cache:

package main

import (
    "log/slog"
    "net/http"
    "time"
    
	"github.com/bartventer/httpcache"
    // Register the file system cache backend
    _ "github.com/bartventer/httpcache/store/fscache" 
)

func main() {
    // Example DSN for the file system cache backend
    dsn := "fscache://?appname=myapp" 
    client := &http.Client{
        Transport: httpcache.NewTransport(
            dsn,
            httpcache.WithSWRTimeout(10*time.Second),
            httpcache.WithLogger(slog.Default()),
    	),
    }
    // ... Use the client as usual
}

!!! tip The DSN (Data Source Name) specifies the cache backend and its configuration. In this example, fscache://?appname=myapp uses the file system cache with an application name of myapp. You can customize the DSN based on the backend you choose.

Cache Backends

Consult the documentation for each backend for specific configuration options and usage details.

Custom Cache Backends

To implement a custom cache backend, create a type that satisfies the store.Cache interface, then register it using the store.Register function. Refer to the built-in backends for examples of how to implement this interface.

Options

Cache Status Header

Every response includes a cache status header to indicate how the response was served. The header is named X-Httpcache-Status and can have the following values:

Example

X-Httpcache-Status: HIT

Limitations

• Range Requests & Partial Content: This cache does not support HTTP range requests or partial/incomplete responses (e.g., status code 206, Range/Content-Range headers). All requests with a Range header are bypassed, and 206 responses are not cached. For example:

  GET /example.txt HTTP/1.1
  Host: example.com
  Range: bytes=0-99
  

  The above request will bypass the cache and fetch the response directly from the origin server. See RFC 9111 §3.3-3.4 for details.

RFC 9111 Compliance Matrix

Legend for Requirements:

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.