ghcache

README

DOCUMENTATION DEPRECATION NOTICE: This file is deprecated. Please refer to the new migrated location. Please do not edit this file; instead, make changes to the new location!

The new location is served on the web at https://docs.prow.k8s.io/docs/ghproxy/ghcache/.

Documentation

Overview

Package ghcache implements an HTTP cache optimized for caching responses from the GitHub API (https://api.github.com).

Specifically, it enforces a cache policy that revalidates every cache hit with a conditional request to upstream regardless of cache entry freshness because conditional requests for unchanged resources don't cost any API tokens!!! See: https://developer.github.com/v3/#conditional-requests

It also provides request coalescing and prometheus instrumentation.

Index

• Constants
• func CacheModeIsFree(mode CacheResponseMode) bool
• func NewDiskCache(roundTripper http.RoundTripper, cacheDir string, ...) http.RoundTripper
• func NewFromCache(roundTripper http.RoundTripper, cache CachePartitionCreator, ...) http.RoundTripper
• func NewMemCache(roundTripper http.RoundTripper, maxConcurrency int, ...) http.RoundTripper
• func NewRedisCache(roundTripper http.RoundTripper, redisAddress string, maxConcurrency int, ...) http.RoundTripper
• func Prune(baseDir string, now func() time.Time)
• type CachePartitionCreator
• type CacheResponseMode
• type RequestThrottlingTimes
  • func NewRequestThrottlingTimes(...) RequestThrottlingTimes

Constants

const LogMessageWithDiskPartitionFields = "Not using a partitioned cache because legacyDisablePartitioningByAuthHeader is true"

Functions

func CacheModeIsFree

func CacheModeIsFree(mode CacheResponseMode) bool

func NewDiskCache

func NewDiskCache(roundTripper http.RoundTripper, cacheDir string, cacheSizeGB, maxConcurrency int, legacyDisablePartitioningByAuthHeader bool, cachePruneInterval time.Duration, throttlingTimes RequestThrottlingTimes) http.RoundTripper

NewDiskCache creates a GitHub cache RoundTripper that is backed by a disk cache. It supports a partitioned cache.

func NewFromCache

func NewFromCache(roundTripper http.RoundTripper, cache CachePartitionCreator, maxConcurrency int, throttlingTimes RequestThrottlingTimes) http.RoundTripper

NewFromCache creates a GitHub cache RoundTripper that is backed by the specified httpcache.Cache implementation.

func NewMemCache

func NewMemCache(roundTripper http.RoundTripper, maxConcurrency int, throttlingTimes RequestThrottlingTimes) http.RoundTripper

NewMemCache creates a GitHub cache RoundTripper that is backed by a memory cache. It supports a partitioned cache.

func NewRedisCache

func NewRedisCache(roundTripper http.RoundTripper, redisAddress string, maxConcurrency int, throttlingTimes RequestThrottlingTimes) http.RoundTripper

NewRedisCache creates a GitHub cache RoundTripper that is backed by a Redis cache. Important note: The redis implementation does not support partitioning the cache which means that requests to the same path from different tokens will invalidate each other.

func Prune

func Prune(baseDir string, now func() time.Time)

Types

type CachePartitionCreator

type CachePartitionCreator func(partitionKey string, expiresAt *time.Time) httpcache.Cache

CachePartitionCreator creates a new cache partition using the given key

type CacheResponseMode

type CacheResponseMode string

const (
	CacheModeHeader = "X-Cache-Mode"

	ModeError   CacheResponseMode = "ERROR"    // internal error handling request
	ModeNoStore CacheResponseMode = "NO-STORE" // response not cacheable
	ModeMiss    CacheResponseMode = "MISS"     // not in cache, request proxied and response cached.
	ModeChanged CacheResponseMode = "CHANGED"  // cache value invalid: resource changed, cache updated
	ModeSkip    CacheResponseMode = "SKIP"     // cache was skipped, not applicable. e.g. POST request.
	// The modes below are the happy cases in which the request is fulfilled for
	// free (no API tokens used).
	ModeCoalesced   CacheResponseMode = "COALESCED"   // coalesced request, this is a copied response
	ModeRevalidated CacheResponseMode = "REVALIDATED" // cached value revalidated and returned

	// TokenBudgetIdentifierHeader is used to identify the token budget for
	// which metrics should be recorded if set. If unset, the sha256sum of
	// the Authorization header will be used.
	TokenBudgetIdentifierHeader = "X-PROW-GHCACHE-TOKEN-BUDGET-IDENTIFIER"

	// TokenExpiryAtHeader includes a date at which the passed token expires and all associated caches
	// can be cleaned up. It's value must be in RFC3339 format.
	TokenExpiryAtHeader = "X-PROW-TOKEN-EXPIRES-AT"
)

Cache response modes describe how ghcache fulfilled a request.

type RequestThrottlingTimes

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

RequestThrottlingTimes keeps the information about throttling times per API and request methods

func NewRequestThrottlingTimes

func NewRequestThrottlingTimes(requestThrottlingTime, requestThrottlingTimeV4, requestThrottlingTimeForGET, requestThrottlingMaxDelayTime, requestThrottlingMaxDelayTimeV4 uint) RequestThrottlingTimes

NewRequestThrottlingTimes creates a new RequestThrottlingTimes and returns it