package module
Version: v0.1.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Apr 1, 2021 License: Apache-2.0 Imports: 3 Imported by: 156


cachecontrol: HTTP Caching Parser and Interpretation

PkgGoDevBuild Status

cachecontrol implements RFC 7234 Hypertext Transfer Protocol (HTTP/1.1): Caching. It does this by parsing the Cache-Control and other headers, providing information about requests and responses -- but cachecontrol does not implement an actual cache backend, just the control plane to make decisions about if a particular response is cachable.


cachecontrol.CachableResponse returns an array of reasons why a response should not be cached and when it expires. In the case that len(reasons) == 0, the response is cachable according to the RFC. However, some people want non-compliant caches for various business use cases, so each reason is specifically named, so if your cache wants to cache POST requests, it can easily do that, but still be RFC compliant in other situations.


Can you cache

package main

import (


func main() {
	req, _ := http.NewRequest("GET", "", nil)

	res, _ := http.DefaultClient.Do(req)
	_, _ = ioutil.ReadAll(res.Body)

	reasons, expires, _ := cachecontrol.CachableResponse(req, res, cachecontrol.Options{})

	fmt.Println("Reasons to not cache: ", reasons)
	fmt.Println("Expiration: ", expires.String())

Can I use this in a high performance caching server?

cachecontrol is divided into two packages: cachecontrol with a high level API, and a lower level cacheobject package. Use Object in a high performance use case where you have previously parsed headers containing dates or would like to avoid memory allocations.

package main

import (


func main() {
	req, _ := http.NewRequest("GET", "", nil)

	res, _ := http.DefaultClient.Do(req)
	_, _ = ioutil.ReadAll(res.Body)

	reqDir, _ := cacheobject.ParseRequestCacheControl(req.Header.Get("Cache-Control"))

	resDir, _ := cacheobject.ParseResponseCacheControl(res.Header.Get("Cache-Control"))
	expiresHeader, _ := http.ParseTime(res.Header.Get("Expires"))
	dateHeader, _ := http.ParseTime(res.Header.Get("Date"))
	lastModifiedHeader, _ := http.ParseTime(res.Header.Get("Last-Modified"))

	obj := cacheobject.Object{
		RespDirectives:         resDir,
		RespHeaders:            res.Header,
		RespStatusCode:         res.StatusCode,
		RespExpiresHeader:      expiresHeader,
		RespDateHeader:         dateHeader,
		RespLastModifiedHeader: lastModifiedHeader,

		ReqDirectives: reqDir,
		ReqHeaders:    req.Header,
		ReqMethod:     req.Method,

		NowUTC: time.Now().UTC(),
	rv := cacheobject.ObjectResults{}

	cacheobject.CachableObject(&obj, &rv)
	cacheobject.ExpirationObject(&obj, &rv)

	fmt.Println("Errors: ", rv.OutErr)
	fmt.Println("Reasons to not cache: ", rv.OutReasons)
	fmt.Println("Warning headers to add: ", rv.OutWarnings)
	fmt.Println("Expiration: ", rv.OutExpirationTime.String())

Improvements, bugs, adding features, and taking cachecontrol new directions!

Please open issues in Github for ideas, bugs, and general thoughts. Pull requests are of course preferred :)


cachecontrol has recieved significant contributions from:


cachecontrol is licensed under the Apache License, Version 2.0



Package cachecontrol implements the logic for HTTP Caching

Deciding if an HTTP Response can be cached is often harder and more bug prone than an actual cache storage backend. cachecontrol provides a simple interface to determine if request and response pairs are cachable as defined under RFC 7234



This section is empty.


This section is empty.


func CachableResponse

func CachableResponse(req *http.Request,
	resp *http.Response,
	opts Options) ([]cacheobject.Reason, time.Time, error)

Given an HTTP Request and Response, determine the possible reasons a response SHOULD NOT be cached.

func CachableResponseWriter

func CachableResponseWriter(req *http.Request,
	statusCode int,
	resp http.ResponseWriter,
	opts Options) ([]cacheobject.Reason, time.Time, error)

Given an HTTP Request, the future Status Code, and an ResponseWriter, determine the possible reasons a response SHOULD NOT be cached.


type Options

type Options struct {
	// Set to True for a private cache, which is not shared among users (eg, in a browser)
	// Set to False for a "shared" cache, which is more common in a server context.
	PrivateCache bool

Source Files


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL