cache

Documentation

Index

• type Cache
  • func NewCache(client api.Client, cc *config.Cache) *Cache
  • func (c *Cache) Refresh(entry *Entry)
  • func (c *Cache) Resolve(ctx context.Context, domain string) *api.Lookup
• type Entry
  • func (e *Entry) IsUpToDate() bool
  • func (e *Entry) Lookup() *api.Lookup
  • func (e *Entry) NeedsRefresh() bool
• type Retriever
  • func NewRetriever(client api.Client, retrievalTimeout, maxRetrievalInterval time.Duration, ...) *Retriever
  • func (r *Retriever) Retrieve(originalCtx context.Context, domain string) (lookup api.Lookup)
• type Store

Types

type Cache

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

Cache is a short and long caching mechanism for GitLab source

func NewCache

func NewCache(client api.Client, cc *config.Cache) *Cache

NewCache creates a new instance of Cache.

func (*Cache) Refresh

func (c *Cache) Refresh(entry *Entry)

Refresh will update the entry in the store only when it gets resolved successfully. If an existing successful entry exists, it will only be replaced if the new resolved entry is successful too. Errored refreshed Entry responses will not replace the previously successful entry.response for a maximum time of e.expirationTimeout.

func (*Cache) Resolve

func (c *Cache) Resolve(ctx context.Context, domain string) *api.Lookup

Resolve is going to return a lookup based on a domain name. The caching algorithm works as follows:

• We first check if the cache entry exists, and if it is up-to-date. If it is fresh we return the lookup entry from cache and it is a cache hit.
• If entry is not up-to-date, that means it has been created in a cache more than `entryRefreshTimeout` duration ago, we schedule an asynchronous retrieval of the latest configuration we are going to obtain through the API, and we immediately return an old value, to avoid blocking clients. In this case it is also a cache hit.
• If cache entry has not been populated with a lookup information yet, we block all the clients and make them wait until we retrieve the lookup from the GitLab API. Clients should not wait for longer than `retrievalTimeout`. It is a cache miss.

We are going to retrieve a lookup from GitLab API using a retriever type. In case of failures (when GitLab API client returns an error) we will retry the operation a few times, waiting `maxRetrievalInterval` in between, total amount of requests is defined as `maxRetrievalRetries`. In case of an erroneous response, we will cache it, and it get recycled as every other cache entry.

Examples: 1. Everything works

• a client opens pages
• we create a new cache entry
• cache entry needs a warm up
• a client waits until we retrieve a lookup
• we successfully retrieve a lookup
• we cache this response
• and we pass it upstream to all clients

2. A domain does not exist

• a client opens pages
• we create a new cache entry
• cache entry needs a warm up
• a client waits until we retrieve a lookup
• GitLab responded with a lookup and 204 HTTP status
• we cache this response with domain being `nil`
• we pass this lookup upstream to all the clients

3. GitLab is not responding

• a client opens pages
• we create a new cache entry
• cache entry needs a warm up
• a client waits until we retrieve a lookup
• GitLab does not respond or responds with an error
• we retry this retrieval every `maxRetrievalInterval`
• we retry this retrieval `maxRetrievalRetries` in total
• we create a lookup that contains information about an error
• we cache this response
• we pass this lookup upstream to all the clients

type Entry

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

Entry represents a cache object that can be retrieved asynchronously and holds a pointer to *api.Lookup when the domain lookup has been retrieved successfully

func (*Entry) IsUpToDate

func (e *Entry) IsUpToDate() bool

IsUpToDate returns true if the entry has been resolved correctly and has not expired yet. False otherwise.

func (*Entry) Lookup

func (e *Entry) Lookup() *api.Lookup

Lookup returns a retriever Lookup response.

func (*Entry) NeedsRefresh

func (e *Entry) NeedsRefresh() bool

NeedsRefresh return true if the entry has been resolved correctly but it has expired since then.

type Retriever

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

Retriever is an utility type that performs an HTTP request with backoff in case of errors

func NewRetriever

func NewRetriever(client api.Client, retrievalTimeout, maxRetrievalInterval time.Duration, maxRetrievalRetries int) *Retriever

NewRetriever creates a Retriever with a client

func (*Retriever) Retrieve

func (r *Retriever) Retrieve(originalCtx context.Context, domain string) (lookup api.Lookup)

Retrieve retrieves a lookup response from external source with timeout and backoff. It has its own context with timeout.

type Store

type Store interface {
	LoadOrCreate(domain string) *Entry
	ReplaceOrCreate(domain string, entry *Entry) *Entry
}

Store defines an interface describing an abstract cache store