git

Documentation

Index

• Constants
• Variables
• type CachedPack
• type Handler
  • func NewHandler(index *Index, store store.Store, opts ...HandlerOption) *Handler
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type HandlerOption
  • func WithAllowedHosts(hosts []string) HandlerOption
  • func WithDownloader(dl *download.Downloader) HandlerOption
  • func WithLogger(logger *slog.Logger) HandlerOption
  • func WithMaxRequestBodySize(size int64) HandlerOption
  • func WithRouter(router *Router) HandlerOption
  • func WithUpstream(upstream *Upstream) HandlerOption
• type Index
  • func NewIndex(packIndex *metadb.EnvelopeIndex) *Index
  • func (idx *Index) DeleteCachedPack(ctx context.Context, cacheKey string) error
  • func (idx *Index) GetCachedPack(ctx context.Context, cacheKey string) (*CachedPack, error)
  • func (idx *Index) PutCachedPack(ctx context.Context, cacheKey string, pack *CachedPack) error
• type RepoRef
  • func (r RepoRef) String() string
  • func (r RepoRef) UpstreamURL() string
• type Route
• type RouteMatch
• type Router
  • func NewRouter(routes []Route, opts ...RouterOption) (*Router, error)
  • func (r *Router) Match(repo RepoRef) *Upstream
• type RouterOption
  • func WithFallback(u *Upstream) RouterOption
  • func WithRouterLogger(logger *slog.Logger) RouterOption
• type Upstream
  • func NewUpstream(opts ...UpstreamOption) *Upstream
  • func (u *Upstream) FetchInfoRefs(ctx context.Context, repo RepoRef, gitProtocol string) (io.ReadCloser, string, error)
  • func (u *Upstream) FetchUploadPack(ctx context.Context, repo RepoRef, gitProtocol string, body io.Reader) (io.ReadCloser, error)
• type UpstreamOption
  • func WithBasicAuth(username, password string) UpstreamOption
  • func WithHTTPClient(client *http.Client) UpstreamOption
  • func WithUpstreamLogger(logger *slog.Logger) UpstreamOption

Constants

const (
	// ContentTypeUploadPackAdvertisement is the content type for info/refs responses.
	ContentTypeUploadPackAdvertisement = "application/x-git-upload-pack-advertisement"

	// ContentTypeUploadPackRequest is the content type for upload-pack request bodies.
	ContentTypeUploadPackRequest = "application/x-git-upload-pack-request"

	// ContentTypeUploadPackResult is the content type for upload-pack responses.
	ContentTypeUploadPackResult = "application/x-git-upload-pack-result"

	// DefaultMaxRequestBodySize is the maximum size of a git-upload-pack request body (100MB).
	DefaultMaxRequestBodySize int64 = 100 * 1024 * 1024
)

Variables

var ErrNotFound = errors.New("not found")

ErrNotFound is returned when a cached pack is not found.

Types

type CachedPack

type CachedPack struct {
	RequestHash  contentcache.Hash `json:"request_hash"`
	ResponseHash contentcache.Hash `json:"response_hash"`
	ResponseSize int64             `json:"response_size"`
	Repo         string            `json:"repo"`
	GitProtocol  string            `json:"git_protocol"`
	CachedAt     time.Time         `json:"cached_at"`
}

CachedPack represents a cached git-upload-pack response.

type Handler

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

Handler implements the Git Smart HTTP proxy as an HTTP handler.

func NewHandler

func NewHandler(index *Index, store store.Store, opts ...HandlerOption) *Handler

NewHandler creates a new Git proxy handler.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler.

type HandlerOption

type HandlerOption func(*Handler)

HandlerOption configures a Handler.

func WithAllowedHosts

func WithAllowedHosts(hosts []string) HandlerOption

WithAllowedHosts sets the allowlist of permitted upstream Git hosts.

func WithDownloader

func WithDownloader(dl *download.Downloader) HandlerOption

WithDownloader sets the singleflight downloader for deduplicating concurrent fetches.

func WithLogger

func WithLogger(logger *slog.Logger) HandlerOption

WithLogger sets the logger for the handler.

func WithMaxRequestBodySize

func WithMaxRequestBodySize(size int64) HandlerOption

WithMaxRequestBodySize sets the maximum size for upload-pack request bodies.

func WithRouter

func WithRouter(router *Router) HandlerOption

WithRouter sets the Git router for prefix-based upstream selection.

func WithUpstream

func WithUpstream(upstream *Upstream) HandlerOption

