gitcache

Documentation

Overview

Package gitcache implements a git repo cache on GCS or local filesystem.

The served API is as follows:

/get: Serve the cached repo metadata object, populating the cache if necessary.
  - uri: Git repo URI e.g. github.com/org/repo
  - contains: The RFC3339-formatted time after which a cache entry must have been created.
  - ref: Git reference (branch/tag) to cache. If provided, creates a separate cache entry per ref.

For GCS backend, redirects to GCS URL. For local backend, serves file directly.

Storage Backends

The -cache flag accepts either:

• gs://bucket-name: Use GCS storage
• /path/to/dir or file:///path/to/dir: Use local filesystem storage

Object Format

The repo cache is stored as a gzipped tar archive of the .git/ directory from an empty checkout of the upstream repo.

Data Races

Racing requests for the same resource will write and return different copies of the repo but these are expected to be ~identical and, given the storage backend's write semantics, subsequent requests will converge to return the latest version of the archive.

The current behavior could be improved by coalescing like requests and blocking on a single writer.

Cache Lifecycle

If the caller provides the "contains" parameter that is more recent than the most recent cache entry, it will be re-fetched and overwritten.

There is currently no TTL for cache entries nor a size limitation for the backing storage. These are areas for future work.

Index

• type Client
  • func (c Client) Clone(ctx context.Context, s storage.Storer, fs billy.Filesystem, ...) (*git.Repository, error)
  • func (c Client) GetLink(repo string, contains time.Time) (uri string, err error)
  • func (c Client) GetLinkWithRef(repo string, contains time.Time, ref string) (uri string, err error)
• type GetRequest
  • func (r GetRequest) Validate() error
• type Server
  • func NewServer(ctx context.Context, cacheStr string) (*Server, error)
  • func (s *Server) HandleGet(rw http.ResponseWriter, httpReq *http.Request)

Types

type Client

type Client struct {
	// IDClient is the HTTP client to use to access the cache service.
	IDClient *http.Client
	// APIClient is the HTTP client to use to access the underlying cache storage.
	APIClient *http.Client
	// URL is the address of the cache service.
	*url.URL
	// DefaultFreshness is the freshness bound to use if none is provided.
	DefaultFreshness time.Time
}

Client is an interface abstracting the rebuilder git-cache service.

func (Client) Clone

func (c Client) Clone(ctx context.Context, s storage.Storer, fs billy.Filesystem, opt *git.CloneOptions) (*git.Repository, error)

Clone provides an interface to clone a git repo using the GitCache.

func (Client) GetLink

func (c Client) GetLink(repo string, contains time.Time) (uri string, err error)

GetLink returns a GCS link to the cached repo resource.

func (Client) GetLinkWithRef

func (c Client) GetLinkWithRef(repo string, contains time.Time, ref string) (uri string, err error)

GetLinkWithRef returns a GCS link to the cached repo resource for a specific ref.

type GetRequest

type GetRequest struct {
	URI      string `form:"uri"`
	Contains string `form:"contains"`
	Ref      string `form:"ref"`
}

GetRequest represents a request to the /get endpoint.

func (GetRequest) Validate

func (r GetRequest) Validate() error

Validate checks that the request fields are valid.

type Server

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

Server provides HTTP handling for the git cache.

func NewServer

func NewServer(ctx context.Context, cacheStr string) (*Server, error)

NewServer creates a new Server with the given cache location string.

func (*Server) HandleGet

func (s *Server) HandleGet(rw http.ResponseWriter, httpReq *http.Request)

HandleGet serves cached repo metadata, populating the cache if necessary.