WithUpstream sets a single upstream Git client (for backward compatibility). This creates a router with the given upstream as the fallback.

type Index

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

Index manages the Git pack cache index using metadb envelope storage.

func NewIndex

func NewIndex(packIndex *metadb.EnvelopeIndex) *Index

NewIndex creates a new Git pack cache index.

func (*Index) DeleteCachedPack

func (idx *Index) DeleteCachedPack(ctx context.Context, cacheKey string) error

DeleteCachedPack removes a cached pack entry by its cache key.

func (*Index) GetCachedPack

func (idx *Index) GetCachedPack(ctx context.Context, cacheKey string) (*CachedPack, error)

GetCachedPack retrieves a cached pack by composite key. Key format: {host}/{repoPath}:{gitProtocol}:{requestBodyHash}

func (*Index) PutCachedPack

func (idx *Index) PutCachedPack(ctx context.Context, cacheKey string, pack *CachedPack) error

PutCachedPack stores a cached pack with a blob reference.

type RepoRef

type RepoRef struct {
	Host     string
	RepoPath string // supports multi-segment paths (e.g., group/sub/repo)
}

RepoRef identifies a Git repository by host and path.

func (RepoRef) String

func (r RepoRef) String() string

String returns the canonical form: {Host}/{RepoPath}

func (RepoRef) UpstreamURL

func (r RepoRef) UpstreamURL() string

UpstreamURL returns the HTTPS URL for the upstream repository.

type Route

type Route struct {
	Match    RouteMatch
	Upstream *Upstream // pre-constructed upstream with credentials
}

Route defines a routing rule that maps repo prefixes to upstream credentials.

type RouteMatch

type RouteMatch struct {
	RepoPrefix string // e.g., "github.com/orgA/" — prefix match against repo ref
	Any        bool   // catch-all route
}

RouteMatch defines the matching criteria for a Git route.

type Router

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

Router selects an upstream based on the repository reference.

func NewRouter

func NewRouter(routes []Route, opts ...RouterOption) (*Router, error)

NewRouter creates a new Git router with the given routes.

Validation rules:

• If routes is non-empty, the last route must have Any: true (catch-all required)
• Only the last route may have Any: true
• RepoPrefix values must end with "/" to prevent ambiguous matching
• RepoPrefix values are normalized to lowercase
• Prefixes must not be duplicated

func (*Router) Match

func (r *Router) Match(repo RepoRef) *Upstream

Match returns the upstream for the given repo reference. If no routes are configured, returns the fallback upstream.

type RouterOption

type RouterOption func(*Router)

RouterOption configures a Router.

func WithFallback

func WithFallback(u *Upstream) RouterOption

WithFallback sets the fallback upstream used when no routes are configured.

func WithRouterLogger

func WithRouterLogger(logger *slog.Logger) RouterOption

WithRouterLogger sets the logger for the router.

type Upstream

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

Upstream fetches from upstream Git repositories over HTTPS.

func NewUpstream

func NewUpstream(opts ...UpstreamOption) *Upstream

NewUpstream creates a new upstream Git client. The default HTTP client uses no Client.Timeout — it relies on context deadlines instead, since large repo clones can take minutes.

func (*Upstream) FetchInfoRefs

func (u *Upstream) FetchInfoRefs(ctx context.Context, repo RepoRef, gitProtocol string) (io.ReadCloser, string, error)

FetchInfoRefs fetches the info/refs discovery response from the upstream repository. The gitProtocol parameter is forwarded as the Git-Protocol header if non-empty.

func (*Upstream) FetchUploadPack

func (u *Upstream) FetchUploadPack(ctx context.Context, repo RepoRef, gitProtocol string, body io.Reader) (io.ReadCloser, error)

FetchUploadPack sends a git-upload-pack request to the upstream repository. The gitProtocol parameter is forwarded as the Git-Protocol header if non-empty.

type UpstreamOption

type UpstreamOption func(*Upstream)

UpstreamOption configures an Upstream.

func WithBasicAuth

func WithBasicAuth(username, password string) UpstreamOption

WithBasicAuth sets the username and password for upstream authentication. This covers GitHub PATs (username=x-access-token, password=<PAT>), GitLab tokens, and Bitbucket app passwords.

func WithHTTPClient

func WithHTTPClient(client *http.Client) UpstreamOption

WithHTTPClient sets a custom HTTP client.

func WithUpstreamLogger

func WithUpstreamLogger(logger *slog.Logger) UpstreamOption

WithUpstreamLogger sets the logger for the upstream client.